开篇

本篇内容其实在之前讲解如何设计知识库的文章中也有所涉及，事实上大部分 SKILL 的效果好坏，很大程度上取决于知识库是否完善和精准。下面咱们进入正题。

「需求评审」和「手工用例生成」的知识库要如何构建

下面先展示一下需求评审的多 SKILL 串联的工作流结构

• 需求评审：req-review（主）+ req-review-associator（关联分析子 Skill）+ req-review-challenger（审查挑战子 Skill）
• 手工用例生成：req-test-cases

三个重点：

1. 知识库如何构建——需求文档沉淀 + 两类人工维护文档（通用规则、业务规则）
2. Skill 是自学习的——评审通过的需求、生成的用例都会回流知识库，供以后复用
3. 工作流如何设计——主从编排、人工卡点、分层加载

这里我们没有使用多 Agent，而是用了单 Agent+ 多 SKILL 的结构，这也是考虑到大多数同学对 token 的消耗有要求，所以我们尽量用更为节省的方式来完成工作。

在这套工作流里，我们的思路是是先审查需求的合理性，需求是否有缺失，或者有考虑不周的地方。 只有需求足够完善了，用例的生成才能足够的准确。比如我给了一个类似一句话需求：产品增加了连接器的功能，其实与 mcp 插件是一样的。 填写服务名称， 描述， 选择接入类型（sse 和 streambleHttp），输入服务 url。 在 Agent 模式中可以添加连接器并在对话中使用。

上面明显是一个很不负责任的需求说明， 产品人员默认开发和测试人员能理解他的意思， 但事实上这里有很多还未澄清的东西。 所以在生成用例之前，我们需要先让 AI 来审查，这里面还缺少的产品信息。 这里我列一下 SKILL 分析结果的一部分片段（全文太长了）：

## 🚨 阻塞问题（Blocker）

### B1. 连接器与已有 MCP 插件的关系未定义

- **问题**: 需求说"与 MCP 插件是一样的"，但平台已存在功能完全覆盖的 MCP 插件（SSE/HTTP 双协议、Agent 集成、`cases/plugin_marketplace/mcp_plugin_create_test.py` 已稳定运行）。两者是替换、并存还是子集？不明确则无法确定测试范围。
- **引用证据**: `产品文档/工作流文档/工作流/工作流节点分类说明/信息处理节点/插件节点.md#常见问题`
- **给 PM 的追问**: 「连接器」与已有「MCP 插件」是什么关系？(a) 替换 MCP 插件并废弃旧入口？(b) 并存为独立新类型？(c) MCP 插件的子集？现有 MCP 插件用户的迁移路径是什么？旧 API（CreateMcpPlugin / mcp_type 字段）是否保留？插件搜索 create_types 枚举如何变化？

### B2. 服务名称长度和字符集未明确

- **问题**: 只说"填写服务名称"，未给最小/最大字符数、字符集、空字符串处理、超长处理。
- **给 PM 的追问**: 连接器名称的最小/最大字符数是多少？支持哪些字符（中文/英文/数字/符号/emoji）？空字符串和纯空格如何处理？超长输入截断还是拒绝？

### B3. 描述字段长度和格式未明确

- **问题**: 只说"填写描述"，未给字符数范围、是否允许换行/URL/Markdown。
- **给 PM 的追问**: 描述字段的最大字符数是多少？是否支持换行、URL、Markdown？在 Agent 工具列表中展示时是否截断？

### I4. 审计日志格式扩展

- **问题**: 现有日志 Content 格式为"编辑-Multi-Agent 模式-Agent\"name\"添加工具\"x\""，Agent 中添加连接器是否走同一路径？
- **引用证据**: `cases/platform_management/audit_log/agent/agent_add_plugin_audit_log_test.py`
- **给 PM 的追问**: 创建/编辑/删除连接器以及在 Agent 中添加/移除连接器是否记录审计日志？Content 文案格式是什么？

### I5. 计费/用量统计口径

- **问题**: 用户自带 URL 的连接器属于自调用，是否纳入插件用量统计？
- **引用证据**: `产品文档/公共模块/数据报表-资源看板.md`
- **给 PM 的追问**: 连接器调用是否纳入资源看板插件用量统计？是否计费？统计颗粒度（调用次数/Token/流量）？

### I6. 工作流插件节点是否支持引用连接器

