@modus-ai/modus 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +98 -98
  2. package/package.json +2 -2
  3. package/templates/commands/harness.md +2 -0
  4. package/templates/commands/plan.md +6 -4
  5. package/templates/commands/spec.md +7 -5
  6. package/templates/paths-v4.md +2 -0
  7. package/templates/skills/modus-harness/SKILL.md +1 -0
  8. package/templates/skills/modus-plan/SKILL.md +134 -11
  9. package/templates/skills/modus-spec/SKILL.md +89 -3
  10. package/templates/template/api-chain.md +69 -0
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  </p>
4
4
 
5
5
  <p align="center">
6
- <a href="https://www.npmjs.com/package/@modus-ai/modus"><img alt="npm version" src="https://img.shields.io/npm/v/@modus-ai/modus?style=flat-square" /></a>
6
+ <a href="https://www.npmjs.com/package/@tencent/modus-ai"><img alt="npm version" src="https://img.shields.io/npm/v/@tencent/modus-ai?style=flat-square" /></a>
7
7
  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
8
8
  </p>
9
9
 
@@ -38,12 +38,12 @@ Modus 对外只暴露 **Command（斜杠命令）**，这是框架与使用者
38
38
 
39
39
  ### 框架的价值：解决 AI Coding 的四个根本性问题
40
40
 
41
- | AI Coding 的根本问题 | Spring 当年的解法 | Modus 的解法 |
42
- |---------------------|-----------------|-------------|
43
- | AI 不了解我的项目业务 | IoC 容器统一管理依赖 | 三层知识体系，业务上下文按需注入 |
44
- | AI 不遵守我的团队规范 | AOP 切面统一处理横切关注点 | Rule 项目宪法，全局强约束，AI 不可绕过 |
45
- | AI 行为每次不一致 | 约定优于配置，标准化行为模式 | Skill 固化最佳实践，Command 保证执行路径可复现 |
46
- | 经验随人员流动消失 | Spring 生态让经验沉淀为社区标准 | 知识体系随每次交付自动积累，越用越快 |
41
+ | AI Coding 的根本问题 | Spring 当年的解法 | Modus 的解法 |
42
+ | --------------------- | ------------------------------- | ---------------------------------------------- |
43
+ | AI 不了解我的项目业务 | IoC 容器统一管理依赖 | 三层知识体系，业务上下文按需注入 |
44
+ | AI 不遵守我的团队规范 | AOP 切面统一处理横切关注点 | Rule 项目宪法，全局强约束，AI 不可绕过 |
45
+ | AI 行为每次不一致 | 约定优于配置，标准化行为模式 | Skill 固化最佳实践，Command 保证执行路径可复现 |
46
+ | 经验随人员流动消失 | Spring 生态让经验沉淀为社区标准 | 知识体系随每次交付自动积累，越用越快 |
47
47
 
48
48
  **结果是：** 第 1 次用 Modus 开发约 45 分钟，第 N 次约 15 分钟——不是因为 AI 变聪明了，而是框架帮你把项目知识、团队规范、执行流程都预装好了，冷启动成本趋近于零。
49
49
 
@@ -53,14 +53,14 @@ Modus 对外只暴露 **Command（斜杠命令）**，这是框架与使用者
53
53
 
54
54
  就像 Spring 从 Core 扩展到 MVC、Security、Cloud，Modus 的目标是为研效全链路每个节点提供开箱即用的 Command 与配套资产（**当前已完成代码开发全链路，各节点持续扩充中**）：
55
55
 
56
- | 研效节点 | 建设状态 | 代表 Command |
57
- |---------|---------|-------------|
58
- | 项目冷启动 | ✅ 已完成 | `modus init` — 自动扫描代码库，生成三层知识体系 |
59
- | 需求创建 | ✅ 已完成 | `/modus:auto` — 读取 Story，四维评分，智能推荐执行路径 |
60
- | 评估设计 | ✅ 已完成 | `/modus:plan` · `/modus:spec` — 规划设计，产出物人工确认 |
56
+ | 研效节点 | 建设状态 | 代表 Command |
57
+ | ---------- | --------- | ---------------------------------------------------------- |
58
+ | 项目冷启动 | ✅ 已完成 | `modus init` — 自动扫描代码库，生成三层知识体系 |
59
+ | 需求创建 | ✅ 已完成 | `/modus:auto` — 读取 Story，四维评分，智能推荐执行路径 |
60
+ | 评估设计 | ✅ 已完成 | `/modus:plan` · `/modus:spec` — 规划设计，产出物人工确认 |
61
61
  | 代码开发 | ✅ 已完成 | `/modus:vibe` · `/modus:harness` — 轻量编码到全自动双 Loop |
62
- | 测试 | ✅ 已完成 | Harness 内置 — 单测 / 性能 / 安全 / CR 四路并行 |
63
- | 部署发布 | ✅ 已完成 | Harness 内置 — CI 监控 + 逐级灰度冒烟 + 上线日志监控 |
62
+ | 测试 | ✅ 已完成 | Harness 内置 — 单测 / 性能 / 安全 / CR 四路并行 |
63
+ | 部署发布 | ✅ 已完成 | Harness 内置 — CI 监控 + 逐级灰度冒烟 + 上线日志监控 |
64
64
 
65
65
  每个节点均有结构化产出物（`01-analysis.md` → `08-deploy-status.md` + `cr-report.md`）作为决策留痕，支持断点续跑，确保 AI 行为可追溯、可审计、可接手。
66
66
 
@@ -70,14 +70,14 @@ Modus 对外只暴露 **Command（斜杠命令）**，这是框架与使用者
70
70
 
71
71
  Modus 的核心设计理念之一是**按需加载，而非全量预加载**。三级渐进加载策略在实际使用中相比全量加载可节省大量 token：
72
72
 
73
- | 加载方式 | 典型 token 消耗 | 说明 |
74
- |---------|---------------|------|
75
- | **Level 1（必须）** | ~200 | knowledge-catalog 目录索引 |
76
- | **Level 2（按需）** | ~3,000/域 | 仅加载匹配的业务 Skill |
77
- | **Level 3（按需）** | ~500–2,000/文件 | 编码时才读取实际源码 |
78
- | **典型单域 vibe 总计** | **~3,700** | L1 + L2 × 1 域 |
79
- | **典型双域 vibe 总计** | **~6,700** | L1 + L2 × 2 域 |
80
- | **全量加载（8 个业务 Skill）** | **~24,000+** | 应避免 |
73
+ | 加载方式 | 典型 token 消耗 | 说明 |
74
+ | ------------------------------ | --------------- | -------------------------- |
75
+ | **Level 1（必须）** | ~200 | knowledge-catalog 目录索引 |
76
+ | **Level 2（按需）** | ~3,000/域 | 仅加载匹配的业务 Skill |
77
+ | **Level 3（按需）** | ~500–2,000/文件 | 编码时才读取实际源码 |
78
+ | **典型单域 vibe 总计** | **~3,700** | L1 + L2 × 1 域 |
79
+ | **典型双域 vibe 总计** | **~6,700** | L1 + L2 × 2 域 |
80
+ | **全量加载（8 个业务 Skill）** | **~24,000+** | 应避免 |
81
81
 
