199 lines
11 KiB
Markdown
199 lines
11 KiB
Markdown
# 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 <fn>` 导出（缺 → ImportError / AttributeError）；
|
||
3. `pbl_kdb_ext/init.py` —— `env.<fn> = <fn>`（缺 → dspy 内 `NameError: name '<fn>' 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 <role> <path>` 清单并以退出码 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 审计。
|