@modus-ai/modus 0.2.10 → 0.3.0

package/schemas/harness-schema.yaml

@@ -10,8 +10,8 @@ schema_version: "1.1"  # HANDOFF 协议版本（见 docs/protocol.md）
 
 # 产物根目录（v3.2）
 directories:
-  harness: "modus/stories/{story-id}/harness/"
-  knowledge: "modus/knowledge/"
+  harness: "modus/artifacts/{story_id}/code/"
+  knowledge: "modus/knowledge_base/"
   sessions: "modus/sessions/"
 
 # SubAgent 清单（SA00~SA08，共 9 个）
@@ -24,8 +24,8 @@ subAgents:
     handoff_agent: "00-skills-builder"
     name: 知识注入/提取（Skills Builder）
     generates:
-      - "Skill 文件（modus/knowledge/biz-*/SKILL.md）"
-      - "modus/knowledge-catalog.md"
+      - "Skill 文件（modus/knowledge_base/domain/*/code/SKILL.md）"
+      - "modus/knowledge_base/map.md"
     requires: []
     loop: 1
     modes:
@@ -39,7 +39,7 @@ subAgents:
     skill: modus-harness-01-analysis
     handoff_agent: "01-analysis"
     name: 需求分析
-    generates: ["modus/stories/{story-id}/harness/01-analysis.md"]
+    generates: ["modus/artifacts/{story_id}/pid/prd.md"]
     requires: ["00-INIT"]
     loop: 1
     gateAfter: A0   # Gate A0: 检查 01-analysis.md HANDOFF gate_status = "passed"
@@ -49,7 +49,7 @@ subAgents:
     skill: modus-harness-01-5-design
     handoff_agent: "02-design"
     name: 设计方案生成
-    generates: ["modus/stories/{story-id}/harness/02-design-brief.md"]
+    generates: ["modus/artifacts/{story_id}/design/design.md"]
     requires: ["01"]
     loop: 1
     human_checkpoint: true   # 架构决策确认 ⏸️ 人工交互节点
@@ -60,7 +60,7 @@ subAgents:
     skill: modus-harness-02-dev
     handoff_agent: "03-dev"
     name: 代码开发
-    generates: ["modus/stories/{story-id}/harness/03-sprint-contract.md"]
+    generates: ["modus/artifacts/{story_id}/code/sprint-contract.md"]
     requires: ["02"]
     loop: 1
     gateAfter: A    # Gate A: 执行 constitution.build_command，exit code = 0
@@ -70,7 +70,7 @@ subAgents:
     skill: modus-harness-03-test
     handoff_agent: "04-test"
     name: 代码测试（单元测试）
-    generates: ["modus/stories/{story-id}/harness/04-test-report.md"]
+    generates: ["modus/artifacts/{story_id}/code/test-report.md"]
     requires: ["03"]
     loop: 1
     parallel: ["04", "05", "06"]  # 与 SA05/SA06 并行执行
@@ -81,7 +81,7 @@ subAgents:
     skill: modus-harness-04-perf
     handoff_agent: "05-perf"
     name: 性能审计
-    generates: ["modus/stories/{story-id}/harness/05-perf-report.md"]
+    generates: ["modus/artifacts/{story_id}/code/perf-report.md"]
     requires: ["03"]
     loop: 1
     parallel: ["04", "05", "06"]
@@ -92,7 +92,7 @@ subAgents:
     skill: modus-harness-05-security
     handoff_agent: "06-security"
     name: 安全审计
-    generates: ["modus/stories/{story-id}/harness/06-security-report.md"]
+    generates: ["modus/artifacts/{story_id}/code/security-report.md"]
     requires: ["03"]
     loop: 1
     parallel: ["04", "05", "06"]
@@ -103,7 +103,7 @@ subAgents:
     skill: modus-harness-06-review
     handoff_agent: "07-review"
     name: 代码评审（CR）
-    generates: ["modus/stories/{story-id}/harness/cr-report.md"]
+    generates: ["modus/artifacts/{story_id}/code/cr-report.md"]
     requires: ["04", "05", "06"]  # Gate B 通过后触发
     loop: 1                        # CR 在 Loop 1 执行；Loop 2 是对 SA03 的精准重入，非 CR 重跑
     gateAfter: C    # Gate C: cr-report.md HANDOFF issues 为空或全为 P3
