knowledge-build

name	knowledge-build
description	从开发文档构建或更新测试知识库（L0 架构索引 / L1 模块功能 / L2 需求变更），以灰盒测试人员视角提取可测试契约
when_to_use	当用户提供新的需求文档、接入指南或历史测试文档，需要构建或增量更新测试知识库时
argument-hint	<doc_dir> [knowledge_dir]
arguments	["doc_dir","knowledge_dir"]
user-invocable	true
allowed-tools	Read Glob Grep Write Edit Bash
effort	high

测试知识库构建

从 $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 文件）→ 执行第四步

第三步：初始化构建

1. 分析所有文档，识别系统模块和变更迭代
2. 创建目录结构：

   $knowledge_dir/
   ├── L0_system_architecture.md
   ├── L1/
   └── L2/
   

3. 按模板生成 L0、L1、L2 文件
4. 文档中没有的信息一律标注 [?]，不猜测
5. 生成完毕后，向用户输出知识库摘要（模块列表 + [?] 统计）

第四步：增量更新

1. 读取已有的 L0 索引，了解当前知识库结构
2. 对比新文档与已有 L2，识别：
   • 全新的迭代 → 新建 L2 文件
   • 已有迭代的补充信息 → 更新对应 L2 文件
3. 根据变更影响，更新受影响的 L1 模块文件
4. 如果出现新模块 → 新建 L1 文件
5. L0 一致性校验：用新文档内容逐项校验 L0 现有描述，必须检查：
   • Pipeline 阶段顺序是否与新文档一致（这是最容易过时的部分）
   • 版本号是否需要更新
   • 服务拓扑是否有变化
   • 发现不一致时直接修正 L0，不能跳过
6. 更新 L0 索引表
7. 向用户输出变更摘要（新增/修改了哪些文件，新增了哪些 [?]）

分层说明

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 文件时必须读取对应模板，按模板结构输出。

质量约束

1. 不猜测：文档没写的标 [?]，附简短说明缺什么（如 [?错误码未明确]、[?是否必填]）
2. 不脑补必填性：字段是否必填、是否有默认值，文档没明确说的就标 [?]
3. 溯源原则：每条规则应可追溯到具体文档原文，不做推理延伸
4. 行数限制：L0 ≤ 80 行，L1 ≤ 150 行，L2 ≤ 100 行
5. 增量更新时：只修改受新文档影响的文件，不动其他文件

[?] 标注规范

标注 [?] 时按类型分类，便于后续分批补全：

• [?行为未定义: ...] — 文档未说明某条件下的系统行为（如"候选券为空时的行为"），需读代码或找产品确认
• [?值未明确: ...] — 具体字段名、加密方式、阈值等文档未给出（如"7 个特征字段名"），需读配置或代码提取
• [?可观测性缺失: ...] — 模块缺少日志/指标/健康检查的描述，需审计实际可观测覆盖度

补全时建议按 pipeline 数据流顺序（校验→路由→粗排→特征→打分→校准→发放）逐模块处理，上下文连贯性更好，更容易发现跨模块问题。

错误场景标注规范

错误场景段落中，区分两类：

• 设计行为：系统有意为之的降级/兜底（如"候选券为空→返回空列表"），直接描述行为
• [!风险]：系统未处理的异常路径（如"Redis 连接异常未捕获，会导致整个请求失败"），用 [!风险] 标记，这些是高价值测试点

可观测状态段落要求

每个 L1 模块必须填写"可观测状态"段，包含：

• 已有的可观测手段（日志级别+内容、Redis Key、API 端点、指标等）
• 盲区：关键路径上缺少日志/指标的地方（如"目录不存在时无日志"、"限流触发无日志"）
• 已定义但未使用的错误码/常量（如"STOCK_EMPTY=1006 已定义但代码未使用"），这类信息对测试设计有价值

完成后输出

执行完毕后，向用户输出：

## 知识库构建摘要

模式：初始化 / 增量更新
文档源：（读了哪些文档）

### 文件清单
（列出所有生成/修改的文件及行数）

### [?] 统计
（列出所有标了 [?] 的信息点，按模块分组）

### 待确认项
（需要用户补充或确认的关键信息）