knowledge-buildlisted

# 测试知识库构建 从 `$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 阶