82
82
  **节省幅度：** 单域场景三级加载约为全量的 **15%**，双域约为 **28%**。
83
83
 
@@ -93,22 +93,22 @@ Modus 的核心设计理念之一是**按需加载，而非全量预加载**。
93
93
 
94
94
  **SubAgent**
95
95
 
96
- | 名称 | 说明 |
97
- |------|------|
96
+ | 名称 | 说明 |
97
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
98
98
  | `SA00 Skills Builder SubAgent` | 知识生命周期管家——初始化、增量更新、ARCHIVE 提取，五种调用模式（A/B/C/D/E）覆盖知识全流程，团队级可复用 |
99
99
 
100
100
  **Commands**
101
101
 
102
- | 名称 | 说明 |
103
- |------|------|
102
+ | 名称 | 说明 |
103
+ | ------------- | ------------------------------------------------------------------------------------- |
104
104
  | `/modus:init` | 一键扫描代码库，自动识别业务域，生成三层知识底座 + 知识全景目录，存量老项目当天可接入 |
105
105
 
106
106
  **Skills**
107
107
 
108
- | 名称 | 说明 |
109
- |------|------|
110
- | `modus-init` | 定义 `/modus:init` 完整执行逻辑（8 步流程、多平台扫描、Skill 生成规范），可复用到任意项目 |
111
- | `modus-skill-creator` | Skill 创建 / 增量更新 / 知识提取的核心引擎，被所有工作流命令共享调用 |
108
+ | 名称 | 说明 |
109
+ | --------------------- | ----------------------------------------------------------------------------------------- |
110
+ | `modus-init` | 定义 `/modus:init` 完整执行逻辑（8 步流程、多平台扫描、Skill 生成规范），可复用到任意项目 |
111
+ | `modus-skill-creator` | Skill 创建 / 增量更新 / 知识提取的核心引擎，被所有工作流命令共享调用 |
112
112
 
113
113
  **目的**
114
114
 
@@ -124,14 +124,14 @@ Modus 的核心设计理念之一是**按需加载，而非全量预加载**。
124
124
 
125
125
  **Commands**
126
126
 
127
- | 名称 | 说明 |
128
- |------|------|
127
+ | 名称 | 说明 |
128
+ | ------------- | ----------------------------------------------------------------------------- |
129
129
  | `/modus:auto` | 读取 TAPD Story，四维评分后推荐最优执行模式，自动透传上下文启动，避免工具错配 |
130
130
 
131
131
  **Skills**
132
132
 
133
- | 名称 | 说明 |
134
- |------|------|
133
+ | 名称 | 说明 |
134
+ | ------------ | ----------------------------------------------------------------- |
135
135
  | `modus-auto` | 四维评分判定树 + 模式推荐逻辑，可复用于任何需要智能分流的研效场景 |
136
136
 
137
137
  **目的**
@@ -146,27 +146,27 @@ Modus 的核心设计理念之一是**按需加载，而非全量预加载**。
146
146
 
147
147
  **SubAgent**
148
148
 
149
- | 名称 | 说明 |
150
- |------|------|
149
+ | 名称 | 说明 |
150
+ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
151
151
  | `SA01 需求分析 SubAgent` | 将 TAPD Story 翻译为精确技术规格，方法级影响范围 + Sprint 拆分，为后续 SubAgent 建立统一上下文；产出 `01-analysis.md`，触发 Gate A0 |
152
- | `SA02 设计方案 SubAgent` | 在需求与编码之间插入设计推导层，生成 LLM 可直接消费的 `02-design-brief.md`，减少编码时的架构歧义；含人工确认节点，触发 Gate A0.5 |
152
+ | `SA02 设计方案 SubAgent` | 在需求与编码之间插入设计推导层，生成 LLM 可直接消费的 `02-design-brief.md`，减少编码时的架构歧义；含人工确认节点，触发 Gate A0.5 |
153
153
 
154
154
  **Commands**
155
155
 
156
- | 名称 | 说明 |
157
- |------|------|
156
+ | 名称 | 说明 |
157
+ | ------------- | ---------------------------------------------------------------------------------- |
158
158
  | `/modus:plan` | 上下文感知规划，六维复杂度分级 + 精准 3 问澄清 + plan.md，Build 确认后直接驱动编码 |
159
- | `/modus:spec` | 规范驱动开发，生成 GIVEN/WHEN/THEN 行为规格 + 四层产出物，归档自动合并主规格库 |
159
+ | `/modus:spec` | 规范驱动开发，生成 GIVEN/WHEN/THEN 行为规格 + 四层产出物，归档自动合并主规格库 |
160
160
 
161
161
  **Skills**
162
162
 
163
- | 名称 | 说明 |
164
- |------|------|
165
- | `modus-plan` | `/modus:plan` 完整执行逻辑，含复杂度评估、知识检索、3 问澄清、Build 确认循环，可复用 |
166
- | `modus-spec` | `/modus:spec` 执行逻辑，含 delta specs、冲突检测、可选 verify、主规格库归档，可复用 |
167
- | `modus-design-brief` | 结构化设计方案生成（落盘 + 内联双模式），被 plan/spec/vibe 共享调用，可独立复用 |
168
- | `modus-analyst` | Harness 需求分析 SubAgent 行为定义，方法级影响范围提取 + HANDOFF 协议，可复用 |
169
- | `modus-designer` | Harness 设计推导 SubAgent 行为定义，架构澄清 + design-brief 生成，可复用 |
163
+ | 名称 | 说明 |
164
+ | -------------------- | ------------------------------------------------------------------------------------ |
165
+ | `modus-plan` | `/modus:plan` 完整执行逻辑，含复杂度评估、知识检索、3 问澄清、Build 确认循环，可复用 |
166
+ | `modus-spec` | `/modus:spec` 执行逻辑，含 delta specs、冲突检测、可选 verify、主规格库归档，可复用 |
167
+ | `modus-design-brief` | 结构化设计方案生成（落盘 + 内联双模式），被 plan/spec/vibe 共享调用，可独立复用 |
168
+ | `modus-analyst` | Harness 需求分析 SubAgent 行为定义，方法级影响范围提取 + HANDOFF 协议，可复用 |
169
+ | `modus-designer` | Harness 设计推导 SubAgent 行为定义，架构澄清 + design-brief 生成，可复用 |
170
170
 
171
171
  **目的**
172
172
 
@@ -181,24 +181,24 @@ Modus 的核心设计理念之一是**按需加载，而非全量预加载**。
181
181
 
182
182
  **SubAgent**
183
183
 
184
- | 名称 | 说明 |
185
- |------|------|
186
- | `SA03 代码开发 SubAgent` | 按 Sprint 逐层实现（数据→服务→编排→接口），编译 Gate A 自动验证（mvn compile），P1/P2 精准重入修复 |
184
+ | 名称 | 说明 |
185
+ | ------------------------ | -------------------------------------------------------------------------------------------------------- |
186
+ | `SA03 代码开发 SubAgent` | 按 Sprint 逐层实现（数据 → 服务 → 编排 → 接口），编译 Gate A 自动验证（mvn compile），P1/P2 精准重入修复 |
187
187
 
188
188
  **Commands**
189
189
 