- **问题**: 需求只说 Agent 模式可用，未提工作流。工作流插件节点已支持 API/代码/MCP/应用四类。
- **引用证据**: `产品文档/工作流文档/工作流/工作流节点分类说明/信息处理节点/插件节点.md`
- **给 PM 的追问**: 连接器是否支持在工作流的插件节点中引用？若不支持，UI 上是否明确告知用户"仅 Agent 模式可用"？

从上面的分析片段可以看出，SKILL 结合了产品其他模块的功能，来对新加的连接器需求进行了思考。 即便需求里没有写审计，计费，工作流，但模型还是从知识库中分析出来了关联性。所以在这里，需要测试人员跟产品经理补全这些缺失的信息，才可以进入下一步的测试用例生成的步骤。

PS：需求分析这一步是非常重要的，很多同学都是简单的把需求文档扔给 AI 后就开始生成用例，这种操作的效果会非常差。

下面再看一下生成的测试用例是什么样的：

## 测试点清单

### 🟥 P0 - 核心主流程

- [x] TP01 创建连接器（SSE 类型）成功
- [x] TP02 创建连接器（Streamable HTTP 类型）成功
- [x] TP03 在 Agent 应用中添加已创建的连接器
- [x] TP04 评测端对话中连接器被成功调用，返回正常响应
- [x] TP05 发布含连接器的 Agent 应用，用户端对话正常调用连接器
- [x] TP06 删除连接器

### 🟧 P1 - 边界值 & 异常路径

- [x] TP07 服务名称：最大字符数边界值
- [x] TP08 服务名称：超出最大字符数
- [x] TP09 服务名称：空字符串 / 纯空格
- [x] TP10 服务名称：包含特殊符号
- [x] TP11 服务 URL：填入内网地址（SSRF 防护）
- [x] TP12 服务 URL：填入 localhost / 127.0.0.1
- [x] TP13 服务 URL：格式非法
- [x] TP14 服务 URL：超出最大长度
- [x] TP15 连接器调用外部服务超时，对话降级行为符合预期
- [x] TP16 连接器调用外部服务返回 5xx，对话异常处理符合预期
- [x] TP17 删除已被 Agent 引用的连接器
- [x] TP18 重复创建同名连接器

### 🟨 P2 - 兼容性 & 权限 & 多环境

- [x] TP19 含连接器的 Agent 应用版本回退，连接器配置不丢失
- [x] TP20 无权限角色尝试创建连接器
- [x] TP21 无权限角色尝试在 Agent 中添加连接器
- [x] TP22 Private 环境：创建连接器并在对话中调用
- [x] TP23 International 环境：创建连接器并在对话中调用
- [x] TP24 审计日志：Agent 中添加连接器的操作日志 Content 格式正确
- [x] TP25 连接器调用次数在资源看板中正确统计

### ⬜ 暂不测试 / 待澄清

- [ ] TP-X1 工作流插件节点引用连接器（待 PM 澄清 finding I6）
- [ ] TP-X2 共享/导出含连接器的应用，凭证处理正确（待 PM 澄清 finding I3）
- [ ] TP-X3 连接器鉴权方式（待 PM 澄清 finding B6）
- [ ] TP-X4 连接器与已有 MCP 插件的迁移兼容性（待 PM 澄清 finding B1）

---

## 手工测试用例

### TC01 创建连接器（SSE 类型）成功

- **优先级**: P0
- **测试点**: TP01
- **前置条件**:
  - 已登录系统，具备"创建连接器"权限
  - 当前空间连接器数量未达上限
- **测试步骤**:
  1. 进入连接器管理页面，点击"新建连接器"
  2. 填写服务名称：`test-connector-sse`（合法值，中英文均可）
  3. 填写描述：`测试用 SSE 连接器`
  4. 接入类型选择 `SSE`
  5. 服务 URL 填写：`https://mcp.example.com/sse`（合法 https 地址）
  6. 点击"保存"
- **预期结果**:
  1. 连接器创建成功，页面跳转回连接器列表
  2. 列表中可见新建的连接器，名称、类型（SSE）、URL 均正确显示
  3. 连接器状态显示为正常/可用
- **关联用例参考**: `cases/plugin_marketplace/mcp_plugin_create_test.py`

---

### TC02 创建连接器（Streamable HTTP 类型）成功

- **优先级**: P0
- **测试点**: TP02
- **前置条件**:
  - 已登录系统，具备"创建连接器"权限
