@modus-ai/modus 0.1.8 → 0.2.2

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

@@ -21,7 +21,7 @@ disable: false
 
 读取 `modus/config.yaml`（若存在），提取 `constitution` 字段中的硬性约束，作为整个初始化过程的最高优先级约束。
 
-若 `modus/config.yaml` 不存在，将在 Step 7 创建默认配置。
+若 `modus/config.yaml` 不存在，将在 Step 9 创建默认配置。
 
 ### Step 1：扫描已有 AI 工具配置
 
@@ -92,41 +92,275 @@ disable: false
 
 ---
 
-### Step 2：项目扫描与业务分类
+### Step 2：项目扫描与业务分类（4 轮全量扫描）
 
-启动一个「项目分析 SubAgent」，执行以下操作：
+启动一个「项目分析 SubAgent」，执行以下 **4 轮结构化扫描**（替代原有的简单目录读取）：
 
-1. 读取项目根目录结构，识别主要模块、包或服务
-2. 扫描核心代码文件（优先：Controller/Facade、Service、Manager、Mapper/DAO、Domain/Entity、配置文件）
-3. 结合文件名、包名、注释、接口命名，提炼业务域列表
-4. 每个业务域给出：
-   - 域名称（英文，用作目录名，如 `order`, `payment`, `user`）
-   - 中文名称（如 订单域、支付域、用户域）
-   - 核心职责一句话概述
-   - 涉及的主要文件路径（最多 5 个代表性路径）
+#### 轮次 1：模块发现
 