190
- | 名称 | 说明 |
191
- |------|------|
192
- | `/modus:vibe` | 氛围编程——渐进加载业务上下文后直接编码，适合轻量任务，人工随时介入 |
190
+ | 名称 | 说明 |
191
+ | ---------------- | ------------------------------------------------------------------------ |
192
+ | `/modus:vibe` | 氛围编程——渐进加载业务上下文后直接编码，适合轻量任务，人工随时介入 |
193
193
  | `/modus:harness` | 全自动双 Loop 流程入口，8 个 SubAgent 从需求到部署全程闭环，一条命令驱动 |
194
194
 
195
195
  **Skills**
196
196
 
197
- | 名称 | 说明 |
198
- |------|------|
199
- | `modus-vibe` | 三级渐进加载逻辑 + 编码执行规范，节省约 59% token，可复用于任意上下文感知编码场景 |
200
- | `modus-harness` | Harness Orchestrator 调度中枢，双 Loop 调度规则 + Gate 机制 + HANDOFF 协议，核心可复用 |
201
- | `modus-developer` | 代码开发 SubAgent 行为定义，Sprint 分层实现 + self-code-review + 编译验证，可复用 |
197
+ | 名称 | 说明 |
198
+ | ----------------- | -------------------------------------------------------------------------------------- |
199
+ | `modus-vibe` | 三级渐进加载逻辑 + 编码执行规范，节省约 59% token，可复用于任意上下文感知编码场景 |
200
+ | `modus-harness` | Harness Orchestrator 调度中枢，双 Loop 调度规则 + Gate 机制 + HANDOFF 协议，核心可复用 |
201
+ | `modus-developer` | 代码开发 SubAgent 行为定义，Sprint 分层实现 + self-code-review + 编译验证，可复用 |
202
202
 
203
203
  **目的**
204
204
 
@@ -213,21 +213,21 @@ Modus 的核心设计理念之一是**按需加载，而非全量预加载**。
213
213
 
214
214
  **SubAgent**
215
215
 
216
- | 名称 | 说明 |
217
- |------|------|
218
- | `SA04 代码测试 SubAgent` | 三路径单元测试生成（Happy Path / 边界 / 异常），覆盖并发 + 事务 + 权限场景；与 SA05/SA06 并行执行 |
219
- | `SA05 性能审计 SubAgent` | 静态检测 N+1 / 大数据量 / 深分页风险，量化每个风险影响条数，高/中/低分级；与 SA04/SA06 并行执行 |
216
+ | 名称 | 说明 |
217
+ | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
218
+ | `SA04 代码测试 SubAgent` | 三路径单元测试生成（Happy Path / 边界 / 异常），覆盖并发 + 事务 + 权限场景；与 SA05/SA06 并行执行 |
219
+ | `SA05 性能审计 SubAgent` | 静态检测 N+1 / 大数据量 / 深分页风险，量化每个风险影响条数，高/中/低分级；与 SA04/SA06 并行执行 |
220
220
  | `SA06 安全审计 SubAgent` | 检测多租户隔离漏洞 / 权限缺失 / SQL 注入 / 敏感信息泄露，严重/高/低分级；有严重/高危问题则 Gate B 强制拦截 |
221
- | `SA07 代码评审 SubAgent` | 综合质量评估，P1/P2 触发 Loop 2 精准重入，唯一出口是通过 Gate C（无 P1/P2） |
221
+ | `SA07 代码评审 SubAgent` | 综合质量评估，P1/P2 触发 Loop 2 精准重入，唯一出口是通过 Gate C（无 P1/P2） |
222
222
 
223
223
  **Skills**
224
224
 
225
- | 名称 | 说明 |
226
- |------|------|
227
- | `modus-tester` | 单元测试生成规范 + 三路径覆盖逻辑，可复用为独立测试 Agent |
228
- | `modus-perf-auditor` | N+1 检测规则库 + 性能风险分级模型，可复用为独立性能审计 Agent |
225
+ | 名称 | 说明 |
226
+ | ------------------------ | -------------------------------------------------------------------- |
227
+ | `modus-tester` | 单元测试生成规范 + 三路径覆盖逻辑，可复用为独立测试 Agent |
228
+ | `modus-perf-auditor` | N+1 检测规则库 + 性能风险分级模型，可复用为独立性能审计 Agent |
229
229
  | `modus-security-auditor` | 多租户安全规则 + SQL 注入 / 权限检查规范，可复用为独立安全审计 Agent |
230
- | `modus-reviewer` | CR 问题分级标准 + Loop 2 重入触发逻辑，可复用为独立代码评审 Agent |
230
+ | `modus-reviewer` | CR 问题分级标准 + Loop 2 重入触发逻辑，可复用为独立代码评审 Agent |
231
231
 
232
232
  **目的**
233
233
 
@@ -242,14 +242,14 @@ Modus 的核心设计理念之一是**按需加载，而非全量预加载**。
242
242
 
243
243
  **SubAgent**
244
244
 
245
- | 名称 | 说明 |
246
- |------|------|
245
+ | 名称 | 说明 |
246
+ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
247
247
  | `SA08 部署发布 SubAgent` | CI 监控 + 灰度逐级冒烟 + 上线后 30 分钟日志监控，prd 等待人工确认，可复用为独立部署验证 Agent；完成后触发 ARCHIVE 知识提取 |
248
248
 
249
249
  **Skills**
250
250
 
251
- | 名称 | 说明 |
252
- |------|------|
251
+ | 名称 | 说明 |
252
+ | ---------------- | ---------------------------------------------------------------------------------- |
253
253
  | `modus-deployer` | 部署验证完整流程定义（CI 状态轮询 / 冒烟测试 / 日志监控），可复用到任意 CI/CD 场景 |
254
254
 
255
255
  **目的**
@@ -277,7 +277,7 @@ Modus 的核心设计理念之一是**按需加载，而非全量预加载**。
277
277
  全局安装并初始化：
278
278
 
279
279
  ```bash
280
- npm install -g @modus-ai/modus
280
+ npm install -g @tencent/modus-ai
281
281
  cd your-project
282
282
  modus init # CLI 初始化，生成框架文件和配置
283
283
  ```
@@ -290,15 +290,15 @@ modus init # CLI 初始化，生成框架文件和配置
290
290
 
291
291
  ## 7 个核心命令
292
292
 
