编写高质量 Skill 系列 -- 如何设计需求分析与用例生成的 SKILL

找死的豆腐

241人浏览 · 2026-07-09 17:58:02

找死的豆腐 · 2026-07-09 17:58:02 发布

「需求评审」和「手工用例生成」的知识库要如何构建
下面先展示一下需求评审的多 SKILL 串联的工作流结构

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

知识库如何构建——需求文档沉淀 + 两类人工维护文档（通用规则、业务规则）
Skill 是自学习的——评审通过的需求、生成的用例都会回流知识库，供以后复用
工作流如何设计——主从编排、人工卡点、分层加载
这里我们没有使用多 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) 并存为独立新类型？© 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 - 核心主流程

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

🟧 P1 - 边界值 & 异常路径

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

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

TP19 含连接器的 Agent 应用版本回退，连接器配置不丢失
TP20 无权限角色尝试创建连接器
TP21 无权限角色尝试在 Agent 中添加连接器
TP22 Private 环境：创建连接器并在对话中调用
TP23 International 环境：创建连接器并在对话中调用
TP24 审计日志：Agent 中添加连接器的操作日志 Content 格式正确
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 中的细节。

先认识这两套 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 ──► -review.md (评审报告)
│
▼
req-test-cases ──► -test-cases.md (手工用例)
记住这张图，后面所有设计都是围绕"如何让 Agent 在每一步都拿到恰好够用的知识"展开的。

重点一：知识库如何构建
核心理念：知识库不是"再写一份文档"，而是让团队已有资产能被 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/.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 │───►│ -review.md│ │ req-test-cases │
│ （评审通过） │ │ （沉淀产物） │─►│ （生成用例） │
└──────────────┘ └────────────────┘ └───────────────┘
│ │
└──── 作为下次输入 ──┘
▼
-test-cases.md（沉淀产物）
复制代码
用一句话说：生成的需求文档和测试用例文档，都会归档到知识库中，以供后续的需求使用。完成这种自学习的闭环能力。

重点三：工作流设计
知识库解决"知识放哪"，工作流解决"按什么顺序、用哪些知识、产出什么"。两套 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: 生成测试点清单 ──► 写入 -test-cases.md（status: 测试点待确认）
──► 在对话中展示，等用户确认/增删
┃
【人工卡点】 ← 用户说"确认，生成用例" / “删掉 TP09” / “TP06 补充：最大50字符”
┃
Phase 2: 展开手工用例 ──► 覆写文件（status: 已生成）
复制代码