@@ -112,7 +112,7 @@ subAgents:
     skill: modus-harness-07-deploy
     handoff_agent: "08-deploy"
     name: 部署发布
-    generates: ["modus/stories/{story-id}/harness/08-deploy-status.md"]
+    generates: ["modus/artifacts/{story_id}/code/deploy-status.md"]
     requires: ["07"]  # Gate C 通过后触发
     loop: 1
     human_checkpoint: true  # prd 环境等待人工确认
@@ -195,7 +195,7 @@ archive:
 
 # 断点续跑状态文件
 stateFile:
-  path: "modus/stories/{story-id}/harness/.harness-state.yaml"
+  path: "modus/artifacts/{story_id}/code/.harness-state.yaml"
   fields:
     story_id: "string"
     loop: "integer（1 或 2）"

package/templates/agents/modus-analyst.md

@@ -7,8 +7,8 @@ enabledAutoRun: true
 enabled: true
 ---
 
-读取并严格遵循 `.codebuddy/skills/modus-analyst/SKILL.md` 中的执行规范。
+读取并严格遵循 `.modus/skills/modus-analyst/SKILL.md` 中的执行规范。
 
-产出物路径：`modus/stories/{story-id}/harness/01-analysis.md`
+产出物路径：`modus/artifacts/{story_id}/pid/prd.md`（v4.0 路径；详见 `templates/paths-v4.md`）
 
 产出物头部必须包含 HANDOFF 块，包含 `agent`、`story_id`、`domains`、`risk_level`、`key_constraints`、`skill_refs`、`gate_status` 字段。

package/templates/agents/modus-deployer.md

@@ -7,7 +7,7 @@ enabledAutoRun: false
 enabled: true
 ---
 
-读取并严格遵循 `.codebuddy/skills/modus-deployer/SKILL.md` 中的执行规范。
+读取并严格遵循 `.modus/skills/modus-deployer/SKILL.md` 中的执行规范。
 
 输入依赖：`cr-report.md`（HANDOFF.gate_status = passed）+ `02-sprint-contract.md`。
 

package/templates/agents/modus-designer.md

@@ -4,7 +4,7 @@ SubAgent — 技术方案设计。
 
 ## Instructions
 
-Read and follow the skill at `.codebuddy/skills/modus-designer/SKILL.md` to execute this SubAgent.
+Read and follow the skill at `.modus/skills/modus-designer/SKILL.md` to execute this SubAgent.
 
 ## Quick Summary
 

package/templates/agents/modus-developer.md

@@ -7,7 +7,7 @@ enabledAutoRun: true
 enabled: true
 ---
 
-读取并严格遵循 `.codebuddy/skills/modus-developer/SKILL.md` 中的执行规范。
+读取并严格遵循 `.modus/skills/modus-developer/SKILL.md` 中的执行规范。
 
 输入依赖：`modus/plans/active/{story-id}/01-analysis.md` 的 HANDOFF 块 + 相关业务 Skill 内容（由 Orchestrator 传入）。
 

package/templates/agents/modus-perf-auditor.md

@@ -7,7 +7,7 @@ enabledAutoRun: true
 enabled: true
 ---
 
-读取并严格遵循 `.codebuddy/skills/modus-perf-auditor/SKILL.md` 中的执行规范。
+读取并严格遵循 `.modus/skills/modus-perf-auditor/SKILL.md` 中的执行规范。
 
 输入依赖：`modus/plans/active/{story-id}/02-sprint-contract.md` 的 HANDOFF 块 + 代码变更文件。
 

package/templates/agents/modus-reviewer.md

@@ -7,7 +7,7 @@ enabledAutoRun: true
 enabled: true
 ---
 
-读取并严格遵循 `.codebuddy/skills/modus-reviewer/SKILL.md` 中的执行规范。
+读取并严格遵循 `.modus/skills/modus-reviewer/SKILL.md` 中的执行规范。
 
 输入依赖：全部产出物（01-analysis.md 至 05-security-report.md）的 HANDOFF 块 + 代码变更。
 

package/templates/agents/modus-security-auditor.md

@@ -7,7 +7,7 @@ enabledAutoRun: true
 enabled: true
 ---
 
-读取并严格遵循 `.codebuddy/skills/modus-security-auditor/SKILL.md` 中的执行规范。
+读取并严格遵循 `.modus/skills/modus-security-auditor/SKILL.md` 中的执行规范。
 
 输入依赖：`modus/plans/active/{story-id}/02-sprint-contract.md` 的 HANDOFF 块 + 代码变更文件。
 

