《Agent Runtime 工程化》试读章节：Tool Runtime 与权限审批

少这些字段，系统不会立刻报错。

但后面某个模块一定会用猜的。

工程事故常常就是从'先随便填一下'开始的。

Schema 只说明长得对，不说明能执行

以 read_file 为例。

schema 可能只要求：

const ReadFileInput = {
  type: "object",
  required: ["path"],
  properties: {
    path: { type: "string" },
    startLine: { type: "integer", optional: true },
    endLine: { type: "integer", optional: true },
  },
};

这能证明什么？

只能证明 path 是字符串。

它不能证明：

path 在 workspace 内
path 不是 symlink escape
path 不是 .env
文件大小适合进入上下文
用户有权限读取

所以要分三层：

Schema validation：参数形状对不对。
Policy validation：这个行为是否允许。
Approval decision：是否需要人确认。

把这三层混在一起，后面测试会很痛。

Tool Registry 先生成计划

模型返回 tool call 后，不应该直接 execute。

Runtime 应先生成工具计划：

type ToolPlan = {
  call: ToolCall;
  tool?: ToolDefinition;
  validationErrors: string[];
};

示例：

class ToolRegistry {
  plan(call: ToolCall): ToolPlan {
    const tool = this.tools.get(call.name);
    if (!tool) {
      return { call, validationErrors: ["UNKNOWN_TOOL"] };
    }

    const validation = validateObjectSchema(tool.inputSchema, call.input);
    if (!validation.ok) {
      return { call, tool, validationErrors: validation.errors };
    }

    return { call, tool, validationErrors: [] };
  }
}

计划阶段的价值，是把风险摊开。

工具不存在，不执行。
参数非法，不执行。
高风险工具，进入审批。
只读工具，可以自动允许。
写入工具，生成 preview。

Runtime 要在执行前知道自己准备做什么。

PermissionGate 是 Runtime 的裁判

工具自己不应该决定'我能不能执行'。

工具可以声明风险。

Runtime 根据工具风险、参数、用户策略和当前模式做裁决。

一个最小决策对象：

type PermissionDecision = {
  callId: string;
  toolName: string;
  action: "allow" | "deny" | "ask";
  reason: string;
  risk: "read" | "write" | "shell" | "network" | "dangerous";
  decidedAt: string;
  preview?: string;
};

demo 里可以这样处理：

read：自动允许
shell：如果 allowShellReadonly=true，允许只读 shell
network：默认拒绝
write：需要显式 allowWrites
dangerous：默认拒绝

真实产品里，ask 会进入 UI 审批。

但不管是 policy 自动裁决，还是用户点击批准，都要写入 trace。

审批是系统事实。

不是前端弹窗状态。

写文件为什么必须 preview

写文件工具不能只显示：

Allow write_file?

用户不知道它要写哪里，也不知道改什么。

一个可用 preview 至少要说清：

目标路径
内容长度
是否新建文件
diff 摘要
写入原因
是否会覆盖已有内容

学习 demo 可以先简化：

function previewWrite(plan: ToolPlan): string | undefined {
  if (plan.call.name !== "write_text") return undefined;
  const input = plan.call.input as { path?: unknown; content?: unknown };
  return `准备写入 ${String(input.path ?? "unknown")}，内容长度 ${String(input.content ?? "").length} 字符。`;
}

生产系统里，最好给 diff。

因为用户批准的不是'运行一个工具'。

用户批准的是具体副作用。

Shell 工具要保守

Shell 是最有用也最危险的工具。

npm test 看起来安全，但 test script 可以做任何事。
node script.js 看起来普通，但脚本可以联网、删文件、读环境变量。
curl 可能只是查资料，也可能上传数据。

所以 shell policy 第一版应该保守。

示例：

const READONLY_COMMANDS = new Set(["pwd", "ls", "find", "rg", "cat", "sed", "wc"]);