-**输出格式（向用户展示）：**
+递归枚举项目中所有构建单元：
+- Java/Kotlin：递归发现所有 Maven Module（`pom.xml`）或 Gradle 子项目（`settings.gradle`）
+- Python：发现所有包目录（含 `__init__.py` 或 `pyproject.toml`）
+- 前端：发现所有独立 Node Package（`package.json`）
+
+输出：模块列表（含模块名、路径、构建文件路径）
+
+#### 轮次 2：包级清单
+
+对每个模块，逐包统计：
+- 文件数量
+- 类型分布（`Controller/Facade` / `Service/Manager` / `Mapper/DAO` / `Domain/Entity` / `Enum/Constant` / `DTO/VO` / `Exception/ErrorCode` / `MQ Consumer/Producer` / `XML Mapper` / `@Configuration`）
+
+**输出格式：按文件数从多到少排序，完整展示不截断：**
+
+```
+包级清单（共 {N} 个包）：
+
+  order（43个文件）   Controller✓ Facade✓  主要概念: 订单创建/支付/状态流转
+  payment（31个文件） Controller✓          主要概念: 支付发起/回调/退款
+  user（28个文件）    Controller✓ Facade✓  主要概念: 用户注册/登录/权限
+  inventory（12个文件）                    主要概念: 库存管理
+  diversion（3个文件）                     主要概念: 流量分发（⚠️ 小包候选）
+  singerfollower（2个文件）                主要概念: 关注关系（⚠️ 小包候选）
+  ...（全量展示，不截断）
+```
+
+#### 轮次 3：域语义分析
+
+按命名模式 + 调用链分析推断域归属：
+- 分析包名中的业务语义词（如 `order`、`pay`、`user`）
+- 扫描 Service 类中的方法命名，归纳核心职责
+- 识别 Facade/Controller 入口，确认域的对外暴露点
+
+#### 轮次 4：跨域依赖
+
+扫描 RPC 调用、MQ Topic 订阅/发布，绘制域间依赖关系：
+- `@DubboReference` / `@FeignClient` — 识别跨域 RPC 依赖
+- `eventPublisher.publish()` / `kafkaTemplate.send()` / `rocketMQTemplate.send()` — 识别 MQ 发布
+- `@KafkaListener` / `@RocketMQMessageListener` — 识别 MQ 订阅
+- `@Autowired` 或构造注入了来自其他业务包的 Service — 识别 Spring 跨域注入
+- `ApplicationEventPublisher.publishEvent()` + `@EventListener` — 识别事件驱动隐式依赖
+
+#### 轮次 5：数据库表所有权图谱（新增）
+
+扫描所有 XML Mapper 中的表名 + `@TableName` 注解，构建全局表归属地图：
+
+```
+扫描目标：
+  - resources/**/mapper/*.xml 中所有 <select>/<insert>/<update>/<delete> 的 FROM/INTO/UPDATE 子句
+  - @TableName("table_name") 注解（MyBatis-Plus）
+
+输出：表所有权矩阵
+  order_main        → [order]          ← 独占表（置信度+2）
+  order_item        → [order]          ← 独占表
+  payment_record    → [payment]        ← 独占表
+  user_account      → [user, payment]  ← ⚠️ 共享表，存在隐式跨域耦合
+  config_dict       → [order, user, payment] ← 公共配置表（排除出所有权统计）
+
+孤立表（无任何域 Mapper 访问）：
+  → 提示「发现 {N} 个无域归属的表，需人工决策归属：{表名列表}」
+```
+
+#### 轮次 3 末尾：域置信度评分矩阵（新增）
+
+完成轮次 1-5 后，对每个候选域执行置信度评分（满分 10 分）：
+
+| 评分维度 | 评分规则 | 说明 |
+|---------|---------|------|
+| ① 包名语义内聚度 | 高=2 / 中=1 / 低=0 | 包名与业务术语匹配度 |
+| ② 数据库表独占率 | >70%=2 / >40%=1 / <40%=0 | 独占表数 ÷ 总访问表数 |
+| ③ 对外入口完备性 | 有 Controller/Facade=2 / 仅内部=1 / 无入口=0 | 是否有对外暴露点 |
+| ④ 核心实体独立性 | 仅本域路径=2 / 跨域共享=1 / 无 Entity=0 | Domain/Entity 是否封装 |
+| ⑤ 事务边界清晰度 | 集中在本域 Service=2 / 跨域=1 / 无=0 | @Transactional 分布 |
+
+**置信度分级处理：**
+
+```
+≥ 7 分 → [高置信度] 自动确认，在扫描结果中标 ✅
+4-6 分 → [中置信度] 标 ⚠️，在展示时突出显示，请用户确认
+< 4 分 → [低置信度] 标 ❌，强制暂停等待用户决策，不允许直接进入 Step 4
+```
+
+---
+
+**扫描结果展示（向用户展示）：**
 
 ```
 我识别到以下业务域，请确认：
 
-1. order（订单域）— 订单创建、状态流转、查询
-   关键文件: OrderController, OrderService, OrderMapper, OrderDomain
-2. payment（支付域）— 支付发起、回调、退款
-   关键文件: PayFacade, PayManager, PayRecordMapper
-3. user（用户域）— 用户注册、登录、权限
+1. order（订单域）— 订单创建、状态流转、查询        [置信度: 9/10 ✅]
+   关键文件: OrderController, OrderService, OrderMapper, OrderDomain, OrderStatus(Enum)
+   独占表: order_main, order_item（共2个）
+   
+2. payment（支付域）— 支付发起、回调、退款          [置信度: 8/10 ✅]
+   关键文件: PayFacade, PayManager, PayRecordMapper, PayStatus(Enum)
+   独占表: payment_record（共1个）
+   
+3. user（用户域）— 用户注册、登录、权限             [置信度: 5/10 ⚠️ 请确认]
    关键文件: UserController, UserService, AuthManager
+   ⚠️ 该域未发现独立 Entity 类（得分偏低），请确认是否独立域？
+   
+4. diversion（流量分发）— 流量路由                 [置信度: 2/10 ❌ 需要决策]
+   ❌ 低置信度：仅 2 个业务类，无 Controller/Facade，无独占表
+   建议选择：A) 合并至 user 域  B) 合并至 platform 域  C) 保持独立
+
+域间依赖：order → payment（RPC），order → user（RPC），payment → notify（MQ）
+共享表警告：user_account 被 user 和 payment 两个域访问，存在隐式耦合
+
+是否确认以上分类？（❌ 低置信度域必须先处理）
+```
+
+---
+
+#### 扫描覆盖率报告（Step 2 末尾输出）
+
+```
+📊 扫描覆盖率报告
+  已识别域：{N} 个
+  项目总文件：{total} 个（已排除 *Test.java 和 generated/ 目录）
+  已纳入域的文件：{covered} 个（{percent}%）
+
+  未纳入文件（{uncovered} 个）：
+    排除原因 → 测试类（*Test.java）：{n} 个
+    排除原因 → 自动生成类（generated/、target/）：{n} 个
+    排除原因 → 待确认归属：
+      - src/main/java/com/example/util/DateUtils.java
+      - src/main/java/com/example/common/PageHelper.java
+      （以上文件未归入任何域，需用户决策）
+
+  如需将「待确认」文件归入某域，请回复：{文件路径} → {域名}
+```
+
+---
+
+### Step 3：用户确认 + 置信度门槛 + 小包评估 + 大域保护
+
+等待用户确认域列表之前，先执行以下评估：
+
+#### 3.0 置信度门槛强制执行
+
+在展示域列表前，按置信度分级执行不同策略：
+
+```
+对所有低置信度域（< 4分，标 ❌）：
+  → 必须在展示时明确列出「建议处理方案」（合并/拆分/重命名）
+  → 严禁自动进入 Step 4，必须等待用户对每个 ❌ 域给出明确决策
+
+对所有中置信度域（4-6分，标 ⚠️）：
+  → 在展示时附上「置信度偏低原因说明」
+  → 用户可直接确认通过，也可调整
+
+对高置信度域（≥ 7分，标 ✅）：
+  → 用户可批量确认，无需逐一说明
+```
+
+#### 3.1 小包检测（三维综合评分）
+
+对每个候选域，按以下三项指标综合评分：
+- ① **业务类文件数 < 5 个**（不含测试类、DTO、生成类）
+- ② **无 Controller / Facade 对外入口**
+- ③ **仅有单一业务概念**（包名/类名语义高度聚焦）
+
+满足 ≥2 项的域标记为「小包候选」，统一在域确认前展示：
+
+```
+📦 发现以下可能需要合并的小包（请逐一决策）：
+  diversion（分流，2个业务类）    → 建议合并至 traffic 或 user 域
+  singerfollower（关注，3个业务类）→ 建议合并至 user 或 social 域
+  mobile（移动端适配，2个业务类）  → 建议合并至 platform 域
 
-是否确认以上分类？（可以修改/新增/删除）
+请指定每个小包的处理方式（合并/独立/重命名）或回复「保持原样」：
 ```
 
-### Step 3：用户确认
+**严禁自动决策**：必须在一次交互中等待用户对「域归属确认 + 小包合并决策」全部回复后，才能进入 Step 3.5。
+
+#### 3.2 大域反向拆分保护
+
+当某域文件数超过 80 个时，额外提示：
+
+```
+⚠️ order 域包含 {N} 个文件，超过建议上限（80个）。
+建议考虑子域拆分方案：
+  - order-core（订单核心流程）：OrderService / OrderDomain / OrderMapper
+  - order-settle（结算子流程）：SettleService / SettleManager
+  - order-query（查询侧）：OrderQueryFacade / OrderQueryService
+
+请确认：保持单域 / 按建议拆分 / 自定义拆分方案：
+```
 
