Skip to content

TypeScript SDK ​

@preworld/guard 是给 Node.js Agent 用的 SDK。它和 Python SDK 保持一致:同样的控制面接口、策略摘要、审批摘要和缓存文件。只支持 ESM,需要 Node.js 22.12 及以上,没有运行时依赖。

当前托管生产提供 @preworld/guard@0.2.0。后续 0.3.0 将改名为 @yilabs/guard;须等实际发布并出现在私有源后再修改包名、作用域和导入。

安装 ​

这个包只由你们的私有 SDK 源提供,地址是 SDK 主机上的 /npm/,用和 pip 一样的 SDK 下载令牌。公共 npm 上没有它,不要从那里安装同名的包。

  1. 把接入包里的 .npmrc.example 复制成项目根目录的 .npmrc,并提交到 Git。它把 @preworld 作用域指向私有源,凭据从环境变量读,文件本身不含凭据:
@preworld:registry=https://sdk.guard.example.com/npm/
//sdk.guard.example.com/npm/:_auth=${PREWORLD_GUARD_SDK_NPM_AUTH}
replace-registry-host=npmjs
  1. 把 PREWORLD_GUARD_SDK_NPM_AUTH 设成 token:<SDK 下载令牌> 的 base64 编码。控制台签发令牌时也会显示这个值,同样只显示一次。只放在环境变量或 CI 密钥里,不要写进 .npmrc 或 Git。
sh
export PREWORLD_GUARD_SDK_NPM_AUTH=$(printf 'token:%s' "$SDK_DOWNLOAD_TOKEN" | base64)  # or the value the console shows
  1. 用向导给出的命令安装,例如:
sh
npm install --save-exact --@preworld:registry=https://sdk.guard.example.com/npm/ @preworld/guard@0.2.0
npm install ai zod                                                                     # from the public registry

没有提交 .npmrc 的话,新克隆的仓库、npm update、Dependabot 或 Renovate 都会去公共源找 @preworld/guard。replace-registry-host=npmjs 防止用户或全局配置改写私有源的下载地址。package-lock.json 只记录下载地址和 sha512 integrity,不含凭据,可以提交。字节不一致的包装不上。

运行命令行时一律写 npx --no preworld-guard …。不加 --no,SDK 没装时 npx 会从公共源下载同名的包。

使用 ​

ts
import { GuardClient, guardRun } from "@preworld/guard";

const guard = await new GuardClient({
  endpoint: process.env.PREWORLD_GUARD_ENDPOINT!,
  token: process.env.PREWORLD_GUARD_TOKEN!,
  projectId: process.env.PREWORLD_GUARD_PROJECT_ID!,
  agentId: process.env.PREWORLD_GUARD_AGENT_ID!,
  backgroundEvents: true,
}).start();

const updateRecord = guard.tool("crm.update", async (args: { id: string; fields: Record<string, string> }) => {
  // the side effect runs only after Guard allowed this exact call
});

await guardRun({ sessionId: conversationId, subjectId: signedInUser }, () => updateRecord({ id, fields }));
await guard.close(); // on shutdown
API做什么
guard.authorize(resource, args, options)判定一次调用。抛出 GuardDenied(子类有 GuardApprovalRequired 和 GuardDegradeRequired),Guard 无法判定时抛出 GuardError。工具由你们自己执行时,用 executionArguments(action) 拿到判定过的那份参数
guard.tool(name, fn)包装一个函数:记录 started 和 completed,遇到降级规则时执行 guard.registerFallback 注册的替代工具,并把判定过的参数副本交给函数
guard.run(authorized, fn)、guard.runStream(...)给适配器用:只执行本客户端 authorize 返回的那一次,且只能执行一次
guardRun({ sessionId, subjectId, runId, traceId }, fn)为 fn 里的每次 Guard 调用设置身份(基于 AsyncLocalStorage)。主体来自你们的应用,不能来自模型
guardApproval(ticketId, ...) 或 approvalTicket 选项重新执行一次已批准的调用
guard.approvalStatus(ticketId)、guard.cancelApproval(ticketId)管理票据

参数只在调用 authorize 或被包装的工具时复制一次,发生在任何 await 之前。之后再改你们的对象,既不影响判定,也不影响工具收到什么。复制按 JSON.stringify 的规则。函数、symbol、Date 这类类实例、NaN、无穷大和循环引用都会被拒绝,因为 Guard 不能放行它看不清的东西。

