@modus-ai/modus 0.2.2 → 0.2.4

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

@@ -1,19 +1,23 @@
 ---
 name: modus-vibe
-description: Use this skill when executing /modus:vibe command for context-aware vibe coding. Loads relevant business Skills before coding so AI works as a knowledgeable project member. Trigger on /modus:vibe command or when user wants to code with business context. Supports --quick flag for simple single-file changes.
+description: Use this skill when executing /modus:vibe command for context-aware vibe coding. Intelligently loads relevant business Skills, auto-syncs stale knowledge, and applies rule-driven AskUserQuestion before coding so AI works as a knowledgeable project member. Trigger on /modus:vibe command or when user wants to code with business context.
 allowed-tools: Read, Write, Glob, Bash
 disable: false
 ---
 
-# modus-vibe（氛围编程）
+# modus-vibe（智能氛围编程）
 
 **触发条件：** 用户运行 `/modus:vibe [描述]` 时使用此 Skill。
 
-支持快速模式：`/modus:vibe --quick [描述]` 跳过 Skill 预更新和域确认，适合简单的单文件改动。
+---
 
 ## 职责
 
-氛围编程入口。在编码前先通过**三级渐进加载**获取相关业务上下文，让 AI 以「懂业务的资深开发者」身份工作，而不是从零开始理解项目。
+氛围编程入口。在编码前通过**三级渐进加载**获取相关业务上下文，让 AI 以「懂业务的资深开发者」身份工作。相比传统 vibe 模式，增加了三大智能机制：
+
+1. **智能分析引擎**：自动判断涉及哪些域（置信度 ≥ 85% 时无需用户确认）、任务复杂度（Simple/Medium/Complex）、歧义风险
+2. **Skill 前置同步**：加载前静默检查知识是否过时，按需更新后再加载，用户仅看到一行状态提示
+3. **Skill 后置写回**：编码结束后自动将新发现的知识写入 Skill 文件，形成知识积累闭环
 
 ---
 
@@ -34,12 +38,14 @@ constitution:
 
 若文件不存在或 `constitution` 为空，跳过此步。
 
+---
+
 ### Step 1：Level 1 加载——读知识目录（~200 tokens）
 
 读取 `modus/knowledge-catalog.md`（全景目录索引）：
 - 了解当前项目有哪些可用的 Skill
-- 识别各 Skill 的 maturity 状态
-- 为 Step 2 的域匹配做准备
+- 识别各 Skill 的 maturity 状态、最近引用时间
+- 为 Step 2 的智能分析做准备
 
 **如果 `knowledge-catalog.md` 不存在：**
 
@@ -54,156 +60,244 @@ B. 继续使用降级模式（无业务上下文，结果质量可能降低）
 ```
 
 - 选 A → 执行 `/modus:init` 流程，完成后继续
-- 选 B → 跳过知识加载，直接进入编码
+- 选 B → 跳过 Step 2-3，直接进入 Step 4（歧义检测仍然执行）
 
-### Step 2：快速模式判断
+---
 
-**如果用户使用 `--quick` 标志：**
-- 跳过 Step 3（域识别与确认）和 Step 4（Level 2 加载）
-- 直接进入 Step 5（澄清意图）
-- 仍然遵守 Step 0 读取的 constitution 约束
+### Step 2：智能分析引擎
 
-**如果是普通模式，继续 Step 3。**
+基于用户 prompt 和 knowledge-catalog 内容，推导以下三个维度，**不需要读取完整 SKILL.md**：
 
-### Step 3：域匹配与确认（Level 2 预备）
+#### 2A：域匹配与置信度
 
-基于 `knowledge-catalog.md` 的目录信息，结合用户 prompt，**无需读取完整 SKILL.md**，仅凭目录中的一行摘要判断涉及哪些业务域：
+对每个 catalog 中的业务域，计算匹配置信度：
 
 ```