-等待用户确认或修改业务域列表。用户可以：
+用户可以：
 - 直接回复「确认」继续
 - 修改某个域的名称或描述
 - 增加遗漏的业务域
 - 删除不需要的域
+- 对小包指定合并目标或保持独立
+
+---
+
+### Step 3.5：结构化访谈问卷（隐性知识捕获）
+
+**触发时机：** 用户确认域列表后、Step 4 启动前执行。
+
+**核心目的：** 代码扫描只能获得「显性结构知识」，此步骤通过动态生成的针对性问题，补全代码中无法推断的**隐性业务知识**（口口相传的规则、历史决策、业务背景）。
+
+#### 问卷生成规则
+
+对每个确认的业务域，基于 Step 2 的扫描发现，**自动识别知识空白**并生成对应问题（每域上限 5 个，按重要性排序）：
+
+| 触发条件 | 生成的问题模板 | 写入目标 |
+|---------|-------------|---------|
+| 发现状态机有孤立状态（无入/出转换） | ❓ 状态 `{STATUS}` 无明确出口转换，请问：它在什么情况下结束？由谁操作？ | Section 8 状态机 |
+| 发现名含 `create/pay/submit` 的接口无幂等保护 | ❓ 接口 `{METHOD} {PATH}` 未发现幂等机制，请问：是否有业务层防重设计？防重 key 是什么？ | Section 5 API 契约 |
+| 发现跨域 RPC 调用无超时/降级配置 | ❓ `{ServiceA}` 调用 `{ServiceB}` 时未发现超时配置，请问：超时的业务兜底逻辑是什么？ | Section 10 跨域依赖 |
+| 发现 `//TODO:` 注释超过 3 处 | ❓ 发现 {N} 处 TODO 注释，其中：{前3条摘录}，请问这些是否是已知技术债务？ | Section 13 开发陷阱 |
+| 发现共享数据库表（多域访问） | ❓ 表 `{table}` 被 {A} 和 {B} 两个域访问，请问：谁是主域？跨域访问是否经过评审？ | Section 10 跨域依赖 |
+| 发现无对应 ErrorCode 的 RuntimeException | ❓ 发现 `{ExceptionClass}` 无对应错误码枚举，请问：该异常对前端展示什么错误信息？HTTP 状态码？ | Section 9 错误码 |
+| 发现金额相关字段类型为 Double/Float | ❓ 发现 `{field}` 使用 Double/Float 存储金额，请问：这是有意为之还是待修复的技术债务？ | Section 15 业务不变量 |
+
+#### 问卷展示格式
+
+```
+📋 {domain-name} 域知识补全问卷（共 {N} 个问题，可逐条回答或跳过）
+
+[问题 1/N] ❓ 状态 PENDING_REVIEW 无明确出口转换，请问：
+  它在什么情况下结束？由谁操作？有没有超时自动处理？
+  
+  > 您的回答（回车跳过）：_
+
+[问题 2/N] ❓ 接口 POST /orders/pay 未发现幂等机制，请问：
+  是否有业务层防重设计？防重 key 是什么？有效期多长？
+  
+  > 您的回答（回车跳过）：_
+
+...
+
+📌 回答将直接写入对应 Skill 节（标注 [人工补充: {YYYY-MM-DD}]）
+📌 跳过的问题将标注 ⚠️「该问题未回答，Skill 存在知识空白，建议后续补充」
+```
+
+#### 访谈结果处理
+
+```
+用户回答 → 写入对应 Section，格式：
+  - [invariant] {用户回答的规则内容}（[人工补充: {YYYY-MM-DD}]）
+
+用户跳过 → 在对应 Section 末尾追加：
+  > ⚠️ 知识空白：{问题描述}（未回答，建议在首次真实开发任务后补充）
+
+所有域问卷回答完成后，统计：
+  已回答问题数 / 总问题数 = 隐性知识补全率
+  
+  隐性知识补全率 < 60% → 在 Step 10 完成报告中标注 ⚠️，提示「知识库完整度偏低，建议重新运行访谈」
+  隐性知识补全率 ≥ 60% → 正常进入 Step 4
+```
+
+**如无任何知识空白被发现（全量扫描无触发条件）：** 跳过问卷，直接进入 Step 4，输出：
+
+```
+✓ {domain-name} 域扫描完整，未发现知识空白，跳过访谈问卷
+```
+
+---
 
 ### Step 4：生成业务 Skill（Layer 2）—— 并行执行
 
@@ -139,30 +373,78 @@ disable: false
 ```
 用户确认域列表后，立即并行启动 N 个 SubAgent：
 
-SubAgent-1 (order域)   ──► 扫描订单相关文件 ──► 生成 modus-biz-order/SKILL.md
-SubAgent-2 (payment域) ──► 扫描支付相关文件 ──► 生成 modus-biz-payment/SKILL.md
-SubAgent-3 (user域)    ──► 扫描用户相关文件 ──► 生成 modus-biz-user/SKILL.md
-          │                                              │
-          └──────────────── 所有 SubAgent 完成 ──────────┘
-                                    ↓
-                         进入 Step 6（串行）
+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 完成 ─────────────────────────────┘
+                                           ↓
+                          主流程执行跨域依赖分析（Section 10 回写）
+                                           ↓
+                                    进入 Step 6（串行）
 ```
 
 **每个 SubAgent 的任务（模式 A 标准流程）：**
