@modus-ai/modus 0.2.10 → 0.3.0

package/templates/commands/spec.md

@@ -2,6 +2,8 @@
 
 **用途：** 在 `/plan` 基础上增加行为规格（delta specs），用 GIVEN/WHEN/THEN 明确系统「WHAT」，规格可测试，归档时自动检测冲突并合并到主规格库（Source of Truth）。适用于有接口契约变更、需要可测试验收标准的场景。
 
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
+
 **借鉴自：** OpenSpec 规范 + Gherkin BDD（Cucumber）的 Feature/Scenario 格式
 
 ## 参数说明
@@ -36,11 +38,11 @@
 | 维度 | `/modus:plan` | `/modus:spec` |
 |------|--------------|----------------|
 | 产出物 | 单一 `plan.md` | `delta-specs.md` + `design.md` + `tasks.md` |
-| 目录 | `modus/plans/{name}/` | `modus/changes/{name}/` |
-| 行为规格 | 无 | 有（ADDED/MODIFIED/REMOVED + GIVEN/WHEN/THEN） |
-| 验收标准 | 无 | 有（可测试 Scenario） |
-| 冲突检测 | 无 | 有（MODIFIED/REMOVED 目标必须存在于主库） |
-| 归档目标 | `modus/plans/archive/` | 合并到 `modus/specs/{domain}/spec.md` |
+| 目录 | `modus/artifacts/{story_id}/code/` 或 `modus/plans/{name}/` | `modus/artifacts/{story_id}/code/spec/` 或 `modus/changes/{name}/` |
+| 行为规格 | 无 | 有（ADDED/MODIFIED/REMOVED + GIVEN/WHEN/THEN）|
+| 验收标准 | 无 | 有（可测试 Scenario）|
+| 冲突检测 | 无 | 有（MODIFIED/REMOVED 目标必须存在于主库）|
+| 归档目标 | `modus/artifacts/{id}/archive/` 或 `modus/plans/archive/` | 合并到 `modus/knowledge_base/domain/{d}/scenarios/` 或 `modus/specs/{domain}/spec.md` |
 
 ## Delta Specs 格式（Gherkin 风格）
 
@@ -60,22 +62,33 @@ Feature: 批量审批订单
   Then 系统返回 400 错误："批量操作上限 50 条"
 ```
 
-## 产出物
+## 产出物（v4.0）
 
+**Story 模式（含 --story）：**
+```
+modus/artifacts/{story_id}/
+├── design/design.md
+└── code/
+    ├── spec/                       — delta specs（ADDED/MODIFIED/REMOVED）
+    ├── spec-proposal.md            — 意图与范围
+    ├── tasks.md                    — 实现清单（追踪到 Scenario）
+    └── testcases.md                — QA 用例（--testcase 时生成）
+```
+
+**独立模式（不含 --story）：**
 ```
 modus/changes/{name}/
-├── .modus-state.yaml               — 状态文件（支持断点续跑）
-├── proposal.md                     — 意图与范围
-├── specs/{domain}/spec.md          — delta specs（ADDED/MODIFIED/REMOVED）
-├── design.md                       — 技术方案
-├── design-brief.md                 — 精确实现指南（Full 模式）
-├── tasks.md                        — 实现清单（追踪到 Scenario）
-└── testcases.md                    — QA 用例（--testcase 时生成）
-
-归档后：modus/changes/archive/{date}-{name}/
-主规格库：modus/specs/{domain}/spec.md（历次归档合并）
+├── .modus-state.yaml
+├── proposal.md
+├── specs/{domain}/spec.md
+├── design.md
+├── design-brief.md
+├── tasks.md
+└── testcases.md
 ```
 
+归档后：Story 模式合并到 `modus/knowledge_base/domain/{domain}/scenarios/`；独立模式合并到 `modus/specs/{domain}/spec.md`。
+
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-spec/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-spec/SKILL.md` 中的完整流程（中性源；各平台目录为引用桩）。

package/templates/commands/upgrade.md

@@ -33,8 +33,9 @@
 
 | 版本 | 主要变更 |
 |------|---------|
