@agent-native/core 0.79.2 → 0.79.5

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

@@ -0,0 +1,146 @@
+---
+title: "調度"
+description: "工作區控制平面：秘密庫、整合中心、跨應用程式委托以及 Slack、電子郵件、Telegram、WhatsApp 的中央收件箱。"
+---
+
+# 調度
+
+Dispatch 是中央應用程式，位於工作區中所有其他應用程式的前面，負責處理機密、整合、訊息傳遞和跨應用程式委派。它是**工作區控制平面** - 您的團隊與之交談的單一代理、實時的單一位置憑證以及決定哪個專業應用程式應處理給定請求的單一路由器。
+
+> **調度範本與 `@agent-native/dispatch` 包。** 此頁面介紹調度應用程式/範本概念 - 它的作用以及您為什么需要它。 `@agent-native/dispatch` npm 包是單獨發布的執行時，它將 Dispatch 範本的伺服器邏輯（保管庫、整合、目標、計畫作業和跨應用程式委派）捆綁為擴充功能它的工作區的嵌入式包。對於腳手架應用程式本身（路線、螢幕、代理指南），請參閱 [Dispatch template](/docs/template-dispatch)。
+
+如果沒有 Dispatch，多應用工作區中的每個應用最終都會重新實現相同的管道：自己的 Slack 機器人、自己的秘密存儲、自己的計畫作業、自己的工作區指令副本。旋轉一把 API 鑰匙會變成十次重新部署。新增一個新策略會變成十次複製貼上。 Dispatch 將所有這些都集中在一個應用程式中，以便其他應用程式能夠專注於自己的領域。
+
+```an-diagram title="Dispatch 作為工作區控制平面" summary="一個收件箱、一個保管庫、一個 MCP 網關和共用資源位於域應用程式前面，Dispatch 作為 A2A 對等方進行存取。"
+{
+  "html": "<div class=\"dsp-hub\"><div class=\"diagram-node\">Users &amp; external agents<br><small class=\"diagram-muted\">Slack · 郵件 · Telegram · WhatsApp · MCP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel dsp-control\" data-rough><span class=\"diagram-pill accent\">Dispatch &mdash; control plane</span><div class=\"dsp-caps\"><span class=\"diagram-pill\">中央收件箱</span><span class=\"diagram-pill\">金鑰保險庫</span><span class=\"diagram-pill\">跨應用委派</span><span class=\"diagram-pill\">MCP gateway</span><span class=\"diagram-pill\">工作區資源</span></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"dsp-peers\"><div class=\"diagram-box\" data-rough>Mail</div><div class=\"diagram-box\" data-rough>Calendar</div><div class=\"diagram-box\" data-rough>Analytics</div></div><small class=\"diagram-muted\">domain apps &mdash; A2A peers</small></div>",
+  "css": ".dsp-hub{display:flex;flex-direction:column;align-items:center;gap:10px}.dsp-hub .dsp-control{display:flex;flex-direction:column;align-items:center;gap:10px;width:100%}.dsp-hub .dsp-caps{display:flex;gap:8px;flex-wrap:wrap;justify-content:center}.dsp-hub .dsp-peers{display:flex;gap:10px;flex-wrap:wrap;justify-content:center}"
+}
+```
+
+## 當您需要調度時 {#when}
+
+滿足以下任一條件時進行調度：
+
+- 您正在執行 [multi-app workspace](/docs/multi-app-workspace) — 郵件、行事曆、分析、內容 — 並且您不希望每個應用有一個 Slack 機器人。
+- 您希望 **為“代理”提供一個收件箱**，以便使用者通過 DM 發送單個機器人，然後由正確的專業應用程式接手幕後的工作。
+- 您擁有多個應用程式需要的**工作區範圍的秘密**（Stripe 金鑰、OpenAI 金鑰、第三方 API 權杖），並且您需要一個保管庫，而不是將值複製到每個 `.env` 中。
+- 您希望在敏感更改（儲存的目標、策略編輯）之前有一個**執行時審批流程**，以便非管理員可以請求，而管理員可以在不部署程式碼的情況下退出。
+- 您需要工作區中的應用程式繼承的**共用 skills、說明、代理設定檔案和 MCP 伺服器** - 更改一次，覆蓋所有。
+
+如果您獨立執行單個範本，則不需要 Dispatch — 每個範本都可以直接連線自己的訊息傳遞整合。有關獨立設定，請參閱 [Messaging](/docs/messaging)。
+
+## Dispatch 的作用 {#what-it-does}
+
+七種功能，全部位於其他應用程式使用的同一工作區資料庫之上：
+
+| 能力            | 它給你什么                                                            | 設定                                                      |
+| --------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
+| **中央收件箱**  | Slack、電子郵件、Telegram、WhatsApp 均通過共用內存 + 工具到達一個代理 | **設定 → 訊息傳送** ([Messaging](/docs/messaging))        |
+| **秘密金庫**    | 將每個憑證存儲一次；在每個應用程式的一處輪換                          | **保管庫** + 存取模式（所有應用程式或手動）               |
+| **跨應用委托**  | 通過 A2A 將請求路由到正確的專業應用並線上程內回複                     | 自動（[A2A](/docs/a2a-protocol)）                         |
+| **統一MCP網關** | 用於外部代理的一個 MCP 連線器可到達每個授權的工作區應用               | [External Agents](/docs/external-agents)                  |
+| **工作區資源**  | 作者 skills/說明/設定檔案一次；應用程式在執行時繼承它們               | **資源**（[Workspace](/docs/workspace#global-resources)） |
+| **夢想**        | 審查過去的執行/意見回饋並提出持久的改進建議供您批準                   | **夢想**分頁                                              |
+| **審批流程**    | 控制內聯管理審核背後的敏感執行時更改                                  | **調度審批政策**                                          |
+
+下面詳細介紹了每項內容。
+
+### 中央收件箱
+
+Slack、電子郵件、Telegram 和 WhatsApp 都流入 Dispatch 的代理循環。在**設定 → 訊息傳送**中連線每個平台一次，每個渠道都會使用相同的內存和工具到達相同的代理。 Slack 私信 和發送給 `agent@yourcompany.com` 的電子郵件最終會成為一個對話歷史紀錄中的兩個表面，而不是兩個斷開連線的機器人。請參閱 [Messaging](/docs/messaging) 以獲取憑證和 Webhook URL。
+
+### 秘密金庫
+
+將憑證存儲在 Dispatch 的保管庫中一次。預設情況下，保管庫存取權限是**所有應用程式**：每個儲存的金鑰均可用於每個工作區應用程式，並且 `sync-vault-to-app` 將完整保管庫推送到目標應用程式。需要更嚴格分離的工作空間可以將保管庫切換到**手動**模式，在同步之前需要明確的每個應用程式授權。非管理員可以**請求**應用程式的秘密；管理員**批準**，這會建立秘密，並在手動工作流程中建立授權。每次讀取、授予、同步和輪換都會紀錄在審核記錄中。這使得“旋轉 OpenAI 鍵”成為跨十個應用而不是十個 PR 的一鍵操作。
+
+### 跨應用委托
+
+Dispatch 自動發現工作區中的其他應用程式作為 A2A 對等體 - 無需手動註冊，無需每個應用程式設定。當使用者在 Slack 中詢問“匯總上週的註冊情況”時，Dispatch 會將其識別為分析請求，並通過 [A2A](/docs/a2a-protocol) 調用分析應用程式。當他們詢問“起草給 Alice 的回複”時，它會路由到郵件應用程式。 Dispatch 將最終答案發布回原始線程中。行為規則存在於調度代理的指令中：域工作屬於域應用程式。 Dispatch 是協調者，而不是專家。
+
+### 統一MCP網關
+
+Dispatch 可以是外部代理的單個 MCP 連線器：在 Claude、ChatGPT、Codex 或 Cursor 中新增一次 `https://dispatch.agent-native.com/_agent-native/mcp`，一次授權可到達每個授予的工作區應用程式，而不是每個應用程式一個連線器。請參閱 [External Agents](/docs/external-agents) 了解完整的連線流程、應用程式授權、OAuth 和內聯 MCP 應用程式預覽。
+
+```an-api
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "統一MCP網關端點",
+  "description": "The single MCP connector URL external agents add (e.g. `https://dispatch.agent-native.com/_agent-native/mcp`). One authorization here reaches every **granted** workspace app instead of wiring one connector per app. App grants, OAuth, and inline MCP App previews are covered in [External Agents](/docs/external-agents).",
+  "auth": "Standard remote MCP OAuth, handled by the framework. The granted-app set scopes which workspace apps the connector can reach.",
+  "responses": [
+    { "status": "200", "description": "MCP JSON-RPC response — tools, resources, and MCP App UI resources aggregated across granted workspace apps." }
+  ]
+}
+```
+
+### 工作區資源
+
+Skills、護欄指令、代理設定檔案和參考資源可以在 Dispatch 中創作一次，並由工作區的其餘部分繼承。 **所有應用程式**範圍的資源是全域的：Dispatch 在工作區範圍內存儲它們一次，每個應用程式代理在執行時讀取它們。它們不會複製到每個應用程式中，並且沒有手動工作區資源同步步驟。應用共用資源和個人資源可以在本機覆蓋或縮小工作區預設值。
+
+請參閱 [Workspace — Global resources](/docs/workspace#global-resources) 了解規範路徑表、入門包和覆蓋模型。
+
+MCP 伺服器資源使用 JSON，並且有意僅限於 HTTP。將權杖存儲在
+調度 Vault，將這些金鑰授予或同步到目標應用程式，並引用它們
+來自帶有 `${keys.NAME}` 的標頭，因此原始憑證永遠不會存在於
+資源主體。
+
+**資源**頁面突出顯示推薦的入門包，以便管理員可以快速檢視存在哪些檔案、恢復丟失的入門檔案而不覆蓋現有檔案，以及編輯其內容。展開任何資源以預覽所選應用程式/使用者的有效執行時堆堆疊。每個應用程式卡還有一個**上下文**視圖，準確顯示該應用程式接收到的內容。
+
+### 夢想
+
+Dispatch Dreams 會審查之前的代理執行、意見回饋、評估和重複的失敗，以提出持久的改進建議。夢想報告是一個審查表面，而不是無聲重寫：它可以建議個人內存更新、陳舊內存清理、共用 `LEARNINGS.md` 編輯、工作區指令/技能/知識/代理資源或重複作業，並且每個建議都連結回證明其合理性的執行。共用指令和團隊範圍的資源在應用之前需要進行審查，特別是當證據來自入站 Slack、電子郵件、Telegram、WhatsApp 或網路內容時。
+
+在提出寫入之前，Dreams 將證據與個人記憶指數、現有的 `memory/*.md` 筆記和共用的 `LEARNINGS.md` 進行比較。如果已捕獲課程，則報告會紀錄該課程已被跳過；如果相關的個人記憶看起來陳舊，提案會針對現有筆記而不是建立副本。
+
+從 Dispatch 中的 **Dreams** 分頁開始。首先執行手動傳遞，開啟提案審核表以將目前目標與提案內容和來源證據進行比較，然後僅應用您想要保留的更改。一旦報告始終有用，Dispatch 就可以建立一個重複的理想工作，不斷生成提案，而無需自動應用共用或指令級更改。
+
+### 審批流程
+
+Dispatch 可以在管理員審核後控制敏感的執行時更改。如今，這涵蓋了**儲存的目的地**（代理可以主動發送到的 Slack 渠道和電子郵件地址）、共用/團隊**夢想提案**、所有應用程式**工作空間資源**建立/更新/刪除以及**調度審批策略**本身。啟用策略後，更改將排隊，並且客服人員直接在聊天中顯示內聯批準預覽 - 管理員無需離開對話即可批準或拒絕。
+
+## Slack訊息如何流經Dispatch {#flow}
+
+端對端地演練一個範例。使用者向機器人發送私信：_“總結上週的註冊情況。”_
+
+1. **Slack → webhook。** Dispatch 應用程式上的 Slack `POST` 到 `/_agent-native/integrations/slack/webhook`。處理程序驗證簽名並**將一行插入 `integration_pending_tasks`**，然後將自定位的 `POST` 觸發到其自己的處理器並立即返回 `200`，以便 Slack 不會重試。
+2. **新處理器執行。**處理器端點在全新的函數執行中執行，具有自己的完全超時。它以原子方式聲明工作並啟動代理循環。
+3. **調度代理決定。**代理讀取訊息，將“註冊”識別為分析意圖，並針對分析應用程式的 [A2A endpoint](/docs/a2a-protocol) 調用 `call-agent`。實際的 SQL 工作在那裡執行。
+4. **線上程中發布回複。**分析代理返回結果。 Dispatch 將其格式化並回發到使用者寫入的同一個 Slack 線程中，如果存在連結身分，則使用連結身分（因此代理根據請求者的權限進行操作，而不是工作區所有者的權限）。
+5. **如果出現任何問題則進行恢復。**如果處理器在執行中當機 — A2A 超時、下游代理錯誤、功能凍結 — 重試作業每 60 秒清除卡住的工作並重新啟動處理器。在工作被標記為 `failed` 之前最多嘗試 3 次。
+
+```an-diagram title="通過 Dispatch 的 Slack 訊息" summary="Slack 排隊到 SQL 中，新的執行耗盡它，Dispatch 代理將域工作委托給 A2A，並且回複返回到原始線程。 60 秒重試作業可恢復任何在飛行中死亡的內容。"
+{
+  "html": "<div class=\"dsp-flow\"><div class=\"dsp-row\"><div class=\"diagram-node\">Slack 私信<br><small class=\"diagram-muted\">\"summarize last week's signups\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><strong>/slack/webhook</strong><br><small class=\"diagram-muted\">驗證 + INSERT 待處理工作</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">200</div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough><strong>fresh processor</strong><br><small class=\"diagram-muted\">領取工作 · 啟動 Agent 循環</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\">Dispatch 代理決策</span><small class=\"diagram-muted\">analytics intent &rarr; call-agent</small></div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough>分析應用<br><small class=\"diagram-muted\">A2A 對等方 · 執行 SQL 工作</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">reply posted in thread</div></div><div class=\"diagram-panel dsp-retry\" data-rough><span class=\"diagram-pill warn\">recovery</span> <span class=\"diagram-muted\">if the processor crashes &mdash; A2A timeout, downstream error, freeze &mdash; the 60s retry job re-fires it (&le;3 attempts) so the Slack reply still arrives</span> <span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</span></div></div>",
+  "css": ".dsp-flow{display:flex;flex-direction:column;gap:12px}.dsp-flow .dsp-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.dsp-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.dsp-flow .dsp-retry{display:flex;align-items:center;gap:8px;flex-wrap:wrap}"
+}
+```
+
+相同的流程適用於電子郵件、Telegram 和 WhatsApp — 只是適配器發生了變化。
+
+## 可靠性故事 {#reliability}
+
+整個管道的建置是為了在每個無伺服器主機（Netlify、Vercel、Cloudflare Workers）上生存，而不依賴於特定於平台的後台執行 API。
+
+- **Webhook → SQL 佇列 → 新執行處理器。** 代理循環永遠不會在 Webhook 處理程序內執行。處理程序的唯一工作是驗證、入隊並返回 200。單獨的新執行會耗盡佇列，因此緩慢的代理執行永遠不會占用入站 Webhook 或導致平台重試。
+- **A2A 連續輪詢。** 當 Dispatch 委托給另一個應用程式時，它會在有限的超時時間內輪詢下游工作。如果下游代理花費太長時間或當機，Dispatch 會紀錄延續，並且重試作業會拾取它 - 使用者的 Slack 回複仍然到達。
+- **自動簽名的跨應用程式 A2A。** 託管多應用程式工作區在部署時自動生成每個應用程式 A2A 憑證，因此同一工作區中的應用程式可以相互調用，而無需貼上 JWT 金鑰。 Dispatch 的代理發現層從工作區資料庫中讀取這些信用，因此新新增的應用程式會自動顯示為可調用對等點。
+
+## 設定 {#setup}
+
+三個簡短步驟：
+
+1. **搭建一個包含 Dispatch 的工作區。**執行 `npx @agent-native/core@latest create my-company-platform` 並選取 `dispatch` 以及您想要的任何域範本。 Dispatch 位於 `apps/dispatch`，其餘應用程式位於它旁邊。參見[Multi-App Workspace](/docs/multi-app-workspace)。
+2. **連線訊息傳遞。** 在 Dispatch 中開啟 **設定 → 訊息傳遞**，然後點選連線 Slack、電子郵件、電報或 WhatsApp。表單欄位與 [Messaging](/docs/messaging) 檔案中的環境變數相匹配 - 請參閱那裡了解每個平台的需求。
+3. **新增其他應用程式。**從每個域應用程式的工作區根執行 `npx @agent-native/core@latest add-app`。它們在 Dispatch 的 `list-workspace-apps` 中自動顯示為 A2A 對等體 — 無需手動註冊，無需編輯代理卡。一旦可以聯系到他們的代理卡，Dispatch 就會開始委派給他們。
+
+然後將憑證新增到保管庫並（可選）在**資源**下創作全域工作區資源。保管庫金鑰仍然可以根據存取模式同步或授予；所有應用程式工作區資源都會自動繼承。如果您需要每個應用程式的秘密隔離，請在授予單個應用程式之前將保管庫存取設定切換為手動。
+
+## 另請參閱 {#see-also}
+
+- [Dispatch template](/docs/template-dispatch) - 實際的腳手架應用程式，帶有完整的操作目錄和代理指南
+- [Messaging](/docs/messaging) — 連線 Slack、電子郵件、Telegram、WhatsApp
+- [A2A Protocol](/docs/a2a-protocol) — 跨應用委派在幕後如何工作
+- [Multi-App Workspace](/docs/multi-app-workspace) - Dispatch 的部署形狀
+- [Workspace Governance](/docs/workspace-management) - 與 Dispatch 的執行時治理配對的 git/GitHub 治理

package/docs/content/locales/zh-TW/drop-in-agent.md

@@ -0,0 +1,260 @@
+---
+title: "臨時代理"
+description: "使用 <AgentPanel>、<AgentSidebar> 和 sendToAgentChat() 將代理聊天 + 工作區安裝到任何 React 應用中。"
+---
+
+# 臨時代理
+
+> **開發人員頁面。** 此頁面供開發人員將代理嵌入到 React 應用程式中。有關使用代理的最終使用者體驗，請參閱 [Using Your Agent](/docs/using-your-agent)。
+
+您不需要從頭開始建置原生代理。代理聊天、工作區分頁、CLI 終端、語音輸入和所有相關基礎設施都作為少數 React 元件提供給您放入任何應用程式中。
+
+> **先決條件：** 伺服器必須執行 `agent-chat-plugin`（它會自動安裝在每個範本中）。如果您是從頭開始，請參閱 [Server](/docs/server)。
+>
+> 需要公開 API 地圖而不是教程？參見[Component API](/docs/components)。
+
+## 元件一覽 {#components}
+
+| 元件                  | 它是什么                                           | 什么時候使用它                           |
+| --------------------- | -------------------------------------------------- | ---------------------------------------- |
+| `<AgentSidebar>`      | 包裝您的根應用布局並新增包含完整代理的可切換側面板 | 您希望代理在每個螢幕上與您的應用一起使用 |
+| `<AgentToggleButton>` | 開啟/關閉 `<AgentSidebar>`（將其放入標頭中）       | 與 `<AgentSidebar>` 配對                 |
+| `<AgentPanel>`        | 原始面板本身 - 聊天 + CLI + 工作區分頁             | 您想要完全控制布局或專用代理頁面         |
+| `<AgentChatSurface>`  | 預接線面板/頁面聊天介面                            | 您想要在沒有側邊欄包裝器的情況下進行聊天 |
+| `<AssistantChat>`     | 具有作曲家/歷史掛鉤的低級聊天渲染器                | 您需要圍繞標準對話 UI 進行自訂鑲邊       |
+| `sendToAgentChat()`   | 以編程方式向聊天發送訊息                           | 將工作交給代理而不是內聯執行的按鈕       |
+| `useActionMutation()` | 圍繞操作的型別安全前端包裝                         | UI 需要執行代理工具執行的相同操作        |
+
+所有這些都是從`@agent-native/core/client`匯出的。
+
+```an-diagram title="安裝型號" summary="<AgentSidebar> 包裝您現有的布局。您的路線在主要區域中呈現；代理面板安裝在它們旁邊。 <AgentPanel> 是沒有包裝紙的同一面板。"
+{
+  "html": "<div class=\"diagram-mount\"><div class=\"diagram-box sidebar\" data-rough><span class=\"diagram-pill accent\">&lt;AgentSidebar&gt;</span><div class=\"inner\"><div class=\"diagram-node main\">你的應用程式<br><small class=\"diagram-muted\">children: header + &lt;Outlet/&gt;</small></div><div class=\"diagram-node panel\">代理面板<br><small class=\"diagram-muted\">chat &middot; CLI &middot; workspace</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-card alt\"><span class=\"diagram-pill\">&lt;AgentPanel&gt;</span><small class=\"diagram-muted\">same panel, no wrapper &mdash; you own the layout</small></div></div>",
+  "css": ".diagram-mount{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-mount .sidebar{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-mount .inner{display:flex;gap:10px}.diagram-mount .main{flex:2}.diagram-mount .panel{flex:1}.diagram-mount .alt{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-mount .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 80%的情況：`<AgentSidebar>` {#sidebar}
+
+最常見的設定是在任何螢幕上從右側開啟側邊欄。
+用 `<AgentSidebar>` 包裹現有的根布局；無論你傳遞什么
+孩子們留在主應用程式區域。代理聊天位於側面板。
+
+```an-annotated-code title="用 <AgentSidebar> 包裝根布局"
+{
+  "filename": "app/root.tsx",
+  "language": "tsx",
+  "code": "import { Outlet } from \"react-router\";\nimport { AgentSidebar, AgentToggleButton } from \"@agent-native/core/client\";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText=\"我能幫什么？\"\n      suggestions={[\n        \"Summarize my inbox\",\n        \"Draft a reply to the latest email\",\n        \"Show me yesterday's signup numbers\",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position=\"right\"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}",
+  "annotations": [
+    { "lines": "6", "label": "包裝紙", "note": "`<AgentSidebar>` wraps your whole layout. It adds the toggleable side panel; everything you pass as children stays in the main app area." },
+    { "lines": "8-12", "label": "啟動提示", "note": "`suggestions` 在空聊天中呈現為可點擊的筹碼。" },
+    { "lines": "13", "label": "上下文感知芯片", "note": "`dynamicSuggestions` merges screen-aware prompts (e.g. \"Summarize this selection\") with your static ones. On by default." },
+    { "lines": "18-20", "label": "切換按鈕", "note": "Put `<AgentToggleButton />` anywhere in your header to open and close the panel." },
+    { "lines": "22-24", "label": "你的應用程式", "note": "`<Outlet/>` (your routes) renders in the main area, untouched." }
+  ]
+}
+```
+
+就是這樣。使用者現在在每個頁面上都有一個可切換代理 - 具有聊天歷史紀錄、工作區分頁、CLI 終端、語音輸入和全屏模式。通過 `localStorage` 重新載入，狀態仍然存在。
+
+### 道具
+
+- **`children`** — 您的應用程式的正常布局和路線。在主區域渲染；代理面板在桌面上安裝在其旁邊，在行動/全屏上安裝在其上方。
+- **`emptyStateText`** — 聊天沒有訊息時顯示的問候語。預設值：`"How can I help you?"`。
+- **`suggestions`** — 啟動提示在空時呈現為可點擊的筹碼。
+- **`dynamicSuggestions`** — 上下文感知提示芯片與 `suggestions` 合並。預設啟用；傳遞 `false` 僅顯示靜態建議，或傳遞 `{ max, includeStatic, getSuggestions }` 進行自訂。
+- **`defaultSidebarWidth`** — 初始像素寬度（僅安裝；使用者調整大小並覆蓋儲存的值）。預設值：`380`。
+- **`position`** — `"left"` 或 `"right"`。預設值：`"right"`。
+- **`defaultOpen`** — 側邊欄是否開始開啟（僅限桌面）。預設值：`false`。
+
+## 另外20%：`<AgentPanel>` {#panel}
+
+當您需要完全控制布局時 - 專用的 `/chat` 路線、您管理的側欄中的嵌入式面板或快顯窗口 - 直接渲染 `<AgentPanel>`：
+
+```tsx
+// app/routes/agent.tsx
+import { AgentPanel } from "@agent-native/core/client";
+
+export default function AgentRoute() {
+  return (
+    <div className="h-screen">
+      <AgentPanel defaultMode="chat" className="h-full" />
+    </div>
+  );
+}
+```
+
+`<AgentPanel>` 為您提供原始分頁（聊天/CLI/工作區），無需側邊欄包裝、折疊按鈕或任何狀態持久性。把它放在你想要的任何地方；您負責布局。
+
+### 選定的道具
+
+- **`defaultMode`** — `"chat"` 或 `"cli"`。預設值：`"chat"`。
+- **`className`** — 外部容器的 CSS 類。
+- **`onCollapse`** — 如果提供，標題中會出現折疊按鈕。
+- **`isFullscreen`** / **`onToggleFullscreen`** — 如果您想要 Claude 樣式的居中列，請連線外部全屏狀態。
+- **`storageKey`** — `localStorage` 金鑰的命名空間。當您在同一頁面中渲染多個面板（不同的應用程式執行個體或工作區）時很有用。
+
+完整道具：`@agent-native/core/client` 中的 `AgentPanelProps`。
+
+## 編程訊息：`sendToAgentChat()` {#send}
+
+將工作交給代理的按鈕（而不是執行內聯 `llm()` 調用 - [ladder](/docs/what-is-agent-native#the-ladder) 的反模式）：
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Generate a chart showing signups by source",
+      context: `Dashboard ID: ${dashboardId}, date range: last 30 days`,
+      submit: true,
+    })
+  }
+>
+  Generate chart
+</Button>;
+```
+
+### 選項
+
+- **`message`** — 聊天中顯示的可見提示。
+- **`context`** - 附加到提示的隱藏上下文（選定的文本、光標位置、目前實體 ID - 代理應該知道但使用者不應看到兩次的任何內容）。
+- **`submit`** — `true` 自動執行，`false` 預填充但等待。省略使用專案預設值。
+- **`newTab`** — 為此提示建立一個單獨的聊天線程。
+- **`background`** — 使用 `newTab`，執行時無需聚焦新線程。隱藏執行在 `RunsTray` 中進行跟蹤。
+- **`openSidebar`** — 設定為 `false` 以進行後台/靜默發送。預設開啟側邊欄，以便使用者看到回應。
+- **`type`** — `"content"`（預設）將工作保留在嵌入式應用程式代理中。 `"code"` 路由到程式碼編輯框架（對於代理編寫的程式碼更改，請參閱 [Frames](/docs/frames)）。
+
+`sendToAgentChat` 返回一個穩定的 `tabId`，您可以使用它來跟蹤聊天執行。
+
+要實現靜音工作，請將 `newTab`、`background` 和 `openSidebar: false` 配對：
+
+```ts
+sendToAgentChat({
+  message: "Summarize the selected thread and save the summary",
+  context: `Thread id: ${threadId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+這仍然是一個使用工具、actions、線程狀態和執行執行的完整代理
+跟蹤。它根本不會從使用者目前的側邊欄狀態中竊取焦點。
+
+當嵌入相同的路由作為MCP App時，提交
+`sendToAgentChat()` 呼叫將轉發至支持的聊天主機；參見
+[Client](/docs/client#sendtoagentchat) 用於 MCP 應用橋接行為。
+
+如果您想要載入狀態，請使用 `useSendToAgentChat()` 鉤子 - 它返回 `send` 和 `isGenerating`：
+
+```ts
+import { useSendToAgentChat } from "@agent-native/core/client";
+
+const { send, isGenerating } = useSendToAgentChat();
+```
+
+## 當常用側邊欄不合適時 {#custom-chat-ui}
+
+`<AgentSidebar>`和`<AgentPanel>`涵蓋了大多數應用程式。當您需要擁有
+圍繞代理進行布局，或者您想要與代理進行對話
+您在其他地方建置，放下一層 - 但繼續讓框架擁有
+執行時、actions 和 SQL 支持的狀態：
+
+- **在標準執行時擁有 chrome。**使用 `<AgentChatSurface>`
+  專用聊天路由，或者當您需要自訂標題時為 `<AssistantChat>`，
+  分頁，以及標準對話週圍的空白狀態。完整圖層圖 —
+  每個元件、鉤子、編寫器和適配器，以及匯入路徑 - 都位於
+  [Component API](/docs/components#agent-chat-ui).
+- **自帶代理執行時。**如果您在其他地方建置的代理應該
+  在 Agent-Native 保留作曲家、文字紀錄和工具的同時推動對話
+  卡片、批準和本機小部件，將 `AgentChatRuntime` 傳遞給
+  `<AssistantChat runtime={...} />`。連線器
+  （`createHttpAgentChatRuntime()` 和 OpenAI / Claude / Vercel AI / AG-UI
+  helpers）和事件契約紀錄在
+  [Native 聊天介面 — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
+
+無論您選取哪一層，都將 actions 和 SQL 支持的應用程式狀態保留為合約，
+並避免從產品 UI 直接發布到 `/_agent-native/agent-chat`。如果一個
+真正的自訂表面缺少指定的助手，請先新增該助手
+用戶端程式碼不會學習第二個臨時傳輸。
+
+## 來自 UI 的型別安全 actions：`useActionMutation()` {#use-action-mutation}
+
+當 UI 需要執行代理工具將執行的相同操作（[ladder](/docs/what-is-agent-native#rung-three) 的梯級 3）時，請使用 `useActionMutation`：
+
+```tsx
+import { useActionMutation } from "@agent-native/core/client";
+
+const { mutate, isPending } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+型別安全參數來自 `defineAction()` 中的 zod 模式。完整的動作系統請參見 [Actions](/docs/actions)。
+
+```an-callout
+{
+  "tone": "decision",
+  "body": "**`useActionMutation` vs `sendToAgentChat`.** Run the operation directly with `useActionMutation` when the user clicked a deterministic button (\"Send reply\"). Hand it to `sendToAgentChat` when the work needs the agent's reasoning, tools, or multi-step planning. Never call an inline `llm()` from UI — that is rung 1 of the [ladder](/docs/what-is-agent-native#the-ladder)."
+}
+```
+
+## 選取+光標感知 {#selection}
+
+代理可以在應用程式狀態下通過 `navigation` 和 `selection` 鍵檢視使用者選取的內容 - 文本、單元格、幻燈片、聯系人。當目前螢幕使它們相關時，空聊天還使用這些鍵提供動態建議，例如“總結此選取”或“改進此幻燈片”。如果您希望使用 Cmd-I（或類似鍵）將選定的範圍作為上下文發送到聊天中，請參閱 [Context Awareness](/docs/context-awareness)。
+
+## 將它們放在一起 {#putting-it-together}
+
+典型的嵌入式設定：
+
+```tsx
+// app/root.tsx
+import {
+  AgentSidebar,
+  AgentToggleButton,
+  sendToAgentChat,
+} from "@agent-native/core/client";
+
+export default function Root() {
+  return (
+    <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>
+      <Header>
+        <AgentToggleButton />
+      </Header>
+
+      <Main>
+        <YourRoutes />
+      </Main>
+    </AgentSidebar>
+  );
+}
+```
+
+```tsx
+// Anywhere else in the app
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Summarize this thread",
+      context: `Thread id: ${threadId}`,
+      submit: true,
+    })
+  }
+>
+  Summarize
+</Button>
+```
+
+使用者在標題中看到一個聊天按鈕，可以開啟它，並可以與客服人員交談。您的按鈕將工作交給同一個代理，而不是執行一次性 LLM 調用。
+
+## 下一步是什么
+
+- [**Actions**](/docs/actions) — `defineAction()` 和 `useActionMutation()`
+- [**Context Awareness**](/docs/context-awareness) — 選取、導覽、檢視螢幕
+- [**Workspace**](/docs/workspace) —“工作空間”分頁包含的內容（skills、內存、MCP 伺服器、計畫作業）
+- [**Voice Input**](/docs/voice-input) — 聊天編輯器中的麥克風

package/docs/content/locales/zh-TW/durable-resume.md

@@ -0,0 +1,65 @@
+---
+title: "持久的簡歷"
+description: "當託管代理執行被中斷並恢復時，已完成的副作用工具調用不會重新執行 - 從持久帳本派生的工具調用記錄會阻止重複發送、收費和票證。"
+---
+
+# 持久的簡歷
+
+> **這是誰的：**任何想要了解框架如何執行的人
+> 恢復可避免重複的副作用。這是內置行為——有
+> 無需連線。
+
+託管代理執行被中斷：無伺服器函數在中途遇到硬超時，網關在 45 秒時斷開連線，套接字暫停，平台冷啟動。該框架已經通過儲存對話前綴並重新執行 LLM 調用（“從上次中斷的地方繼續”）來恢復。但僅恢復就有一個明顯的優勢：如果被中斷的嘗試**已經發送了一封電子郵件或建立了一個票證**，那么天真的簡歷可以再次做到這一點。
+
+持久的簡歷彌補了這一差距。恢復時，框架知道哪個副作用工具調用已經完成，並拒絕在兩層重新執行它們。
+
+```an-diagram title="兩層可阻止簡歷上重複的副作用" summary="記錄讀取持久帳本並對之前的調用進行分類；第 1 層告訴模型，第 2 層硬阻止與已完成條目匹配的重新分派寫入。"
+{
+  "html": "<div class=\"diagram-durable\"><div class=\"diagram-box\" data-rough>Run-event ledger<br><small class=\"diagram-muted\">tool_start / tool_done</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Tool-call journal</strong><small class=\"diagram-ok\">completed = start+done</small><small class=\"diagram-warn\">interrupted = start, no done</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">Layer 1 · prompt note &rarr; model</div><div class=\"diagram-pill accent\">第 2 層 · 硬阻塞重新派發寫入</div></div></div>",
+  "css": ".diagram-durable{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-durable .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-durable .diagram-arrow{font-size:22px;line-height:1}.diagram-durable .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 工具調用記錄 {#journal}
+
+記錄是**對持久執行事件分類帳的純粹讀取** - 熱路徑中沒有新的紀錄掛鉤。它對目前回合已紀錄的工具調用進行分類：
+
+- **已完成** — `tool_start` 與匹配的 `tool_done`。調用執行，它的副作用發生，並且它的結果被紀錄。 **不要重新執行。**
+- **中斷** — `tool_start`，**沒有**匹配 `tool_done`。通話開始了，它的副作用可能已經發生，也可能沒有發生，而中斷則吞噬了結果。結果未知。
+
+匹配反映了如何在其他地方重建耐用轉彎：`tool_done` 與最舊的仍開啟的 `tool_start` 配對，使用相同的工具名稱（每個工具 FIFO）。 `clear` 事件（廢棄的部分輸出）會重置每輪計數，因此廢棄的部分輸出不會留下虛擬的開放調用。
+
+## 第1層：提示級日記筆記 {#prompt-note}
+
+當執行恢復時（軟超時、網關超時或任何可恢復的傳輸錯誤），框架會在“從上次停止的地方繼續”輕推之後，將**結構化記錄注釋**附加到恢復提示中。該注釋以純文本形式告訴模型：
+
+- 哪個工具調用**已經完成**（結果很短），因此它會重用它們並且**不會**重新執行它們，並且
+- 哪個工具調用被**因未知結果而中斷**，因此它會在假設成功或失敗之前驗證狀態。
+
+當記錄為空時（沒有工具活動的回合，或幹淨的延續），不會附加任何額外內容，並且恢復行為與之前的情況相同。該注釋是盡力而為的：失敗的帳本讀取永遠不會阻止本來會成功的恢復。
+
+## 第2層：工具層硬塊 {#hard-block}
+
+提示資訊是建議性的 - 一個表現良好的模型會注意到它，但模型並不能保證。因此循環也在工具層強制執行它。
+
+在循環在恢復的塊中執行之前，它會對記錄進行一次快照（僅捕獲此邏輯回合的**之前**塊）。當模型重新分派工具名稱**和輸入**與已完成的日記條目匹配的**寫入**工具時，循環會短路：它返回日記結果而不是執行操作，並注意該調用已在之前中斷的嘗試中完成，並且不會重新執行以避免重複的副作用。
+
+關鍵屬性：
+
+- **僅限寫入工具。**唯讀 (`readOnly` / GET) actions 永遠不會被阻止 - 重新讀取是安全且冪等的。
+- **內容尋址。** 匹配基於工具名稱 + 輸入簽名，因此輪流中位於不同位置的恢復調用仍然匹配； _ different_ 調用（不同的參數）被視為新鮮調用並正常執行。
+- **消費一次。**每個已完成的條目在匹配時都會被聲明，因此同一輪中兩個真正不同的相同的新調用不會在一個記錄完成時同時短路。
+- **新呼叫未受影響。**首輪呼叫會看到空記錄；正常執行沒有任何變化。
+
+```an-callout
+{
+  "tone": "success",
+  "body": "Together the two layers mean an interrupted run that already had a real side effect resumes **without repeating it** — no duplicate emails, charges, or tickets — while genuinely new work still runs. Read-only actions are never blocked; re-reading is always safe."
+}
+```
+
+## 相關
+
+- [**Real-Time Sync**](/docs/real-time-collaboration) — 持久執行帳本如何流式傳輸到用戶端並在重新連線時重播。
+- [**Actions**](/docs/actions) — `readOnly` 將讀取標記為可以安全地重新執行；其他一切都被視為副作用。
+- [**In-Loop Processors**](/docs/processors) — 另一個循環內部硬化接縫。