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

下面先展示一下需求评审的多 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 | 平台端用户权限 | 新增角色/调整权限点 | 应用导出-权限校验, 空间管理-权限校验, 所有业务模块-越权验证 | 权限变更需在所有受保护入口回归越权 |