add-guard-protection

添加 Arcjet Guard 防护

Arcjet Guard 为没有 HTTP 请求的代码路径提供速率限制、提示词注入检测、敏感信息拦截和自定义规则，例如 AI Agent 工具调用、MCP 工具处理程序、后台任务处理器、队列工作器等。

第 0 步：设置 Arcjet CLI

Arcjet CLI 是用于身份验证、管理站点、配置远程规则和监控流量的主要工具。如果尚未安装，请先安装：

# Via npx (no install required)
npx @arcjet/cli --help

# Or install globally via npm
npm install -g @arcjet/cli

# Or via Homebrew
brew install arcjet

身份验证

arcjet auth login

打开浏览器进行身份验证。使用 arcjet auth status 检查状态。

站点和密钥设置

# List your teams
arcjet teams list

# List sites for a team
arcjet sites list --team-id <team-id>

# Create a new site
arcjet sites create --team-id <team-id> --name "My Guard App" --confirm

# Get the SDK key for a site
arcjet sites get-key --site-id <site-id>

将密钥添加到环境文件（.env、.env.local 等）中，变量名为 ARCJET_KEY。

第 1 步：检测语言并安装

检查项目中的语言标识：

• package.json → JavaScript/TypeScript → npm install @arcjet/guard（需要 @arcjet/guard >= 1.4.0）
• requirements.txt / pyproject.toml → Python → pip install arcjet（需要 arcjet >= 0.7.0；其中已包含 Guard）
• go.mod、Cargo.toml、pom.xml 或其他语言 → Guard 不可用。告知用户 Arcjet Guard 目前仅支持 JavaScript/TypeScript 和 Python。不要自行编写仿制实现，也不要臆造不存在的软件包。建议用户联系 Arcjet，说明其使用场景。

第 2 步：阅读语言参考文档

编写任何代码之前，必须先阅读检测到的语言对应的参考文件。 参考文件包含该语言的准确导入项、构造函数签名、规则配置语法和 guard() 调用模式。

• JavaScript/TypeScript：references/javascript.md
• Python：references/python.md

不要猜测 API。所有代码模式都应以参考文件为准。

第 3 步：创建 Guard 客户端（在模块作用域中创建一次）

客户端会维持持久连接。在模块作用域中创建一次并重复使用，切勿在函数内部或每次调用时创建。将变量命名为 arcjet。

检查环境文件（.env、.env.local 等）中是否设置了 ARCJET_KEY。如果没有，请按以下优先顺序获取密钥：

1. CLI（首选）： 运行 arcjet sites get-key --site-id <site-id>（需要先运行 arcjet auth login；请参阅第 0 步）
2. MCP： 如果已连接 Arcjet MCP 服务，请使用它列出站点并获取密钥
3. 手动（最后手段）： 添加占位符，并告知用户从 https://app.arcjet.com 获取密钥

第 4 步：在模块作用域中配置规则

规则配置一次，作为可重复使用的工厂，然后使用每次调用的输入调用。这种两阶段模式很重要——规则配置包含一个稳定 ID，用于服务器端聚合，而每次调用的输入则会变化。

配置速率限制规则时，将 bucket 设置为描述性名称（例如 "tool-calls"、"session-api"），以提高清晰度并减少冲突。

根据使用场景选择规则

使用场景	推荐规则
AI Agent 工具调用	tokenBucket + detectPromptInjection
MCP 工具处理程序	slidingWindow 或 tokenBucket + detectPromptInjection
后台 AI 任务处理器	tokenBucket + localDetectSensitiveInfo
接受用户输入的队列工作器	tokenBucket + detectPromptInjection + localDetectSensitiveInfo
扫描工具结果中的注入内容	detectPromptInjection（扫描返回的内容）

第 5 步：在每次操作之前内联调用 guard()

在每次操作发生的位置直接调用 guard()——内联放在需要保护的每个工具处理器、任务处理器或函数中。不要将 guard 封装在共享辅助函数中。

每次 guard() 调用都需要传入：

• label：用于仪表板的描述性字符串（例如，"tools.search_web"、"tasks.generate"）
• rules：绑定规则调用的数组
• metadata（可选）：用于分析／审计的键值对（例如，{ userId }）

速率限制规则需要一个显式的 key 字符串——使用用户 ID、会话 ID、API 密钥或任何稳定标识符。