293
- | 命令 | 用途 | 产出物位置 |
294
- |------|------|-----------|
295
- | `/modus:init` | 扫描项目，生成业务/团队/技术三层知识库 + 知识目录 | `modus/knowledge/biz-*/SKILL.md`（权威源）+ `.codebuddy/skills/`（平台适配桩）+ `modus/knowledge-catalog.md` |
296
- | `/modus:vibe` | 氛围编程，三级渐进加载业务上下文后直接编码，节省约 59% token | 直接修改代码，编码发现的新知识暂存 `modus/sessions/pending-knowledge.yaml` |
297
- | `/modus:commit` | 知识感知提交：沉淀 vibe 会话发现的新知识到 Skill，再执行 git commit | `modus/sessions/pending-knowledge.yaml`（清空后写入 Skill） |
298
- | `/modus:plan` | 功能规划，两层知识检索 + 3 问澄清 + plan.md + Build 确认执行 | Story 模式：`modus/stories/{story-id}/plan.md`；独立模式：`modus/plans/{name}/plan.md` |
299
- | `/modus:spec` | 规范开发，delta specs + GIVEN/WHEN/THEN 验收，含可选 verify + 冲突检测 | `modus/changes/{name}/`，归档合并到 `modus/specs/` |
300
- | `/modus:auto` | 智能模式推荐：读 TAPD Story，四维评分，推荐 vibe/plan/spec/harness | 启动所选模式后按该模式产出 |
301
- | `/modus:harness` | 全自动双 Loop 多智能体流程，9 个 SubAgent（SA00~SA08）协作，含知识沉淀闭环 | `modus/stories/{story-id}/harness/` |
293
+ | 命令 | 用途 | 产出物位置 |
294
+ | ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
295
+ | `/modus:init` | 扫描项目，生成业务/团队/技术三层知识库 + 知识目录 | `modus/knowledge/biz-*/SKILL.md`（权威源）+ `.codebuddy/skills/`（平台适配桩）+ `modus/knowledge-catalog.md` |
296
+ | `/modus:vibe` | 氛围编程，三级渐进加载业务上下文后直接编码，节省约 59% token | 直接修改代码，编码发现的新知识暂存 `modus/sessions/pending-knowledge.yaml` |
297
+ | `/modus:commit` | 知识感知提交：沉淀 vibe 会话发现的新知识到 Skill，再执行 git commit | `modus/sessions/pending-knowledge.yaml`（清空后写入 Skill） |
298
+ | `/modus:plan` | 功能规划，两层知识检索 + 3 问澄清 + plan.md + Build 确认执行 | Story 模式：`modus/stories/{story-id}/plan.md`；独立模式：`modus/plans/{name}/plan.md` |
299
+ | `/modus:spec` | 规范开发，delta specs + GIVEN/WHEN/THEN 验收，含可选 verify + 冲突检测 | `modus/changes/{name}/`，归档合并到 `modus/specs/` |
300
+ | `/modus:auto` | 智能模式推荐：读 TAPD Story，四维评分，推荐 vibe/plan/spec/harness | 启动所选模式后按该模式产出 |
301
+ | `/modus:harness` | 全自动双 Loop 多智能体流程，9 个 SubAgent（SA00~SA08）协作，含知识沉淀闭环 | `modus/stories/{story-id}/harness/` |
302
302
 
303
303
  ## 典型工作流
304
304
 
@@ -339,11 +339,11 @@ Modus 的知识体系让 AI 从「冷启动」变为「越用越快」：
339
339
 
340
340
  **三层知识结构：**
341
341
 
342
- | 层级 | Skill 文件 | 内容 | 生命周期 |
343
- |------|-----------|------|---------|
344
- | Layer 0-T | `modus-team-conventions` | 编码规范、提交规范、硬性约束 | 人工维护为主 |
345
- | Layer 1 | `modus-tech-wiki` | 架构决策、反模式库（跨项目积累） | 工作流 ARCHIVE 自动积累 |
346
- | Layer 2 | `modus-biz-{domain}` | 领域模型、业务规则、API 契约 | 每次 plan/spec/harness 后回写 |
342
+ | 层级 | Skill 文件 | 内容 | 生命周期 |
343
+ | --------- | ------------------------ | -------------------------------- | ----------------------------- |
344
+ | Layer 0-T | `modus-team-conventions` | 编码规范、提交规范、硬性约束 | 人工维护为主 |
345
+ | Layer 1 | `modus-tech-wiki` | 架构决策、反模式库（跨项目积累） | 工作流 ARCHIVE 自动积累 |
346
+ | Layer 2 | `modus-biz-{domain}` | 领域模型、业务规则、API 契约 | 每次 plan/spec/harness 后回写 |
347
347
 
348
348
  **知识成熟度：** `draft` → `verified` → `proven`（在工作流中被引用后自动晋升，长期未引用自动衰减）
349
349
 
@@ -353,11 +353,11 @@ Modus 的知识体系让 AI 从「冷启动」变为「越用越快」：
353
353
 
354
354
  ```yaml
355
355
  constitution:
356
- tech_stack: "Java 17 + Spring Boot 3 + MyBatis"
357
- build_command: "mvn clean compile -q"
356
+ tech_stack: 'Java 17 + Spring Boot 3 + MyBatis'
357
+ build_command: 'mvn clean compile -q'
358
358
  hard_rules:
359
- - "Mapper 接口必须在 dao 包下"
360
- - "金额字段使用 Long（单位：分）"
359
+ - 'Mapper 接口必须在 dao 包下'
360
+ - '金额字段使用 Long（单位：分）'
361
361
  ```
362
362
 
363
363
  ## `/modus:harness` 流程一览
@@ -381,13 +381,13 @@ Loop 2（精准重入，Gate C 发现 P1/P2 时触发）
381
381
  SA08 部署验证 ⏸️（prd 人工确认）→ ARCHIVE 知识提取 → 人工 Final Review
382
382
  ```
383
383
 
384
- | Gate | 检查对象 | 通过条件 |
385
- |------|---------|---------|
386
- | A0 | `01-analysis.md` HANDOFF | `gate_status = "passed"` |
387
- | A0.5 | `02-design-brief.md` HANDOFF | `gate_status ∈ {passed, warning}` |
388
- | A | 编译命令 | `exit_code = 0` |
389
- | B | 04/05/06 三份报告 HANDOFF | `artifact_status` 均完成且无安全严重/高危 |
390
- | C | `cr-report.md` HANDOFF | `issues` 为空或全为 P3 |
384
+ | Gate | 检查对象 | 通过条件 |
385
+ | ---- | ---------------------------- | ----------------------------------------- |
386
+ | A0 | `01-analysis.md` HANDOFF | `gate_status = "passed"` |
387
+ | A0.5 | `02-design-brief.md` HANDOFF | `gate_status ∈ {passed, warning}` |
388
+ | A | 编译命令 | `exit_code = 0` |
389
+ | B | 04/05/06 三份报告 HANDOFF | `artifact_status` 均完成且无安全严重/高危 |
390
+ | C | `cr-report.md` HANDOFF | `issues` 为空或全为 P3 |
391
391
 
392
392
  每个 SubAgent 的产出物（`01-analysis.md` → `08-deploy-status.md` + `cr-report.md`）均存放在 `modus/stories/{story-id}/harness/`，支持断点续跑。
393
393
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@modus-ai/modus",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Modus — Business-grounded AI coding accelerator for CodeBuddy IDE",
5
5
  "keywords": [
6
6
  "ai",
@@ -10,7 +10,7 @@
10
10
  "skill",
11
11
  "harness"
12
12
  ],
13
- "homepage": "https://github.com/modus-ai/modus",
13
+ "homepage": "https://git.woa.com/investOperations/modus",
14
14
  "license": "MIT",
15
15
  "type": "module",
16
16
  "main": "dist/index.js",
package/templates/commands/harness.md CHANGED
@@ -105,6 +105,8 @@ modus/artifacts/{story_id}/
105
105
  │ ├── cr-report.md ← SubAgent 06 (modus-reviewer)，含 HANDOFF.issues
106
106
  │ ├── deploy-status.md ← SubAgent 07 (modus-deployer)
107
107
  │ └── .harness-state.yaml ← 状态机
108
+ ├── scenarios/
109
+ │ └── api-chain.md ← 场景化接口调用链（Step 1 创建目录，harness 完整流程后内容最丰富）
108
110
  └── archive/ ← 上线后人工触发，输出 summary.md 与 key-scenarios/
109
111
  ```