-根据你的需求，我认为涉及以下业务域：
+匹配信号（每命中一项 +分）：
+  ★★★ 高权重（+30%）：用户 prompt 直接提及域名关键词、Skill 描述的核心实体名
+  ★★  中权重（+20%）：用户 prompt 提及该域的核心操作动词（如「审批」命中 approval 域）
+  ★   低权重（+10%）：间接业务词（如「金额」可能命中 payment 域）
+```
 
-✓ order（订单域）— 订单创建、状态流转       [verified] → 将加载完整 Skill
-✓ payment（支付域）— 支付发起、回调          [proven]  → 将加载完整 Skill
-? logistics（物流域）— 发货跟踪             [未初始化] → 是否顺便新建？
+**输出规则：**
+- 置信度 ≥ 85% 的**单个域**：自动选中，无需用户确认。在 Step 3 输出前标注 `[自动匹配: {domain} 域]`
+- 多个域或最高置信度 < 85%：展示候选列表，等待用户确认（可直接回车接受建议）
 
-确认以上分类？（直接回车确认，或告诉我调整）
 ```
+根据你的需求，我匹配到以下业务域：
 
-**`⚠️` 标注的 Skill** 表示可能已过时，提醒用户：「该 Skill 距上次引用已超过阈值，内容可能过时，将以代码为准」。
+✓ order（订单域）— 订单创建、状态流转       [verified] 置信度 92% → 自动加载
+? payment（支付域）— 支付发起、回调          [proven]  置信度 60% → 是否也需要？
 
-若用户确认新建缺失的 Skill，调用 Skills Builder SubAgent（模式 A）新建后再继续。
+直接回车确认 order 域，或告诉我调整。
+```
 
-### Step 4：Level 2 加载——读匹配 Skill（~3000 tokens/个）
+#### 2B：任务复杂度评估
 
-读取用户确认的业务域对应的完整 SKILL.md 文件，将其内容作为背景知识。
+| 复杂度 | 判定条件 | 后续影响 |
+|--------|---------|---------|
+| `Simple` | 单域 / 有明确接口名和功能描述 / 无跨域依赖 / 改动范围可预估为单文件 | Design Brief 精简为 3 节 |
+| `Medium` | 跨域依赖 / 涉及状态机或事务 / 需求描述有一处明显歧义 | Design Brief 完整 9 节 |
+| `Complex` | 多域 + 多处歧义 / 涉及 Pitfall 命中 / prompt 含「大概/可能/随便/看着来/都行」等模糊词 | Design Brief 完整 9 节 + 风险标注 |
 
-**注意事项：**
-- 只加载确认相关的域，不相关的域 Skill **不读取**（节省 token）
-- 若 Skill 的 `maturity` 为 `draft`，提示：「该 Skill 较新，若与代码有出入，以代码为准」
-- 对 Skill 中的内容进行「有则更新无则新增」的感知：
-  - 若当前代码与 Skill 记录有出入，以代码为准，并在回复末尾标注「Skill 更新建议」
-  - 若 Skill 没有覆盖此次需求的概念，在编码过程中补充
+#### 2C：输出分析摘要
 
-### Step 5：澄清用户意图（AskUserQuestion）
+完成 2A / 2B 后，在内联上下文中记录（不输出给用户）：
 
-在开始编码前，确保充分理解用户意图。根据用户 prompt 和已加载的 Skill 上下文，提出 1-3 个关键澄清问题。
+```
+[ANALYSIS]
+domain: {domain}  confidence: {%}
+complexity: Simple | Medium | Complex
+ambiguity_rules_hit: [R1, R3, ...]  ← 命中的规则 ID，见 Step 4
+```
+
+---
+
+### Step 3：条件性 Skill 前置同步（轻感知）
+
+对 Step 2 确认的每个业务域，执行以下检查：
 
-**提问原则：**
-- 只问影响实现方向的关键问题，不问可以从代码中推断的细节
-- 若 prompt 已足够明确（有具体接口名、明确功能描述），可跳过此步
-- 从 Skill 的 `[pitfall]` 条目中检查是否存在与本次需求相关的已知坑，若有则主动提醒
+#### 触发更新的条件（满足任一即触发）
+
+- `maturity = stale`（已被 skill-creator 标记为过期）
+- catalog 中 `last_referenced` 超过 90 天
+- 调用 `modus-skill-creator` 模式 B 的 hash 检查发现 key_files 有变化
+
+#### 执行方式
 
-**示例问题类型：**
 ```