你必须修改现有源文件——仅在 package.json/requirements.txt 中添加依赖是不够的。必须将 guard() 调用集成到实际代码中。

第 6 步：处理决策

务必检查 decision.conclusion：

• "DENY" → 阻止操作。使用每条规则的结果访问器（参见参考文档）获取具体错误信息，例如重试等待时间。
• "ALLOW" → 可以安全继续

准确的决策检查模式和每条规则的结果访问器，请参阅语言参考。

应避免的常见错误

• 将 guard 封装在共享辅助函数中——通过 guardToolCall() 或 protectCall() 包装器调用 guard()，会掩盖每项操作适用的规则。应在每次操作发生的位置内联调用 guard()。
• 每次调用都创建客户端——客户端持有持久连接。应在模块作用域创建一次。
• 在函数中配置规则——规则配置带有稳定 ID。每次调用都创建规则配置会破坏仪表板跟踪和速率限制状态。
• 忘记在速率限制规则中传入 key 参数——没有 key，Guard 就无法跟踪每位用户的限制。
• 忘记在速率限制规则中传入 bucket——没有命名 bucket，不同规则可能会发生冲突。
• 没有请求时仍使用 HTTP SDK——对于非 HTTP 代码，应使用 @arcjet/guard / arcjet.guard，而不是 @arcjet/node、@arcjet/next 或 arcjet()。
• 不检查 decision.conclusion——继续操作之前务必检查。
• 使用笼统的 DENY 消息——使用每条规则的结果访问器，为用户提供具体反馈，例如重试等待时间。

第 7 步：使用 CLI 验证 Guard 决策（即将推出）

注意： arcjet guards CLI 子命令尚未发布。该功能推出后，可使用此反馈循环验证 guard 决策是否正常触发。

添加 guard 代码后，使用 CLI 验证决策是否正常触发。这将形成一个反馈循环：运行应用、触发 guard、检查决策，并在需要时进行调整。

1. 开始监视

在单独的终端中开始流式接收 guard 决策：

arcjet guards watch --site-id <site-id>

此命令会轮询新的 guard 决策，并在收到时打印出来。使用 --conclusion DENY 仅筛选拒绝结果，或使用 --interval 2 加快轮询速度。

2. 触发 Guard

运行应用，并执行会调用 guard() 的代码路径。每次调用都应生成一个决策，并显示在监视输出中。

3. 检查决策

如果决策与预期不符，请检查详情：

# List recent guard decisions
arcjet guards list --site-id <site-id>

# Get per-rule breakdown for a specific decision
arcjet guards details --site-id <site-id> --decision-id <decision-id>

详情视图会显示每条规则的执行情况、模式（live/dry-run）、结论、原因，以及是否跳过——可据此诊断 guard 意外允许或拒绝操作的原因。

4. 调整并重试

如果规则未按预期触发：

• 检查 label 是否与决策中显示的内容一致
• 验证速率限制规则的 key 是否正确（key 错误 = bucket 错误）
• 确认每条规则的 bucket 名称都唯一
• 检查规则顺序——规则按数组顺序执行，较早规则返回 DENY 时，会提前中止后续规则的执行

然后重新运行并再次监视，直到决策符合预期。

CLI 快速参考

任务	命令
安装/运行 CLI	npx @arcjet/cli 或 brew install arcjet
身份验证	arcjet auth login
检查身份验证状态	arcjet auth status
列出团队	arcjet teams list
列出站点	arcjet sites list --team-id <id>
创建站点	arcjet sites create --team-id <id> --name "Name" --confirm
获取 SDK 密钥	arcjet sites get-key --site-id <id>
监视防护决策	arcjet guards watch --site-id <id>
列出防护决策	arcjet guards list --site-id <id>
查看防护决策详情	arcjet guards details --site-id <id> --decision-id <id>

全局标志

所有命令均支持：

• --output text|json — 输出格式（默认：TTY 环境下为 text，否则为 json）
• --fields <list> — 指定要包含在 JSON 输出中的字段，以逗号分隔
• --no-color — 禁用 ANSI 颜色（也会遵循 NO_COLOR 环境变量）
• --timeout <duration> — 最大执行时间（例如 30s、5m；0 表示禁用）

退出代码

代码	含义
0	成功
1	一般错误（未知命令、API 故障、网络错误）
2	身份验证错误（未登录、令牌过期）
3	输入验证错误（ID 无效、值超出范围）
4	需要确认（修改操作需要 --confirm）