@agent-native/core 0.79.12 → 0.79.16

package/docs/content/locales/zh-TW/embedding-sdk.md

@@ -1,19 +1,19 @@
 ---
-title: "嵌入SDK"
-description: "使用頁面上下文和主機指令將 Agent-Native sidecar 嵌入到現有 SaaS 應用中。"
+title: "嵌入 SDK"
+description: "使用頁面脈絡和主機指令將 Agent-Native sidecar 嵌入到現有 SaaS 應用中。"
 ---
 
-# 嵌入SDK
+# 嵌入 SDK
 
 將 Agent-Native 嵌入現有產品：保留您的 SaaS 應用程式，新增耐用的
 代理sidecar，讓該代理檢視使用者所在頁面並進行操作
-已在使用。如果您仍在無頭代理、丰富聊天和
+已在使用。如果您仍在無頭代理、豐富聊天和
 嵌入式邊車，或完整的應用程式，從
 [Agent Surfaces](/docs/agent-surfaces).
 
-```an-diagram title="包埋膜" summary="主機應用程式提供伺服器端驗證和實時頁面上下文； Agent-Native 執行持久 sidecar 並通過用戶端操作和主機指令到達開啟的分頁。"
+```an-diagram title="包埋膜" summary="主機應用程式提供伺服器端驗證和即時頁面脈絡； Agent-Native 執行持久 sidecar 並透過用戶端操作和主機指令到達開啟的分頁。"
 {
-  "html": "<div class=\"diagram-embed\"><div class=\"diagram-box\" data-rough><strong>宿主 SaaS 應用</strong><small class=\"diagram-muted\">你的介面，你的認證</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">getContext &rarr;</div><div class=\"diagram-pill\">&larr; 用戶端操作</div><div class=\"diagram-pill\">&larr; 宿主指令</div></div><div class=\"diagram-panel center\" data-rough><strong>Agent-Native sidecar</strong><small class=\"diagram-muted\">持久聊天 · 應用狀態 · 擴充功能</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL<br><small class=\"diagram-muted\">框架表</small></div></div>",
+  "html": "<div class=\"diagram-embed\"><div class=\"diagram-box\" data-rough><strong>主機 SaaS 應用</strong><small class=\"diagram-muted\">你的介面，你的認證</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">getContext &rarr;</div><div class=\"diagram-pill\">&larr; 用戶端操作</div><div class=\"diagram-pill\">&larr; 主機指令</div></div><div class=\"diagram-panel center\" data-rough><strong>Agent-Native sidecar</strong><small class=\"diagram-muted\">持久聊天 · 應用狀態 · 擴充功能</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL<br><small class=\"diagram-muted\">框架表</small></div></div>",
   "css": ".diagram-embed{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-embed .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-embed .diagram-arrow{font-size:22px;line-height:1}.diagram-embed .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
 }
 ```
@@ -23,15 +23,15 @@ description: "使用頁面上下文和主機指令將 Agent-Native sidecar 嵌
 對於大多數 SaaS 主機，**使用完整的嵌入式執行時** - 伺服器外掛
 `createAgentNativeEmbeddedPlugin` 加上 `<AgentNativeEmbedded>` 用戶端
 元件。這是推薦的預設值：它重用整個框架
-（actions、SQL 支持的應用程式狀態、擴充功能、瀏覽器工作階段工具）並給出
+（actions、SQL 支援的應用程式狀態、擴充功能、瀏覽器工作階段工具）並給出
 代理檢視使用者正在使用的頁面並進行操作的能力。
 
 主機將 Agent-Native 伺服器路由掛載到其現有應用程式中，傳遞其
-使用者登入Agent-Native，並在產品UI中渲染React側邊欄。
+使用者登入 Agent-Native，並在產品 UI 中渲染 React 側邊欄。
 Agent-Native 使用主機部署、主機工作階段和設定
-`DATABASE_URL` 管理自己的框架表：聊天線程、設定，
+`DATABASE_URL` 管理自己的框架表：聊天對話串、設定，
 應用程式狀態、擴充功能、擴充功能資料、機密、瀏覽器工作階段和
-行動路線。
+行動路由。
 
 ```bash
 pnpm add @agent-native/core