Vercel AI SDK ​

ts
import { generateText } from "ai";
import { guardRun } from "@preworld/guard";
import { guardTools } from "@preworld/guard/ai-sdk";

const { tools, toolApproval } = guardTools({ lookup, transfer }, guard);
const result = await guardRun({ subjectId: user.id, sessionId: chat.id }, () =>
  generateText({ model, tools, toolApproval, messages, experimental_toolApprovalSecret: approvalSecret }));
  • 在哪里判定:每个被包装工具的 execute,就在它执行之前。工具收到的是判定过的参数。
  • toolApproval 把 Guard 的判定和你们自己的审批规则合起来,取更严的那个。Guard 放行:由你们的规则决定。Guard 拒绝:{ type: "denied", reason }。Guard 要求审批:{ type: "user-approval", reason },带着票据。
  • 先问你们自己的规则。你们的规则拒绝的调用,不会申请 Guard 票据。如果 Guard 的策略也拒绝它,Guard 仍会记下自己的拒绝。
  • 恢复执行:只有审核员在 Guard 里批准了票据、并且你们自己的规则也同意时,调用才会放行。消息里只有一条审批回复时,不管它是不是伪造的,都不能放行 Guard 要求审批的调用。请传 experimental_toolApprovalSecret,让 ai@7 能分辨伪造的审批回复。
  • Guard 无法判定时,或者没法记录调用开始(GUARD_AUDIT_UNAVAILABLE),调用被拒绝,原因是 GUARD_*,不带内部错误信息。
  • 流式工具(async *execute,或返回异步可迭代对象的函数)在判定之后经由 Guard 流式输出。流结束时记为已完成。
  • Guard 在执行前看不到的工具(模型厂商执行的工具、没有 execute 的工具)一律拒绝,除非列在 unguardedTools 里。
  • 身份只来自 guardRun(或 options.identity)。identity 回调抛出异常时是 GUARD_IDENTITY_UNAVAILABLE。它给出的主体和 guardRun 不一致时是 GUARD_SUBJECT_MISMATCH。

检查接入 ​

sh
npx --no preworld-guard connection-check --config guard-connection.json

令牌从 PREWORLD_GUARD_TOKEN(或 --token-file)读,从不出现在命令行里。退出码 0 表示就绪,2 表示还没就绪,1 表示检查本身失败。

网络与 TLS ​

  • 证书总是校验。NODE_TLS_REJECT_UNAUTHORIZED=0 不起作用。
  • 信任的根证书是 Node 自带的 Mozilla 证书库。NODE_EXTRA_CA_CERTS、--use-system-ca、--use-openssl-ca 都不会增加信任。
  • 忽略 HTTPS_PROXY 和 NO_PROXY。要走代理或信任私有 CA,传 proxy / caBundle,或者设 PREWORLD_GUARD_PROXY / PREWORLD_GUARD_CA_BUNDLE。CA 证书包会替换自带的根证书。
  • 令牌和代理凭据不会出现在 console.log(guard)、util.inspect 或 JSON.stringify 的输出里。

磁盘上的事件 ​

脱敏事件存在策略缓存旁边,直到控制面接收为止。多个进程、工作线程、客户端和 Agent 可以共用默认的 .preworld-guard/ 目录:每个客户端只写自己的文件,文件名按项目、控制面和 Agent 区分。已经退出的客户端留下的文件,由同一个 Agent 的其他客户端接手,事件不会丢。

客户端关闭之后,拒绝一切新的动作。

比 Python 更严的地方 ​

每一种情况都按无法判定处理:拒收策略、拒绝动作,或者 authorize 抛出异常。

  • 策略按严格模式解析。版本写成 "3" 或 3.0、规则里出现 NaN 或 Infinity、版本号大于 2^53−1,都会被拒收。
  • argument_regex 只支持一个可移植的子集:字面量、字符类、分组、选择和量词,^ 只能在开头,$ 只能在结尾。\d、\w、\s、\b、环视、内联标志和反向引用在判定到这条规则时被拒绝。
  • expires_at 必须是 YYYY-MM-DD[(T| )HH:MM[:SS[.fff|.ffffff]][±HH:MM|Z]] 的形式,其他写法让策略被视为已过期。
  • argument_path_under 会跟随符号链接。遇到循环链接或 NUL 字节时抛出异常。Windows 上不支持这项检查。
  • 工具参数必须是 JSON。