pinright

pinright

适用于编码 Agent 的精确版本文档和依赖检查。 Agent 获取库版本的途径有两种：其记忆中保存的信息——在我们的基准测试中，它写入的版本锁定中约有 40% 存在已知安全公告；或者文档 MCP 服务，它会返回文档，但不会检查版本是否存在安全公告。pinright 为它提供所安装确切版本的文档，并在安装运行前对每个新增依赖项给出判定。MCP 服务、安装前钩子、CLI 和 GitHub Action，全部在本地运行。

安装

需要 Node 20.9 或更高版本。一行命令，然后重启 Agent：

npm i -g pinright && pinright init --user   # just you, every project; the hook starts in about 0.2 s
npx -y pinright init                        # your team: writes project files you commit

init 会配置 MCP 服务、客户端支持时可用的安装前钩子，以及一个初始 .pinright.json。共支持 16 个客户端；其中 6 个有钩子：Claude Code、Cursor、VS Code（GitHub Copilot）、OpenAI Codex、Gemini CLI 和 Windsurf。上方的 Cursor 和 VS Code 按钮只会添加 MCP 服务。查看所有客户端、作用范围和 pinright doctor。

不使用 pinright 与使用 pinright

不使用。 Agent 运行 npm install [email protected]。安装成功。现在锁文件中带有 5 个安全公告，其中 2 个为高危，却无人知晓。

使用。 命令运行前，钩子会作出响应，Agent 会看到：

pinright blocked this dependency change:
- [email protected] (npm) has 5 known advisories (CVE-2021-23337, CVE-2026-4800, CVE-2020-28500, HIGH). Use 4.x release 4.18.1: npm install [email protected]
Change the version (or the name) and try again. check-package and get-docs from the pinright MCP server explain each case.

Agent 会在同一发布系列中重试，改用 4.18.1。如果先询问，check-package 和 get-docs 会给出相同的判定，其中包含完整的安全公告列表、建议锁定的版本，以及该版本的文档。以下为 2026-11-01 运行 pinright hook claude 的实际输出。

为什么选择 pinright

文档类 MCP 服务会返回库的文档，但不会检查 Agent 固定的版本，也看不到安装情况。为了衡量这类服务，我们关闭安全层后运行了 pinright 自己的服务（PINRIGHT_ABLATION=docs-only）：返回所请求版本的文档，不提供判定。它不是另一个产品。使用 Claude Code 和 Sonnet 5.5、Haiku 5.5、Opus 5.5，每个单元格运行 2 次，基于 1.0.0 代码；每个单元格给出三个模型的范围。

	无文档	仅文档上下文服务	pinright
已知存在安全公告的直接依赖	40% 至 42%	0% 至 2%	0%
每个项目的全树警报数（npm audit、pip-audit）	29.8 至 31.9	0.3 至 3.5	0.3
使用当前 API 的文档任务	16 项中 9 至 14 项	16 项中 15 或 16 项	16 项
每个 Agent 任务的 Token 数	15k 至 21k	56k 至 94k	42k 至 74k
每个文档任务的 Token 数	17k 至 23k	94k 至 135k	63k 至 95k
每个 Agent 任务的 Agent 轮数	4.0 至 4.3	9.3 至 11.1	5.9 至 7.5
每个 Agent 任务读取的 MCP 工具文本	无	25k 至 45k 个字符	5k 至 17k 个字符
对 Agent 固定版本的判定	无	无	安全公告、恶意软件、仿冒包、不存在的版本
安装运行时检查	无	无	在 6 个客户端中使用安装前钩子
全树锁文件审计	无	无	check-manifest、SARIF、GitHub Action

仅提供当前文档就消除了大部分警报；判定则消除了其余警报。按模型分别计算，在 12 项 Agent 任务中，pinright 比仅文档服务少用 21% 至 26% 的 Token；在 8 项文档任务中少用 26% 至 33%。所有配对区间都高于零；最低下界为 2%。Token 数统计模型处理的全部内容，包括缓存读取。不使用任何工具的成本低于两者。

