@modus-ai/modus 0.2.4 → 0.2.6

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

@@ -1,29 +1,325 @@
 ---
 name: modus-init
-description: Use this skill when executing /modus:init command to scan the codebase, classify business domains, and generate Business Skill files, team-conventions Skill, tech-wiki Skill, and knowledge-catalog index. Trigger on /modus:init command or when user asks to initialize Modus or build business Skills from scratch.
+description: Use this skill when executing /modus:init command (or /modus:init --help/--enhance/--migrate/--dry-run etc.) to scan the codebase, classify business domains, generate Business Skill files in modus/knowledge/, update knowledge-catalog.md, and sync to multi-platform adapters. Trigger on /modus:init or any of its parameter variants. (Modus v3.2)
 allowed-tools: Read, Write, Glob, Bash
 disable: false
+supported_platforms:
+  claude:
+    status: full       # 全功能支持：SubAgent 并行扫描、多轮访谈、Bash 工具可用
+    notes: "推荐平台。所有步骤均可完整执行，Bash 可直接运行 mvn/npm 命令检测项目结构。"
+  codebuddy:
+    status: full       # 全功能支持
+    notes: "推荐平台。与 Claude 能力对等，Skill 生成格式与 .codebuddy/ 目录结构完全兼容。"
+  cursor:
+    status: partial    # 部分支持：无 SubAgent、无 Bash，Skill 以 .mdc 规则文件输出
+    notes: "Cursor 不支持 SubAgent，init 流程退化为单 Agent 串行执行；Bash 工具不可用，目录扫描依赖 Glob/Read 工具。生成的 Skill 以 .cursor/rules/modus-biz-*.mdc 格式输出，不支持 v3/17节完整格式。"
+    limitations:
+      - "无 SubAgent：5 轮扫描由单 Agent 串行执行，速度较慢"
+      - "无 Bash：无法直接执行构建命令，技术栈检测依赖文件内容推断"
+      - "Skill 格式降级：输出为 .mdc 规则文件，不支持 frontmatter 防腐字段"
+  copilot:
+    status: minimal    # 最小支持：所有内容合并为单文件
+    notes: "GitHub Copilot 仅支持单文件 copilot-instructions.md，init 将核心知识摘要合并输出，不支持分域 Skill 和防腐机制。"
+    limitations:
+      - "所有 Skill 合并为单个 copilot-instructions.md，无法按需加载"
+      - "不支持防腐机制（无 hash/stale 字段）"
+      - "不支持 Harness SubAgent"
 ---
 
 # modus-init
 
-**触发条件：** 用户运行 `/modus:init` 时使用此 Skill。
+**触发条件：** 用户运行 `/modus:init [参数]` 时使用此 Skill。
 
-## 职责
+## 参数参考（完整列表）
 
-分析当前项目代码库，按业务领域分类，为每个业务域生成 Business Skill 文件，同时初始化团队约定 Skill（Layer 0-T）、技术知识 Skill（Layer 1）和知识全景目录索引（`modus/knowledge-catalog.md`），作为后续所有 Modus 命令的知识底座。
+```
+/modus:init [参数]
+
+参数:
+  --help                    显示本帮助文档（中文）
+  --project <name>          指定项目（多项目 workspace 必填，单项目可省略）
+  --enhance <domain>        仅增量更新指定业务域，不重建全部（如 --enhance biz-track）
+  --enhance-all             重建所有业务域 Skill（保留框架 Skill，不影响 _conventions/_tech-wiki）
+  --platform <p1,p2>        仅同步指定平台（claude,cursor,codex,copilot，逗号分隔）
+  --dry-run                 预览将生成/修改的文件清单，不写入磁盘
+  --force                   跳过所有「是否确认」交互，直接执行
+  --no-sync                 跳过多平台同步，仅生成 modus/knowledge/ 下的文件
+  --migrate                 将旧路径 .codebuddy/skills/modus-biz-* 迁移到 modus/knowledge/
+  --verbose                 输出详细扫描过程（文件列表、token 预估、hash 变化）
+  --reset-maturity          重置所有 Skill 的 maturity 为 draft（谨慎使用）
+
+组合示例:
+  /modus:init                          # 全量初始化（首次或大重构后）
+  /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 --enhance biz-album  # 多项目指定
+```
+
+---
+
+## --help 响应模板
+
+当用户运行 `/modus:init --help` 时，输出以下内容：
+
+```
+Modus Init — 业务知识库初始化工具
+版本：3.2.0
+
+用途：
+  扫描项目代码，按业务域分类，生成结构化 Skill 文件，作为后续所有
+  Modus 命令（vibe/plan/spec/harness）的知识底座。
+  支持多项目工作区路由，知识库统一存放于 modus/knowledge/（平台无关）。
+
+语法：
+  /modus:init [参数]
+
+参数：
+  --help                    显示本帮助
+  --project <name>          指定项目（多项目时必须）
+  --enhance <domain>        仅增量更新指定业务域
+  --enhance-all             重建所有业务域 Skill
+  --platform <p1,p2>        仅同步指定平台（claude,cursor,codex,copilot）
+  --dry-run                 预览模式，不写入文件
+  --force                   跳过所有确认提示
+  --no-sync                 跳过多平台同步
+  --migrate                 迁移旧知识路径到 modus/knowledge/
+  --verbose                 显示详细扫描日志
+  --reset-maturity          重置 Skill 成熟度为 draft
+
+知识库路径（v3.1）：
+  modus/knowledge/_conventions/SKILL.md   — Layer 0-T 团队约定
+  modus/knowledge/_tech-wiki/SKILL.md     — Layer 1 技术知识
+  modus/knowledge/biz-*/SKILL.md          — Layer 2 业务域知识（Single Source of Truth）
+
+平台适配文件（引用式，勿直接编辑）：
+  .codebuddy/skills/modus-biz-*/SKILL.md  — CodeBuddy 引用桩
+  .cursor/rules/modus-knowledge.mdc       — Cursor 引用
+  CLAUDE.md（Modus 章节）                  — Claude Code 引用
+  AGENTS.md                               — Codex/OpenCode 引用
+
+相关命令：
+  /modus:vibe    -- 上下文感知编码
+  /modus:plan    -- 功能规划
+  /modus:spec    -- 规范驱动开发
+  /modus:harness -- 全自动交付流程
+  /modus:auto    -- 智能模式推荐
+```
+
+---
+
+## 本文件结构索引（Agent 必读）
+
+> 本文件共分三个区块，请根据当前任务按需加载，避免无效 token 消耗：
+
+| 区块 | 内容 | Agent 读取时机 | 典型使用场景 |
+|------|------|----------------|------------|
+| **区块 A：执行流程**（Step 0-14） | Agent 执行 `/modus:init` 时的完整步骤指令 | **每次执行 `/modus:init` 必须完整读取** | 全新初始化、重新初始化（模式 1-4）、补全新节 |
+| **区块 B：防腐机制总览** | 防腐字段说明、双级 hash 规则、活跃度感知衰减、status 全链路图、同步副本管理规约 | 执行 Step 8 生成 Skill 前必读；执行 `/modus:verify`、`/modus:refresh` 前必读 | hash 不一致处理、status 升降级、副本同步问题排查 |
+| **区块 C：Business Skill 标准格式**（v3/17节模板） | 多语言适配说明 + 生成每个业务 Skill 时的完整格式参考 | 执行 Step 8 时按需读取对应节的格式要求；辅助命令 `/modus:verify`、`/modus:refresh` 执行时读取 | 格式参考、节内容门槛检查、信号词归属判断 |
 
 ---
+<!-- ============================================================ -->
+<!-- 区块 A：执行流程（执行 /modus:init 时完整读取）             -->
+<!-- ============================================================ -->
 
 ## 执行流程
 
-### Step 0：读取项目宪法
+### Step 0：参数解析
+
+**在做任何其他事之前**，解析用户输入的参数：
+
+```
+输入：/modus:init [参数字符串]
+
+解析规则：
+1. 扫描参数字符串，提取所有 --xxx 和 --xxx value 对
+2. 识别特殊参数：
+   --help       → 输出 --help 响应模板，立即结束，不执行后续 Step
+   --dry-run    → 设置 DRY_RUN=true，所有文件写入操作仅打印不执行
+   --force      → 设置 FORCE=true，跳过所有 confirm 交互
+   --migrate    → 设置 MIGRATE_MODE=true，转入迁移流程（Step 1）
+   --enhance X  → 设置 ENHANCE_DOMAIN=X，转入增量更新流程（Step 2）
+   --enhance-all → 设置 ENHANCE_ALL=true，全量重建业务域（保留框架 Skill）
+   --platform X → 设置 TARGET_PLATFORMS=X（逗号分隔）
+   --no-sync    → 设置 NO_SYNC=true，跳过 Step 6 平台同步
+   --verbose    → 设置 VERBOSE=true，详细输出
+   --project X  → 设置 TARGET_PROJECT=X，读取对应项目路径
+   --reset-maturity → 设置 RESET_MATURITY=true
+```
+
+**参数路由决策树：**
+
+```
+检测到 --help?
+  是 → 输出帮助文档，结束
+  
+检测到 --migrate?
+  是 → 跳转到 Step 1（迁移模式）
+  
+检测到 --enhance <domain> 或 --enhance-all?
+  是 → 跳转到 Step 2（增量更新模式）
+  
+以上都无 → 执行标准全量初始化（Step 3 → Step 14）
+```
+
+---
+
+### Step 1：迁移模式（--migrate）
+
+当用户运行 `/modus:init --migrate` 时执行此流程。
+
+**目标：** 将旧路径 `.codebuddy/skills/modus-biz-*` 迁移到 `modus/knowledge/biz-*`
+
+**执行步骤：**
+
+```
+Step 1-1: 扫描现有文件
+  检测 .codebuddy/skills/modus-biz-*/SKILL.md（旧路径）
+  检测 modus/knowledge/biz-*/SKILL.md（新路径，若已存在则提示）
+
+Step 1-2: 展示迁移计划（即使不带 --dry-run 也先展示）
+  迁移计划（共 N 个域）：
+  ┌──────────────────────────────────────────────────┐
+  │ 从：.codebuddy/skills/modus-biz-track/SKILL.md   │
+  │ 到：modus/knowledge/biz-track/SKILL.md           │
+  │ 操作：复制 → 改写原文件为引用桩                    │
+  └──────────────────────────────────────────────────┘
+  (重复 N 次)
+  同时更新：knowledge-catalog.md 路径引用
+  同时更新：CLAUDE.md / AGENTS.md / .cursor/rules/ 中的路径
+
+Step 1-3: 用户确认（--force 时跳过）
+  确认执行迁移？[Y/n]
+
+Step 1-4: 执行迁移
+  对每个业务域：
+  a. mkdir -p modus/knowledge/biz-{domain}/
+  b. 复制完整 SKILL.md 内容到新路径
+  c. 将原 .codebuddy/skills/modus-biz-{domain}/SKILL.md 改写为引用桩：
+     ---
+     name: modus-biz-{domain}
+     modus_ref: "{project}/modus/knowledge/biz-{domain}/SKILL.md"
+     stub: true
+     ---
+     <!-- MODUS_REF: {project}/modus/knowledge/biz-{domain}/SKILL.md -->
+     > 业务知识已迁移至：`{project}/modus/knowledge/biz-{domain}/SKILL.md`
+  d. 对 _conventions 和 _tech-wiki 同理处理
+
+Step 1-5: 更新所有引用文件
+  - knowledge-catalog.md：更新 Skill 文件路径索引
+  - CLAUDE.md：更新 Modus 章节中的知识库路径说明
+  - AGENTS.md：更新知识库入口路径
+  - .cursor/rules/modus-knowledge.mdc（若存在）：更新路径
+
+Step 1-6: 完成回报
+  ✅ 迁移完成
+  已迁移 N 个业务域：
+    biz-track → modus/knowledge/biz-track/SKILL.md ✓
+    ...
+  已更新引用文件：knowledge-catalog.md, CLAUDE.md, AGENTS.md
+```
+
+---
+
+### Step 2：增量更新模式（--enhance <domain> 或 --enhance-all）
+
+**目标：** 仅重建指定域的 Skill，不触动其他域和框架 Skill
+
+```
+Step 2-1: 确定目标域
+  --enhance biz-track    → 目标：modus/knowledge/biz-track/SKILL.md
+  --enhance-all          → 目标：所有 modus/knowledge/biz-*/SKILL.md
+
+Step 2-2: hash 检查（跳过未变化的域）
+  读取当前 Skill frontmatter 中的 last_hash
+  计算对应 key_files 的当前 SHA-1
+  若 hash 相同 → 跳过，输出 "biz-track: 无变化，跳过重建"
+  若 hash 不同 → 继续重建
+
+Step 2-3: 扫描目标域代码
+  深度扫描 key_files 中列出的源文件
+  提取：核心实体变化、业务规则变化、API 契约变化
+
+Step 2-4: 重建 Skill 文件
+  更新 modus/knowledge/biz-{domain}/SKILL.md
+  更新 frontmatter: updated, last_hash, last_referenced
+
+Step 2-5: 同步引用桩（若平台适配文件存在）
+  更新 .codebuddy/skills/modus-biz-{domain}/SKILL.md 引用桩的摘要行
+  
+Step 2-6: 更新 knowledge-catalog.md 的 updated 时间戳
+
+Step 2-7: 完成回报
+  ✅ 增量更新完成
+    biz-track: 已重建（3 处实体变化，1 条新 pitfall）
+    biz-album: 无变化，已跳过
+```
+
+---
+
+### Step 3：读取项目宪法 + 多项目工作区检测 + 重新初始化检查
+
+**多项目工作区检测：**
+
+```
+优先级：
+1. 若用户传入 --project <name>：直接读取 modus-workspace.yaml 中对应项目配置
+2. 若当前工作目录在某项目子目录内：自动检测项目（匹配 modus-workspace.yaml 中 path）
+3. 若都不满足：读取 modus/workspace-catalog.md，展示项目列表让用户选择
+```
+
+扫描 workspace 根目录是否存在 `modus-workspace.yaml`：
+
+- 若**存在**：读取 `workspace_catalog`（新字段）和 `projects` 列表，按上方优先级路由
+- 若**不存在**：检查当前目录是否为单项目（有 `modus/config.yaml` 或 `pom.xml`），若是直接初始化；若检测到多个子项目，**提示用户是否创建 `modus-workspace.yaml`**
+
+**读取项目宪法：**
 
 读取 `modus/config.yaml`（若存在），提取 `constitution` 字段中的硬性约束，作为整个初始化过程的最高优先级约束。
 
