Skills 产品化融合：从能力包到智能测试设计全流程
图表索引
本文配套 5 张 draw.io 架构图，可在项目 docs/diagrams/ 目录下查看，用 draw.io 或 VS Code Draw.io 插件打开编辑。导出 PNG/SVG 后可嵌入其他文档。
| 图表 | 文件 | 说明 |
|---|---|---|
| 系统整体架构 | 01-system-architecture.drawio | 前端 → API → MAS → Skills → 基础设施 分层 |
| Skills 三层披露 | 02-skills-3layer-disclosure.drawio | L1 发现 → L2 激活 → L3 执行 |
| ReAct 执行循环 | 03-react-execution-loop.drawio | Think → Act → Observe → Loop |
| 产品交互与阶段流转 | 04-product-interaction.drawio | 用户、Tab、对话区、产出物、门禁、后端 |
| 阶段内部流程 | 05-phase-internal-flow.drawio | LOAD-RULES → ANALYZE → GENERATE → VERIFY |
为什么要写这篇
你可能会想：Skills 听起来像「技能」，但具体是啥？和产品、和测试设计又有什么关系？
这篇就是想用一篇讲清楚三件事：什么是 Skills、怎么把 Skills 融进产品、架构怎么设计。尽量口语化、通俗易懂。上面先给了图表索引，方便对着图看。
一、先说清楚：Skills 到底是什么？
一句话概括：Skills 就是一整套可被 AI Agent 按步骤执行的「能力包」，用文件夹 + Markdown 文件来描述，而不是写死在代码里。
打个比方：以前我们做测试设计，得在代码里写死「先分析需求、再建模型、再生成用例」——改一步就要改代码、发版。而 Skills 的做法是：把这些步骤写成一份份「说明书」（Markdown），Agent 启动时读一读，就知道该怎么做。加新能力 = 加新文件夹，不用动主流程代码。
Skills 长什么样？
以 DongTDD 为例，一个 Skill 的目录结构大概是这样的：
skills/dongtdd/
├── SKILL.md # 主指南：这个 Skill 能干啥、怎么用
├── references/
│ ├── rules.md # 全局规则
│ ├── modeling-sop.md # 建模标准流程
│ └── phases/ # 每个阶段的执行策略
│ ├── 01-req-preprocess/
│ │ ├── analyze.md # 怎么分析
│ │ ├── generate.md # 怎么生成
│ │ └── verify.md # 怎么验证
│ ├── 02-domain-analyze/
│ ├── 03-mbt-design/
│ └── ...
└── assets/
├── templates/ # 产出物模板
└── examples/ # 参考示例
核心就三块：
- SKILL.md：总纲，告诉 Agent「我是谁、我能干啥、整体流程是啥」
- references/phases/：每个阶段的「说明书」，分 analyze / generate / verify 三步
- assets/：模板和示例，Agent 照着填、照着学
这种设计遵循一个叫 Agent Skills 规范 的东西，核心思想是「三层渐进式披露」：
- L1 发现：先
list_skills()，只拿 name + description，轻量 - L2 激活：需要时
read_skill_md(skill_id)，读完整 SKILL.md - L3 执行：按需读
read_phase_guide、read_template、read_example，用到哪读到哪
这样 Agent 不用一上来就把所有文档塞进上下文，按需加载，省 token、也省脑子。三层披露的流程示意见上文「图表索引」里的 02-skills-3layer-disclosure。
二、产品形态：用户看到的六个 Tab
说完 Skills 是什么，再看用户端长什么样。
在 qin-client 的用例设计页面里，你会看到六个阶段 Tab：
需求分析 | 测试分析 | 设计 | 规划 | 评审 | 沉淀
这六个 Tab 不是拍脑袋定的，而是和 DongTDD 的 6 个 Phase 一一对应：
| 产品 Tab | DongTDD Phase | 核心产出 |
|---|---|---|
| 需求分析 | 01-req-preprocess | 需求分析文档、需求清单 |
| 测试分析 | 02-domain-analyze + 03-mbt-design | 域划分、建模计划、测试模型 |
| 设计 | 04-testcase-gen | 测试用例（思维导图） |
| 规划 | 原有功能 | 执行计划、资源分配 |
| 评审 | 05-quality-review | 追溯矩阵、质量报告 |
| 沉淀 | 06-evaluation | 项目评测、经验沉淀 |
也就是说：前端的六个 Tab，就是 Skills 六个阶段在产品上的具象化。用户切 Tab，本质是在不同阶段之间切换；每个阶段背后，都有一套 Skills 定义的 analyze → generate → verify 流程在跑。产品交互与阶段流转见上文「图表索引」里的 04-product-interaction。
三、怎么把 Skills 融进工程？核心架构
Skills 是「说明书」，那谁来读、谁来执行？这就是 testdata-llm/app/mas 这套多智能体系统（MAS）要干的事。
3.1 整体思路：Skills 驱动，而不是硬编码
以前的做法：在代码里写死「需求分析 Agent 调 A 工具、测试分析 Agent 调 B 工具」——加一个阶段就要改一堆代码。
现在的做法：Agent 启动时先 list_skills() 发现能力，再根据用户意图选 Skill，读 SKILL.md 按步骤执行。加新 Skill = 在 app/skills/ 下放一个符合规范的文件夹，主流程几乎不用动。
3.2 核心组件一览
整体分层大概是：前端（六个 Tab）→ API 层（unified chat stream）→ MAS 多智能体层（小T + 各类 tools）→ Skills 层（dongtdd 等）。小T（Master Agent）手里有这几类工具：
- skill_tools：发现 Skills、读 SKILL.md、读阶段指南（L1/L2/L3）
- file_tools：读文档、读 URL
- artifact_tools：保存/读取阶段产出物（OSS + MySQL）
- script_tools：执行 Python 脚本
- subagent_tools：动态创建子 Agent，上下文隔离
- mcp_bridge_tools：复用现有文档/接口分析能力
系统整体架构的示意图见上文「图表索引」里的 01-system-architecture。
3.3 执行流程：Think → Act → Observe → Loop
小T 是一个 ReActAgent，核心循环就是：
- Think：根据当前上下文，决定下一步干啥（调工具 or 给答案）
- Act：调用工具（比如
skill_tools.read_phase_guide） - Observe：拿到工具返回结果，塞进对话历史
- Loop：继续 Think，直到任务完成或达到最大轮次
关键设计：第一步自动执行 list_skills()，这样 Agent 一上来就知道有哪些 Skill 可用，不会「瞎猜」。ReAct 循环的示意见上文「图表索引」里的 03-react-execution-loop。
当用户说「帮我分析这个需求文档」时，Agent 会：从 list_skills 的结果里匹配到 dongtdd → 调用 read_skill_md("dongtdd") 拿到完整执行指南 → 按 SKILL.md 的 Step 4，对每个阶段执行 LOAD-RULES → ANALYZE → GENERATE（读模板、生成、保存）→ VERIFY。每一步都会通过 skill_tools 按需读取 analyze/generate/verify 的 md，以及 read_template、read_example，而不是把整本「说明书」一次性塞给 LLM。阶段内部流程见上文「图表索引」里的 05-phase-internal-flow。
3.4 阶段间数据怎么传？
Skills 的每个 Phase 都有输入输出：比如「域分析」要读「需求分析」的产出，「用例生成」要读「建模计划」。
在 Web 环境下，没有本地 .dongtdd/ 目录，所以用 artifact_tools：
- 保存：
artifact_tools.save_artifact(project_id, phase_id, artifact_type, artifact_name, content)→ 存到 OSS + MySQL - 读取：
artifact_tools.read_artifact(project_id, artifact_type, phase_id)→ 前序阶段的产出物
同时，AgentContext 里有一个 shared_data，父子 Agent 共享，用来在内存里传递「当前项目 ID」「已完成阶段」等信息，避免重复执行。
3.5 兜底逻辑：阶段流程完整性检查
Agent 有时会「偷懒」：只说了句「我已经分析完了」就停，但实际没调用 save_artifact。
所以 ReActAgent 里有一套 阶段流程完整性检查：检查是否读过 analyze / generate 指南、是否读过模板、是否调用了 save_artifact、是否执行了 verify。如果发现缺了哪一步，就自动给 Agent 塞一条系统提示，逼它把流程补全。这样即使用户不盯着，也能保证每个阶段按 SKILL.md 的标准流程跑完。
四、架构设计要点（为什么这样设计）
为什么用 Skill 而不是硬编码？
| 对比项 | 硬编码 | Skills 驱动 |
|---|---|---|
| 加新能力 | 改代码、发版 | 加文件夹、重启即可 |
| 改流程 | 改逻辑、回归测试 | 改 md 文件 |
| 多 Skill 共存 | 要写路由、if-else | 扫描目录、自动发现 |
| 能力描述 | 写在代码注释里 | 写在 SKILL.md，Agent 直接读 |
Skills 的本质是：把「做什么、怎么做」从代码里抽出来，变成可配置的文档。这样 Agent 更灵活，人也更好维护。
为什么 Agent 要「按需读取」？
如果一上来就把 SKILL.md + 所有 phases 的 md 全塞进 prompt，token 会爆，而且 LLM 容易「注意力涣散」。所以用三层渐进式披露：先发现、再激活、再按需读。Agent 只加载当前阶段需要的指南和模板，用完就丢，下一阶段再读下一阶段的。这样既省 token，又让每一步的指令更清晰。
工具和 Agent 的统一调度
在 MAS 里，调工具和调子 Agent 用的是同一个接口：ctx.call(callee, **kwargs)。Agent 不需要区分「这是工具还是子 Agent」，统一通过 call 调度，权限由 permitted_callees 控制，调用链通过 call_stack 追踪。
前后端怎么衔接？
前端六个 Tab 的 stage 会传到后端，后端通过 project_id + design_id 等上下文，知道用户当前在哪个阶段。Agent 执行时会从 ctx.shared_data 里拿到 completed_phases，避免重复执行；从 ctx.links 里拿到用户提供的文档链接。SSE 会推送 stage（thinking / acting / phase_progress / completed 等），前端根据这些状态更新 UI 和进度条。
五、产品交互：用户实际怎么用
界面布局上（以需求分析 Tab 为例）：左侧文档输入区域（添加文档链接、文档预览），右侧小T 对话区；下方是产出物展示（需求清单、功能点列表、测试要点等）。SSE 的 stage（thinking / acting / phase_progress / streaming / completed / error）会驱动前端的「思考中…」「正在读取技能指南…」、进度条和完成态。
用户切换 Tab 时，前端有阶段门禁：例如进「测试分析」要先完成「需求分析」，进「规划」要先完成「设计」等。不满足时会提示对应文案；设计创建人可以点击阶段前图标切换状态（designStatus 的 status：0=未开始，1=进行中，2=已完成）。
一个典型的用户旅程：用户进「需求分析」Tab，粘贴文档链接，输入「帮我分析这个需求」→ 小T 自动 list_skills，匹配 dongtdd，读 SKILL.md，执行 01-req-preprocess：LOAD-RULES → ANALYZE → GENERATE → VERIFY → 产出物通过 artifact_tools 保存，前端展示需求清单等 → 用户切到「测试分析」Tab（门禁通过），继续「生成域划分」→ 小T 读 02-domain-analyze 指南，从 read_artifact 读需求分析产出，生成域划分和建模计划。
六、小结：一句话串起来
Skills 是一套用文件夹 + Markdown 描述的「能力包」，Agent 通过 skill_tools 发现、读取、按步骤执行；产品端的六个 Tab 对应 Skills 的六个阶段，每个阶段背后是 analyze → generate → verify 的标准流程；架构上 MAS 负责「读说明书、调工具、传数据」，Skills 只负责「写好说明书」——这样加新能力不用改主流程，改流程也不用改代码。
如果你要扩展：加一个新 Skill，就在 app/skills/ 下放一个符合规范的文件夹；加一个新阶段，就在对应的 phase 下补 analyze / generate / verify 三个 md。剩下的，交给 Agent 和工具链自动跑起来。
基于 DongTDD / testdata-llm / qin-client 的现有实现整理。