@@ -121,13 +121,13 @@ export function BuilderAppShell({ children, content, editor }) {
 }
 ```
 
-此模式是建議的預設模式，因為它重用了完整的框架：後端 actions 安裝在 `/_agent-native/actions` 下，代理可以調用與 UI 相同的 actions，使用者建立的擴充功能存儲在 SQL 中，`extensionData` 是持久的且具有使用者/組織範圍，瀏覽器工作階段工具允許後端代理檢查或操作目前開啟的分頁。
+此模式是建議的預設模式，因為它重用了完整的框架：後端 actions 安裝在 `/_agent-native/actions` 下，代理可以呼叫與 UI 相同的 actions，使用者建立的擴充功能儲存在 SQL 中，`extensionData` 是持久的且具有使用者/組織範圍，瀏覽器工作階段工具允許後端代理檢查或操作目前開啟的分頁。
 
 主機驗證是伺服器端的。不要將瀏覽器的身分作為事實來源傳遞；使用主機的請求/工作階段物件或短期伺服器驗證的權杖。如果主機不公開電子郵件，則返回穩定的 `userId`，Agent-Native 將使用它作為所有者金鑰。
 
 ### 資料庫隔離
 
-嵌入模式管理SQL中的Agent-Native表。對於成熟的 SaaS 產品，最安全的預設設定是**相同的託管和驗證、專用的 Agent-Native 資料庫/架構**：
+嵌入模式管理 SQL 中的 Agent-Native 表。對於成熟的 SaaS 產品，最安全的預設設定是**相同的託管和驗證、專用的 Agent-Native 資料庫/架構**：
 
 ```ts
 export default createAgentNativeEmbeddedPlugin({
@@ -137,22 +137,22 @@ export default createAgentNativeEmbeddedPlugin({
 });
 ```
 
-支持使用主機產品的主要 `DATABASE_URL`，但請明確選取。 Agent-Native 建立 `settings`、`application_state`、`tools`、`tool_data` 等框架表、瀏覽器工作階段表、秘密、聊天線程和相關索引。專用的資料庫/模式可以避免表名衝突，保持託管表的所有權清晰，並使備份/保留策略更容易推理。如果您有意共用主機資料庫，請首先檢查現有表名稱，並將 Agent-Native 表視為框架擁有的表。
+支援使用主機產品的主要 `DATABASE_URL`，但請明確選取。 Agent-Native 建立 `settings`、`application_state`、`tools`、`tool_data` 等框架表、瀏覽器工作階段表、秘密、聊天對話串和相關索引。專用的資料庫/模式可以避免表名衝突，保持託管表的所有權清晰，並使備份/保留策略更容易推理。如果您有意共用主機資料庫，請首先檢查現有表名稱，並將 Agent-Native 表視為框架擁有的表。
 
 ## 其他模式 {#other-modes}
 
 上面的包含電池的外掛是幸福的道路。伸手去拿其中之一
 只有當它更適合您的情況時：
 
-| 模式                     | 什么時候使用它                                                                        | 包                                      |
+| 模式                     | 什麼時候使用它                                                                        | 包                                      |
 | ------------------------ | ------------------------------------------------------------------------------------- | --------------------------------------- |
-| **嵌入式應用程式選取器** | 啟動完整的 Agent-Native 應用程式作為重點 iframe（資產選取器、表單生成器、審批面板）。 | `@agent-native/embedding`               |
-| **`<AgentNative>` 主橋** | 手動連線頁面上下文和用戶端 actions 的獨立 sidecar 應用或跨來源 iframe。               | `@agent-native/core/client`             |
-| **便攜式擴充功能**       | 當 SaaS 已擁有擴充功能存儲/批準時，讓主機使用者建置沙盒迷你應用程式。                 | `@agent-native/core/client`擴充功能插槽 |
+| **嵌入式應用程式選取器** | 啟動完整的 Agent-Native 應用程式作為重點 iframe（資產選取器、表單生成器、核准面板）。 | `@agent-native/embedding`               |
+| **`<AgentNative>` 主橋** | 手動連線頁面脈絡和用戶端 actions 的獨立 sidecar 應用或跨來源 iframe。                 | `@agent-native/core/client`             |
+| **便攜式擴充功能**       | 當 SaaS 已擁有擴充功能儲存/核准時，讓主機使用者建置沙盒迷你應用程式。                 | `@agent-native/core/client`擴充功能插槽 |
 
-較低級別的 `@agent-native/embedding` 包公開：
+較低階別的 `@agent-native/embedding` 包公開：
 
-| 匯入路徑                           | 它提供什么                                                                        |
+| 匯入路徑                           | 它提供什麼                                                                        |
 | ---------------------------------- | --------------------------------------------------------------------------------- |
 | `@agent-native/embedding`          | `EmbeddedApp` 選取器元件、`getA2AUrl`、`getMcpUrl`、`sendMessage`（流式傳輸 A2A） |
 | `@agent-native/embedding/react`    | React 特定的鉤子和元件                                                            |
@@ -168,9 +168,9 @@ pnpm add @agent-native/embedding
 
 當主機產品想要推出完整的產品時，請使用`@agent-native/embedding`
 Agent-Native 應用程式作為聚焦的 iframe 表面：資產選取器、資產生成器，
-表單建置器、行事曆時段選取器、審批面板或任何其他特定於工作的
+表單建置器、行事曆時段選取器、核准面板或任何其他特定於工作的
 工作流程。這是故意小於下面的 sidecar 主橋：
-iframe 宣布準備就緒，主機可以發送命名訊息，並且嵌入
+iframe 宣布準備就緒，主機可以傳送命名訊息，並且嵌入
 應用程式可以發出域事件，例如 `chooseAsset` 或 `close`。
 
 ```tsx
@@ -200,7 +200,7 @@ export function AssetPickerDialog({ close }) {
 }
 ```
 
-在嵌入式應用程式內，使用瀏覽器橋宣布準備就緒並發送
+在嵌入式應用程式內，使用瀏覽器橋宣布準備就緒並傳送
 事件返回主機：
 
 ```ts
@@ -217,8 +217,8 @@ sendEmbeddedAppMessage("chooseAsset", {
 });
 ```
 
-資產還發出 `chooseImage` 作為舊圖片選取器的兼容性別名
-主機；新的整合應該偵听 `chooseAsset`。
+資產還發出 `chooseImage` 作為舊圖片選取器的相容性別名
+主機；新的整合應該偵聽 `chooseAsset`。
 
 對於託管的第一方應用，啟用跨應用 SSO，並以 Dispatch 作為身分
 集線器，使 `content.agent-native.com` 和 `assets.agent-native.com` 連結使用者
@@ -226,8 +226,8 @@ sendEmbeddedAppMessage("chooseAsset", {
 在需要第三方 cookie 彈性時嵌入工作階段；普通應用程式cookie
 本身並不是一個完整的嵌入驗證故事。
 
-同一包包括用於協議發現的代理端點幫助程序和
-通過 A2A 流式傳輸文本：
+同一包包括用於協議發現的代理端點幫助程式和
+透過 A2A 流式傳輸文字：
 
 ```ts
 import { getA2AUrl, getMcpUrl, sendMessage } from "@agent-native/embedding";
@@ -245,11 +245,11 @@ for await (const chunk of sendMessage(
 
 ### 主機應用程式（`<AgentNative>`主機橋）
 
-> 首選上面包含電池的外掛。使用這個較低級別的橋
+> 首選上面包含電池的外掛。使用這個較低階別的橋
 > 僅適用於您連線頁面的獨立 sidecar 應用程式或跨來源 iframe
-> 上下文和用戶端 actions 自己。
+> 脈絡和用戶端 actions 自己。
 
-對於獨立的 sidecar 應用程式或跨來源 iframe，請使用較低級別的 `<AgentNative />`。它將 iframe sidecar 和連線頁面上下文、實時用戶端 actions 以及主機刷新/導覽指令呈現在一個位置：
+對於獨立的 sidecar 應用程式或跨來源 iframe，請使用較低階別的 `<AgentNative />`。它將 iframe sidecar 和連線頁面脈絡、即時用戶端 actions 以及主機重新整理/導覽指令呈現在一個位置：
 
 ```tsx
 import { AgentNative, defineClientAction } from "@agent-native/core/client";
@@ -324,13 +324,13 @@ export function AssistantDock({ customer, sessionToken }) {
 }
 ```
 
-如果您只需要顯式語義上下文，請使用 `screen={false}`。使用 `screen={{ includeDomHtml: true }}` 作為尚未將 UI 對應到語義 ID 和選取狀態的應用程式的後備。預設情況下，主橋僅接受來自 `agentUrl` 來源的訊息。如果 iframe URL 是可信來源不同的路由/代理 URL，則傳遞 `agentOrigin`。
+如果您只需要顯式語義脈絡，請使用 `screen={false}`。使用 `screen={{ includeDomHtml: true }}` 作為尚未將 UI 對應到語義 ID 和選取狀態的應用程式的後備。預設情況下，主橋僅接受來自 `agentUrl` 來源的訊息。如果 iframe URL 是可信來源不同的路由/代理 URL，則傳遞 `agentOrigin`。
 
-對於非 React 主機，直接調用 `createAgentNativeHostBridge()` 並傳遞相同的 `getContext`、`actions` 和 `commands` 選項。
+對於非 React 主機，直接呼叫 `createAgentNativeHostBridge()` 並傳遞相同的 `getContext`、`actions` 和 `commands` 選項。
 
 ### Iframe 側
 
-在 Agent-Native sidecar 內，使用框架助手請求主機上下文，發現實時瀏覽器工作階段 actions，執行它們，或要求主機執行 UI 工作。在正式環境中始終通過預期的 `hostOrigin`：
+在 Agent-Native sidecar 內，使用框架助手請求主機脈絡，發現即時瀏覽器工作階段 actions，執行它們，或要求主機執行 UI 工作。在正式環境中始終透過預期的 `hostOrigin`：
 
 ```ts
 import {
@@ -371,9 +371,9 @@ const hostTools = createAgentNativeHostTools({
 
 ### 伺服器中介工具橋
 
-對於 CLAW 風格的同事，iframe 還可以向 sidecar 後端註冊其實時瀏覽器分頁。然後，代理獲取正常的後端工具，將請求排入佇列，iframe 聲明它，主機頁面執行它，後端將結果返回給代理。
+對於 CLAW 風格的同事，iframe 還可以向 sidecar 後端註冊其即時瀏覽器分頁。然後，代理取得正常的後端工具，將請求排入佇列，iframe 聲明它，主機頁面執行它，後端將結果返回給代理。
 
-```an-diagram title="伺服器介導的瀏覽器工作階段橋" summary="後端工具將工作排隊；註冊的分頁聲明它，在實時頁面上執行它，並將結果返回給代理 - 因此 backend/Slack/A2A 代理仍然可以觸摸開啟的分頁。"
+```an-diagram title="伺服器介導的瀏覽器工作階段橋" summary="後端工具將工作排隊；註冊的分頁聲明它，在即時頁面上執行它，並將結果返回給代理 - 因此 backend/Slack/A2A 代理仍然可以觸摸開啟的分頁。"
 {
   "html": "<div class=\"diagram-bridge\"><div class=\"diagram-node\" data-rough>後端代理<br><small class=\"diagram-muted\">聊天 · Slack · A2A</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>enqueue request<br><small class=\"diagram-muted\">/_agent-native/browser-sessions</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>活動標籤頁面接管它<br><small class=\"diagram-muted\">registered bridge</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">result &rarr; agent</div></div>",
   "css": ".diagram-bridge{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bridge .diagram-arrow{font-size:22px;line-height:1}"
@@ -401,15 +401,15 @@ export function SidecarRuntime() {
 
 框架自動掛載`/_agent-native/browser-sessions`。一旦網橋執行，sidecar 代理就可以使用：
 
-| 工具                           | 目的                                           |
-| ------------------------------ | ---------------------------------------------- |
-| `list-browser-sessions`        | 檢視目前使用者的已連線主機分頁。               |
-| `view-browser-session`         | 向實時分頁詢問目前頁面上下文和螢幕快照。       |
-| `list-browser-session-actions` | 向實時分頁詢問目前用戶端操作清單。             |
-| `run-browser-session-action`   | 通過實時分頁執行一項目前用戶端操作。           |
-| `send-browser-session-command` | 請求主機刷新、導覽、重新安裝、重新載入或批準。 |
+| 工具                           | 目的                                               |
+| ------------------------------ | -------------------------------------------------- |
+| `list-browser-sessions`        | 檢視目前使用者的已連線主機分頁。                   |
+| `view-browser-session`         | 向即時分頁詢問目前頁面脈絡和螢幕截圖。             |
+| `list-browser-session-actions` | 向即時分頁詢問目前用戶端操作清單。                 |
+| `run-browser-session-action`   | 透過即時分頁執行一項目前用戶端操作。               |
+| `send-browser-session-command` | 請求主機重新整理、導覽、重新安裝、重新載入或核准。 |
 
-這是當代理在後端、Slack/Telegram/email 中執行或作為 A2A 被調用者執行時使用的橋，但在開啟時仍需要觸摸使用者目前的瀏覽器分頁。如果瀏覽器關閉，後端 actions 仍應處理持久工作，並且瀏覽器工作階段工具將報告沒有連線活動分頁。
+這是當代理在後端、Slack/Telegram/email 中執行或作為 A2A 被呼叫者執行時使用的橋，但在開啟時仍需要觸摸使用者目前的瀏覽器分頁。如果瀏覽器關閉，後端 actions 仍應處理持久工作，並且瀏覽器工作階段工具將報告沒有連線活動分頁。
 
 ### Actions
 
@@ -417,20 +417,20 @@ export function SidecarRuntime() {
 
 | 動作型別   | 執行位置                                              | 瀏覽器關閉時可以工作嗎？ | 最適合                                                                           |
 | ---------- | ----------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------- |
-| 後端操作   | Sidecar 應用、後端 API、MCP 或整合適配器              | 是                       | 持久的工作，例如建立、更新、發布、同步、發送、匯入。                             |
-| 用戶端操作 | 通過 `<AgentNative actions={...} />` 的目前瀏覽器分頁 | 否                       | 臨時 UI 的工作方式類似於選取元素、讀取編輯器狀態、滾動到一行、複製目前畫布狀態。 |
+| 後端操作   | Sidecar 應用、後端 API、MCP 或整合轉接器              | 是                       | 持久的工作，例如建立、更新、發布、同步、傳送、匯入。                             |
+| 用戶端操作 | 透過 `<AgentNative actions={...} />` 的目前瀏覽器分頁 | 否                       | 臨時 UI 的工作方式類似於選取元素、讀取編輯器狀態、滾動到一行、複製目前畫布狀態。 |
 
-後端 actions 應該是任何必須在刷新、關閉瀏覽器、重試或整合觸發執行後仍然存在的預設設定。它們屬於 sidecar 應用程式的正常 Agent-Native 操作/工具層，代理可以在其中通過聊天、自動化、Slack/Telegram/電子郵件整合和後台作業調用它們。
+後端 actions 應該是任何必須在重新整理、關閉瀏覽器、重試或整合觸發執行後仍然存在的預設設定。它們屬於 sidecar 應用程式的正常 Agent-Native 操作/工具層，代理可以在其中透過聊天、自動化、Slack/Telegram/電子郵件整合和背景作業呼叫它們。
 
-用戶端 actions 是一個瀏覽器分頁的實時橋梁。主機使用 `source: "client"` 和 `availability: "browser-session"` 來通告它們，並且 sidecar 應該將該清單視為臨時的。當路線或選取發生變化時重新列出 actions，並在分頁消失時回退到後端 actions。
+用戶端 actions 是一個瀏覽器分頁的即時橋梁。主機使用 `source: "client"` 和 `availability: "browser-session"` 來通告它們，並且 sidecar 應該將該清單視為臨時的。當路由或選取發生變化時重新列出 actions，並在分頁消失時回退到後端 actions。
 
 ### 便攜式擴充功能
 
 > 當您希望 Agent-Native 進行管理時，首選包含電池的外掛
-> 擴充功能定義、批準、存儲和代理建立的擴充功能。使用
+> 擴充功能定義、核准、儲存和代理建立的擴充功能。使用
 > 僅當 SaaS 已經擁有這些問題時才使用下面的可移植插槽。
 
-SDK 還支持使用者定義的擴充功能：主機 SaaS 可以在命名槽中呈現的沙盒 Alpine.js 迷你應用程式。當客戶想要針對代理使用的相同操作/上下文介面建置自己的小面板、計算器、儀表板或工作流程助手時，請使用此選項。
+SDK 還支援使用者定義的擴充功能：主機 SaaS 可以在命名槽中呈現的沙盒 Alpine.js 迷你應用程式。當客戶想要針對代理使用的相同操作/脈絡介面建置自己的小面板、計算器、儀表板或工作流程助手時，請使用此選項。
 
 ```tsx
 import {
@@ -506,7 +506,7 @@ export function CustomerSidebar({ customer, userExtensions }) {
 }
 ```
 
-清單是安裝合同。當存在 `requestedActions`、`requestedCommands` 或 `storageScopes` 時，SDK 在 iframe 請求到達操作橋或存儲適配器之前在主機中強制執行它們。當 `slots` 存在時，`AgentNativeExtensionSlot` 僅在匹配插槽中渲染擴充功能。主機仍然可以使用 `allowedActions`、`allowedCommands` 和 `allowedStorageScopes` 覆蓋每個插槽的策略。
+清單是安裝合同。當存在 `requestedActions`、`requestedCommands` 或 `storageScopes` 時，SDK 在 iframe 請求到達操作橋或儲存轉接器之前在主機中強制執行它們。當 `slots` 存在時，`AgentNativeExtensionSlot` 僅在匹配插槽中渲染擴充功能。主機仍然可以使用 `allowedActions`、`allowedCommands` 和 `allowedStorageScopes` 覆蓋每個插槽的策略。
 
 擴充功能名是普通的 HTML。 iframe 執行時為迷你應用程式提供相同的安全橋原語：
 
@@ -531,51 +531,51 @@ iframe 內的可用全域變數：
 | ------------------------------ | ------------------------------------------ |
 | `appAction(name, args)`        | 執行主機聲明的操作。                       |
 | `agentNative.context()`        | 讀取目前主機頁面、資源、插槽和使用者資料。 |
-| `agentNative.command(name, p)` | 要求主機導覽、刷新、重新安裝或開啟。       |
+| `agentNative.command(name, p)` | 要求主機導覽、重新整理、重新安裝或開啟。   |
 | `agentNative.refresh(payload)` | `refreshData` 的快捷方式。                 |
-| `extensionData.*`              | 通過主機適配器保留擴充功能本機資料。       |
+| `extensionData.*`              | 透過主機轉接器保留擴充功能本機資料。       |
 
-預設情況下，`extensionData` 使用瀏覽器 `localStorage`，這對於原型和本機小部件很有用。正式環境 SaaS 主機應傳遞後端支持的 `storage` 適配器，以便使用者和組織範圍的擴充功能資料持久、可審核並受應用程式權限管理。通用 HTTP 適配器發送 POST 主體（如 `{ operation, extensionId, slotId, collection, id, data, options, context }`），並直接期望 `{ result }` 或結果 JSON。
+預設情況下，`extensionData` 使用瀏覽器 `localStorage`，這對於原型和本機小工具很有用。正式環境 SaaS 主機應傳遞後端支援的 `storage` 轉接器，以便使用者和組織範圍的擴充功能資料持久、可審核並受應用程式權限管理。通用 HTTP 轉接器傳送 POST 主體（如 `{ operation, extensionId, slotId, collection, id, data, options, context }`），並直接期望 `{ result }` 或結果 JSON。
 
-這個可移植的 SDK 層與框架的內置 SQL 支持的擴充功能存儲是分開的。在 Agent-Native 應用程式中，使用現有的 `ExtensionSlot`/`EmbeddedExtension` 元件和 `create-extension` 操作。在託管 SaaS 嵌入場景中，當您希望 Agent-Native 開箱即用地管理擴充功能定義、審批、存儲和代理建立的擴充功能時，首選 `createAgentNativeEmbeddedPlugin()` 加上 `AgentNativeEmbedded`。僅當 SaaS 已擁有擴充功能定義、批準、市場、存儲和計費時才使用 `AgentNativeExtensionSlot`。
+這個可移植的 SDK 層與框架的內建 SQL 支援的擴充功能儲存是分開的。在 Agent-Native 應用程式中，使用現有的 `ExtensionSlot`/`EmbeddedExtension` 元件和 `create-extension` 操作。在託管 SaaS 嵌入場景中，當您希望 Agent-Native 開箱即用地管理擴充功能定義、核准、儲存和代理建立的擴充功能時，首選 `createAgentNativeEmbeddedPlugin()` 加上 `AgentNativeEmbedded`。僅當 SaaS 已擁有擴充功能定義、核准、市場、儲存和計費時才使用 `AgentNativeExtensionSlot`。
 
 安全模型：
 
 - 擴充功能 iframe 是沙盒的，沒有 `allow-same-origin`；小應用程式無法直接讀取父DOM、cookies或應用程式執行時。
-- 擴充功能只能調用主機和擴充功能清單允許的 actions 和指令。
-- 有風險的 actions 應設定 `destructive` 或 `requiresApproval`，以便主機可以顯示審批流程。
-- 將使用者建立的擴充功能 HTML 視為不受信任。按使用者/組織檢視市場安裝、紀錄操作使用情況和範圍後端存儲。
+- 擴充功能只能呼叫主機和擴充功能清單允許的 actions 和指令。
+- 有風險的 actions 應設定 `destructive` 或 `requiresApproval`，以便主機可以顯示核准流程。
+- 將使用者建立的擴充功能 HTML 視為不受信任。按使用者/組織檢視市場安裝、紀錄操作使用情況和範圍後端儲存。
 
 ### 工作階段和分頁
 
-主機橋的作用域為一對 iframe/主機窗口。如果同一使用者開啟多個分頁，則每個分頁都有自己的 `session`、上下文、選取、用戶端 actions 和暫停的指令回應。不要假設在一個分頁中發現的用戶端操作可以在另一分頁中執行，或者它在導覽後仍然存在。
+主機橋的作用域為一對 iframe/主機視窗。如果同一使用者開啟多個分頁，則每個分頁都有自己的 `session`、脈絡、選取、用戶端 actions 和暫停的指令回應。不要假設在一個分頁中發現的用戶端操作可以在另一分頁中執行，或者它在導覽後仍然存在。
 
-對於多分頁產品，在 SQL/後端 actions 中保持持久狀態，並僅將用戶端 actions 用於分頁本機部分：聚焦行、複製可見編輯器狀態、選取畫布元素或刷新目前 React 查詢快取。包含足夠的 `route`、`resource` 和 `selection` 上下文，以便 sidecar 決定目前分頁是否是執行瀏覽器工作階段操作的正確位置。
+對於多分頁產品，在 SQL/後端 actions 中保持持久狀態，並僅將用戶端 actions 用於分頁本機部分：聚焦行、複製可見編輯器狀態、選取畫布元素或重新整理目前 React 查詢快取。包含足夠的 `route`、`resource` 和 `selection` 脈絡，以便 sidecar 決定目前分頁是否是執行瀏覽器工作階段操作的正確位置。
 
 ### 指令模型
 
-內置指令名稱故意采用應用程式形式，而不是資料庫形式：
+內建指令名稱故意采用應用程式形式，而不是資料庫形式：
 
 | 指令                                   | 目的                                            |
 | -------------------------------------- | ----------------------------------------------- |
-| `navigate`                             | 將主機 UI 行動到路徑/視圖/資源。                |
+| `navigate`                             | 將主機 UI 行動到路徑/檢視/資源。                |
 | `refreshData` / `refresh-data`         | 要求主機使用戶端資料無效。                      |
 | `remountView` / `remount-view`         | 要求主機重新掛載子樹，例如`<App key={key} />`。 |
 | `hardReload` / `hard-reload`           | 完全重新載入瀏覽器。                            |
-| `openResource` / `open-resource`       | 在主機UI中開啟特定域物件。                      |
-| `requestApproval` / `request-approval` | 要求主持人展示確認流程。為此註冊一個處理程序。  |
+| `openResource` / `open-resource`       | 在主機 UI 中開啟特定域物件。                    |
+| `requestApproval` / `request-approval` | 要求主持人展示確認流程。為此註冊一個處理常式。  |
 
-如果未提供處理程序，安全預設值將調度瀏覽器事件，例如 `agentNative:refresh-data` 和 `agentNative:remount-view`。 `requestApproval`沒有預設處理程序；在依賴它之前先註冊一個。
+如果未提供處理常式，安全預設值將調度瀏覽器事件，例如 `agentNative:refresh-data` 和 `agentNative:remount-view`。 `requestApproval`沒有預設處理常式；在依賴它之前先註冊一個。
 
-### 審批指南
+### 核准指南
 
-在其清單中將有風險的用戶端 actions 標記為 `destructive: true`，並在執行刪除、發布、發送、收費、邀請、共用或以其他方式影響目前視圖之外的使用者的操作之前需要主機批準。後端 actions 也應該執行自己的授權和批準檢查；主機批準是有用的使用者體驗，而不是安全邊界。
+在其清單中將有風險的用戶端 actions 標記為 `destructive: true`，並在執行刪除、發布、傳送、收費、邀請、共用或以其他方式影響目前檢視之外的使用者的操作之前需要主機核准。後端 actions 也應該執行自己的授權和核准檢查；主機核准是有用的使用者體驗，而不是安全邊界。
 
 更喜歡這個形狀：
 
 - 持久突變在後端操作中執行，包括驗證、驗證、審核記錄紀錄和重試。
-- 主機指令開啟批準UI或聚焦受影響的資源。
-- 用戶端操作僅處理無法在後端發生的實時 UI 步驟。
+- 主機指令開啟核准 UI 或聚焦受影響的資源。
+- 用戶端操作僅處理無法在後端發生的即時 UI 步驟。
 
 ### 執行時整合
 
@@ -583,15 +583,15 @@ iframe 內的可用全域變數：
 
 | 工具                | 目的                                           |
 | ------------------- | ---------------------------------------------- |
-| `view-host-screen`  | 讀取語義主機上下文和螢幕快照。                 |
-| `list-host-actions` | 列出目前分頁公開的實時瀏覽器工作階段 actions。 |
-| `run-host-action`   | 按名稱執行一個實時用戶端操作。                 |
-| `send-host-command` | 發送刷新、導覽、重新安裝或批準等主機指令。     |
+| `view-host-screen`  | 讀取語義主機脈絡和螢幕截圖。                   |
+| `list-host-actions` | 列出目前分頁公開的即時瀏覽器工作階段 actions。 |
+| `run-host-action`   | 按名稱執行一個即時用戶端操作。                 |
+| `send-host-command` | 傳送重新整理、導覽、重新安裝或核准等主機指令。 |
 
-助手有意返回普通的 `{ name, description, parameters, execute }` 物件，以便 sidecar 可以將它們調整為 AI SDK、Anthropic、OpenAI 函數調用或 Agent-Native `ActionEntry` 形狀，而無需將此 SDK 耦合到一個執行時。
+助手有意返回普通的 `{ name, description, parameters, execute }` 物件，以便 sidecar 可以將它們調整為 AI SDK、Anthropic、OpenAI 函式呼叫或 Agent-Native `ActionEntry` 形狀，而無需將此 SDK 耦合到一個執行時。
 
 ## 推薦產品形狀
 
 首先啟動 iframe。它適用於 Builder.io、客戶 SaaS 應用程式和內部管理工具，無需耦合發布週期或 CSS/執行時假設。
 
-sidecar 本身應該仍然是 Agent-Native 應用程式/範本：actions 是後端 API 表面，SQL 支持的應用程式狀態是代理的內存，並且 Slack 或 Telegram 等整合可以路由到相同的持久聊天。嵌入的 SDK 在該 sidecar 和目前主機頁面之間提供活動膜。
+sidecar 本身應該仍然是 Agent-Native 應用程式/範本：actions 是後端 API 表面，SQL 支援的應用程式狀態是代理的記憶，並且 Slack 或 Telegram 等整合可以路由到相同的持久聊天。嵌入的 SDK 在該 sidecar 和目前主機頁面之間提供活動膜。

package/docs/content/locales/zh-TW/evals.md

@@ -5,18 +5,18 @@ description: "編寫 *.eval.ts 測試用例，根據固定輸入執行真實代
 
 # CI 評估門
 
-評估是一流的測試原語：您聲明一個提示加上您期望的行為，執行程序**實際上針對該輸入執行代理循環**，使用可組合評分器對輸出進行評分，如果任何情況得分低於其閾值，則以非零值退出。這種非零退出使 `agent-native eval` 成為一個嵌入式 CI 部署入口。
+評估是一流的測試原語：您聲明一個提示加上您期望的行為，執行程式**實際上針對該輸入執行代理迴圈**，使用可組合評分器對輸出進行評分，如果任何情況得分低於其閾值，則以非零值退出。這種非零退出使 `agent-native eval` 成為一個嵌入式 CI 部署入口。
 
 這是對 [Observability](/docs/observability) 中事後評分的補充：
 
-- **可觀測性評估** (`observability/evals.ts`) — _“這次實際執行效果如何？”_ 被動、采樣、緊鄰痕跡。
-- **`*.eval.ts`（此原語）** — _“代理在此固定輸入上執行正確的操作嗎？”_ 主動、確定性、通過 CLI 執行的 CI 門。
+- **可觀測性評估** (`observability/evals.ts`) — _“這次實際執行效果如何？”_ 被動、取樣、緊鄰痕跡。
+- **`*.eval.ts`（此原語）** — _“代理在此固定輸入上執行正確的操作嗎？”_ 主動、確定性、透過 CLI 執行的 CI 門。
 
-執行程序從現有註冊表中解析與提供者無關的引擎/模型 - 沒有模型被硬編碼 - 因此相同的套件可以針對應用程式設定的任何引擎執行。
+執行程式從現有註冊表中解析與提供者無關的引擎/模型 - 沒有模型被硬編碼 - 因此相同的套件可以針對應用程式設定的任何引擎執行。
 
-```an-diagram title="從固定輸入到部署門" summary="跑步者實際上在每種情況下執行代理循環，對輸出進行評分，如果任何評分者低於閾值，則以非零值退出——使其成為一個插入式 CI 門。"
+```an-diagram title="從固定輸入到部署門" summary="跑步者實際上在每種情況下執行代理迴圈，對輸出進行評分，如果任何評分者低於閾值，則以非零值退出——使其成為一個插入式 CI 門。"
 {
-  "html": "<div class=\"eval-flow\"><div class=\"diagram-node\">*.eval.ts<br><small class=\"diagram-muted\">prompt + expected behavior</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">執行代理循環<br><small class=\"diagram-muted\">real engine/model</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Scorers<br><small class=\"diagram-muted\">every one must pass threshold</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box ok\">exit 0 &rarr; deploy</div><div class=\"diagram-box warn\">exit 1 &rarr; block</div></div></div>",
+  "html": "<div class=\"eval-flow\"><div class=\"diagram-node\">*.eval.ts<br><small class=\"diagram-muted\">prompt + expected behavior</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">執行代理迴圈<br><small class=\"diagram-muted\">real engine/model</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Scorers<br><small class=\"diagram-muted\">every one must pass threshold</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box ok\">exit 0 &rarr; deploy</div><div class=\"diagram-box warn\">exit 1 &rarr; block</div></div></div>",
   "css": ".eval-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.eval-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.eval-flow .diagram-col{display:flex;flex-direction:column;gap:8px}.eval-flow .diagram-arrow{font-size:22px;line-height:1}"
 }
 ```
@@ -40,9 +40,9 @@ export default defineEval({
 });
 ```
 
-只有當**每個**得分者都達到閾值時，評估才會通過。關鍵 `defineEval` 欄位：
+只有當**每個**得分者都達到閾值時，評估才會透過。關鍵 `defineEval` 欄位：
 
-| 欄位        | 型別                  | 注釋                                             |
+| 欄位        | 型別                  | 註解                                             |
 | ----------- | --------------------- | ------------------------------------------------ |
 | `name`      | 字串                  | 必填。報告中顯示。                               |
 | `input`     | `{ prompt, history }` | 需要`prompt`；可選的先前 `{ role, text }` 轉彎。 |
@@ -63,24 +63,24 @@ interface AgentRunOutput {
 }
 ```
 
-## 內置記分器 {#built-in}
+## 內建記分器 {#built-in}
 
 從 `@agent-native/core/eval` 匯入：
 
 | 得分手                   | 得分                                                  | 型號？ |
 | ------------------------ | ----------------------------------------------------- | ------ |
-| `exactMatch(expected)`   | `1.0` 如果文本等於 `expected`（已修剪，不區分大小寫） | 沒有   |
+| `exactMatch(expected)`   | `1.0` 如果文字等於 `expected`（已修剪，不區分大小寫） | 沒有   |
 | `contains(needles)`      | 存在所需子字串的分數（因此部分命中）                  | 不     |
-| `usesTool(toolName)`     | `1.0`（如果代理調用該工具/操作至少一次）              | 否     |
+| `usesTool(toolName)`     | `1.0`（如果代理呼叫該工具/操作至少一次）              | 否     |
 | `llmJudge({ criteria })` | LLM 作為評委根據自然語言評分標準進行評分，→ `0..1`    | 是     |
 
-`exactMatch` 和 `contains` 采用可選的 `{ caseSensitive }`。 `llmJudge` 采用 `{ criteria, rubric?, name?, scoreRange? }` - 其輸出標準化為 `[0, 1]`，判斷模型是執行程序解析的任何內容（絕不是硬編碼的提供程序）。
+`exactMatch` 和 `contains` 采用可選的 `{ caseSensitive }`。 `llmJudge` 采用 `{ criteria, rubric?, name?, scoreRange? }` - 其輸出標準化為 `[0, 1]`，判斷模型是執行程式解析的任何內容（絕不是硬編碼的提供者）。
 
 ## 自訂評分器：4 步流程 {#custom}
 
 `createScorer` 從 Mastra 風格的 4 步管道建置一個記分器。僅需要 `generateScore`：
 
-```an-diagram title="4 步評分管道" summary="預處理和分析預設身分；僅需要generateScore。 analyze 可以執行普通 JS 或通過 ctx 調用 LLM 判斷。"
+```an-diagram title="4 步評分管道" summary="預處理和分析預設身分；僅需要generateScore。 analyze 可以執行普通 JS 或透過 ctx 呼叫 LLM 判斷。"
 {
   "html": "<div class=\"scorer\"><div class=\"diagram-card\"><span class=\"diagram-pill\">preprocess(run)</span><small class=\"diagram-muted\">transform the run/output &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">analyze(x, ctx)</span><small class=\"diagram-muted\">plain JS or LLM judge &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">generateScore(a)</span><small class=\"diagram-muted\">&rarr; 0..1 normalized &middot; <strong>required</strong></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">generateReason</span><small class=\"diagram-muted\">human-readable why &middot; optional</small></div></div>",
   "css": ".scorer{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.scorer .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.scorer .diagram-arrow{font-size:20px;line-height:1}"
@@ -94,7 +94,7 @@ generateScore(a)    → 0..1       REQUIRED, normalized
 generateReason(...) → string     human-readable why (optional)
 ```
 
-`preprocess` 和 `analyze` 預設為身分（記分員看到原始 `AgentRunOutput`）。 `analyze` 步驟接收 `ctx` 以及與提供者無關的 `judge()` 幫助程序，用於 LLM 支持的評分：
+`preprocess` 和 `analyze` 預設為身分（記分員看到原始 `AgentRunOutput`）。 `analyze` 步驟接收 `ctx` 以及與提供者無關的 `judge()` 幫助程式，用於 LLM 支援的評分：
 
 ```ts
 import { createScorer, clamp01 } from "@agent-native/core/eval";
@@ -133,7 +133,7 @@ agent-native eval --threshold 0.8    # override every eval's pass threshold (0..
 
 | 程式碼 | 含義                                                  |
 | ------ | ----------------------------------------------------- |
-| `0`    | 所有評估均已通過 - *或*未找到評估檔案（CI 友好）。    |
+| `0`    | 所有評估均已透過 - *或*未找到評估檔案（CI 友好）。    |
 | `1`    | 至少有一項評估得分低於閾值，或者套件出錯。            |
 | `2`    | 錯誤的參數（例如 `--threshold` 位於 `[0, 1]` 之外）。 |
 
@@ -148,7 +148,7 @@ agent-native eval --threshold 0.8    # override every eval's pass threshold (0..
 
 將任何評分器降低到閾值以下的回歸會導致該步驟失敗並阻止部署。沒有評估檔案的應用程式會退出 `0`，因此采用評估是每個應用程式的選取。
 
-## 下一步是什么
+## 下一步是什麼
 
 - [**Observability**](/docs/observability) - 實際正式環境執行的事後評分（補充層）
 - [**Actions**](/docs/actions) — `toolCalls` 中顯示的工具/actions