@agent-native/core 0.79.2 → 0.79.5

package/corpus/core/docs/content/locales/zh-TW/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="安全帶擁有它的環； Agent-Native 驅動工作階段" summary="AgentHarness 底層 creates/resumes 本機工作階段，將其事件流式傳輸到正常轉錄本中，並在輪次之間將恢復狀態保留在 SQL 中。"
+{
+  "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="跨回合、流程和部署恢復" summary="每一輪都會將一個不透明的resumeState分離到SQL中；下一回合將其意見回饋到 createSession 而不是重播聊天紀錄。"
+{
+  "html": "<div class=\"diagram-resume\"><div class=\"diagram-node\" data-rough>第 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\">不透明 · SQL harness 工作階段</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>第 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 聊天介面](/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 聊天介面](/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/corpus/core/docs/content/locales/zh-TW/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="限制一項後果性行動"
+{
+  "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": "整個大門", "note": "一面旗帜。當它為真且調用未獲批準時，循環會在 `run` 之前停止 - 模型本身永遠不會達到副作用。" },
+    { "lines": "11-13", "label": "run() is untouched", "note": "處理程序保持不變。批準是由其週圍的循環強制執行的，而不是由 `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="審批中斷" summary="門控調用會在 run() 觸發之前暫停回合。批準重新發出攜帶呼叫金鑰的回合；只有這樣，副作用才會發生。"
+{
+  "html": "<div class=\"diagram-approve\"><div class=\"diagram-box\" data-rough>代理調用 send-email</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel warn\" data-rough><strong>Gate 為真，調用尚未批準</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>人在聊天中點擊批準<br><small class=\"diagram-muted\">用戶端用 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/corpus/core/docs/content/locales/zh-TW/internationalization.md

@@ -0,0 +1,147 @@
+---
+title: "國際化"
+description: "使用共用區域設定目錄、語言選取器、瀏覽器語言回退和區域設定感知檔案內容本機化 Agent Native 應用。"
+---
+
+# 國際化
+
+Agent Native應用程式可以通過共用本機化框架和範本UI
+`@agent-native/core/client/i18n` 執行時。框架存儲使用者的
+SQL 設定中的語言選取，將其公開為 actions，並回退到
+當應用尚未翻譯字串時為英語。
+
+## 執行時
+
+通過`AppProviders`使用提供者：
+
+```tsx
+import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import { i18nCatalog } from "./i18n";
+
+const LOCALE_INIT_SCRIPT = getLocaleInitScript();
+
+<script
+  data-agent-native-locale-init
+  dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+/>;
+
+<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+  <Outlet />
+</AppProviders>;
+```
+
+`getLocaleInitScript()` 設定初始 `lang`、`dir` 和
+`window.__AGENT_NATIVE_LOCALE__` 在 React 水合之前。公開SSR路線可以
+從`@agent-native/core/server`調用`resolveLocaleFromRequest()`並傳遞
+將區域設定/目錄解析到該腳本中以避免水合不匹配。
+
+## 目錄
+
+每個本機化範本都將目錄儲存在 `app/i18n/` 下：
+
+```ts
+// app/i18n/index.ts
+import enUS from "./en-US";
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+
+export const i18nCatalog = {
+  sourceLocale: "en-US",
+  messages: enUS,
+  loadMessages: async (locale) => {
+    switch (locale) {
+      case "zh-CN":
+        return (await import("./zh-CN")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;
+```
+
+始終捆綁 `en-US`。動態匯入非英語目錄，僅限使用者
+下載活動區域設定。支援的區域設定程式碼為 `en-US`、`zh-CN`、
+`es-ES`、`fr-FR`、`de-DE`、`ja-JP`、`ko-KR`、`pt-BR`、`hi-IN` 和 `ar-SA`。
+
+## UI
+
+使用 `useT()` 作為介面字串，並將 `<LanguagePicker />` 放在應用程式的
+`/settings` 頁面。側邊欄應用程式應在應用程式側邊欄中公開**設定**；
+標題語言圖標只是一個快捷方式。
+
+```tsx
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
+
+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>
+    </>
+  );
+}
+```
+
+“代理設定”控件應開啟右側代理側邊欄的“設定”分頁
+用於模型、API 按鍵、自動化、語音和其他框架級控件。
+應用可能會在自己的設定頁面中複製高價值的框架設定
+當設定是應用程式的核心，但側邊欄設定分頁仍然是
+事實來源。
+
+使用 `useFormatters()` 表示日期、數字、相對時間和列表。不要放
+翻譯字串中區域設定敏感的日期/數字格式。
+
+## 檔案網站內容 {#docs-site-content}
+
+公開檔案頁面使用相同的核心提供程序，但具有
+`persistPreference={false}` 因此匿名檔案流量使用 localStorage 和
+瀏覽器語言而不是 SQL 設定 actions。英文來源程式碼保留在
+`packages/core/docs/content/*.md`。本機化頁面覆蓋其旁邊的實時頁面
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+使用與應用程式目錄相同的 BCP-47 區域設定程式碼。保留與
+英文來源，在翻譯的標題上使用 `{#anchor}` 保留穩定的錨點，
+並留下路由、操作名稱、協議欄位、環境變數和提供程序名稱
+未翻譯。如果某個語言環境沒有為頁面翻譯 Markdown，則檔案站點
+該頁面恢復為英語，同時仍本機化導覽和 Chrome。
+
+Docs Markdown 可能包含結構化的 `an-*` 可視塊。請在合理時翻譯其中面向使用者的文本欄位，例如 file-tree 標題和 `entries[].note`、callout 內文、tab 標籤以及 annotated-code 的 labels/notes。保持穩定標識符不變：檔案名、路徑、env vars、路由字串、action 名稱、language tags、程式碼片段、JSON keys 和協議名稱。
+
+## Actions和堅持
+
+每個應用程式都會繼承：
+
+- `get-localization-preference` — 讀取目前使用者的`{ locale }`
+- `set-localization-preference` — 設定 `"system"` 或支援的區域設定
+
+持久值存在於 `localization` 下的使用者範圍 SQL 設定中。
+`localStorage` 僅用於預水合和匿名回退。主動
+區域設定作為環境上下文鏡像到應用程式狀態中，以便代理可以看到
+目前介面語言。
+
+## 守衛
+
+執行：
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+守衛驗證支援的區域設定檔案名、金鑰對等、預留位置對等，
+過時的金鑰，以及 CLDR 複數類別到 `Intl.PluralRules`。它檢查
+結構，而不是翻譯品質；高可見度字串仍然需要人類
+審查。
+
+不要翻譯穩定的標識符，例如操作名稱、路由、枚舉值，
+應用程式狀態鍵、資料庫值、協議欄位、環境變數名稱或提供程序
+名字。