@modus-ai/modus 0.2.11 → 0.3.1

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）
 ```
 
 ---
@@ -78,11 +78,11 @@ disable: false
 
 ### Step 1：Level 1 加载——读知识目录（~200 tokens）
 
-读取 `modus/knowledge-catalog.md`，了解当前可用 Skill 及其状态。
+读取 `modus/knowledge_base/map.md`，了解当前可用 Skill 及其状态。
 
 若不存在，输出降级提示：
 ```
-⚠️  未找到 modus/knowledge-catalog.md，建议先运行 /modus:init 初始化知识库。
+⚠️  未找到 modus/knowledge_base/map.md，建议先运行 /modus:init 初始化知识库。
     将使用平台规则文件和源码扫描作为替代知识来源继续执行。
 ```
 
@@ -165,11 +165,11 @@ disable: false
 
 #### 4-1：读取 Skill frontmatter（轻量操作，仅读前 20 行）
 
-读取 `modus/knowledge/biz-{domain}/SKILL.md` 的 YAML frontmatter，提取：
+读取 `modus/knowledge_base/domain/{domain}/code/SKILL.md` 的 YAML frontmatter，提取：
 - `last_hash`：上次记录的 key_files 内容摘要
 - `key_files`：关键源文件列表
 
-若 Skill 不存在（包括 modus/knowledge/ 目录下不存在），跳到 4-4（新建）。
+若 Skill 不存在（包括 modus/knowledge_base/ 目录下不存在），跳到 4-4（新建）。
 
 > **注意**：`.codebuddy/skills/modus-biz-{domain}/SKILL.md` 自 v3.2 起已降级为引用桩，不含实际内容，请勿从此路径读取。
 
@@ -323,7 +323,7 @@ done | shasum -a 1 | awk '{print $1}'
 
 ```
 情形 A：来自 /modus:auto（context_bundle 含 story_id）
-  产出路径：modus/stories/{story-id}/plan.md
+  产出路径：modus/artifacts/{story_id}/code/plan.md
   
 情形 B：用户直接运行 /modus:plan（无 story_id）
   产出路径：modus/plans/{name}/plan.md
@@ -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 执行多平台同步。
 
@@ -710,7 +761,7 @@ plan.md 生成后，展示结果并进入确认循环：
 
 1. 读取 `modus/config.yaml` 的 `platforms` 字段
 2. 对受影响的每个业务域（Step 4 前置更新 / 新建的域），按以下规则同步：
-   - **CodeBuddy** → 同步更新 `.codebuddy/skills/modus-biz-{domain}/SKILL.md` 引用桩的摘要行（权威源已在 `modus/knowledge/biz-{domain}/SKILL.md` 中更新）
+   - **CodeBuddy** → 同步更新 `.codebuddy/skills/modus-biz-{domain}/SKILL.md` 引用桩的摘要行（权威源已在 `modus/knowledge_base/domain/{domain}/code/SKILL.md` 中更新）
    - **Claude** → 写入 `.claude/agents/modus-biz-{domain}.md`（覆盖旧版本）
    - **Cursor** → 写入 `.cursor/rules/modus-biz-{domain}.mdc`（带 frontmatter，覆盖旧版本）
    - **Copilot** → 在 `.github/copilot-instructions.md` 中替换对应域的标记段落