-| v4.0.0 | plan --design 设计评审节点；plan --continue + harness --from-plan 接力机制；HANDOFF protocol schema v1.3（plan 专用字段）；Progress Event Protocol（events.jsonl）；AGENTS.md 自动生成（modus update 驱动，不再手动维护） |
-| v3.2.0 | 跨 Skill 路径全面统一到 `modus/knowledge/biz-*/`；步骤编号规范化（禁止小数步骤）；modus-analyst 产出路径更正到 `modus/stories/{id}/harness/`；modus-plan 双路径产出规则（Story 模式 vs 独立模式） |
+| **v4.0.0** | 目录范式重构：`modus/knowledge/` → `modus/knowledge_base/domain/<d>/code/` (拆分 5 文件) + `business/` + `scenarios/` + `history/`；`modus/stories/` → `modus/artifacts/<id>/` (pid/design/code/archive)；`modus/knowledge-catalog.md` → `modus/knowledge_base/map.md`；新增 `modus/template/` 产出模板；新增 `.modus/commands/` + `.modus/skills/` 中立命令与团队技能包；平台目录全部降为引用桩 |
+| v3.3.0 | plan --design 设计评审节点；plan --continue + harness --from-plan 接力机制；HANDOFF protocol schema v1.3 (plan 专用字段)；Progress Event Protocol (events.jsonl)；AGENTS.md 自动生成 |
+| v3.2.0 | 跨 Skill 路径全面统一到 `modus/knowledge/biz-*/`；步骤编号规范化（禁止小数步骤）；modus-analyst 产出路径更正到 `modus/stories/{id}/harness/`；modus-plan 双路径产出规则 |
 | v3.1.0 | 知识库路径迁移：`.codebuddy/skills/modus-biz-*` → `modus/knowledge/biz-*`；新增工作区顶层路由 `modus/workspace-catalog.md`；HANDOFF 协议升级到 schema v1.1 |
 | v3.0.0 | 多项目工作区支持（modus-workspace.yaml）；引用式适配（不复制知识） |
 | v2.x | 初始版本 |