-若 `modus/config.yaml` 不存在，将在 Step 9 创建默认配置。
+若 `modus/config.yaml` 不存在，将在 Step 13 创建默认配置。
+
+#### 重新初始化分支检查（Step 3 末尾执行）
+
+在进入 Step 4 之前，检查是否已有业务 Skill（`modus/knowledge/biz-*` 或 `.codebuddy/skills/modus-biz-*`）：
+
+**若发现已存在业务 Skill：**
+
+```
+当前已有以下业务 Skill：
+  modus-biz-order    v1.2.0  [verified]  更新: 2025-11-20  (v2/14节格式)
+  modus-biz-payment  v1.0.0  [draft]     更新: 2025-10-05  (v1/7节格式 → ⚠️ 建议迁移)
+  modus-biz-user     v2.1.0  [proven]    更新: 2025-12-01  (v2/14节格式)
+
+请选择重初始化模式：
+  1. 全量重建        — 全部删除重新生成（会覆盖所有人工标注）
+  2. 仅更新指定域    — 选择哪些域重新扫描
+  3. 新增缺失域      — 只为新发现的域生成 Skill
+  4. 补全新节（推荐）— 保留已有内容，扫描代码补充生成缺失节 ✨
+     v1(7节) → v2(14节)：补全 8-14 节
+     v2(14节) → v3(17节)：补全 15-17 节（业务不变量/词汇表/新人指南）
+```
+
+**各模式执行规则：**
+- **全量重建（模式 1）**：清空业务 Skill 目录，然后从 Step 4 开始全量执行
+- **仅更新指定域（模式 2）**：用户选定域后，对这些域重新执行 Step 5→Step 8；其余域保持不变
+- **新增缺失域（模式 3）**：执行 Step 5 扫描，仅对新发现的域执行 Step 8 生成，已有域跳过
+- **补全新节（模式 4，推荐）**：
+  - 读取已有 Skill 的已有节，**不修改任何已有内容**
+  - 仅追加缺失节（满足域适用性条件的节，不满足则跳过，不填占位符）
+  - 对 v2 → v3 迁移：补充 Section 15（业务不变量）、Section 16（领域词汇表）、Section 17（新人上手指南）
+  - 同步扩展 frontmatter 的 `key_files`（补充优先级 2/3 类文件，上限 20 个）
+  - 更新 `format_version`（v1→v2 或 v2→v3）、`version`（小版本 +1）和 `updated` 日期
+  - 迁移完成后自动触发 Step 9 多平台同步（`--force` 时默认选择「仅新增缺失域」）
 
-### Step 1：扫描已有 AI 工具配置
+无论何种模式，都在最后更新 `modus/knowledge-catalog.md` 的索引信息。
+
+**若未发现已有 Skill：** 继续 Step 4 开始全新初始化流程。
+
+
+### Step 4：扫描已有 AI 工具配置
 
 在扫描业务代码之前，先读取项目中已有的 AI 工具配置文件，将存量规则、上下文和 MCP 配置融入 Modus 知识库，避免重复发明轮子。
 
@@ -43,7 +339,7 @@ disable: false
 | **CodeBuddy** | `.codebuddy/rules/*.mdc` | 项目规则 |
 | **CodeBuddy** | `.codebuddy/settings.json` | MCP 服务器配置 |
 | **Continue.dev** | `.continue/config.json`、`.continue/config.yaml` | 上下文提供者、模型配置 |
-| **OpenCode** | `AGENT.md`、`.claude-internal/AGENT.md` | 项目 Agent 指令 |
+| **OpenCode/Codex** | `AGENTS.md`、`AGENT.md`、`.claude-internal/AGENT.md` | 项目 Agent 指令 |
 
 #### 提取与融合规则
 
@@ -51,29 +347,22 @@ disable: false
 
 1. **项目描述 / 背景**（`context` 字段）
    - 从 `CLAUDE.md` / `AGENTS.md` 的开头段落提取项目一句话描述
-   - 若 `modus/config.yaml` 中 `context` 为空，自动填入（需用户确认）
 
 2. **技术栈信息**（`techStack` 字段）
    - 从 `CLAUDE.md` 中寻找构建命令、框架名称等技术栈线索
-   - 与代码文件检测结果合并，用于 Step 7 的技术知识 Skill
 
-3. **编码规范 / 团队约定**（→ `modus-team-conventions` Skill）
-   - 将各工具中找到的约定规则（命名规范、禁止模式、最佳实践等）汇总
-   - 在 Step 6 生成团队约定 Skill 时，把这些规则作为**基础输入**，标注来源（如 `[来源: .cursor/rules/naming.mdc]`）
-   - 避免重复：如果规则已在其他 Skill 中描述，仅添加引用
+3. **编码规范 / 团队约定**（→ `modus/knowledge/_conventions` Skill）
+   - 将各工具中找到的约定规则汇总，标注来源（如 `[来源: .cursor/rules/naming.mdc]`）
 
 4. **MCP 服务器配置**（→ `modus/config.yaml` `mcpServers` 字段）
-   - 若 `modus init` CLI 已自动检测并写入 `mcpServers`，则跳过
-   - 否则从 `.claude/settings.json` / `.cursor/mcp.json` 提取，写入 `modus/config.yaml`
+   - 从 `.claude/settings.json` / `.cursor/mcp.json` 提取，写入 `modus/config.yaml`
 
 5. **已有自定义命令**（仅记录，不重复生成）
-   - 列出 `.claude/commands/` 中已有的命令名称
-   - 在 `/modus:init` 完成回报中提示用户这些命令已存在
 
 #### 向用户展示扫描结果
 
 ```
-🔍 扫描已有 AI 工具配置...
+扫描已有 AI 工具配置...
 
 ✓ Claude Code — 找到 3 个文件
     CLAUDE.md（项目指令 + 构建命令）
@@ -84,29 +373,69 @@ disable: false
     .cursor/rules/naming.mdc（命名规范）
     .cursor/mcp.json（MCP: tapd）
 
-将把以上规则融入 modus-team-conventions Skill，MCP 配置写入 modus/config.yaml。
-继续？[Y/n]
+将把以上规则融入 modus/knowledge/_conventions/SKILL.md，MCP 配置写入 modus/config.yaml。
+继续？[Y/n]（--force 时自动确认）
 ```
 
-若用户确认，继续 Step 2；若无任何已有配置，直接进入 Step 2。
-
 ---
 
-### Step 2：项目扫描与业务分类（5 轮全量扫描）
+### Step 5：项目扫描与业务分类（5 轮全量扫描）
 
 启动一个「项目分析 SubAgent」，执行以下 **5 轮结构化扫描**（替代原有的简单目录读取）：
 
+#### 扫描前置：读取 scanRules 配置
+
+在开始轮次 1 前，读取 `modus/config.yaml` 中的 `scanRules` 字段（若存在），构建本次扫描的规则集：
+
+```
+scanRules.include_extensions（用户配置）
+  ||（合并）
+默认后缀：[.java, .kt, .py, .ts, .tsx, .js, .go, .rs, .php, .rb, .swift, .scala]
+
+scanRules.exclude_patterns（用户配置）
+  ||（合并）
+默认排除：[target/**, build/**, dist/**, node_modules/**, .idea/**, .vscode/**,
+           generated/**, **/*Generated.java, *.lock, .git/**, .github/**]
+  ||（合并）
+项目根目录 .gitignore / .modus-ignore（若存在）
+
+最终公式：扫描文件 = (include_extensions 匹配) - (exclude_patterns 排除)
+```
+
+若 `scanRules` 不存在，使用全部默认值，不向用户提示。
+若存在用户自定义规则，输出一行说明：`[读取自定义扫描规则：排除 N 个额外路径，包含 M 个扩展名]`
+
 #### 轮次 1：模块发现
 
+**进度输出（轮次开始时）：**
+```
+[1/5 模块发现] 扫描中...
+```
+
 递归枚举项目中所有构建单元：
 - Java/Kotlin：递归发现所有 Maven Module（`pom.xml`）或 Gradle 子项目（`settings.gradle`）
 - Python：发现所有包目录（含 `__init__.py` 或 `pyproject.toml`）
 - 前端：发现所有独立 Node Package（`package.json`）
 
+**进度输出（轮次完成时）：**
+```
+[1/5 模块发现] ✓ 发现 {N} 个构建模块 — {模块名1}, {模块名2}...
+```
+
+**失败回退：** 若无法识别任何构建单元，输出：
+```
+[1/5 模块发现] ⚠️ 未发现标准构建文件（pom.xml/package.json），将以目录结构为单位扫描。
+```
+
 输出：模块列表（含模块名、路径、构建文件路径）
 
 #### 轮次 2：包级清单
 
+**进度输出（轮次开始时）：**
+```
+[2/5 包级清单] 扫描中...（{N} 个模块）
+```
+
 对每个模块，逐包统计：
 - 文件数量
 - 类型分布（`Controller/Facade` / `Service/Manager` / `Mapper/DAO` / `Domain/Entity` / `Enum/Constant` / `DTO/VO` / `Exception/ErrorCode` / `MQ Consumer/Producer` / `XML Mapper` / `@Configuration`）
@@ -125,15 +454,64 @@ disable: false
   ...（全量展示，不截断）
 ```
 
-#### 轮次 3：域语义分析
+**进度输出（轮次完成时）：**
+```
+[2/5 包级清单] ✓ 扫描 {N} 个文件，发现 {M} 个候选域（其中 {K} 个小包候选）
+```
+
+#### 轮次 3：域语义分析（方法签名级）
 
-按命名模式 + 调用链分析推断域归属：
+按**三层递进**推断域归属，对非标准命名（如 `UserModuleV2Manager`、`BizOpportunityFacade`）也能准确识别：
+
+**层 A：包名语义词匹配**（快速初判）
 - 分析包名中的业务语义词（如 `order`、`pay`、`user`）
-- 扫描 Service 类中的方法命名，归纳核心职责
-- 识别 Facade/Controller 入口，确认域的对外暴露点
+- 若包名与已知业务词完全匹配，直接归入对应域（置信度 High）
+
+**层 B：公开方法签名分析**（语义细化）
+- 对 Service/Manager/Facade 类，提取所有 `public` 方法签名：
+  - 方法名（提取语义动词 + 名词，如 `confirmOrder` → 操作=confirm，对象=Order）
+  - 返回类型（List/PageResult/void → 推断是查询/写操作/事件）
+  - 参数中的 DTO/Entity 名称（如 `CreateOrderRequest` → 明确归入 order 域）
+- 从方法语义词聚类推断域：同包内方法名含有同一业务名词 ≥ 3 个 → 确认域归属
+
+**输出格式（增强版，包含代表性方法签名）：**
+
+```
+域识别结果（共 {N} 个域）：
+
+  order（订单域）  [置信度 High]
+    核心方法：createOrder(CreateOrderReq) → OrderVO
+             cancelOrder(Long orderId) → void
+             getOrderDetail(Long orderId) → OrderDetailVO
+             batchConfirmOrder(List<Long>) → BatchResultVO
+             queryOrderPage(OrderPageQuery) → PageResult<OrderVO>
+    → 关键文件：OrderService, OrderManager, OrderMapper
+
+  payment（支付域）  [置信度 Medium — 包名为 pay，方法含 payment/refund/callback]
+    核心方法：initPayment(PaymentInitReq) → PaymentVO
+             handleCallback(PayCallbackReq) → void
+    → 关键文件：PaymentService, PaymentMapper
+```
+
+**层 C：回退策略**（当 A/B 均无法确定时）
+- 若类名含有多个语义域的词（如 `OrderPaymentService`），标记为"待人工确认"的跨域类
+- 若整个包只有 1-2 个文件，标记为"⚠️ 小包候选，建议合并到相近域"
+- 输出候选归属列表，等待轮次 5 跨域依赖分析后再最终确认
+
+**进度输出（在轮次3开始处添加，在输出域清单后标注完成）：**
+```
+[3/5 域语义分析] 分析方法签名中...
+...（域识别结果）...
+[3/5 域语义分析] ✓ 确认 {N} 个域（{M} 个待人工确认）
+```
 
 #### 轮次 4：跨域依赖
 
+**进度输出：**
+```
+[4/5 跨域依赖] 扫描 RPC / MQ 调用链...
+```
+
 扫描 RPC 调用、MQ Topic 订阅/发布，绘制域间依赖关系：
 - `@DubboReference` / `@FeignClient` — 识别跨域 RPC 依赖
 - `eventPublisher.publish()` / `kafkaTemplate.send()` / `rocketMQTemplate.send()` — 识别 MQ 发布
@@ -143,6 +521,11 @@ disable: false
 
 #### 轮次 5：数据库表所有权图谱（新增）
 
+**进度输出：**
+```
+[5/5 表所有权] 扫描 Mapper 文件...
+```
+
 扫描所有 XML Mapper 中的表名 + `@TableName` 注解，构建全局表归属地图：
 
 ```