- **测试步骤**:
  1. 进入连接器管理页面，点击"新建连接器"
  2. 填写服务名称：`test-connector-http`
  3. 填写描述：`测试用 HTTP 连接器`
  4. 接入类型选择 `Streamable HTTP`
  5. 服务 URL 填写：`https://mcp.example.com/mcp`
  6. 点击"保存"
- **预期结果**:
  1. 连接器创建成功
  2. 列表中可见新建的连接器，类型显示为 `Streamable HTTP`（或其正确文案）
- **待澄清**: 接入类型文案以 PM 确认为准（finding B5：需求原文"streambleHttp"疑似拼写错误）

---

### TC03 在 Agent 应用中添加连接器

- **优先级**: P0
- **测试点**: TP03
- **前置条件**:
  - 已完成 TC01，连接器创建成功
  - 已创建一个 Agent 模式应用
- **测试步骤**:
  1. 进入 Agent 模式应用的配置页面
  2. 找到"工具/连接器"配置区域，点击"添加连接器"
  3. 在连接器列表中选择 TC01 创建的连接器
  4. 点击"确认添加"
  5. 保存 Agent 应用配置
- **预期结果**:
  1. 连接器成功添加到 Agent，工具列表中可见该连接器
  2. 连接器名称、类型显示正确
  3. 应用配置保存成功
- **关联用例参考**: `cases/plugin_marketplace/mcp_plugin_create_test.py`（AgentModelService.add_plugin 步骤）

---

### TC04 评测端对话中连接器被成功调用

- **优先级**: P0
- **测试点**: TP04
- **前置条件**:
  - 已完成 TC03，连接器已添加到 Agent 应用
  - 评测端可用
- **测试步骤**:
  1. 进入 Agent 应用评测端
  2. 输入能触发连接器调用的问题（如："调用 [连接器名称] 执行查询"）
  3. 等待 Agent 响应
- **预期结果**:
  1. Agent 对话成功完成，状态码为 1（成功）
  2. Agent 调用链中可见连接器被调起（tool_invoke 记录存在）
  3. 响应内容包含连接器返回的数据
- **关联用例参考**: `cases/plugin_marketplace/mcp_plugin_create_test.py`（do_chat_with_options + check_agent_invoke）

上面是生成的测试用例的一些片段。下面我们来看一下，这一套 skill 中的细节。

---

0. 先认识这两套 Skill

一个 Skill 不是一段"超级提示词"，而是 SKILL.md（工作流编排）+ references/（知识库）+ 可选 scripts/ 的组合。本仓库的两套 Skill 目录如下：

.codebuddy/skills/
├── req-review/                       # 需求评审主 Skill
│   ├── SKILL.md                      #   工作流编排（3 步）
│   └── references/                   #   知识库（人工维护）
│       ├── association_rules.md      #     关联规则表（起步为空）
│       ├── requirement_types.md      #     需求类型识别表（起步为空）
│       ├── review_checklist_common.md#     通用审查 checklist（核心）
│       └── review_checklist_by_type/ #     按类型的专项 checklist（待启用）
├── req-review-associator/SKILL.md    # 子 Skill：找关联模块 + 受影响用例
├── req-review-challenger/SKILL.md    # 子 Skill：按 checklist 挑战 + 写报告
└── req-test-cases/                   # 手工用例生成 Skill
    ├── SKILL.md                      #   两阶段工作流（测试点 → 用例）
    └── references/
        └── feature_impact_rules.md   #     产品特性关联规则（业务规则）

整条链路串起来是：

新需求 ──► req-review ──► <slug>-review.md (评审报告)
                              │
                              ▼
                       req-test-cases ──► <slug>-test-cases.md (手工用例)

记住这张图，后面所有设计都是围绕"如何让 Agent 在每一步都拿到恰好够用的知识"展开的。

---

1. 重点一：知识库如何构建

核心理念：知识库不是"再写一份文档"，而是让团队已有资产能被 Agent 读懂、并按需取用。 而且，知识库和测试代码一起放进 git 工程（Everything in Git），让"知识演进"和"版本演进"绑定，避免规则改了代码没改的漂移。

测试 Skill 真正会用到的知识有三个来源，缺一不可，也不应合并：