110
112
 
package/templates/commands/plan.md CHANGED
@@ -86,10 +86,12 @@
86
86
  ```
87
87
  modus/artifacts/{story_id}/
88
88
  ├── design/design.md — --design 模式产出
89
- └── code/
90
- ├── plan.md — 标准模式产出
91
- ├── .modus-state.yaml — 状态机，支持断点续跑
92
- └── spec/ — （如后续接 /modus:spec）
89
+ ├── code/
90
+ │ ├── plan.md — 标准模式产出
91
+ │ ├── .modus-state.yaml — 状态机，支持断点续跑
92
+ │ └── spec/ — （如后续接 /modus:spec）
93
+ └── scenarios/
94
+ └── api-chain.md — 场景化接口调用链（Step 8 生成，供测试团队消费）
93
95
  ```
94
96
 
95
97
  **独立模式（不含 --story）：**
package/templates/commands/spec.md CHANGED
@@ -68,11 +68,13 @@ Feature: 批量审批订单
68
68
  ```
69
69
  modus/artifacts/{story_id}/
70
70
  ├── design/design.md
71
- └── code/
72
- ├── spec/ — delta specs（ADDED/MODIFIED/REMOVED）
73
- ├── spec-proposal.md — 意图与范围
74
- ├── tasks.md — 实现清单（追踪到 Scenario）
75
- └── testcases.md — QA 用例（--testcase 时生成）
71
+ ├── code/
72
+ │ ├── spec/ — delta specs（ADDED/MODIFIED/REMOVED）
73
+ │ ├── spec-proposal.md — 意图与范围
74
+ │ ├── tasks.md — 实现清单（追踪到 Scenario）
75
+ │ └── testcases.md — QA 用例（--testcase 时生成）
76
+ └── scenarios/
77
+ └── api-chain.md — 场景化接口调用链（Step 8 生成，供测试团队消费）
76
78
  ```
77
79
 
78
80
  **独立模式（不含 --story）：**
package/templates/paths-v4.md CHANGED
@@ -73,6 +73,8 @@ last_updated: "2026-05-22"
73
73
  │ ├── vibe-log.md # 编码日志
74
74
  │ ├── cr-report.md # CR 报告
75
75
  │ └── .harness-state.yaml # Harness 状态机
76
+ ├── scenarios/ # 场景化接口调用链（plan/spec 生成）
77
+ │ └── api-chain.md # 业务场景描述 + 接口调用链（供测试团队消费）
76
78
  └── archive/ # 上线验收后人工触发归档
77
79
  ├── summary.md # 精简版人阅读摘要
78
80
  └── key-scenarios/ # 关键场景快照（供后续迭代检索）
package/templates/skills/modus-harness/SKILL.md CHANGED
@@ -144,6 +144,7 @@ B. 强制继续（无业务上下文，风险较高）
144
144
  **解析 Story ID + 初始化状态追踪：**
145
145
  - 从 TAPD URL 提取 Story ID（格式：`tapd.cn/{project}/stories/view/{id}`）
146
146
  - 创建工作目录：`modus/artifacts/{story_id}/code/`
147
+ - 创建场景目录：`modus/artifacts/{story_id}/scenarios/`
147
148
 
148
149
  **`.harness-state.yaml` 断点续跑机制（优先级高于 HANDOFF 块探测）：**
149
150
 
package/templates/skills/modus-plan/SKILL.md CHANGED
@@ -29,11 +29,30 @@ disable: false
29
29
  --continue X → CONTINUE_MODE=true，PLAN_NAME=X（进入接力分支，见「Continue 流程」）
30
30
  --code X → CODE_MODE=true，CODE_PLAN=X（进入任务驱动编码分支，见「Code Mode 流程」）
31
31
  --quick → QUICK_MODE=true（跳过域确认和澄清问题）
32
- --story X → STORY_ID=X（关联 TAPD Story）
32
+ --story X → 提取 X 末尾的纯数字段作为 STORY_ID（若 X 已是纯数字则直接使用）
33
+ 示例：https://tapd.woa.com/.../1020426489134444072 → STORY_ID=1020426489134444072
33
34
  --project X → PROJECT=X（多项目指定）
34
35
  --enhance X → ENHANCE_DOMAIN=X（前置强制刷新指定域 Skill）
35
36
  --no-build → NO_BUILD=true（生成 plan.md 后跳过 Build 循环）
36
37
  --read-only → READ_ONLY=true（同 NO_BUILD，永远不触发代码生成）
38
+ ```
39
+
40
+ **TAPD URL 自动检测（无需 --story flag）：**
41
+
42
+ 若用户 prompt 中**直接包含 TAPD URL**（匹配正则 `https://tapd[^/]*/.*?/(\d{10,})` 或末尾为纯数字段），
43
+ 自动提取末尾数字段作为 STORY_ID，等同于 `--story` 被隐式触发：
44
+
45
+ ```
46
+ /modus:plan https://tapd.woa.com/tapd_fe/20426489/story/detail/1020426489134444072
47
+ → 自动提取 STORY_ID=1020426489134444072（无需显式 --story）
48
+
49
+ /modus:plan --quick https://tapd.woa.com/.../1020426489134444072 新增批量审核
50
+ → QUICK_MODE=true，STORY_ID=1020426489134444072
51
+ ```
52
+
53
+ > 自动检测仅对 TAPD URL 格式生效；普通文字 prompt 不受影响。
54
+
55
+ ```
37
56
  --resume X → RESUME_NAME=X（断点续跑）
38
57
  --complexity X → FORCED_COMPLEXITY=X
39
58
  ```
@@ -49,7 +68,7 @@ disable: false
49
68
 
50
69
  检测到 --design？
51
70
  是 → 执行 Step 0→Step 1→Step 2→Step 3→Step 4→Step 5→Step 6→Design Mode Step 7（生成 design.md + tasks.md 后暂停）
52
- 否 → 执行标准流程（Step 0 → Step 9）
71
+ 否 → 执行标准流程（Step 0 → Step 11）
53
72
  ```
54
73
 
55
74
  ---
@@ -324,16 +343,23 @@ done | shasum -a 1 | awk '{print $1}'
324
343
  ```
325
344
  情形 A：来自 /modus:auto（context_bundle 含 story_id）
326
345
  产出路径：modus/artifacts/{story_id}/code/plan.md
327
-
328
- 情形 B：用户直接运行 /modus:plan（无 story_id）
346
+
347
+ 情形 B：用户直接运行 /modus:plan --story <tapd-url>（从 TAPD URL 中解析 story_id）
348
+ story_id：从 URL 末尾路径段提取数字 ID（如 https://tapd.woa.com/.../1020426489134444072 → 1020426489134444072）
349
+ 产出路径：modus/artifacts/{story_id}/code/plan.md
350
+ 状态文件：modus/artifacts/{story_id}/code/.modus-state.yaml
351
+
352
+ 情形 C：用户直接运行 /modus:plan（无 story_id，无 --story）
329
353
  产出路径：modus/plans/{name}/plan.md
