tlzmw001 测试知识库构建
从 $doc_dir 目录下的文档构建或更新测试知识库，输出到 $knowledge_dir（未指定时默认为 $doc_dir 同级的 knowledge/ 目录）。
你的角色
你是一个新入职的测试人员。你不能阅读源码实现，只能从文档和接口定义文件中获取信息。
信息来源
主要信息源是 $doc_dir 目录下的文档。
以下文件也可以读取（它们定义了系统的外部行为，属于测试人员应了解的范畴）：
- 接口定义文件：
.proto、OpenAPI/Swagger spec 等 - 配置文件：
.json、.yaml、.toml、.ini等 - 数据文件：
.tsv、.csv等（了解数据格式和字段含义） - Schema 文件：JSON Schema、数据库 DDL 等
禁止读取的是源码实现（.py、.java、.go、.ts 等）——测试人员关注系统做什么，不关注怎么实现。
每条信息必须能溯源到文档或上述可读文件，无法确认的标 [?]。
信息边界（灰盒）
可以包含：API 接口定义、请求/响应结构、proto message/service、配置项含义与默认值、存储 Key 格式、错误码、业务算法公式
不包含：源码函数名、行号、变量名、内部实现逻辑
执行流程
第一步：盘点文档
读取 $doc_dir 下所有文档，将每份文档分类为：
- 系统总览：整体架构、API 列表、流程
- 迭代变更：增量改动需求
- 接入指南：组件/SDK 使用方式
- 历史测试文档：已有测试用例、测试报告
- 其他：标注类型
第二步：判断模式
检查 $knowledge_dir 目录：
- 初始化模式（目录不存在或无 L0 文件）→ 执行第三步
- 增量更新模式（已有 L0 文件）→ 执行第四步
第三步：初始化构建
- 分析所有文档，识别系统模块和变更迭代
- 创建目录结构：
$knowledge_dir/ ├── L0_system_architecture.md ├── L1/ └── L2/ - 按模板生成 L0、L1、L2 文件
- 文档中没有的信息一律标注
[?]，不猜测 - 生成完毕后，向用户输出知识库摘要（模块列表 +
[?]统计）
第四步：增量更新
- 读取已有的 L0 索引，了解当前知识库结构
- 对比新文档与已有 L2，识别：
- 全新的迭代 → 新建 L2 文件
- 已有迭代的补充信息 → 更新对应 L2 文件
- 根据变更影响，更新受影响的 L1 模块文件
- 如果出现新模块 → 新建 L1 文件
- L0 一致性校验：用新文档内容逐项校验 L0 现有描述，必须检查：
- Pipeline 阶段顺序是否与新文档一致（这是最容易过时的部分）
- 版本号是否需要更新
- 服务拓扑是否有变化
- 发现不一致时直接修正 L0，不能跳过
- 更新 L0 索引表
- 向用户输出变更摘要（新增/修改了哪些文件，新增了哪些
[?]）
分层说明
L0 — 系统架构（路由索引）
- 控制在 80 行以内
- 一段话描述系统功能
- 服务拓扑
- Pipeline 阶段概览
- 模块索引表：模块名 | 说明 | L1 路径 | 相关 L2 路径
- 不包含具体业务规则
L0 — 系统架构（路由索引）补充
- 如果项目有接口定义文件（
.proto、OpenAPI spec），在 L0 中添加"接口契约"章节，链接到这些文件 - 这些文件是输入/输出结构的权威来源，知识库不需要复制字段表，链接即可
L1 — 模块功能（可测试契约）
- 每个文件控制在 150 行以内
- 功能差异大的模块拆成独立文件
- 反映当前最新全貌（增量更新时合并变更到已有文件）
- 输入/输出章节：如果系统有 proto 或 OpenAPI 定义，在章节中链接到对应的 message/schema 定义，不重复列字段
- 接口契约必须记录：每个 L1 模块如果有对应的 HTTP/gRPC 测试入口，必须在"输入"章节之前添加"接口"章节，包含：(1) 完整端点路径（如
POST /api/v1/recommend），从 proto/OpenAPI/路由定义文件中提取；(2) 链接到请求/响应 Schema 定义文件。即使模块只关注部分字段，L1 也必须至少列出请求体中所有必填字段及其类型（或链接到完整定义），因为 test-design 需要构造完整请求体才能生成可执行用例
L2 — 需求变更
- 每个文件控制在 100 行以内
- 描述变更 delta 和测试重点
L1/L2 模板
L1 模块文档模板见 aitest_config/refs/l1-template.md。
L2 需求变更文档模板见 aitest_config/refs/l2-template.md。
生成 L1/L2 文件时必须读取对应模板，按模板结构输出。
质量约束
- 不猜测：文档没写的标
[?]，附简短说明缺什么（如[?错误码未明确]、[?是否必填]） - 不脑补必填性：字段是否必填、是否有默认值，文档没明确说的就标
[?] - 溯源原则：每条规则应可追溯到具体文档原文，不做推理延伸
- 行数限制：L0 ≤ 80 行，L1 ≤ 150 行，L2 ≤ 100 行
- 增量更新时：只修改受新文档影响的文件，不动其他文件
[?] 标注规范
标注 [?] 时按类型分类，便于后续分批补全：
[?行为未定义: ...]— 文档未说明某条件下的系统行为（如"候选券为空时的行为"），需读代码或找产品确认[?值未明确: ...]— 具体字段名、加密方式、阈值等文档未给出（如"7 个特征字段名"），需读配置或代码提取[?可观测性缺失: ...]— 模块缺少日志/指标/健康检查的描述，需审计实际可观测覆盖度
补全时建议按 pipeline 数据流顺序（校验→路由→粗排→特征→打分→校准→发放）逐模块处理，上下文连贯性更好，更容易发现跨模块问题。
错误场景标注规范
错误场景段落中，区分两类：
- 设计行为：系统有意为之的降级/兜底（如"候选券为空→返回空列表"），直接描述行为
[!风险]：系统未处理的异常路径（如"Redis 连接异常未捕获，会导致整个请求失败"），用[!风险]标记，这些是高价值测试点
可观测状态段落要求
每个 L1 模块必须填写"可观测状态"段，包含：
- 已有的可观测手段（日志级别+内容、Redis Key、API 端点、指标等）
- 盲区：关键路径上缺少日志/指标的地方（如"目录不存在时无日志"、"限流触发无日志"）
- 已定义但未使用的错误码/常量（如"STOCK_EMPTY=1006 已定义但代码未使用"），这类信息对测试设计有价值
完成后输出
执行完毕后，向用户输出：
## 知识库构建摘要
模式：初始化 / 增量更新
文档源：（读了哪些文档）
### 文件清单
（列出所有生成/修改的文件及行数）
### [?] 统计
（列出所有标了 [?] 的信息点，按模块分组）
### 待确认项
（需要用户补充或确认的关键信息）