-1. 接收域名称 + 代表性文件路径列表（来自 Step 2 的分析结果）
-2. 深度扫描该域的 Service/Manager/Mapper/Domain/Entity 层文件
-3. 提取：核心实体、业务规则、API 契约、关键代码模式
-4. 生成标准格式的 Skill 文件（含 `key_files`、`maturity: draft`）
 
-**聚合等待：** 所有 SubAgent 完成后，收集各 SubAgent 的完成状态摘要，在主流程中汇总展示：
+1. 接收域名称 + **全量文件路径列表**（来自 Step 2 轮次 2/3 的分析结果，含所有 10 类文件）
+2. 按优先级分三批扫描（**无文件数量上限，全量覆盖**）：
+   - **第一批（核心知识，必须完整扫描）**
+     - ① Controller/Facade → API 契约、权限注解
+     - ② Service/Manager → 业务规则、事务边界
+     - ③ Domain/Entity → 核心字段、业务方法
+     - ⑥ Enum/Constant → 完整枚举值和业务含义
+   - **第二批（细节知识，全量扫描）**
+     - ④ Mapper/DAO → 数据操作模式
+     - ⑤ XML Mapper → 关键 SQL（JOIN/子查询/复杂条件）
+     - ⑦ DTO/VO/Request/Response → 字段约束、校验规则
+   - **第三批（扩展知识，按 git 最近修改时间排序，优先扫描最新文件）**
+     - ⑧ Exception/ErrorCode → 错误码体系
+     - ⑨ MQ Consumer/Producer → 消息契约、幂等性保障
+     - ⑩ @Configuration → 开关配置、扩展点注册
+3. 提取：核心实体、业务规则、API 契约、状态机、错误码、关键 SQL 模式、扩展点、**业务不变量**（新增）
+4. 生成标准 17 节格式的 Skill 文件（含 `key_files`、`status: draft`、`format_version: v3`）
+
+**Context 超限自动保护策略（替换原有硬限制）：**
+
+```
+当 token 预算不足（预计超出上下文窗口）时：
+  → 自动拆分：启动 SubAgent-A 扫描第一批 + 第二批文件
+              启动 SubAgent-B 扫描第三批文件（含剩余第二批）
+  → 合并：两个 SubAgent 完成后，由主流程执行知识合并：
+          - SubAgent-A 的结果作为 Skill 主体（Section 1-9）
+          - SubAgent-B 的补充结果追加合并（Section 10-17 + 知识条目去重）
+  → 在 Skill 末尾标注：「[两段合并扫描: 批次A={N}个 + 批次B={M}个，共 {N+M} 个文件]」
+
+当两段都超限时（超大域 > 200 个文件）：
+  → 按域内子包进一步拆分（如 order-core / order-query / order-settle）
+  → 提示用户是否手动拆分为多个子域，或接受分段扫描
+```
+
+**废除所有「⚠️ 未覆盖文件」提示块**，替换为：
 
 ```
-✓ modus-biz-order   已生成（8 个 key_files，5 条业务规则，3 个 API）
-✓ modus-biz-payment 已生成（6 个 key_files，4 条业务规则，2 个 API）
-✓ modus-biz-user    已生成（5 个 key_files，3 条业务规则，4 个 API）
+✓ {domain} 域已完成全量扫描（共 {N} 个文件，第一批 {A} 个 + 第二批 {B} 个 + 第三批 {C} 个）
 ```
 
-每个 Skill 文件遵循 Business Skill 标准格式（含 maturity/last_referenced/usage_count 字段）。
+**Section 10 跨域依赖回写（所有 SubAgent 完成后，主流程执行）：**
+
+所有并行 SubAgent 完成后，主流程统一执行一轮跨域依赖分析：
+1. 汇总 Step 2 轮次 4 的跨域依赖关系图
+2. 对每个域 Skill 的 Section 10 进行回写，填入上游依赖域和下游被依赖域
+3. 同步更新各 Skill frontmatter 的 `upstream_skills` 和 `downstream_skills` 字段
+4. 执行 upstream/downstream 双向同步（详见 `00-skills-builder` Step 4 扩展算法）
+
+**聚合等待：** 所有 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）
+
+跨域依赖 Section 10 回写完成：
+  order.upstream_skills   = [payment, user]
+  payment.downstream_skills = [order, refund]
+```
 
 ### Step 5：多平台同步（Business Skills）
 
@@ -274,7 +556,7 @@ alwaysApply: false
 
 ### Step 8：生成知识全景目录（knowledge-catalog.md）
 
-在 `modus/knowledge-catalog.md` 创建全景索引，内容如下：
+在 `modus/knowledge-catalog.md` 创建全景索引，使用升级后的条目格式：
 
 ```markdown
 # Modus 知识全景目录
@@ -283,21 +565,38 @@ alwaysApply: false
 updated: {YYYY-MM-DD}
 
 ## 团队约定 (Layer 0-T)
-- **modus-team-conventions**: 代码规范/提交规范/最佳实践 [maturity: draft] 更新: {日期}
+- **modus-team-conventions**: 代码规范/提交规范/最佳实践
+  [status: draft] [format: v2/14节] [upstream: -]
+  更新: {日期}
 
 ## 技术知识 (Layer 1)
-- **modus-tech-wiki**: 跨项目技术经验（反模式、架构决策、性能优化） [maturity: draft] 更新: {日期}
+- **modus-tech-wiki**: 跨项目技术经验（反模式、架构决策、性能优化）
+  [status: draft] [format: v2/14节] [upstream: -]
+  更新: {日期}
 
 ## 业务知识 (Layer 2)