来源	位置	谁维护	本教程是否重点
来源 1：需求文档	产品需求文档/、docs/req-review/*-review.md	PM 产出 + Skill 沉淀	✅ 重点
来源 2：人工维护规则	.codebuddy/skills/*/references/*.md	测试人员手写	✅ 重点
来源 3：自动化用例代码与注释	cases/**/*.py	测试人员/Skill 产出	辅助

我之前说过 everything in git 是一个非常重要的理念，这里可以看到我们的自动化测试用例代码，也可以是知识库供 SKILL 读取分析

下面把重点放在来源 1 和来源 2。

1.1 来源 1：需求文档的沉淀

需求文档是知识库的"事实底座"。它回答的是 "产品到底长什么样、有哪些约束"。

关键设计不是把所有需求堆进一个大文件，而是按模块分类切片。 原因是渐进式披露：海量信息一次性塞给 Agent 会撑爆上下文、稀释信噪比。所以需求文档要分类到 Agent 能"按当前任务精准定位"的粒度。例如本仓库的 产品需求文档/ 就是按模块、按功能拆成多个 md，而不是一份万字长文。

Skill 怎么用它？看 req-review-associator 的工作流——它做"关联分析"时，用 codebase_search（语义检索）在 产品需求文档/ 下做语义召回，找出新需求会影响哪些已有模块；codebase_search 失效时降级用 search_content 文本召回。这意味着：需求文档写得越清晰、分类越合理，关联分析的召回率就越高。

1.2 来源 2：人工维护的规则文档（核心规则）

需求文档只说"产品是什么"，但不会教 Agent 怎么测。测试经验、方法论、业务踩坑——这些"只在测试同学脑子里"的知识，必须显式落盘成 Agent 可读的规则文件，放在 references/ 下。

这类规则又分两种，一定要分开维护：

(A) 通用规则——与具体业务无关的测试方法论

典型代表：req-review/references/review_checklist_common.md。它把"任何字符串字段都要查长度边界""任何数字字段都要查取值范围"这类放之四海皆准的测试经验，固化成结构化条目：

### CHK-BD-001 字符串字段的长度边界
- 类别: boundary
- 默认严重度: blocker
- 适用范围: 任何用户输入的字符串字段（名称、描述、备注、标签等）
- 检查问题:
  1. 是否明确了最小字符数？
  2. 是否明确了最大字符数？
  3. 空字符串、纯空格如何处理（拒绝/默认值/允许）？
  4. 超长输入是截断、报错还是拒绝？
- 命中条件: 需求中提到"输入/名称/描述/备注/标签"等字段，但未给出长度范围
- 建议追问: 请明确 <字段名> 的字符数范围（含上下界）、空值/纯空格的处理、超长输入的处理策略

设计要点：

• 每条规则结构统一（id / 类别 / 默认严重度 / 适用范围 / 检查问题 / 命中条件 / 建议追问），Agent 才能稳定解析。
• 唯一 id（CHK-XX-NNN），便于报告里追溯"这条 finding 来自哪条规则"。
• 改规则不改代码：调整审查行为只需编辑这个 md，SKILL.md 不动。这是知识与流程解耦的关键。

(B) 业务规则——绑定具体产品的"踩坑经验"

典型代表：req-test-cases/references/feature_impact_rules.md。它编码的是业务专家才知道的隐式依赖：某个模块发生某种变更时，必须连带验证哪些下游特性。

| rule_id | trigger_module | trigger_action | must_test_features | reason |
|---------|----------------|----------------|--------------------|--------|
| FR002 | 模型广场 | 新增支持深度思考的模型 | 标准模式-深度思考功能, 多Agent模式-深度思考功能 | 深度思考绑定模型能力，新增需验证入口和效果 |
| FR001 | 模型广场 | 新增模型 | 标准模式-模型切换, 多Agent模式-模型切换, ... | 模型是所有应用模式的消费上游，入口分散 |
| FR007 | 平台端用户权限 | 新增角色/调整权限点 | 应用导出-权限校验, 空间管理-权限校验, 所有业务模块-越权验证 | 权限变更需在所有受保护入口回归越权 |

这正是用户问题里提到的例子："模型广场新增了模型，规则里写要询问是否支持深度思考参数，这样才能设计用例。" —— 对应 FR002。语义搜索抓不到这种隐式关联（需求文本里压根不会提"深度思考"），所以必须靠人工沉淀成规则表，req-test-cases 在生成测试点时读取它，自动补出"深度思考入口验证"这类必测点。

这种规则就是测试专家们根据自己产品的特点，总结出来的设计测试用例的规律。