@@ -57,32 +58,43 @@
 ```
 Step 1: 备份
   创建 modus/backup/{YYYYMMDD}-v3.x/ 目录
-  复制所有现有 Skill 文件和 config.yaml 到备份目录
-
-Step 2: HANDOFF 格式兼容检查
-  扫描 modus/stories/*/harness/*.md 中的旧版 HTML 注释块（<!--HANDOFF...-->）
-  自动转换为 YAML frontmatter 格式（schema v1.1 → v1.2/v1.3）
-  输出：「已迁移 N 个产物文件到 YAML frontmatter 格式」
-
-Step 3: plan 产物字段补全
-  扫描 modus/plans/*/plan.md
-  在 HANDOFF frontmatter 中补充新字段（design_mode/status/continue_token/risk_level/estimated_effort）
-  默认值：design_mode=false, status=complete, continue_token=""
-
-Step 4: harness 命令 Skill 更新
-  更新 modus-harness Skill：添加 --from-plan 处理逻辑
-  更新 modus-plan Skill：添加 --design 分支 + --continue 接力逻辑
-  输出：「已更新 modus-harness / modus-plan Skill 模板」
-
-Step 5: 初始化进度事件目录
-  创建 modus/sessions/ 目录（若不存在）
-  创建 modus/sessions/events.jsonl（若不存在，初始化为空文件）
-  输出：「已初始化 Progress Event 日志：modus/sessions/events.jsonl」
-
-Step 6: AGENTS.md 自动生成（Codex 平台）
-  若 config.yaml platforms 含 codex，重新生成 AGENTS.md：
-  融合：workspace-catalog + constitution.hard_rules + 最新命令参数集
-  输出：「AGENTS.md 已重新生成（Codex 平台适配）」
+  复制所有现有知识与产物文件到备份目录
+
+Step 2: 知识库重构
+  modus/knowledge/biz-{d}/SKILL.md
+    → modus/knowledge_base/domain/{d}/code/SKILL.md  (仅保留 frontmatter 与摘要)
+    → 拆分原内容到 entities.md / apis.md / services.md / data-models.md
+    → 创建空的 business/ + scenarios/ + history/子目录
+  modus/knowledge/_conventions/SKILL.md
+    → modus/knowledge_base/domain/_conventions/code/SKILL.md
+  modus/knowledge/_tech-wiki/SKILL.md
+    → modus/knowledge_base/domain/_tech-wiki/code/SKILL.md
+  modus/knowledge-catalog.md
+    → modus/knowledge_base/map.md  (结构重生成)
+  生成 modus/knowledge_base/service-graph.md  (基于代码扫描)
+
+Step 3: 产出区重构
+  modus/stories/{id}/
+    ├─ harness/01-analysis.md       → modus/artifacts/{id}/pid/prd.md
+    ├─ harness/02-design-brief.md   → modus/artifacts/{id}/design/design.md
+    ├─ plan.md                      → modus/artifacts/{id}/code/plan.md
+    ├─ spec/                        → modus/artifacts/{id}/code/spec/
+    ├─ harness/03-sprint-contract   → modus/artifacts/{id}/code/sprint-contract.md
+    ├─ harness/cr-report.md         → modus/artifacts/{id}/code/cr-report.md
+    └─ harness/.harness-state.yaml  → modus/artifacts/{id}/code/.harness-state.yaml
+  创建空的 archive/ 子目录
+
+Step 4: 产出模板与中性命令源
+  将 templates/template/ 复制到项目下 modus/template/
+  将现有命令同步到 .modus/commands/  (中性源)
+  将团队资源迁移到 .modus/skills/  (如某些所谓的「查日志」Skill)
+
+Step 5: 平台目录降为引用桩
+  重写 .codebuddy/skills/modus-*/SKILL.md 为仅 1 行 @import，指向 .modus/skills/
+  .claude/, .cursor/, .continue/ 同理
+
+Step 6: HANDOFF schema 升级与路径调整
+  扫描 modus/artifacts/*/code/*.md 中的旧 HANDOFF 块，路径字段调整为 v4 路径
 
 Step 7: 更新 modus/config.yaml
   将 modus_version 更新为 "4.0.0"
@@ -95,20 +107,20 @@ Step 7: 更新 modus/config.yaml
 ✅ Modus v4.0.0 升级完成
 
 迁移内容：
-  ✓ HANDOFF 格式：N 个产物文件已转换为 YAML frontmatter
-  ✓ plan 产物：M 个 plan.md 已补充 v4.0 专用字段
-  ✓ Skill 更新：modus-harness / modus-plan 已更新
-  ✓ 进度事件：modus/sessions/events.jsonl 已初始化
-  ✓ AGENTS.md：已重新生成（若 codex 已启用）
+  ✓ 知识库：N 个业务域拆分为 code/{entities|apis|services|data-models}.md
+  ✓ 产出区：M 个 Story 从 stories/ 迁移到 artifacts/<id>/{pid|design|code|archive}/
+  ✓ 中性命令源：.modus/commands/ + .modus/skills/ 已生成
+  ✓ 平台目录：.codebuddy / .claude / .cursor / .continue 已重写为引用桩
+  ✓ 模板：modus/template/ 生成（6 个产出模板）
 
 备份位置：modus/backup/{YYYYMMDD}-v3.x/
 
-新功能使用方式：
-  设计评审模式：/modus:plan --design [story-url]
-  接力开发：   /modus:plan --continue {name}
-  进度监控：   /modus:harness ... --show-progress
+后续手动步骤：
+  1. 人工检查 modus/knowledge_base/domain/<d>/business/ 并补充业务规则
+  2. 人工检查 modus/knowledge_base/service-graph.md 并修正调用关系
+  3. 运行 /modus:init --enhance-all 验证迁移后知识是否可重生成
 ```
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-upgrade/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-upgrade/SKILL.md` 中的完整流程（中性源；各平台目录为引用桩）。

package/templates/commands/vibe.md

@@ -1,8 +1,10 @@
 # /modus:vibe — 上下文感知编码（氛围编程）
 
-**用途：** 执行日常编码任务前，自动加载相关业务 Skill，让 AI 以「懂项目的开发者」身份工作，而非冷启动。适合 Bug 修复、小功能迭代、代码重构等日常任务。
+**用途：** 执行日常编码任务前，自动加载相关业务知识，让 AI 以「懂项目的开发者」身份工作，而非冷启动。适合 Bug 修复、小功能迭代、代码重构等日常任务。
 
-> Context-aware vibe coding. Intelligently loads relevant business Skills, auto-syncs stale knowledge, and applies rule-driven clarification before coding so AI works as a knowledgeable project member.
+> **路径范式版本：v4.0**（详见 `templates/paths-v4.md`）
+>
+> Context-aware vibe coding. Intelligently loads relevant domain knowledge, auto-syncs stale knowledge, and applies rule-driven clarification before coding so AI works as a knowledgeable project member.
 
 ## 参数说明
 
@@ -10,7 +12,7 @@
 /modus:vibe [需求描述] [参数]
 
   --help                    显示完整帮助（中文）
-  --domain <name>           强制加载指定业务域（跳过自动匹配，如 --domain biz-track）
+  --domain <name>           强制加载指定业务域（跳过自动匹配，如 --domain track）
   --project <name>          指定项目（多项目 workspace 使用）
   --context <file>          额外加载指定文件作为上下文（相对路径）
   --no-skill                跳过 Skill 加载，直接用原始代码上下文（不推荐）
@@ -21,15 +23,15 @@
 ## 执行流程（概览）
 
 1. Read `modus/config.yaml` for hard constraints (constitution)
-2. Load `modus/knowledge-catalog.md` (Level 1, ~200 tokens)
+2. Load `modus/knowledge_base/map.md` (Level 1, ~200 tokens)
 3. **Smart Analysis Engine**: auto-match domains (confidence ≥ 85% → auto-confirm, no user input needed), assess task complexity (Simple / Medium / Complex), detect ambiguity
-4. **Conditional Skill Pre-sync** (silent): check if matched Skills are stale via hash; update if needed; show one-line status `[已同步 {domain} 域知识]`
+4. **Conditional Skill Pre-sync** (silent): check if matched domain knowledge is stale via hash; update if needed; show one-line status `[已同步 {domain} 域知识]`
 5. **Rule-driven AskUserQuestion**: check 5 ambiguity rules (R1–R5); skip entirely for clear tasks; ask at most 2 questions when rules are hit
-6. Load matched Skill files as context (Level 2, ~3000 tokens each)
+6. Load matched domain knowledge as context (Level 2, ~500 tokens entry / Level 3 ~800 tokens per sub-file as needed)
 7. **Adaptive Design Brief**: Simple tasks → 3-section inline brief; Medium/Complex → full 9-section brief
-8. Execute the coding task with business context (Level 3 on-demand file reads)
-9. **Buffer new knowledge** (silent): if new knowledge discovered (new enums, pitfalls, rule changes), append to `modus/sessions/pending-knowledge.yaml`; show one-line `[缓冲 {N} 条新知识 → 将在 /modus:commit 时沉淀到 Skill]`; if nothing new, stay silent. **Do NOT write to Skill files directly** — run `/modus:commit` to persist buffered knowledge.
-10. Append session log to `modus/sessions/vibe-log.md`
+8. Execute the coding task with business context (Level 4 on-demand file reads)
+9. **Buffer new knowledge** (silent): if new knowledge discovered (new enums, pitfalls, rule changes), append to `modus/sessions/pending-knowledge.yaml`; show one-line `[缓冲 {N} 条新知识 → 将在 /modus:commit 时沉淀到 Skill]`; if nothing new, stay silent. **Do NOT write to knowledge files directly** — run `/modus:commit` to persist buffered knowledge.
+10. Append session log to `modus/sessions/vibe-log.md` (or `modus/artifacts/{story_id}/code/vibe-log.md` if story-bound)
 
 **Degraded mode** (no business Skills): proceed without domain context, note quality may be lower, show `[降级模式：无业务上下文，建议先运行 /modus:init]`.
 
@@ -38,35 +40,43 @@
 ```
 /modus:vibe 给歌曲列表接口加一个按状态筛选的功能
 /modus:vibe 订单支付回调逻辑有个 NPE，帮我排查