354
+ 状态文件：modus/plans/{name}/.modus-state.yaml
330
355
  plan 名称：从用户 prompt 提取关键词，生成 kebab-case（如 add-batch-approve）
331
356
  ```
332
357
 
333
358
  - 如果目录已存在，提示用户确认
334
359
 
335
360
  **写入状态文件：**
336
- 创建 `modus/plans/{name}/.modus-state.yaml`：
361
+ 路径规则与产出路径一致：情形 A/B → `modus/artifacts/{story_id}/code/.modus-state.yaml`；情形 C → `modus/plans/{name}/.modus-state.yaml`。
362
+ 创建对应路径下的 `.modus-state.yaml`：
337
363
  ```yaml
338
364
  mode: plan
339
365
  name: {name}
@@ -389,7 +415,7 @@ created: {ISO8601时间戳}
389
415
 
390
416
  ### Step 7（Design Mode 分支）：多 Artifact 设计文档生成 ⏸️ 【人工审批节点】
391
417
 
392
- > **仅在 DESIGN_MODE=true 时执行此分支，替代标准 Step 8（Build 循环）。**
418
+ > **仅在 DESIGN_MODE=true 时执行此分支，替代标准 Step 9（Build 循环）。**
393
419
  > 参考：speckit.plan 三阶段 + opsx:propose DAG 状态机
394
420
 
395
421
  ---
@@ -614,10 +640,98 @@ MEDIUM（建议）：
614
640
 
615
641
  ---
616
642
 
617
- ### Step 8：Build 确认循环 ⏸️ 【人工审批节点】
643
+ ### Step 8：生成场景化接口调用链（api-chain.md）
644
+
645
+ > **触发条件：** 仅在 story 模式下执行（`STORY_ID` 已设置，即通过 `--story` 或 `/modus:auto` 传入）。
646
+ > 独立模式（`modus/plans/{name}/`）**跳过此步骤**。
647
+
648
+ **目标：** 将本次规划涉及的接口抽取为场景化调用链文档，供测试团队直接进行用例设计。
649
+
650
+ #### 8-1：确定内容来源（按优先级）
651
+
652
+ ```
653
+ 优先级 0（最高，直接扫描代码）：扫描 plan.md 涉及域对应的 *Facade.java 文件
654
+ → 提取所有 @OpenApiPostMapping(apiUrl=..., apiName=...) 注解
655
+ → 提取所有 @OpenApiGetMapping(apiUrl=..., apiName=...) 注解
656
+ → 以 apiUrl 作为接口路径，apiName 作为接口中文名
657
+ → 结合 plan.md「实现 Todos」判断本次需求涉及哪些接口方法，筛选相关项
658
+
659
+ Facade 文件定位规则：
660
+ 1. 优先从 plan.md「影响文件」章节中识别 *Facade.java 路径
661
+ 2. 若无明确路径，则 Glob("**/*Facade.java")，取与本次需求关键词匹配度最高的文件
662
+
663
+ 优先级 1（--design 模式）：读取 modus/artifacts/{story_id}/design/design.md
664
+ → 提取 §3.1 对外暴露接口（接口名/路径/入参/出参）
665
+ → 提取 §3.2 调用下游接口（下游服务/路径/超时）
666
+
667
+ 优先级 2（标准模式，无 design.md）：读取 modus/knowledge_base/domain/{d}/code/apis.md
668
+ → 提取本次 plan.md 涉及域的接口定义
669
+
670
+ 优先级 3（兜底）：扫描 plan.md 的「实现 Todos」接口层任务
671
+ → 提取含接口路径关键词的任务条目（如 POST /api/、GET /api/）
672
+ ```
673
+
674
+ > **优先级 0 说明**：`@OpenApiPostMapping(apiUrl=..., apiName=...)` 注解是接口路径和中文名的唯一真相，比任何文档都准确，无需推断。优先级 1-3 仅在 Facade 文件无法定位时作为降级兜底。
675
+
676
+ #### 8-2：生成 api-chain.md
677
+
678
+ 参照 `modus/template/api-chain.md` 模板，按以下规则生成内容：
679
+
680
+ - **每个业务操作场景对应 1 个 Scenario**（Happy Path）；同一业务操作顺序调用的多个接口，在该 Scenario 的「接口调用链」表格中按调用顺序逐行列出
681
+ - 接口路径（`apiUrl`）和接口中文名（`apiName`）直接来自优先级 0 扫描到的 `@OpenApiPostMapping`/`@OpenApiGetMapping` 注解，禁止自行推断或拼造
682
+ - 示例：「修改合同」= 1 个 Scenario，表格内 3 行（checkContractExist → queryContractDetailV2 → updateContract）
683
+ - **复杂度 ≥ medium 时**，额外生成边界/异常 Scenario（参数超限、权限不足、并发防重）
684
+ - **Given/When/Then** 从 plan.md 的业务背景 + 接口功能描述中提炼
685
+ - **接口调用链表格** 列：步骤 | 接口名称（apiName）| 接口路径（apiUrl）| 关键请求参数 | 预期返回 | 备注
686
+
687
+ **写入路径：** `modus/artifacts/{story_id}/scenarios/api-chain.md`
688
+
689
+ 若目录不存在，自动创建 `scenarios/`。
690
+
691
+ #### 8-3：完成输出
692
+
693
+ ```
694
+ ✅ api-chain.md 已生成：modus/artifacts/{story_id}/scenarios/api-chain.md
695
+ 共 {N} 个 Scenario（Happy Path: {M} | 异常: {K}）
696
+ 来源：{design.md §3 | apis.md | plan.md tasks}
697
+ ```
698
+
699
+ 若无任何可提取的接口信息（如纯重构类任务），输出以下提示并跳过：
700
+
701
+ ```
702
+ ℹ️ 未检测到明确的接口变更，跳过 api-chain.md 生成。
703
+ 如需手动补充，可参考模板：modus/template/api-chain.md
704
+ ```
705
+
706
+ **独立模式（无 STORY_ID）跳过时**，输出以下提示（不再静默跳过）：
707
+
708
+ ```
709
+ ℹ️ 独立模式未生成 api-chain.md（需要 --story 参数才触发）。
710
+ 如需生成调用链文档，请使用：/modus:plan --story {tapd-url} 重新运行。
711
+ 模板参考：modus/template/api-chain.md
712
+ ```
713
+
714
+ ---
715
+
716
+ ### Step 9：Build 确认循环 ⏸️ 【人工审批节点】
618
717
 
619
718
  plan.md 生成后，展示结果并进入确认循环：
620
719
 
