@modus-ai/modus 0.2.10 → 0.2.11

package/templates/skills/modus-init/shared/frontmatter-spec.md

@@ -0,0 +1,255 @@
+---
+title: Frontmatter Spec — 业务 Skill 防腐字段规范（语言无关）
+parent_skill: modus-init
+load_when: "执行 Step 8 生成 Skill 前必读；执行 /modus:verify、/modus:refresh 前必读；任何栈的 strategy 文件都引用本文档"
+---
+
+# Business Skill Frontmatter 规范（防腐机制核心）
+
+> 本文档是**所有栈共用**的 frontmatter 字段规范（语言无关）。Java、Frontend、Go、Python 等所有 strategy 在生成 Skill 时**必须**完整填写下列字段。
+
+---
+
+## 一、基础元数据字段（必填）
+
+| 字段 | 类型 | 含义 | 初始值 |
+|------|------|------|--------|
+| `name` | string | Skill 唯一标识符（与目录名一致） | `biz-{domain}` |
+| `description` | string | 一句话描述，必须包含 `[MODUS:BIZ]` 标记 | 由 strategy 生成 |
+| `version` | semver | 语义化版本号 | `1.0.0` |
+| `updated` | date (YYYY-MM-DD) | 最后更新日期 | 今日 |
+| `status` | enum | 成熟度状态 | `draft` |
+| `format_version` | string | 节结构版本，格式 `v3-{stack}` | `v3-java` / `v3-frontend-react` / ... |
+| `stack` | enum | 主语言栈（与 `modus/config.yaml.primaryStack` 一致） | 由栈检测决定 |
+| `stale_after_days` | integer | 超过此天数自动降为 stale | `90` |
+
+> **关于 `format_version`：** 节骨架（17 节编号 + 名称 + 知识标签）跨栈完全一致；只有节内填充按栈分流。`v3-{stack}` 仅用于让工具/Agent 识别该 Skill 是按哪个 strategy 生成的，便于增量补节时正确选用模板。
+
+---
+
+## 二、防腐机制核心字段（必填，缺少则无法检测代码变更）
+
+| 字段 | 类型 | 用途 | 初始值规则 |
+|------|------|------|-----------|
+| **`last_referenced`** | date | 最后引用时间；超过 `stale_after_days` 自动降级 | = `updated` 日期 |
+| **`usage_count`** | integer | 使用次数；判定成熟度升级（draft→verified→proven） | `0` |
+| **`last_hash`** | SHA-1 string | 全局快速比对入口；不一致时展开 `file_hashes` 逐文件比对 | init 时按下方算法实算 |
+| **`file_hashes`** | map[path→SHA-1] | 文件级 hash；全局 hash 不一致时使用，精准输出"变更文件清单" | 每个 key_files 单独 SHA-1 |
+| **`last_verified_by`** | string | 最后人工验证人；升为 verified 时填写 | `""` |
+| **`verified_at`** | date | 最后验证日期；由 `/modus:verify` 写入 | `""` |
+
+### 标准 hash 计算算法（所有命令统一使用）
+
+```
+1. 对 key_files 中每个文件【单独】计算 SHA-1（写入 file_hashes）
+2. 将「文件路径:SHA-1」对按【文件路径字母序】排序后拼接成字符串
+3. 整体再算一次 SHA-1，得到 last_hash
+```
+
+**Bash 参考实现**（栈无关，所有 strategy 通用）：
+
+```bash
+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` 兼容。
+
+---
+
+## 三、key_files 填写规则（最多 20 个）
+
+`key_files` 是 hash 检测的输入。各 strategy 按本栈优先级选取，**总数上限 20**，超出时按从后往前截断：
+
+> 各栈具体的优先级清单见对应 `strategies/{stack}-init.md` 的"key_files 选取指南"章节。本文档只规定通用原则。
+
+**通用通则：**
+- 必选：业务核心逻辑文件（Service/Hook/Composable/Handler 等）
+- 必选：状态/类型枚举（Status/Type/Schema）
+- 强烈建议：错误处理（Exception/Error/ErrorBoundary 等）
+- 有则加入：消息消费、配置开关、扩展点
+
+---
+
+## 四、质量评分字段（必填，用于知识库质量报告）
+
+| 字段 | 类型 | 用途 |
+|------|------|------|
+| `domain_confidence` | integer 0-10 | 本域置信度评分，来自栈对应的扫描矩阵 |
+| `invariant_count` | integer | Section 15 业务不变量条目数 |
+| `glossary_size` | integer | Section 16 领域词汇表条目数 |
+| `hidden_knowledge_rate` | integer 0-100 | 隐性知识补全率（来自 Step 7 访谈问卷） |
+| `contract_version` | string | 本域对外暴露接口的当前版本（初始 `"1.0"`） |
+
+---
+
+## 五、跨域依赖字段（Section 10 回写阶段自动填入）
+
+| 字段 | 类型 | 用途 |
+|------|------|------|
+| `upstream_skills` | string[] | 本域依赖的其他域 Skill 列表 |
+| `downstream_skills` | string[] | 依赖本域的其他域 Skill 列表 |
+| `stale_cascade` | boolean | 联动失效标记；upstream 任一 hash 变更时自动置为 true |
+
+---
+
+## 六、外部依赖感知字段（init 自动从构建文件提取）
+
+| 字段 | 类型 | 含义 | 提取来源 |
+|------|------|------|---------|
+| `external_deps` | map[string→semver-range] | 本域规范依赖的外部库版本范围 | 按栈而异：见下表 |
+
+### 各栈提取来源
+
+| stack | 提取自 | 排除规则 |
+|-------|--------|---------|
+| `java` | `pom.xml` `<dependencies>` | 排除 `java.*`、`javax.*`、`org.springframework.*`（框架级，不属于域规范） |
+| `frontend-*` / `backend-node` | `package.json` `dependencies + devDependencies` | 排除 `@types/*`、`eslint-*`、`prettier-*`、`@testing-library/*`（工具链级） |
+| `go` | `go.mod` `require` | 排除标准库（无前缀） |
+| `python` | `pyproject.toml` `dependencies` | 排除标准库 |
+
+### 检测时机
+
+| 时机 | 行为 |
+|------|------|
+| `/modus:init` 生成 Skill | 自动扫描该域代码 import 频率最高的前 5 个第三方库，记录 semver-range |
+| `/modus:init --enhance` 增量更新 | 重新扫描，对比版本变化 |
+| `modus update` | 检查 `external_deps` 中的库是否发生 **major version** 升级（如 `2.x → 3.x`），是则将该 Skill 降级为 `stale`，追加 `⚠️ 外部依赖 {lib} 升级（{old} → {new}），规范需验证` |
+
+### 示例
+
+```yaml
+# Java 域示例
+external_deps:
+  spring-boot: "~2.7"
+  mybatis-plus: ">=3.5 <4.0"
+  dubbo: "~3.1"
+
+# 前端 React 域示例
+external_deps:
+  react: "^18.2"
+  "@tanstack/react-query": "^5.0"
+  zustand: "^4.4"
+  "react-hook-form": "^7.45"
+  zod: "^3.22"
+```
+
+---
+
+## ⛔ 防腐字段缺失的后果
+
+如果 frontmatter 缺少上述任一防腐字段（特别是 `last_referenced`、`usage_count`、`last_hash`、`file_hashes`、`key_files`、`stack`），将导致：
+- 无法自动检测代码变更（hash 比对失效）
+- 无法触发 Skill 更新
+- 无法计算知识衰减
+- 无法跨栈识别 Skill 来源
+- **防腐机制完全失效**
+
+> 所有 strategy 文件在 Step 8 中都必须二次校验 frontmatter 完整性，缺字段时自动补 `""` 或 `0` 占位，不允许直接漏写。
+
+---
+
+## 七、frontmatter 模板（语言无关参考）
+
+> 各 strategy 在 Step 8 生成 Skill 时，应以此模板为基础，仅修改 `name` / `stack` / `format_version` / `key_files` 等栈相关字段。
+
+```yaml
+---
+name: biz-{domain}
+description: "[MODUS:BIZ] {中文域名}业务知识 — {核心职责一句话}"
+version: 1.0.0
+updated: {YYYY-MM-DD}
+status: draft
+format_version: v3-{stack}      # v3-java / v3-frontend-react / v3-frontend-vue / ...
+stack: {stack}                  # 与 modus/config.yaml.primaryStack 一致
+stale_after_days: 90
+last_referenced: {YYYY-MM-DD}
+usage_count: 0
+last_hash: ""                   # init 时按标准算法实算后写入
+file_hashes: {}                 # init 时每个 key_files 单独 SHA-1
+last_verified_by: ""
+verified_at: ""
+domain_confidence: 0
+invariant_count: 0
+glossary_size: 0
+hidden_knowledge_rate: 0
+contract_version: "1.0"
+upstream_skills: []
+downstream_skills: []
+stale_cascade: false
+external_deps: {}               # 见本文档第六节
+key_files:                      # 详见各 strategy 的优先级规则，最多 20 个
+  - {按栈而异，由 strategy 决定}
+---
+```
+
+---
+
+## 八、Status 生命周期与衰减规则
+
+> 本节为所有栈通用，与 strategy 无关。
+
+### Status 生命周期
+
+```
+draft → verified → proven
+                       │  (超过阈值未引用)
+verified ←─────────────┘
+   │
+   │ (超过阈值未引用)
+   ▼
+stale
+   │ (超过 stale_after_days)
+   ▼
+archived (需人工确认)
+```
+
+| status | 含义 | 升级条件 | 禁止行为 |
+|--------|------|---------|---------|
+| `draft` | 初始生成，未经验证 | `/modus:verify` 通过四项检查 → `verified` | - |
+| `verified` | 经至少 1 次真实使用验证 | `usage_count ≥ 2` 且不同工作流 → `proven` | - |
+| `proven` | 经 ≥2 个不同工作流验证 | - | - |
+| `stale` | hash 不匹配或衰减超期 | `/modus:refresh` → `draft` | **禁止直接引用** |
+| `archived` | 域已废弃 | - | **禁止引用** |
+
+### 活跃度感知衰减（基于 `usage_count`）
+
+| 活跃度 | usage_count | verified→stale 阈值 | proven→verified 阈值 |
+|--------|------------|----------------------|----------------------|
+| 活跃域 | ≥ 10 | 12 个月 | 24 个月 |
+| 正常域 | 3-9 | **6 个月（默认）** | **12 个月（默认）** |
+| 冷门域 | ≤ 2 | 3 个月 | 6 个月 |
+
+---
+
+## 九、同步副本管理规约
+
+> 本节适用于所有平台（codebuddy / claude / cursor / continue / codex / copilot / 自定义）。
+
+### 权威源 vs. 副本
+
+| 文件 | 角色 | 防腐字段权威性 | 更新方式 |
+|------|------|-------------|---------|
+| `modus/knowledge/biz-{domain}/SKILL.md` | **权威源** | 所有防腐字段的唯一权威存储 | 命令直接写入 |
+| 各平台同步副本（`.codebuddy/skills/biz-*/`、`.claude/agents/modus-biz-*.md`、`.continue/skills/biz-*/` 等） | 只读快照 | 仅通过 `<!-- modus:meta -->` 注释暴露核心字段 | Step 9 同步时自动更新 |
+
+**关键原则：**
+- 所有防腐机制的触发（hash 比对、衰减计算、`usage_count` 更新）**只操作 `modus/knowledge/` 权威源**
+- 副本变更不触发防腐机制
+- 副本与权威源不一致时，以权威源为准，下次同步强制覆盖
+
+### 机器可读 meta 注释（供工具层解析）
+
+副本文件（如 `.claude/agents/modus-biz-{domain}.md`）顶层 frontmatter 之后必须插入：
+
+```markdown
+<!-- modus:meta
+last_hash: "{从权威源读取}"
+status: "{从权威源读取}"
+updated: "{从权威源读取}"
+stack: "{从权威源读取}"
+-->
+```
+
+工具层优先读取此注释，不解析正文中的二级 frontmatter。