@@ -967,5 +1018,5 @@ for each Phase（按顺序）:
 ────────────────────────────────────────────────
 ```
 
-**后置知识回写（与标准 plan Step 9 相同逻辑）：**
+**后置知识回写（与标准 plan Step 10 相同逻辑）：**
 扫描编码过程中新发现的 pitfall/decision，询问用户是否写回 Skill（不强制）。

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

@@ -153,7 +153,7 @@ bizSkill:
   outputPath: "{outputDir}/modus-biz-{domain}.{fileExtension}"
   wrapper: |
     # {domain} Business Domain Rules
-    <!-- Source: modus/knowledge/biz-{domain}/SKILL.md -->
+    <!-- Source: modus/knowledge_base/domain/{domain}/code/SKILL.md -->
     {content}
 constitutionTemplate: |
   # Modus Project Rules — {label}

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

@@ -58,7 +58,7 @@ supported_platforms:
 
 ### Step 1：Level 1 加载——读知识目录（~200 tokens）
 
-读取 `modus/knowledge-catalog.md`，了解当前可用 Skill 及其状态。
+读取 `modus/knowledge_base/map.md`，了解当前可用 Skill 及其状态。
 
 若不存在，输出降级提示并继续（使用平台规则文件扫描替代）。
 
@@ -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/skills/modus-vibe/SKILL.md

@@ -43,7 +43,7 @@ disable: false
 --enhance X  → ENHANCE_DOMAIN=X（Step 3 前先增量更新该域 Skill）
 --file X     → FOCUS_FILE=X（Step 3 从该文件推断域，而非 prompt 匹配）
 --no-design  → SKIP_DESIGN=true（跳过 Step 6 Design Brief）
---story X    → STORY_ID=X（Step 9 日志写入 modus/stories/{X}/vibe-log.md）
+--story X    → STORY_ID=X（Step 9 日志写入 modus/artifacts/{X}/code/vibe-log.md）
 --dry-run    → DRY_RUN=true（Step 7 只输出设计，不生成代码）
 --watch      → WATCH_MODE=true（Step 10 启用文件监听，实验性）
 --codex      → CODEX_MODE=true（禁用交互提问，全批量推断输出）
@@ -75,7 +75,7 @@ constitution:
 
 ### Step 1：Level 1 加载——读知识目录（~200 tokens）
 
-读取 `modus/knowledge-catalog.md`（全景目录索引）：
+读取 `modus/knowledge_base/map.md`（全景目录索引）：
 - 了解当前项目有哪些可用的 Skill
 - 识别各 Skill 的 maturity 状态、最近引用时间
 - 为 Step 2 的智能分析做准备
@@ -83,7 +83,7 @@ constitution:
 **如果 `knowledge-catalog.md` 不存在：**
 
 ```
-⚠️ 未找到知识目录（modus/knowledge-catalog.md）
+⚠️ 未找到知识目录（modus/knowledge_base/map.md）
 
 建议先运行 /modus:init 初始化知识库，可以让 AI 更准确地理解项目。
 
@@ -233,10 +233,10 @@ Codex 模式：所有同步静默执行，不输出状态行（减少干扰）
 
 **路径规则（v3.1 Single Source of Truth）：**
 ```
-modus/knowledge/biz-{domain}/SKILL.md
+modus/knowledge_base/domain/{domain}/code/SKILL.md
 ```
 
-例如：`modus/knowledge/biz-order/SKILL.md`、`modus/knowledge/biz-payment/SKILL.md`
+例如：`modus/knowledge_base/biz-order/SKILL.md`、`modus/knowledge_base/biz-payment/SKILL.md`
 
 > **注意**：`.codebuddy/skills/modus-biz-{domain}/SKILL.md` 为旧路径引用桩，已废弃，请勿使用。
 
@@ -285,7 +285,7 @@ modus/knowledge/biz-{domain}/SKILL.md
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ## 实现蓝图
-Data:    {Mapper 类/方法}（路径: modus/knowledge/biz-{domain}/SKILL.md → 关键文件索引）
+Data:    {Mapper 类/方法}（路径: modus/knowledge_base/domain/{domain}/code/SKILL.md → 关键文件索引）
 Service: {Manager/Service 类/方法，标注 @Transactional 位置}
 API:     {Facade/Controller 类/方法}
 
@@ -383,7 +383,7 @@ Codex 模式下，每个文件生成前输出分隔符：`=== 生成文件: {pat
 #### 执行方式
 
 ```
-有新知识 → 写入 modus/knowledge/biz-{domain}/SKILL.md（v3.1 路径）
+有新知识 → 写入 modus/knowledge_base/domain/{domain}/code/SKILL.md（v3.1 路径）
           → 写入完成后输出单行提示：
             [已更新 {domain} 域知识: 新增 [pitfall] {摘要} / 更正 [model] {字段名}]
 
@@ -402,7 +402,7 @@ Codex 模式下，每个文件生成前输出分隔符：`=== 生成文件: {pat
 
 编码完成后，将本次会话**追加**（append-only，禁止覆盖原有内容）到日志文件：
 
-- 若 STORY_ID 已设置：写入 `modus/stories/{STORY_ID}/vibe-log.md`
+- 若 STORY_ID 已设置：写入 `modus/artifacts/{STORY_ID}/code/vibe-log.md`
 - 否则：写入 `modus/sessions/vibe-log.md`
 
 ```markdown
