@modus-ai/modus 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modus-ai/modus",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Modus — Business-grounded AI coding accelerator for CodeBuddy IDE",
   "keywords": [
     "ai",

package/schemas/knowledge-schema.yaml

@@ -69,6 +69,18 @@ skill_frontmatter:
       type: date
       required: true
       description: 最近一次被工作流引用的日期，用于衰减计算
+      
+    - name: last_hash
+      type: string
+      required: true
+      description: key_files 内容的 SHA-1 哈希值，用于检测代码变更。初始值为空字符串，首次使用时自动计算
+      default: ""
+      
+    - name: key_files
+      type: list
+      required: true
+      description: 关键源文件路径列表（最多20个），用于计算 last_hash。按优先级选取：Service/Manager/Mapper/Entity（必选），Enum/Exception（强烈建议），MQ/Config（有则加入）
+      default: []
 
     - name: usage_count
       type: integer

package/templates/knowledge-catalog.md

@@ -24,3 +24,30 @@ updated: {YYYY-MM-DD}
   Level 3（按需，无上限）: 执行任务时读 Skill 引用的实际代码文件
 
 目标：不相关的 Skill 不加载，大幅降低 token 消耗。
+
+## Skill 状态生命周期
+
+### 成熟度状态（基于 usage_count）
+- **draft**    → 初始生成，未经验证（usage_count = 0）
+- **verified** → 经至少1次真实使用验证（usage_count ≥ 1，运行 `/modus:verify` 升级）
+- **proven**   → 经≥2个不同工作流验证有效（usage_count ≥ 2）
+- **stale**    → last_hash 不匹配或距 last_referenced 超过 stale_after_days，需更新（禁止直接引用）
+- **archived** → 域已废弃，不再维护
+
+### 衰减规则（基于 last_referenced）
+- proven  + 距 last_referenced 超过 12 个月 → verified
+- verified + 距 last_referenced 超过 6 个月 → stale
+- stale   + 距 last_referenced 超过 stale_after_days → archived（需人工二次确认）
+
+### 防腐机制核心字段
+每个 Skill frontmatter 必须包含以下字段，缺一不可：
+- **last_referenced**: 最后引用时间（用于衰减计算）
+- **usage_count**: 使用次数（用于成熟度升级）
+- **last_hash**: key_files 内容 SHA-1 哈希（用于检测代码变更，初始留空）
+- **key_files**: 关键源文件列表（最多20个，用于 hash 计算）
+
+缺少任一防腐字段将导致：
+- 无法自动检测代码变更
+- 无法触发 Skill 更新
+- 无法计算知识衰减
+- 防腐机制完全失效

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

@@ -230,7 +230,7 @@ shasum -a 1 {key_files...} | awk '{print $1}' | sort | shasum -a 1 | awk '{print
 
 注释汇总统计（Step 1 完成后输出）：
   发现 TODO {N}条 | FIXME {M}条 | WARN/注意 {W}条 | HACK {H}条 | @deprecated {D}条
-  → TODO > 3 条时：触发知识空白标记，供 modus-init Step 3.5 访谈问卷生成使用
+  → TODO > 3 条时：触发知识空白标记，供 modus-init Step 4 访谈问卷生成使用
 ```
 
 ---
@@ -324,7 +324,7 @@ Step 2C-4：构建完整转换矩阵（含禁止转换，不允许留空）：
   | PAID    | COMPLETED | 确认收货 | completeOrder() | @Transactional | - |
   | COMPLETED | CANCELLED | - | - | - | ❌ 抛 InvalidTransitionException |
 
-  孤立状态（无入/出转换的枚举值）→ 标记为 ⚠️「孤立状态，触发 Step 3.5 访谈」
+  孤立状态（无入/出转换的枚举值）→ 标记为 ⚠️「孤立状态，触发 Step 4 访谈」
 ```
 
 #### 2D. 自定义校验器扫描
@@ -522,7 +522,7 @@ Step 2C-4：构建完整转换矩阵（含禁止转换，不允许留空）：
 1. **2A if/else 推断结果** → 将所有 `[invariant]` 标签条目写入本节，标注来源行号
 2. **2D 自定义校验器** → 将 isValid()/validate() 中的判断逻辑转为不变量条目
 3. **Step 1.4 代码注释挖掘** → 将 `//WARN / //注意 / //重要` 注释写入本节（标注来源）
-4. **Step 3.5 人工访谈回答** → 将用户补充的业务约束写入本节（标注 `[人工补充: {日期}]`）
+4. **Step 4 人工访谈回答** → 将用户补充的业务约束写入本节（标注 `[人工补充: {日期}]`）
 
 每条不变量必含：不变量描述、验证位置（类名:行号或方法名）、违反后果（异常类或错误码）、来源标注
 
@@ -537,7 +537,7 @@ Step 2C-4：构建完整转换矩阵（含禁止转换，不允许留空）：
 2. Domain/Entity 类的类级 Javadoc → 实体中文含义与边界说明
 3. Service/Manager 方法 Javadoc 中出现的业务专名词（如「结算」「对账」「预授权」「防重」）
 4. Step 1.4 代码注释中出现的业务术语（`// 注意：此处的"XX"指的是...` 类注释）
-5. Step 3.5 人工访谈中用户提及的专业术语（标注 `[人工补充]`）
+5. Step 4 人工访谈中用户提及的专业术语（标注 `[人工补充]`）
 
 每个术语必含：术语名、定义（1-2句）、与通用概念的区别（若无区别可省略）
 
@@ -737,7 +737,7 @@ last_verified_by: ""        # 最后 verified 确认人（运行 /modus:verify
 domain_confidence: 0        # 域置信度评分（0-10），来自 modus-init Step 2 评分矩阵
 invariant_count: 0          # Section 15 业务不变量条目数（由 Skills Builder 自动统计）
 glossary_size: 0            # Section 16 领域词汇表条目数（由 Skills Builder 自动统计）
-hidden_knowledge_rate: 0    # 隐性知识补全率（0-100），来自 modus-init Step 3.5 访谈问卷
+hidden_knowledge_rate: 0    # 隐性知识补全率（0-100），来自 modus-init Step 4 访谈问卷
 upstream_skills:            # 本 Skill 在 Section 10 中依赖的其他域 Skill（由 Step 4 双向同步维护）
   - modus-biz-payment
 downstream_skills:          # 依赖本域的其他 Skill（由被依赖方的 Step 4 双向同步维护）
@@ -907,7 +907,7 @@ stateDiagram-v2
 
 ## 15. 业务不变量 [invariant]
 
-（无条件生成。来源：2A if/else 推断 + 2D 自定义校验器 + Step 1.4 注释挖掘 + Step 3.5 人工访谈。）
+（无条件生成。来源：2A if/else 推断 + 2D 自定义校验器 + Step 1.4 注释挖掘 + Step 4 人工访谈。）
 
 | 不变量描述 | 验证位置 | 违反后果 | 来源 |
 |---------|---------|---------|------|
@@ -917,7 +917,7 @@ stateDiagram-v2
 
 ## 16. 领域词汇表 [model]
 
-（无条件生成。来源：枚举描述 + Javadoc + 代码注释 + Step 3.5 人工访谈。）
+（无条件生成。来源：枚举描述 + Javadoc + 代码注释 + Step 4 人工访谈。）
 
 | 术语 | 定义 | 与通用概念的区别 |
 |------|------|----------------|

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

@@ -92,9 +92,9 @@ disable: false
 
 ---
 
-### Step 2：项目扫描与业务分类（4 轮全量扫描）
+### Step 2：项目扫描与业务分类（5 轮全量扫描）
 
-启动一个「项目分析 SubAgent」，执行以下 **4 轮结构化扫描**（替代原有的简单目录读取）：
+启动一个「项目分析 SubAgent」，执行以下 **5 轮结构化扫描**（替代原有的简单目录读取）：
 
 #### 轮次 1：模块发现
 
@@ -272,7 +272,7 @@ disable: false
 请指定每个小包的处理方式（合并/独立/重命名）或回复「保持原样」：
 ```
 
-**严禁自动决策**：必须在一次交互中等待用户对「域归属确认 + 小包合并决策」全部回复后，才能进入 Step 3.5。
+**严禁自动决策**：必须在一次交互中等待用户对「域归属确认 + 小包合并决策」全部回复后，才能进入 Step 4。
 
 #### 3.2 大域反向拆分保护
 
@@ -297,9 +297,9 @@ disable: false
 
 ---
 
-### Step 3.5：结构化访谈问卷（隐性知识捕获）
+### Step 4：结构化访谈问卷（隐性知识捕获）
 
-**触发时机：** 用户确认域列表后、Step 4 启动前执行。
+**触发时机：** 用户确认域列表后、Step 5 启动前执行。
 
 **核心目的：** 代码扫描只能获得「显性结构知识」，此步骤通过动态生成的针对性问题，补全代码中无法推断的**隐性业务知识**（口口相传的规则、历史决策、业务背景）。
 
@@ -362,7 +362,7 @@ disable: false
 
 ---
 
-### Step 4：生成业务 Skill（Layer 2）—— 并行执行
+### Step 5：生成业务 Skill（Layer 2）—— 并行执行
 
 用户确认后，**同时**为每个业务域启动独立的「Skills Builder SubAgent」（`modus-skill-creator` Skill，模式 A），并行生成所有业务 Skill 文件。各域之间完全独立，无需等待彼此完成。
 
@@ -446,7 +446,7 @@ SubAgent-3 (user域)    ──► 扫描用户全量文件（含Enum/MQ/Config
   payment.downstream_skills = [order, refund]
 ```
 
-### Step 5：多平台同步（Business Skills）
+### Step 6：多平台同步（Business Skills）
 
 Business Skills 全部生成后，读取 `modus/config.yaml` 的 `platforms` 字段，将每个业务 Skill 同步到其他已选平台。
 
@@ -516,7 +516,7 @@ alwaysApply: false
 
 ---
 
-### Step 6：生成团队约定 Skill（Layer 0-T）
+### Step 7：生成团队约定 Skill（Layer 0-T）
 
 调用「Skills Builder SubAgent」（模式 E：团队约定初始化）：
 
@@ -541,7 +541,7 @@ alwaysApply: false
 > 原始文件保持不变，Modus 仅在此处做统一索引。
 ```
 
-### Step 7：生成技术知识 Skill（Layer 1）
+### Step 8：生成技术知识 Skill（Layer 1）
 
 调用「Skills Builder SubAgent」（模式 E：技术知识初始化），初始化技术知识骨架：
 
@@ -554,7 +554,7 @@ alwaysApply: false
 2. 从构建文件提取的技术栈（`pom.xml` → Spring Boot 版本、`package.json` → 框架版本等）
 3. 占位符章节（反模式库、架构决策、跨项目经验——待后续工作流积累）
 
-### Step 8：生成知识全景目录（knowledge-catalog.md）
+### Step 9：生成知识全景目录（knowledge-catalog.md）
 
 在 `modus/knowledge-catalog.md` 创建全景索引，使用升级后的条目格式：
 
@@ -599,7 +599,7 @@ Skill status 生命周期（统一使用 status 字段）：
 - stale   + 超过 stale_after_days → archived（需人工二次确认）
 ```
 
-### Step 9：初始化 modus/config.yaml（若不存在）
+### Step 10：初始化 modus/config.yaml（若不存在）
 
 若项目尚无 `modus/config.yaml`，生成默认配置：
 
@@ -626,7 +626,7 @@ constitution:
 
 提示用户填写 `constitution` 字段，以便后续命令无需重复说明项目约束。
 
-### Step 10：完成回报
+### Step 11：完成回报
 
 所有业务 Skill 生成完毕后，回复用户：
 
@@ -716,25 +716,54 @@ constitution:
 
 ---
 
-### Step 4 补充：生成 Business Skill 时必须填写 key_files 和质量评分字段
-
-在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写以下字段：
-
-**key_files 填写规则：**
+### Step 5 补充：生成 Business Skill 时必须填写完整 frontmatter（防腐机制核心）
+
+在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写以下**完整字段清单**。这些字段是知识防腐机制的核心，缺一不可：
+
+#### 一、基础元数据字段（必填）
+- `name`: Skill 唯一标识符（与目录名一致）
+- `description`: 一句话描述，必须包含 `[MODUS:BIZ]` 标记
+- `version`: 语义化版本号（初始 1.0.0）
+- `updated`: 最后更新日期（YYYY-MM-DD）
+- `status`: 成熟度状态（初始 draft）
+- `format_version`: 节结构版本（当前 v3）
+- `stale_after_days`: 过期天数阈值（默认 90）
+
+#### 二、防腐机制核心字段（必填，缺少则无法检测代码变更）
+- **`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 时填写
+
+#### 三、key_files 填写规则（最多 20 个，用于 hash 检测）
 - 上限 **20 个**文件（覆盖全部 10 类文件类型）
 - 按以下优先级选取（满 20 个时从后往前截断）：
-  - 优先级 1（必选）：Service、Manager、Mapper/DAO、Domain/Entity
-  - 优先级 2（强烈建议）：Enum/Constant（状态/类型枚举）、Exception/ErrorCode
-  - 优先级 3（有则加入）：MQ Consumer/Producer、@Configuration
-- 这些文件将用于后续 plan/spec/harness 的「前置 Skill 更新 hash 检查」
-- `last_hash` 初始留空（`""`），下次 plan/spec/harness 触发前置更新时自动计算并填入
+  - **优先级 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 检查感知
 
-**质量评分字段（新增，必须填写）：**
-- `domain_confidence`: 本域的置信度评分（0-10），来自 Step 2 置信度评分矩阵
-- `invariant_count`: 生成的业务不变量条目数（Section 15）
-- `glossary_size`: 领域词汇表条目数（Section 16）
-- `hidden_knowledge_rate`: 隐性知识补全率（已回答问卷数 / 总问卷数，0-100）
+#### 四、质量评分字段（必填，用于知识库质量报告）
+- **`domain_confidence`**: 本域的置信度评分（0-10），来自 Step 2 置信度评分矩阵
+- **`invariant_count`**: 生成的业务不变量条目数（Section 15）
+- **`glossary_size`**: 领域词汇表条目数（Section 16）
+- **`hidden_knowledge_rate`**: 隐性知识补全率（0-100，来自 Step 4 访谈问卷）
+
+#### 五、跨域依赖字段（由 Section 10 回写阶段自动填入）
+- **`upstream_skills`**: 本域依赖的其他域 Skill 列表
+- **`downstream_skills`**: 依赖本域的其他域 Skill 列表
+
+**重要提示：** 如果 frontmatter 缺少上述任一防腐字段（特别是 `last_referenced`、`usage_count`、`last_hash`、`key_files`），将导致：
+- 无法自动检测代码变更
+- 无法触发 Skill 更新
+- 无法计算知识衰减
+- 防腐机制完全失效
 
 ---
 
@@ -756,7 +785,7 @@ 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 3.5 访谈问卷
+hidden_knowledge_rate: 0    # 隐性知识补全率（0-100），来自 Step 4 访谈问卷
 upstream_skills:            # 本 Skill 在 Section 10 中依赖的其他域 Skill
   - modus-biz-payment
   - modus-biz-user