package/templates/skills/modus-init/shared/stack-detection.md

@@ -0,0 +1,144 @@
+---
+title: Stack Detection — modus-init Step 0.5 单一真相来源
+parent_skill: modus-init
+load_when: "Router SKILL.md 执行 Step 0.5 时读取本文档；其他命令（auto/harness/spec）需要确认主栈时也可读取"
+---
+
+# 栈检测规则（Stack Detection）
+
+> 本文档定义 `/modus:init` Router 在 **Step 0.5** 如何探测项目主语言栈，并将结果写入 `modus/config.yaml` 的 `primaryStack` 字段，从而路由到对应的 strategy 文件。
+
+---
+
+## 1. 检测顺序与决策树
+
+按以下顺序逐项检查项目根目录，**第一个命中的即为主栈**（不再继续）：
+
+```mermaid
+flowchart TD
+    START([Step 0.5 开始])
+    START --> JVM{"pom.xml / build.gradle\n / build.gradle.kts ?"}
+    JVM -->|是| JAVA["primaryStack = java"]
+    JVM -->|否| GO_CHK{"go.mod ?"}
+    GO_CHK -->|是| GO["primaryStack = go"]
+    GO_CHK -->|否| PY_CHK{"pyproject.toml /\nrequirements.txt / setup.py ?"}
+    PY_CHK -->|是| PY["primaryStack = python"]
+    PY_CHK -->|否| RUST_CHK{"Cargo.toml ?"}
+    RUST_CHK -->|是| RUST["primaryStack = rust"]
+    RUST_CHK -->|否| PKG_CHK{"package.json ?"}
+    PKG_CHK -->|否| FALLBACK["primaryStack = fallback\n(走通用 Glob 兜底)"]
+    PKG_CHK -->|是| DEPS["读取 dependencies +\ndevDependencies"]
+    DEPS --> NEST{"@nestjs/core /\nexpress / fastify / koa ?"}
+    NEST -->|是| NODE["primaryStack = backend-node"]
+    NEST -->|否| NUXT{"vue / nuxt / @vue/cli ?"}
+    NUXT -->|是| VUE["primaryStack = frontend-vue"]
+    NUXT -->|否| REACT{"react / next / @remix-run /\nvite + react?"}
+    REACT -->|是| REACTSTACK["primaryStack = frontend-react"]
+    REACT -->|否| OTHER_FE["primaryStack = frontend-other"]
+```
+
+---
+
+## 2. 探测信号矩阵（精确判定规则）
+
+| 信号文件/字段 | 命中后的 primaryStack | 路由到的 strategy 文件 |
+|--------------|----------------------|--------------------|
+| `pom.xml` | `java` | `strategies/java-init.md` |
+| `build.gradle` / `build.gradle.kts` | `java` | `strategies/java-init.md` |
+| `go.mod` | `go` | `strategies/fallback-init.md`（Phase 4 起改为 `go-init.md`） |
+| `pyproject.toml` / `requirements.txt` / `setup.py` | `python` | `strategies/fallback-init.md`（Phase 4 起改为 `python-init.md`） |
+| `Cargo.toml` | `rust` | `strategies/fallback-init.md` |
+| `package.json` 中 `dependencies/devDependencies` 含 `@nestjs/core` / `express` / `fastify` / `koa` | `backend-node` | `strategies/fallback-init.md`（Phase 4 起改为 `node-init.md`） |
+| `package.json` 含 `vue` / `@vue/cli` / `nuxt` / `nuxt3` | `frontend-vue` | `strategies/frontend-init.md`（§Vue 子流程） |
+| `package.json` 含 `react` / `next` / `@remix-run/react` / `@tanstack/router` | `frontend-react` | `strategies/frontend-init.md`（§React 子流程） |
+| `package.json` 但无上述任意框架 | `frontend-other` | `strategies/frontend-init.md`（§通用前端兜底） |
+| 以上全部未命中 | `fallback` | `strategies/fallback-init.md` |
+
+---
+
+## 3. 多栈共存（混合 monorepo）处理
+
+如果同一仓库**同时**存在多种栈标志（例如 `pom.xml` + `package.json`，典型的"前后端一仓"），按以下策略：
+
+### 3.1 自动模式（带 `--force` 时）
+
+按以下优先级选主栈：
+```
+backend-java > backend-node > frontend-react > frontend-vue > python/go/rust > fallback
+```
+> 优先选后端是因为：业务模型核心通常在后端，前端往往以"消费者"身份存在；harness/plan 命令更依赖后端语义。
+
+### 3.2 交互模式（默认）
+
+向用户展示检测结果，让其手动确认：
+
+```
+检测到本项目存在多个技术栈：
+  ✓ Java (pom.xml — Spring Boot)         — 推荐主栈
+  ✓ React (package.json — react@18.x)
+
+请选择主栈（决定 modus init 使用哪份扫描规则）：
+  [1] java          — 后端 Java 项目（5 轮扫描，17 节业务 Skill）★ 推荐
+  [2] frontend-react — 前端 React 项目（前端版 5 轮扫描，17 节前端化 Skill）
+  [3] 两栈分别独立 init  — 适用 monorepo 两个独立可发布单元
+  [4] 自定义           — 手动指定 primaryStack 值
+
+> _
+```
+
+选项 [3] 为高级模式：
+- 提示用户在 `modus/config.yaml` 中将项目升级为 workspace（`modus-workspace.yaml`）
+- 每个子目录独立运行 `/modus:init --project <name>`
+- 详见区块 A 主流程 Step 3 的"多项目工作区检测"
+
+---
+
+## 4. 写入 modus/config.yaml
+
+栈检测完成后，必须写入：
+
+```yaml
+primaryStack: java                # 见 PrimaryStack 类型定义
+# 其他字段保持不变 ...
+```
+
+后续 `/modus:vibe`、`/modus:plan`、`/modus:spec`、`/modus:harness` 在加载知识时会读取该字段，决定如何渲染上下文。
+
+---
+
+## 5. Skill frontmatter 的 `stack` 字段
+
+每个生成的业务 Skill（`modus/knowledge/biz-*/SKILL.md`）必须在 frontmatter 中包含 `stack` 字段，与 `primaryStack` 保持一致：
+
+```yaml
+---
+name: biz-order
+stack: java                       # 与 modus/config.yaml.primaryStack 一致
+format_version: v3-java           # v3-{stack}：节骨架统一，节内填充按栈分流
+# ...
+---
+```
+
+> 通用知识库原则：**节号、节名、知识标签**跨栈完全一致；只有节内**填充语义**按 `stack` 分流。
+
+---
+
+## 6. 失败兜底
+
+如果检测过程中遇到异常（如 `package.json` 损坏无法解析），主流程必须：
+- 不中断 init 流程
+- `primaryStack = fallback`
+- 在 Step 14 完成回报中给出明确警告：`⚠️ 栈检测降级为 fallback，原因：{异常摘要}。可手动修改 modus/config.yaml.primaryStack 后重跑 /modus:init`
+
+---
+
+## 7. 与 CLI `detectTechStack()` 的关系
+
+`src/commands/init.ts` 中的 `detectTechStack()` 函数仅用于**`modus init` CLI 阶段的展示型描述**（如 `"Java Maven, MySQL"`），它输出的是**人类可读字符串**。
+
+本文档定义的栈检测发生在 **`/modus:init` Skill 阶段**（用户在 AI 工具中执行），输出的是**机器可路由的枚举值**。两者目标不同，互不替代：
+
+| 阶段 | 工具 | 输出 | 用途 |
+|------|------|------|------|
+| `modus init`（CLI） | `detectTechStack()` | `"Java Maven, Spring Boot, React"` | 写入 `config.techStack`，展示给用户看 |
+| `/modus:init`（Skill） | 本文档定义的检测 | `primaryStack: "java"` | 路由到对应 strategy 文件 |