@@ -161,10 +544,23 @@ disable: false
   → 提示「发现 {N} 个无域归属的表，需人工决策归属：{表名列表}」
 ```
 
-#### 轮次 3 末尾：域置信度评分矩阵（新增）
+**进度输出（5轮全部完成后）：**
+```
+[4/5 跨域依赖] ✓ 绘制 {N} 条依赖关系
+[5/5 表所有权] ✓ 覆盖 {M} 张表，发现 {K} 个共享表
+
+扫描完成 ─────────────────────────────────────────────
+确认域：{N} 个 | 待确认：{M} 个 | 孤立表：{K} 张
+下一步：展示域汇总，等待用户确认（Step 6）
+──────────────────────────────────────────────────────
+```
+
+#### 5 轮扫描完成后：域置信度评分矩阵
 
 完成轮次 1-5 后，对每个候选域执行置信度评分（满分 10 分）：
 
+> **执行时机说明**：置信度评分矩阵依赖全部 5 轮的扫描结果（尤其是轮次 4 的跨域依赖和轮次 5 的表所有权），必须在 5 轮全部完成后执行，而非轮次 3 结束后立即执行。
+
 | 评分维度 | 评分规则 | 说明 |
 |---------|---------|------|
 | ① 包名语义内聚度 | 高=2 / 中=1 / 低=0 | 包名与业务术语匹配度 |
@@ -186,21 +582,21 @@ disable: false
 **扫描结果展示（向用户展示）：**
 
 ```
-我识别到以下业务域，请确认：
+我识别到以下业务域，请确认（将生成到 modus/knowledge/）：
 
-1. order（订单域）— 订单创建、状态流转、查询        [置信度: 9/10 ✅]
+1. biz-order（订单域）— 订单创建、状态流转、查询        [置信度: 9/10 ✅]
    关键文件: OrderController, OrderService, OrderMapper, OrderDomain, OrderStatus(Enum)
    独占表: order_main, order_item（共2个）
    
-2. payment（支付域）— 支付发起、回调、退款          [置信度: 8/10 ✅]
+2. biz-payment（支付域）— 支付发起、回调、退款          [置信度: 8/10 ✅]
    关键文件: PayFacade, PayManager, PayRecordMapper, PayStatus(Enum)
    独占表: payment_record（共1个）
    
-3. user（用户域）— 用户注册、登录、权限             [置信度: 5/10 ⚠️ 请确认]
+3. biz-user（用户域）— 用户注册、登录、权限             [置信度: 5/10 ⚠️ 请确认]
    关键文件: UserController, UserService, AuthManager
    ⚠️ 该域未发现独立 Entity 类（得分偏低），请确认是否独立域？
    
-4. diversion（流量分发）— 流量路由                 [置信度: 2/10 ❌ 需要决策]
+4. biz-diversion（流量分发）— 流量路由                 [置信度: 2/10 ❌ 需要决策]
    ❌ 低置信度：仅 2 个业务类，无 Controller/Facade，无独占表
    建议选择：A) 合并至 user 域  B) 合并至 platform 域  C) 保持独立
 
@@ -233,9 +629,9 @@ disable: false
 
 ---
 
-### Step 3：用户确认 + 置信度门槛 + 小包评估 + 大域保护
+### Step 6：用户确认 + 置信度门槛 + 小包评估 + 大域保护
 
-等待用户确认域列表之前，先执行以下评估：
+等待用户确认域列表之前，先执行以下评估（`--force` 时自动确认）：
 
 #### 3.0 置信度门槛强制执行
 
@@ -297,9 +693,9 @@ disable: false
 
 ---
 
-### Step 4：结构化访谈问卷（隐性知识捕获）
+### Step 7：结构化访谈问卷（隐性知识捕获）
 
-**触发时机：** 用户确认域列表后、Step 5 启动前执行。
+**触发时机：** 用户确认域列表后、Step 8 启动前执行。`--force` 时自动跳过（隐性知识率标为 0%）。
 
 **核心目的：** 代码扫描只能获得「显性结构知识」，此步骤通过动态生成的针对性问题，补全代码中无法推断的**隐性业务知识**（口口相传的规则、历史决策、业务背景）。
 
@@ -350,11 +746,11 @@ disable: false
 所有域问卷回答完成后，统计：
   已回答问题数 / 总问题数 = 隐性知识补全率
   
-  隐性知识补全率 < 60% → 在 Step 10 完成报告中标注 ⚠️，提示「知识库完整度偏低，建议重新运行访谈」
-  隐性知识补全率 ≥ 60% → 正常进入 Step 4
+  隐性知识补全率 < 60% → 在 Step 11 完成报告中标注 ⚠️，提示「知识库完整度偏低，建议重新运行访谈」
+  隐性知识补全率 ≥ 60% → 正常进入 Step 5
 ```
 
-**如无任何知识空白被发现（全量扫描无触发条件）：** 跳过问卷，直接进入 Step 4，输出：
+**如无任何知识空白被发现（全量扫描无触发条件）：** 跳过问卷，直接进入 Step 5，输出：
 
 ```
 ✓ {domain-name} 域扫描完整，未发现知识空白，跳过访谈问卷
@@ -362,20 +758,20 @@ disable: false
 
 ---
 
-### Step 5：生成业务 Skill（Layer 2）—— 并行执行
+### Step 8：生成业务 Skill（Layer 2）—— 并行执行
 
 用户确认后，**同时**为每个业务域启动独立的「Skills Builder SubAgent」（`modus-skill-creator` Skill，模式 A），并行生成所有业务 Skill 文件。各域之间完全独立，无需等待彼此完成。
 
-**目标路径：** `.codebuddy/skills/modus-biz-{domain}/SKILL.md`
+**目标路径（v3.1）：** `modus/knowledge/biz-{domain}/SKILL.md`
 
 **并行调度规则：**
 
 ```
 用户确认域列表后，立即并行启动 N 个 SubAgent：
 
-SubAgent-1 (order域)   ──► 扫描订单全量文件（含Enum/MQ/Config等全10类）──► 生成 modus-biz-order/SKILL.md
-SubAgent-2 (payment域) ──► 扫描支付全量文件（含Enum/MQ/Config等全10类）──► 生成 modus-biz-payment/SKILL.md
-SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config等全10类）──► 生成 modus-biz-user/SKILL.md
+SubAgent-1 (biz-order域)   ──► 扫描订单全量文件（含Enum/MQ/Config等全10类）──► 生成 modus/knowledge/biz-order/SKILL.md
+SubAgent-2 (biz-payment域) ──► 扫描支付全量文件（含Enum/MQ/Config等全10类）──► 生成 modus/knowledge/biz-payment/SKILL.md
+SubAgent-3 (biz-user域)    ──► 扫描用户全量文件（含Enum/MQ/Config等全10类）──► 生成 modus/knowledge/biz-user/SKILL.md
           │                                                                        │
           └──────────────────── 所有 SubAgent 完成 ─────────────────────────────┘
                                            ↓
@@ -386,7 +782,7 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
 
 **每个 SubAgent 的任务（模式 A 标准流程）：**
 
-1. 接收域名称 + **全量文件路径列表**（来自 Step 2 轮次 2/3 的分析结果，含所有 10 类文件）
+1. 接收域名称 + **全量文件路径列表**（来自 Step 5 轮次 2/3 的分析结果，含所有 10 类文件）
 2. 按优先级分三批扫描（**无文件数量上限，全量覆盖**）：
    - **第一批（核心知识，必须完整扫描）**
      - ① Controller/Facade → API 契约、权限注解
@@ -416,7 +812,7 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
   → 在 Skill 末尾标注：「[两段合并扫描: 批次A={N}个 + 批次B={M}个，共 {N+M} 个文件]」
 
 当两段都超限时（超大域 > 200 个文件）：
-  → 按域内子包进一步拆分（如 order-core / order-query / order-settle）
+  → 按域内子包进一步拆分（如 biz-order-core / biz-order-query / biz-order-settle）
   → 提示用户是否手动拆分为多个子域，或接受分段扫描
 ```
 
@@ -429,242 +825,302 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
 **Section 10 跨域依赖回写（所有 SubAgent 完成后，主流程执行）：**
 
 所有并行 SubAgent 完成后，主流程统一执行一轮跨域依赖分析：
-1. 汇总 Step 2 轮次 4 的跨域依赖关系图
+1. 汇总 Step 5 轮次 4 的跨域依赖关系图
 2. 对每个域 Skill 的 Section 10 进行回写，填入上游依赖域和下游被依赖域
 3. 同步更新各 Skill frontmatter 的 `upstream_skills` 和 `downstream_skills` 字段
-4. 执行 upstream/downstream 双向同步（详见 `00-skills-builder` Step 4 扩展算法）
+4. 执行 upstream/downstream 双向同步（详见 `modus-skill-creator`（SubAgent 00）Step 7 扩展算法）
 
-**聚合等待：** 所有 SubAgent 完成后，收集各 SubAgent 的完成状态摘要，在主流程中汇总展示：
+**聚合等待：**
 
 ```
-✓ modus-biz-order   已生成（14节，18个key_files，6条业务规则，5个API，状态机含4个状态）
-✓ modus-biz-payment 已生成（14节，12个key_files，5条业务规则，3个API，⚠️ 共87个文件，已覆盖50个）
-✓ modus-biz-user    已生成（14节，10个key_files，4条业务规则，6个API）
+✓ modus/knowledge/biz-order   已生成（v3/17节，18个key_files，6条业务规则，5个API，状态机含4个状态）
+✓ modus/knowledge/biz-payment 已生成（v3/17节，12个key_files，5条业务规则，3个API，⚠️ 共87个文件，已覆盖50个）
+✓ modus/knowledge/biz-user    已生成（v3/17节，10个key_files，4条业务规则，6个API）
 
 跨域依赖 Section 10 回写完成：
-  order.upstream_skills   = [payment, user]
-  payment.downstream_skills = [order, refund]
+  biz-order.upstream_skills   = [biz-payment, biz-user]
+  biz-payment.downstream_skills = [biz-order, biz-refund]
 ```
 
-### Step 6：多平台同步（Business Skills）
+### Step 8 补充：生成 Business Skill 时必须填写完整 frontmatter（防腐机制核心）
 
-Business Skills 全部生成后，读取 `modus/config.yaml` 的 `platforms` 字段，将每个业务 Skill 同步到其他已选平台。
+在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写以下**完整字段清单**。这些字段是知识防腐机制的核心，缺一不可：
 
-**读取 platforms 配置：**
+#### 一、基础元数据字段（必填）
+- `name`: Skill 唯一标识符（与目录名一致）
+- `description`: 一句话描述，必须包含 `[MODUS:BIZ]` 标记
+- `version`: 语义化版本号（初始 1.0.0）
+- `updated`: 最后更新日期（YYYY-MM-DD）
+- `status`: 成熟度状态（初始 draft）
+- `format_version`: 节结构版本（当前 v3）
+- `stale_after_days`: 过期天数阈值（默认 90）
 
-```bash
-# 检查已选平台
-grep -A5 "^platforms:" modus/config.yaml
-```
+#### 二、防腐机制核心字段（必填，缺少则无法检测代码变更）
+- **`last_referenced`**: 最后引用时间（初始值 = `updated` 日期）
+  - 用途：计算知识衰减，超过 `stale_after_days` 自动降级
+- **`usage_count`**: 使用次数（初始值 = 0）
+  - 用途：成熟度升级判定（draft→verified→proven）
+- **`last_hash`**: 全局 SHA-1（按区块 B 标准算法：对每个文件单独 SHA-1，将「路径:SHA-1」对按文件路径字母序排序后拼接，再整体计算 SHA-1）
+  - 用途：**快速比对**入口——先比对全局 hash，一致则跳过；不一致时展开 `file_hashes` 逐文件比对，精准输出「变更文件清单」
+  - 计算时机：**init 生成 Skill 时即计算并写入**；后续命令引用时重新计算并比对
+  - ⚠️ **所有命令必须使用统一算法**，详见下方「标准 hash 计算算法」区块
+- **`file_hashes`**: 文件级 hash map（`{路径: SHA-1}` 格式，与 `key_files` 中每个文件一一对应）
+  - 用途：全局 hash 不一致时逐文件展开比对，精准定位哪个文件发生了变更，而非笼统标为 stale
+  - 计算时机：与 `last_hash` 同步计算写入；key_files 中每个文件单独计算 SHA-1
+- **`last_verified_by`**: 最后确认人（初始值 = ""，留空）
+  - 用途：记录人工验证信息，升为 verified 时填写
+- **`verified_at`**: 最后验证日期（初始值 = ""，留空）
+  - 用途：记录人工验证时间，由 `/modus:verify` 在升为 verified 时自动写入（YYYY-MM-DD 格式）
+
+#### 三、key_files 填写规则（最多 20 个，用于 hash 检测）
+- 上限 **20 个**文件（覆盖全部 10 类文件类型）
+- 按以下优先级选取（满 20 个时从后往前截断）：
+  - **优先级 1（必选）**：Service、Manager、Mapper/DAO、Domain/Entity
+  - **优先级 2（强烈建议）**：Enum/Constant（状态/类型枚举）、Exception/ErrorCode
+  - **优先级 3（有则加入）**：MQ Consumer/Producer、@Configuration
+- 对每个文件单独计算 SHA-1，按「路径:SHA-1」字母序排序后整体 SHA-1 得到 `last_hash`（禁止内容直接拼接，详见区块 B）
+- 确保 Enum/MQ/ErrorCode/Config 的变化能被 hash 检查感知
+
+#### 四、质量评分字段（必填，用于知识库质量报告）
+- **`domain_confidence`**: 本域的置信度评分（0-10），来自 Step 5 置信度评分矩阵
+- **`invariant_count`**: 生成的业务不变量条目数（Section 15）
+- **`glossary_size`**: 领域词汇表条目数（Section 16）
+- **`hidden_knowledge_rate`**: 隐性知识补全率（0-100，来自 Step 7 访谈问卷）
+- **`contract_version`**: 本域对外暴露接口的当前版本（初始 "1.0"）；接口升级时更新，下游调用域在自己的 Section 10 中记录此版本号
+
+#### 五、跨域依赖字段（由 Section 10 回写阶段自动填入）
+- **`upstream_skills`**: 本域依赖的其他域 Skill 列表
+- **`downstream_skills`**: 依赖本域的其他域 Skill 列表
+- **`stale_cascade`**: 联动失效标记（初始 false）；当任一 upstream_skills 的 hash 变更时自动置为 true
+
+#### 六、外部依赖感知字段（新增，init 自动从 pom.xml/package.json 提取）
+- **`external_deps`**: 本域规范依赖的外部库版本范围（map 格式）
+  - 计算时机：init 生成 Skill 时自动扫描 `pom.xml` 或 `package.json`，提取该域代码中 import 频率最高的第三方库
+  - 格式：`{lib-name}: "semver-range"` — 如 `spring-boot: "~2.7"`、`mybatis-plus: ">=3.5"`
+  - 衰减规则：当 `pom.xml` / `package.json` 中被记录的库发生 **major version 升级**（如 2.x → 3.x）时，自动将本 Skill 降级为 `stale`，并追加注释 `⚠️ 外部依赖 {lib} 升级（{old} → {new}），规范需验证`
+  - 检测时机：`/modus:init`（含 `--lint` 模式）及 `modus update` 执行时
+
+  **自动提取逻辑：** 对每个域，扫描其 `key_files` 中 import 语句，统计来自 `pom.xml` 中 `<dependencies>` 的第三方库（排除 java.*、springframework.*）引用频次，取前 5 个高频库记录版本范围。
+
+  **示例：**
+  ```yaml
+  external_deps:
+    spring-boot: "~2.7"         # 整个项目级别的关键框架
+    mybatis-plus: ">=3.5 <4.0"  # 该域 Mapper 依赖
+    dubbo: "~3.1"               # 该域跨域 RPC 依赖
+  ```
+
+**⛔ 重要提示：** 如果 frontmatter 缺少上述任一防腐字段（特别是 `last_referenced`、`usage_count`、`last_hash`、`file_hashes`、`key_files`），将导致：
+- 无法自动检测代码变更
+- 无法触发 Skill 更新
+- 无法计算知识衰减
+- 防腐机制完全失效
+
+---
+
+### Step 9：多平台同步（Business Skills）
+
+Business Skills（Step 8）全部生成后，读取 `modus/config.yaml` 的 `platforms` 字段（若带 `--no-sync` 则跳过此 Step）。
+
+**核心设计原则：引用式适配（Reference over Copy）**
+
+`modus/knowledge/` 是 Single Source of Truth。各平台适配文件**不复制内容**，只写引用说明。
+
+> **读取 platforms 配置**：使用 Read 工具读取 `modus/config.yaml` 完整内容，解析其中的 `platforms:` 列表。（Bash 环境也可用 `grep -A5 "^platforms:" modus/config.yaml`）
 
 **各平台同步规则（仅处理 codebuddy 以外的平台）：**
 