package/templates/agents/modus-skill-creator.md

@@ -7,6 +7,6 @@ enabledAutoRun: true
 enabled: true
 ---
 
-读取并严格遵循 `.codebuddy/skills/modus-skill-creator/SKILL.md` 中的执行规范和五种工作模式（A: 新建 Skill / B: 增量更新 / C: 知识回写 / D: Harness 归档提取 / E: 基础 Skill 初始化）。
+读取并严格遵循 `.modus/skills/modus-skill-creator/SKILL.md` 中的执行规范和五种工作模式（A: 新建 Skill / B: 增量更新 / C: 知识回写 / D: Harness 归档提取 / E: 基础 Skill 初始化）。
 
 调用方必须在 prompt 中明确指定工作模式（A/B/C/D/E）和目标业务域列表。

package/templates/agents/modus-tester.md

@@ -7,7 +7,7 @@ enabledAutoRun: true
 enabled: true
 ---
 
-读取并严格遵循 `.codebuddy/skills/modus-tester/SKILL.md` 中的执行规范。
+读取并严格遵循 `.modus/skills/modus-tester/SKILL.md` 中的执行规范。
 
 输入依赖：`modus/plans/active/{story-id}/02-sprint-contract.md` 的 HANDOFF 块 + 代码变更文件。
 

package/templates/commands/auto.md

@@ -2,6 +2,8 @@
 
 **用途：** 读取 TAPD Story，从四个维度（复杂度/风险/需求明确度/接口契约）进行评分，自动推荐最适合的 Modus 命令（vibe/plan/spec/harness），确认后自动启动。**不确定用哪个命令时，首选此命令。**
 
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
+
 ## 执行流程
 
 1. 接受 TAPD Story URL（或提示手动粘贴内容）
@@ -71,4 +73,4 @@
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-auto/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-auto/SKILL.md` 中的完整流程（中性源；各平台目录为引用桩）。

package/templates/commands/commit.md

@@ -1,6 +1,8 @@
 # /modus:commit
 
-Knowledge-aware git commit. Drains pending knowledge from `modus/sessions/pending-knowledge.yaml` into the corresponding business Skill files, then executes the actual git commit.
+Knowledge-aware git commit. Drains pending knowledge from `modus/sessions/pending-knowledge.yaml` into the corresponding domain knowledge files (`modus/knowledge_base/domain/<d>/code/`) and into `business/` if rule-level, then executes the actual git commit.
+
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
 
 ## Instructions
 
@@ -32,15 +34,19 @@ During `/modus:vibe` sessions, newly discovered knowledge (new enum values, busi
    是否将以上知识写入对应 Skill 文件？[Y/n]
    ```
 
-3. **Write back to Skills (if confirmed):**  
+3. **Write back to knowledge base (if confirmed):**
    For each entry in `pending-knowledge.yaml`:
-   - Call `modus-skill-creator` Mode C to append the entry to the corresponding `modus-biz-{domain}/SKILL.md`
+   - Determine target file by knowledge type:
+     - `[model]` / `[enum]` / `[api]` → `modus/knowledge_base/domain/<d>/code/{entities|apis|services|data-models}.md`
+     - `[pitfall]` / `[guideline]` / `[business-rule]` → `modus/knowledge_base/domain/<d>/business/`
+   - Call `modus-skill-creator` Mode C to append the entry
    - Mark the entry as `settled: true` in `pending-knowledge.yaml`
-   - Output per-entry status: `✓ [pitfall] → modus-biz-order 已写入`
+   - Output per-entry status: `✓ [pitfall] → domain/order/business/ 已写入`
 
    After all entries processed:
    - Remove settled entries from `pending-knowledge.yaml` (keep only `settled: false` entries)
-   - Update `modus/knowledge-catalog.md` if any Skill version changed
+   - Update `modus/knowledge_base/map.md` if any domain knowledge version changed
+   - Append a record to `modus/knowledge_base/domain/<d>/history/{YYYY-MM-DD}-{topic}.md`
 
 4. **Execute git commit:**  
    Run the standard git commit flow:

package/templates/commands/cr.md

@@ -1,6 +1,8 @@
 # /modus:cr — 代码评审（含文档一致性检查）
 
