version-sentinel

Claude Code 插件，能够硬性阻止依赖项的添加、升级和降级，除非记录了最新的、附有源引用的版本检查。

**关键词：** Claude Code, Anthropic, AI 编码护栏, LLM 供应链安全, 依赖管理, 幻觉包版本, npm, PyPI, Cargo, NuGet, PreToolUse 钩子。 ## 为什么 LLM 辅助编码会静默地输出模型在其训练数据中记住的任何版本。对于那些发布频繁或存在已知受损版本的包来说，这是不可接受的。`version-sentinel` 强制插入一个“检查注册表”的步骤——同时不阻止你出于特定目的而固定使用旧版本。 ## 它能防止什么 - **幻觉版本** — LLM 选择了一个从未存在或从未发布过的版本。 - **过时的默认版本** — 模型使用了两年前的固定版本，因为其训练数据停留在那个时间点。 - **安装受损发布版本** — 如果没有进行新的注册表查询，就无法防止安装被撤回/恶意的版本。 - **静默降级** — Claude 通过将包回退到存在漏洞的旧版本来“修复” CI 错误。 - **供应链漂移** — 没有选择特定版本原因的审计记录。 ## 它如何进行对比 | 工具 | 范围 | 执行方式 | |------|-------|----------| | `version-sentinel` | Claude Code **PreToolUse 钩子** — 在编辑落地之前阻止工具调用 | 硬性失败，退出码 2 | | 通用的依赖审计工具 | 对 `package.json` / `requirements.txt` 进行事后扫描 | 建议性 | | Dependabot / Renovate | 针对远程注册表的定时 PR 机器人 | 异步 PR | 与事后审计器不同，`version-sentinel` 运行在 **代理循环内部** — 代理无法意外合并一个糟糕的版本，因为在记录被引用之前，写入操作本身会被拒绝。 ## 支持的生态系统 (v0.1) | 文件 | 生态系统 | 注册表 | |------|-----------|----------| | `package.json` | npm/pnpm/yarn/bun | registry.npmjs.org | | `requirements*.txt`, `constraints*.txt` | pip | pypi.org | | `pyproject.toml` | PEP 621 + Poetry + uv | pypi.org | | `Cargo.toml` | Rust | crates.io | | `*.csproj`, `*.fsproj`, `*.vbproj` | .NET | api.nuget.org | 涵盖 `Edit`, `Write`, `MultiEdit` 命令，以及 `Bash` 安装命令（`npm install`, `pip install`, `poetry add`, `uv add`, `cargo add`, `dotnet add package`）。 ## 安装 ``` /plugin marketplace add https://github.com/KSEGIT/Version-Sentinel.git /plugin install version-sentinel@version-sentinel-marketplace ``` ## 前置条件 - `PATH` 环境变量中需包含 `bash`, `jq`, `curl`, `python3` (3.11+，用于 `tomllib`) - Windows 系统：Git Bash 自带 `bash`/`jq`/`curl`；Python 3.13 需要单独安装。 ## 工作原理 1. Claude 尝试添加/升级一个依赖（例如 `Edit package.json`, `npm install X@Y`, ...） 2. PreToolUse 钩子触发，以 stderr 输出并退出，退出码为 2： `BLOCKED: version-sentinel. Package: lodash (npm). Version: 4.17.21. No fresh version check on record.` 3. Claude 运行 `WebSearch "lodash latest version site:npmjs.com"` 4. Claude 调用 `/vs-record npm lodash 4.17.21 https://www.npmjs.com/package/lodash` 5. Claude 重试 — 钩子找到新记录，放行调用。 ## 命令 - `/vs-record ` — 记录一次版本检查 - `/check-versions` — 根据上游注册表审计清单文件 ## 例外情况处理 | 情况 | 方法 | |------|------| | 故意使用旧版本 | `/vs-record npm pkg 1.0.0 "intentional: CVE fix deferred"` | | 一次性会话 | `export VS_DISABLE=1` | | 私有/分叉包 | 将 `ecosystem:pkg` 添加到 `.version-sentinel/ignore` | | 无法使用 WebSearch（非美国地区） | 使用 WebFetch URL 或填写理由 `intentional: no-websearch-region` | ## 附属文件 状态存储在：`/.version-sentinel/checks.json`。首次写入时会自动被 gitignore。 ## 卸载 ``` /plugin uninstall version-sentinel@version-sentinel-marketplace /plugin marketplace remove version-sentinel-marketplace ``` ## 常见问题 **这个工具是与 Claude Desktop 还是 Claude Code 一起工作？** 仅适用于 Claude Code — 依赖于 CLI 暴露的 PreToolUse 钩子 API。 **它会减慢 Claude 的速度吗？** 首次接触某个包时：会增加一次 `WebSearch` 和一次 `/vs-record` 调用（约 5-10 秒）。后续对同一固定版本的编辑会命中缓存的附属文件 — 零开销。 **我可以将其用于私有/内部注册表吗？** 可以 — 将 `ecosystem:pkg` 条目添加到 `.version-sentinel/ignore` 文件，或记录时附上理由字符串。 **为什么不直接运行 `npm audit` / `pip-audit`？** 那些是事后检查。`version-sentinel` 在最初就拒绝写入，因此有漏洞的版本根本不会进入仓库。 **它支持 Go modules, Gradle, Maven, composer, gems 吗？** 在 v0.1 中不支持。请参见 `docs/roadmap.md`。 ## 相关链接 - [Anthropic Claude Code](https://claude.com/claude-code) - [Claude Code 插件文档](https://code.claude.com/docs/en/plugin-dependencies) ## 许可证 MIT — 详见 [LICENSE](./LICENSE)。

标签：AI编程, Cargo支持, Claude Code插件, npm支持, NuGet支持, pip支持, Poetry支持, uv支持, 依赖管理, 依赖阻止, 安全防护, 审计追踪, 幻觉版本防护, 应用安全, 强制版本检查, 暗色界面, 源引用验证, 版本检查, 编码守卫, 软件开发, 逆向工具