-#### Claude Code（`.claude/agents/modus-biz-{domain}.md`）
+#### Claude Code（更新 `CLAUDE.md` + 创建 `.claude/agents/modus-biz-{domain}.md`）
 
-对每个业务域，创建 Claude Sub-Agent 定义文件：
+更新 `CLAUDE.md` 的 Modus 章节（若存在则更新，否则追加）：
+
+```markdown
+## Modus 知识库（AI 编码加速框架）v3.1
+
+执行任何涉及业务逻辑的任务时：
+
+1. 先读取 `modus/knowledge-catalog.md` 或 `modus/workspace-catalog.md`（多项目）
+2. 按需加载 `{project}/modus/knowledge/biz-*/SKILL.md` 获取完整业务上下文
+3. **知识库统一在 modus/knowledge/，不要去 .codebuddy/skills/modus-biz-* 读取（已是引用桩）**
+
+可用命令：/modus:init | /modus:vibe | /modus:plan | /modus:spec | /modus:harness | /modus:auto
+```
+
+对每个业务域，创建 Claude Sub-Agent 定义文件（包含 `<!-- modus:meta -->` 机器可读注释）：
 
 ```markdown
 ---
 name: modus-biz-{domain}
-description: Business knowledge for the {domain} domain — {核心职责一句话}
+description: "[MODUS:BIZ] {中文域名}业务知识。完整知识在 {project}/modus/knowledge/biz-{domain}/SKILL.md"
 ---
+<!-- modus:meta
+last_hash: "{从 CodeBuddy 主文件读取的 last_hash 值}"
+status: "{从 CodeBuddy 主文件读取的 status 值}"
+updated: "{从 CodeBuddy 主文件读取的 updated 日期}"
+-->
 
-{.codebuddy/skills/modus-biz-{domain}/SKILL.md 的完整内容}
+<!-- MODUS_REF: {project}/modus/knowledge/biz-{domain}/SKILL.md -->
+**域：** {中文域名} | **成熟度：** {maturity} | **更新：** {date}
+> 完整知识见：`{project}/modus/knowledge/biz-{domain}/SKILL.md`
 ```
 
-#### Cursor（`.cursor/rules/modus-biz-{domain}.mdc`）
+> 注意：`<!-- modus:meta -->` 注释供工具层快速读取核心防腐字段，每次同步时自动从 CodeBuddy 主文件更新，禁止手动修改。
 
-对每个业务域，创建 Cursor 规则文件（带 frontmatter）：
+#### Cursor（更新/创建 `.cursor/rules/modus-knowledge.mdc`）
 
 ```markdown
 ---
-description: "Business rules and conventions for the {domain} domain — {核心职责一句话}"
+description: "[MODUS] 知识库引用规则 — 所有业务知识在 modus/knowledge/"
 alwaysApply: false
 ---
 
-{.codebuddy/skills/modus-biz-{domain}/SKILL.md 的完整内容}
+<!-- MODUS v3.1 知识库路径 -->
+业务知识（Single Source of Truth）：`{project}/modus/knowledge/biz-*/SKILL.md`
+团队约定：`{project}/modus/knowledge/_conventions/SKILL.md`
+技术知识：`{project}/modus/knowledge/_tech-wiki/SKILL.md`
+加载入口：`{project}/modus/knowledge-catalog.md`（~200 tokens）
 ```
 
-#### GitHub Copilot（`.github/copilot-instructions.md`）
+#### OpenAI Codex / OpenCode（`AGENTS.md`）
 
-将每个业务域的 Skill 内容以带标记的段落形式追加或更新（幂等）：
+`AGENTS.md` 由 `modus init` CLI 自动生成和维护（codex 平台），此步骤无需手动写入。
+如需更新业务域引用，调用 `syncBizSkillToCodex` 在 `AGENTS.md` 的业务域索引章节追加条目即可。
 
-```markdown
-<!-- modus:biz-skill:{domain}:start -->
+#### GitHub Copilot（更新 `.github/copilot-instructions.md`）
 
-### Business Skill: {domain}
+在文件中追加/更新 modus 知识库引用段落（幂等，带标记防止重复）。
 
-{.codebuddy/skills/modus-biz-{domain}/SKILL.md 的完整内容}
+#### CodeBuddy（创建引用桩）
 
-<!-- modus:biz-skill:{domain}:end -->
-```
+为每个业务域在 `.codebuddy/skills/modus-biz-{domain}/` 下创建引用桩 SKILL.md（内容见 Step M-4 格式）。
 
-**若文件中已存在对应域的标记段落，替换其内容（不重复追加）。**
+#### 自定义平台（持续同步）
 
-**同步完成输出：**
+扫描 `modus/platforms/*/platform.yaml`，对 `bizSkill.enabled=true` 的自定义平台：
 
 ```
-📡 多平台同步：
-✓ Claude   .claude/agents/modus-biz-order.md
-✓ Claude   .claude/agents/modus-biz-payment.md
-✓ Cursor   .cursor/rules/modus-biz-order.mdc
-✓ Cursor   .cursor/rules/modus-biz-payment.mdc
-✓ Copilot  .github/copilot-instructions.md（已更新 2 个域段落）
+对每个自定义平台 {platformName}：
+  outputPath = platform.yaml 中 bizSkill.outputPath 模板（替换 {domain}、{ext}）
+  body       = platform.yaml 中 bizSkill.wrapper 模板（替换 {domain}、{content}）
+             若 wrapper 未定义，直接写入 Skill 原文
+  写入 outputPath，确保父目录存在
+
+输出：[已同步 {domain} 到自定义平台: {platform1}, {platform2}]
+若无自定义平台：静默跳过
 ```
 
-若 `platforms` 只包含 `codebuddy`（或字段不存在），跳过此步骤。
+> 这一步解决了 `/modus:platform -add` 后的**持续同步痛点**：每次更新业务域知识时，
+> 所有已注册的自定义平台目录都会被自动同步，无需用户手动干预。
 
 ---
 
-### Step 7：生成团队约定 Skill（Layer 0-T）
+### Step 10：生成团队约定 Skill（Layer 0-T）
 
-调用「Skills Builder SubAgent」（模式 E：团队约定初始化）：
+**目标路径（v3.1）：** `modus/knowledge/_conventions/SKILL.md`
 
 从以下来源提取团队规范（**按优先级排列**）：
 
-1. **Step 1 扫描结果**（最高优先级）
-   - 从 `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/` / `.codebuddy/rules/` 提取的编码规范
-   - 每条规则注明来源，例如：`[来源: .cursor/rules/naming.mdc]`
-   - 若同一规则在多个工具中重复，合并为一条并列出所有来源
-
-2. 项目中已有的 `CONTRIBUTING.md`、`.editorconfig`、`checkstyle.xml`、`pmd.xml` 等规范文件
-
+1. **Step 4 扫描结果**（最高优先级）— 各工具中找到的编码规范
+2. 项目中已有的 `CONTRIBUTING.md`、`.editorconfig`、`checkstyle.xml` 等规范文件
 3. `modus/config.yaml` 中的 `constitution.hard_rules`
+4. 代码中高频出现的注解模式
 
-4. 代码中高频出现的注解模式（如 `@Transactional`、`@DistributedLock` 的用法）
-
-生成文件：`.codebuddy/skills/modus-team-conventions/SKILL.md`
-
-**注意：** 若 Step 1 中已有来自其他工具的规则，在 Skill 文件开头添加来源声明：
-```markdown
-> 本 Skill 融合了以下 AI 工具的已有配置：Claude Code (CLAUDE.md)、Cursor (.cursor/rules/)
-> 原始文件保持不变，Modus 仅在此处做统一索引。
-```
+---
 
-### Step 8：生成技术知识 Skill（Layer 1）
 
-调用「Skills Builder SubAgent」（模式 E：技术知识初始化），初始化技术知识骨架：
+### Step 11：生成技术知识 Skill（Layer 1）
 
-生成文件：`.codebuddy/skills/modus-tech-wiki/SKILL.md`
+**目标路径（v3.1）：** `modus/knowledge/_tech-wiki/SKILL.md`
 
 初始内容来源（按优先级）：
-1. **Step 1 扫描结果中的技术信息**
-   - `CLAUDE.md` 中记录的构建命令、测试命令（如 `mvn test`、`npm run test`）
-   - `.continue/config.json` 中的模型/上下文提供者配置
-2. 从构建文件提取的技术栈（`pom.xml` → Spring Boot 版本、`package.json` → 框架版本等）
-3. 占位符章节（反模式库、架构决策、跨项目经验——待后续工作流积累）
+1. Step 4 扫描结果中的技术信息
+2. 从构建文件提取的技术栈（`pom.xml` → Spring Boot 版本等）
+3. 占位符章节（反模式库、架构决策——待后续工作流积累）
 
-### Step 9：生成知识全景目录（knowledge-catalog.md）
+---
 
-在 `modus/knowledge-catalog.md` 创建全景索引，使用升级后的条目格式：
+### Step 12：生成知识全景目录（knowledge-catalog.md）
 
-```markdown
-# Modus 知识全景目录
-# 所有 Modus 命令启动时先读此文件（~200 tokens），按需加载完整 Skill
+在 `modus/knowledge-catalog.md`（项目级）创建全景索引。
 
-updated: {YYYY-MM-DD}
+> **单一真相来源**：目录结构、层级定义、字段格式以 `modus/templates/knowledge-catalog.md` 模板文件为准，本 Step 不再内嵌重复结构。执行时读取该模板文件并按以下规则替换占位符后写入目标路径。
 
-## 团队约定 (Layer 0-T)
-- **modus-team-conventions**: 代码规范/提交规范/最佳实践
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}
+**路径说明（v3.1 格式）：**
+- Layer 0-T 路径：`{project}/modus/knowledge/_conventions/SKILL.md`
+- Layer 1 路径：`{project}/modus/knowledge/_tech-wiki/SKILL.md`
+- Layer 2 路径：`{project}/modus/knowledge/biz-{domain}/SKILL.md`
 
-## 技术知识 (Layer 1)
-- **modus-tech-wiki**: 跨项目技术经验（反模式、架构决策、性能优化）
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}
+**操作步骤：**
+1. 读取 `{MODUS_PACKAGE}/templates/knowledge-catalog.md`（安装包模板）
+2. 将 Layer 2 的 `{domain}` 条目替换为 Step 5/6/7 扫描到的实际业务域列表，每域一行
+3. 完成以下占位符替换：
 
-## 业务知识 (Layer 2)
-- **modus-biz-order**: 订单域 — 创建/状态流转/查询
-  [status: draft] [format: v2/14节] [upstream: payment, user]
-  更新: {日期}  hash: {初始hash}
-- **modus-biz-payment**: 支付域 — 发起/回调/退款
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}  hash: {初始hash}
-- **modus-biz-user**: 用户域 — 注册/登录/权限
-  [status: draft] [format: v2/14节] [upstream: -]
-  更新: {日期}  hash: {初始hash}
+**写入前必须完成的字段替换（断言，不可遗漏）：**
+- `{YYYY-MM-DD}` → 实际执行日期（如 `2026-05-06`）
+- `{日期}` → 实际执行日期
+- `{domain}` → 扫描到的实际域名（如 `biz-order`、`biz-payment`、`biz-user`）；每个域生成独立条目
+- `{中文域名}` → 对应域的中文名称（如 `订单`、`支付`、`用户`）
+- `{核心职责一句话}` → 对应域的简短职责描述
+- `{依赖域列表，无则写-}` → upstream_skills 依赖关系（Step 5 扫描结果）
+- `{last_hash 前8位}` → 运行 hash 计算后的实际值前 8 位；若无法计算，写入 `⚠️ PENDING` 并在知识目录顶部说明原因
+- `{待填入}` → 域依赖图（从 upstream 字段推导：biz-payment --> biz-order 等）
+- 写入后执行自检：`grep -n '{' modus/knowledge-catalog.md | grep -v '<!--'` 输出应为空（注释中的占位符示例不算）
 
-## 使用说明
-Skill status 生命周期（统一使用 status 字段）：
-- draft    → 初始生成，未经验证
-- verified → 经至少1名开发者在真实需求中验证，且无知识缺失反馈（运行 /modus:verify 升级）
-- proven   → 经≥2个不同工作流验证有效
-- stale    → hash 不匹配或超过 stale_after_days，需更新（禁止直接引用）
-- archived → 域已废弃，不再维护
+同时更新工作区顶层的 `modus/workspace-catalog.md`（若存在）中的项目更新时间。
 
-衰减规则：
-- proven  + 超过 12 个月未引用 → verified
-- verified + 超过 6 个月未引用 → stale（保留人工标注痕迹，非降为 draft）
-- stale   + 超过 stale_after_days → archived（需人工二次确认）
-```
+---
 