Token 更少的原因。 仅提供文档时，Agent 会通过文档查询版本：每个 Agent 任务中，它在写入文件前会对每个包调用一次 get-docs，共 5.2 至 5.7 次。87% 的调用未指定版本，因此返回的是最新版本的文档；75% 的查询中询问了“版本”或“最新”。使用 pinright 时，每次 Agent 任务运行都会先对整个列表调用 check-packages，获得约 600 个字符的判定和待固定版本；之后每项任务调用 get-docs 0.7 至 1.7 次，其中 87 次调用有 86 次指定了版本。

局限。 剩下的 0.3 是 nuxt；它的当前版本会引入尚无修复版本的包。不指定版本安装也会得到同样的 0.3，而且仅文档服务与 pinright 的警报区间有重叠。数据来自一家供应商的模型、我们编写的任务、未启用 Shell，以及两天的安全公告数据，样本量较小。在第二轮启用 Shell 的测试中，Agent 会先通过 npm view 或 pip index 查询版本再固定，因此每种方案最终都达到每个模型 6 个警报：在这种情况下，pinright 对固定版本没有可测量的影响。对于 2026 年 8 月之后发布的 API，不提供文档时 48 次运行中有 2 次使用了当前 API；仅文档时为 45 次，pinright 为 46 次。在从公开 GitHub issue 中选取的 12 项任务中，不提供文档时 25% 至 29% 的直接固定版本带有安全公告，使用 pinright 时则没有。该钩子在 25,077 条公开命令中拦截或询问了 1.46%，并误读了我们一个月 Agent 会话中的 154,402 次工具调用中的 10 次。 各模型数据表 · 结果与注意事项 · 技术报告 · 复现测试

询问你的 Agent

• “添加 zod，并固定一个没有已知安全公告的版本。”
• “显示这个项目已安装版本的 next 文档。”
• “审计 package-lock.json，并告诉我需要升级哪些包，同时保持在相同的发布系列中。”
• “在我迁移之前，express 4 和 5 之间有哪些变化？”

工具

工具	功能
check-packages	一次调用可检查最多 50 个软件包：应固定的版本、简短原因，以及仅在需要时提供的完整通知
check-package	深入检查单个软件包：包含 CVE 和修复方案的安全公告、弃用情况、许可证、名称相似的软件包、策略违规
get-docs	获取已发布软件包及其仓库在发布标签处的文档，适用于指定版本或已安装的版本
find-library	将库名称映射到注册表软件包（next.js 映射到 npm:next），并给出安全版本
upgrade-guide	说明两个版本之间的变化：重大变更、重命名的 API，以及此次升级可修复的安全公告
check-manifest	审计整个锁文件或清单树，并生成 SARIF；GitHub Action 会在 CI 中运行此检查

支持的生态系统：npm、PyPI、Cargo、Go、Maven 和 Gradle、NuGet、RubyGems、Composer、GitHub Actions。 如果数据源未返回结果，判定结果绝不会显示为 ok。提交到仓库的 .pinright.json 可设置允许和 拒绝列表、许可证规则、严重性阈值，以及数据源不可用时的处理方式。 工作原理 · 钩子 · 团队策略 · CLI · GitHub Action

隐私与限制

无需账户，不收集遥测数据。pinright 会将软件包名称和版本发送到 deps.dev、OSV、各注册表、jsDelivr 和 GitHub，绝不会发送你的代码； SECURITY.md 列出了每个主机。钩子会静态读取命令和文件：它是防护措施，不是沙箱； 威胁模型 列出了哪些内容可能绕过它。如果数据源不可用，内置默认设置会允许安装通过； 入门策略则会改为询问。

更多信息

安装 · 提示词注入 · 基准测试 · 安全审查 · 更新日志 · 贡献指南 · 发布操作手册

我们最看重的报告是误报：钩子拦截了本应放行的命令，或标记了本应通过的软件包。请使用模板新建 issue，并粘贴命令及 npx pinright doctor --json 的输出。如需报告 pinright 中的漏洞，请按照 SECURITY.md 中的说明私下提交。

MIT。由 Hiper AI 构建（[email protected]）。 网站：pinright.dev。所有参与者均须遵守 行为准则。