开发者指南

编写并验证智能体授权书

授权书只能通过有效的强制字段表达边界。无效授权书会使每次操作检查都回答 error。

从模板开始

这个文件沙箱条目原样取自嵌入 public/try.1.js的模板。第一条款拒绝敏感前缀，第二条款许可在一个工作区前缀下读取和写入文件，默认规则拒绝任何未匹配项。

  {
    "name": "file-sandbox",
    "title": "File sandbox",
    "description": "Deny sensitive directories and permit reads and writes under one bounded directory.",
    "mandate": {
      "schema_version": "0.2-draft",
      "mandate_id": "template-file-sandbox",
      "purpose": "Confine file reads and writes to one working directory.",
      "default": "deny",
      "clauses": [
        { "id": "deny-sensitive", "effect": "deny", "match": { "kind": ["file"], "target_prefix": ["~/.ssh/", "/etc/"] } },
        { "id": "permit-workspace", "effect": "permit", "match": { "kind": ["file"], "verb": ["read", "write"], "target_prefix": ["/workspace/project/"] } }
      ]
    },
    "action": {
      "schema_version": "0.1-draft",
      "requested_by": { "agent": "template-agent" },
      "operation": { "kind": "file", "verb": "write", "target": "/workspace/project/report.txt" },
      "justification": "Write the report inside the bounded workspace."
    },
    "outcome": "permit"
  },

更改授权书标识符以便跟踪，并更改强制字段以匹配你希望授予的权限。purpose、note 和 justification 都是说明性文字，绝不会限制操作。只有条款匹配字段、 not_valid_after、 requires_human和 default 才会限制操作。由于第一个匹配条款决定结果，应将较窄的拒绝放在较宽的许可之前。不要在授权书中放入秘密、个人数据或机密政策。

验证授权书

表单原样使用来自 public/try.1.js的验证流程。它初始化 MCP，调用 validate_mandate，并接受结构化内容或文本回退。

export async function validateMandate(mandateText, fetchImpl = fetch) {
  const mandate = parseDocument(mandateText, "mandate");
  const initialized = await postJson(MCP_URL, {
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: "2025-11-25",
      capabilities: {},
      clientInfo: { name: "hanria.ai-try-it", version: "1" }
    }
  }, fetchImpl);
  if (initialized.error) throw new Error(initialized.error.message || "initialize failed", { cause: "response" });
  const called = await postJson(MCP_URL, {
    jsonrpc: "2.0",
    id: 2,
    method: "tools/call",
    params: { name: "validate_mandate", arguments: { mandate } }
  }, fetchImpl);
  if (called.error) throw new Error(called.error.message || "validate_mandate failed", { cause: "response" });
  const structured = called.result?.structuredContent;
  if (structured && typeof structured === "object") return structured;
  const text = called.result?.content?.find((item) => item.type === "text")?.text;
  if (typeof text === "string") {
    try {
      return JSON.parse(text);
    } catch {
      throw new Error("invalid validate_mandate result", { cause: "response" });
    }
  }
  throw new Error("missing validate_mandate result", { cause: "response" });
}

运行

打开表单
前往试用表单，然后选择“File sandbox”。
编辑授权书
将示例标识符和边界替换为你希望采用的结构化限制。
仅验证
选择 仅验证授权书。结果为 valid: true 表示验证器接受了文档。结果为 valid: false 会指出验证问题。请在使用授权书前修复。
检查操作
用授权书检查具有代表性的操作，并查看结果、决定结果的条款和签名回执。

处理每一种结果

操作检查返回 permit、 deny或 escalate ，并附上决定结果的条款和签名回执。检查仅提供建议，真正拒绝操作的是你的集成。托管检查在内存中评估请求，不保留请求内容。

permit: 一个条款许可这一次拟议操作。你的集成可以按照自身权限流程继续。
deny: 不要执行该操作，也不要尝试其他路径。
escalate: 停止，并在集成之外请求运营者作出决定。
error: 将其视为 deny，报告原因，并且不要盲目重试。

无效授权书会使每次操作检查都返回 error，你的集成必须将其视为 deny。无效授权书不表达边界。验证也不会把授权书转变为强制边界。

参考资料

试用检查 · 验证签名回执 · OpenAPI 文档 · 面向智能体的摘要

编写并验证智能体授权书

从模板开始

验证授权书

运行

打开表单

编辑授权书

仅验证

检查操作

处理每一种结果

参考资料