-**用途：** 基于技术方案文档（design.md / plan.md）和可选的 PRD，对代码变更进行「文档-代码一致性检查」与「代码质量 CR」，输出分级问题报告，可选自动创建 TAPD Bug 单。
+**用途：** 基于技术方案文档（`design.md` / `plan.md`）和可选的 PRD，对代码变更进行「文档-代码一致性检查」与「代码质量 CR」，输出分级问题报告，可选自动创建 TAPD Bug 单。
+
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
 
 **借鉴自：** speckit.analyze（文档一致性自检）+ modus-reviewer（代码质量 CR 框架）+ opsx:apply（contextFiles 上下文加载）
 
@@ -20,9 +22,10 @@
 ## 使用示例
 
 ```
-/modus:cr --doc modus/plans/batch-export/design.md
-/modus:cr --doc modus/plans/batch-export/design.md --story https://tapd.cn/.../123
-/modus:cr --doc "modus/plans/feat/design.md modus/plans/feat/tasks.md"
+/modus:cr --doc modus/artifacts/{story_id}/design/design.md
+/modus:cr --doc modus/artifacts/{story_id}/design/design.md --story https://tapd.cn/.../123
+/modus:cr --doc "modus/artifacts/{story_id}/design/design.md modus/artifacts/{story_id}/code/plan.md"
+/modus:cr --doc modus/plans/batch-export/design.md     # 独立模式（不关联 Story）
 /modus:cr --quick --diff src/order/
 /modus:cr --doc modus/plans/refactor/design.md --diff src/payment/
 ```
@@ -39,12 +42,13 @@
 ⑥ 可选：自动创建 TAPD Bug 单（需配置 tapdProjectId）
 ```
 
-## 产出物
+## 产出物（v4.0）
 
-```
-modus/cr/{YYYYMMDD}-{feature-name}/
-└── cr-report.md    — 评审报告（HANDOFF 格式，含一致性摘要 + P1/P2/P3 问题）
-```
+**关联 Story时**：写入 `modus/artifacts/{story_id}/code/cr-report.md`
+
+**独立模式**：写入 `modus/cr/{YYYYMMDD}-{feature-name}/cr-report.md`
+
+报告格式与HANDOFF 一致，含一致性摘要 + P1/P2/P3 分级问题列表。
 
 ## 与 harness 内置 CR 的对比
 
@@ -71,4 +75,4 @@ modus/cr/{YYYYMMDD}-{feature-name}/
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-cr/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-cr/SKILL.md` 中的完整流程（中性源；各平台目录为引用桩）。

package/templates/commands/harness.md

@@ -1,6 +1,8 @@
 # /modus:harness — 双 Loop 全自动开发流程
 
-**用途：** 输入 TAPD Story URL，自动执行从需求分析到部署验证的完整开发流程。8 个专业 SubAgent 分工协作，双 Loop 质量闭环，最终将开发经验自动沉淀到知识库。
+**用途：** 输入 TAPD Story URL，自动执行从需求澄清、设计、开发到部署验证的完整开发流程。8 个专业 SubAgent 分工协作，双 Loop 质量闭环，最终将开发经验自动沉淀到知识库。
+
+> **路径范式版本：v4.0**（产出物废 `modus/plans/active/`，统一使用 `modus/artifacts/{story_id}/` 按 pid/design/code/archive 划分子目录；详见 `templates/paths-v4.md`）
 
 **借鉴自：** GitHub Actions Job/Step/Gate 模型 + Devin 多步骤 Agent 架构
 
@@ -50,13 +52,14 @@
 
 ```
 Loop 1（生产层）
-  INIT:   SubAgent 00 知识注入（更新相关 Skill 至最新）
-  SA 01:  需求分析 → 01-analysis.md
-  SA 02:  代码开发 → 02-sprint-contract.md + 代码变更
+  INIT:   SubAgent 00 知识注入（更新相关 domain 知识至最新）
+  SA 01:  需求澄清 → modus/artifacts/{story_id}/pid/prd.md + dialog/
+  SA 01.5: 设计评审 → modus/artifacts/{story_id}/design/design.md
+  SA 02:  代码开发 → modus/artifacts/{story_id}/code/sprint-contract.md + 代码变更
   Gate A: 编译验证（mvn clean compile）→ 失败重入 SA 02，最多 3 次
   SA 03+04+05: 并行（测试/性能/安全）
   Gate B: 三份报告全部 complete
-  SA 06:  代码评审 → cr-report.md
+  SA 06:  代码评审 → modus/artifacts/{story_id}/code/cr-report.md
 
 Loop 2（修复层）
   Gate C: 读 cr-report.md 的 issues 列表
@@ -64,8 +67,8 @@ Loop 2（修复层）
   → 通过：进入收尾
 
 收尾
-  SA 07:  部署验证 → 07-deploy-status.md（prd 等待人工确认）
-  ARCHIVE: 知识提取回写 Skill + 更新 catalog
+  SA 07:  部署验证 → modus/artifacts/{story_id}/code/deploy-status.md（prd 等待人工确认）
+  ARCHIVE: 知识提取回写 modus/knowledge_base/domain/{d}/history/ + 更新 map.md
   Human Final Review: 人工确认后合入主干
 ```
 
