diff --git a/README.md b/README.md index f0f0087..6abcd57 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,198 @@ -# pbl_kdb_ext +# pbl_kdb_ext —— PBL 知识库（KDB）只读桩扩展模块（M7） +## 1. 模块用途 + +`pbl_kdb_ext` 是 PBL（Project/Problem-Based Learning）Agent OS 的**知识库只读扩展层**，为 +Designer / Critic Agent 与教师端提供「查得到、改不了」的知识条目检索与研究数据聚合能力。 + +设计定位（对应两个开放问题的当期落地口径）： + +| 开放问题 | 当期口径 | 本模块实现 | +|---------|---------|-----------| +| **Q-OPEN-5** KDB 是否落地向量库 | 暂不引入向量库/Embedding | **不落地向量桩**：检索走结构化字段等值 + `LIKE` 关键词匹配，返回体带 `stub` 标记，后续可平滑替换为向量检索而不改契约 | +| **Q-OPEN-6** research 数据是否可写回 | 只读、匿名 | **只读匿名聚合**：分组统计评估分数，最小分组 `k_min=5`，样本不足的分组直接抑制（`suppressed_groups` 计数），返回 `anonymous=true / written=false` | + +### G6 范围纪律（硬约束，可 grep 核对） + +本模块**零写入业务对象**，明确**不实现**以下任何能力： + +- ❌ `kdb.write` / `kdb.add_candidate` / `kdb.propose_pattern`（知识条目写入、候选入库、模式提炼） +- ❌ `research.write`（研究数据写回） +- ❌ `sim.*`（仿真/模拟相关全部接口） + +`pbl_kdb_item.is_write_locked` 恒为 `1`，模块内**不存在**任何 `UPDATE` / `INSERT` / `DELETE` +`pbl_kdb_item` 的代码路径；唯一的写操作是**查询留痕日志** `pbl_kdb_query_log`（审计用途， +append-only，不属于业务对象写入）。 + +## 2. 数据表（2 张，定义在 `models/`） + +### 2.1 `pbl_kdb_item` —— 知识条目表（只读，写锁定） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | str(32) | 主键 | +| `tenant_id` | str(32) | 租户隔离，**所有查询强制打头** | +| `code` | str(64) | 条目业务编码（唯一，配合 tenant_id） | +| `item_type` | str(32) | 条目类型（pattern / case / rubric_ref 等，取自 appcodes） | +| `title` | str(255) | 标题（检索字段） | +| `summary_txt` | text | 摘要正文（`LIKE` 关键词匹配字段） | +| `payload_json` | text | 结构化载荷（JSON，读取时反序列化为 dict） | +| `source` | str(64) | 来源（可作过滤维度） | +| `version_no` | int | 版本号 | +| `status` | str(16) | 状态，检索仅命中 `published` | +| `is_write_locked` | short | **恒为 1**：写锁定标记，本模块只读约束的数据层体现 | +| `created_at` / `updated_at` | timestamp | 审计时间戳 | + +> 表数据由上游（蓝图编译 / 治理域）产生并置 `is_write_locked=1`；本模块只消费，不生产。 + +### 2.2 `pbl_kdb_query_log` —— 检索留痕日志表（append-only） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | str(32) | 主键 | +| `tenant_id` | str(32) | 租户隔离 | +| `query_uid` | str(64) | 查询唯一标识（`Q` + sha256(参数+时间) 前 20 位） | +| `caller_type` | str(16) | 调用方类型（agent / teacher，缺省 `agent`） | +| `caller_id` | str(32) | 调用方 ID（取自 `actor_id()`） | +| `query_json` | text | 查询参数快照（剔除 `caller_id`，避免重复存储） | +| `hit_count` | int | 命中条数 | +| `latency_ms` | int | 检索耗时（毫秒） | +| `ok` | short | 是否成功（恒 1，异常路径直接抛错不落日志） | +| `created_at` | timestamp | 记录时间 | + +用途：检索行为可观测（命中率 / 延迟）与审计追溯。**只 INSERT，不 UPDATE / DELETE。** + +### 2.3 跨模块只读依赖 + +`pbl_research_aggregate` 只读聚合 **`pbl_assessment_record`**（属 `pbl_assessment` 模块， +M6 产出）的 `total_score` / `band` / `assessor_type` / `blueprint_id` 字段——**跨模块只读， +不写不建表**，符合交互/扩展层模块的数据所有权边界。 + +## 3. 契约接口（3 个，全部只读） + +三个契约均为 `wwwroot/api/*.dspy` 薄封装 → 调用 `pbl_kdb_ext/api.py` 中的同名 async 函数 +（函数经 `load_pbl_kdb_ext()` 注册到 ServerEnv，dspy 内直接以全局名调用，无需 import）。 + +| # | 契约名 | HTTP 路径（自动路由） | 入参 | 返回要点 | +|---|--------|---------------------|------|---------| +| 1 | `pbl_kdb_search` | `/pbl_kdb_ext/api/pbl_kdb_search.dspy` | `item_type`、`source`、`keyword`、`limit`(≤50，默认 10)、`caller_type` | `{ok, data[], hit_count, latency_ms, writable:false, stub}`；固定过滤 `tenant_id` + `is_write_locked=1` + `status='published'`；写一条 `pbl_kdb_query_log` | +| 2 | `pbl_kdb_get` | `/pbl_kdb_ext/api/pbl_kdb_get.dspy` | `id` 或 `code` | `{ok, data{...payload_json 已反序列化}, is_write_locked:true, stub}`；未命中抛 `PBL_KDB_NOT_FOUND` | +| 3 | `pbl_research_aggregate` | `/pbl_kdb_ext/api/pbl_research_aggregate.dspy` | `group_by` ∈ {`band`, `assessor_type`, `blueprint_id`}（默认 `band`） | `{ok, dimension, groups[{group,n,avg_score,min_score,max_score}], suppressed_groups, k_min:5, anonymous:true, written:false, note}`；维度非法抛 `PBL_AGG_DIM_INVALID` | + +错误码沿用 `pbl_common` 统一错误体系（`PblError`）：`PBL_KDB_NOT_FOUND`、`PBL_AGG_DIM_INVALID`。 +本模块**不另设** `errors.py`——错误类型与错误码常量由公共内核 `pbl_common.api` 统一提供， +模块内只做抛出，避免与公共内核重复定义（交付清单与磁盘文件一一对应）。 + +## 4. 目录结构 + +``` +pbl_kdb_ext/ +├── pbl_kdb_ext/ # Python 包（包目录 = 模块名） +│ ├── __init__.py # ② 导出三个契约函数（三处同步之②） +│ ├── init.py # ③ load_pbl_kdb_ext()：env.<契约> = <契约> +│ └── api.py # ① 契约实现（只读检索 / 详情 / 匿名聚合） +├── wwwroot/ +│ ├── index.ui # 模块入口页（三张卡片 → urlwidget 到内容区） +│ └── api/ +│ ├── pbl_kdb_search.dspy +│ ├── pbl_kdb_get.dspy +│ └── pbl_research_aggregate.dspy +├── models/ +│ ├── pbl_kdb_item.json # 表定义（四段式 summary/fields/indexes/codes） +│ └── pbl_kdb_query_log.json +├── json/ # CRUD 定义（只读浏览用，无 editable 写入 URL） +│ ├── kdb_ext_pbl_kdb_item.json +│ └── kdb_ext_pbl_kdb_query_log.json +├── scripts/load_path.py # RBAC 路径注册（显式枚举，无通配符） +├── sql/pbl_kdb_ext.sql # DDL（建表脚本） +├── skill/SKILL.md # Agent 必读模块技能文档 +├── pyproject.toml +└── README.md # 本文件 +``` + +## 5. 挂载方式（宿主应用集成） + +模块**不是独立部署单元**——无自己的 `app.py` / 端口 / Dockerfile / 服务脚本，只能由宿主应用 +（`apps/pbls`）挂载： + +```python +# apps/pbls/app/pbls.py 的 init() 中，ServerEnv() 与基础模块加载之后： +from pbl_kdb_ext.init import load_pbl_kdb_ext +load_pbl_kdb_ext() # 返回 'pbl_kdb_ext' +``` + +`load_pbl_kdb_ext()` 是**唯一集成点**，做且只做一件事：把三个契约函数注册到 `ServerEnv` +（`env.pbl_kdb_search` / `env.pbl_kdb_get` / `env.pbl_research_aggregate`），使 `.dspy` / `.ui` +能以全局名直接调用。宿主决定何时、以何顺序挂载。 + +### 5.1 三处同步铁律 + +新增/删除一个契约函数必须同步改三处，缺一即运行期报错： + +1. `pbl_kdb_ext/api.py` —— 函数实现； +2. `pbl_kdb_ext/__init__.py` —— `from .api import ` 导出（缺 → ImportError / AttributeError）； +3. `pbl_kdb_ext/init.py` —— `env. = `（缺 → dspy 内 `NameError: name '' is not defined`）。 + +核对命令：`grep -rn 'pbl_kdb_search' pbl_kdb_ext/ --include='*.py'` 应恰好命中这三处。 + +### 5.2 RBAC 注册（`scripts/load_path.py`） + +由 `apps/pbls/build.sh` 调用 `register()`，逐条注册（**显式枚举，禁止 `%` / `*` 通配符**）： + +| 路径 | 角色 | +|------|------| +| `/pbl_kdb_ext` | `logined` | +| `/pbl_kdb_ext/index.ui` | `logined` | +| `/pbl_kdb_ext/api/pbl_kdb_search.dspy` | `logined` | +| `/pbl_kdb_ext/api/pbl_kdb_get.dspy` | `logined` | +| `/pbl_kdb_ext/api/pbl_research_aggregate.dspy` | `logined` | + +入口页的**目录路径与文件路径都要注册**，否则入口页上线即 403。`set_role_perm.py` 不在位时 +脚本打印 `PENDING ` 清单并以退出码 1 返回（不静默跳过、不抛异常），由部署角色 +手工补注册。本模块全部接口为登录可读，无 `any`（匿名）路径，也无 teacher/admin 专属写路径 +（因为没有写接口）。 + +### 5.3 数据库名 + +模块内**不硬编码库名**，统一通过 `pbl_common` 的 DB 适配层（`sql_rows` / `sql_exec` 的 +`'pbl'` 逻辑库标识）由宿主应用的 `get_module_dbname()` 解析到真实库。 + +## 6. 只读 / 匿名聚合约束说明（验收要点） + +1. **零写入**：模块内无 `kdb.write` / `research.write` / `sim.*` 任何实现； + `grep -rn "def .*write\|def .*sim_" pbl_kdb_ext/` 结果为空。 +2. **写锁定**：`pbl_kdb_search` 的 WHERE 固定包含 `is_write_locked = 1`；`pbl_kdb_get` + 返回体固定 `is_write_locked: true`；无任何路径可修改该字段。 +3. **租户隔离**：三个契约的 SQL 全部以 `tenant_id = ${t}$` 打头（`tenant_id()` 取自 + `pbl_common` 请求上下文），缺失租户上下文即报错，不降级为全租户查询。 +4. **匿名聚合（隐私线）**：`k_min = 5`；分组样本数 `< 5` 的分组**不出现在 `groups` 中**， + 仅计入 `suppressed_groups`；返回体不含任何个体标识（无 student_id / user_id / 明细行）。 +5. **聚合维度白名单**：`group_by` 仅允许 `band` / `assessor_type` / `blueprint_id`， + 其它值抛 `PBL_AGG_DIM_INVALID`（同时杜绝 SQL 注入——维度名不来自自由文本拼接）。 +6. **参数化 SQL**：全部使用 sqlor `${name}$` 占位符，无字符串拼接用户输入。 +7. **桩标记透明**：检索/详情返回体带 `stub: 'kdb_stub: no vector store (Q-OPEN-5)'`， + 调用方可据此判断结果来自结构化匹配而非语义向量检索。 +8. **可观测**：每次检索落一条 `pbl_kdb_query_log`（hit_count / latency_ms / query_json）， + 用于命中率与延迟分析；日志表 append-only。 + +## 7. 依赖 + +- **基础/公共**：`pbl_common`（租户上下文、DB 适配、`PblError` 错误码、`actor_id` / + `now_str` / `json_dump` 工具）、`ahserver`（ServerEnv）、`sqlor`（数据访问）。 +- **数据依赖（只读）**：`pbl_assessment` 的 `pbl_assessment_record`（聚合数据源）。 +- **被依赖**：`pbl_agent_runtime`（Designer/Critic Agent 检索知识条目）、 + `pbl_scense_ext` / 教师端页面（研究数据聚合展示）。 + +## 8. 本地校验 + +```bash +cd modules/pbl_kdb_ext +python3 -m py_compile pbl_kdb_ext/*.py scripts/load_path.py # .py 编译 +python3 -c "import json;[json.load(open('models/'+f)) for f in ('pbl_kdb_item.json','pbl_kdb_query_log.json')]" +python3 -c "import json;json.load(open('wwwroot/index.ui'));print('index.ui JSON OK')" +grep -rn "^import\|^from" wwwroot/ --include='*.dspy' # dspy 审计：应为空 +grep -rn "entire_url(" wwwroot/index.ui | grep -v "/pbl_kdb_ext/" # 绝对路径核对：应为空 +``` + +> `.dspy` 不能用 `py_compile` 校验（框架运行期注入 async 函数体，顶层 `return`/`await` 合法）， +> 只做 grep 审计。 diff --git a/docs/work-log-2026-09-18.md b/docs/work-log-2026-09-18.md new file mode 100644 index 0000000..2951525 --- /dev/null +++ b/docs/work-log-2026-09-18.md @@ -0,0 +1,52 @@ +# pbl_kdb_ext 工作日志 —— 2026-09-18（QC 退回重做轮） + +## 范围 / 背景 + +- 仓库/模块：机构工作空间 `modules/pbl_kdb_ext`（PBL Agent OS，项目 `projects/pbls`） +- 任务：`[M7] pbl_kdb_ext KDB 只读桩扩展`（pipeline_tasks.id = `OgtZuajAdd0y65BZdv8jr`， + iteration `pbls-初始迭代`，task_kind = new_dev → 本轮为 QC 退回后的重做修复） +- 本轮目标：逐条闭环 agent.qc 的 5 条退回意见，不扩大范围（G6 范围纪律：仍零写入， + 不新增 kdb.write / research.write / sim.*）。 + +## QC 退回意见 → 处理结果（逐条） + +| # | 位置 | 问题 | 处理 | +|---|------|------|------| +| 1 | `scripts/load_path.py` PATHS | 仅注册 3 个 `.dspy`，缺 `/pbl_kdb_ext` 与 `/pbl_kdb_ext/index.ui`，入口页上线即 403 | **已修**：PATHS 补两条 `logined` 记录（目录路径 + index.ui 文件路径），共 5 条，仍显式枚举无通配符 | +| 2 | `wwwroot/index.ui` 三处 `binds.options.url` | `{{entire_url('api/pbl_kdb_search.dspy')}}` 为相对路径，可能丢模块前缀 → RBAC 403（module-development-spec 2.3c） | **已修**：三处全部改为绝对路径 `{{entire_url('/pbl_kdb_ext/api/xxx.dspy')}}`（search / get / aggregate） | +| 3 | `scripts/load_path.py` 第 38 行 | `print(' PENDING %%-12s %s' %(role, path))` —— `%%` 转义后格式串只剩 1 个 `%s` 却传 2 个参数，出现 pending 必抛 TypeError，注册失败时脚本崩溃而非打印清单 | **已修**：改为 `print(' PENDING %-12s %s' % (role, path))`；同时给 `subprocess.call` 加 `try/except OSError`（CLI 不存在时归入 pending 而非崩溃），summary 行补上 MODULE 名 | +| 4 | `README.md` | 全文仅 15 字节 `# pbl_kdb_ext`，boilerplate-only（spec 明令禁止） | **已修**：重写为 8 节完整文档——模块用途（Q-OPEN-5/6 口径 + G6 范围纪律）、2 张表字段说明（pbl_kdb_item / pbl_kdb_query_log）+ 跨模块只读依赖、3 个契约接口（路径/入参/返回/错误码）、目录结构、挂载方式（load_pbl_kdb_ext + 三处同步铁律 + RBAC 表 + 库名）、只读/匿名聚合 8 条验收约束、依赖、本地校验命令 | +| 5 | 交付摘要清单 vs 磁盘 | 清单声称写入 `pbl_kdb_ext/errors.py`，实测不存在，声称与事实矛盾 | **已修（走"移除"分支）**：错误类型/错误码由公共内核 `pbl_common.api` 的 `PblError` 统一提供，本模块只抛出不另定义，故 `errors.py` **不是本任务应产出**，已从交付清单移除；README 第 3 节明确写出该决策，保证清单与盘上文件一一对应。`api.py` 的 import 闭包保持 `from pbl_common.api import PblError, ...` 不变，无悬空引用 | + +## 关键技术决策 + +1. **errors.py 取舍**：两个合法分支（补写并纳入 import 闭包 / 从清单移除）中选**移除**。 + 理由：`PblError` 与错误码体系属 `pbl_common` 公共内核职责，模块内再建 errors.py 会与 + 公共内核重复定义、增加两处维护点；本模块仅 2 个错误码（`PBL_KDB_NOT_FOUND`、 + `PBL_AGG_DIM_INVALID`），直接在 api.py 抛出即可。 +2. **load_path.py 健壮性**：QC #3 的根因是"失败路径未被测过"。除修格式串外，补 + `try/except OSError`，使 `set_role_perm.py` 不在位时走 pending 打印分支（退出码 1）， + 而不是抛 FileNotFoundError 让 build.sh 第 8 步整体中断。 +3. **index.ui 保持纯 JSON**：入口页三张卡片（VBox + binds click → `actiontype: urlwidget` + → `target: app.pbl_kdb_ext_content`，`mode: replace`），内容区 VBox 的 `id` 放在 + **widget 顶层**（不是 options 内），符合 bricks 规范；无 ``/`