-为了准确实现，我需要确认几点：
+触发更新 → 静默调用 modus-skill-creator 模式 B（增量更新）
+         → 更新完成后输出单行状态：
+           [已同步 {domain} 域知识]
 
-1. [范围] 这次修改只影响 {domain} 域，还是还涉及 {other domain}？
-2. [行为] {具体业务规则的歧义点，如「审批拒绝后是否可以重新提交」}？
-3. [约束] 有没有特殊的兼容性要求（如需要兼容历史数据 / 不能修改现有接口签名）？
-4. [风险] ⚠️ 此功能涉及到已知的 {pitfall}，请确认是否已考虑到？
+无需更新 → 直接进入 Step 4，不输出任何提示
 ```
 
-等待用户回答后，输出理解摘要：
+**注意：** 整个同步过程对用户完全透明，无需确认，不中断流程。若同步耗时较长（超过 3 秒），追加进度提示 `[同步中...]`。
+
+---
+
+### Step 4：规则驱动 AskUserQuestion
+
+#### 歧义规则清单
+
+根据 Step 2C 中记录的 `ambiguity_rules_hit`，判断是否需要提问。
+
+| 规则 ID | 触发条件 | 问题类型 |
+|---------|---------|---------|
+| R1 | 涉及 ≥ 2 个域且边界不清（用户未明确主导域） | [范围] 哪个域是主导？期望在哪一层修改？ |
+| R2 | prompt 含「可能/大概/随便/看着来/都行/先这样」等模糊词 | [需求] 明确期望行为和完成标准 |
+| R3 | catalog 的 `[pitfall]` 摘要有命中条目 | [风险] 确认已知坑的处理方案 |
+| R4 | 描述缺少关键决策参数（如幂等策略/权限范围/兼容性要求） | [约束] 补充边界条件 |
+| R5 | 复杂度为 `Complex` 且 `modus/plans/` 下无对应 `plan.md` | [设计] 建议先 /modus:plan 还是直接 vibe？ |
+
+#### 提问决策
 
 ```
-好的，我的理解是：
-- {要点1}
-- {要点2}
-- 遵守项目约束：{来自 constitution 的关键规则}
+不命中任何规则 → 跳过，直接进入 Step 5，输出：
+  [任务清晰，直接开始]
+
+命中 1-2 条规则 → 提出对应问题（最多 2 个），等待用户回答后继续
+
+命中 ≥ 3 条规则 → 优先选择最高影响的 2 条规则提问（R5 > R1 > R3 > R4 > R2）
+```
+
+**提问格式（命中时）：**
+
+```
+编码前需确认几点：
+
+1. [{问题类型}] {具体问题}
+2. [{问题类型}] {具体问题}  ← 最多 2 个
 