-### Step 10：初始化 modus/config.yaml（若不存在）
+### Step 13：初始化 modus/config.yaml（若不存在）
 
-若项目尚无 `modus/config.yaml`，生成默认配置：
+若项目尚无 `modus/config.yaml`，生成默认配置（参见模板），提示用户填写 `constitution` 字段。
 
-```yaml
-# Modus 项目配置
+---
 
-# TAPD 项目 ID（可选，用于 Harness 自动创建 Bug 单）
-tapdProjectId: ""
+### Step 14：完成回报
 
-# Harness 流程配置
-harness:
-  buildCommand: "mvn clean compile -q"
-  environments: [dev, test, pre]
+所有文件生成完毕后，回复用户：
 
-# 项目宪法（所有 SubAgent 必须遵守的硬性约束）
-# 这些约束在每次命令执行时自动加载，无需重复说明
-constitution:
-  tech_stack: ""              # 如 "Java 17 + Spring Boot 3 + MyBatis"
-  test_command: ""            # 如 "mvn test -pl {module}"
-  hard_rules: []              # 如 ["Mapper 接口必须在 dao 包下", "金额使用 Long 单位分"]
-  build_command: ""           # 如 "mvn clean compile -q"
-  key_patterns: []            # 项目特有的技术模式描述
 ```
+✅ Modus 知识库初始化完成（v3.2）
 
-提示用户填写 `constitution` 字段，以便后续命令无需重复说明项目约束。
-
-### Step 11：完成回报
-
-所有业务 Skill 生成完毕后，回复用户：
-
-```
-✅ Modus 知识库初始化完成
+知识库路径（Single Source of Truth）：
+  modus/knowledge/_conventions/SKILL.md  (Layer 0-T) [draft]
+  modus/knowledge/_tech-wiki/SKILL.md    (Layer 1)   [draft]
+  modus/knowledge/biz-*/SKILL.md         (Layer 2)   [draft] × N 个域
 
 已融合的已有 AI 工具配置（若有）：
-  Claude Code  — CLAUDE.md + .claude/rules/ (3 条规则已写入 modus-team-conventions)
-  Cursor       — .cursor/rules/ (2 条规则已写入 modus-team-conventions)
-  MCP 服务器   — tapd (来自 .claude/settings.json) 已写入 modus/config.yaml
+  Claude Code  — CLAUDE.md + .claude/rules/ (M 条规则融入 _conventions)
+  Cursor       — .cursor/rules/ (K 条规则融入 _conventions)
 
 生成了 N 个业务 Skill（Layer 2）：
-- .codebuddy/skills/modus-biz-order/SKILL.md    [draft] [v3/17节]
-- .codebuddy/skills/modus-biz-payment/SKILL.md  [draft] [v3/17节]
+- modus/knowledge/biz-order/SKILL.md    [draft] [v3/17节]
+- modus/knowledge/biz-payment/SKILL.md  [draft] [v3/17节]
 - ...
 
-多平台同步（来自 modus/config.yaml platforms 配置）：
-- Claude Code  → .claude/agents/modus-biz-*.md（N 个域）
-- Cursor       → .cursor/rules/modus-biz-*.mdc（N 个域）
-- Copilot      → .github/copilot-instructions.md（N 个域段落）
+多平台同步（引用式适配，来自 modus/config.yaml platforms 配置）：
+  Claude   → CLAUDE.md 更新 + .claude/agents/modus-biz-*.md（N 个）
+  Cursor   → .cursor/rules/modus-knowledge.mdc（路径引用）
+  Codex    → AGENTS.md（由 modus init CLI 生成，此处追加业务域索引条目）
+  Copilot  → .github/copilot-instructions.md（N 个域段落）
+  CodeBuddy → .codebuddy/skills/modus-biz-*/SKILL.md（N 个引用桩）
 
 初始化基础 Skill：
-- .codebuddy/skills/modus-team-conventions/SKILL.md  (Layer 0-T) [draft]
-  └─ 融合来源：CLAUDE.md, .cursor/rules/, CONTRIBUTING.md, 代码注解模式
-- .codebuddy/skills/modus-tech-wiki/SKILL.md          (Layer 1)   [draft]
+  modus/knowledge/_conventions/SKILL.md  (Layer 0-T) [draft]
+    └─ 融合来源：CLAUDE.md, .cursor/rules/, CONTRIBUTING.md, 代码注解模式
+  modus/knowledge/_tech-wiki/SKILL.md    (Layer 1)   [draft]
 
 知识目录：
-- modus/knowledge-catalog.md（所有命令的快速索引，~200 tokens）
+  modus/knowledge-catalog.md（所有命令的快速索引，~200 tokens）
 
 📊 知识库质量评分报告：
 ┌─────────────────┬──────┬──────┬──────┬──────┬──────┬──────────┐
 │ 域名            │置信度│规则数│状态机│API完备│不变量│隐性知识率│
 ├─────────────────┼──────┼──────┼──────┼──────┼──────┼──────────┤
-│ modus-biz-order │ 9/10 │  8条 │ 100% │ 100% │  3条 │   80%    │
-│ modus-biz-payment│ 8/10 │  5条 │ 100% │  80% │  2条 │   60%    │
-│ modus-biz-user  │ 5/10 │  4条 │  -   │  90% │  1条 │   40% ⚠️ │
+│ biz-order       │ 9/10 │  8条 │ 100% │ 100% │  3条 │   80%    │
+│ biz-payment     │ 8/10 │  5条 │ 100% │  80% │  2条 │   60%    │
+│ biz-user        │ 5/10 │  4条 │  -   │  90% │  1条 │   40% ⚠️ │
 └─────────────────┴──────┴──────┴──────┴──────┴──────┴──────────┘
-⚠️ modus-biz-user 隐性知识补全率 40%（低于 60% 阈值），建议补充访谈。
+⚠️ biz-user 隐性知识补全率 40%（低于 60% 阈值），建议补充访谈。
 
 💡 建议：填写 modus/config.yaml 中的 constitution 字段，
    记录项目硬性约束（技术栈、命名规范等），后续所有命令将自动加载。
@@ -674,104 +1130,254 @@ constitution:
 
 现在可以使用：
   /modus:vibe     — 氛围编程（自动加载业务上下文）
-  /modus:plan     — 功能规划
+  /modus:plan     — 功能规划（可带 --story <tapd-url>）
   /modus:spec     — 规范驱动开发
-  /modus:harness  — 全自动 Harness 流程
+  /modus:harness [tapd-url] — 全自动 Harness 流程
+  /modus:auto [tapd-url]    — 智能推荐模式
   /modus:verify   — 升级 Skill 状态（draft → verified）
 ```
 
 ---
+<!-- ============================================================ -->
+<!-- 区块 B：防腐机制总览（执行 Step 5 / verify / refresh 时读取）-->
+<!-- ============================================================ -->
+
+## 防腐机制总览（Skill Anti-corruption Reference）
+
+> 本章节是防腐机制的**唯一权威来源**。`knowledge-catalog.md`、`modus-init-flow.md` 等其他文档如有冲突，以本章节为准。
+
+**重新初始化逻辑（已有 Skill 时）：**
+
+如果 `modus/knowledge/biz-*` 下已存在业务 Skill：
+
+1. 展示已有域列表及 status、最后更新时间
+2. 询问：全量重建 / 仅更新指定域（`--enhance`）/ 新增缺失域
+3. 按用户选择执行（`--force` 时默认选择「仅新增缺失域」）
+4. 无论何种选择，都更新 `modus/knowledge-catalog.md` 的时间戳
+
+### 防腐机制全链路图
+
+```mermaid
+flowchart TD
+    CMD["Modus 命令加载 Skill\n(vibe/plan/spec/harness)"]
+    CMD --> HASH1["第一步：全局 hash 快速比对\n重算 key_files 拼接 SHA-1"]
+
+    HASH1 -->|"全局 hash 一致"| DECAY["衰减检查\n(基于 last_referenced + usage_count)"]
+    HASH1 -->|"全局 hash 不一致"| HASH2["第二步：file_hashes 逐文件比对\n输出变更文件清单"]
 
-## 重新初始化（已有 Skill 时）
+    HASH2 --> STALE_H["status → stale\n警告：列出具体变更文件"]
+    STALE_H -->|"用户确认继续"| USE["使用当前 Skill（可能过时）"]
+    STALE_H -->|"运行 /modus:refresh"| REFRESH["增量更新 Skill\nstatus → draft"]
 
-如果 `.codebuddy/skills/` 下已存在 `modus-biz-*` 目录：
+    DECAY --> ACTIVE{"活跃度判断\n(usage_count)"}
+    ACTIVE -->|"≥10 活跃域"| THRESH_A["衰减阈值\nverified→stale: 12个月\nproven→verified: 24个月"]
+    ACTIVE -->|"3-9 正常域"| THRESH_N["衰减阈值\nverified→stale: 6个月\nproven→verified: 12个月"]
+    ACTIVE -->|"≤2 冷门域"| THRESH_C["衰减阈值\nverified→stale: 3个月\nproven→verified: 6个月"]
 
-提示用户当前已有哪些业务 Skill 及其最后更新时间、status 和 format_version：
+    THRESH_A --> DECAY_CHECK{"距 last_referenced\n是否超过阈值？"}
+    THRESH_N --> DECAY_CHECK
+    THRESH_C --> DECAY_CHECK
 
+    DECAY_CHECK -->|"未超过"| VALID["Skill 有效\n更新 last_referenced = 今日"]
+    DECAY_CHECK -->|"已超过"| STALE_D["status 自动降级\nproven→verified 或 verified→stale"]
+
+    VALID --> USE
+
+    subgraph lifecycle [Status 生命周期]
+        direction LR
+        DRAFT["draft\n初始/刷新后"]
+        VERIFIED["verified\n真实使用验证"]
+        PROVEN["proven\n≥2个工作流验证"]
+        STALE_S["stale\nhash不匹配或衰减超期"]
+        ARCHIVED["archived\n废弃（需人工确认）"]
+
+        DRAFT -->|"/modus:verify\n满足对应门槛"| VERIFIED
+        VERIFIED -->|"usage_count≥2\n不同工作流"| PROVEN
+        PROVEN -.->|"超过衰减阈值"| VERIFIED
+        VERIFIED -.->|"超过衰减阈值"| STALE_S
+        STALE_S -->|"/modus:refresh"| DRAFT
+        STALE_S -.->|"超过stale_after_days"| ARCHIVED
+    end
 ```
-当前已有以下业务 Skill：
-  modus-biz-order    v1.2.0  [verified]  更新: 2025-11-20  (v2/14节格式)
-  modus-biz-payment  v1.0.0  [draft]     更新: 2025-10-05  (v1/7节格式 → ⚠️ 建议迁移)
-  modus-biz-user     v2.1.0  [proven]    更新: 2025-12-01  (v2/14节格式)
 
-请选择重初始化模式：
-  1. 全量重建        — 全部删除重新生成（会覆盖所有人工标注）
-  2. 仅更新指定域    — 选择哪些域重新扫描
-  3. 新增缺失域      — 只为新发现的域生成 Skill
-  4. 补全新节（推荐）— 保留已有内容，扫描代码补充生成缺失节 ✨
-     v1(7节) → v2(14节)：补全 8-14 节
-     v2(14节) → v3(17节)：补全 15-17 节（业务不变量/词汇表/新人指南）
+### 防腐字段说明
+
+每个 Business Skill frontmatter 必须包含以下防腐字段：
+
+| 字段 | 类型 | 初始值 | 用途 |
+|------|------|--------|------|
+| `last_referenced` | date (YYYY-MM-DD) | = `updated` 日期 | 计算知识衰减；每次被 vibe/plan/spec/harness 引用时更新为当日 |
+| `usage_count` | integer | 0 | 成熟度升级判定；每次成功引用完成开发任务后 +1 |
+| `last_hash` | string (SHA-1) | 生成时计算的真实全局 hash | 快速检测是否有变更；不一致时展开 `file_hashes` 逐文件比对 |
+| `file_hashes` | map[path→SHA-1] | `{}` (空 map) | 文件级 hash 映射；全局 hash 不一致时使用，精准输出「变更文件清单」 |
+| `key_files` | list | 按优先级选取的源文件路径 | hash 计算的输入；最多 20 个，覆盖全部 10 类文件 |
+| `last_verified_by` | string | "" (空) | 记录最后人工验证人；升为 verified 时填写 |
+
+### Status 生命周期
+
 ```
+draft → verified → proven
+             ↑         |  (超过阈值未引用，见下表)
+             └─────────┘
 
-**选择「补全新节」时的执行规则：**
-- 读取已有 Skill 的已有节，**不修改任何已有内容**
-- 仅追加缺失节（满足域适用性条件的节，不满足则跳过，不填占位符）
-- 对 v2 → v3 迁移：补充 Section 15（业务不变量）、Section 16（领域词汇表）、Section 17（新人上手指南）
-- 同步扩展 frontmatter 的 `key_files`（补充优先级 2/3 类文件，上限 20 个）
-- 更新 `format_version`（v1→v2 或 v2→v3）、`version`（小版本 +1）和 `updated` 日期
+verified + 超过阈值未引用 → stale（阈值按 usage_count 分 3/6/12 个月，见下表）
+stale   + 超过 stale_after_days 天 → archived（需人工二次确认）
+```
 