-/modus:vibe --domain biz-track 重构歌曲同步的重试机制
+/modus:vibe --domain track 重构歌曲同步的重试机制
 /modus:vibe --verbose 分析专辑发行流程的性能瓶颈
 /modus:vibe --dry-run 优化版权审核的并发处理
 ```
 
-## 知识加载策略（渐进三级）
+## 知识加载策略（v4.0 渐进四级）
 
 ```
 Level 1（必须，~200 tokens）
-  读 modus/knowledge-catalog.md
+  读 modus/knowledge_base/map.md
   → 了解可用知识域，匹配当前任务相关域
 
-Level 2（按需，~3000 tokens/个）
-  仅读与任务语义匹配的 modus/knowledge/biz-*/SKILL.md
-  → 不相关的域不加载，节省 ~59% token
+Level 2（按需，~500 tokens/域）
+  仅读匹配域的入口：modus/knowledge_base/domain/{d}/code/SKILL.md
+  → 含子文件索引，不预读子文件
 
-Level 3（执行时，无上限）
-  从 Skill 的 key_files 索引按需读取实际代码文件
+Level 3（按需，~800 tokens/文件）
+  按 SKILL.md 索引读取 entities.md / apis.md / services.md / data-models.md
+  → 任务不涉及的子文件不加载
+
+Level 4（执行时，无上限）
+  从知识中的 key_files 索引按需读取实际代码文件
   → 绝不预先全量读取
