@agent-native/core 0.79.2 → 0.79.6

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

@@ -0,0 +1,164 @@
+---
+title: "代理提及"
+description: "使用@提及在聊天中標記自訂代理、連線的代理和檔案。"
+---
+
+# 代理提及
+
+在聊天編輯器中鍵入 `@` 以提及自訂代理、連線的代理、檔案和資源。
+
+## 概述 {#overview}
+
+`@` 提及系統將聊天編輯器連線到更廣泛的代理生態系統。當您鍵入 `@` 時，會出現一個快顯窗口，列出可用的自訂代理、連線的代理、程式碼庫檔案和資源。
+
+這是您通過單個聊天協調多代理工作流程的方式。要求您當地的 `@design` 代理評論布局，`@analytics` 從另一個應用程式中提取最新資料，主要代理可以將兩者合並到一個對話中。
+
+## 提及代理 {#mentioning-agents}
+
+要在聊天編輯器中提及代理：
+
+1. 輸入 `@` 開啟提及快顯窗口
+2. 瀏覽或搜尋可用代理列表
+3. 選取一個代理 - 它在您的訊息中顯示為標籤
+4. 發送訊息 - 伺服器解析提及並將該代理的回應包含在對話上下文中
+
+有兩條代理路徑：
+
+- **自訂代理** — `agents/*.md` 中的本機工作區代理設定檔案。它們使用代理設定檔案的指令和可選模型覆蓋在目前應用程式/執行時內執行。
+- **連線的代理** — 遠端 A2A 對等點。這些是通過 [A2A protocol](/docs/a2a-protocol) 調用的。
+
+在這兩種情況下，您的主要代理都會看到回應並可以引用或建置它。
+
+```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}"
+}
+```
+
+## 它是如何工作的 {#how-it-works}
+
+當發送包含 `@` 提及的訊息時，伺服器上會發生以下情況：
+
+1. 伺服器從訊息中提取提及引用
+2. 對於每個提到的代理：
+   - 自訂代理按照其設定檔案說明在本機執行
+   - 通過 A2A 調用連線的代理
+3. 代理的回應被包裝在 `<agent-response>` XML 塊中並注入到對話上下文中
+4. 主代理處理丰富的訊息，檢視使用者的文本和提到的代理的回應
+
+主代理在其上下文中看到的內容：
+
+```text
+User: Draft an email with the latest signup numbers. @analytics
+
+<agent-response agent="analytics">
+Last week's signups: 1,247 total
+  - Organic: 623
+  - Paid: 412
+  - Referral: 212
+</agent-response>
+```
+
+然後，主代理可以在其回應中自然地使用這些資料 - 例如，將這些數字合並到電子郵件草稿中。
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Mentioned-agent output arrives as an `<agent-response agent=\"…\">` block in the **main agent's** context — not as separate chat bubbles. The main agent decides how to weave it into the reply."
+}
+```
+
+## 新增代理 {#adding-agents}
+
+可以通過多種機制提及代理：
+
+- **自訂工作區代理** — 在“工作區”分頁中建立代理設定檔案為 `agents/*.md`
+- **自動發現** - 框架自動發現在已知端口或設定的 URL 上執行的連線代理
+- **遠端清單** — 新增連線代理清單為 `remote-agents/*.json`
+
+### 自訂工作區代理
+
+自訂代理是存儲在工作區中的 Markdown 檔案：
+
+```markdown
+---
+name: Design
+description: Reviews layouts, product UX, and visual direction.
+model: inherit
+---
+
+You are a focused design agent.
+```
+
+請參閱 [Workspace — Custom Agents](/docs/workspace#custom-agents) 了解完整格式（包括 `tools`、`delegate-default` 和模型覆蓋）。
+
+您可以使用以下方法從“工作區”分頁建立它們：
+
+- `Create Agent` -> `Describe It`
+- `Create Agent` -> `Fill Form`
+
+### 連線代理清單
+
+遠端 A2A 代理仍然使用 JSON 清單：
+
+```json
+// remote-agents/analytics.json
+{
+  "name": "Analytics Agent",
+  "url": "https://analytics.example.com",
+  "apiKey": "env:ANALYTICS_A2A_KEY",
+  "description": "Runs analytics queries and returns data",
+  "skills": ["run-query", "generate-chart"]
+}
+```
+
+---
+
+## 對於開發者：擴充功能提及 {#extending-mentions}
+
+範本可以註冊自訂提及提供程序，以新增代理和檔案之外的特定於域的可提及專案。提及提供者實現了 `MentionProvider` 介面：
+
+```an-annotated-code title="自訂 MentionProvider"
+{
+  "filename": "server/mentions/contacts.ts",
+  "language": "ts",
+  "code": "import type { MentionProvider } from \"@agent-native/core/server\";\n\nconst contactsProvider: MentionProvider = {\n  id: \"contacts\",\n  label: \"Contacts\",\n\n  // 搜尋 for mentionable items\n  async search(query: string) {\n    const contacts = await db.query.contacts.findMany({\n      where: like(contacts.name, `%${query}%`),\n      limit: 10,\n    });\n    return contacts.map((c) => ({\n      id: c.id,\n      label: c.name,\n      description: c.email,\n      type: \"contact\",\n    }));\n  },\n\n  // Resolve a mention into context for the agent\n  async resolve(id: string) {\n    const contact = await db.query.contacts.findFirst({\n      where: eq(contacts.id, id),\n    });\n    return {\n      type: \"context\",\n      text: `Contact: ${contact.name} (${contact.email})`,\n    };\n  },\n};",
+  "annotations": [
+    { "lines": "4-5", "label": "身分", "note": "`id` namespaces the provider; `label` is the section heading shown in the `@` popover." },
+    { "lines": "8-9", "label": "search", "note": "Runs as the user types after `@`. Return up to a handful of matches as `{ id, label, description, type }`." },
+    { "lines": "23-24", "label": "resolve", "note": "Called when the message is sent. Turns a picked id into `{ type: \"context\", text }` that is injected into the agent's context." }
+  ]
+}
+```
+
+在代理聊天外掛設定中註冊提供者：
+
+```ts
+// server/plugins/agent-chat.ts
+import { createAgentChatPlugin } from "@agent-native/core/server";
+
+export default createAgentChatPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  mentionProviders: { contacts: contactsProvider },
+});
+```
+
+自訂提及提供程序與內置代理和檔案提供程序一起顯示在提及快顯窗口中。
+
+## 引用檔案 {#referencing-files}
+
+`@` 快顯窗口不僅限於代理。您還可以參考：
+
+- **程式碼庫檔案** — 輸入 `@` 並搜尋檔案名。檔案內容包含在代理的上下文中，因此它可以讀取、分析或修改檔案。
+- **工作空間資源** — 在“工作空間”分頁中定義的參考檔案。這些可以是資料檔案、設定或任何其他結構化內容。
+- **Skills** — 輸入 `/` 來引用技能。 Skills 提供結構化指令來指導代理如何處理工作。
+
+所有引用型別都遵循相同的模式：從快顯窗口中進行選取，發送訊息時引用的內容將被解析並注入到代理的上下文中。
+
+## 子代理選取 {#sub-agent-selection}
+
+當使用 `agent-teams` 生成子代理時，主代理還可以使用自訂代理（操作：“spawn”）。
+
+傳遞`agent`參數以從`agents/*.md`中選取設定檔案。該設定檔案的指令將新增到委托執行中，並且其 `model` frontmatter 可以覆蓋該子代理的預設模型。

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

@@ -0,0 +1,397 @@
+---
+title: "特工表面"
+description: "將 Agent-Native 無頭使用，作為丰富的聊天，在現有應用程式中，或作為完整的代理本機應用程式。"
+search: "無頭代理丰富聊天完整應用程式 BYO 代理執行時 AgentChatRuntime 嵌入 actions MCP A2A HTTP CLI"
+---
+
+# 特工表面
+
+Agent-Native 是故意可組合的。不用太多就可以使用代理UI，
+在沒有內置代理執行時的情況下使用 UI，或者將兩者一起用作完整的
+應用程式。
+
+有用的選取方法不是先按協議。選取產品表面
+你想要，然後使用匹配的原語。
+
+| 表面                          | 什么時候使用它                                                                   | 開始於                                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **無頭代理**                  | 程式碼、作業、腳本、另一個應用程式或另一個代理應直接調用該工作。                 | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
+| **Agent-Native 上的丰富聊天** | 您想要由內置代理循環支持的獨立或嵌入式聊天。                                     | [Chat template](/docs/template-chat), `<AgentChatSurface>`, `<AssistantChat>`               |
+| **與您的代理進行丰富的聊天**  | 您在其他地方建置了代理，並想要 Agent-Native 的編寫器、腳本、工具卡和本機小部件。 | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`                                     |
+| **嵌入式邊車**                | 您已經有一個 SaaS 應用程式，並希望在其旁邊有一個具有頁面上下文和主機指令的代理。 | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`                                  |
+| **完整應用程式**              | 人類和代理應該共用持久的螢幕、資料、導覽和協作。                                 | 範本、actions、SQL 狀態、上下文感知                                                         |
+
+這些是階段，而不是單獨的產品。工作流程可以以無頭方式啟動
+代理只需執行一個操作，就會以表格或圖表的形式出現在聊天中，然後成為
+應用程式中的全屏，而不更改代理調用的操作。
+
+```an-diagram title="表面光譜" summary="一個操作介面，四種產品形狀——每一種都增加了 UI，而不改變下面的操作。"
+{
+  "html": "<div class=\"diagram-spectrum\"><div class=\"diagram-card\"><strong>Headless</strong><small class=\"diagram-muted\">actions、工作、腳本、其他代理</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>丰富聊天</strong><small class=\"diagram-muted\">輸入框、轉錄、工具卡片</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>嵌入式 sidecar</strong><small class=\"diagram-muted\">agent beside an existing app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">大部分 UI</span><strong>完整應用</strong><small class=\"diagram-muted\">持久螢幕、資料、協作</small></div></div><div class=\"diagram-base\" data-rough><span class=\"diagram-muted\">相同 actions · 相同 SQL · 相同代理循環</span></div>",
+  "css": ".diagram-spectrum{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-spectrum .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px;flex:1}.diagram-spectrum .diagram-arrow{align-self:center;font-size:22px;line-height:1}.diagram-base{margin-top:12px;padding:10px 14px;text-align:center}"
+}
+```
+
+## 無頭代理 {#headless}
+
+當沒有人需要盯著自訂應用螢幕時，請使用無頭路徑
+工作執行：計畫作業、整合、後端工作流程、CLI 循環，
+另一個代理或調用 Agent-Native 的現有產品。
+
+這也是當**代理*是*產品**時要達到的形狀 -
+app-agent 循環是前門，而不是儀表板。您從
+終端、Slack、電子郵件、預定工作、其他代理或聊天 —“總結我的
+未讀電子郵件，”“將每日指標發布到 Slack，”“查找符合以下條件的候選人
+上週回複”——代理執行操作並返回結果
+屬於。它仍然是一個真正的應用程式，而不是無狀態提示：actions，驗證工作階段，
+應用程式狀態、線程/執行歷史紀錄、設定、憑證和共用紀錄全部實時
+在SQL。
+
+在以下情況下選取此模式：
+
+- **工作在後台進行。**大部分價值是在使用者不注意的時候創造的 - 分類代理、每日報告代理、待命回應人員。
+- **輸出離開應用程式。**代理發布到 Slack、發送電子郵件或更新第三方系統；應用內沒有任何內容可供瀏覽。
+- **該域是一次性的。**研究機器人、摘要生成器、報告編寫器 - 沒有需要列表視圖的持久物件。
+- **您正在制作原型。**立即發送代理；如果使用者想要的話，稍後新增更丰富的 UI。
+
+如果您的產品是圍繞持久物件建置的，使用者會瀏覽、透視和
+分享 — 電子郵件、事件、檔案、圖表 — 選取 [full application](#full-application)
+或 [template](/docs/cloneable-saas) 代替；這些新增了完整的 UI _plus_ 代理。
+
+### 盒子裡裝的是什么 {#in-the-box}
+
+無頭應用程式會跳過數週的儀表板工作，並且從一天開始就與渠道無關
+一個 - 同一代理從網路、Slack、Telegram、電子郵件和其他代理執行
+因為一切都通過代理，而不是 UI。權衡是有的
+沒有“一目了然地瀏覽所有內容”視圖；如果使用者需要，請混合模式和
+新增小型狀態頁面或列表視圖。
+
+當新增內置的Chat shell時，框架提供了五種管理
+您不必建置的介面：**聊天**（主要輸入）、**工作區**
+（skills、內存、指令、子代理、連線的 MCP 伺服器、已調度
+jobs）、**作業歷史紀錄**、**線程歷史紀錄**和**設定**。這些通常是
+足夠了——與它交談，看看它做了什么，設定它的行為方式。伸手去拿
+[Chat](/docs/template-chat) 當您準備好新增瀏覽器 UI 時，或
+[Dispatch template](/docs/template-dispatch) 工作空間式啟動
+使用 Slack/Telegram、計畫作業和開箱即用的共用機密。
+
+最小的本機路徑是無頭代理腳手架加上一個操作：
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+cd my-agent
+pnpm install
+```
+
+然後定義持久操作：
+
+```ts
+// actions/summarize-week.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Summarize this week's submissions.",
+  readOnly: true,
+  schema: z.object({ formId: z.string() }),
+  run: async ({ formId }) => {
+    return { formId, summary: "34 submissions, up 18% from last week." };
+  },
+});
+```
+
+然後可以調用一個操作：
+
+- **HTTP** — `POST /_agent-native/actions/summarize-week`
+- **CLI** — `pnpm action summarize-week --formId form_123`
+- **應用程式代理 CLI** — `pnpm agent "Summarize form_123"`
+- **MCP** — 來自 Claude、ChatGPT、Codex、Cursor、OpenCode、Copilot 和其他 MCP 主機
+- **A2A** - 來自另一個代理本機應用程式或代理對等點
+- **UI** — 通過 `useActionQuery`、`useActionMutation` 或 `callAction`
+- **代理工具** - 來自內置聊天循環
+
+```an-api title="通過 HTTP 調用操作"
+{
+  "method": "POST",
+  "path": "/_agent-native/actions/summarize-week",
+  "summary": "通過 HTTP 按名稱調用任何操作",
+  "description": "Every `defineAction` is auto-mounted at `/_agent-native/actions/<name>`. The JSON body is validated against the action's zod schema before `run` executes.",
+  "request": {
+    "contentType": "application/json",
+    "example": "{ \"formId\": \"form_123\" }"
+  },
+  "responses": [
+    { "status": "200", "description": "The action's return value as JSON", "example": "{ \"formId\": \"form_123\", \"summary\": \"34 submissions, up 18% from last week.\" }" },
+    { "status": "400", "description": "Input failed schema validation" }
+  ]
+}
+```
+
+這不是無資料庫或無狀態模式。應用程式代理循環存儲工作階段，
+線程、執行、設定、憑證、應用程式狀態和共用紀錄
+SQL。本機開發預設為SQLite；託管無頭應用程式應使用
+持久 SQL 資料庫。
+
+如果您需要從專案資料夾中無頭地執行整個代理循環，請使用：
+
+```bash
+pnpm agent "Summarize this week's forms."
+```
+
+如果另一個應用程式或腳本需要調用整個代理，請使用
+`agentNative.invoke("analytics", "...")` 或 `agent-native invoke` CLI。那
+將跨應用工作保留在 A2A 路徑上，而本機工作保留在 actions 上。
+
+工作人員、作業、整合 webhooks 和自訂主機可以驅動代理循環
+直接通過伺服器API。這比 actions 級別低 - 您提供
+您自己的引擎、模型、訊息、actions 和事件接收器：
+
+```ts
+import { runAgentLoop } from "@agent-native/core/server";
+
+await runAgentLoop({ engine, model, systemPrompt, actions, messages, send });
+```
+
+對於大多數應用程式，計畫的提示和整合 webhooks 已經調用此循環
+給你。僅在建置自訂無頭主機時直接獲取它，eval
+執行程序，或伺服器端編排表面 - 請參閱[伺服器 - 正式環境代理
+handler](/docs/server#agent-handler) 獲取完整簽名。
+
+### 針對資料夾執行 {#folder-loop}
+
+如果您的目標是“針對此資料夾執行代理”，請從應用程式代理開始
+在該資料夾中循環：建置無頭應用程式，新增 actions/指令，執行
+`pnpm agent "..."`。這使工作保持在相同的操作/執行時/狀態內
+應用程式將在正式環境中使用的合同。
+
+外部編碼線束是用於嵌入 Claude 的獨立產品表面
+Agent-Native 應用內的程式碼、Codex、Pi、Cursor、Mastra 或類似執行時。
+在建置編碼代理產品時使用它們，而不是作為預設方式
+啟動本機代理本機工作流程。
+
+### 雲端儲存庫存取 {#cloud-repo-access}
+
+對於需要儲存庫存取的雲端無頭應用程式，請使用 GitHub 連線器
+加上代幣CRUD模型：列出儲存庫、搜尋檔案、讀取檔案、建立或
+通過提供者範圍編輯檔案、刪除檔案和撤銷存取權限
+憑證。在本機開發中，明確設定目標儲存庫：
+
+```bash
+GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action."
+```
+
+不要將虛擬機克隆或長期沙箱簽出視為主要雲端
+儲存庫存取模型。沙箱對於隔離程式碼執行仍然很重要，但是
+儲存庫存取應該是明確的、經過授權的、可審核的和可撤銷的
+通過連線器層。
+
+### 共用工作階段和執行 {#sharing-runs}
+
+無頭工作階段和執行是持久物件。共用性應該分階段進行：
+首先閱讀/共用連結，以便隊友可以檢查經過清理的提示、輸出
+和執行狀態；稍後授予可寫協作權限，因此繼續執行，
+批準 actions、編輯計畫或更改設定已完成
+顯式存取檢查。
+
+## Agent-Native 上的丰富聊天 {#rich-chat}
+
+當使用者應該與代理交談時使用內置聊天，檢視工具調用，
+批準工作、檢查本機結果並保留持久的線程歷史紀錄。
+
+要獲得完整的應用程式起點，請使用 [Chat template](/docs/template-chat)：
+
+```bash
+npx @agent-native/core@latest create my-chat-app --template chat
+```
+
+最簡單的全頁面聊天：
+
+```tsx
+import { AgentChatSurface } from "@agent-native/core/client/chat";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-screen" />;
+}
+```
+
+當應用同時具有全頁面聊天分頁和 `AgentSidebar` 時，請使用相同的
+在兩個表面上安裝`storageKey`，啟用`chatViewTransition`，並安裝
+布局中的聊天主頁面切換助手。聊天之外的普通應用內連結
+頁面可以將完整的聊天內容轉變為側邊欄，同時保持活動狀態
+線程：
+
+```tsx
+import {
+  AgentChatSurface,
+  AgentSidebar,
+  useAgentChatHomeHandoff,
+  useAgentChatHomeHandoffLinks,
+} from "@agent-native/core/client/chat";
+import { useLocation } from "react-router";
+
+function ChatRoute() {
+  return (
+    <AgentChatSurface mode="page" storageKey="my-app" chatViewTransition />
+  );
+}
+
+function AppLayout({ children }: { children: React.ReactNode }) {
+  const location = useLocation();
+  const handoffActive = useAgentChatHomeHandoff({
+    storageKey: "my-app",
+    activePath: location.pathname,
+    enabled: location.pathname !== "/chat",
+  });
+  useAgentChatHomeHandoffLinks({ storageKey: "my-app", chatPath: "/chat" });
+
+  return (
+    <AgentSidebar
+      storageKey="my-app"
+      chatViewTransition
+      openOnChatRunning={handoffActive}
+    >
+      {children}
+    </AgentSidebar>
+  );
+}
+```
+
+使用您自己的 chrome 進行最簡單的嵌入式聊天：
+
+```tsx
+import { AssistantChat } from "@agent-native/core/client/chat";
+
+export function ProjectChat({ threadId }: { threadId: string }) {
+  return <AssistantChat threadId={threadId} />;
+}
+```
+
+Actions 可以返回顯式的本機小部件結果，因此聊天輸出不僅僅是
+文本。表格、圖表和鍵入的產品卡呈現為第一方 React
+聊天中的元件，沒有 iframe。參見[Native 聊天介面](/docs/native-chat-ui)。
+
+## 與您的代理進行丰富的聊天 {#byo-agent}
+
+當您的代理已使用其他框架建置時，請使用此路徑
+執行時，你想要 Agent-Native 的聊天 UI 圍繞它。 `AgentChatRuntime` 是
+邊界：您的執行時流規範化事件，Agent-Native 呈現
+作曲家、腳本、工具調用、批準、本機小部件和應用布局。
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  endpoint: "/api/support-agent/chat",
+});
+
+export function SupportAgentChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+針對 OpenAI 代理、OpenAI 回應、Claude 存在現成的執行時助手
+Agent SDK、Vercel AI SDK 和 AG-UI，以及上面的標準化 HTTP 執行時
+對於任何其他代理（Mastra、Flue、Eve、LangGraph 或自訂服務）。 ACP 是
+不是最終使用者應用聊天或 A2A 傳輸，並且 Agent-Native 目前沒有
+要求 A2UI 支持。 ACP 在一個特定位置受支持 - 駕駛本機
+編碼代理（Gemini CLI，Claude程式碼，...）通過
+[harness layer](/docs/harness-agents#acp)，這裡不作為聊天執行時。
+
+[Native 聊天介面 — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes)
+是事件形狀、執行時助手和 `chatUI` 的規範主頁面
+工具結果元資料。將外部代理連線到聊天中時從這裡開始。
+
+## 嵌入式邊車 {#embedded-sidecar}
+
+當主產品已經存在並且您想要一個時，請使用嵌入式 sidecar
+代理在旁邊。
+
+伺服器外掛將 Agent-Native 路由安裝到您的主機應用程式中並解析
+主機身分伺服器端：
+
+```ts
+import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server";
+
+export default createAgentNativeEmbeddedPlugin({
+  databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL,
+  auth: getHostSession,
+  actions: hostActions,
+});
+```
+
+React sidecar 傳遞頁面上下文和主機指令：
+
+```tsx
+import { AgentNativeEmbedded } from "@agent-native/core/client";
+
+export function AppShell({ children }) {
+  return (
+    <AgentNativeEmbedded
+      getContext={() => ({
+        route: { pathname: window.location.pathname },
+        selection: { text: window.getSelection()?.toString() || undefined },
+      })}
+      onNavigate={(payload) =>
+        router.navigate((payload as { path: string }).path)
+      }
+      onRefresh={() => queryClient.invalidateQueries()}
+    >
+      {children}
+    </AgentNativeEmbedded>
+  );
+}
+```
+
+```an-diagram title="Sidecar 如何橋接到主機應用程式" summary="該外掛在伺服器端掛載 Agent-Native 路由； React sidecar 流輸入頁面上下文並輸出主機指令。"
+{
+  "html": "<div class=\"diagram-sidecar\"><div class=\"diagram-panel\"><strong>宿主應用</strong><small class=\"diagram-muted\">你現有的 SaaS</small><div class=\"diagram-node\">getContext()<br><small class=\"diagram-muted\">路由 · 選取</small></div><div class=\"diagram-node\">onNavigate / onRefresh<br><small class=\"diagram-muted\">宿主指令</small></div></div><div class=\"diagram-col-arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div></div><div class=\"diagram-panel accent-panel\"><span class=\"diagram-pill accent\">AgentNativeEmbedded</span><small class=\"diagram-muted\">agent + workspace</small><div class=\"diagram-box\" data-rough>Agent-Native 路由<br><small class=\"diagram-muted\">mounted by the server plugin</small></div></div></div>",
+  "css": ".diagram-sidecar{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sidecar .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px 16px;min-width:200px}.diagram-sidecar .diagram-col-arrows{display:flex;flex-direction:column;gap:6px}.diagram-sidecar .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+請參閱 [Embedding SDK](/docs/embedding-sdk) 以了解主機驗證、資料庫隔離，
+iframe/picker 模式，以及較低級別的橋 APIs。
+
+## 完整應用程式 {#full-application}
+
+當使用者需要持久物件和工作流程時使用完整的應用路徑：表單，
+儀表板、行事曆、收件箱、編輯器、檔案、資產或報告。
+
+完整應用程式圍繞相同的操作和代理合同新增產品 UI：
+
+- **SQL 狀態** — 應用資料、導覽、設定和聊天歷史紀錄是持久的。
+- **上下文感知** - 代理知道目前路線、選取和聚焦物件。
+- **實時同步** - 代理更改會更新 UI，UI 更改會更新代理的上下文。
+- **深層連結** — 操作結果可以開啟正確的應用視圖。
+- **本機聊天小部件** — 表格、圖表、卡片、批準和鍵入的結果內聯顯示。
+
+當您想要一個最小的應用程式時，請從 [Chat template](/docs/template-chat) 開始
+您的 actions 週圍，或來自域 [template](/docs/cloneable-saas)，當您
+想要一個完整的產品形狀。
+
+## 如何選取 {#how-to-choose}
+
+| 如果您在想...                                        | 選取                      |
+| ---------------------------------------------------- | ------------------------- |
+| “我只需要一個可調用的工具或工作流程。”               | 無頭代理                  |
+| “我想要框架的代理，但是聊天應該是主要的UI。”         | Agent-Native 上的丰富聊天 |
+| “我已經有一個代理；我需要一個完美的聊天 UI。”        | 與您的代理進行丰富的聊天  |
+| “我已經有一個 SaaS 應用程式；在它旁邊新增一個代理。” | 嵌入式邊車                |
+| “代理和 UI 應該作為產品一起進化。”                   | 完整應用程式              |
+
+保持合約較小：將持久操作定義為 actions，顯式返回
+聊天需要丰富UI時的小部件結果，並且僅在使用者時新增全屏
+需要瀏覽、比較、設定或協作持久物件。
+
+## 相關檔案 {#related-docs}
+
+- [Actions](/docs/actions) — 定義一次無頭操作。
+- [Native 聊天介面](/docs/native-chat-ui) — 在聊天中呈現鍵入的操作結果。
+- [Drop-in Agent](/docs/drop-in-agent) — 安裝聊天、側邊欄或面板表面。
+- [Component API](/docs/components) — 較低級別的 React 聊天/作曲片段。
+- [Embedding SDK](/docs/embedding-sdk) — 將 Agent-Native 新增到現有應用。
+- [External Agents](/docs/external-agents) — 將 MCP 兼容主機連線到應用。
+- [A2A Protocol](/docs/a2a-protocol) — 從其他座席呼叫座席。