@@ -85,18 +88,24 @@ Loop 2（修复层）
 [ARCH]  ✓ 知识沉淀 (2 [pitfall], 1 [decision] 回写)
 ```
 
-## 产出物
+## 产出物（v4.0）
 
 ```
-modus/plans/active/{story-id}/
-├── 01-analysis.md          ← SubAgent 01 产出，含 HANDOFF 块（影响范围、Sprint 拆分）
-├── 01.5-design-brief.md    ← SubAgent 01.5 产出，含架构决策
-├── 02-sprint-contract.md   ← SubAgent 02 产出，含代码变更清单（接口契约）
-├── 03-test-report.md       ← SubAgent 03 产出（单元测试报告）
-├── 04-perf-report.md       ← SubAgent 04 产出（性能审计 N+1/分页风险）
-├── 05-security-report.md   ← SubAgent 05 产出（安全审计 多租户/权限）
-├── cr-report.md            ← SubAgent 06 产出，含 HANDOFF.issues（P1/P2/P3）
-└── 07-deploy-status.md     ← SubAgent 07 产出（部署状态 各环境结果）
+modus/artifacts/{story_id}/
+├── pid/
+│   ├── prd.md                   ← SubAgent 01 (modus-analyst)产出
+│   └── dialog/                  ← 多轮澄清对话历史
+├── design/
+│   └── design.md                ← SubAgent 01.5 (modus-designer)产出
+├── code/
+│   ├── sprint-contract.md       ← SubAgent 02 (modus-developer)产出，含 HANDOFF
+│   ├── test-report.md           ← SubAgent 03 (modus-tester)
+│   ├── perf-report.md           ← SubAgent 04 (modus-perf-auditor)
+│   ├── security-report.md       ← SubAgent 05 (modus-security-auditor)
+│   ├── cr-report.md             ← SubAgent 06 (modus-reviewer)，含 HANDOFF.issues
+│   ├── deploy-status.md         ← SubAgent 07 (modus-deployer)
+│   └── .harness-state.yaml      ← 状态机
+└── archive/                     ← 上线后人工触发，输出 summary.md 与 key-scenarios/
 ```
 
 所有产出物头部包含 HANDOFF 块（schema v1.1，见 `modus/docs/protocol.md`）。
@@ -119,4 +128,4 @@ skill_refs: ["biz-track@v2.1"]
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-harness/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-harness/SKILL.md` 中的完整流程（中性源；各平台目录为引用桩）。

package/templates/commands/init.md

@@ -1,6 +1,8 @@
-# /modus:init — 业务知识库初始化
+# /modus:init — 业务知识库初始化（v4.0）
 
-**用途：** 扫描项目代码，按业务域分类，在 `modus/knowledge/` 下生成结构化 Skill 文件，作为后续所有 Modus 命令的知识底座。支持多项目工作区路由和多平台引用式适配。
+**用途：** 扫描项目代码，按业务域分类，在 `modus/knowledge_base/domain/` 下生成结构化知识，作为后续所有 Modus 命令的知识底座。支持多项目工作区路由、多平台引用式适配，以及 v3.2 → v4.0 路径迁移。
+
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
 
 ## 参数说明
 
@@ -9,41 +11,72 @@
 
   --help                    显示完整帮助（中文）
   --project <name>          指定项目（多项目 workspace 使用）
-  --enhance <domain>        仅增量更新指定业务域（如 --enhance biz-track）
-  --enhance-all             重建所有业务域 Skill（保留框架 Skill）
-  --platform <p1,p2>        仅同步指定平台（claude,cursor,codex,copilot）
+  --enhance <domain>        仅增量更新指定业务域（如 --enhance contract）
+  --enhance-all             重建所有业务域知识（保留 _conventions / _tech-wiki）
+  --platform <p1,p2>        仅同步指定平台（claude,cursor,codex,copilot,codebuddy,continue）
   --dry-run                 预览将生成/修改的文件，不写入磁盘
   --force                   跳过所有确认提示，直接执行