-- **modus-biz-order**: 订单域 — 创建/状态流转/查询 [maturity: draft] 最近引用: {日期}
-- **modus-biz-payment**: 支付域 — 发起/回调/退款 [maturity: draft] 最近引用: {日期}
-- **modus-biz-user**: 用户域 — 注册/登录/权限 [maturity: draft] 最近引用: {日期}
+- **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}
 
 ## 使用说明
-所有 Skill 初始 maturity 为 draft。随着工作流执行和人工验证：
-- 在 1 个工作流中被成功引用 → verified
-- 在 ≥2 个工作流中验证有效 → proven
-衰减规则：proven 12 个月未引用 → verified；verified 6 个月未引用 → draft（标注 ⚠️ 可能已过时）
+Skill status 生命周期（统一使用 status 字段）：
+- draft    → 初始生成，未经验证
+- verified → 经至少1名开发者在真实需求中验证，且无知识缺失反馈（运行 /modus:verify 升级）
+- proven   → 经≥2个不同工作流验证有效
+- stale    → hash 不匹配或超过 stale_after_days，需更新（禁止直接引用）
+- archived → 域已废弃，不再维护
+
+衰减规则：
+- proven  + 超过 12 个月未引用 → verified
+- verified + 超过 6 个月未引用 → stale（保留人工标注痕迹，非降为 draft）
+- stale   + 超过 stale_after_days → archived（需人工二次确认）
 ```
 
 ### Step 9：初始化 modus/config.yaml（若不存在）
@@ -340,8 +639,8 @@ constitution:
   MCP 服务器   — tapd (来自 .claude/settings.json) 已写入 modus/config.yaml
 
 生成了 N 个业务 Skill（Layer 2）：
-- .codebuddy/skills/modus-biz-order/SKILL.md    [draft]
-- .codebuddy/skills/modus-biz-payment/SKILL.md  [draft]
+- .codebuddy/skills/modus-biz-order/SKILL.md    [draft] [v3/17节]
+- .codebuddy/skills/modus-biz-payment/SKILL.md  [draft] [v3/17节]
 - ...
 
 多平台同步（来自 modus/config.yaml platforms 配置）：
@@ -357,6 +656,16 @@ constitution:
 知识目录：
 - 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% ⚠️ │
+└─────────────────┴──────┴──────┴──────┴──────┴──────┴──────────┘
+⚠️ modus-biz-user 隐性知识补全率 40%（低于 60% 阈值），建议补充访谈。
+
 💡 建议：填写 modus/config.yaml 中的 constitution 字段，
    记录项目硬性约束（技术栈、命名规范等），后续所有命令将自动加载。
 
@@ -364,10 +673,11 @@ constitution:
   .claude/commands/deploy.md、.claude/commands/review.md（来自 Claude Code）
 
 现在可以使用：
-  /modus:vibe  — 氛围编程（自动加载业务上下文）
-  /modus:plan  — 功能规划
-  /modus:spec  — 规范驱动开发
-  /modus:harness — 全自动 Harness 流程
+  /modus:vibe     — 氛围编程（自动加载业务上下文）
+  /modus:plan     — 功能规划
+  /modus:spec     — 规范驱动开发
+  /modus:harness  — 全自动 Harness 流程
+  /modus:verify   — 升级 Skill 状态（draft → verified）
 ```
 
 ---
@@ -376,25 +686,59 @@ constitution:
 
 如果 `.codebuddy/skills/` 下已存在 `modus-biz-*` 目录：
 
-1. 提示用户当前已有哪些业务 Skill 及其最后更新时间和 maturity
-2. 询问：全量重建 / 仅更新指定域 / 新增缺失域
-3. 按用户选择执行对应操作
-4. 无论何种选择，都更新 `modus/knowledge-catalog.md` 的索引信息
+提示用户当前已有哪些业务 Skill 及其最后更新时间、status 和 format_version：
+
+```
+当前已有以下业务 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 节（业务不变量/词汇表/新人指南）
+```
+
+**选择「补全新节」时的执行规则：**
+- 读取已有 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 5 多平台同步逻辑（更新 Claude Code、Cursor、Copilot 对应文件）
+
+无论何种选择，都更新 `modus/knowledge-catalog.md` 的索引信息。
 
 ---
 
-### Step 4 补充：生成 Business Skill 时必须填写 key_files
+### Step 4 补充：生成 Business Skill 时必须填写 key_files 和质量评分字段
 
-在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写 `key_files` 字段：
+在生成每个业务 Skill（`.codebuddy/skills/modus-biz-{domain}/SKILL.md`）时，**必须**在 frontmatter 中填写以下字段：
 
-- 列出本域最具代表性的源文件路径（最多 10 个）
-- 优先选择 Service / Manager / Mapper / Domain / Entity 文件
-- 这些文件将用于后续 plan/spec/harness 的「前置 Skill 更新 hash 检查」——若文件内容未变化，则跳过更新，节省 token
+**key_files 填写规则：**
+- 上限 **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 触发前置更新时自动计算并填入
+- 确保 Enum/MQ/ErrorCode/Config 的变化能被 hash 检查感知
+
+**质量评分字段（新增，必须填写）：**
+- `domain_confidence`: 本域的置信度评分（0-10），来自 Step 2 置信度评分矩阵
+- `invariant_count`: 生成的业务不变量条目数（Section 15）
+- `glossary_size`: 领域词汇表条目数（Section 16）
+- `hidden_knowledge_rate`: 隐性知识补全率（已回答问卷数 / 总问卷数，0-100）
 
 ---
 
