# @figo5/diffguard 中文文档

规范地址：https://npmcn.com/package/%40figo5/diffguard/

版本：0\.1\.3
npm 元数据更新时间：2026-08-07T21:46:59.603Z
中文译文更新时间：2026-11-14T17:34:58.631Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40figo5/diffguard
原文对照：https://npmcn.com/package/%40figo5/diffguard/?lang=original
项目主页：https://github.com/Figo5/diffguard#readme
源码仓库：https://github.com/Figo5/diffguard

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：123 kB，83 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-08-07T15:52:07.212Z
- 最新版本发布：2026-08-07T21:46:59.445Z
- 近 30 天下载量：6083（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

使用您自己的 Anthropic API 密钥对安全问题和意外行为进行修改的审计代码 .

## 安装

```sh
npm install @figo5/diffguard
```

也可以使用：`pnpm add @figo5/diffguard`、`yarn add @figo5/diffguard`、`bun add @figo5/diffguard`

## README

# Diff 守护

审计代码更改 **安全问题** 财务报告和审定财务报表 **意外行为改变** 使用您的 拥有 Anthropic API 密钥。 DiffGuard读出一个""字",发给Claude审查,然后 打印结构化的发现——或者在无出错时干净地退出. 修建于 终端:在任何一台机器上工作 `git` 和节点,直入CI 承诺前钩.

## 安装

```bash
npm install -g @figo5/diffguard
```

## 设置

```
diffguard config
```

`diffguard config` 通过选择供应商(Anthropic, OpenAI, OpenRouter, Groq, Ollama, 或自定义的 OpenAI 兼容基础 URL, 选择一个模型并存储您的 平台密钥链中的API密钥. 后来,平地 `diffguard` 只是工作,没有inv vars 需要帮助。 非交互设置也可用:

```
diffguard config --provider=ollama --model=gemma4:e2b
diffguard config --show    # print the effective config (never the key)
diffguard config --reset   # clear the saved config
```

说明: `diffguard config --key=...` 将密钥放入可见的命令行 以及任何能列出机器上进程的人 喜欢 交互式向导( e)`diffguard config`)或(或) `diffguard key set`,从 a 读取密钥 隐藏快取或 stdin 代替 .

您仍然可以使用 Env vars 来配置所有的东西 —— 见配置表 . Env vars 总是覆盖已保存的配置文件 .

## 使用量

```bash
diffguard            # audit the working-tree diff
diffguard --staged   # audit the staged diff (pre-commit)
diffguard --json     # machine-readable output
diffguard config    # one-time setup: provider, model, and key
```

### 编码代理

DiffGuard作为编码代理内部的点播审计工具:

-   **Pi** ——安装扩展到 `~/.pi/agent/extensions/pi.ts` (或 `.pi/extensions/pi.ts`) (中文(简体) ).
-   **MCP 有能力的剂** (Claude Code, Codex, Cursor, Windsurf, Copilot, Cline)——运行该程序 `diffguard-mcp` stdio服务器并加入为MCP服务器.

特工打电话来 `diffguard_audit` 带有工具的工具 `scope` 参数 :

| 范围 | 审计 |
| --- | --- |
| `working` (默认) | 未承诺的变动 |
| `staged` | 基特指数(承诺前) |
| `file:<path>` | 一个文件 |
| `repo` | 整个仓库(仅安全) |

该工具返回文本报告加上结构化结果。 API 密钥从 代理人本人的证书(Pi), `ANTHROPIC_API_KEY`键链 (单位:千美元)`diffguard key set`) (中文(简体) ). 密钥从未进入代理上下文 .

代理层读取与 CLI 相同的已保存的配置文件, 所以提供者和模型化您 配置为 `diffguard config` 也适用于 Pi 和 MCP 。 (当地供应商,如Ollama) 在代理环境中仍然需要一个密钥——设置 `ANTHROPIC_API_KEY` 至任何数值。 )

### 退出代码

| 代码 | 含义 |
| --- | --- |
| 0 个 | 清洁——无结果 |
| 1个 | 调查结果 |
| 2个 | 出错( 丢失密钥, 不是 git repo, 审计失败) |