@@ -514,7 +514,7 @@ Codex 平台与 Cursor 的核心差异及适配方式：
   --enhance <domain>     编码前先对指定域执行增量 Skill 更新（如 --enhance album）
   --file <path>          聚焦单文件：从该文件推断域，只加载相关 Skill
   --no-design            跳过 Design Brief 内联设计（极速模式，仅适合单行改动）
-  --story <id>           关联 TAPD Story ID，将编码日志写入 modus/stories/{id}/vibe-log.md
+  --story <id>           关联 TAPD Story ID，将编码日志写入 modus/artifacts/{id}/code/vibe-log.md
   --dry-run              只输出 Design Brief，不生成实际代码（用于方案确认）
   --watch                持续监听文件变化，触发 save-driven vibe coding（实验性）
   --codex                Codex 平台模式：禁用交互提问，全批量推断输出，自动推断所有决策
@@ -531,7 +531,7 @@ Codex 平台与 Cursor 的核心差异及适配方式：
   /modus:vibe 实现艺人等级更新 --codex --story 9876543
 
 业务知识路径（v3.1）：
-  modus/knowledge/biz-{domain}/SKILL.md
+  modus/knowledge_base/domain/{domain}/code/SKILL.md
 
 相关命令：
   /modus:init    初始化/更新知识库（首次使用前建议先跑）

package/templates/template/analysis.md

@@ -0,0 +1,83 @@
+# Analysis — Harness Loop1 分析报告模板
+
+> **生成位置**：（v3.2 旧）`modus/stories/<id>/harness/01-analysis.md`
+> **生成位置**：（v4.0 新）通常拆为 `modus/artifacts/<id>/pid/prd.md` + `modus/artifacts/<id>/design/design.md`
+> 当只需轻量分析（不区分 PID/Design）时，使用本模板，置于 `modus/artifacts/<id>/pid/analysis.md`
+> **生成命令**：Harness Loop1 SubAgent00（modus-analyst）
+
+---
+
+## 元信息
+
+```yaml
+story_id: ""
+agent: "modus-analyst"
+schema_version: "1.1"
+created_at: ""
+input:
+  tapd_url: ""
+  prd_attachments: []
+output:
+  next_subagent: "modus-designer"
+  handoff_block: "see HANDOFF below"
+```
+
+---
+
+## 1. 需求理解
+
+### 1.1 一句话总结
+
+### 1.2 详细需求（结构化）
+- **谁**：（用户角色）
+- **做什么**：（业务动作）
+- **价值**：（业务价值）
+- **场景**：（典型场景）
+
+---
+
+## 2. 关键信息抽取
+
+| 字段 | 值 | 来源 |
+|------|-----|------|
+| 优先级 |  | TAPD/产品 |
+| 截止日期 |  |  |
+| 涉及模块 |  |  |
+
+---
+
+## 3. 不确定项（必须澄清后才能进入 Design）
+
+| 不确定点 | 影响范围 | 候选方案 | 推荐 |
+|---------|---------|---------|------|
+|  |  |  |  |
+
+---
+
+## 4. 历史相似需求
+
+| Story ID | 相似度 | 差异点 |
+|----------|--------|-------|
+|  |  |  |
+
+---
+
+## HANDOFF（schema v1.1）
+
+```yaml
+schema_version: "1.1"
+from: "modus-analyst"
+to: "modus-designer"
+story_id: ""
+status: "ready_for_design"
+artifacts:
+  - "modus/artifacts/<id>/pid/prd.md"
+checkpoints:
+  unresolved_questions: []
+  related_stories: []
+issues: []
+```
+
+---
+
+> **维护规则**：本模板仅用于 Harness Loop1 内部 handoff；最终用户阅读产物以 `pid/prd.md` 为准。

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"}` | 权限校验 |
+
+### 测试数据
+
+- **前置数据**：{...}
+- **清理数据**：{...}

package/templates/template/design.md