-如果理解无误，我来开始实现。
+回答后我立即开始实现。
 ```
 
-### Step 6：内联设计思考（Design Brief CoT）
+等待用户回答后，输出一句话确认摘要：
+
+```
+好的，理解了：{核心决策点 1-2 句话}。开始实现。
+```
+
+---
+
+### Step 5：Level 2 加载——读匹配 Skill（~3000 tokens/个）
+
+读取用户确认的业务域对应的完整 SKILL.md 文件，将其内容作为背景知识。
+
+**注意事项：**
+- 只加载确认相关的域，不相关的域 Skill **不读取**（节省 token）
+- 若 Skill 的 `maturity` 为 `draft`，提示：「该 Skill 较新，若与代码有出入，以代码为准」
+- 在 Skill 中重点关注 `[pitfall]`、`[model]`、`[guideline]` 条目，以及 `关键文件索引`
+
+---
+
+### Step 6：自适应内联设计方案（Design Brief CoT）
 
-**触发：** 每次编码任务前强制执行，不可跳过（包括 `--quick` 模式）。  
+**触发：** 每次编码任务前强制执行，不可跳过。  
 **产出：** 内联于当前 LLM 上下文，**不写入任何文件**。
 
+根据 Step 2B 评估的复杂度，输出不同深度的设计方案：
+
+#### Simple 模式（3 节精简版，~200 tokens）
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[Design Brief — Simple | 域: {domain}]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## 实现蓝图
+Data:    {Mapper 类/方法}
+Service: {Manager/Service 类/方法}
+API:     {Facade/Controller 类/方法}
+
+## 禁止事项
+{constitution hard_rules + Skill [pitfall] 关键项，逐条列出}
+
+## 需求追踪
+| 需求点 | 对应实现 | 校验方式 |
+|-------|---------|---------|
+| {需求} | {类/方法} | {测试/联调} |
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+#### Medium/Complex 模式（完整 9 节）
+
 调用 `modus-design-brief` Skill，传入：
-- `mode: vibe`（触发内联输出模式，不落盘）
-- `analysis_doc: 用户 prompt + Step 5 确认的意图摘要`
-- `business_skills: Step 4 已加载的 Skill 内容`
+- `mode: vibe`（内联输出模式，不落盘）
+- `complexity: Medium | Complex`
+- `analysis_doc: 用户 prompt + Step 4 确认的意图摘要`
+- `business_skills: Step 5 已加载的 Skill 内容`
 - `constitution: Step 0 读取的 constitution 字段`
 
-Skill 将按 9 节结构，基于已加载上下文实时推导并输出以下内联块：
+**Complex 模式额外要求：**
+- 节 6（边界条件）必须完整展开所有失败路径
+- 节 9（需求追踪矩阵）每行追加 `⚠️` 标注已命中的 Pitfall
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-[Design Brief — 内联设计方案，仅用于本次编码，不写文件]
+[Design Brief — {Simple|Medium|Complex} | 域: {domain1}, {domain2}]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ## 1. 基本信息
-模式: vibe | 涉及域: {domain1}, {domain2}
-
 ## 2. 业务意图摘要
-{来自 Step 5 的意图摘要}
-
 ## 3. 实体与数据模型
-{基于 Skill [model] 条目和用户意图推导，字段带类型}
-
 ## 4. API / 接口合同
-{方法签名，带完整包路径}
-
 ## 5. 实现蓝图
-Data: {具体 Mapper 类/方法}
-Service: {具体 Manager/Service 类/方法，标注 @Transactional 位置}
-API: {Facade/Controller 类/方法}
-
 ## 6. 边界条件与异常处理
-{覆盖关键失败路径，含错误码}
-
 ## 7. 代码生成提示
-{来自 Skill key_files 的可复用类 + 命名规范示例}
-
 ## 8. 禁止事项与已知坑
-{constitution hard_rules + Skill [pitfall]}
-
 ## 9. 需求-任务追踪矩阵
-| 需求点 | 对应实现 | 对应校验方式 |
-|---|---|---|
-| {需求} | {类/方法} | {测试/联调} |
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [End of Design Brief — 开始编码]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**简化原则（vibe 模式）：**
-- 若 Skill 中某节内容明确，可适度精简，但不可省略节标题
-- 节 9 追踪矩阵在 vibe 模式下用「需求点→实现→校验方式」代替完整 Sprint 映射
-- 若 `--quick` 模式，节 3/4/9 可简化为一行摘要，但节 8 禁止事项必须完整输出
+---
 
 ### Step 7：执行编码任务（Level 3 按需加载）
 
 基于 Step 6 内联设计方案和澄清后的意图，执行用户的编码请求：
 
-- 以 Step 6 内联设计方案中节 5（实现蓝图）为编码路线图
-- 严格遵守节 8（禁止事项）——这是 constitution hard_rules 和 Skill [pitfall] 的汇总
-- 引用节 7（代码生成提示）中的现有类路径，不凭空创造类名
+- 以设计方案中「实现蓝图」为编码路线图
+- 严格遵守「禁止事项」——这是 constitution hard_rules 和 Skill [pitfall] 的汇总
+- 引用「代码生成提示」中的现有类路径，不凭空创造类名
 - **Level 3 加载：** 需要具体代码实现时，按需读取 Skill 中 `关键文件索引` 指向的实际代码文件（而非预先全量读取）
 - 对不确定的业务规则，优先参考 Skill 中的规则描述
-- 如发现 Skill 中记录有误或过时，在回复末尾标注「Skill 更新建议」
+- 如发现 Skill 中记录有误或过时，记录到内部缓冲区，在 Step 8 处理
+
+---
+
+### Step 8：Skill 后置自动写回
+
+编码完成后，检查本次编码过程中是否发现新知识：
 
-### Step 8（可选）：Skill 更新建议
+#### 触发写回的条件（满足任一即触发）
 
-如果在编码过程中发现业务 Skill 有遗漏或错误，在回复末尾追加：
+- 发现代码中存在 Skill 未记录的枚举值、状态机节点、接口方法
+- 发现 Skill 中已记录的规则与代码实际不符（需要更正）
+- 编码过程中踩到了一个 Skill 中未记录的坑（新 `[pitfall]`）
+- 新增了一个值得记录的 `[guideline]` 或 `[decision]`
+
+#### 执行方式
 
 ```
