@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/harness-agents.md

@@ -0,0 +1,349 @@
+---
+title: "安全带特工"
+description: "将 Claude Code、Codex、Pi 和其他完整的编码工具作为 Agent-Native 内的嵌入式代理运行，并具有自己的循环、沙箱、本机工具和可恢复的 SQL 支持的会话。"
+search: "harness代理AgentHarness ai-sdk HarnessAgent Claude代码Codex Pi Cursor Mastra嵌入式编码代理resolveAgentHarness startAgentHarnessRun可恢复会话沙箱主机工具"
+---
+
+# 安全特工
+
+> **这是给谁的：** 主机作者连接完整的编码运行时（Claude 代码，
+> Codex, Pi) 转换为 Agent-Native 作为代理。构建应用程序？从
+> [Creating Templates](/docs/creating-templates).
+
+线束代理是一个完整的代理运行时 - Claude 代码、Codex、Pi 等 -
+拥有自己的循环、工作区、本机文件工具、会话状态、压缩，
+审批模型和沙箱行为。 Agent-Native 通过
+**`AgentHarness`** `@agent-native/core/agent/harness` 中的基质，流式传输它们
+将事件放入正常的记录中，并保留其本机会话，以便成为一个线程
+可以暂停和恢复。
+
+这与内置聊天代理和自带聊天功能不同
+运行时。内置代理和`AgentEngine`为一个模型往返
+在`runAgentLoop`下面。一个harness不是一个`AgentEngine`提供者——它运行它的
+自己的端到端循环，因此 Agent-Native 将其作为会话驱动，而不是单个
+模型调用。
+
+```an-diagram title="A harness owns its loop; Agent-Native drives the session" summary="The AgentHarness substrate creates/resumes the native session, streams its events into the normal transcript, and persists resumeState in SQL between turns."
+{
+  "html": "<div class=\"diagram-harness\"><div class=\"diagram-box\" data-rough><strong>AgentHarness substrate</strong><small class=\"diagram-muted\">@agent-native/core/agent/harness</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Native harness loop</strong><small class=\"diagram-muted\">Claude Code · Codex · Pi — own tools, sandbox, compaction</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">events &rarr; transcript</div><div class=\"diagram-pill ok\">resumeState &rarr; SQL session</div></div></div>",
+  "css": ".diagram-harness{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-harness .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-harness .diagram-arrow{font-size:22px;line-height:1}.diagram-harness .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 我需要哪个编码文档？ {#which-doc}
+
+| 你想要……                                               | 使用                                         |
+| ------------------------------------------------------ | -------------------------------------------- |
+| 使用自己的循环+工具**作为代理**运行Claude代码/Codex/Pi | **安全带代理**（本页）                       |
+| 渲染 Claude-Code/Codex 样式 **编码工作区 UI**          | [Agent-Native Code UI](/docs/code-agents-ui) |
+| 交换运行代理的 **`run-code` 工具**的后端               | [Adapters](/docs/sandbox-adapters)           |
+| 封装一个CLI工具（`gh`、`ffmpeg`）供代理调用            | [Adapters](/docs/sandbox-adapters)           |
+
+相邻表面：将您在其他地方构建的代理放在 Agent-Native 的聊天后面
+UI 与 [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes)；让一个
+外部 MCP 主机通过 [External Agents](/docs/external-agents) 调用您的应用；
+生成后台/子代理与 [Custom Agents & Teams](/docs/agent-teams) 一起运行。
+
+## 内置安全带 {#built-in}
+
+`registerBuiltinAgentHarnesses()` 注册由 AI SDK 支持的三个适配器
+`HarnessAgent`:
+
+| 姓名                         | 运行时     | 沙盒 | 批准 |
+| ---------------------------- | ---------- | ---- | ---- |
+| `ai-sdk-harness:claude-code` | Claude代码 | 是的 | 是的 |
+| `ai-sdk-harness:codex`       | Codex      | 是的 | 没有 |
+| `ai-sdk-harness:pi`          | 圆周率     | 没有 | 是的 |
+
+它们的运行时包是**可选的对等依赖项**并且延迟加载，因此
+从不使用安全带的应用程序无需付费。每个适配器都带有一个
+`installPackage` 提示（例如`@ai-sdk/harness@canary
+@ai-sdk/harness-codex@canary`); `resolveAgentHarness`抛出一个明确的安装
+如果缺少包，则会出现错误，并且 `isAgentHarnessPackageInstalled(entry)`
+让您先检查。
+
+`registerBuiltinAgentHarnesses()` 还注册了 [ACP](#acp) 线束
+(`acp`, `acp:gemini`, `acp:claude-code`).
+
+## ACP代理 {#acp}
+
+Agent-Native可以充当[ACP](https://agentclientprotocol.com)（代理客户端
+协议）**客户端**并驱动本地编码代理 - Gemini CLI、Claude 代码，
+或任何符合ACP标准的代理——通过相同的基材。代理作为
+本地子进程通过stdio使用换行符分隔的JSON-RPC； ACP的编辑
+↔ 代理模型就是这个形状。
+
+此适配器的范围是**本地编码**。子进程继承
+父环境，因此代理重用它已有的任何本地 CLI 登录
+（例如用户主目录中的 `gemini` 或 `claude` 身份验证）。这不是一个
+托管或沙盒传输，并且它不是聊天/A2A 传输 - 对于这些，
+参见[Agent Surfaces](/docs/agent-surfaces)。
+
+| 姓名              | 默认命令                                       | 可恢复\* |
+| ----------------- | ---------------------------------------------- | -------- |
+| `acp`             | _(通过配置提供`command`/`args`)_               | 是的     |
+| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp` | 是的     |
+| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`       | 是的     |
+
+\*当代理通告 `loadSession` 功能时恢复工作并且
+否则将降级为新会话。
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+
+// A built-in preset (command/args are overridable through the resolve config):
+const adapter = resolveAgentHarness("acp:gemini");
+
+// Or any ACP agent by command:
+const custom = resolveAgentHarness("acp", {
+  command: "gemini",
+  args: ["--experimental-acp"],
+});
+```
+
+协议传输（`@zed-industries/agent-client-protocol`）是可选的
+通过`installPackage`提示延迟加载依赖，就像AI SDK一样
+安全带。代理二进制文件本身（`@google/gemini-cli`，
+`@zed-industries/claude-code-acp`, …) 是一个单独的外部 CLI；预设
+通过 `npx` 启动它，并且命令/参数保持可重写，因为代理 ACP
+入口标志仍在演变。
+
+`permissionMode` 使用工具调用映射到 ACP `session/request_permission`
+设置代理报告：读取始终运行，编辑在 `allow-edits` 下运行，以及
+一切有风险的提示，除非`allow-all`。批准表面正常
+`approval-request` 事件。该适配器服务于 `fs/read_text_file` 和
+`fs/write_text_file` 针对会话工作区（拒绝逃逸路径
+it) 并写入发出 `file-change` 事件；终端方法未公布，
+因此代理使用自己的 shell。
+
+## Codex 身份验证：代码 UI 与 Harness 沙箱 {#codex-auth}
+
+有两个 Codex 表面，它们的身份验证方式不同：
+
+- **Agent-Native 代码/桌面** 在用户计算机上运行 `codex exec`。如果
+  用户已运行`codex login`，此本地运行重用任何ChatGPT
+  通过订阅或API密钥验证已安装的Codex CLI报告
+  `codex login status`.
+- **`ai-sdk-harness:codex`**加载`@ai-sdk/harness-codex`，它驱动Codex
+  通过 `@openai/codex-sdk` 进入线束沙箱。它不会默默地
+  继承用户的桌面 `~/.codex` 登录名，因为沙箱可能是远程的
+  或孤立。对于可信/私有沙箱，请选择使用 `codexCliAuth: true`；
+  Agent-Native 将本地 Codex CLI auth 文件复制到沙箱中
+  安全带启动。对于托管或共享沙箱，配置 API-key / gateway
+  改为验证。
+
+因此，如果有人询问哪个包带有 Codex OAuth 路径：用于本地编码
+会话，使用`@agent-native/core` /桌面加上已安装的
+`@openai/codex` CLI 和 `codex login`。对于沙盒 `ai-sdk-harness:codex`，
+将登录信息复制到沙箱时使用显式 `codexCliAuth` 选择加入
+可以接受。
+
+```ts
+const adapter = resolveAgentHarness("ai-sdk-harness:codex", {
+  codexCliAuth: true,
+});
+```
+
+`codexCliAuth: true` 读取为 `CODEX_HOME/auth.json` 或 `~/.codex/auth.json`。至
+指向不同的本地登录，通过
+`{ codexCliAuth: { codexHome: "/path/to/.codex" } }` 或
+`{ codexCliAuth: { authJsonPath: "/path/to/auth.json" } }`.
+
+## 注册并解析 {#register-resolve}
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+const adapter = resolveAgentHarness("ai-sdk-harness:codex");
+```
+
+`resolveAgentHarness(name, config?)` 返回 `AgentHarnessAdapter`。
+可选的 `config` 被转发到适配器工厂 - 用于 AI SDK 适配器
+映射到 `AiSdkHarnessAdapterOptions`（`label`、`description`，
+仅 `permissionMode`、`harnessOptions`、`agentOptions` 和 Codex
+`codexCliAuth`）。使用`listAgentHarnesses()`枚举注册的内容
+一个选择器。
+
+## 跑一圈 {#run-a-turn}
+
+`startAgentHarnessRun` 将线束会话桥接到共享运行管理器
+生命周期。它创建（或重用）本机会话，保留它，流式传输
+turn，将每个线束事件转换为转录事件，并分离
+回合完成时可恢复状态。
+
+```ts
+import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
+
+const run = startAgentHarnessRun({
+  runId,
+  threadId,
+  adapter,
+  input: { prompt },
+  createSession: {
+    sessionId,
+    resumeState, // opaque value from a previous turn, if resuming
+    instructions,
+    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
+    permissionMode: "allow-reads",
+    tools, // a narrow, intentional set of host tools (see below)
+  },
+  ownerEmail,
+  orgId,
+});
+```
+
+`startAgentHarnessRun`从运行管理器返回`ActiveRun`，所以轮到
+通过现有的跑步路线、成绩单和取消显示，就像
+任何其他代理运行。传递已经创建的 `session` 而不是 `createSession`
+继续您在内存中保存的会话。
+
+## 会议和简历 {#sessions}
+
+线束拥有长期存在的本机会话状态。 Agent-Native 将其保留在 SQL
+因此线程可以在轮流、进程和部署中生存。 `resumeState`
+是**不透明** - Agent-Native 存储它并将其返还，但从不检查或
+解释它。
+
+```an-diagram title="Resume across turns, processes, and deploys" summary="Each turn detaches an opaque resumeState into SQL; the next turn feeds it back into createSession instead of replaying chat history."
+{
+  "html": "<div class=\"diagram-resume\"><div class=\"diagram-node\" data-rough>Turn N<br><small class=\"diagram-muted\">streamTurn</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>detach &rarr; resumeState<br><small class=\"diagram-muted\">opaque · SQL harness session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Turn N+1<br><small class=\"diagram-muted\">createSession.resumeState</small></div></div>",
+  "css": ".diagram-resume{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-resume .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```ts
+import {
+  getLatestAgentHarnessSessionForThread,
+  listAgentHarnessSessions,
+} from "@agent-native/core/agent/harness";
+
+const last = await getLatestAgentHarnessSessionForThread(threadId);
+// Feed last?.resumeState into createSession.resumeState on the next turn.
+```
+
+商店还公开了`saveAgentHarnessSession`、`updateAgentHarnessSession`，
+`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
+`markAgentHarnessSessionStopped` 和 `ensureAgentHarnessSessionTables`。
+`startAgentHarnessRun` 为您调用保存/更新/停止路径；伸手去够他们
+仅直接在自定义主机中。
+
+## 托管工具和权限 {#host-tools}
+
+线束带有自己的本机工具（读取、编辑、写入、shell 等），因此
+您**不**将文件编辑重新公开为主机工具。仅通过**狭窄，
+当您通过 `createSession.tools` 有意设置** Agent-Native actions
+希望该工具能够实现特定的应用操作 - 并保留 `defineAction`
+身份验证、请求上下文、超时、截断和只读元数据完好无损
+你知道。
+
+`permissionMode` 控制安全带在未经批准的情况下可以执行的操作：
+
+| 模式          | 含义                                      |
+| ------------- | ----------------------------------------- |
+| `allow-reads` | 默认。读取运行；编辑和有风险的actions提示 |
+| `allow-edits` | 读取和编辑运行；其他有风险actions提示     |
+| `allow-all`   | 无审批门控                                |
+
+当线束暂停等待批准时，它会发出 `approval-request` 事件，并且
+会话标记为 `idle`，并记录待批准，因此 UI 可以
+将其浮出水面并根据用户的决定继续。请参阅
+[Human Approval](/docs/human-approval) 为批准表面。
+
+## 活动 {#events}
+
+线束会话流式传输 `AgentHarnessEvent` 值，其中 Agent-Native
+转换为标准 `AgentChatEvent` 流
+`agentHarnessEventToAgentChatEvents`。事件联盟覆盖`text-delta`，
+`thinking-delta`、`activity`、`tool-start`、`tool-done`（可携带
+`mcpApp` 原生小部件的负载）、`approval-request`、`file-change`，
+`compaction`、`usage`、`error` 和 `done`。因为工具结果流经
+相同的翻译，动作声明的本机小部件仍然呈现 - 请参阅
+[Native Chat UI](/docs/native-chat-ui).
+
+## 后台运行和UI {#background-runs}
+
+Harness 将项目运行到共享的 `BackgroundAgentRun` 形状中
+`createAgentHarnessBackgroundAgentController()` 并可通过
+现有运行路线为`goalId=agent-harness`。这意味着长期运行的 Claude
+代码或 Codex 会话出现在相同的后台运行和转录表面中
+作为代理团队和其他适配器，使用 `listAgentHarnessBackgroundRuns`，
+`listAgentHarnessBackgroundTranscriptEvents`、`getAgentHarnessBackgroundRun` 和
+`stopAgentHarnessBackgroundRun` 可用于自定义主机。
+
+## 自定义适配器 {#custom-adapters}
+
+要包装不是内置函数之一的运行时，请实现
+`AgentHarnessAdapter` 并注册它。适配器声明其功能并且
+创建会话；会话公开 `streamTurn` 和可选的 `continueTurn`，
+`approve`、`detach`、`stop` 和 `destroy`。
+
+```ts
+import {
+  registerAgentHarness,
+  type AgentHarnessAdapter,
+} from "@agent-native/core/agent/harness";
+
+const myHarness: AgentHarnessAdapter = {
+  name: "acme:my-coder",
+  label: "Acme Coder",
+  description: "Runs the Acme coding agent.",
+  installPackage: "@acme/coder",
+  capabilities: {
+    sandbox: true,
+    resumable: true,
+    approvals: true,
+    hostTools: true,
+    fileEvents: true,
+  },
+  async createSession(opts) {
+    // Build your native session and adapt it to AgentHarnessSession.
+    return createAcmeSession(opts);
+  },
+};
+
+registerAgentHarness({
+  name: myHarness.name,
+  label: myHarness.label,
+  description: myHarness.description,
+  installPackage: myHarness.installPackage,
+  capabilities: myHarness.capabilities,
+  create: () => myHarness,
+});
+```
+
+通过 `createSession` 中的动态导入和一个
+`installPackage` 提示。对于桥支持的编码线束，需要真正的
+沙箱/工作区提供程序，而不是在中运行任意编码代理
+主机进程 - 请参阅 [Sandbox Adapters](/docs/sandbox-adapters)。 AI SDK适配器
+（`createAiSdkHarnessAdapter`，由 `@ai-sdk/harness` 的 `HarnessAgent` 支持）是
+此合约的一个实现，而不是公共抽象。
+
+## 不要 {#donts}
+
+- 请勿将 Claude 代码、Codex、光标、Mastra 或 Pi 添加为 `AgentEngine`。他们
+  拥有自己的循环；在 `AgentEngine.stream()` 下运行一个双运行循环
+  并丢失会话生命周期语义。
+- 不要每回合将完整的 Agent-Native 聊天历史记录重播到安全带中。简历
+  使用 `resumeState` 的线束会话。
+- 不要将`resumeState`存储在`application_state`中。它属于安全带
+  会话 SQL 表。
+- 默认情况下，不要将每个应用操作公开给每个线束会话。递给它
+  小型、专用工具集。
+
+## 相关文档 {#related-docs}
+
+- [Native Chat UI](/docs/native-chat-ui) — 将您自己的代理置于 UI 与 `AgentChatRuntime` 的聊天后面。
+- [Agent Surfaces](/docs/agent-surfaces) — 选择无头、聊天、边车或完整应用。
+- [Agent-Native Code UI](/docs/code-agents-ui) — 可重用的编码工作区表面。
+- [Custom Agents & Teams](/docs/agent-teams) — 后台运行和子代理委派。
+- [Sandbox Adapters](/docs/sandbox-adapters) — 用于编码工具的可插入执行后端。
+- [Human Approval](/docs/human-approval) — 批准表面线束运行使用。

package/docs/content/locales/zh-CN/human-approval.md

@@ -0,0 +1,86 @@
+---
+title: "人在环批准"
+description: "在高后果操作运行之前暂停代理 - defineAction 的 needApproval 门会发出一个approval_required 事件，人工批准，然后工具才会执行。"
+---
+
+# 人在环批准
+
+大多数 actions 应该直接运行。其中一些操作（发送电子邮件、为卡充值、删除帐户）是面向外部且难以撤消的，您不希望代理自主执行这些操作。对于这些，`defineAction` 有一个选择加入的**批准门**：当代理尝试调用该操作时，循环会暂停，向人类显示批准/拒绝功能，并*仅*在人类批准该特定调用后才运行该操作。
+
+> [!WARNING]
+> 保持很少的批准。每个门控操作都是代理循环中的硬停止——它会中断运行并需要人工往返。仅将 `needsApproval` 用于真正后果严重、难以撤销、面向外的操作。如果您发现自己对读取或例行写入进行门控，那么您就错了。默认为**关闭**，几乎每个操作都应将其关闭。
+
+## `needsApproval` 门 {#needs-approval}
+
+在 `defineAction` 上设置 `needsApproval`。它接受布尔值或谓词：
+
+```an-annotated-code title="Gating the one consequential action"
+{
+  "filename": "actions/send-email.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Send an email via Gmail.\",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting/queueing is\n  // unaffected — only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});",
+  "annotations": [
+    { "lines": "10", "label": "The whole gate", "note": "One flag. With it truthy and the call unapproved, the loop stops before `run` — the model never reaches the side effect on its own." },
+    { "lines": "11-13", "label": "run() is untouched", "note": "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`." }
+  ]
+}
+```
+
+- **`needsApproval: true`** — 始终需要批准。
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** — 仅当谓词返回 true 时才需要批准。有条件地选择门，例如仅适用于外部收件人或仅高于美元阈值：
+
+  ```ts
+  needsApproval: (args) => !args.to.endsWith("@your-company.com"),
+  ```
+
+  保持谓词纯粹且快速。 **关闭失败**：如果谓词抛出异常，框架会将其视为“需要批准”，而不是默默地运行后果严重的操作。
+
+当 `needsApproval` 被省略时，行为是逐字节不变的——公共路径上没有额外的成本。
+
+这对于旧版 `parameters` 样式的 actions 和基于架构的 actions，以及应用内代理、子代理、A2A 和 MCP 调用者（每个代理通过同一循环进行表面路由）的工作原理相同。
+
+## 循环如何暂停 {#loop}
+
+当代理调用门控操作并且此特定调用尚未获得批准时，循环不会执行 `run()`。相反，它：
+
+1. 解析门。对于谓词，它调用`needsApproval(input, ctx)`；抛出被视为“必须批准”（失败关闭）。
+2. 发出 `tool_start` 事件（以便 UI 显示呼叫），然后立即发出 **`approval_required`** 事件，然后停止转弯。该操作的副作用永远不会发生。
+
+`approval_required` 事件包含客户端呈现可供性所需的一切：
+
+| 字段          | 类型     | 注释                                         |
+| ------------- | -------- | -------------------------------------------- |
+| `tool`        | `string` | 代理尝试调用的操作名称。                     |
+| `input`       | 对象     | 代理传递的参数。                             |
+| `approvalKey` | `string` | **稳定密钥**客户端回显以批准*此确切的调用*。 |
+| `toolCallId`  | `string` | 模型端工具调用 ID（如果可用）。              |
+
+`approvalKey` 是根据工具名称及其输入确定性派生的，因此相同的逻辑调用始终会生成相同的密钥。模型永远不会看到或设置它 - 它纯粹是框架和人类的批准功能之间的握手。
+
+暂停工具返回一个结果，告诉模型转动已暂停并且不再重试，因此模型不会旋转。
+
+## 人类如何认可 {#approve}
+
+在 `approval_required` 上，聊天 UI 在暂停的工具调用上呈现 **批准/拒绝** 提示。这是在 `AssistantChat` 中自动连接的 - 您无需根据模板构建它。
+
+- **批准**重新发出在 `approvedToolCalls: [approvalKey]` 中携带呼叫密钥的轮次（普通的继续消息）。在重新发出的回合中，门会看到已批准的集合中的密钥，并让特定的调用正常运行。
+- **Deny** 在本地消除可供性；没有重新发出任何内容，因此该操作永远不会运行。
+
+`approvedToolCalls` 是聊天请求 (`AgentChatRequest.approvedToolCalls`) 上的字段。其中不存在的密钥将保持暂停状态 - 批准一个呼叫永远不会茫然地批准其他呼叫。因为密钥是内容寻址的，所以批准授权*使用这些参数进行调用*；如果模型稍后建议不同的发送，那就是新的密钥和新的批准。
+
+## 端到端 {#flow}
+
+```an-diagram title="The approval interrupt" summary="A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key; only then does the side effect happen."
+{
+  "html": "<div class=\"diagram-approve\"><div class=\"diagram-box\" data-rough>Agent calls send-email</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel warn\" data-rough><strong>Gate truthy, call not yet approved</strong><small class=\"diagram-muted\">loop emits tool_start + approval_required { tool, input, approvalKey }</small><span class=\"diagram-pill warn\">turn pauses &mdash; run() did NOT execute</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Human clicks Approve in chat<br><small class=\"diagram-muted\">client re-issues the turn with approvedToolCalls: [approvalKey]</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel ok\" data-rough><span class=\"diagram-pill ok\">Gate sees the key &rarr; run() executes &rarr; email sends</span></div></div>",
+  "css": ".diagram-approve{display:flex;flex-direction:column;align-items:center;gap:8px}.diagram-approve .diagram-panel{display:flex;flex-direction:column;gap:6px;align-items:center;padding:12px 16px;text-align:center}.diagram-approve .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+在框架中此门的典型（并且故意很少）使用是邮件模板的 `send-email` 操作，该操作设置 `needsApproval: true`，以便代理可以自由起草和排队，但在没有人工批准特定发送的情况下永远无法实际发送消息。
+
+## 相关
+
+- [**Actions**](/docs/actions#needs-approval) — 完整的 `defineAction` 表面，包括用于验证返回值的 `outputSchema`。
+- [**Security**](/docs/security) - 何时达到批准门与向模型隐藏操作。
+- [**Mail template**](/docs/template-mail) — `send-email` 是参考示例。

package/docs/content/locales/zh-CN/internationalization.md

@@ -1,15 +1,18 @@
 ---
 title: "国际化"
-description: "使用共享语言目录、语言选择器、浏览器语言回退和按语言区分的文档内容来本地化 Agent Native 应用。"
+description: "使用共享区域设置目录、语言选择器、浏览器语言回退和区域设置感知文档内容本地化 Agent Native 应用。"
 ---
 
 # 国际化
 
-Agent Native 应用可以通过共享的 `@agent-native/core/client/i18n` 运行时来本地化框架和模板 UI。框架把用户的语言选择存储在 SQL 设置中，将它暴露为 actions，并在应用尚未翻译某个字符串时回退到 English。
+Agent Native应用程序可以通过共享本地化框架和模板UI
+`@agent-native/core/client/i18n` 运行时。框架存储用户的
+SQL 设置中的语言选择，将其公开为 actions，并回退到
+当应用尚未翻译字符串时为英语。
 
-## 运行时 {#runtime}
+## 运行时
 
-通过 `AppProviders` 使用 provider：
+通过`AppProviders`使用提供者：
 
 ```tsx
 import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
@@ -27,11 +30,14 @@ const LOCALE_INIT_SCRIPT = getLocaleInitScript();
 </AppProviders>;
 ```
 
-`getLocaleInitScript()` 会在 React hydration 之前设置初始的 `lang`、`dir` 和 `window.__AGENT_NATIVE_LOCALE__`。公共 SSR 路由可以从 `@agent-native/core/server` 调用 `resolveLocaleFromRequest()`，并把解析出的 locale/catalog 传入脚本，避免 hydration 不一致。
+`getLocaleInitScript()` 设置初始 `lang`、`dir` 和
+`window.__AGENT_NATIVE_LOCALE__` 在 React 水合之前。公共SSR路线可以
+从`@agent-native/core/server`调用`resolveLocaleFromRequest()`并传递
+将区域设置/目录解析到该脚本中以避免水合不匹配。
 
-## 目录 {#catalogs}
+## 目录
 
-每个本地化模板都把目录放在 `app/i18n/` 下：
+每个本地化模板都将目录保存在 `app/i18n/` 下：
 
 ```ts
 // app/i18n/index.ts
@@ -52,44 +58,76 @@ export const i18nCatalog = {
 } satisfies AgentNativeI18nCatalog;
 ```
 
-始终打包 `en-US`。非 English 目录使用动态导入，这样用户只下载当前语言。支持的 locale codes 是 `en-US`、`zh-CN`、`es-ES`、`fr-FR`、`de-DE`、`ja-JP`、`ko-KR`、`pt-BR`、`hi-IN` 和 `ar-SA`。
+始终捆绑 `en-US`。动态导入非英语目录，仅限用户
+下载活动区域设置。支持的区域设置代码为 `en-US`、`zh-CN`、
+`es-ES`、`fr-FR`、`de-DE`、`ja-JP`、`ko-KR`、`pt-BR`、`hi-IN` 和 `ar-SA`。
 
-## UI {#ui}
+## UI
 
-界面字符串使用 `useT()`，设置页使用 `<LanguagePicker />`：
+使用 `useT()` 作为接口字符串，并将 `<LanguagePicker />` 放在应用程序的
+`/settings` 页面。侧边栏应用程序应在应用程序侧边栏中公开**设置**；
+标题语言图标只是一个快捷方式。
 
 ```tsx
-import { LanguagePicker, useT } from "@agent-native/core/client";
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
 
-function SettingsLanguageCard() {
+function SettingsPage() {
   const t = useT();
   return (
     <>
       <h2>{t("settings.languageTitle")}</h2>
       <LanguagePicker label={t("settings.languageLabel")} />
+
+      <h2>{t("settings.agentTitle")}</h2>
+      <p>{t("settings.agentDescription")}</p>
+      <button type="button" onClick={() => openAgentSettings()}>
+        {t("settings.openAgentSettings")}
+      </button>
     </>
   );
 }
 ```
 
-日期、数字、相对时间和列表使用 `useFormatters()`。不要把依赖 locale 的日期或数字格式直接放进翻译字符串。
+“代理设置”控件应打开右侧代理侧边栏的“设置”选项卡
+用于模型、API 按键、自动化、语音和其他框架级控件。
+应用可能会在自己的设置页面中复制高价值的框架设置
+当设置是应用程序的核心，但侧边栏设置选项卡仍然是
+事实来源。
+
+使用 `useFormatters()` 表示日期、数字、相对时间和列表。不要放
+翻译字符串中区域设置敏感的日期/数字格式。
 
-## 文档站点内容 {#docs-site-content}
+## 文档网站内容 {#docs-site-content}
 
-公共文档页使用同一个 core provider，但设置 `persistPreference={false}`，因此匿名文档流量使用 localStorage 和浏览器语言，而不是 SQL 设置 actions。English 源文件仍在 `packages/core/docs/content/*.md`。本地化页面覆盖文件放在 `packages/core/docs/content/locales/<locale>/<slug>.md`。
+公共文档页面使用相同的核心提供程序，但具有
+`persistPreference={false}` 因此匿名文档流量使用 localStorage 和
+浏览器语言而不是 SQL 设置 actions。英文源代码保留在
+`packages/core/docs/content/*.md`。本地化页面覆盖其旁边的实时页面
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
 
-使用与应用目录相同的 BCP-47 locale codes。文件 slug 要与 English 源保持一致，翻译后的标题要用 `{#anchor}` 保留稳定锚点，并且不要翻译 routes、action names、protocol fields、env vars 或 provider names。如果某个 locale 没有某页 Markdown，文档站点会对该页回退到 English，同时继续本地化导航和 chrome。
+使用与应用程序目录相同的 BCP-47 区域设置代码。保留与
+英文来源，在翻译的标题上使用 `{#anchor}` 保留稳定的锚点，
+并留下路由、操作名称、协议字段、环境变量和提供程序名称
+未翻译。如果某个语言环境没有为页面翻译 Markdown，则文档站点
+该页面恢复为英语，同时仍本地化导航和 Chrome。
 
-## Actions 与持久化 {#actions-and-persistence}
+## Actions和坚持
 
-每个应用都会继承：
+每个应用程序都会继承：
 
-- `get-localization-preference` — 读取当前用户的 `{ locale }`
-- `set-localization-preference` — 设置 `"system"` 或支持的 locale
+- `get-localization-preference` — 读取当前用户的`{ locale }`
+- `set-localization-preference` — 设置 `"system"` 或支持的区域设置
 
-持久值存储在用户作用域 SQL 设置的 `localization` 下。`localStorage` 只用于 hydration 前和匿名回退。当前 locale 会同步到 application state，作为环境上下文，让 agents 能看到当前界面语言。
+持久值存在于 `localization` 下的用户范围 SQL 设置中。
+`localStorage` 仅用于预水合和匿名回退。主动
+区域设置作为环境上下文镜像到应用程序状态中，以便代理可以看到
+当前界面语言。
 
-## Guard {#guard}
+## 守卫
 
 运行：
 
@@ -97,6 +135,11 @@ function SettingsLanguageCard() {
 pnpm guard:i18n-catalogs
 ```
 
-guard 会通过 `Intl.PluralRules` 验证支持的 locale 文件名、key parity、placeholder parity、stale keys 和 CLDR plural categories。它检查结构，不检查翻译质量；高可见度字符串仍需要人工审校。
+守卫验证支持的区域设置文件名、密钥奇偶校验、占位符奇偶校验，
+过时的密钥，以及 CLDR 复数类别到 `Intl.PluralRules`。它检查
+结构，而不是翻译质量；高可见度字符串仍然需要人类
+审查。
 
-不要翻译稳定标识符，例如 action names、routes、enum values、app-state keys、database values、protocol fields、env var names 或 provider names。
+不要翻译稳定的标识符，例如操作名称、路由、枚举值，
+应用程序状态键、数据库值、协议字段、环境变量名称或提供程序
+名字。