-**迁移完成后：** 自动触发 Step 5 多平台同步逻辑（更新 Claude Code、Cursor、Copilot 对应文件）
+> 以下表格为权威衰减阈值定义，ASCII 图仅示意流向；
 
-无论何种选择，都更新 `modus/knowledge-catalog.md` 的索引信息。
+| status | 含义 | 升级条件 | 禁止行为 |
+|--------|------|---------|---------|
+| `draft` | 初始生成，未经验证 | 运行 `/modus:verify` 且满足四项条件 → `verified` | - |
+| `verified` | 经至少 1 次真实使用验证 | `usage_count ≥ 2` 且不同工作流 → `proven` | - |
+| `proven` | 经 ≥2 个不同工作流验证 | - | - |
+| `stale` | hash 不匹配或衰减超期 | 运行 `/modus:refresh` 更新后 → `draft` | **禁止直接引用** |
+| `archived` | 域已废弃 | - | **禁止引用** |
 
----
+### 衰减规则（活跃度感知，基于 last_referenced + usage_count）
 
-### Step 5 补充：生成 Business Skill 时必须填写完整 frontmatter（防腐机制核心）
+衰减阈值根据 `usage_count` 动态调整，高频使用的域享有更长保鲜期：
 
-在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写以下**完整字段清单**。这些字段是知识防腐机制的核心，缺一不可：
+| 活跃度 | usage_count | verified → stale 阈值 | proven → verified 阈值 |
+|--------|------------|----------------------|----------------------|
+| 活跃域 | ≥ 10       | **12 个月**            | **24 个月**            |
+| 正常域 | 3-9        | **6 个月**（默认）        | **12 个月**（默认）       |
+| 冷门域 | ≤ 2        | **3 个月**             | **6 个月**             |
 
-#### 一、基础元数据字段（必填）
-- `name`: Skill 唯一标识符（与目录名一致）
-- `description`: 一句话描述，必须包含 `[MODUS:BIZ]` 标记
-- `version`: 语义化版本号（初始 1.0.0）
-- `updated`: 最后更新日期（YYYY-MM-DD）
-- `status`: 成熟度状态（初始 draft）
-- `format_version`: 节结构版本（当前 v3）
-- `stale_after_days`: 过期天数阈值（默认 90）
+- `proven` + 距 `last_referenced` 超过阈值（见表）→ 自动降为 `verified`
+- `verified` + 距 `last_referenced` 超过阈值（见表）→ 自动降为 `stale`（保留人工标注痕迹，不降回 `draft`）
+- `stale` + 距 `last_referenced` 超过 `stale_after_days`（默认 90 天）→ 建议降为 `archived`（需人工确认）
 
-#### 二、防腐机制核心字段（必填，缺少则无法检测代码变更）
-- **`last_referenced`**: 最后引用时间（初始值 = `updated` 日期）
-  - 用途：计算知识衰减，超过 `stale_after_days` 自动降级
-- **`usage_count`**: 使用次数（初始值 = 0）
-  - 用途：成熟度升级判定（draft→verified→proven）
-- **`last_hash`**: key_files 内容 SHA-1 哈希值（初始值 = ""，留空）
-  - 用途：检测代码变更，触发 Skill 更新
-  - 计算时机：首次被 plan/spec/harness 引用时自动计算并写入
-- **`last_verified_by`**: 最后确认人（初始值 = ""，留空）
-  - 用途：记录人工验证信息，升为 verified 时填写
+> **说明**：活跃度分级在每次 Modus 命令加载 Skill 时实时判断，无需手动维护。
 
-#### 三、key_files 填写规则（最多 20 个，用于 hash 检测）
-- 上限 **20 个**文件（覆盖全部 10 类文件类型）
-- 按以下优先级选取（满 20 个时从后往前截断）：
-  - **优先级 1（必选）**：Service、Manager、Mapper/DAO、Domain/Entity
-  - **优先级 2（强烈建议）**：Enum/Constant（状态/类型枚举）、Exception/ErrorCode
-  - **优先级 3（有则加入）**：MQ Consumer/Producer、@Configuration
-- 这些文件的内容拼接后计算 SHA-1 得到 `last_hash`
-- 确保 Enum/MQ/ErrorCode/Config 的变化能被 hash 检查感知
+### hash 检测触发时机
 
-#### 四、质量评分字段（必填，用于知识库质量报告）
-- **`domain_confidence`**: 本域的置信度评分（0-10），来自 Step 2 置信度评分矩阵
-- **`invariant_count`**: 生成的业务不变量条目数（Section 15）
-- **`glossary_size`**: 领域词汇表条目数（Section 16）
-- **`hidden_knowledge_rate`**: 隐性知识补全率（0-100，来自 Step 4 访谈问卷）
+每次 Modus 命令（`/modus:vibe`、`/modus:plan`、`/modus:spec`、`/modus:harness`）加载某域 Skill 时：
 
-#### 五、跨域依赖字段（由 Section 10 回写阶段自动填入）
-- **`upstream_skills`**: 本域依赖的其他域 Skill 列表
-- **`downstream_skills`**: 依赖本域的其他域 Skill 列表
+> **标准 hash 计算算法（所有命令必须统一使用）：**
+> 1. 对 key_files 中每个文件**单独**计算 SHA-1（用于 `file_hashes` 逐文件比对）
+> 2. 将「文件路径:SHA-1」对按**文件路径字母序排序**后拼接成字符串，再整体计算一次 SHA-1，得到 `last_hash`
+>
+> ```bash
+> # 标准全局 hash 计算命令（顺序无关，与 file_hashes 完全兼容）
+> for f in $(echo "{key_files}" | tr ' ' '\n' | sort); do
+>   echo "$(shasum -a 1 "$f" | awk '{print $1}'):$f"
+> done | shasum -a 1 | awk '{print $1}'
+> ```
+>
+> **禁止使用「内容拼接后整体计算」的方式**（受文件顺序影响，且无法与 file_hashes 兼容）。
 
-**重要提示：** 如果 frontmatter 缺少上述任一防腐字段（特别是 `last_referenced`、`usage_count`、`last_hash`、`key_files`），将导致：
-- 无法自动检测代码变更
-- 无法触发 Skill 更新
-- 无法计算知识衰减
-- 防腐机制完全失效
+```
+1. 读取 Skill frontmatter 中的 last_hash、file_hashes 和 key_files
+
+2. 【第一步：全局快速比对】
+   按上方标准算法重新计算全局 SHA-1，与 last_hash 比对：
+   ├── 一致 → Skill 有效，正常使用，更新 last_referenced 为今日
+   └── 不一致 → 进入第二步（逐文件比对）
+
+3. 【第二步：文件级精准比对】（仅在全局 hash 不一致时执行）
+   逐文件重新计算 SHA-1，与 file_hashes 中对应值比对，输出变更清单：
+   ⚠️ modus-biz-{domain} 检测到代码变更（{N} 个文件）：
+     ✗ src/.../OrderService.java   — 已变更（业务规则/状态机可能过期）
+     ✗ src/.../OrderStatus.java    — 已变更（枚举值可能新增/修改）
+     ✓ src/.../OrderMapper.java    — 无变更
+   建议运行 /modus:refresh {domain} 增量更新 Skill
+   继续使用当前 Skill（内容可能过时）？[y/N]
+
+   → 将 status 降为 stale，更新 last_referenced 为今日
+```
 