-  --no-sync                 跳过多平台同步，仅生成 modus/knowledge/
-  --migrate                 迁移旧路径 .codebuddy/skills/modus-biz-* → modus/knowledge/
+  --no-sync                 跳过多平台同步，仅生成 modus/knowledge_base/
+  --migrate-v4              迁移 v3.2 路径 → v4.0（modus/knowledge/ → modus/knowledge_base/domain/<d>/code/，
+                            modus/stories/ → modus/artifacts/）
+  --migrate                 兼容旧版别名，等同 --migrate-v4
   --verbose                 输出详细扫描过程
-  --reset-maturity          重置所有 Skill 的 maturity 为 draft
+  --reset-maturity          重置所有业务域知识的 maturity 为 draft
 ```
 
 ## 使用示例
 
 ```
-/modus:init                          # 全量初始化（首次使用或大重构后）
-/modus:init --help                   # 查看帮助
-/modus:init --enhance biz-track      # 仅更新歌曲域知识
-/modus:init --migrate --dry-run      # 预览知识库路径迁移
-/modus:init --migrate                # 执行迁移（旧路径 → modus/knowledge/）
-/modus:init --enhance-all --no-sync  # 重建所有域，不同步平台
-/modus:init --project operations-job # 多项目时指定项目
+/modus:init                                # 全量初始化（首次使用或大重构后）
+/modus:init --help                         # 查看帮助
+/modus:init --enhance contract             # 仅更新合同域知识（v4 域名不再带 biz- 前缀）
+/modus:init --migrate-v4 --dry-run         # 预览 v3.2 → v4.0 迁移
+/modus:init --migrate-v4                   # 执行迁移
+/modus:init --enhance-all --no-sync        # 重建所有域，不同步平台
+/modus:init --project operations-job       # 多项目时指定项目
 ```
 
-## 产出物
+## 产出物（v4.0）
 
 ```
-modus/knowledge/
-├── _conventions/SKILL.md   — Layer 0-T 团队约定（融合各平台规则）
-├── _tech-wiki/SKILL.md     — Layer 1 技术知识骨架
-└── biz-{domain}/SKILL.md   — Layer 2 业务域知识（每个域一个）
+modus/knowledge_base/
+├── map.md                                 # L0 全景索引（替代旧 knowledge-catalog.md）
+├── service-graph.md                       # L0 全局服务调用图
+└── domain/
+    ├── _conventions/code/SKILL.md         # 团队约定（横切）
+    ├── _tech-wiki/code/SKILL.md           # 技术 Wiki（横切）
+    └── <domain>/                          # 普通业务域
+        ├── README.md                      # 域描述
+        ├── code/                          # 代码翻译层（强刷生成）
+        │   ├── SKILL.md                   # 入口（含 frontmatter）
+        │   ├── entities.md
+        │   ├── apis.md
+        │   ├── services.md
+        │   └── data-models.md
+        ├── business/                      # 业务规则（人工维护，不被覆盖）
+        ├── scenarios/                     # 测试场景（人工/spec 命令维护）
+        └── history/                       # 变更历史（追加）
+
+modus/workspace-catalog.md                 # 工作区顶层路由（多项目）
+
+# 命令源（中性层，所有平台共用）
+.modus/commands/*.md
+.modus/skills/*/                           # 团队自定义技能包
 
-modus/knowledge-catalog.md  — 全景索引（所有命令的快速入口）
-modus/workspace-catalog.md  — 工作区顶层路由（多项目）
+# 平台引用桩（仅 1 行 @import 指向中性源）
+.codebuddy/ | .claude/ | .cursor/ | .continue/ ...
 ```
 
+## v3.2 → v4.0 迁移要点
+
+| v3.2 旧 | v4.0 新 |
+|---------|---------|
+| `modus/knowledge/biz-{d}/SKILL.md` | `modus/knowledge_base/domain/{d}/code/SKILL.md`（拆为 5 文件） |
+| `modus/knowledge-catalog.md` | `modus/knowledge_base/map.md` |
+| `modus/stories/{id}/...` | `modus/artifacts/{id}/...`（按 pid/design/code/archive 分目录） |
+
+详见 `templates/paths-v4.md`。
+
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-init/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-init/SKILL.md` 中的完整流程（中性源；平台目录如 `.codebuddy/skills/modus-init/SKILL.md` 为引用桩）。

