@modus-ai/modus 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modus-ai/modus",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Modus — Business-grounded AI coding accelerator for CodeBuddy IDE",
   "keywords": [
     "ai",

package/templates/commands/harness.md

@@ -105,6 +105,8 @@ modus/artifacts/{story_id}/
 │   ├── cr-report.md             ← SubAgent 06 (modus-reviewer)，含 HANDOFF.issues
 │   ├── deploy-status.md         ← SubAgent 07 (modus-deployer)
 │   └── .harness-state.yaml      ← 状态机
+├── scenarios/
+│   └── api-chain.md             ← 场景化接口调用链（Step 1 创建目录，harness 完整流程后内容最丰富）
 └── archive/                     ← 上线后人工触发，输出 summary.md 与 key-scenarios/
 ```
 

package/templates/commands/plan.md

@@ -86,10 +86,12 @@
 ```
 modus/artifacts/{story_id}/
 ├── design/design.md       — --design 模式产出
-└── code/
-    ├── plan.md            — 标准模式产出
-    ├── .modus-state.yaml  — 状态机，支持断点续跑
-    └── spec/              — （如后续接 /modus:spec）
+├── code/
+│   ├── plan.md            — 标准模式产出
+│   ├── .modus-state.yaml  — 状态机，支持断点续跑
+│   └── spec/              — （如后续接 /modus:spec）
+└── scenarios/
+    └── api-chain.md       — 场景化接口调用链（Step 8 生成，供测试团队消费）
 ```
 
 **独立模式（不含 --story）：**

package/templates/commands/spec.md

@@ -68,11 +68,13 @@ Feature: 批量审批订单
 ```
 modus/artifacts/{story_id}/
 ├── design/design.md
-└── code/
-    ├── spec/                       — delta specs（ADDED/MODIFIED/REMOVED）
-    ├── spec-proposal.md            — 意图与范围
-    ├── tasks.md                    — 实现清单（追踪到 Scenario）
-    └── testcases.md                — QA 用例（--testcase 时生成）
+├── code/
+│   ├── spec/                       — delta specs（ADDED/MODIFIED/REMOVED）
+│   ├── spec-proposal.md            — 意图与范围
+│   ├── tasks.md                    — 实现清单（追踪到 Scenario）
+│   └── testcases.md                — QA 用例（--testcase 时生成）
+└── scenarios/
+    └── api-chain.md                — 场景化接口调用链（Step 8 生成，供测试团队消费）
 ```
 
 **独立模式（不含 --story）：**

package/templates/paths-v4.md

@@ -73,6 +73,8 @@ last_updated: "2026-05-22"
             │   ├── vibe-log.md          # 编码日志
             │   ├── cr-report.md         # CR 报告
             │   └── .harness-state.yaml  # Harness 状态机
+            ├── scenarios/               # 场景化接口调用链（plan/spec 生成）
+            │   └── api-chain.md         # 业务场景描述 + 接口调用链（供测试团队消费）
             └── archive/                 # 上线验收后人工触发归档
                 ├── summary.md           # 精简版人阅读摘要
                 └── key-scenarios/       # 关键场景快照（供后续迭代检索）

package/templates/skills/modus-harness/SKILL.md

@@ -144,6 +144,7 @@ B. 强制继续（无业务上下文，风险较高）
 **解析 Story ID + 初始化状态追踪：**
 - 从 TAPD URL 提取 Story ID（格式：`tapd.cn/{project}/stories/view/{id}`）
 - 创建工作目录：`modus/artifacts/{story_id}/code/`
+- 创建场景目录：`modus/artifacts/{story_id}/scenarios/`
 
 **`.harness-state.yaml` 断点续跑机制（优先级高于 HANDOFF 块探测）：**
 

package/templates/skills/modus-plan/SKILL.md

@@ -49,7 +49,7 @@ disable: false
 
 检测到 --design？
   是 → 执行 Step 0→Step 1→Step 2→Step 3→Step 4→Step 5→Step 6→Design Mode Step 7（生成 design.md + tasks.md 后暂停）
-  否 → 执行标准流程（Step 0 → Step 9）
+  否 → 执行标准流程（Step 0 → Step 11）
 ```
 
 ---
@@ -389,7 +389,7 @@ created: {ISO8601时间戳}
 
 ### Step 7（Design Mode 分支）：多 Artifact 设计文档生成 ⏸️ 【人工审批节点】
 
-> **仅在 DESIGN_MODE=true 时执行此分支，替代标准 Step 8（Build 循环）。**
+> **仅在 DESIGN_MODE=true 时执行此分支，替代标准 Step 9（Build 循环）。**
 > 参考：speckit.plan 三阶段 + opsx:propose DAG 状态机
 
 ---
@@ -614,7 +614,58 @@ MEDIUM（建议）：
 
 ---
 
-### Step 8：Build 确认循环 ⏸️ 【人工审批节点】
+### Step 8：生成场景化接口调用链（api-chain.md）
+
+> **触发条件：** 仅在 story 模式下执行（`STORY_ID` 已设置，即通过 `--story` 或 `/modus:auto` 传入）。
+> 独立模式（`modus/plans/{name}/`）**跳过此步骤**。
+
+**目标：** 将本次规划涉及的接口抽取为场景化调用链文档，供测试团队直接进行用例设计。
+
+#### 8-1：确定内容来源（按优先级）
+
+```
+优先级 1（--design 模式）：读取 modus/artifacts/{story_id}/design/design.md
+  → 提取 §3.1 对外暴露接口（接口名/路径/入参/出参）
+  → 提取 §3.2 调用下游接口（下游服务/路径/超时）
+
+优先级 2（标准模式，无 design.md）：读取 modus/knowledge_base/domain/{d}/code/apis.md
+  → 提取本次 plan.md 涉及域的接口定义
+
+优先级 3（兜底）：扫描 plan.md 的「实现 Todos」接口层任务
+  → 提取含接口路径关键词的任务条目（如 POST /api/、GET /api/）
+```
+
+#### 8-2：生成 api-chain.md
+
+参照 `modus/template/api-chain.md` 模板，按以下规则生成内容：
+
+- **每个对外接口对应 1 个 Scenario**（Happy Path）
+- **复杂度 ≥ medium 时**，额外生成边界/异常 Scenario（参数超限、权限不足、并发防重）
+- **Given/When/Then** 从 plan.md 的业务背景 + 接口功能描述中提炼
+- **接口调用链表格** 中填写完整 HTTP 路径、关键请求参数、预期状态码 + 错误码
+
+**写入路径：** `modus/artifacts/{story_id}/scenarios/api-chain.md`
+
+若目录不存在，自动创建 `scenarios/`。
+
+#### 8-3：完成输出
+
+```
+✅ api-chain.md 已生成：modus/artifacts/{story_id}/scenarios/api-chain.md
+   共 {N} 个 Scenario（Happy Path: {M} | 异常: {K}）
+   来源：{design.md §3 | apis.md | plan.md tasks}
+```
+
+若无任何可提取的接口信息（如纯重构类任务），输出以下提示并跳过：
+
+```
+ℹ️ 未检测到明确的接口变更，跳过 api-chain.md 生成。
+   如需手动补充，可参考模板：modus/template/api-chain.md
+```
+
+---
+
+### Step 9：Build 确认循环 ⏸️ 【人工审批节点】
 
 plan.md 生成后，展示结果并进入确认循环：
 
@@ -671,7 +722,7 @@ plan.md 生成后，展示结果并进入确认循环：
 
 ---
 
-### Step 9：后置 Skill 更新（知识回写，用户确认后执行）
+### Step 10：后置 Skill 更新（知识回写，用户确认后执行）
 
 规划阶段完成后，先扫描 `plan.md` 中可能值得沉淀的新知识，向用户展示并**请求确认**后再写回：
 
@@ -696,13 +747,13 @@ plan.md 生成后，展示结果并进入确认循环：
 
 **`usage_count` 更新时机（plan 模式）：**
 
-用户在 Build 确认循环中回复「Build/开始/执行」后（即 Step 8 Build 触发时），对本次 plan 涉及的每个业务域执行 `usage_count += 1`，并同步更新对应 Skill 的 frontmatter。此操作在 Step 8 Build 触发内执行，不依赖后续 vibe session 的完成。
+用户在 Build 确认循环中回复「Build/开始/执行」后（即 Step 9 Build 触发时），对本次 plan 涉及的每个业务域执行 `usage_count += 1`，并同步更新对应 Skill 的 frontmatter。此操作在 Step 9 Build 触发内执行，不依赖后续 vibe session 的完成。
 
 > **设计理由（Karpathy Surgical Changes）：** 用户请求的是"生成规划文档"，不是"更新 Skill 文件"。自动写回会在用户不知情的情况下修改多个知识文件，违反"Touch only what you must"。用户确认机制既保留了知识闭环能力，又把文件修改的控制权还给用户。
 
 ---
 
-### Step 10：多平台 Skill 同步（后置）
+### Step 11：多平台 Skill 同步（后置）
 
 知识回写完成后，对所有本次**更新或新建**的业务 Skill 执行多平台同步。
 
@@ -967,5 +1018,5 @@ for each Phase（按顺序）:
 ────────────────────────────────────────────────
 ```
 
-**后置知识回写（与标准 plan Step 9 相同逻辑）：**
+**后置知识回写（与标准 plan Step 10 相同逻辑）：**
 扫描编码过程中新发现的 pitfall/decision，询问用户是否写回 Skill（不强制）。

package/templates/skills/modus-spec/SKILL.md

@@ -211,7 +211,64 @@ supported_platforms:
 
 ---
 
-### Step 8：归档确认 ⏸️ 【人工审批节点】
+### Step 8：生成场景化接口调用链（api-chain.md）
+
+> **触发条件：** 仅在 story 模式下执行（`STORY_ID` 已设置）。
+> 独立模式（`modus/changes/{name}/`）**跳过此步骤**。
+
+**目标：** 将本次规格涉及的 Gherkin 场景转换为面向测试团队的接口调用链文档。
+
+#### 8-1：确定内容来源（按优先级）
+
+```
+优先级 1：读取 modus/artifacts/{story_id}/code/spec/*.feature.md
+  → 提取每个 Scenario 的 When 子句（接口调用动作）
+  → 将 Gherkin 步骤转换为调用链表格（When → 接口路径 + 参数）
+
+优先级 2：读取 modus/artifacts/{story_id}/design/design.md（若存在）
+  → 用 §3.1/§3.2 接口合同补充完整 HTTP 路径、请求参数、响应格式
+
+优先级 3：读取 modus/artifacts/{story_id}/pid/prd.md（若存在）
+  → 从验收标准 AC 的 Given/When/Then 中补充业务背景
+```
+
+#### 8-2：生成或追加 api-chain.md
+
+**检测文件是否已存在：**
+
+- **不存在**（首次，如只跑了 spec 未跑 plan）：参照 `modus/template/api-chain.md` 模板完整生成
+- **已存在**（先跑了 plan 已生成）：追加新 Scenario 块，**不覆盖已有内容**，在文件末尾追加：
+
+```markdown
+---
+<!-- 以下 Scenario 由 /modus:spec 生成，追加于 {YYYY-MM-DD} -->
+
+## Scenario N: {来自 spec 的场景标题}
+...
+```
+
+**写入路径：** `modus/artifacts/{story_id}/scenarios/api-chain.md`
+
+若目录不存在，自动创建 `scenarios/`。
+
+#### 8-3：完成输出
+
+```
+✅ api-chain.md 已生成/更新：modus/artifacts/{story_id}/scenarios/api-chain.md
+   共 {N} 个 Scenario（来自 spec: {M} | 已有 plan 场景: {K}）
+   来源：{spec/*.feature.md | design.md §3 | prd.md AC}
+```
+
+若无任何 Gherkin When 子句含接口调用动作，输出以下提示并跳过：
+
+```
+ℹ️ 未检测到明确的接口调用场景，跳过 api-chain.md 生成。
+   如需手动补充，可参考模板：modus/template/api-chain.md
+```
+
+---
+
+### Step 9：归档确认 ⏸️ 【人工审批节点】
 
 文档生成后，展示结果并等待用户决定：
 
@@ -243,7 +300,7 @@ supported_platforms:
 
 ---
 
-### Step 9：后置 Skill 知识写回（归档后执行）
+### Step 10：后置 Skill 知识写回（归档后执行）
 
 从 proposal.md + design-brief.md 中提取可沉淀的知识，**请求用户确认后**写回 Skill（调用 `modus-skill-creator` 模式 C）：
 
@@ -256,7 +313,7 @@ supported_platforms:
 
 ---
 
-### Step 10：多平台 Skill 同步（后置）
+### Step 11：多平台 Skill 同步（后置）
 
 与 `modus-plan` Step 10 相同逻辑，对本次更新/新建的业务 Skill 执行多平台同步（根据 `modus/config.yaml` 的 `platforms` 字段）。
 

package/templates/template/api-chain.md

@@ -0,0 +1,69 @@
+# API 调用链 — {业务场景名}
+
+> **来源**：{plan.md | spec/{feature}.feature.md}
+> **关联域**：{domain}
+> **Story**：{story_id}
+> **生成时间**：{YYYY-MM-DD}
+> **说明**：本文件由 `/modus:plan` 或 `/modus:spec` 自动生成，供测试团队进行场景化用例设计。
+>
+> - Happy Path 场景：验证主业务流程正常执行
+> - 边界/异常场景：验证参数校验、权限、并发等防御性逻辑
+> - 每个 Scenario 包含：业务描述（Given/When/Then）+ 接口调用链（步骤表格）+ 测试数据
+
+---
+
+## Scenario 1: {场景标题}（Happy Path）
+
+**Given** {前置条件，如：用户已登录，tenantId=xxx，待处理记录 N 条}
+**When** {触发动作，如：调用 POST /api/v1/{resource}/xxx 接口}
+**Then** {预期结果，如：返回 200，记录状态更新为 approved，审批日志写入}
+
+### 接口调用链
+
+| 步骤 | 接口 | 请求参数 | 预期返回 | 备注 |
+|------|------|---------|---------|------|
+| 1 | `POST /api/v1/...` | `{"key": "value"}` | `200 {"code":0}` | 主入口 |
+| 2 | `GET /api/v1/.../status` | `id={id}` | `200 {"status":"xxx"}` | 验证状态流转 |
+
+### 测试数据
+
+- **前置数据**：{如：tenantId=1001, userId=2001, recordId=3001}
+- **清理数据**：{如：删除 recordId=3001 的记录}
+
+---
+
+## Scenario 2: {场景标题}（边界/异常）
+
+**Given** {前置条件，如：请求参数超过上限}
+**When** {触发动作}
+**Then** {预期结果，如：返回 400，错误码 ERROR_BATCH_LIMIT_EXCEEDED}
+
+### 接口调用链
+
+| 步骤 | 接口 | 请求参数 | 预期返回 | 备注 |
+|------|------|---------|---------|------|
+| 1 | `POST /api/v1/...` | `{"ids": [...超限数量...]}` | `400 {"code":"ERROR_XXX"}` | 参数校验 |
+
+### 测试数据
+
+- **前置数据**：{...}
+- **清理数据**：{无需清理}
+
+---
+
+## Scenario 3: {场景标题}（权限/并发）
+
+**Given** {前置条件，如：无操作权限的用户 / 并发提交同一任务}
+**When** {触发动作}
+**Then** {预期结果，如：返回 403 / 分布式锁触发，返回 409}
+
+### 接口调用链
+
+| 步骤 | 接口 | 请求参数 | 预期返回 | 备注 |
+|------|------|---------|---------|------|
+| 1 | `POST /api/v1/...` | `{...}` | `403 {"code":"NO_PERMISSION"}` | 权限校验 |
+
+### 测试数据
+
+- **前置数据**：{...}
+- **清理数据**：{...}