# Knowledge Build

> 从开发文档构建或更新测试知识库（L0 架构索引 / L1 模块功能 / L2 需求变更），以灰盒测试人员视角提取可测试契约

- Skill: `tlzmw001/knowledge-build` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tlzmw001/knowledge-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tlzmw001/knowledge-build/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tlzmw001 (https://skillmd.com/u/tlzmw001)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tlzmw001/knowledge-build

---


# 测试知识库构建

从 `$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 已定义但代码未使用"），这类信息对测试设计有价值

## 完成后输出

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

```
## 知识库构建摘要

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

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

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

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