package/templates/commands/modus.md

@@ -6,7 +6,7 @@
 
 | 命令 | 用途 | 常用参数 |
 |------|------|---------|
-| `/modus:init` | 扫描代码库，初始化/更新业务知识库 | `--enhance <domain>`, `--migrate`, `--dry-run` |
+| `/modus:init` | 扫描代码库，初始化/更新业务知识库 | `--enhance <domain>`, `--migrate-v4`, `--dry-run` |
 | `/modus:vibe` | 上下文感知日常编码（氛围编程） | `--domain <name>`, `--verbose` |
 | `/modus:plan` | 功能规划（设计文档 + Build 循环） | `--story <url>`, `--design`, `--quick` |
 | `/modus:spec` | 规范驱动开发（行为规格 + 验收标准） | `--story <url>`, `--lite`, `--testcase` |
@@ -43,22 +43,44 @@
 /modus:harness https://tapd.cn/.../stories/view/1234567890
 ```
 
-## 知识库路径（v3.2）
+## 知识库路径（v4.0）
 
 ```
-modus/knowledge/                   # Single Source of Truth（平台无关）
-├── _conventions/SKILL.md          # 团队约定（Layer 0-T）
-├── _tech-wiki/SKILL.md            # 技术知识（Layer 1）
-└── biz-{domain}/SKILL.md          # 业务域知识（Layer 2）
-
-modus/knowledge-catalog.md         # 项目知识目录（~200 tokens）
-modus/workspace-catalog.md         # 工作区顶层路由（多项目）
+modus/                                          # 顶层 Models 层
+├── template/                                    # 产出模板（pid/design/spec/plan/...）
+├── knowledge_base/                              # Single Source of Truth
+│   ├── map.md                                   # 全景索引（~200 tokens）
+│   ├── service-graph.md                         # L0 全局调用图
+│   └── domain/
+│       ├── _conventions/code/SKILL.md           # 团队约定
+│       ├── _tech-wiki/code/SKILL.md             # 技术知识
+│       └── <domain>/                            # 业务域
+│           ├── code/                            # 代码翻译层（自动生成）
+│           │   ├── SKILL.md
+│           │   ├── entities.md
+│           │   ├── apis.md
+│           │   ├── services.md
+│           │   └── data-models.md
+│           ├── business/                        # 业务规则（人工维护）
+│           ├── scenarios/                       # 测试场景
+│           └── history/                         # 变更历史
+└── artifacts/<STORY_ID>/                        # 产出区（按 Story 隔离）
+    ├── pid/                                     # 需求澄清
+    ├── design/                                  # 评估设计
+    ├── code/                                    # 编码实施（plan/spec/harness）
+    └── archive/                                 # 上线后人工归档
+
+.modus/                                         # CLI 中性层
+├── commands/                                    # 命令全集源头
+└── skills/                                      # 团队自定义技能包
+
+.codebuddy/ | .claude/ | .cursor/ | .continue/  # 平台引用桩（仅 1 行 @import）
 ```
 
 重新初始化或更新知识库：
 
 ```
-/modus:init --enhance biz-track    # 仅更新某个域
+/modus:init --enhance <domain>     # 仅更新某个域（v4 名不带 biz- 前缀）
 /modus:init --enhance-all          # 重建所有业务域