720
+ **（Story 模式：STORY_ID 已设置）：**
721
+ ```
722
+ ✅ plan.md 已就绪：modus/artifacts/{story_id}/code/plan.md
723
+ ✅ api-chain.md 已就绪：modus/artifacts/{story_id}/scenarios/api-chain.md
724
+
725
+ ──────────────────────────────────────────
726
+ 你可以：
727
+ [修改] 直接说出修改意见，我会更新 plan.md，更新后再次展示
728
+ [Build] 确认方案，开始按 plan.md 中的 Todos 生成代码
729
+ [归档] 仅保存文档，暂不执行代码生成
730
+
731
+ 等待你的指令。
732
+ ```
733
+
734
+ **（独立模式：无 STORY_ID）：**
621
735
  ```
622
736
  ✅ plan.md 已就绪：modus/plans/{name}/plan.md
623
737
 
@@ -642,6 +756,15 @@ plan.md 生成后，展示结果并进入确认循环：
642
756
  以下是 modus-plan → modus-vibe 的**标准上下文传递协议**：
643
757
 
644
758
  1. 输出 Build 启动提示（让用户感知上下文已传递）：
759
+ - Story 模式（STORY_ID 已设置）：
760
+ ```
761
+ 🚀 开始执行 plan.md 中的 Todos，启动 /modus:vibe...
762
+ 规划文件: modus/artifacts/{story_id}/code/plan.md
763
+ 场景文档: modus/artifacts/{story_id}/scenarios/api-chain.md
764
+ 执行范围: {Todos 列表}
765
+ 传递标记: [FROM_PLAN: modus/artifacts/{story_id}/code/plan.md]
766
+ ```
767
+ - 独立模式（无 STORY_ID）：
645
768
  ```
646
769
  🚀 开始执行 plan.md 中的 Todos，启动 /modus:vibe...
647
770
  规划文件: modus/plans/{name}/plan.md
@@ -671,7 +794,7 @@ plan.md 生成后，展示结果并进入确认循环：
671
794
 
672
795
  ---
673
796
 
674
- ### Step 9：后置 Skill 更新（知识回写，用户确认后执行）
797
+ ### Step 10：后置 Skill 更新（知识回写，用户确认后执行）
675
798
 
676
799
  规划阶段完成后，先扫描 `plan.md` 中可能值得沉淀的新知识，向用户展示并**请求确认**后再写回：
677
800
 
@@ -696,13 +819,13 @@ plan.md 生成后，展示结果并进入确认循环：
696
819
 
697
820
  **`usage_count` 更新时机（plan 模式）：**
698
821
 
699
- 用户在 Build 确认循环中回复「Build/开始/执行」后（即 Step 8 Build 触发时），对本次 plan 涉及的每个业务域执行 `usage_count += 1`，并同步更新对应 Skill 的 frontmatter。此操作在 Step 8 Build 触发内执行，不依赖后续 vibe session 的完成。
822
+ 用户在 Build 确认循环中回复「Build/开始/执行」后（即 Step 9 Build 触发时），对本次 plan 涉及的每个业务域执行 `usage_count += 1`，并同步更新对应 Skill 的 frontmatter。此操作在 Step 9 Build 触发内执行，不依赖后续 vibe session 的完成。
700
823
 
701
824
  > **设计理由（Karpathy Surgical Changes）：** 用户请求的是"生成规划文档"，不是"更新 Skill 文件"。自动写回会在用户不知情的情况下修改多个知识文件，违反"Touch only what you must"。用户确认机制既保留了知识闭环能力，又把文件修改的控制权还给用户。
702
825
 
703
826
  ---
704
827
 
705
- ### Step 10：多平台 Skill 同步（后置）
828
+ ### Step 11：多平台 Skill 同步（后置）
706
829
 
707
830
  知识回写完成后，对所有本次**更新或新建**的业务 Skill 执行多平台同步。
708
831
 
@@ -967,5 +1090,5 @@ for each Phase（按顺序）:
967
1090
  ────────────────────────────────────────────────
968
1091
  ```
969
1092
 
970
- **后置知识回写（与标准 plan Step 9 相同逻辑）：**
1093
+ **后置知识回写（与标准 plan Step 10 相同逻辑）：**
971
1094
  扫描编码过程中新发现的 pitfall/decision，询问用户是否写回 Skill（不强制）。
package/templates/skills/modus-spec/SKILL.md CHANGED
@@ -37,6 +37,35 @@ supported_platforms:
37
37
 
38
38
  ---
39
39
 
40
+ ## 参数解析（优先执行，Step 0 之前）
41
+
42
+ **首先**检测用户输入中的参数标志：
43
+
44
+ ```
45
+ --story X → 提取 X 末尾的纯数字段作为 STORY_ID（若 X 已是纯数字则直接使用）
46
+ 示例：https://tapd.woa.com/.../1020426489134444072 → STORY_ID=1020426489134444072
47
+ --lite → LITE_MODE=true（精简版，见模式对比表）
48
+ --quick → QUICK_MODE=true（跳过域确认）
49
+ --no-archive → 生成文档后不触发归档确认
50
+ ```
51
+
52
+ **TAPD URL 自动检测（无需 --story flag）：**
53
+
54
+ 若用户 prompt 中**直接包含 TAPD URL**（匹配正则 `https://tapd[^/]*/.*?/(\d{10,})` 或末尾为纯数字段），
55
+ 自动提取末尾数字段作为 STORY_ID：
56
+
57
+ ```
58
+ /modus:spec https://tapd.woa.com/tapd_fe/20426489/story/detail/1020426489134444072
59
+ → 自动提取 STORY_ID=1020426489134444072
60
+
61
+ /modus:spec --lite https://tapd.woa.com/.../1020426489134444072 修改审核状态枚举
62
+ → LITE_MODE=true，STORY_ID=1020426489134444072
63
+ ```
64
+
65
+ > STORY_ID 一旦设置，Step 8（api-chain.md 生成）自动触发，产出写入 `modus/artifacts/{story_id}/scenarios/`。
66
+
67
+ ---
68
+
40
69
  ## 执行流程
41
70
 
42
71
  ### Step 0：读取项目宪法 + 断点续跑检查
@@ -211,7 +240,64 @@ supported_platforms:
211
240
 
212
241
  ---
213
242
 