+### 同步副本管理规约
+
+> 本节规定多平台同步副本（Claude Agent 文件、Cursor 规则等）的防腐字段处理标准，所有平台同步操作均须遵守。
+
+#### 双重 frontmatter 的结构问题
+
+通过 Step 6 多平台同步生成的 Claude Agent 文件（`.claude/agents/modus-biz-{domain}.md`）采用**双重 frontmatter 格式**：
+
+```markdown
+---
+name: modus-biz-{domain}          ← Claude Agent 顶层 frontmatter（Claude 平台解析）
+description: ...
+---
+
+---
+name: modus-biz-{domain}          ← Skill frontmatter（被解析为 Markdown 正文，非顶层 YAML）
+last_hash: "xxx"
+last_referenced: ...
+...
 ---
 
-## Business Skill 标准格式参考（v3/17节）
+# 业务知识正文 ...
+```
+
+**结构约束**：防腐字段（`last_hash`、`file_hashes`、`last_referenced`、`usage_count` 等）在 Claude Agent 文件中位于正文区，**无法被标准 YAML 解析器从顶层 frontmatter 中读取**。
+
+#### 机器可读 meta 注释（供工具层解析）
+
+为使工具层能从 Claude Agent 文件中快速读取核心防腐字段，**每个 Claude Agent 文件的顶层 frontmatter 之后、第二个 frontmatter 之前**，插入一段 HTML 注释：
 
 ```markdown
 ---
 name: modus-biz-{domain}
+description: ...
+---
+<!-- modus:meta
+last_hash: "{last_hash_value}"
+status: "{status_value}"
+updated: "{updated_date}"
+-->
+
+---
+name: modus-biz-{domain}
+...
+```
+
+**规则**：
+- `<!-- modus:meta ... -->` 注释在每次 Step 6 同步时自动从 CodeBuddy 主文件写入
+- 工具层优先读取此注释，不解析第二层 frontmatter
+- 注释内容与 CodeBuddy 主文件保持严格一致，不允许手动修改
+
+#### 权威源与副本的责任边界
+
+| 文件 | 角色 | 防腐字段权威性 | 更新方式 |
+|------|------|-------------|---------|
+| `modus/knowledge/biz-{domain}/SKILL.md` | **权威源** | 所有防腐字段的唯一权威存储 | 命令直接写入 |
+| `.claude/agents/modus-biz-{domain}.md` | 只读快照 | 仅通过 `<!-- modus:meta -->` 注释暴露核心字段 | Step 6 同步时自动更新 |
+| `.cursor/rules/modus-knowledge.mdc` | 只读快照 | 不存储防腐字段（仅路径引用） | Step 6 同步时自动更新 |
+
+**关键原则**：
+- 所有防腐机制的触发（hash 比对、衰减计算、`usage_count` 更新）**均只操作 `modus/knowledge/` 权威源文件**
+- 副本文件发生变更不触发防腐机制，不影响 status
+- 若副本与权威源不一致（如手动修改副本），以权威源为准，下次 Step 6 同步时强制覆盖
+
+---
+<!-- ============================================================ -->
+<!-- 区块 C：Business Skill 标准格式参考（执行 Step 5 时按需读取）-->
+<!-- ============================================================ -->
+
+## Business Skill 标准格式参考（v3.1 / 17节）
+
+### 多语言适配说明
+
+本模板以 **Java + Spring Boot + MyBatis** 为默认实现（最常见的企业 Java 技术栈）。对于其他语言/框架的项目，按以下规则调整：
+
+| 调整点 | Java（默认） | Go + Gin/gRPC | Python + FastAPI |
+|--------|------------|--------------|-----------------|
+| **Section 3 字段表** | Java 类型（`Long`、`String`） | Go 类型（`int64`、`string`） | Pydantic 模型字段（含 `Field(...)` 校验） |
+| **Section 6 特有模式** | `AopContext.currentProxy()`、`@Transactional`、`BaseRpcResponse` | 中间件链（`middleware`）、`defer` 错误处理、gRPC status codes | `async/await` 模式、依赖注入（`Depends()`）、Pydantic 校验器 |
+| **Section 7 代码示例** | Java 类风格 | Go 函数风格（接收者方法） | Python async 函数风格 |
+| **Section 8 状态机** | 包含 `@Transactional` 注解 | 包含数据库事务块（`db.Begin()`/`tx.Commit()`） | 包含 SQLAlchemy 事务上下文 |
+| **Section 12 SQL 模式** | MyBatis XML Mapper | GORM / sqlx 查询 | SQLAlchemy ORM / 原生 SQL |
+| **key_files 文件类型** | `.java` | `.go` | `.py` |
+
+> **操作指引**：当 Step 2 检测到项目为 Go/Python 项目时，生成 Business Skill 前须先调整以上差异项，其余节格式保持不变。
+
+---
+
+```markdown
+---
+name: biz-{domain}
 description: "[MODUS:BIZ] {中文域名}业务知识 — {核心职责一句话}"
 version: 1.0.0
 updated: {YYYY-MM-DD}
@@ -780,22 +1386,24 @@ format_version: v3          # v1=7节 | v2=14节 | v3=17节（当前默认，含
 stale_after_days: 90        # 超过此天数自动降为 stale（默认 90 天）
 last_referenced: {YYYY-MM-DD}
 usage_count: 0
-last_hash: ""               # SHA-1(key_files 内容拼接)，前置更新时自动计算并填入
+last_hash: ""               # 全局 SHA-1（key_files 所有内容拼接后计算）；init 时写入，引用时快速比对
+file_hashes: {}             # 文件级 hash map：{路径: SHA-1}，与 key_files 一一对应；全局 hash 不一致时展开精准比对
 last_verified_by: ""        # 最后确认人（升为 verified 时填写）
 domain_confidence: 0        # 域置信度评分（0-10），来自 Step 2 评分矩阵
 invariant_count: 0          # Section 15 业务不变量条目数
 glossary_size: 0            # Section 16 领域词汇表条目数
 hidden_knowledge_rate: 0    # 隐性知识补全率（0-100），来自 Step 4 访谈问卷
+contract_version: "1.0"     # 本域对外暴露接口的当前版本；升级接口时同步更新，下游调用域在 Section 10 中记录此版本
 upstream_skills:            # 本 Skill 在 Section 10 中依赖的其他域 Skill
-  - modus-biz-payment
-  - modus-biz-user
+  - biz-payment
+  - biz-user
 downstream_skills:          # 依赖本域的其他 Skill（被依赖方）
-  - modus-biz-refund
+  - biz-refund
 key_files:                  # 关键源文件列表，用于 hash 检查（最多 20 个，覆盖全 10 类文件）
   # 优先级 1：核心业务逻辑（必选）
   - src/.../service/{Domain}Service.java
   - src/.../manager/{Domain}Manager.java
-  - src/.../dao/{Domain}Mapper.java
+  - src/.../dao/{Domain}CustomMapper.java
   - src/.../domain/{Domain}.java
   # 优先级 2：状态与规则（强烈建议）
   - src/.../enums/{Domain}Status.java
@@ -811,6 +1419,27 @@ key_files:                  # 关键源文件列表，用于 hash 检查（最
 
 > 由 Modus Skills Builder 自动生成。[MODUS:BIZ]
 
+---
+
+> **渐进加载模式（Agent 按任务类型选择，降低 token 消耗）：**
+>
+> | 模式 | 读取范围 | 预估 token | 适用场景 |
+> |------|---------|-----------|---------|
+> | **极简模式** | Section 1、2、15 | ~500 tokens | 快速了解业务边界和不变量约束 |
+> | **开发模式** | Section 1-8、10 | ~1500 tokens | 新增功能、接口开发 |
+> | **审查模式** | Section 3、8、13、15 | ~1000 tokens | Code Review、架构评审 |
+> | **排查模式** | Section 9、13 + Section 8 | ~600 tokens | 线上 Bug 排查、异常分析 |
+> | **完整模式** | 全量（Section 1-17） | ~3500 tokens | 首次接触本域、生成设计文档 |
+>
+> **员工速读导航：**
+> 初次接触本域 → 推荐阅读顺序：**Section 16（词汇表）→ Section 17.B（新人手册）→ Section 8（状态机）→ Section 3（业务规则）**
+> 排查线上问题 → 重点读：**Section 9（错误码）→ Section 13（开发陷阱）→ Section 15（业务不变量）**
+>
+> **Skill 状态：** `[SKILL_STATUS]` | **最后更新：** `[UPDATED]` | **hash：** `[HASH_PREFIX]`
+> 若 status 为 `stale`，禁止直接引用，先运行 `/modus:refresh {domain}`
+
+---
+
 ## 1. 域概述
 
 {业务域的职责边界和核心价值，2-3 句话，人类可读}
@@ -837,12 +1466,44 @@ CANCELLED(4, "已取消")
 
 ## 3. 业务规则 [process] [guideline]
 
+**Section 3 子节划分规范（必须按此结构组织，禁止混写）：**
+
+### 核心字段说明
+
 Section 3 最低内容门槛：每个核心字段必含：Java 类型、是否非空、业务含义、关联枚举（如有）
 
-- [process]   {流程规则：如 订单状态只能按 CREATED→PAID→COMPLETED 单向流转}
+| 字段 | Java 类型 | 非空 | 业务含义 | 关联枚举 |
+|------|----------|------|----------|----------|
+| {fieldName} | {类型} | ✓/- | {业务含义} | {枚举类名，无则-} |
+
+### 业务流程规则 [process]
+
+- [process] {流程规则：如 订单状态只能按 CREATED→PAID→COMPLETED 单向流转}
+
+### 推荐做法 [guideline]
+
 - [guideline] {推荐做法：如 退款金额必须 ≤ 原始支付金额，在 Service 层校验}
-- [pitfall]   {已知坑：如 并发创建时若不加锁会出现重复订单}
-- [decision]  {架构决策：如 选择 MQ 异步通知而非同步 RPC，原因是解耦和削峰}
+
+### 架构决策 [decision]
+
+- [decision] {架构决策：如 选择 MQ 异步通知而非同步 RPC，原因是解耦和削峰}
+
+> **⚠️ 内容边界约束（含信号词分流指引）：**
+>
+> 当不确定某条内容该写在哪个 Section 时，根据以下**信号词**判断归属：
+>
+> | 信号词模式 | 正确归属 | 典型例子 |
+> |----------|---------|---------|
+> | 「必须/禁止 + 违反=Bug/生产事故」 | Section 15 `[invariant]` | 「退款金额必须 ≤ 原始支付金额，否则为严重 Bug」 |
+> | 「推荐/建议/最佳实践」 | Section 3 `[guideline]` | 「建议在 Service 层做二次校验，而非只依赖前端」 |
+> | 「如果 A 发生则执行 B 流程」 | Section 3 `[process]` | 「支付超时后订单状态自动流转至 CANCELLED」 |
+> | 「选择方案 A 而非 B，因为...」 | Section 3 `[decision]` | 「选用 MQ 异步通知而非同步 RPC，原因是解耦削峰」 |
+> | 「曾经踩过/容易犯/易错点」 | Section 13 `[pitfall]` | 「曾因未加分布式锁导致重复订单，教训：必须加锁」 |
+> | 「新人首次开发前需了解/开发时注意」 | Section 17 | 「新人必读：状态枚举只存 code 值而非 name()」 |
+>
+> - `[process]`/`[guideline]`/`[decision]` 写本节，`[pitfall]` 写 Section 13，`[invariant]` 写 Section 15
+> - 禁止在 Section 3 中混入「不变量」内容（如「金额必须 > 0」——这是约束而非规则，属 Section 15）
+> - 若某子节无内容，可省略该子节标题
 
 ## 4. 关键文件索引 [model]
 
@@ -870,15 +1531,27 @@ Section 5 最低内容门槛：每个接口必含：入参校验规则、成功
 
 ## 7. 典型代码示例
 
+**Section 7 最低内容门槛：**
+- 示例代码必须来自实际扫描的源码（不能是纯伪代码框架）
+- 每段示例必须附带关键步骤的内联说明注释
+- 至少包含 1 个「写入/变更」场景 + 1 个「查询/权限」场景（若存在）
+- 示例中必须体现 Section 6 中列出的项目特有模式（如 AopContext、BaseRpcResponse 等）
+
 \`\`\`java
-// 订单创建的标准模式
+// 订单创建的标准模式（来自 OrderService.createOrder()）
 public OrderDTO createOrder(CreateOrderRequest request) {
-    // 1. 参数校验（Service 层）
-    // 2. 业务校验（余额、库存）
-    // 3. 创建 Domain 对象
-    // 4. 持久化
-    // 5. 发送 MQ 通知
-    // 6. 返回 DTO
+    // 1. 参数校验（Service 层，非 Controller 层）
+    validateCreateRequest(request);
+    // 2. 业务校验（余额、库存、限购等）
+    checkBusinessRules(request);
+    // 3. 创建 Domain 对象（领域逻辑封装在 Domain 中，不直接操作 Entity）
+    Order order = Order.create(request);
+    // 4. 持久化（通过 Mapper，注意：Mapper 必须在 dao 包下）
+    orderMapper.insert(order);
+    // 5. 发送 MQ 通知（异步，不影响主流程事务）
+    orderEventPublisher.publish(new OrderCreatedEvent(order));
+    // 6. 返回 DTO（使用 BaseRpcResponse 包装）
+    return BaseRpcResponse.build(OrderConverter.toDTO(order));
 }
 \`\`\`
 
@@ -897,13 +1570,52 @@ stateDiagram-v2
     REFUNDING --> REFUNDED : processRefund() @Transactional
     CREATED --> CANCELLED : cancelOrder() 超时/主动取消 @Transactional
     PAID --> CANCELLED : cancelOrder() 支付后取消（触发退款）
+    CREATED --> CREATE_FAILED : [异常流] 创建失败 (虚线)
+    PAID --> PAY_FAILED : [异常流] 支付失败回调 (虚线)
 \`\`\`
 
+> **图例说明：** 实线 = 正常流转；虚线 = 异常流/超时流（在实际 Mermaid 中用 `-->` 配合状态名区分，说明见下方子节）
+
+### 正常流转表
+
 | 起始状态 | 目标状态 | 触发条件 | 触发方法 | 事务保护 |
 |---------|---------|---------|---------|---------|
 | CREATED | PAID | 支付成功回调 | payOrder() | ✓ @Transactional |
 | PAID | COMPLETED | 用户确认收货 | completeOrder() | ✓ @Transactional |
 
+### 异常流（失败态处理）
+
+**前置检测条件：** 域中存在 `FAILED`/`ERROR`/`EXCEPTION` 类后缀状态，或 try-catch 中有状态变更操作，才生成本子节；否则省略。
+
+| 起始状态 | 失败目标状态 | 触发条件 | 触发方法 | 失败后处理 |
+|---------|-----------|---------|---------|----------|
+| CREATING | CREATE_FAILED | 数据库写入异常/库存不足 | createOrder() catch 块 | 记录失败原因，前端展示错误信息 |
+| PAYING | PAY_FAILED | 支付网关超时/余额不足 | payOrder() catch 块 | 订单回退可支付状态，允许重新支付 |
+
+> 若无失败态枚举值，写「暂无发现，随工作流积累」。
+
+### 超时自动流转
+
+**前置检测条件：** 域中存在定时任务（`@XxlJob`/`@Scheduled`/`XXXTimeoutJob`），或有 TTL 相关业务逻辑，才生成本子节；否则省略。
+
+| 当前状态 | 超时时长 | 流转目标 | 触发方式 | 补偿操作 |
+|---------|---------|---------|---------|---------|
+| CREATED | 30 分钟未支付 | CANCELLED | OrderTimeoutJob @XxlJob | 释放库存，发送取消通知 |
+| REFUNDING | 24 小时未处理 | 需人工介入 | RefundTimeoutJob @XxlJob | 创建人工工单，发送告警 |
+
+> 若无超时自动流转，写「暂无发现，随工作流积累」。
+
+### 补偿机制（MQ 失败重试与死信）
+
+**前置检测条件：** 域中存在 MQ 消费者（`@KafkaListener`/`@RocketMQMessageListener`），才生成本子节；否则省略。
+
+| 消息类型 | 正常消费 | 失败处理 | 重试策略 | 超限处理 |
+|---------|---------|---------|---------|---------|
+| payment.success | 订单状态流转至 PAID | 记录失败日志，状态不变 | 重试 3 次，间隔 1/2/5 分钟 | 进入死信队列，人工处理 |
+| order.timeout | 订单状态流转至 CANCELLED | 幂等检查通过则忽略 | 重试 1 次 | 记录告警日志 |
+
+> 若无 MQ 消费，写「暂无发现，随工作流积累」。
+
 ## 9. 错误码与异常 [pitfall]
 
 （无条件生成。若为空则写「暂无发现，随工作流积累」，此为合法初始内容，质量自检通过。）
@@ -918,19 +1630,27 @@ stateDiagram-v2
 （无条件生成。若为空则写「暂无发现，随工作流积累」，此为合法初始内容。由主流程 Section 10 回写阶段统一填入。）
 
 **上游依赖（本域调用的其他域）：**
-| 依赖域 | 交互方式 | 调用点 | 说明 |
-|--------|---------|-------|------|
-| payment | RPC @DubboReference | OrderService.createOrder() | 发起支付 |
-| user | RPC @DubboReference | OrderService.checkUser() | 校验用户状态 |
+| 依赖域 | 交互方式 | 调用点 | 接口版本 | 降级预案 | 说明 |
+|--------|---------|-------|---------|---------|------|
+| payment | RPC @DubboReference | OrderService.createOrder() | v2.1 | 超时 3s 后返回支付处理中，异步重试 | 发起支付 |
+| user | RPC @DubboReference | OrderService.checkUser() | v1.0 | 超时降级：跳过用户状态校验，记录告警 | 校验用户状态 |
 
 **下游被依赖（调用本域的其他域）：**
-| 调用域 | 交互方式 | 场景 |
-|--------|---------|------|
-| refund | RPC | 退款申请时查询原订单 |
+| 调用域 | 交互方式 | 接口版本（本域提供）| 场景 |
+|--------|---------|-----------------|------|
+| refund | RPC | v1.2 | 退款申请时查询原订单信息 |
+
+> **契约版本维护规则：**
+> - 本域对外暴露接口的当前版本记录在 frontmatter 的 `contract_version` 字段
+> - 调用方在本节上游依赖表中记录**调用时使用的版本号**
+> - 接口升级时：① 更新 `contract_version` ② 通知下游调用域更新其 Section 10 记录 ③ 触发 hash 更新
 
 ## 11. 数据流向 [process]
 
-**前置检测条件：** 域中存在 `@KafkaListener` / `sendMessage()` / `@RocketMQMessageListener` 才生成本节；否则整节省略。
+**前置检测条件：** 域中存在以下任意一项即生成本节；否则整节省略：
+- MQ 消息：`@KafkaListener` / `@RocketMQMessageListener` / `kafkaTemplate.send()` / `rocketMQTemplate.send()`
+- Spring 事件：`ApplicationEventPublisher.publishEvent()` / `@EventListener` / `implements *EventListener` 接口
+- 其他异步数据流：`@Async` + 跨域调用、`CompletableFuture` 跨域通信
 
 | 方向 | Topic/方法 | 触发时机 | 消费者/生产者 | 幂等保障 |
 |------|-----------|---------|------------|---------|
@@ -958,7 +1678,11 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
 
 ## 14. 扩展点 [decision]
 
-**前置检测条件：** 域中存在 `interface + 多实现类` 或 `@ConditionalOn*` 注解才生成本节；否则整节省略。
+**前置检测条件：** 域中存在以下任意一项即生成本节；否则整节省略：
+- 标准扩展点：`interface + ≥2 个实现类`（策略模式、模板方法模式）
+- 配置条件化：`@ConditionalOn*` 注解（Spring Boot 条件化装配）
+- 项目级接口：`项目定义的 *EventListener` / `*Handler` / `*Strategy` / `*Processor` 接口 + ≥1 个实现类
+- 插件化机制：`@Plugin` / `@Extension` / SPI `ServiceLoader` 加载点
 
 | 扩展点 | 接口/注解 | 当前实现 | 扩展方式 |
 |--------|---------|---------|---------|
@@ -991,27 +1715,84 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
 
 ## 17. 新人上手指南 [process]
 
-（无条件生成。基于本 Skill 内容自动合成，目标：读完本节即可开始在本域开发，无需找业务方答疑。）
+（无条件生成。本节分为两个独立子节，分别服务不同受众：Agent 快速定位 + 员工新人入门。）
+
+---
+
+### 17.A — Agent 快速定位指南（机器优先）
+
+> 适用受众：AI Agent 执行任务时，根据任务类型找到最小必读路径。
+
+#### 按任务类型的最小读取路径
+
+| 任务类型 | 必读 Section | 关键文件 | 核心约束提示 |
+|---------|------------|---------|------------|
+| **新增 API 接口** | 5（API契约）→ 3（业务规则）→ 15（不变量） | `{Domain}Controller.java` / `{Domain}Facade.java` | 确认权限注解、幂等需求（见 Section 5）|
+| **修改业务规则** | 3（业务规则）→ 8（状态机）→ 15（不变量） | `{Domain}Service.java` / `{Domain}Manager.java` | 修改后同步维护 Section 15 不变量 |
+| **新增/修改状态流转** | 8（状态机）→ 3（流程规则）→ 9（错误码） | `{Domain}Status.java` / `{Domain}Service.java` | 同步更新 Section 8 状态图和转换表 |
+| **Code Review** | 15（不变量）→ 13（陷阱）→ 8（状态机）→ 3（规则） | — | 重点检查不变量是否有校验代码 |
+| **排查线上 Bug** | 9（错误码）→ 13（陷阱）→ 8（状态机） | — | 优先查错误码，再对照状态机异常流 |
+| **新增 MQ 消息** | 11（数据流向）→ 3（规则）→ 15（不变量） | `{Domain}Consumer.java` / `{Domain}Producer.java` | 确认幂等保障机制（见 Section 11）|
+| **修改数据库查询** | 12（SQL模式）→ 4（文件索引）→ 2（核心实体） | `{Domain}Mapper.java` / XML Mapper | 注意慢查询风险（见 Section 12）|
+
+---
+
+### 17.B — 员工新人入门手册（人类优先）
 
-### 开发前必读清单
+> 适用受众：初次接触本域的研发同学，目标是读完本节即可开始独立开发，无需找业务方反复答疑。
 
-- [ ] 理解 {Domain}Status 枚举的 {N} 个状态及合法转换（见 Section 8）
-- [ ] 了解 Section 15 的 {M} 条业务不变量，违反将导致生产事故
-- [ ] 熟悉 Section 6 的项目特有模式（如 AopContext.currentProxy()）
-- [ ] 确认本地环境的依赖配置（MQ Topic、RPC 地址等，见 Section 11）
+#### 开发前必读清单
 
-### 常见开发场景速查
+> 建议逐项确认后再开始开发：
 
-| 场景 | 入口文件 | 关键类 | 注意事项 |
-|------|---------|-------|---------|
-| 新增业务状态 | {Domain}Status.java | {Domain}Status / {Domain}Service | 必须同步更新状态机校验逻辑（见 Section 8）|
-| 新增查询接口 | {Domain}Facade.java | {Domain}QueryService | 注意多租户 tenantId 过滤 |
-| 新增写入接口 | {Domain}Controller.java | {Domain}Service | 确认是否需要幂等保护（见 Section 5）|
-| 修改业务规则 | {Domain}Service.java | {Domain}Manager | 更新后同步维护 Section 15 不变量 |
+1. 理解 `{Domain}Status` 枚举的 {N} 个状态及合法转换（见 Section 8 状态机）
+2. 了解 Section 15 的 {M} 条业务不变量，违反将导致生产事故
+3. 熟悉 Section 6 的项目特有编码模式（如 `AopContext.currentProxy()`、`BaseRpcResponse.build()`）
+4. 阅读「高频踩坑」中摘录的前 3 条 Section 13 陷阱
 
-### 高频踩坑（新人必看，精选自 Section 13）
+#### 本域关键设计决策历史
 
-（自动提取 Section 13 前 3 条 [pitfall]，无内容时写「暂无记录，随工作流积累」）
+（自动从 Section 3 `[decision]` 条目中提取，补充设计背景；无内容时写「暂无记录，随工作流积累」）
+
+> **为什么这样设计？**（帮助新人理解现有架构，而不是仅知道怎么做）
+
+| 设计决策 | 选择方案 | 未选方案 | 设计理由 |
+|---------|---------|---------|---------|
+| {决策描述，如「通知方式」} | {选用方案，如「MQ 异步」} | {弃用方案，如「同步 RPC」} | {简要理由，如「解耦 + 削峰，支付服务故障不影响订单主流程」} |
+
+#### 本地环境搭建 Checklist
+
+（基于 Section 11 数据流向和 Section 10 跨域依赖自动生成；无相关配置时写「无特殊本地配置要求」）
+
+> **说明：** 以下为纯文字编号清单，本地启动前逐项确认：
+
+1. **MQ Topic 配置**：确认 `application-local.yml` 中 Topic 名称与联调环境一致
+   - 本域订阅 Topic：{来自 Section 11 的订阅 Topic 列表，无则写「-」}
+   - 本域发布 Topic：{来自 Section 11 的发布 Topic 列表，无则写「-」}
+2. **RPC 依赖服务**：确认以下服务在本地可访问（或已 Mock）
+   - {来自 Section 10 的上游依赖域列表，无则写「-」}
+3. **数据库**：确认本地 DB 已执行最新 migration，重点关注以下表
+   - {来自 Section 2 核心实体对应的主表，无则写「-」}
+4. **配置开关**：确认以下特性开关状态
+   - {来自 Section 14 扩展点的条件化配置，无则写「-」}
+
+#### 首次开发任务推荐
+
+（推荐从最简单的查询接口入手，逐步熟悉域内结构）
+
+推荐路径：**查询接口** → **写入接口** → **状态流转** → **跨域集成**
+
+#### 常见问题 FAQ
+
+（来自 Step 4 访谈问卷的回答摘要；无内容时写「暂无记录，随工作流积累」）
+
+| 问题 | 答案 | 来源 |
+|------|------|------|
+| {高频问题，如「为什么枚举存 code 不存 name？」} | {答案} | {代码推断 / [人工补充: {日期}]} |
+
+#### 高频踩坑（精选自 Section 13 前 3 条）
+
+（自动提取 Section 13 前 3 条 `[pitfall]`，无内容时写「暂无记录，随工作流积累」）
 
 1. ...
 2. ...
@@ -1034,19 +1815,31 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
 **执行逻辑：**
 
 ```
