仓库健康扫描 chenyinrusi/dsh-repo-health

repo-health

只读仓库健康扫描器：定义漂移、未接线模块可达性、提示词膨胀、证据门校准和注册完整性——以 CLI 和 MCP 服务器的形式提供。

代码库会无声地腐烂。最具破坏性的缺陷是任何测试、类型检查器或 linter 都捕捉不到的那些：

- 一个概念在两处定义，但只有一份副本会被更新（漂移），
- 一个模块已经写好但从未接线（不可达），
- 一个固定注入的提示词片段悄悄吞噬上下文（膨胀），
- 一个扩展点存在但从未注册（注册）。

repo-health 是五个只读扫描器，专门监视这些问题。它是一个大型生产级 agent 系统背后质量守护工具经过提取和泛化的核心，被重新打包，使任何仓库都能运行它。

安装

pip install "dsh-repo-health" # CLI
pip install "dsh-repo-health[mcp]" # + MCP server

需要 Python 3.11+（registration 扫描器使用 tomllib；其他扫描器可在 3.10+ 上运行）。

快速开始

repo-health drift --root /path/to/repo # definition drift report
repo-health reach --root /path/to/repo # unwired-module report
repo-health prompt-bloat --root /path/to/repo # prompt segment shares
repo-health evidence --path logs/evidence_gate.jsonl
repo-health registration --root /path/to/repo --config registration.toml
repo-health all --root /path/to/repo # run every scanner

每个扫描器还附带一个 --selftest，它会在被信任用来评判你的代码之前，用合成 fixture 验证工具自身——这些扫描器的前身在发布时曾产生过漂亮但错误的数字，只有已知答案的 fixture 抓住了它们。

五个扫描器

drift —— 多源定义漂移

检测同一名称在多个位置定义且成员结构重叠的情况，并在其中一份副本发生变化而另一份没有变化时标记它。

- A 类（受保护）：同名且结构重叠 ≥ 0.5——被监视是否发生漂移。
- B 类（不受保护）：同名，结构不相交——名称冲突，令人困惑但不是数据风险。
- 同步变更通过。 如果有人勤勉地更新了两份副本，那是正确行为；惩罚这种行为的保护机制会被禁用。

repo-health drift --root . # report
repo-health drift --root . --write-baseline # freeze a baseline
repo-health drift --root . --check # exit 1 on drift / new pairs

reach —— 未接线模块可达性

构建导入图，并从启动入口点（__main__.py、if __name__ == "__main__" 保护块、main.py、启动脚本）进行 BFS 搜索。无法到达的模块就是“已接线但已死”。

它的基线带有可审计的原因：每个不可达模块都需要一个结构化的 {verdict, anchor} 条目，并以确定性方式验证（V1–V7），因此单个错误原因永远无法永久地将代码从所有机制中隐藏起来。

repo-health reach --root . # 报告 repo-health reach --root . --write-baseline # 冻结 repo-health reach --root . --check # 存在新的未接线模块时以退出码 1 退出 repo-health reach --root . --audit-reasons # 校验基线原因

prompt-bloat — 提示词片段占比基线

读取提示词检查 JSONL 日志（{segments: [{name, pct, kind}]}），并观察每个片段的占比中位数，而非绝对大小（绝对大小会随任务复杂度自然变化；占比才反映结构性膨胀）。

repo-health prompt-bloat --root . --check --json

evidence — 证据门决策日志校准

汇总决策日志（{passed, suggested_action, tool, issues} JSONL），以
回答“这个门是否已经校准好了？”——样本不足或某个工具容易产生假阳性，都会使任何结论无法成立。

registration — 配置驱动的注册完整性

在 TOML 配置中声明你架构的扩展点，并验证每个已定义项都出现在其注册表中。参见 config/registration.example.toml 中带注释的示例，涵盖 agent 角色、检查器、API 路由、侧边栏页面和 LLM 提供方。

MCP 服务器（DeepSeek Harness 及任何 MCP 客户端）

pip install "dsh-repo-health[mcp]"
python -m repo_health.mcp_server

将扫描器作为只读 MCP 工具暴露（drift_scan、reach_scan、 reach_reason_audit、prompt_bloat、evidence_calibration、registration）。
将其注册到 DeepSeek Harness 的 MCP 设置（或任何 MCP 客户端）中，让 agent 诊断自己的仓库。大型仓库可能超出 MCP 的默认工具超时——请传入更窄的 root 值或提高客户端超时。

方法论（为什么这不是“又一个 linter”）

这些扫描器共享一套历经艰难才学到的纪律：

1. 观察事件，而非状态。“重复”是一种状态；“一侧变了而另一侧没变”才是真正破坏数据的事件。
2. 守卫不得惩罚正确行为。 同步更新应通过；否则守卫会在一周内被禁用。
3. 绝不要从不足的样本中冻结基线。 来自三条记录的中位数不是事实——据此冻结的基线是虚假的自信。
4. 原因必须可校验。 自由文本的基线理由正是
代码永久躲过所有机制的方式；让它们成为 {verdict, anchor}。
5. 在扫描器评判任何东西之前，先对它进行自测。 已知答案的测试夹具是唯一能抓住前身错误但看似合理输出的东西。

已知限制

- drift 仅扫描 Python（配置的包目录下的 .py）。
- reach 是模块粒度的：一个可达模块，即使其函数从未被调用，也不会被报告；动态导入（importlib、插件加载器）不可见，应归入基线。
- evidence 和 prompt-bloat 使用特定的 JSONL schema；请调整你的日志器以输出该格式（示例见 docstring）。

许可证 MIT © 2026 陈（Jarry）潘