214
- ### Step 8：归档确认 ⏸️ 【人工审批节点】
243
+ ### Step 8：生成场景化接口调用链（api-chain.md）
244
+
245
+ > **触发条件：** 仅在 story 模式下执行（`STORY_ID` 已设置）。
246
+ > 独立模式（`modus/changes/{name}/`）**跳过此步骤**。
247
+
248
+ **目标：** 将本次规格涉及的 Gherkin 场景转换为面向测试团队的接口调用链文档。
249
+
250
+ #### 8-1：确定内容来源（按优先级）
251
+
252
+ ```
253
+ 优先级 1：读取 modus/artifacts/{story_id}/code/spec/*.feature.md
254
+ → 提取每个 Scenario 的 When 子句（接口调用动作）
255
+ → 将 Gherkin 步骤转换为调用链表格（When → 接口路径 + 参数）
256
+
257
+ 优先级 2：读取 modus/artifacts/{story_id}/design/design.md（若存在）
258
+ → 用 §3.1/§3.2 接口合同补充完整 HTTP 路径、请求参数、响应格式
259
+
260
+ 优先级 3：读取 modus/artifacts/{story_id}/pid/prd.md（若存在）
261
+ → 从验收标准 AC 的 Given/When/Then 中补充业务背景
262
+ ```
263
+
264
+ #### 8-2：生成或追加 api-chain.md
265
+
266
+ **检测文件是否已存在：**
267
+
268
+ - **不存在**（首次，如只跑了 spec 未跑 plan）：参照 `modus/template/api-chain.md` 模板完整生成
269
+ - **已存在**（先跑了 plan 已生成）：追加新 Scenario 块，**不覆盖已有内容**，在文件末尾追加：
270
+
271
+ ```markdown
272
+ ---
273
+ <!-- 以下 Scenario 由 /modus:spec 生成，追加于 {YYYY-MM-DD} -->
274
+
275
+ ## Scenario N: {来自 spec 的场景标题}
276
+ ...
277
+ ```
278
+
279
+ **写入路径：** `modus/artifacts/{story_id}/scenarios/api-chain.md`
280
+
281
+ 若目录不存在，自动创建 `scenarios/`。
282
+
283
+ #### 8-3：完成输出
284
+
285
+ ```
286
+ ✅ api-chain.md 已生成/更新：modus/artifacts/{story_id}/scenarios/api-chain.md
287
+ 共 {N} 个 Scenario（来自 spec: {M} | 已有 plan 场景: {K}）
288
+ 来源：{spec/*.feature.md | design.md §3 | prd.md AC}
289
+ ```
290
+
291
+ 若无任何 Gherkin When 子句含接口调用动作，输出以下提示并跳过：
292
+
293
+ ```
294
+ ℹ️ 未检测到明确的接口调用场景，跳过 api-chain.md 生成。
295
+ 如需手动补充，可参考模板：modus/template/api-chain.md
296
+ ```
297
+
298
+ ---
299
+
300
+ ### Step 9：归档确认 ⏸️ 【人工审批节点】
215
301
 
216
302
  文档生成后，展示结果并等待用户决定：
217
303
 
@@ -243,7 +329,7 @@ supported_platforms:
243
329
 
244
330
  ---
245
331
 
246
- ### Step 9：后置 Skill 知识写回（归档后执行）
332
+ ### Step 10：后置 Skill 知识写回（归档后执行）
247
333
 
248
334
  从 proposal.md + design-brief.md 中提取可沉淀的知识，**请求用户确认后**写回 Skill（调用 `modus-skill-creator` 模式 C）：
249
335
 
@@ -256,7 +342,7 @@ supported_platforms:
256
342
 
257
343
  ---
258
344
 
259
- ### Step 10：多平台 Skill 同步（后置）
345
+ ### Step 11：多平台 Skill 同步（后置）
260
346
 
261
347
  与 `modus-plan` Step 10 相同逻辑，对本次更新/新建的业务 Skill 执行多平台同步（根据 `modus/config.yaml` 的 `platforms` 字段）。
262
348
 
package/templates/template/api-chain.md ADDED
@@ -0,0 +1,69 @@
1
+ # API 调用链 — {业务场景名}
2
+
3
+ > **来源**：{plan.md | spec/{feature}.feature.md}
4
+ > **关联域**：{domain}
5
+ > **Story**：{story_id}
6
+ > **生成时间**：{YYYY-MM-DD}
7
+ > **说明**：本文件由 `/modus:plan` 或 `/modus:spec` 自动生成，供测试团队进行场景化用例设计。
8
+ >
9
+ > - Happy Path 场景：验证主业务流程正常执行（1 个业务操作 = 1 个 Scenario，串联所有涉及的接口）
10
+ > - 边界/异常场景：验证参数校验、权限、并发等防御性逻辑
11
+ > - 每个 Scenario 包含：业务描述（Given/When/Then）+ 接口调用链（步骤表格）+ 测试数据
12
+ > - **接口路径和名称来源**：`@OpenApiPostMapping(apiUrl=..., apiName=...)` 或 `@OpenApiGetMapping(...)` 注解，禁止推断
13
+
14
+ ---
15
+
16
+ ## Scenario 1: {业务场景标题}（Happy Path）
17
+
18
+ **Given** {前置条件，如：合同已存在，tenantId=xxx，contractId=yyy，当前状态为草稿}
19
+ **When** {触发动作，如：用户发起修改合同操作}
20
+ **Then** {预期结果，如：返回成功，合同信息更新}
21
+
22
+ ### 接口调用链
23
+ > 接口路径来源：`@OpenApiPostMapping(apiUrl=...)` 注解
24
+
25
+ | 步骤 | 接口名称 | 接口路径 | 关键请求参数 | 预期返回 | 备注 |
26
+ |------|---------|---------|------------|---------|------|
27
+ | 1 | `{apiName，如：检查合同是否存在}` | `POST {apiUrl，如：/musician/companySaas/checkContractExist}` | `{"contractId":"yyy"}` | `{"data":true}` | {说明，如：前置存在性校验，false 则终止} |
28
+ | 2 | `{apiName，如：查询合同详情V2}` | `POST {apiUrl，如：/musician/companySaas/queryContractDetailV2}` | `{"contractId":"yyy"}` | `{"data":{...}}` | {说明，如：获取当前合同快照} |
29
+ | 3 | `{apiName，如：更新合同}` | `POST {apiUrl，如：/musician/companySaas/updateContract}` | `{"contractId":"yyy","...":"..."}` | `{"data":null}` | {说明，如：执行更新} |
30
+
31
+ ### 测试数据
32
+ - **前置数据**：{如：tenantId=1001, contractId=3001，status=DRAFT}
33
+ - **清理数据**：{如：将 contractId=3001 恢复为原始数据}
34
+
35
+ ---
36
+
37
+ ## Scenario 2: {业务场景标题}（边界/异常）
38
+
39
+ **Given** {前置条件，如：contractId=9999 不存在}
40
+ **When** {触发动作}
41
+ **Then** {预期结果，如：第 1 步返回 false，流程中止，不调用后续接口}
42
+
43
+ ### 接口调用链
44
+
45
+ | 步骤 | 接口名称 | 接口路径 | 关键请求参数 | 预期返回 | 备注 |
46
+ |------|---------|---------|------------|---------|------|
47
+ | 1 | `{apiName}` | `POST {apiUrl}` | `{...超限或非法参数...}` | `{"code":"ERROR_XXX"}` | {说明，如：参数校验失败，流程终止} |
48
+
49
+ ### 测试数据
50
+ - **前置数据**：{...}
51
+ - **清理数据**：{无需清理}
52
+
53
+ ---
54
+
55
+ ## Scenario 3: {业务场景标题}（权限/并发）
56
+
57
+ **Given** {前置条件，如：无操作权限的用户 / 并发提交同一任务}
58
+ **When** {触发动作}
59
+ **Then** {预期结果，如：返回权限错误 / 分布式锁触发，返回冲突错误}
60
+
61
+ ### 接口调用链
62
+
63
+ | 步骤 | 接口名称 | 接口路径 | 关键请求参数 | 预期返回 | 备注 |
64
+ |------|---------|---------|------------|---------|------|
65
+ | 1 | `{apiName}` | `POST {apiUrl}` | `{...}` | `{"code":"NO_PERMISSION"}` | {说明，如：权限校验} |
66
+
67
+ ### 测试数据
68
+ - **前置数据**：{...}
69
+ - **清理数据**：{...}