-## Business Skill 标准格式参考（含知识体系字段）
+## Business Skill 标准格式参考（v3/17节）
 
 ```markdown
 ---
@@ -402,47 +746,321 @@ name: modus-biz-{domain}
 description: "[MODUS:BIZ] {中文域名}业务知识 — {核心职责一句话}"
 version: 1.0.0
 updated: {YYYY-MM-DD}
-maturity: draft             # draft | verified | proven
+status: draft               # draft | verified | proven | stale | archived
+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 内容拼接)，前置更新时自动计算并填入
-key_files:                  # 关键源文件列表，用于 hash 检查（最多 10 个，优先 Service/Manager/Mapper）
+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 访谈问卷
+upstream_skills:            # 本 Skill 在 Section 10 中依赖的其他域 Skill
+  - modus-biz-payment
+  - modus-biz-user
+downstream_skills:          # 依赖本域的其他 Skill（被依赖方）
+  - modus-biz-refund
+key_files:                  # 关键源文件列表，用于 hash 检查（最多 20 个，覆盖全 10 类文件）
+  # 优先级 1：核心业务逻辑（必选）
   - src/.../service/{Domain}Service.java
   - src/.../manager/{Domain}Manager.java
   - src/.../dao/{Domain}Mapper.java
   - src/.../domain/{Domain}.java
+  # 优先级 2：状态与规则（强烈建议）
+  - src/.../enums/{Domain}Status.java
+  - src/.../enums/{Domain}Type.java
+  - src/.../exception/{Domain}Exception.java
+  # 优先级 3：消息与配置（有则加入）
+  - src/.../mq/{Domain}Consumer.java
+  - src/.../mq/{Domain}Producer.java
+  - src/.../config/{Domain}Config.java
 ---
 
 # {中文域名}业务知识
 
+> 由 Modus Skills Builder 自动生成。[MODUS:BIZ]
+
 ## 1. 域概述
-{业务域的职责边界、核心价值，2-3句话}
+
+{业务域的职责边界和核心价值，2-3 句话，人类可读}
+
+**边界说明：**
+- 属于本域：{列举主要职责}
+- 不属于本域：{明确排除的职责}
 
 ## 2. 核心实体 [model]
-| 实体名 | 说明 | 关键字段 |
-|--------|------|----------|
-| ...    | ...  | ...      |
+
+| 实体名 | 中文名 | 说明 | 关键字段 |
+|--------|--------|------|----------|
+| Order  | 订单   | ...  | id, status, tenantId, amount |
+
+### 重要枚举 [model]
+
+\`\`\`java
+// OrderStatus — 订单状态
+CREATED(1, "已创建"),
+PAID(2, "已支付"),
+COMPLETED(3, "已完成"),
+CANCELLED(4, "已取消")
+\`\`\`
 
 ## 3. 业务规则 [process] [guideline]
-- [guideline] {规则1：如 订单状态只能按指定方向流转}
-- [process]   {规则2：如 退款金额不能超过原始支付金额}
-- [pitfall]   {已知坑：如 并发创建订单时需加分布式锁}
 
-## 4. 关键文件 [decision]
-| 层次 | 文件/类 | 说明 |
-|------|---------|------|
-| Controller | ...Controller | ... |
-| Service | ...Service | ... |
-| Mapper | ...Mapper | ... |
+Section 3 最低内容门槛：每个核心字段必含：Java 类型、是否非空、业务含义、关联枚举（如有）
+
+- [process]   {流程规则：如 订单状态只能按 CREATED→PAID→COMPLETED 单向流转}
+- [guideline] {推荐做法：如 退款金额必须 ≤ 原始支付金额，在 Service 层校验}
+- [pitfall]   {已知坑：如 并发创建时若不加锁会出现重复订单}
+- [decision]  {架构决策：如 选择 MQ 异步通知而非同步 RPC，原因是解耦和削峰}
+
+## 4. 关键文件索引 [model]
 
-## 5. API 契约（重要接口）[model]
-- `POST /api/v1/{domain}/create` — {说明}
-- `GET /api/v1/{domain}/{id}` — {说明}
+| 层次 | 类名 | 路径 | 说明 |
+|------|------|------|------|
+| Controller | OrderController | src/.../controller/OrderController.java | 订单 REST 接口 |
+| Service | OrderService | src/.../service/OrderService.java | 订单核心逻辑 |
+| Mapper | OrderMapper | src/.../dao/OrderMapper.java | 订单 DB 操作（注意：在 dao 包下）|
+| Domain | Order | src/.../domain/Order.java | 订单领域对象 |
+
+## 5. API 契约 [model]
+
+Section 5 最低内容门槛：每个接口必含：入参校验规则、成功返回结构、错误码列表、是否需要幂等、权限注解值
+
+| 方法 | 路径 | 说明 | 关键参数 | 权限注解 | 幂等 |
+|------|------|------|----------|----------|------|
+| POST | /api/v1/orders | 创建订单 | amount(必填,>0), productId(必填) | @UserAuthorization | 是（防重token） |
+| GET | /api/v1/orders/{id} | 查询订单 | id(必填) | @UserAuthorization | - |
 
 ## 6. 项目特有模式 [decision] [guideline]
-- [decision] {架构决策：如 选择事件驱动而非同步 RPC 的原因}
-- [guideline] {推荐做法：如 AopContext.currentProxy() 解决事务同类调用}
+
+- [guideline] 事务使用 `AopContext.currentProxy()` 解决同类调用问题（avoid: @Transactional 直接同类调用）
+- [guideline] 分布式锁使用 `@DistributedLock` 注解，key 格式为 `{domain}:{id}`
+- [guideline] 响应统一用 `BaseRpcResponse.build(data)` 包装
 
 ## 7. 典型代码示例
-{重要业务逻辑的代码片段，帮助 AI 理解实现风格}
+
+\`\`\`java
+// 订单创建的标准模式
+public OrderDTO createOrder(CreateOrderRequest request) {
+    // 1. 参数校验（Service 层）
+    // 2. 业务校验（余额、库存）
+    // 3. 创建 Domain 对象
+    // 4. 持久化
+    // 5. 发送 MQ 通知
+    // 6. 返回 DTO
+}
+\`\`\`
+
+## 8. 状态机 [process]
+
+**前置检测条件：** 域中存在含 `status`/`state` 字段的 Entity 才生成本节；否则整节省略，禁止填占位符。
+
+Section 8 最低内容门槛：每条转换必含：起始状态、目标状态、触发条件、触发方法名、是否有事务保护
+
+\`\`\`mermaid
+stateDiagram-v2
+    [*] --> CREATED : createOrder() @Transactional
+    CREATED --> PAID : payOrder() 支付成功回调 @Transactional
+    PAID --> COMPLETED : completeOrder() 确认收货 @Transactional
+    PAID --> REFUNDING : applyRefund() 申请退款
+    REFUNDING --> REFUNDED : processRefund() @Transactional
+    CREATED --> CANCELLED : cancelOrder() 超时/主动取消 @Transactional
+    PAID --> CANCELLED : cancelOrder() 支付后取消（触发退款）
+\`\`\`
+
+| 起始状态 | 目标状态 | 触发条件 | 触发方法 | 事务保护 |
+|---------|---------|---------|---------|---------|
+| CREATED | PAID | 支付成功回调 | payOrder() | ✓ @Transactional |
+| PAID | COMPLETED | 用户确认收货 | completeOrder() | ✓ @Transactional |
+
+## 9. 错误码与异常 [pitfall]
+
+（无条件生成。若为空则写「暂无发现，随工作流积累」，此为合法初始内容，质量自检通过。）
+
+| 错误码 | 异常类 | 触发场景 | HTTP状态 | 处理建议 |
+|--------|--------|---------|---------|---------|
+| ORDER_NOT_FOUND | OrderNotFoundException | 查询/操作不存在的订单 | 404 | 前端展示「订单不存在」 |
+| ORDER_STATUS_INVALID | OrderStatusException | 状态流转不合法 | 400 | 检查当前订单状态后重试 |
+
+## 10. 跨域依赖 [decision]
+
+（无条件生成。若为空则写「暂无发现，随工作流积累」，此为合法初始内容。由主流程 Section 10 回写阶段统一填入。）
+
+**上游依赖（本域调用的其他域）：**
+| 依赖域 | 交互方式 | 调用点 | 说明 |
+|--------|---------|-------|------|
+| payment | RPC @DubboReference | OrderService.createOrder() | 发起支付 |
+| user | RPC @DubboReference | OrderService.checkUser() | 校验用户状态 |
+
+**下游被依赖（调用本域的其他域）：**
+| 调用域 | 交互方式 | 场景 |
+|--------|---------|------|
+| refund | RPC | 退款申请时查询原订单 |
+
+## 11. 数据流向 [process]
+
+**前置检测条件：** 域中存在 `@KafkaListener` / `sendMessage()` / `@RocketMQMessageListener` 才生成本节；否则整节省略。
+
+| 方向 | Topic/方法 | 触发时机 | 消费者/生产者 | 幂等保障 |
+|------|-----------|---------|------------|---------|
+| 发布 | order.created | 订单创建成功 | OrderService → NotifyConsumer | 业务唯一键去重 |
+| 订阅 | payment.success | 支付成功回调 | PaymentConsumer → OrderService | DB 唯一索引防重 |
+
+## 12. 关键 SQL 模式 [guideline]
+
+**前置检测条件：** 域中存在 XML Mapper 文件或含复杂 SQL 的注解（超过 2 表 JOIN 或有子查询）才生成本节；否则整节省略。
+
+Section 12 最低内容门槛：每条复杂 SQL 必含：查询语义说明、JOIN 表关系、索引命中路径、预期返回数据量级、是否存在慢查询风险
+
+| SQL 标识 | 查询语义 | JOIN 表 | 索引命中 | 数据量级 | 慢查询风险 |
+|---------|---------|--------|---------|---------|---------|
+| selectOrderWithItems | 查询订单及明细 | order + order_item | idx_order_id | ~20行 | 低（有索引） |
+| selectByStatusAndDate | 按状态+日期查订单 | order | idx_status_date | 可能万级 | ⚠️ 注意分页 |
+
+## 13. 常见开发陷阱 [pitfall]
+
+（无条件生成。若为空则写「暂无发现，随工作流积累」，此为合法初始内容。）
+
+- [pitfall] 并发创建订单时若不加 `@DistributedLock(key="order:create:{userId}")` 会出现重复订单
+- [pitfall] `OrderStatus` 枚举在数据库存 code 值（int），禁止直接存 name()，避免改名导致数据不一致
+- [pitfall] 跨 Service 调用 `@Transactional` 方法时必须通过 `AopContext.currentProxy()` 代理调用
+
+## 14. 扩展点 [decision]
+
+**前置检测条件：** 域中存在 `interface + 多实现类` 或 `@ConditionalOn*` 注解才生成本节；否则整节省略。
+
+| 扩展点 | 接口/注解 | 当前实现 | 扩展方式 |
+|--------|---------|---------|---------|
+| 支付渠道策略 | PayChannelStrategy | AlipayStrategy, WechatStrategy | Map<String, PayChannelStrategy> 注入 |
+| 订单事件监听 | @ConditionalOnProperty("order.notify") | DefaultNotifyHandler | 实现 OrderEventHandler 接口 |
+
+## 15. 业务不变量 [invariant]
+
+（无条件生成。记录系统必须始终为真的业务约束，违反即为 Bug。来源：if/else 推断 + 校验器分析 + 人工访谈。）
+
+| 不变量描述 | 验证位置 | 违反后果 | 来源 |
+|---------|---------|---------|------|
+| 订单金额必须 > 0 | OrderService:validateAmount() | 抛 InvalidAmountException | 代码推断 |
+| 同一用户同一商品当日限购 5 件 | OrderManager:checkDailyLimit() | 抛 PurchaseLimitException | 代码推断 |
+| 退款金额 ≤ 原始支付金额 | RefundService:84 | 抛 InvalidRefundException | [人工补充: {YYYY-MM-DD}] |
+
+> 若无任何不变量，写「暂无发现，随工作流积累」（此为合法初始内容）。
+
+## 16. 领域词汇表 [model]
+
+（无条件生成。帮助新人理解本域专属术语，消除歧义。来源：类名/枚举值语义分析 + 代码注释 + 人工访谈。）
+
+| 术语 | 定义 | 与通用概念的区别 |
+|------|------|----------------|
+| 订单 | 用户完成商品选购后生成的业务凭证，包含商品明细+支付信息 | 区别于「购物车」（临时）和「合同」（签约后） |
+| 结算 | 将已完成订单的金额从冻结余额转为可提现余额的操作 | 区别于「支付」（资金从用户到平台） |
+| 防重Token | 客户端生成的唯一标识符，服务端用于幂等检查，有效期5分钟 | 项目特有机制，非标准 JWT |
+
+> 若无特殊术语，写「暂无特定领域术语，使用通用定义」（此为合法初始内容）。
+
+## 17. 新人上手指南 [process]
+
+（无条件生成。基于本 Skill 内容自动合成，目标：读完本节即可开始在本域开发，无需找业务方答疑。）
+
+### 开发前必读清单
+
+- [ ] 理解 {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 不变量 |
+
+### 高频踩坑（新人必看，精选自 Section 13）
+
+（自动提取 Section 13 前 3 条 [pitfall]，无内容时写「暂无记录，随工作流积累」）
+
+1. ...
+2. ...
+3. ...
+
+---
+<!-- 更新摘要（由 Skills Builder 自动追加）
+[{YYYY-MM-DD}] 模式A生成：17节完整格式（v3），扫描 {M} 个文件，不变量{I}条，词汇{G}个，隐性知识率{H}%
+-->
+```
+
+---
+
+## 辅助命令
+
+### `/modus:verify {skill-name}`
+
+**定义**：升级 Skill 状态，从 `draft` 升为 `verified`。
+
+**执行逻辑：**
+
+```
+1. 读取 .codebuddy/skills/{skill-name}/SKILL.md 的 frontmatter
+2. 运行质量自检清单：
+   □ Section 3：每个 Entity 字段均有业务含义注释？
+   □ Section 5：所有 Facade 方法均列出了错误码？
+   □ Section 8（如存在）：所有 status 枚举值均出现在状态图中？
+   □ Section 12（如存在）：每条 SQL 均有查询语义说明？
+   □ 无条件生成节（9/10/13）：
+       - 「暂无发现，随工作流积累」是合法初始内容 → 质量自检通过 ✓
+       - 仅在 status 为 stale 时再次执行自检，若三节仍为此内容
+         → 标注 ⚠️「知识库超期且无积累，建议重新扫描或人工补充」
+
+3. 检查 verified 四项条件：
+   条件 1：所有无条件生成节（9/10/13）非空且非占位符
+   条件 2：质量自检清单零 ⚠️ 警告
+   条件 3：计算 key_files 当前 hash，与 last_hash 一致（无 stale）
+   条件 4：人工确认（见下方交互）
+
+条件 4 检查（人工确认环节）：
+  ❓ 是否已有开发者在真实需求中使用「{skill-name}」且无知识缺失反馈？
+     （如果是您本人使用过且满意，也可以确认）[y/N]
+
+  → 用户回复 y：
+      记录：last_verified_by: {运行者用户标识或 "self-verified"}
+            verified_at: {今日 YYYY-MM-DD}
+      条件 4 ✅ 通过，继续检查 verified 合计结论
+
+  → 用户回复 N 或跳过：
+      输出：「条件 4 未满足（尚无开发者真实使用反馈）
+             建议：将此 Skill 用于一个真实开发任务后，再运行 /modus:verify」
+      status 保持 draft，不执行升级
+
+4. 全部通过 → 将 status 从 draft 升为 verified，写入：
+   last_verified_by: {运行者标识}
+   updated: {今日日期}
+   version: 小版本 +1（如 v1.0.0 → v1.0.1）
+5. 未通过 → 列出未达标条件，不修改 status
+```
+
+---
+
+### `/modus:refresh {domain}`
+
+**定义**：对大域未覆盖的文件执行补充扫描，增量合并至已有 Skill。
+
+**执行逻辑：**
+
+```
+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）
 ```