@@ -0,0 +1,160 @@
+# Design — 技术评估设计
+
+> **生成位置**：`modus/artifacts/<STORY_ID>/design/design.md`
+> **生成命令**：`/modus:plan --design <pid-path>` 或 Harness Loop1 SubAgent01.5（modus-designer）
+
+---
+
+## 元信息
+
+```yaml
+story_id: ""
+pid_ref: "modus/artifacts/<STORY_ID>/pid/prd.md"
+created_at: ""
+updated_at: ""
+status: "draft"           # draft | reviewed | approved | implemented
+reviewers: []             # 评审人列表
+related_designs: []       # 历史可复用设计
+```
+
+---
+
+## 1. 设计目标
+
+> 一段话：本次方案要达到的技术目标 + 与 PID 验收标准的对应关系。
+
+---
+
+## 2. 整体架构
+
+### 2.1 上下游关系
+```mermaid
+graph LR
+  A[上游系统] --> B[本服务]
+  B --> C[下游系统]
+```
+
+### 2.2 涉及模块清单
+
+| 模块 | 是否新增 | 变更类型 | 说明 |
+|------|---------|---------|------|
+|  |  | （新增/修改/删除） |  |
+
+---
+
+## 3. 接口设计
+
+### 3.1 对外暴露接口
+
+| 接口名 | 类型 | 路径/Topic | 是否新增 | 入参 | 出参 |
+|-------|------|-----------|---------|------|------|
+|  | HTTP/MQ/RPC |  |  |  |  |
+
+### 3.2 调用下游接口
+
+| 下游服务 | 接口 | 调用频率 | 超时 | 重试策略 | 降级方案 |
+|---------|------|---------|------|---------|---------|
+|  |  |  |  |  |  |
+
+> ⚠️ **超时必填**：每个下游调用必须明确写出超时时间和重试次数，不接受"按默认"。
+
+---
+
+## 4. 数据模型
+
+### 4.1 新增/修改的表
+
+| 表名 | 字段 | 类型 | 是否索引 | 说明 |
+|------|------|------|---------|------|
+|  |  |  |  |  |
+
+### 4.2 数据迁移
+
+- 是否需要迁移：（是/否）
+- 迁移方式：（脚本/在线 DDL/双写切流）
+- 回滚方案：
+
+---
+
+## 5. 状态流转（如适用）
+
+```mermaid
+stateDiagram-v2
+  [*] --> 待审核
+  待审核 --> 已通过
+  待审核 --> 已驳回
+  已通过 --> [*]
+  已驳回 --> [*]
+```
+
+| 状态 | 流入条件 | 流出条件 | 副作用 |
+|------|---------|---------|--------|
+|  |  |  |  |
+
+---
+
+## 6. 边界控制
+
+> 明确**本设计不解决**的问题，以及**与既有设计冲突点**的解决方案。
+
+- ❌ 不解决：（如：跨地域容灾，由基础设施层兜底）
+- ⚠️ 冲突点：与 XXX 模块的 YYY 字段语义存在歧义，约定使用 ZZZ
+- 🛡️ 兜底：当下游 A 不可用时，降级返回 B 的默认值
+
+---
+
+## 7. 性能与并发
+
+| 维度 | 目标 | 风险点 | 缓解措施 |
+|------|------|-------|---------|
+| QPS |  |  |  |
+| P99 延迟 |  |  |  |
+| 并发锁 |  |  |  |
+| 缓存穿透 |  |  |  |
+
+---
+
+## 8. 安全与合规
+
+- 鉴权方式：
+- 数据脱敏：
+- 审计日志：
+
+---
+
+## 9. 测试策略
+
+- 单元测试：
+- 集成测试：
+- 性能测试：
+- 灰度方案：
+
+---
+
+## 10. 实施步骤（高阶）
+
+> 仅描述大步骤；细粒度步骤在 plan.md 中展开。
+
+1. （步骤一）
+2. （步骤二）
+3. （步骤三）
+
+---
+
+## 11. 历史可复用资产
+
+| 来源 Story | 可复用内容 | 复用路径 |
+|-----------|-----------|---------|
+|  |  | `modus/artifacts/<id>/design/design.md` |
+
+---
+
+## 12. 评审记录
+
+| 日期 | 评审人 | 关键意见 | 决议 |
+|------|-------|---------|------|
+|  |  |  |  |
+
+---
+
+> **维护规则**：本模板由 modus-designer 自动填充第 1-10 节；评审记录由人工填写。