为什么通用规则和业务规则要分开放？

	通用规则	业务规则
内容	测试方法论（边界、异常、并发…）	产品特定的依赖/踩坑
是否随产品变	基本不变	产品迭代就要更新
加载时机	req-review-challenger 永远加载	req-test-cases 按命中加载
例子	字符串长度校验	新增模型→验证深度思考

分开维护，才能让"稳定的方法论"和"易变的业务知识"各自演进，互不干扰。

1.3 知识库的"分层披露"——别一股脑全塞给 Agent

规则一多，就不能全量塞进上下文。两套 Skill 都用了分层加载：

• 第一层（SKILL.md）：基本工作流 + 通用规则索引，触发即加载。
• 第二层（按需 references）：req-review-challenger 先读 requirement_types.md 判断需求类型，只加载命中类型的专项 checklist（review_checklist_by_type/<type>.md）；类型表为空时退化为只加载通用 checklist。
• 第三层（用例库语义搜索）：req-test-cases Phase 2 用 codebase_search 在 cases/ 下搜 2-3 次、读 Top 3 用例的文件头，学步骤粒度和断言习惯。

---

2. 重点二：Skill 是自学习的（知识回流闭环）

这是整套设计最关键的理念：Skill 每跑一次，都在给知识库添砖加瓦。 知识库不是一次性写完的静态资产，而是随着使用越用越厚。

2.1 回流闭环全景

     ┌──────────────────────────────────────────────────┐
     │                    知识库（git 工程内）              │
     │                                                  │
     │  需求文档        人工规则           历史用例          │
     │  产品需求文档/  references/*.md    cases/**/*.py     │
     └────▲─────────────────▲────────────────▲──────────┘
          │ 沉淀评审报告      │ 人工提炼规则      │ 沉淀新用例
          │                 │（候选规则提示）    │
┌─────────┴────┐    ┌───────┴────────┐  ┌──────┴────────┐
│  req-review   │───►│ <slug>-review.md│  │ req-test-cases │
│ （评审通过）    │    │  （沉淀产物）     │─►│  （生成用例）    │
└──────────────┘    └────────────────┘  └───────────────┘
                             │                  │
                             └──── 作为下次输入 ──┘
                                   ▼
                           <slug>-test-cases.md（沉淀产物）

用一句话说：生成的需求文档和测试用例文档，都会归档到知识库中，以供后续的需求使用。 完成这种自学习的闭环能力。

---

3. 重点三：工作流设计

知识库解决"知识放哪"，工作流解决"按什么顺序、用哪些知识、产出什么"。两套 Skill 的工作流有四个值得学习的设计模式。

3.1 模式一：主从编排（单一职责拆分）

req-review 没有把所有事塞进一个 SKILL.md，而是拆成"主 + 两子"：

req-review（主：编排 + 输入理解 + 最终确认）
   │
   ├─ Step 2 ─► req-review-associator（子：只负责"找关联"，返回 md 片段，不落盘）
   │
   └─ Step 3 ─► req-review-challenger（子：只负责"按 checklist 挑战 + 写报告"）

每个子 Skill 单一职责：associator 只找关联模块和受影响用例；challenger 只挑战需求并组装报告。好处是各自的上下文干净、可独立演进、可被复用。

3.2 模式二：人工卡点（Human Checkpoint）

req-test-cases 的两阶段工作流刻意在中间设了一个人工确认点：

Phase 1: 生成测试点清单 ──► 写入 <slug>-test-cases.md（status: 测试点待确认）
                          ──► 在对话中展示，等用户确认/增删
              ┃
          【人工卡点】  ← 用户说"确认，生成用例" / "删掉 TP09" / "TP06 补充：最大50字符"
              ┃
Phase 2: 展开手工用例 ──► 覆写文件（status: 已生成）

为什么要卡？因为测试点是廉价的、用例是昂贵的。让用户在便宜的阶段（测试点清单）就介入调整，避免在昂贵的阶段（几十条详细用例）才发现方向错了。这是 Agent 工作流里"早反馈、低成本纠偏"的典型实践。

文件里的 status 字段还支持中断续跑：用户说"继续生成用例"时，Skill 读 status 决定从哪一步恢复。

结尾

今天就先讲这么多， 我这套东西仍然还需要脱敏， 后续会在星球中开启直播并分享相关 SKILL 包。 最后再宣传一下我得星球：