function classifyReadonlyCommand(command: string) {
  const first = command.trim().split(/\s+/)[0] ?? "";
  if (!READONLY_COMMANDS.has(first)) return "DENY_UNKNOWN_COMMAND";
  if (/[>|;&`$]/.test(command)) return "DENY_SHELL_OPERATOR";
  if (/\b(rm|mv|cp|chmod|chown|curl|wget|ssh|sudo)\b/.test(command)) {
    return "DENY_RISKY_TOKEN";
  }
  return "ALLOW_READONLY_COMMAND";
}

这不是完美沙箱。

它是第一层策略。

后面还要配合：

workspace cwd
环境变量过滤
timeout
输出上限
进程树清理
网络策略
sandbox profile
trace

不要指望一个正则表达式守住所有安全边界。

Workspace 边界是底线

文件工具必须限制在 workspace 内。

这件事不能靠 prompt。

路径检查也不能只做字符串前缀。

更稳的方式是：

先 path.resolve
再 realpath
再 path.relative 判断是否逃出 workspace
写入时检查父目录真实路径
拒绝写入 symlink

本书 demo 里，resolveForWrite 会拒绝 symlink 写入：

if (stat.isSymbolicLink()) {
  throw new WorkspaceSecurityError("拒绝写入符号链接目标", "DENY_SYMLINK_WRITE");
}

这类代码看着不酷。

但很重要。

很多工具事故不是发生在模型'想作恶'。

而是发生在路径、符号链接、环境变量、默认工作目录这些细节里。

ToolResult 要同时服务模型和工程系统

工具结果不能只返回：

done

也不能把完整日志一股脑塞回模型。

一个更可用的结构：

type ToolResult = {
  callId: string;
  toolName: string;
  status: "ok" | "error" | "denied" | "timeout" | "cancelled";
  content: string;
  errorCode?: string;
  metadata: {
    durationMs: number;
    outputChars: number;
    truncated: boolean;
    retryable: boolean;
    sideEffects?: ToolSideEffect[];
  };
};

content 是给模型继续推理的 observation。

metadata 是给 Runtime、trace、eval 和 checkpoint 的证据。

如果工具被拒绝，要返回 denied。
如果命令超时，要返回 timeout。
如果输出被截断，要标记 truncated。
如果写了文件，要记录 sideEffects。

这就是 Tool Runtime 和普通函数调用的差别。

权限拒绝也要写回模型

当写入被拒绝时，不应该直接崩溃。

更好的做法是生成一个 tool result：

status: denied
errorCode: PERMISSION_DENIED
content: 写入工具需要显式开启 --allow-writes。
retryable: false

然后写回 message history。

模型下一步应该基于这个 observation 停止，或者找低风险替代方案。

如果 Runtime 只是抛异常，模型看不到拒绝原因，用户也只看到程序失败。

一条工具治理管线

把整个流程串起来，是这样：

ToolDefinition
  ↓
ToolRegistry.plan()
  ↓
schema validation
  ↓
policy validation
  ↓
PermissionGate.review()
  ↓
preview / allow / ask / deny
  ↓
ToolExecutor.execute()
  ↓
ToolResult normalize
  ↓
MessageStore + Trace + Checkpoint

这条线少一步都容易出事。

少 schema validation，模型乱填参数。
少 policy validation，路径越界和危险命令混进来。
少 PermissionGate，高风险动作自动执行。
少 ToolResult normalize，模型只能猜失败原因。
少 trace，事故后没人知道发生了什么。
少 checkpoint，恢复时不知道副作用到哪一步。

试读小结

Tool Runtime 的目标不是让模型拥有更多按钮。

目标是让 Runtime 能稳定、安全、可追溯地使用这些按钮。

模型负责提出：

我想调用哪个工具，参数是什么。

Runtime 负责判断：

这个工具是否存在，参数是否合法，风险是否可接受，用户是否批准，怎样执行，失败如何反馈。

这是生产级 Agent 的分水岭。

推荐阅读

• 一个 Agent Runtime 失败案例的完整 Trace
• 生产级 Agent 上线前必须检查的 50 件事
• Agent Runtime Engineering v0.1 发布