-📝 Skill 更新建议（运行 /modus:plan 或 /modus:spec 时会自动应用）：
-- [model] order 域：发现 OrderStatus 枚举新增了 PENDING_REVIEW 状态
-- [pitfall] order 域：批量操作时若不分页会导致内存溢出
+有新知识 → 静默调用 modus-skill-creator 模式 C（知识提取写入）
+          → 写入完成后输出单行提示：
+            [已更新 {domain} 域知识: 新增 [pitfall] {摘要} / 更正 [model] {字段名}]
+
+无新知识 → 静默跳过，不输出任何提示
 ```
 
+**写回原则：**
+- 只写入有明确代码证据的知识，不写推测性内容
+- 每次写回最多 3 条新条目，避免批量污染
+- 更正已有条目时，保留原条目并追加修订记录（不覆盖历史）
+
+---
+
 ### Step 9：写入 Session 日志
 
 编码完成后，将本次会话**追加**（append-only，禁止覆盖原有内容）到 `modus/sessions/vibe-log.md`：
@@ -212,8 +306,9 @@ API: {Facade/Controller 类/方法}
 ## {YYYY-MM-DD HH:mm} — {需求一句话摘要}
 
 - **涉及域：** {domain1}, {domain2}
+- **复杂度：** Simple | Medium | Complex
 - **修改文件：** {变更文件列表，最多 5 个}
-- **Skill 更新建议：** {发现的新知识，无则填「无」}
+- **知识写回：** {本次写回条目摘要，无则填「无」}
 
 ---
 ```
@@ -224,10 +319,22 @@ API: {Facade/Controller 类/方法}
 
 ## 氛围编程原则
 
+- **智能优先，减少打断**：域匹配明确时自动确认，无需强制等用户输入；任务清晰时跳过提问
 - **先设计再编码**：Step 6 内联设计方案是编码的前置必要步骤，不可省略
-- **设计驱动**：编码时以内联设计方案的实现蓝图（节 5）为路线图，禁止事项（节 8）为红线
+- **知识闭环**：每次 vibe 编码都是一次知识更新机会，通过 Step 3 前置同步 + Step 8 后置写回，知识库随项目演进自动积累
 - **有据可依**：引用的实体、字段、接口名必须来自 Skill 或已有代码
-- **风格一致**：生成的代码应与项目现有风格保持一致
-- **宪法优先**：constitution.hard_rules 是不可违反的底线，优先于一切（已汇总到设计方案节 8）
+- **宪法优先**：constitution.hard_rules 是不可违反的底线，优先于一切
 - **按需加载**：不预先读取所有 Skill，降低 token 消耗
 - **主动补全**：发现明显缺失（如缺少参数校验、日志）时主动补充
+
+---
+
+## 降级模式（无知识库）
+
+当 `knowledge-catalog.md` 不存在且用户选择跳过初始化时：
+
+1. 跳过 Step 2-3（无 catalog 可分析）
+2. Step 4 仅执行 R2（模糊词检测）和 R4（缺少决策参数检测）
+3. Step 6 固定使用 Medium 模式（无法判断复杂度）
+4. Step 8 跳过写回（无 Skill 文件可写入）
+5. 在回复开头标注：`[降级模式：无业务上下文，建议先运行 /modus:init]`