用作承诺前门:

```bash
# .git/hooks/pre-commit, or via a pre-commit framework
diffguard --staged || exit 1
```

### 示例

```
$ diffguard
[security] high  src/auth.ts:42
  Credentials compared with == instead of a constant-time comparison.
  Fix: use crypto.timingSafeEqual.

2 findings (1 security, 1 behavior)
```

### 配置

| 新闻 var | 默认 | 含义 |
| --- | --- | --- |
| `ANTHROPIC_API_KEY` | _(未设定)_ | API密钥. 先检查;倒回平台键链. Ollama等本地供应商不需要. |
| `DIFFGUARD_MODEL` | `claude-sonnet-5` | 审计所用的模式 |
| `DIFFGUARD_SEVERITY_THRESHOLD` | `medium` | 人类产出中的最低严重程度`critical`编号 :`high`编号 :`medium`编号 :`low`编号 :`info`(中文(简体) ) |
| `DIFFGUARD_SECURITY_ENABLED` | `true` | 对安全问题的审计 |
| `DIFFGUARD_BEHAVIOR_ENABLED` | `true` | 对行为变化的审计 |
| `DIFFGUARD_MAX_DIFF_TOKENS` | `8000` | 截取前最大 diff 大小( 审计变为部分) |
| `DIFFGUARD_PROVIDER` | `anthropic` | 提供者 : `anthropic` 或者说 `openai` (开放AI兼容) |
| `DIFFGUARD_BASE_URL` | _(未设定)_ | OpenAI 兼容供应商的基础 URL(例如). `http://localhost:11434/v1`(中文(简体) ) |
| `~/.config/diffguard/config.json` | _(未设定)_ | 保存的设置 `diffguard config` (提供者、模型、基址、, `needsKey`Env vars 覆盖它。 设定 `XDG_CONFIG_HOME` 以搬迁. |

优先发言: **env var > config 文件 > 默认**。API 密钥从未存储在配置中 文件 —— 它生活在平台键链中(`diffguard key set` 编号 : `diffguard config`)或为: `ANTHROPIC_API_KEY` (原始内容存档于2018-10-21). Env var. CLI先检查env var,再检查键链.

## 如何运作

1.  DiffGuard收集了git diff和一些轻量级回放上下文.
2.  它迅速指示克洛德 以JSON的严格身份回归调查结论 答复(删除 `Ctrl-C`) (中文(简体) ).
3.  答复经过解析和验证——错误的调查结果被删除和计算, 从来没有默默接受.
4.  调查结果作为分组报告打印,或作为原始JSON `--json`。 。 。 .

如果diff为空,DiffGuard在0出站时不拨打API. 如果diff也一样 很大,它被切换到 `DIFFGUARD_MAX_DIFF_TOKENS` 并且审计部分标明.

## 隐私

-   您的审计被发送到 Anthropic 生成结果 。 不要审计密码 送去第三方API很不舒服.
-   DiffGuard不打其他网络电话,也不收集遥测数据.

## 路线图

-   承诺前钩子安装器( E)`diffguard install`) (中文(简体) ).
-   `--path` 过滤, `--fail-on <severity>`。 。 。 .
-   与安全/行为结果一起进行检验和许可证遵守情况检查.

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40figo5/diffguard/LICENSE)。 。 。 .

## 常见问题

### @figo5/diffguard 是什么？

使用您自己的 Anthropic API 密钥对安全问题和意外行为进行修改的审计代码 \.

### 如何安装 @figo5/diffguard？

在项目目录运行 npm install @figo5/diffguard，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 diffguard、diffguard-mcp，可以用 npx diffguard 直接运行。

### @figo5/diffguard 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @figo5/diffguard 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @figo5/diffguard 可以商用吗？

@figo5/diffguard 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @figo5/diffguard 的下载量有多少？

根据 npm 官方下载统计，@figo5/diffguard 在 2026/10/15 – 2026/11/13 这 30 天内被下载 6,083 次，日均约 203 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @figo5/diffguard 还在维护吗？

最新版本 0\.1\.3 发布于 2026/08/08（3 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/08/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。