-1. 读取 .codebuddy/skills/{skill-name}/SKILL.md 的 frontmatter
+0. 判断当前 draft 状态类型（影响 verified 门槛）：
+   - draft(fresh)：usage_count = 0（Skill 刚生成，尚未用于真实任务）
+   - draft(used) ：usage_count ≥ 1（已用于至少一次开发，有反馈基础）
+
+1. 读取 modus/knowledge/biz-{domain}/SKILL.md 的 frontmatter（v3.2 Single Source of Truth）
+
 2. 运行质量自检清单：
    □ Section 3：每个 Entity 字段均有业务含义注释？
    □ Section 5：所有 Facade 方法均列出了错误码？
    □ Section 8（如存在）：所有 status 枚举值均出现在状态图中？
    □ Section 12（如存在）：每条 SQL 均有查询语义说明？
    □ 无条件生成节（9/10/13）：
-       - 「暂无发现，随工作流积累」是合法初始内容 → 质量自检通过 ✓
-       - 仅在 status 为 stale 时再次执行自检，若三节仍为此内容
-         → 标注 ⚠️「知识库超期且无积累，建议重新扫描或人工补充」
+       - draft(fresh)：「暂无发现，随工作流积累」是合法初始内容 → 自检通过 ✓
+       - draft(used) ：若三节仍为「暂无发现」→ 标注 ⚠️「已使用但知识未积累，建议补充后再 verify」
 
-3. 检查 verified 四项条件：
-   条件 1：所有无条件生成节（9/10/13）非空且非占位符
+3. 检查 verified 升级条件：
+
+   【draft(fresh) 门槛（宽松）】
+   条件 1：所有节结构存在且符合标准格式（无条件节可为「暂无发现」）
+   条件 2：质量自检清单零 ⚠️ 警告
+   条件 3：计算 key_files 当前 hash，与 last_hash 一致
+   条件 4：人工确认（见下方交互）
+
+   【draft(used) 门槛（严格）】
+   条件 1：所有无条件生成节（9/10/13）非「暂无发现」占位符，有真实内容
    条件 2：质量自检清单零 ⚠️ 警告
    条件 3：计算 key_files 当前 hash，与 last_hash 一致（无 stale）
    条件 4：人工确认（见下方交互）
@@ -1058,7 +1851,7 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
   → 用户回复 y：
       记录：last_verified_by: {运行者用户标识或 "self-verified"}
             verified_at: {今日 YYYY-MM-DD}
-      条件 4 ✅ 通过，继续检查 verified 合计结论
+      条件 4 ✅ 通过
 
   → 用户回复 N 或跳过：
       输出：「条件 4 未满足（尚无开发者真实使用反馈）
@@ -1069,27 +1862,60 @@ Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、J
    last_verified_by: {运行者标识}
    updated: {今日日期}
    version: 小版本 +1（如 v1.0.0 → v1.0.1）
-5. 未通过 → 列出未达标条件，不修改 status
+5. 未通过 → 列出未达标条件，并说明属于 draft(fresh) 还是 draft(used) 门槛，不修改 status
 ```
 
 ---
 
 ### `/modus:refresh {domain}`
 
-**定义**：对大域未覆盖的文件执行补充扫描，增量合并至已有 Skill。
+**定义**：重新扫描指定域的代码文件，检测变更并增量更新已有 Skill。
+
+**触发场景：**
+- 代码发生较大变更，`last_hash` 已失效（status = stale）
+- 想主动刷新某域的业务知识（如新增了大量接口、重构了状态机）
 
 **执行逻辑：**
 
 ```
-1. 读取 .codebuddy/skills/modus-biz-{domain}/SKILL.md 末尾的「未覆盖文件列表」
-   （由 Step 4 大域分批策略生成的 ⚠️ 提示块）
-2. 若无未覆盖文件列表 → 输出「{domain} 已全量覆盖，无需补扫」
-3. 若有 → 启动补充扫描 SubAgent，按 10 类优先级顺序读取剩余文件
-4. 将新发现的知识增量合并至已有 Skill（不覆盖已有内容，append-only）
-5. 更新 ⚠️ 提示块：
-   - 已补扫文件标记 ✓
-   - 剩余未扫文件更新列表
-   - 若所有文件已覆盖，移除 ⚠️ 提示块
-6. 重新计算 key_files hash 并写入 last_hash
-7. 更新 updated 日期和 version（小版本 +1）
+1. 读取 modus/knowledge/biz-{domain}/SKILL.md 的 frontmatter（v3.2 Single Source of Truth）：
+   - key_files 列表
+   - last_hash（上次生成时的 SHA-1 值）
+   - status（若已为 archived，询问用户是否继续）
+
+2. 重新计算当前 key_files 的 SHA-1 hash（按区块 B 标准算法）：
+   - 逐一对 key_files 中的每个文件单独计算 SHA-1
+   - 将「文件路径:SHA-1」对按文件路径字母序排序后拼接，再整体计算 SHA-1 得到 last_hash
+
+3. 比对 hash：
+   - 若 hash 一致 → 输出「{domain} 代码无变更，Skill 仍为最新，无需刷新」
+   - 若 hash 不一致 → 继续执行补扫流程
+
+4. 启动补充扫描 SubAgent，按 10 类文件类型重新扫描：
+   - 优先扫描 key_files 中已有文件（比对变更内容）
+   - 再扫描该域目录下新增但不在 key_files 中的文件
+   - 按 git 最近修改时间排序，优先读取最近变更的文件
+
+5. 将新发现的知识增量合并至已有 Skill（append-only，不覆盖已有人工标注内容）：
+   - 新增的枚举值补充至 Section 2
+   - 新增的业务规则补充至 Section 3
+   - 新增的 API 补充至 Section 5
+   - 新增的陷阱补充至 Section 13
+   - 新增的不变量补充至 Section 15
+
+6. 更新 frontmatter：
+   - 重新计算并写入新的 last_hash
+   - 若 status 为 stale → 升级为 draft（需人工重新 /modus:verify 才能到 verified）
+   - 更新 updated 日期
+   - version 小版本 +1（如 1.2.0 → 1.2.1）
+
+7. 触发多平台同步（若 platforms 已配置）：
+   - 更新 Claude Agent 文件、Cursor 规则等
+
+8. 输出刷新摘要：
+   ✓ {domain} 域刷新完成
+     代码变更：hash 从 {old_hash[:8]} → {new_hash[:8]}
+     补充内容：Section 2（+2条枚举）、Section 13（+1条陷阱）
+     Skill 版本：v{old} → v{new}
+     status：stale → draft（运行 /modus:verify 升级为 verified）
 ```