-/modus:init --migrate              # 从旧路径迁移到 modus/knowledge/
+/modus:init --migrate-v4           # 从 v3.2 路径迁移
 ```

package/templates/commands/plan.md

@@ -1,6 +1,8 @@
 # /modus:plan — 功能规划（含 Build 执行与知识归档）
 
-**用途：** 针对一个具体需求，基于业务 Skill 上下文进行六维复杂度评估，提出 3 个精准澄清问题后生成结构化 `plan.md`，在用户确认后执行代码生成，最后自动回写新知识到 Skill 库。
+**用途：** 针对一个具体需求，基于业务知识库（`modus/knowledge_base/`）上下文进行六维复杂度评估，提出 3 个精准澄清问题后生成结构化 `plan.md`，在用户确认后执行代码生成，最后自动回写新知识到知识库。
+
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
 
 **借鉴自：** Cursor Plan Mode（只读规划阶段 + 用户确认后执行）
 
@@ -36,8 +38,8 @@
 /modus:plan --design 评估版权对账系统的重构方案
 /modus:plan --design --story https://tapd.cn/.../123456        # 设计评审模式，关联 TAPD
 /modus:plan --continue my-feature                              # 评审通过，接力 harness 开发
-/modus:plan --code modus/plans/batch-export/design.md          # 按 design.md 任务清单编码（★ 新增）
-/modus:plan --code modus/plans/batch-export/                   # 自动定位目录下的设计文档（★ 新增）
+/modus:plan --code modus/artifacts/{story_id}/code/design.md   # 按 design.md 任务清单编码（v4 路径）
+/modus:plan --code modus/artifacts/{story_id}/code/             # 自动定位目录下的设计文档
 /modus:plan --quick 修复版权审核列表分页 bug
 /modus:plan --read-only 分析中央曲库同步的架构方案
 /modus:plan --resume batch-export 继续上次中断的规划
@@ -53,7 +55,7 @@
   ↓ 人工评审通过后（两种路径可选）
 
 路径 A：任务驱动编码（轻量，无 harness）
-  /modus:plan --code modus/plans/{name}/design.md
+  /modus:plan --code modus/artifacts/{story_id}/code/design.md
   ↓ 按 tasks.md 中的 T-ID 逐任务执行，`- [ ]` → `- [x]`
   ↓ 完成后建议 /modus:cr --doc
 
@@ -67,10 +69,10 @@
 ## 执行流程概览
 
 ```
-① 域匹配：基于 knowledge-catalog.md 判断涉及的业务域
+① 域匹配：基于 modus/knowledge_base/map.md 判断涉及的业务域
 ② 复杂度评估：六维评分 → simple / medium / complex 分级
    complex → 提示考虑升级为 /modus:spec 或 /modus:harness
-③ 两层知识检索：Skill 前置更新（hash 检查）→ 源码按需加载
+③ 两层知识检索：域入口 SKILL.md 前置更新（hash 检查）→ entities/apis/services/data-models 按需加载 → 源码按需加载
 ④ 精准 3 问：pitfall 关联问题 + 范围边界 + 优先级约束
 ⑤ 生成 plan.md：概述 / 关键约束 / 已知风险 / 方案对比 / Todos / 影响文件
    ⚠️ 规划阶段 — 此时尚未修改任何代码
@@ -78,25 +80,27 @@
 ⑦ 后置知识回写：技术决策 → [decision]，新风险 → [pitfall]
 ```
 
-## 产出物
+## 产出物（v4.0）
 
-**标准模式（无 --design）：**
+**Story 模式（含 --story）：**
 ```
-modus/plans/{name}/
-├── .modus-state.yaml   — 状态文件（含 complexity，支持断点续跑）
-└── plan.md             — 规划文档（概述/风险/方案对比/Todos/影响文件）
+modus/artifacts/{story_id}/
+├── design/design.md       — --design 模式产出
+└── code/
+    ├── plan.md            — 标准模式产出
+    ├── .modus-state.yaml  — 状态机，支持断点续跑
+    └── spec/              — （如后续接 /modus:spec）
 ```
 
-**--design 模式（多 artifact）：**
+**独立模式（不含 --story）：**
 ```
-modus/plans/{name}/
-├── .modus-state.yaml   — 状态文件（含 artifacts DAG 状态）
-├── research.md         — 技术可行性研究（复杂度 ≥ medium 时生成）
-├── design.md           — 技术设计文档（9 节：5W1H/3方案/影响范围/API/数据模型/约束/风险/估时）
-└── tasks.md            — 任务清单（spec-kit T-ID 格式，供 --code 模式消费）
+modus/plans/{name}/        — 临时规划区（未关联 Story）
+├── .modus-state.yaml
+├── plan.md
+└── design.md / research.md / tasks.md  （仅 --design 模式）
 ```
 
-归档后移动到：`modus/plans/archive/{date}-{name}/`
+归档后移动到：`modus/artifacts/{story_id}/archive/`（Story 模式）或 `modus/plans/archive/{date}-{name}/`（独立模式）
 
 ## 与其他命令的对比
 
@@ -109,4 +113,4 @@ modus/plans/{name}/
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-plan/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-plan/SKILL.md` 中的完整流程（中性源；各平台目录下同名文件为引用桩）。