Arthur920/Staleguard

# Staleguard

捕捉**文档漂移** —— 即你的 README、`CLAUDE.md` 和 `*.md` 文档中声明的内容已不再受代码支持。Staleguard 会根据实际的代码库检查文档， 并报告哪些内容已经陈旧、错误或缺失。 完全本地且离线运行。其核心是**确定性的** —— 没有模型，没有 API —— 并且 经过调整以实现**零误报**：每一项发现都指向一个具体的路径、 命令、符号或 import 边缘，这些都是文档弄错的地方。 **它能捕捉到什么**，概括来说：损坏的引用（路径、命令、环境变量、 flags、代码符号）、从文本中解析出的架构规则违规、 未记录的公共接口、陈旧的图表，以及随着时间推移产生的漂移（附带 CI 对齐分数）。详细分类请见 [DETAILS.md](DETAILS.md)。 ## 工作原理 确定性核心（**Layer 1**）即为该工具本身。它会根据真实的 代码库检查文档 —— 路径、命令、配置键、入口点，以及从文本中解析出的架构规则与实际 import graph 的对比 —— 并且仅报告它可以 证明是错误的内容。它不需要模型，在 33 万行代码的 repo 上运行仅需约 1.2 秒，并且是 每次安装默认提供的内容。 ``` Layer 1 — DETERMINISTIC (no ML, zero false positives) paths exist? commands real? config keys present? architecture rules hold? ``` ### 实验性 ML 层（可选启用） 在 `ml` 构建功能背后，有两个本地 ONNX 层试图捕捉 确定性核心无法看到的*行为*漂移 —— 例如“缓存在写入时失效”这样的描述： ``` Layer 2 — RETRIEVAL (local embeddings) for each claim, fetch relevant code Layer 3 — VERIFICATION (NLI cross-encoder) (evidence, claim) → supported | contradicted | unverifiable ``` 这些是**实验性的且仅供参考** —— 请将 `contradicted` 判定视为 一个高精度的提示，提醒你去查看，而不是一个拦截门。如果你只想要一个可靠的检查， 推荐仅使用 Layer 1。为满足好奇心，具体方法和测量数据请见 [DETAILS.md](DETAILS.md#status)。 ## 安装说明 ``` # Homebrew (macOS / Linux) brew install Arthur920/tap/staleguard # 或使用 install 脚本 (macOS / Linux) curl --proto '=https' --tlsv1.2 -LsSf \ https://github.com/Arthur920/Staleguard/releases/latest/download/staleguard-installer.sh | sh # 或从源码 cargo install --git https://github.com/Arthur920/Staleguard ``` （Windows：每个 [发布版](https://github.com/Arthur920/Staleguard/releases) 都附带了一个 PowerShell 安装程序。 最近的 Homebrew 版本会提示信任第三方 tap —— 如果 被询问，请运行 `brew trust arthur920/tap`。） 所有这些方式都会为你提供 **Layer 1** —— 确定性的、零误报的核心， 它不需要模型。然后： ``` staleguard check # full repo (Layer 1) ``` ### 实验性 ML 层（Layers 2–3） Layers 2–3 是可选的且仅供参考（在你依赖它们之前，请参阅 [评估](DETAILS.md#status)）。 它们运行本地 ONNX 模型并需要 `ml` 功能，而 预编译的二进制文件省略了该功能（因为 ONNX + embedding 依赖项体积庞大）。有两种方式可以获得支持 ml 的构建版本 —— 两者都是从源码编译，然后在运行时获取模型： ``` # Homebrew (使用 ml feature 编译；与普通的 `staleguard` 冲突) brew install Arthur920/tap/staleguard-ml # 或使用 cargo cargo install --git https://github.com/Arthur920/Staleguard --features ml ``` 然后： ``` staleguard setup # fetch + load every model, offline thereafter staleguard check --layer 3 # all three layers ``` `staleguard setup` 会准备好所有层，并预先显示任何模型下载错误。 （模型文件始终是在运行时下载的 —— 没有单独的“安装模型”步骤。） Layer 3 的判定器是 Hugging Face 上的 [`staleguard`](https://huggingface.co/Arthur920/staleguard) 模型（一个 `microsoft/unixcoder-base` 的 fine-tune 版本）；它会在 `setup` / 首次运行时下载。你可以通过 `STALEGUARD_*` 环境变量覆盖任何模型或阈值 —— 请参阅 [DETAILS.md](DETAILS.md#environment-overrides)。 ## CI 集成 `staleguard check` 在发现任何问题或分数出现回归时会以非零状态退出，因此可以直接 放入 pipeline 中。在你的主分支上提交一个 baseline，然后据此拦截 PR： ``` # 一次，在 base branch 上 —— 将 alignment baseline 记录在 .staleguard/ 下 staleguard check --write-ledger # 在 CI 中对每个 PR —— 仅当 alignment 退化至 baseline 以下时才失败 staleguard check --fail-on-regression ``` GitHub Actions 步骤示例： ``` - name: doc-coherence run: | brew install Arthur920/tap/staleguard # or: cargo install --git https://github.com/Arthur920/Staleguard staleguard check --fail-on-regression --format json ``` 要在 CI 中进行行为检查，请构建 `--features ml` 并运行 `staleguard setup`（在运行之间 缓存模型下载）。 ## 在 AI 辅助编程中使用（MCP / agents） Staleguard 是一个带有 `--format json` 的 CLI，因此任何编程 agent 都可以运行它并读取 返回的发现。有两种将其接入的方法： **1. 作为 agent 直接运行的工具。** 在 Claude Code（或任何具有 shell 访问权限的 agent）中，只需让它调用： ``` staleguard check --format json --diff main ``` 在 `CLAUDE.md` 中的一个好的常规指令：*“在编辑代码或文档后，运行 `staleguard check --format json` 并在完成前修复任何报告的漂移。”* **2. 作为 MCP 服务器。** 通过一个轻量级的命令运行器 MCP（例如一个通用的“运行此 CLI”服务器）通过 Model Context Protocol 公开 staleguard，将 `check_doc_drift` 工具映射到 `staleguard check --format json`。然后 agent 会调用该 工具并接收结构化的发现作为上下文 —— 无需 shell 访问权限。 JSON 输出（每个发现对应一个对象：层、判定、文档引用、代码锚点、 详情）是映射到 MCP 工具结果的契约。 无论哪种方式，都将 agent 指向 JSON 输出，并将 `contradicted` / `stale` 发现作为修复反馈回去。 ## 构建 ``` cargo build # debug binary at target/debug/staleguard cargo test # unit tests cargo build --features ml # with Layers 2-3 cargo run --features ml -- check --layer 3 ``` 深度 AI 辅助的个人项目 —— 参见 [DETAILS.md](DETAILS.md#about-this-project)。 完整的功能分解、性能和环境变量覆盖也请参阅 [DETAILS.md](DETAILS.md)。

标签：CNCF毕业项目, Rust, SOC Prime, 云安全监控, 可视化界面, 开发工具, 文档同步, 网络流量审计, 通知系统, 静态分析