| name | flow-health |
| description | [project] 代码库健康巡检器。只产健康报告 + 改造建议清单，不直接改代码。 支持工具路径（brooks-lint / jscpd / knip 等）、GitNexus MCP（语义级未用导出/循环依赖/跨模块检测）和内置 AI 回退三种模式。 Use when 用户说"健康检查/health/体检/技术债扫描/巡检/代码质量检查"，或周期性/里程碑前/接手陌生项目时。
|
| paradigm | scout |
| trigger | [{"pattern":"健康检查|health|体检|技术债|巡检|代码质量|质量检查|债务扫描|debt|lint|sweep|audit","context":"用户想对代码库做健康度评估，不针对某个具体 change"},{"pattern":"每月检查|季度检查|版本发布前检查|接手项目|重构前","context":"周期性或里程碑前的健康巡检场景"}] |
flow-health — 代码库健康巡检
M 前缀表示 Maintenance / 横向命令，不属于任何 change，不写 CHANGE.md / REQUIREMENT.md。直接产出健康报告。
角色
Maintenance Engineer。只产健康报告 + 改造建议清单，不直接改代码。
触发场景
- 周期性：每月 / 每季度跑一次
- 里程碑前：版本发布前 / 季度复盘 / 年终总结
- 接手陌生项目：第一周必跑，了解整体健康度
- 重构决策：决定要不要重构某模块前，先体检
输入
- 仓库根（不限单一 change）
.specs/CONTEXT.md（含技术栈 + 团队偏好）.specs/LESSONS.md（已记录的失败教训）- 最近 N 次的
archive/<date>-<name>/ 归档（看历史趋势）
- 当前 git log 最近 30 天
你的职责
步骤 1 · 选模式
| 场景 | 推荐 | 输出深度 |
|---|
| 快速体检（5~10 分钟） | /brooks-health | 4 维仪表板 + 综合分 |
| 完整审计（30 分钟+） | /brooks-sweep | 6 维 + 6 测试维度 + 架构图 + 技术债 |
| 单维深挖 | /brooks-audit 或 /brooks-debt 或 /brooks-test | 单维度详细报告 |
选择优先级：
- 第一次跑 →
/brooks-sweep（一次拿全貌）
- 周期性 →
/brooks-health（轻量 · 看趋势）
- 拿到 health 报告后想深挖 → 对应单维命令
步骤 2 · 工具路径（首选）
尝试调用 brooks-lint（如项目已装）：
/brooks-sweep
/brooks-health
工具输出原样贴入报告。
步骤 2.1 · GitNexus MCP 语义级巡检（装/未装 brooks-lint 都可跑 · 优先级高于 grep fallback）
GitNexus 可用时，跑以下检测（与步骤 2.5 互补）：
| 检测维度 | GitNexus MCP 工具 | 输出 |
|---|
| 未用导出（public 无调用者） | gitnexus_cypher：查无 IMPORTS/CALLS 入边的 Function/Class | 符号名 + 文件路径 + 🟡候选 |
| 循环依赖 | gitnexus_cypher：查 IMPORTS 双向循环 | 循环链 + 文件路径 + 🔴 Critical |
| 跨模块依赖违例 | gitnexus_impact：domain 层依赖 controller 层等 | 违例符号 + 影响范围 + 🟡 Major |
| 死代码分支 | gitnexus_query：搜索 "if false / unreachable / deprecated" | 符号名 + 文件路径 + 🟢 Minor |
| API shape 不匹配 | gitnexus_shape_check 或 gitnexus_api_impact | 路由 + 消费者 + mismatch 字段 + 🟡 Major |
执行策略：对每个检测维度调用对应 MCP 工具，结果直接贴入报告，标注"GitNexus MCP 语义级检测 · 精度高"。
GitNexus 不可用时：跳过此步，进步骤 2.5 grep fallback。
步骤 2.5 · 冗余巡检（装/未装都要跑）
为什么单独一步：brooks-lint 的 R3 是概念级（同决策多处表达），本步补 4 个字面级 + 死代码级维度。
2.5.1 语言检测
读 .specs/CONTEXT.md「技术栈」段 + 扫清单文件定主语言：
| 清单文件 | 语言 |
|---|
package.json | JavaScript / TypeScript |
pyproject.toml / requirements.txt | Python |
go.mod | Go |
Cargo.toml | Rust |
pom.xml / build.gradle | Java / Kotlin |
composer.json | PHP |
Gemfile | Ruby |
2.5.2 调工具（首选）
| 维度 | 全语言 | TS/JS | Python | Go | Rust |
|---|
| 字面重复块 | npx jscpd src/ | 同左 | 同左 | 同左 | 同左 |
| 未用导出 | — | npx knip / npx ts-prune | vulture | deadcode | cargo udeps |
| 未用依赖 | — | npx depcheck | deptry | go mod tidy -v | cargo udeps |
| 死代码 | — | ESLint no-unreachable | vulture | staticcheck | cargo clippy |
执行策略：
- 优先
jscpd（全语言 · 5 分钟）：npx jscpd src/ --min-lines 5 --min-tokens 50 --reporters json --output .specs/health/tmp/
- 再跑语言原生工具（按上表任选 1-2 个）
- 工具未装 → 提示用户：
ℹ️ 需要跑《<cmd>》，是否授权自动安装？（2 次拒绝 → 进 2.5.3 fallback）
2.5.3 Fallback：AI grep 抓样
用户不肯装工具的退路：
- 重复块：抽样 10 个最近改动的源文件，查 ≥ 5 行连续逻辑块在其他文件的出现
- 未用导出：
grep "^export " 拼符号后反向查引用数，0 次为候选
- 死代码：只抽检明显的（
if false / return 后的语句 / 永负分支）
- 未用依赖：按清单文件逐条 grep 引用次数
在报告里标记：⚠️ 内置 fallback 检测 · 精度低 · 漏报率高 · 建议装 jscpd / knip / vulture / staticcheck
2.5.4 严重度分级
| 分类 | 标准 |
|---|
| 🔴 Critical | ≥ 20 行重复块出现在 ≥ 3 处 · 被跨模块调用的公共导出无引用 · 死分支导致业务规则静默失效 |
| 🟡 Major | 5-19 行重复块 · 明显未使用的 public export · 清单文件顶层未用依赖 |
| 🟢 Minor | < 5 行重复 · 未使用的内部辅助函数 · 注释掉的死代码 · 孤立文档 |
2.5.5 边界（避免误报）
- 测试文件不算未用：
*.test.ts / *_test.go 里的导出在源代码里无引用是正常的
- 公共 API 导出需人工确认：lib / SDK 项目的
index.ts / __init__.py 导出供外部用。标 🟡候选 + 注"需确认是公共 API"
- 跨模块"重复块"常见假阳性：模板化 CRUD / 单测 setup 常长得类似，语义不同 → 不算冷败，留 🟢提示
- 与 flow-review R3 协作：本步是字面级 + 死代码级；flow-review R3 是概念级。两者不互代替
步骤 3 · 未装 brooks-lint（内置回退）
AI 自己按 6+6 维度过一遍主仓库的 src/ / lib/ / app/：
3.1 生产代码 6 维抽样
随机抽 5 个最近改动频繁的模块（用 git log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -5），每个按 6 维（R1~R6）打分。
3.2 测试 6 维抽样
随机抽 5 个测试文件，按 T1~T6 打分。
3.3 架构图
AI 用 grep + import 分析画简化 Mermaid 依赖图，标出循环依赖。
3.4 综合分（自评）
每维度命中数 → 扣分（🔴 -10 / 🟡 -3 / 🟢 -1），从 100 起扣。标注「内置回退评分，仅供参考，建议装 brooks-lint」。
步骤 4 · 输出健康报告
写入 .specs/health/<YYYY-MM-DD>-HEALTH.md，结构见 references/HEALTH.md 模板。
步骤 5 · 反哺到 flow-x 工件
- 🔴 Critical → 自动开新 CHANGE（编号如
health-fix-2026-q1），进入 flow-change
- 🟡 Scheduled → 追加到
.specs/CONTEXT.md「技术债」段
- 🟢 Monitored → 追加到
.specs/LESSONS.md（用 观察 类型 entry）
- 冗余巡检特殊处理：
- 🔴 未用导出 / 死分支 → 合并到 health-fix CHANGE（不单开）
- 🟡 重复块 → 记 CONTEXT.md「技术债」段，标"待抽公共函数"
- 🟡 未用依赖 → 写到 CONTEXT.md「禁动清单」段（标"下次清理窗口移除"），避免 AI 再次为已被移除的库写代码
- 🟢 关联
flow-evolve 下次同步时主动提醒
约束
- 不直接改代码（与 flow-review 同约束）
- 不开多个 fix CHANGE：所有 Critical 合并成 1 个 health-fix change
- 基线对比强制：第二次跑起，必须与上次报告对比
自检
触发下一步
- 有 🔴 Critical → 用户选「现在修」 →
flow-change 开 health-fix change
- 全部 🟡/🟢 → 报告归档，提示用户「下次巡检建议日期：1 个月后」
