@modus-ai/modus 0.2.11 → 0.3.0

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 个节点，可拆分为子域文件。

package/templates/domain-history-readme.md

@@ -0,0 +1,60 @@
+# {Domain} — 知识演变历史（History）
+
+> **路径**：`modus/knowledge_base/domain/{domain}/history/`
+> **作用**：增量变更历史。**最新版本写入 `code/`**，旧版本归档于此，形成可追溯的演变链。
+> **维护**：`/modus:init` 强刷时自动归档旧版本；命令归档（`/modus:auto --archive`）时按 Story 写入。
+
+---
+
+## 文件命名规范
+
+```
+history/
+├── README.md
+├── 2026-05-22-init.md           # 首次初始化快照
+├── 2026-06-10-S12345.md         # 关联 Story 的变更
+├── 2026-07-01-refactor.md       # 重构变更
+└── snapshots/                   # 整目录快照（重大重构前）
+    └── 2026-08-15-pre-refactor/
+```
+
+---
+
+## 文件内容模板
+
+```markdown
+# {YYYY-MM-DD} — {Change Title}
+
+## 元信息
+- 触发：（init / story / refactor / manual）
+- 关联 Story：S-12345
+- 涉及文件：code/entities.md, code/apis.md
+- 变更摘要：
+
+## 关键 Diff（人类可读）
+- 新增：实体 `XxxBO`，字段 `yyy`
+- 修改：接口 `/api/v1/foo` 入参从 `bar` 改为 `baz`
+- 删除：废弃的 `OldService.process`
+
+## 业务影响
+（变更是否破坏向后兼容？是否需要灰度？）
+
+## 评审记录
+| 评审人 | 意见 |
+|-------|------|
+|  |  |
+```
+
+---
+
+## 检索方式
+
+| 场景 | 检索路径 |
+|------|---------|
+| 历史相似 Story | grep `S-XXXXX` history/*.md |
+| 某个实体的演变 | grep `EntityName` history/*.md |
+| 某段时间的所有变更 | ls history/2026-Q2-*.md |
+
+---
+
+> **维护提示**：本目录**只追加，不删除**（除非显式手工清理 snapshots/）。

package/templates/domain-scenarios-readme.md

@@ -0,0 +1,58 @@
+# {Domain} — 测试场景（Test Scenarios）
+
+> **路径**：`modus/knowledge_base/domain/{domain}/scenarios/`
+> **作用**：场景化接口调用链 + 端到端用例，供**测试团队消费**与**spec 阶段引用**。
+> **特性**：人工维护为主；命令也可写入（如 `/modus:spec` 完成时回写）。
+
+---
+
+## 文件组织
+
+```
+scenarios/
+├── README.md                  # 本文件
+├── e2e-{flow}.md              # 端到端流程（如 e2e-purchase.md）
+├── api-chain-{topic}.md       # 接口调用链（如 api-chain-checkout.md）
+├── data-prep.md               # 测试数据准备
+└── matrix.md                  # 兼容性/参数矩阵
+```
+
+---
+
+## 场景模板
+
+```markdown
+# Scenario: 新增专辑分发主流程
+
+## 前置数据
+- 用户：`uid=10086`，类型=个人
+- 专辑：`album_id=A001`，状态=待审核
+
+## 调用链
+
+| 步骤 | 接口 | 参数 | 预期返回 |
+|------|------|------|---------|
+| 1 | POST /api/album/submit | {...} | 200, status=pending |
+| 2 | GET /api/album/A001 | — | status=pending |
+| 3 | POST /admin/album/approve | {id: A001} | 200 |
+| 4 | GET /api/album/A001 | — | status=approved |
+
+## 验收点
+- [ ] 状态机正确流转
+- [ ] 审核日志写入
+- [ ] 通知发送
+```
+
+---
+
+## 与其他资产的关联
+
+| 关联 | 说明 |
+|------|------|
+| `../code/apis.md` | 场景使用的接口定义 |
+| `../business/` | 场景背后的业务规则 |
+| `modus/artifacts/<id>/code/spec/` | spec 命令产出的 Gherkin 场景 |
+
+---
+
+> **维护提示**：本目录优先服务于"测试团队、spec 阶段、回归测试"；命令侧仅在用户显式触发时写入。

package/templates/knowledge-base-map.md

@@ -0,0 +1,78 @@
+# Knowledge Base Map — 知识库地图（v4.0）
+
+> **路径**：`modus/knowledge_base/map.md`
+> **作用**：所有 Modus 命令的 Level 1 入口（~200 tokens 加载）；提供"部门 → 团队 → 项目 → 业务域"四层索引。
+> **维护**：由 `/modus:init` 自动生成与刷新；用户可手工补充团队/项目元信息。
+
+---
+
+## 1. 项目元信息
+
+```yaml
+project: ""                 # 项目英文名
+project_zh: ""              # 项目中文名
+department: ""              # 所属部门
+team: ""                    # 所属团队
+primary_stack: ""           # java | frontend | go | python | mixed
+modus_version: "4.0"
+last_init_at: ""
+```
+
+---
+
+## 2. 业务域索引（Domain Catalog）
+
+> 每个 domain 对应 `modus/knowledge_base/domain/<domain>/`。
+
+| Domain | 名称 | 入口 Skill | 业务规则 | 测试场景 | 历史 |
+|--------|------|-----------|---------|---------|------|
+| `_conventions` | 团队约定 | `domain/_conventions/code/SKILL.md` | — | — | — |
+| `_tech-wiki` | 技术 Wiki | `domain/_tech-wiki/code/SKILL.md` | — | — | — |
+| `<domain>` | （示例：合同域） | `domain/<domain>/code/SKILL.md` | `domain/<domain>/business/` | `domain/<domain>/scenarios/` | `domain/<domain>/history/` |
+
+---
+
+## 3. 服务调用全图
+
+> 详见 `modus/knowledge_base/service-graph.md`。本节仅作快速索引。
+
+- 当前注册服务数：N
+- 跨域调用关系：见 service-graph.md §2
+- 外部依赖：见 service-graph.md §3
+
+---
+
+## 4. 加载策略（命令执行时按需读取）
+
+```
+L0  modus/knowledge_base/map.md                              # ~200 tokens（必读）
+L1  modus/knowledge_base/domain/<d>/code/SKILL.md            # ~500 tokens（按域）
+L2  modus/knowledge_base/domain/<d>/code/{entities|apis|services|data-models}.md  # ~800 tokens/个（按需）
+L3  modus/knowledge_base/domain/<d>/business/                # 业务规则（仅业务约束相关任务）
+L4  modus/knowledge_base/domain/<d>/scenarios/               # 测试场景（仅 spec 阶段或测试）
+```
+
+---
+
+## 5. 与产物的关联
+
+| 阶段 | 产物路径 | 引用知识 |
+|------|---------|---------|
+| 需求澄清 | `modus/artifacts/<id>/pid/` | `domain/<d>/business/` |
+| 评估设计 | `modus/artifacts/<id>/design/` | `domain/<d>/code/`, `service-graph.md` |
+| 编码实施 | `modus/artifacts/<id>/code/` | 全部 |
+| 上线归档 | `modus/artifacts/<id>/archive/` | 反向写入 `domain/<d>/history/` |
+
+---
+
+## 6. 跨项目工作区路由（如适用）
+
+> 多项目工作区在仓库根有 `workspace-catalog.md`，列出每个子项目的 `modus/knowledge_base/map.md` 路径。
+
+| 子项目 | 路径 |
+|--------|------|
+|  | `<sub>/modus/knowledge_base/map.md` |
+
+---
+
+> **维护提示**：本文件由 `/modus:init` 强刷生成；如需手工补充，请使用 `> [人工补充]` 注释段落，避免被覆盖。