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 上没有它,不要从那里安装同名的包。
- 把接入包里的
.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- 把
PREWORLD_GUARD_SDK_NPM_AUTH设成token:<SDK 下载令牌>的 base64 编码。控制台签发令牌时也会显示这个值,同样只显示一次。只放在环境变量或 CI 密钥里,不要写进.npmrc或 Git。
export PREWORLD_GUARD_SDK_NPM_AUTH=$(printf 'token:%s' "$SDK_DOWNLOAD_TOKEN" | base64) # or the value the console shows- 用向导给出的命令安装,例如:
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 会从公共源下载同名的包。
使用
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
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。
检查接入
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。