+
+# 业务规则与场景的特殊加载（按需）
+  modus/knowledge_base/domain/{d}/business/   ← 仅业务约束相关任务
+  modus/knowledge_base/domain/{d}/scenarios/  ← 仅 spec 阶段或测试视角
 ```
 
-## 无业务 Skill 时的兜底
+## 无业务知识时的兜底
 
 ```
-⚠️ 未找到业务知识库！建议先运行：/modus:init
+⚠️ 未找到业务知识库（modus/knowledge_base/）！建议先运行：/modus:init
 A. 现在运行快速初始化
 B. 继续（无业务上下文，结果质量可能降低）
 ```
 
 ## 执行此命令
 
-读取并执行 `.codebuddy/skills/modus-vibe/SKILL.md` 中的完整流程。
+读取并执行 `.modus/skills/modus-vibe/SKILL.md` 中的完整流程（中性源；平台目录如 `.codebuddy/skills/modus-vibe/SKILL.md` 为引用桩）。

package/templates/domain-business-readme.md

@@ -0,0 +1,69 @@
+# {Domain} — 业务规则（人工维护层）
+
+> **路径**：`modus/knowledge_base/domain/{domain}/business/`
+> **作用**：存放**强业务约束**与**领域知识**——这些内容**不能从代码自动提取**，必须由产品/业务/工程师人工沉淀。
+> **特性**：`/modus:init` 不会覆盖本目录；强刷只更新 `code/`。
+
+---
+
+## 文件组织建议
+
+```
+business/
+├── README.md                  # 本文件（入口与索引）
+├── rules-{topic}.md           # 业务规则（如 rules-pricing.md, rules-permission.md）
+├── glossary.md                # 业务术语表
+├── policies.md                # 业务策略（运营规则、风控规则等）
+└── decisions/                 # 关键设计决策记录（ADR）
+    └── ADR-001-xxx.md
+```
+
+---
+
+## 维护规范
+
+1. **谁维护**：业务专家 + 资深工程师，每月至少 review 一次
+2. **何时更新**：
+   - 新需求落地后，提炼出"代码无法表达的业务规则"
+   - 出现一次故障/客诉，且根因是"业务理解不一致"时
+3. **格式要求**：
+   - 每条规则有唯一 ID（如 `R-001`）
+   - 必须给出"为什么"，而不只是"是什么"
+   - 关联 PID/Story ID（便于追溯）
+
+---
+
+## 与其他目录的关系
+
+| 目录 | 关系 |
+|------|------|
+| `../code/` | 代码事实层；本目录是业务理解层 |
+| `../scenarios/` | 测试场景；规则用于校验场景的正确性 |
+| `../history/` | 历史变更；本目录的规则演变会写入 history |
+
+---
+
+## 示例：规则模板
+
+```markdown
+# R-001：合同到期自动失效规则
+
+**业务描述**：合同到期后，关联的所有授权场景自动失效，但已发生的结算保留。
+
+**触发条件**：合同到期日 ≤ 当前日期
+
+**影响范围**：
+- 授权场景：标记 `disabled`
+- 结算流水：保留历史，不再产生新流水
+- 通知：到期前 7 天发送 alert
+
+**业务依据**：合规要求（来自合同法 §X 条）
+
+**关联 Story**：S-12345, S-23456
+
+**最后更新**：2026-05-22 / 张三
+```
+
+---
+
+> **维护提示**：本目录文件由人工创建/维护；`/modus:init` 仅在首次创建 README.md，后续不会覆盖本目录任何内容。

package/templates/domain-code/SKILL.md

@@ -0,0 +1,94 @@
+---
+schema_version: "4.0"
+name: "biz-{domain}"
+domain: "{domain}"
+domain_zh: ""
+stack: ""                 # java | frontend | go | python
+generated_by: "/modus:init"
+generated_at: ""
+last_updated: ""
+content_hash: ""          # 用于防腐校验
+usage_count: 0
+decay_score: 0
+---
+
+# {domain_zh}（{domain}）— 业务域知识入口
+
+> **作用**：本业务域的知识入口，提供摘要 + 索引；详细知识在同目录的 `entities.md` / `apis.md` / `services.md` / `data-models.md`。
+> **维护**：由 `/modus:init` 自动生成；如需手工增强，请在 `business/` 目录维护，**禁止直接编辑本目录**。
+
+---
+
+## 1. 一句话定位
+
+（业务域是干什么的，为谁服务，核心价值）
+
+---
+
+## 2. 子文件索引
+
+| 文件 | 内容 | 何时加载 |
+|------|------|---------|
+| `entities.md` | 核心业务实体（如：合同、艺人、专辑） | 涉及实体 CRUD |
+| `apis.md` | 对外接口清单 | 涉及接口设计/调用 |
+| `services.md` | 内部服务调用 + 跨域调用 | 涉及调用链分析 |
+| `data-models.md` | 数据库表结构 + 主要字段 | 涉及数据迁移/查询 |
+
+---
+
+## 3. 关键实体快览（来自 entities.md）
+
+| 实体 | 中文 | 关键字段 |
+|------|------|---------|
+|  |  |  |
+
+---
+
+## 4. 关键接口快览（来自 apis.md）
+
+| 接口 | 类型 | 用途 |
+|------|------|------|
+|  |  |  |
+
+---
+
+## 5. 与其他域的关系
+
+| 关联域 | 关系 | 接口 |
+|-------|------|------|
+|  | 上游/下游/兄弟 |  |
+
+---
+
+## 6. 业务规则入口（人工维护层）
+
+> 详见 `../business/`。本节只列**最关键的 3-5 条**业务约束。
+
+- ...
+
+---
+
+## 7. 测试场景入口
+
+> 详见 `../scenarios/`。
+
+---
+
+## 8. 历史变更入口
+
+> 详见 `../history/`。
+
+---
+
+## 9. 防腐元信息
+
+```yaml
+content_hash: ""           # 由 init 计算
+last_full_refresh: ""
+last_incremental_update: ""
+related_stories_count: 0   # 关联过的 Story 数
+```
+
+---
+
+> **维护规则**：本文件由 `/modus:init` 强刷重写；手工维护内容请放到 `../business/`。

package/templates/domain-code/apis.md

@@ -0,0 +1,48 @@
+# APIs — {domain} 接口清单
+
+> **路径**：`modus/knowledge_base/domain/{domain}/code/apis.md`
+> **加载时机**：涉及接口设计/调用/契约对齐时
+
+---
+
+## 1. 对外接口（Inbound）
+
+| 接口名 | 类型 | 路径/Topic | 调用方 | 关键参数 | 关键返回 | 关联场景 |
+|-------|------|-----------|-------|---------|---------|---------|
+|  | HTTP/MQ/RPC |  |  |  |  | `../scenarios/` |
+
+---
+
+## 2. 调用下游接口（Outbound）
+
+| 服务 | 接口 | 用途 | 超时 | 重试 | 降级 |
+|------|------|------|------|------|------|
+|  |  |  |  |  |  |
+
+---
+
+## 3. 接口详情
+
+### {APIName}
+
+**契约**：
+
+```yaml
+method: POST
+path: /api/v1/...
+request:
+  body:
+    field1: type
+response:
+  code: int
+  data: object
+  msg: string
+```
+
+**业务规则**：（参见 `../business/{rule}.md`）
+
+**典型场景**：（参见 `../scenarios/{scenario}.md`）
+
+---
+
+> 模板说明：接口数量过多时按"前台接口/后台接口/内部接口/批处理"拆分多文件。

package/templates/domain-code/data-models.md

@@ -0,0 +1,57 @@
+# Data Models — {domain} 数据模型
+
+> **路径**：`modus/knowledge_base/domain/{domain}/code/data-models.md`
+> **加载时机**：涉及数据迁移、复杂查询、字段含义对齐时
+
+---
+
+## 1. 数据库表清单
+
+| 表名 | 用途 | 主键 | 关键索引 | 数据量级 |
+|------|------|------|---------|---------|
+|  |  |  |  |  |
+
+---
+
+## 2. 表详情
+
+### {TableName}
+
+**用途**：
+
+**字段**：
+
+| 字段名 | 类型 | 是否非空 | 含义 | 备注 |
+|-------|------|---------|------|------|
+|  |  |  |  |  |
+
+**索引**：
+
+| 索引名 | 字段 | 类型 | 用途 |
+|-------|------|------|------|
+|  |  | unique/normal |  |
+
+**与实体的映射**：参见 `entities.md` 中的 `{EntityName}`
+
+---
+
+## 3. 数据生命周期
+
+| 表 | 写入触发 | 更新规则 | 归档/删除策略 |
+|----|---------|---------|--------------|
+|  |  |  |  |
+
+---
+
+## 4. 跨表查询关键 SQL
+
+> 仅记录"频繁出现且复杂"的关键查询，方便排障时直接复用。
+
+```sql
+-- 查询说明
+SELECT ...
+```
+
+---
+
+> 模板说明：表数量过多时按"主业务表/扩展表/审计表"拆分多文件。

package/templates/domain-code/entities.md

@@ -0,0 +1,45 @@
+# Entities — {domain} 业务实体
+
+> **路径**：`modus/knowledge_base/domain/{domain}/code/entities.md`
+> **加载时机**：涉及实体 CRUD、字段映射、状态流转时
+> **维护**：`/modus:init` 自动扫描代码生成
+
+---
+
+## 实体清单
+
+| 实体 ID | 中文 | 英文类名 | 数据表 | 所属包/模块 |
+|---------|------|---------|-------|------------|
+|  |  |  |  |  |
+
+---
+
+## 实体详情
+
+### {EntityName}
+
+**用途**：（一句话描述）
+
+**关键字段**：
+
+| 字段 | 类型 | 含义 | 是否必填 | 示例 |
+|------|------|------|---------|------|
+|  |  |  |  |  |
+
+**状态机**（如适用）：
+
+```mermaid
+stateDiagram-v2
+  [*] --> 初始
+  初始 --> 处理中
+  处理中 --> 已完成
+```
+
+**关联关系**：
+
+- 关联实体：（如 1:N、N:N）
+- 外键：
+
+---
+
+> 模板说明：每个实体一个二级标题；如实体过多（>10），考虑按子域拆为多个文件 `entities-<sub>.md`。

package/templates/domain-code/services.md

@@ -0,0 +1,51 @@
+# Services — {domain} 服务调用图
+
+> **路径**：`modus/knowledge_base/domain/{domain}/code/services.md`
+> **加载时机**：涉及调用链分析、跨域协作、依赖梳理时
+> **关联**：与全局 `modus/knowledge_base/service-graph.md` 保持一致
+
+---
+
+## 1. 本域服务清单
+
+| 服务名 | 类型 | 入口 | 主要职责 |
+|-------|------|------|---------|
+|  | Controller/Provider/Job/Listener |  |  |
+
+---
+
+## 2. 域内调用关系
+
+```mermaid
+graph LR
+  S1[ServiceA] --> S2[ServiceB]
+  S1 --> S3[ServiceC]
+```
+
+---
+
+## 3. 跨域调用
+
+| 本域调用方 | 目标域 | 接口 | 用途 |
+|-----------|-------|------|------|
+|  |  |  |  |
+
+---
+
+## 4. 异步调用与事件
+
+| 事件名 | 生产者 | 消费者 | 主题/队列 |
+|-------|-------|-------|----------|
+|  |  |  |  |
+
+---
+
+## 5. 调用约束
+
+- 同步超时：默认 X ms
+- 重试策略：
+- 熔断阈值：
+
+---
+
+> 模板说明：服务调用关系若超过 30 个节点，可拆分为子域文件。