@agent-native/core 0.79.12 → 0.79.16

package/corpus/core/docs/content/locales/zh-TW/actions.md

@@ -7,27 +7,27 @@ description: "defineAction - 成為代理工具、型別化前端掛鉤、框架
 
 Actions 是您的應用所做的任何事情的唯一事實來源。使用 `defineAction()` 定義一次操作，將其放入 `actions/` 中，然後立即可用：
 
-- **代理工具** — 代理通過 zod 派生的 JSON 架構檢視它，並可以在聊天中調用它。
+- **代理工具** — 代理透過 zod 派生的 JSON 架構檢視它，並可以在聊天中呼叫它。
 - **型別安全 React 掛鉤** - 前端的 `useActionQuery("name")` 和 `useActionMutation("name")`，從架構推斷的型別。
-- **指令式用戶端調用** — 當鉤子不適合時 `callAction("name", params)`。
+- **指令式用戶端呼叫** — 當鉤子不適合時 `callAction("name", params)`。
 - **框架傳輸** — 由這些鉤子後面的框架自動安裝，並可供外部 HTTP 用戶端使用。
-- **MCP 工具** - 暴露給 Claude、ChatGPT 自訂 MCP 應用、Claude 桌面/程式碼、光標、Codex 和任何其他 MCP 用戶端。
-- **A2A 工具** — 由其他代理本機應用通過 A2A 調用。
-- **CLI 指令** - `pnpm action <name>` 用於腳本和開發循環。
+- **MCP 工具** - 暴露給 Claude、ChatGPT 自訂 MCP 應用、Claude 桌面/程式碼、游標、Codex 和任何其他 MCP 用戶端。
+- **A2A 工具** — 由其他 Agent-Native 應用透過 A2A 呼叫。
+- **CLI 指令** - `pnpm action <name>` 用於指令碼和開發迴圈。
 
 一個定義，七個消費者。這是 [ladder](/docs/what-is-agent-native#the-ladder) 的第 3 級。
 如果您正在決定是否在聊天中、在聊天中無頭公開操作
 嵌入式 sidecar，或作為完整的應用螢幕，請參閱 [Agent Surfaces](/docs/agent-surfaces)。
 
-```an-diagram title="一個定義，七個消費者" summary="單個 defineAction() 扇出到每個表面 - 代理、UI、HTTP、MCP、A2A 和 CLI - 具有一個經過驗證的模式和一個 run() 主體。"
+```an-diagram title="一個定義，七個消費者" summary="單一 defineAction() 扇出到每個表面 - 代理、UI、HTTP、MCP、A2A 和 CLI - 具有一個經過驗證的模式和一個 run() 主體。"
 {
-  "html": "<div class=\"diagram-fanout\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">defineAction()</span><small class=\"diagram-muted\">schema + run()，只定義一次</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><div class=\"diagram-node\">Agent 工具<br><small class=\"diagram-muted\">上下文中的 JSON Schema</small></div><div class=\"diagram-node\">React 鉤子<br><small class=\"diagram-muted\">useActionQuery/Mutation</small></div><div class=\"diagram-node\">callAction()<br><small class=\"diagram-muted\">指令式用戶端</small></div><div class=\"diagram-node\">HTTP<br><small class=\"diagram-muted\">/_agent-native/actions/:name</small></div><div class=\"diagram-node\">MCP 工具<br><small class=\"diagram-muted\">外部主機</small></div><div class=\"diagram-node\">A2A 工具<br><small class=\"diagram-muted\">其他 agent-native 應用</small></div><div class=\"diagram-node\">CLI<br><small class=\"diagram-muted\">pnpm action &lt;name&gt;</small></div></div></div>",
+  "html": "<div class=\"diagram-fanout\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">defineAction()</span><small class=\"diagram-muted\">schema + run()，只定義一次</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><div class=\"diagram-node\">Agent 工具<br><small class=\"diagram-muted\">脈絡中的 JSON Schema</small></div><div class=\"diagram-node\">React 鉤子<br><small class=\"diagram-muted\">useActionQuery/Mutation</small></div><div class=\"diagram-node\">callAction()<br><small class=\"diagram-muted\">指令式用戶端</small></div><div class=\"diagram-node\">HTTP<br><small class=\"diagram-muted\">/_agent-native/actions/:name</small></div><div class=\"diagram-node\">MCP 工具<br><small class=\"diagram-muted\">外部主機</small></div><div class=\"diagram-node\">A2A 工具<br><small class=\"diagram-muted\">其他 agent-native 應用</small></div><div class=\"diagram-node\">CLI<br><small class=\"diagram-muted\">pnpm action &lt;name&gt;</small></div></div></div>",
   "css": ".diagram-fanout{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fanout .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-fanout .diagram-arrow{font-size:22px;line-height:1}.diagram-fanout .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
 }
 ```
 
-如果 UI 和代理都需要做某事，請采取行動 - 而不是自訂
-路線。對於何時路由型協議才是正確的調用，請參閱[首選 Actions
+如果 UI 和代理都需要做某事，請採取行動 - 而不是自訂
+路由。對於何時路由型協議才是正確的呼叫，請參閱[首選 Actions
 對於應用程式操作](/docs/server#actions-first)。
 
 ## 從一個動作開始 {#hello-action}
@@ -61,19 +61,19 @@ pnpm action hello '{"name":"Steve"}'
 ```
 
 CLI 接受 JSON 物件作為操作輸入，它與結構化的匹配
-代理已進行工具調用。簡單的標志仍然適用於快速手動執行：
+代理已進行工具呼叫。簡單的標誌仍然適用於快速手動執行：
 
 ```bash
 pnpm action hello --name Steve
 ```
 
-然後針對該資料夾執行應用程式代理循環：
+然後針對該資料夾執行應用程式代理迴圈：
 
 ```bash
 pnpm agent "Call hello for Steve and explain the result"
 ```
 
-這與您計畫的作業、聊天 UI、外部 MCP 循環相同的應用程式代理
+這與您計畫的作業、聊天 UI、外部 MCP 迴圈相同的應用程式代理
 工具，以及未來的螢幕將使用。聊天和域範本用於新增 UI
 大約 actions，不是操作本身的必需先決條件。
 
@@ -85,28 +85,28 @@ pnpm agent "Call hello for Steve and explain the result"
   "language": "ts",
   "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Reply to an email thread in the user's voice.\",\n  schema: z.object({\n    emailId: z.string().describe(\"The id of the email to reply to.\"),\n    body: z.string().describe(\"The reply body, in markdown.\"),\n  }),\n  run: async ({ emailId, body }) => {\n    await db.insert(replies).values({ emailId, body });\n    return { ok: true, emailId };\n  },\n});",
   "annotations": [
-    { "lines": "5", "label": "工具表面", "note": "`description` 是代理讀取以決定何時調用此動作的內容。每個欄位的 `.describe()` 也會進入 JSON Schema。" },
+    { "lines": "5", "label": "工具表面", "note": "`description` 是代理讀取以決定何時呼叫此動作的內容。每個欄位的 `.describe()` 也會進入 JSON Schema。" },
     { "lines": "6-9", "label": "型別化契約", "note": "一個 schema 會驗證來自**每個**介面的輸入，並轉換為供模型使用的 JSON Schema。無效輸入永遠不會進入 `run`。" },
     { "lines": "10-13", "label": "單一實現", "note": "`run` 主體是唯一事實來源，UI 按鈕和代理工具都會執行這一段。" }
   ]
 }
 ```
 
-就是這樣。該框架會自動發現 `actions/` 中的每個檔案並在啟動時掛載它們。
+就是這樣。此框架會自動發現 `actions/` 中的每個檔案並在啟動時掛載它們。
 
 ### 架構選項 {#schemas}
 
-`schema` 接受任何 [Standard Schema](https://standardschema.dev) 兼容庫：
+`schema` 接受任何 [Standard Schema](https://standardschema.dev) 相容庫：
 
 - **Zod** (v4) — 最常見、最佳型別推斷，自動轉換為 JSON 架構。
 - **Valibot** — 最小捆綁包大小（如果重要的話）。
 - **ArkType** — 如果您喜歡語法。
 
-該架構將轉換為 Claude API 工具定義的 JSON 架構，並在執行時用於在 `run()` 觸發之前驗證輸入。無效輸入永遠不會到達您的處理程序。
+該架構將轉換為 Claude API 工具定義的 JSON 架構，並在執行時用於在 `run()` 觸發之前驗證輸入。無效輸入永遠不會到達您的處理常式。
 
 ### 驗證返回值 {#output-schema}
 
-`schema` 驗證*輸入*。要驗證操作 **返回**，請傳遞 `outputSchema`（任何標準模式兼容模式 - Zod、Valibot、ArkType、與 `schema` 相同的表面）。框架在 `run()` 解析之後驗證結果，並與輸入驗證組合：在 `run` 之前驗證輸入，在 `run` 之後驗證輸出。
+`schema` 驗證*輸入*。要驗證操作 **返回**，請傳遞 `outputSchema`（任何標準模式相容模式 - Zod、Valibot、ArkType、與 `schema` 相同的表面）。框架在 `run()` 解析之後驗證結果，並與輸入驗證組合：在 `run` 之前驗證輸入，在 `run` 之後驗證輸出。
 
 ```ts
 export default defineAction({
@@ -131,9 +131,9 @@ export default defineAction({
 | `"strict"`   | 拋出一個明顯的錯誤，以便大聲地浮現出有問題的操作。             |
 | `"fallback"` | 返回提供的 `outputFallback` 值來代替無效結果。                 |
 
-成功後，將返回 **validated** 值，因此 `outputSchema` 上定義的任何強制或預設值都會生效（鏡像輸入路徑）。當沒有提供 `outputSchema` 時，行為是逐字節不變的——沒有包裝。這是從 Mastra/Flue 結構化輸出借來的，並且在操作層上保持無依賴性。
+成功後，將返回 **validated** 值，因此 `outputSchema` 上定義的任何強制或預設值都會生效（鏡像輸入路徑）。當沒有提供 `outputSchema` 時，行為是逐位元組不變的——沒有包裝。這是從 Mastra/Flue 結構化輸出借來的，並且在操作層上保持無依賴性。
 
-### HTTP設定 {#http}
+### HTTP 設定 {#http}
 
 預設情況下，每個操作都公開為 `POST /_agent-native/actions/<name>`。使用 `http` 選項覆蓋：
 
@@ -154,9 +154,9 @@ export default defineAction({
 {
   "method": "GET",
   "path": "/_agent-native/actions/get-lead",
-  "summary": "每個 action 都會自動掛載在這裡 - 檔案名就是 action 名稱。",
-  "description": "預設是 POST；`http: { method: \"GET\" }` 會讓它成為 GET。無論任何 `http.path` 覆蓋如何，React 鉤子 和 `callAction` 始終按名稱調用這個路徑。",
-  "auth": "工作階段 cookie；前端調用會攜帶 `X-Agent-Native-Frontend: 1`",
+  "summary": "每個 action 都會自動掛載在這裡 - 檔名就是 action 名稱。",
+  "description": "預設是 POST；`http: { method: \"GET\" }` 會讓它成為 GET。無論任何 `http.path` 覆蓋如何，React 鉤子 和 `callAction` 始終按名稱呼叫這個路徑。",
+  "auth": "工作階段 cookie；前端呼叫會攜帶 `X-Agent-Native-Frontend: 1`",
   "params": [
     { "name": "leadId", "in": "query", "type": "string", "required": true, "description": "GET 參數以查詢參數傳入；POST 參數以 JSON body 傳入。" }
   ],
@@ -167,39 +167,39 @@ export default defineAction({
 }
 ```
 
-- **`http: { method: "GET" | "POST" | "PUT" | "DELETE" }`** — 預設 `POST`。 `GET` actions 會自動標記為 `readOnly`，因此成功的調用不會觸發 UI 輪詢刷新。
-- **`http: { path: "..." }`** — 覆蓋 `/_agent-native/actions/` 下安裝的 URL。預設為檔案名。 **路徑覆蓋僅針對直接 HTTP 調用方更改 URL** — 無論此覆蓋如何，`useActionQuery`、`useActionMutation` 和 `callAction` 始終調用 `/_agent-native/actions/<name>`，因此覆蓋路徑會使這些掛鉤 404。僅對外部 HTTP 調用方使用路徑覆蓋。另請注意，覆蓋路徑中的 `:param` 路由段**不會**解析為 `run()` 參數 - 只有查詢字串參數和 JSON 內文欄位。
+- **`http: { method: "GET" | "POST" | "PUT" | "DELETE" }`** — 預設 `POST`。 `GET` actions 會自動標記為 `readOnly`，因此成功的呼叫不會觸發 UI 輪詢重新整理。
+- **`http: { path: "..." }`** — 覆蓋 `/_agent-native/actions/` 下安裝的 URL。預設為檔名。 **路徑覆蓋僅針對直接 HTTP 呼叫方更改 URL** — 無論此覆蓋如何，`useActionQuery`、`useActionMutation` 和 `callAction` 始終呼叫 `/_agent-native/actions/<name>`，因此覆蓋路徑會使這些掛鉤 404。僅對外部 HTTP 呼叫方使用路徑覆蓋。另請注意，覆蓋路徑中的 `:param` 路由段**不會**解析為 `run()` 參數 - 只有查詢字串參數和 JSON 內文欄位。
 - **`http: false`** — 完全停用 HTTP 端點。僅限代理 + CLI。
-- **`readOnly: true`** — 即使對於不變異的 POST actions 也顯式跳過輪詢刷新。
-- **`parallelSafe: true`** — 允許變異操作與其他同回合工具調用同時執行。僅當操作內部並發安全且與順序無關時才設定此項；預設情況下改變 actions 序列化。
+- **`readOnly: true`** — 即使對於不變異的 POST actions 也顯式跳過輪詢重新整理。
+- **`parallelSafe: true`** — 允許變異操作與其他同回合工具呼叫同時執行。僅當操作內部並發安全且與順序無關時才設定此項；預設情況下改變 actions 序列化。
 
 ### 保持操作面較小 {#small-surface}
 
-代理可以看到的每個動作都是模型上下文窗口中的一個工具，而長而重疊的工具列表會降低模型的工具選取品質。將操作介面設計為您維護的 API，而不是為每個 UI 功能提供一個操作：
+代理可以看到的每個動作都是模型脈絡視窗中的一個工具，而長而重疊的工具清單會降低模型的工具選取品質。將操作介面設計為您維護的 API，而不是為每個 UI 功能提供一個操作：
 
-- 更喜歡**一個 CRUD 風格的 `update`**，它采用一個可選欄位補丁，而不是 N 個每個欄位 actions（`update-name`、`update-order`、`update-color`，...）。調用者僅發送更改的內容。
-- 在為每個查詢/過濾器新增新的讀取操作之前，請使用通用逃生口：用於提供程序資料的 [provider API trio](/docs/template-dispatch) (`provider-api-catalog` / `provider-api-docs` / `provider-api-request`) 或用於應用程式資料的 dev `db-query` 工具。
-- 標記僅 UI 或編程 actions [`agentTool: false`](#agent-tool)，以便它們保持前端/HTTP 可調用，而無需在模型的工具列表中占用一個位置。
+- 更喜歡**一個 CRUD 風格的 `update`**，它采用一個可選欄位補丁，而不是 N 個每個欄位 actions（`update-name`、`update-order`、`update-color`，...）。呼叫者僅傳送更改的內容。
+- 在為每個查詢/過濾器新增新的讀取操作之前，請使用通用逃生口：用於提供者資料的 [provider API trio](/docs/template-dispatch) (`provider-api-catalog` / `provider-api-docs` / `provider-api-request`) 或用於應用程式資料的 dev `db-query` 工具。
+- 標記僅 UI 或程式化 actions [`agentTool: false`](#agent-tool)，以便它們保持前端/HTTP 可呼叫，而無需在模型的工具清單中佔用一個位置。
 - 刪除或隱藏 UI 不再使用的 actions，而不是將它們暴露給模型。
 
 回購級諮詢助手 `node scripts/audit-template-actions.mjs [template ...]`（別名 `pnpm actions:audit`）靜態掃描範本的 `actions/` 並標記可能的 UI 死 actions 和冗餘的每欄位叢集。它僅是建議性的（始終退出 0，永遠不會失敗 CI）並使用保守的啟發式方法，因此請檢視其建議，而不是將其視為錯誤。
 
-### 曝光標志 {#exposure-flags}
+### 曝游標誌 {#exposure-flags}
 
-四個標志控制誰可以調用操作。所有預設值都為允許值，因此您只需設定一個即可收緊特定表面。該表是一目了然的摘要；這些小節新增了每個需要的細節。
+四個標誌控制誰可以呼叫操作。所有預設值都為允許值，因此您只需設定一個即可收緊特定表面。該表是一目了然的摘要；這些小節新增了每個需要的細節。
 
-| 標記            | 預設         | 限制值→誰仍然可以調用                                          | 典型用途                                        |
+| 標記            | 預設         | 限制值→誰仍然可以呼叫                                          | 典型用途                                        |
 | --------------- | ------------ | -------------------------------------------------------------- | ----------------------------------------------- |
-| `agentTool`     | `true`       | `false` → 僅 UI、HTTP、CLI — **對模型隱藏**、MCP 和 A2A        | 僅 UI/程序化 actions，不應該花費工具槽          |
+| `agentTool`     | `true`       | `false` → 僅 UI、HTTP、CLI — **對模型隱藏**、MCP 和 A2A        | 僅 UI/程式化 actions，不應該花費工具槽          |
 | `toolCallable`  | `true`       | `false` → 一切**除了**沙盒擴充功能 iframe 橋 (403)             | 授權相鄰操作（刪除帳戶、更改組織成員資格/角色） |
 | `publicAgent`   | 關閉（私人） | `{ expose: true }` → 將操作新增到**公開** MCP/A2A/OpenAPI 表面 | 無需驗證即可存取安全讀取/攝取工具               |
-| `needsApproval` | `false`      | `true` → 特工**暫停**；人類必須批準特定的呼叫                  | 間接副作用（發送電子郵件、為卡充值、刪除）      |
+| `needsApproval` | `false`      | `true` → 代理**暫停**；人類必須核准特定的呼叫                  | 間接副作用（傳送電子郵件、為卡充值、刪除）      |
 
-這些是獨立的：`agentTool` 控制模型的視圖，`toolCallable` 僅控制擴充功能 iframe，`publicAgent` 新增選取加入的公開介面（公開 Web 路由絕不意味著公開工具暴露），而 `needsApproval` 在調用後控制執行 - 請參閱下面的 [Human-in-the-loop approval](#needs-approval)。
+這些是獨立的：`agentTool` 控制模型的檢視，`toolCallable` 僅控制擴充功能 iframe，`publicAgent` 新增選取加入的公開介面（公開 Web 路由絕不意味著公開工具暴露），而 `needsApproval` 在呼叫後控制執行 - 請參閱下面的 [Human-in-the-loop approval](#needs-approval)。
 
 #### `agentTool` — 隱藏模型 {#agent-tool}
 
-預設情況下，每個操作都是可調用的代理工具。設定 `agentTool: false` 以將其保留在框架的驗證 + 操作介面後面，同時將其從每個代理工具列表中刪除 - 它仍然可以從 UI (`useActionMutation` / `callAction`)、CLI 和 `/_agent-native/actions/<name>` 進行調用：
+預設情況下，每個操作都是可呼叫的代理工具。設定 `agentTool: false` 以將其保留在框架的驗證 + 操作介面後面，同時將其從每個代理工具清單中刪除 - 它仍然可以從 UI (`useActionMutation` / `callAction`)、CLI 和 `/_agent-native/actions/<name>` 進行呼叫：
 
 ```ts
 export default defineAction({
@@ -213,11 +213,11 @@ export default defineAction({
 });
 ```
 
-當您新增僅 UI 或純編程操作時，或者當 UI 停止使用您本來會暴露給模型的操作時，請使用它。
+當您新增僅 UI 或純程式化操作時，或者當 UI 停止使用您本來會暴露給模型的操作時，請使用它。
 
 #### `toolCallable` — 阻止擴充功能 iframe {#tool-callable}
 
-擴充功能 ([Alpine.js mini-apps in sandboxed iframes](/docs/extensions)) 通過 `appAction(name, params)` 調用 actions，以檢視者的權限、機密和 SQL 範圍執行。對於高爆炸半徑的操作，預設情況下信任度過高。設定 `toolCallable: false` 以使擴充功能橋返回 403，同時保持可從 UI、代理、CLI、MCP 和 A2A 調用的操作：
+擴充功能 ([Alpine.js mini-apps in sandboxed iframes](/docs/extensions)) 透過 `appAction(name, params)` 呼叫 actions，以檢視者的權限、機密和 SQL 範圍執行。對於高爆炸半徑的操作，預設情況下信任度過高。設定 `toolCallable: false` 以使擴充功能橋返回 403，同時保持可從 UI、代理、CLI、MCP 和 A2A 呼叫的操作：
 
 ```ts
 export default defineAction({
@@ -230,11 +230,11 @@ export default defineAction({
 });
 ```
 
-將其用於 actions，刪除或轉移帳戶/組織、更改驗證狀態、修改組織成員資格或授予共用存取權限。該框架的內置 `share-resource`、`unshare-resource` 和 `set-resource-visibility` 已被選取退出。通過 iframe 調用上不可欺騙的主機集標頭執行；常規 UI/agent/CLI/MCP/A2A 呼叫不受影響 - 詳情請參閱 [Security](/docs/security)。
+將其用於 actions，刪除或轉移帳戶/組織、更改驗證狀態、修改組織成員資格或授予共用存取權限。此框架的內建 `share-resource`、`unshare-resource` 和 `set-resource-visibility` 已被選取退出。透過 iframe 呼叫上不可欺騙的主機集標頭執行；一般 UI/agent/CLI/MCP/A2A 呼叫不受影響 - 詳情請參閱 [Security](/docs/security)。
 
-### 執行上下文（第二個參數） {#run-context}
+### 執行脈絡（第二個參數） {#run-context}
 
-`run` 接收可選的第二個參數 `ctx`，它攜帶解析的請求標識和調用操作的表面。讀取它而不是手動調用`getRequestUserEmail()` / `getRequestOrgId()`，並將整個`ctx`傳遞給跟蹤：
+`run` 接收可選的第二個參數 `ctx`，它攜帶解析的請求識別和呼叫操作的表面。讀取它而不是手動呼叫`getRequestUserEmail()` / `getRequestOrgId()`，並將整個`ctx`傳遞給跟蹤：
 
 ```ts
 export default defineAction({
@@ -259,30 +259,30 @@ export default defineAction({
 
 `ActionRunContext` 欄位：
 
-| 欄位          | 型別                    | 注釋                                                                                                                                                            |
+| 欄位          | 型別                    | 註解                                                                                                                                                            |
 | ------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `userEmail`   | `string \| undefined`   | Resolved request user. **Never defaulted to a dev identity** — `undefined` when the request has no authenticated user. Apply your own fallback if you need one. |
 | `orgId`       | `string \| null`        | Resolved org id, or `null` when the request has no org.                                                                                                         |
-| `caller`      | `ActionCaller`          | 如何調用操作（見下文）。                                                                                                                                        |
-| `send`        | `(event) => void`       | 可選。向用戶端發出 SSE 事件。僅存在於代理工具循環內部（`caller: "tool"`）； `undefined` 其他地方。                                                              |
-| `attachments` | `AgentChatAttachment[]` | 目前代理提交的檔案、圖片和貼上的文本塊。僅當`caller: "tool"`時才填充； `undefined` 在所有其他表面上。                                                           |
+| `caller`      | `ActionCaller`          | 如何呼叫操作（見下文）。                                                                                                                                        |
+| `send`        | `(event) => void`       | 可選。向用戶端發出 SSE 事件。僅存在於代理工具迴圈內部（`caller: "tool"`）； `undefined` 其他地方。                                                              |
+| `attachments` | `AgentChatAttachment[]` | 目前代理提交的檔案、圖片和貼上的文字塊。僅當`caller: "tool"`時才填充； `undefined` 在所有其他表面上。                                                           |
 
 `caller` 是並集 `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a"`：
 
 | `caller`     | 設定當...                                                                                                             |
 | ------------ | --------------------------------------------------------------------------------------------------------------------- |
-| `"tool"`     | 應用內代理循環、子代理/代理團隊或 A2A 請求（A2A 驅動相同的代理循環，因此其工具調用為 `"tool"`）。                     |
-| `"frontend"` | 通過 `useActionMutation` / `useActionQuery` / `callAction` 的瀏覽器調用（用 `X-Agent-Native-Frontend: 1` 標頭標記）。 |
-| `"http"`     | 沒有前端標記的裸編程 `POST` / `GET` 到 `/_agent-native/actions/<name>`。                                              |
+| `"tool"`     | 應用內代理迴圈、子代理/代理團隊或 A2A 請求（A2A 驅動相同的代理迴圈，因此其工具呼叫為 `"tool"`）。                     |
+| `"frontend"` | 透過 `useActionMutation` / `useActionQuery` / `callAction` 的瀏覽器呼叫（用 `X-Agent-Native-Frontend: 1` 標頭標記）。 |
+| `"http"`     | 沒有前端標記的裸程式化 `POST` / `GET` 到 `/_agent-native/actions/<name>`。                                            |
 | `"cli"`      | `pnpm action <name>`（CLI 跑步者）。                                                                                  |
 | `"mcp"`      | MCP `tools/call` 端點上的外部代理。                                                                                   |
-| `"a2a"`      | 保留用於將來的直接 A2A 操作調度。今天 A2A 執行在代理循環中，因此這些調用是 `"tool"`。                                 |
+| `"a2a"`      | 保留用於將來的直接 A2A 操作調度。今天 A2A 執行在代理迴圈中，因此這些呼叫是 `"tool"`。                                 |
 
-`run` 保持向後兼容：現有的 1 參數處理程序和僅解構 `{ send }` 的處理程序繼續保持不變。
+`run` 保持向後相容：現有的 1 參數處理常式和僅解構 `{ send }` 的處理常式繼續保持不變。
 
 ### actions中的存取控制 {#access-control}
 
-使用者擁有的表必須通過 `accessFilter` 進行讀取，並通過 `assertAccess` 進行寫入——框架的共用系統使用相同的幫助程序。這是一個完整的、可貼上的範例：
+使用者擁有的表必須透過 `accessFilter` 進行讀取，並透過 `assertAccess` 進行寫入——框架的共用系統使用相同的幫助程式。這是一個完整的、可貼上的範例：
 
 ```ts
 // actions/create-lead.ts
@@ -307,11 +307,11 @@ export default defineAction({
 });
 ```
 
-對於列出和讀取 actions，請使用 `accessFilter` 將查詢範圍限定為目前使用者和組織。對於更新或刪除特定行的 actions，在寫入之前使用 `assertAccess` 來確認調用者是否被允許。請參閱 [Security](/docs/security#access-guards) 和 [Sharing](/docs/sharing) 了解完整助手 API。
+對於列出和讀取 actions，請使用 `accessFilter` 將查詢範圍限定為目前使用者和組織。對於更新或刪除特定行的 actions，在寫入之前使用 `assertAccess` 來確認呼叫者是否被允許。請參閱 [Security](/docs/security#access-guards) 和 [Sharing](/docs/sharing) 了解完整助手 API。
 
-### 人機互動批準 {#needs-approval}
+### 人機互動核准 {#needs-approval}
 
-少數 actions 過於重要，無法讓代理自主執行 - 發送電子郵件、為卡充值、刪除帳戶。對於這些，設定 `needsApproval` 暫停循環並要求人員在 `run()` 執行之前批準特定調用：
+少數 actions 過於重要，無法讓代理自主執行 - 傳送電子郵件、為卡充值、刪除帳戶。對於這些，設定 `needsApproval` 暫停迴圈並要求人員在 `run()` 執行之前核准特定呼叫：
 
 ```ts
 export default defineAction({
@@ -324,14 +324,14 @@ export default defineAction({
 });
 ```
 
-`needsApproval` 還接受謂詞 `(args, ctx) => boolean | Promise<boolean>` 進行有條件的門控（例如，僅外部接收者，僅高於閾值）；它**無法關閉**，因此拋出算作“需要批準”。當門為真且未經批準時，循環會停止回合，並且副作用永遠不會觸發，直到有人在聊天 UI 中批準為止。
+`needsApproval` 還接受謂詞 `(args, ctx) => boolean | Promise<boolean>` 進行有條件的門控（例如，僅外部接收者，僅高於閾值）；它**無法關閉**，因此拋出算作“需要核准”。當門為真且未經核准時，迴圈會停止回合，並且副作用永遠不會觸發，直到有人在聊天 UI 中核准為止。
 
 > [!WARNING]
-> 保持很少的批準。每個門控操作都是代理循環中的硬停止。預設值為**關閉**，幾乎每個操作都應將其關閉。請參閱 [Human-in-the-Loop Approvals](/docs/human-approval) 了解謂詞 API、`approval_required` 事件和完整流程。
+> 保持很少的核准。每個門控操作都是代理迴圈中的硬停止。預設值為**關閉**，幾乎每個操作都應將其關閉。請參閱 [Human-in-the-Loop Approvals](/docs/human-approval) 了解謂詞 API、`approval_required` 事件和完整流程。
 
 ### 審核記錄紀錄 {#audit}
 
-每個變異操作都會被**自動審核**——框架會紀錄誰執行它、何時執行、從哪個表面執行、以及（當它是代理時）哪個線程/輪次，以及經過憑證編輯的輸入。唯讀 (`GET`) actions 被跳過。您無需為此編寫任何程式碼；它發生在 `defineAction` 接縫處。
+每個變異操作都會被**自動審核**——框架會紀錄誰執行它、何時執行、從哪個表面執行、以及（當它是代理時）哪個對話串/輪次，以及經過憑證編輯的輸入。唯讀 (`GET`) actions 被跳過。您無需為此編寫任何程式碼；它發生在 `defineAction` 接縫處。
 
 僅將 `audit` 塊新增到 _tune_ capture - 最有用的是聲明操作更改的資源，以便更改顯示在該資源所有者的跟蹤中：
 
@@ -349,9 +349,9 @@ export default defineAction({
 });
 ```
 
-其他旋鈕：`audit: { onRead: true }` 審核敏感讀取（秘密存取、批量匯出）； `audit: { enabled: false }` 選取噪聲寫入； `audit: { recordInputs: false }` 跳過捕獲參數。使用內置 `list-audit-events` / `get-audit-event` actions 讀取軌跡。詳細資訊請參見 [Audit Log](/docs/audit-log)。
+其他旋鈕：`audit: { onRead: true }` 審核敏感讀取（秘密存取、批量匯出）； `audit: { enabled: false }` 選取噪聲寫入； `audit: { recordInputs: false }` 跳過捕獲參數。使用內建 `list-audit-events` / `get-audit-event` actions 讀取軌跡。詳細資訊請參見 [Audit Log](/docs/audit-log)。
 
-## 從UI調用 {#ui}
+## 從 UI 呼叫 {#ui}
 
 兩個掛鉤，均位於 `@agent-native/core/client` 中。型別是從您的 `defineAction` 架構中推斷出來的 - 無需手動型別聲明。
 
@@ -372,7 +372,7 @@ const { mutate, isPending } = useActionMutation("reply-to-email");
 </Button>;
 ```
 
-成功後，框架會發出 `source: "action"` 的更改事件，以便 `useActionQuery` 使用者和活動查詢觀察者自動重新獲取。參見[Live Sync](/docs/key-concepts#polling-sync)。
+成功後，框架會發出 `source: "action"` 的更改事件，以便 `useActionQuery` 使用者和活動查詢觀察者自動重新取得。參見[Live Sync](/docs/key-concepts#polling-sync)。
 
 ### `useActionQuery` {#use-action-query}
 
@@ -386,11 +386,11 @@ const { data, isLoading } = useActionQuery("get-lead", { leadId });
 
 查詢快取在 `["action", "get-lead", { leadId }]` 下，並在完成任何變異操作後自動失效。
 
-## 渲染原生聊天UI {#native-chat-ui}
+## 渲染原生聊天 UI {#native-chat-ui}
 
-Actions 可以返回應用內聊天呈現的結構化小部件資料
+Actions 可以返回應用內聊天呈現的結構化小工具資料
 本機。這是可重用表格、圖表、設定的第一方聊天路徑
-摘要和見解卡；使用 [MCP Apps](/docs/mcp-apps) 進行內聯 UI
+摘要和見解卡；使用 [MCP Apps](/docs/mcp-apps) 進行行內 UI
 外部 MCP 主機。
 
 ```ts
@@ -432,34 +432,34 @@ export default defineAction({
 });
 ```
 
-內置判別式為 `"data-table"`、`"data-chart"` 和
+內建判別式為 `"data-table"`、`"data-chart"` 和
 `"data-insights"`，具有伺服器安全的建置器和架構
 `@agent-native/core/data-widgets`。見[Native 聊天介面](/docs/native-chat-ui)
-獲取完整結果合約和 BYO 執行時指南，或
+取得完整結果合約和 BYO 執行時指南，或
 [Agent Surfaces](/docs/agent-surfaces) 了解如何保持相同的操作
-無頭、在聊天中渲染或變成全屏。
+無頭、在聊天中渲染或變成全螢幕。
 
-## 從CLI調用 {#cli}
+## 從 CLI 呼叫 {#cli}
 
-每個操作都可以通過 `pnpm action` 執行：
+每個操作都可以透過 `pnpm action` 執行：
 
 ```bash
 pnpm action reply-to-email '{"emailId":"thread-123","body":"Thanks!"}'
 ```
 
-JSON 輸入是代理和複雜物件的首選形狀。標志是
+JSON 輸入是代理和複雜物件的首選形狀。標誌是
 仍然解析為相同的模式形狀，以進行簡單的手動執行和現有
-腳本。對於代理開發循環、腳本和 cron 很有用。
+指令碼。對於代理開發迴圈、指令碼和 cron 很有用。
 
-## 從另一個代理調用它（A2A） {#a2a}
+## 從另一個代理呼叫它（A2A） {#a2a}
 
-如果您的應用程式是 [A2A](/docs/a2a-protocol) 對等點，則其他代理本機應用程式會自動發現您的 actions 並可以通過名稱調用它們。同來源部署跳過JWT簽名；跨域使用共用的`A2A_SECRET`。
+如果您的應用程式是 [A2A](/docs/a2a-protocol) 對等點，則其他 Agent-Native 應用程式會自動發現您的 actions 並可以透過名稱呼叫它們。同來源部署跳過 JWT 簽名；跨域使用共用的`A2A_SECRET`。
 
-## 通過 MCP 公開它 {#mcp}
+## 透過 MCP 公開它 {#mcp}
 
-啟用 MCP 後，您的 actions 將顯示在框架的 MCP 伺服器中，位置為 `/_agent-native/mcp`。預設情況下，每個調用者都會獲得一個緊湊的目錄 - 面向應用程式的內置程序以及範本聲明的應用程式 actions - 並且 `tool-search` 始終存在，因此任何其他工具都可以按需存取。完整的操作介面僅在明確選取加入（`--full-catalog` 代幣或 `AGENT_NATIVE_MCP_FULL_CATALOG=1`）時提供，並且 `publicAgent.expose` 在公開介面上選取安全讀取/攝取工具。請參閱 [MCP Protocol](/docs/mcp-protocol) 了解目錄層、驗證和 `mcpApp` 資源詳細資訊。
+啟用 MCP 後，您的 actions 將顯示在框架的 MCP 伺服器中，位置為 `/_agent-native/mcp`。預設情況下，每個呼叫者都會獲得一個緊湊的目錄 - 面向應用程式的內建程式以及範本聲明的應用程式 actions - 並且 `tool-search` 始終存在，因此任何其他工具都可以按需存取。完整的操作介面僅在明確選取加入（`--full-catalog` 代幣或 `AGENT_NATIVE_MCP_FULL_CATALOG=1`）時提供，並且 `publicAgent.expose` 在公開介面上選取安全讀取/攝取工具。請參閱 [MCP Protocol](/docs/mcp-protocol) 了解目錄層、驗證和 `mcpApp` 資源詳細資訊。
 
-對於支持 UI 的 MCP 主機，操作可以通過 `mcpApp` 欄位（加上匹配的 `link`）聲明可選的 MCP Apps 資源，以便有能力的主機內聯渲染結果。當 `link` 和 `mcpApp` 應指向同一路線時，`embedRoute()` 從一個純路徑建置器建置兩者：
+對於支援 UI 的 MCP 主機，操作可以透過 `mcpApp` 欄位（加上匹配的 `link`）聲明可選的 MCP Apps 資源，以便有能力的主機行內渲染結果。當 `link` 和 `mcpApp` 應指向同一路由時，`embedRoute()` 從一個純路徑建置器建置兩者：
 
 ```ts
 import { embedRoute } from "@agent-native/core";
@@ -487,7 +487,7 @@ export default defineAction({
 
 ### 檢視螢幕 {#view-screen}
 
-讀取目前導覽狀態，獲取上下文資料，並返回使用者所看到內容的快照。當代理需要重新檢視螢幕時會調用此函數。
+讀取目前導覽狀態，取得脈絡資料，並返回使用者所看到內容的快照。當代理需要重新檢視螢幕時會呼叫此函式。
 
 ```ts
 // actions/view-screen.ts
@@ -537,7 +537,7 @@ export default defineAction({
 
 ## 舊版 CLI 樣式 actions {#legacy-cli-actions}
 
-該框架仍然支持未包含在 `defineAction` 中的較舊的 `export default async function(args)` actions - 對於不需要代理/HTTP 暴露的一次性開發腳本很有用。這些僅限 CLI；它們不會顯示為代理工具，不會掛載 HTTP 端點，也不會獲得型別安全的前端掛鉤。
+此框架仍然支援未包含在 `defineAction` 中的較舊的 `export default async function(args)` actions - 對於不需要代理/HTTP 暴露的一次性開發指令碼很有用。這些僅限 CLI；它們不會顯示為代理工具，不會掛載 HTTP 端點，也不會獲得型別安全的前端掛鉤。
 
 ```ts
 // actions/debug-dump.ts — CLI-only
@@ -553,7 +553,7 @@ export default async function main(args: string[]) {
 
 ### `parseArgs(args)` {#parseargs}
 
-舊式 actions 的幫助程序。解析 `--key value` 或 `--key=value` 格式的 CLI 參數：
+舊式 actions 的幫助程式。解析 `--key value` 或 `--key=value` 格式的 CLI 參數：
 
 ```ts
 import { parseArgs } from "@agent-native/core";
@@ -562,7 +562,7 @@ const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
 // { name: "Steve", verbose: "true", count: "3" }
 ```
 
-## 實用函數 {#utility-functions}
+## 實用函式 {#utility-functions}
 
 | 功能                    | 退貨      | 描述                                   |
 | ----------------------- | --------- | -------------------------------------- |
@@ -573,9 +573,9 @@ const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
 | `ensureDir(dir)`        | `void`    | `mkdir -p` 助手。                      |
 | `fail(message)`         | `never`   | 列印到stderr和`exit(1)`。              |
 
-## 下一步是什么
+## 下一步是什麼
 
-- [**Audit Log**](/docs/audit-log) — 每個操作的自動誰更改了什么跟蹤
+- [**Audit Log**](/docs/audit-log) — 每個操作的自動誰更改了什麼跟蹤
 - [**Human-in-the-Loop Approvals**](/docs/human-approval) — `needsApproval` 門的深度
 - [**Drop-in Agent**](/docs/drop-in-agent) — React 中的 `useActionMutation` / `useActionQuery`
 - [**Context Awareness**](/docs/context-awareness) — `view-screen` + `navigate` 模式的深度

package/corpus/core/docs/content/locales/zh-TW/agent-mentions.md

@@ -9,27 +9,27 @@ description: "使用@提及在聊天中標記自訂代理、連線的代理和
 
 ## 概述 {#overview}
 
-`@` 提及系統將聊天編輯器連線到更廣泛的代理生態系統。當您鍵入 `@` 時，會出現一個快顯窗口，列出可用的自訂代理、連線的代理、程式碼庫檔案和資源。
+`@` 提及系統將聊天編輯器連線到更廣泛的代理生態系統。當您鍵入 `@` 時，會出現一個快顯視窗，列出可用的自訂代理、連線的代理、程式碼庫檔案和資源。
 
-這是您通過單個聊天協調多代理工作流程的方式。要求您當地的 `@design` 代理評論布局，`@analytics` 從另一個應用程式中提取最新資料，主要代理可以將兩者合並到一個對話中。
+這是您透過單一聊天協調多代理工作流程的方式。要求您本機的 `@design` 代理評論布局，`@analytics` 從另一個應用程式中擷取最新資料，主要代理可以將兩者合併到一個對話中。
 
 ## 提及代理 {#mentioning-agents}
 
 要在聊天編輯器中提及代理：
 
-1. 輸入 `@` 開啟提及快顯窗口
-2. 瀏覽或搜尋可用代理列表
+1. 輸入 `@` 開啟提及快顯視窗
+2. 瀏覽或搜尋可用代理清單
 3. 選取一個代理 - 它在您的訊息中顯示為標籤
-4. 發送訊息 - 伺服器解析提及並將該代理的回應包含在對話上下文中
+4. 傳送訊息 - 伺服器解析提及並將該代理的回應包含在對話脈絡中
 
 有兩條代理路徑：
 
 - **自訂代理** — `agents/*.md` 中的本機工作區代理設定檔案。它們使用代理設定檔案的指令和可選模型覆蓋在目前應用程式/執行時內執行。
-- **連線的代理** — 遠端 A2A 對等點。這些是通過 [A2A protocol](/docs/a2a-protocol) 調用的。
+- **連線的代理** — 遠端 A2A 對等點。這些是透過 [A2A protocol](/docs/a2a-protocol) 呼叫的。
 
 在這兩種情況下，您的主要代理都會看到回應並可以引用或建置它。
 
-```an-diagram title="@提及路由的位置" summary="伺服器按型別拆分每個提及：自訂代理在本機執行，連線的代理通過 A2A - 兩個回應都折疊回主代理的上下文中。"
+```an-diagram title="@提及路由的位置" summary="伺服器按型別拆分每個提及：自訂代理在本機執行，連線的代理透過 A2A - 兩個回應都折疊回主代理的脈絡中。"
 {
   "html": "<div class=\"diagram-mention\"><div class=\"diagram-node\">@-mention<br><small class=\"diagram-muted\">in the composer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">伺服器解析</span><small class=\"diagram-muted\">extract refs by type</small></div><div class=\"diagram-col\"><div class=\"row\"><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\">自訂代理<br><small class=\"diagram-muted\">agents/*.md &middot; runs local</small></div></div><div class=\"row\"><span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</span><div class=\"diagram-box\">已連線代理<br><small class=\"diagram-muted\">A2A peer &middot; remote call</small></div></div></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box diagram-accent\">&lt;agent-response&gt;<br><small class=\"diagram-muted\">injected into main agent</small></div></div>",
   "css": ".diagram-mention{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-mention .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-mention .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-mention .row{display:flex;align-items:center;gap:8px}.diagram-mention .diagram-arrow{font-size:22px;line-height:1}"
@@ -38,16 +38,16 @@ description: "使用@提及在聊天中標記自訂代理、連線的代理和
 
 ## 它是如何工作的 {#how-it-works}
 
-當發送包含 `@` 提及的訊息時，伺服器上會發生以下情況：
+當傳送包含 `@` 提及的訊息時，伺服器上會發生以下情況：
 
-1. 伺服器從訊息中提取提及引用
+1. 伺服器從訊息中擷取提及引用
 2. 對於每個提到的代理：
    - 自訂代理按照其設定檔案說明在本機執行
-   - 通過 A2A 調用連線的代理
-3. 代理的回應被包裝在 `<agent-response>` XML 塊中並注入到對話上下文中
-4. 主代理處理丰富的訊息，檢視使用者的文本和提到的代理的回應
+   - 透過 A2A 呼叫連線的代理
+3. 代理的回應被包裝在 `<agent-response>` XML 塊中並注入到對話脈絡中
+4. 主代理處理豐富的訊息，檢視使用者的文字和提到的代理的回應
 
-主代理在其上下文中看到的內容：
+主代理在其脈絡中看到的內容：
 
 ```text
 User: Draft an email with the latest signup numbers. @analytics
@@ -60,7 +60,7 @@ Last week's signups: 1,247 total
 </agent-response>
 ```
 
-然後，主代理可以在其回應中自然地使用這些資料 - 例如，將這些數字合並到電子郵件草稿中。
+然後，主代理可以在其回應中自然地使用這些資料 - 例如，將這些數字合併到電子郵件草稿中。
 
 ```an-callout
 {
@@ -71,15 +71,15 @@ Last week's signups: 1,247 total
 
 ## 新增代理 {#adding-agents}
 
-可以通過多種機制提及代理：
+可以透過多種機制提及代理：
 
 - **自訂工作區代理** — 在“工作區”分頁中建立代理設定檔案為 `agents/*.md`
-- **自動發現** - 框架自動發現在已知端口或設定的 URL 上執行的連線代理
+- **自動發現** - 框架自動發現在已知連接埠或設定的 URL 上執行的連線代理
 - **遠端清單** — 新增連線代理清單為 `remote-agents/*.json`
 
 ### 自訂工作區代理
 
-自訂代理是存儲在工作區中的 Markdown 檔案：
+自訂代理是儲存在工作區中的 Markdown 檔案：
 
 ```markdown
 ---
@@ -117,7 +117,7 @@ You are a focused design agent.
 
 ## 對於開發者：擴充功能提及 {#extending-mentions}
 
-範本可以註冊自訂提及提供程序，以新增代理和檔案之外的特定於域的可提及專案。提及提供者實現了 `MentionProvider` 介面：
+範本可以註冊自訂提及提供者，以新增代理和檔案之外的特定於域的可提及專案。提及提供者實現了 `MentionProvider` 介面：
 
 ```an-annotated-code title="自訂 MentionProvider"
 {
@@ -145,17 +145,17 @@ export default createAgentChatPlugin({
 });
 ```
 
-自訂提及提供程序與內置代理和檔案提供程序一起顯示在提及快顯窗口中。
+自訂提及提供者與內建代理和檔案提供者一起顯示在提及快顯視窗中。
 
 ## 引用檔案 {#referencing-files}
 
-`@` 快顯窗口不僅限於代理。您還可以參考：
+`@` 快顯視窗不僅限於代理。您還可以參考：
 
-- **程式碼庫檔案** — 輸入 `@` 並搜尋檔案名。檔案內容包含在代理的上下文中，因此它可以讀取、分析或修改檔案。
+- **程式碼庫檔案** — 輸入 `@` 並搜尋檔名。檔案內容包含在代理的脈絡中，因此它可以讀取、分析或修改檔案。
 - **工作空間資源** — 在“工作空間”分頁中定義的參考檔案。這些可以是資料檔案、設定或任何其他結構化內容。
 - **Skills** — 輸入 `/` 來引用技能。 Skills 提供結構化指令來指導代理如何處理工作。
 
-所有引用型別都遵循相同的模式：從快顯窗口中進行選取，發送訊息時引用的內容將被解析並注入到代理的上下文中。
+所有引用型別都遵循相同的模式：從快顯視窗中進行選取，傳送訊息時引用的內容將被解析並注入到代理的脈絡中。
 
 ## 子代理選取 {#sub-agent-selection}