@agent-native/core 0.79.2 → 0.79.5

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

@@ -0,0 +1,236 @@
+---
+title: "跟蹤和分析"
+description: "使用可插入提供程序進行伺服器端分析 - PostHog、Mixpanel、Amplitude 或自訂 Webhook"
+---
+
+# 分析跟蹤
+
+一個功能，多個目的地。從任何伺服器端程式碼（actions、外掛、伺服器路由）調用 `track()`，事件就會分發到每個註冊的分析提供者。沒有 SDK 依賴性，沒有用戶端腳本，沒有阻塞。相同的 `track()` 也可在 [browser/app code](#client) 中使用，並路由至相同的提供者。
+
+這是*product*分析——您的應用程式的事件流向PostHog/Mixpanel/Amplitude。有關存儲在您自己的資料庫中的*代理品質*指標（跟蹤、成本、評估、意見回饋），請參閱 [Observability](/docs/observability)。
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "order.completed",
+  { total: 49.99, items: 3 },
+  { userId: "steve@builder.io" },
+);
+```
+
+```an-diagram title="一次 track() 調用，每個提供者" summary="伺服器和用戶端調用者存取相同的註冊表，該註冊表將每個事件並行地分發給所有活動的提供者。"
+{
+  "html": "<div class=\"trk\"><div class=\"diagram-col\"><div class=\"diagram-node\">伺服器程式碼<br><small class=\"diagram-muted\">actions &middot; plugins &middot; routes</small></div><div class=\"diagram-node\">瀏覽器程式碼<br><small class=\"diagram-muted\">POST /_agent-native/track</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Provider registry</span><small class=\"diagram-muted\">扇出，發送即忘</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">PostHog</div><div class=\"diagram-box\">Mixpanel</div><div class=\"diagram-box\">Amplitude</div><div class=\"diagram-box\">Webhook</div></div></div>",
+  "css": ".trk{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.trk .diagram-col{display:flex;flex-direction:column;gap:8px}.trk .diagram-arrow{font-size:22px;line-height:1}.trk .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 內置提供程序 {#built-in}
+
+設定環境變數，提供程序會在伺服器啟動時自動註冊。無需更改程式碼。
+
+| 提供者   | 環境變數                                                                             |
+| -------- | ------------------------------------------------------------------------------------ |
+| PostHog  | `POSTHOG_API_KEY`（必填）、`POSTHOG_HOST`（可選，預設為`https://us.i.posthog.com`）  |
+| 混合面板 | `MIXPANEL_TOKEN`                                                                     |
+| 振幅     | `AMPLITUDE_API_KEY`                                                                  |
+| Webhook  | `TRACKING_WEBHOOK_URL`（必需）、`TRACKING_WEBHOOK_AUTH`（可選 `Authorization` 標頭） |
+
+多個提供程序可以同時處於活動狀態。每個事件都會發生在他們所有人身上。
+
+## API {#api}
+
+### `track(name, properties?, meta?)` {#track}
+
+觸發分析事件。扇出到所有註冊的提供者。
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "steve@builder.io" },
+);
+```
+
+### `identify(userId, traits?)` {#identify}
+
+識別具有特征的使用者。轉發給支持它的提供者（PostHog、Mixpanel、Amplitude、webhook）。
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+```
+
+需要自訂後端、提供程序註冊表 API 或批處理/單例內部元件？見最後的[Advanced: custom providers & internals](#advanced)。
+
+## 在範本中使用 track() {#templates}
+
+從操作處理程序調用 `track()` 以紀錄使用者或代理活動：
+
+```ts
+// actions/create-project.ts
+import { defineAction } from "@agent-native/core/action";
+import { track } from "@agent-native/core/tracking";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Create a new project.",
+  schema: z.object({
+    name: z.string(),
+    template: z.string().optional(),
+  }),
+  run: async ({ name, template }, ctx) => {
+    const project = await db
+      .insert(projects)
+      .values({ name, template })
+      .returning();
+
+    track("project.created", { name, template }, { userId: ctx.userEmail });
+
+    return { ok: true, projectId: project[0].id };
+  },
+});
+```
+
+跟蹤調用是“即發即忘”的 — 它們會立即返回並且永遠不會阻止操作回應。
+
+## 用戶端跟蹤 {#client}
+
+`track()` 也適用於瀏覽器/應用程式程式碼。從 `@agent-native/core/client` 匯入用戶端孿生並以相同的方式調用它 - 它將事件發布到 `POST /_agent-native/track` 的框架路由，後者將其轉發到**相同**註冊的伺服器端提供程序（PostHog、Mixpanel、Amplitude、webhook）。沒有分析 SDK 發送到瀏覽器，也沒有提供者金鑰暴露在用戶端。
+
+```an-api title="客戶追蹤路線"
+{
+  "method": "POST",
+  "path": "/_agent-native/track",
+  "summary": "將瀏覽器事件轉發到註冊的伺服器端提供者",
+  "auth": "Session required + same-origin/CSRF marker (set automatically by the client helper). Not an open analytics relay.",
+  "params": [
+    { "name": "name", "in": "body", "type": "string", "required": true, "description": "Event name. Capped at 200 characters." },
+    { "name": "properties", "in": "body", "type": "object", "description": "Event properties (~16KB cap). `source: \"client\"` and the active `org_id` are added server-side." }
+  ],
+  "description": "Identity is resolved **server-side** from the session — browser code never passes a `userId`. Fire-and-forget: never blocks the UI, never throws, swallows network errors. Oversized or malformed payloads are rejected."
+}
+```
+
+```ts
+import { track } from "@agent-native/core/client";
+
+// e.g. inside a click handler or effect
+track("checkout.completed", { total: 49.99, items: 3 });
+```
+
+與 [server `track()`](#track) 的主要區別：
+
+- **無身分參數。** 該事件在伺服器端歸因於登入使用者（以及活動組織，如 `properties` 中的 `org_id`）。瀏覽器程式碼永遠不會傳遞 `userId`。
+- **`source: "client"`** 新增到每個事件的屬性中，以便您可以區分用戶端發起的事件和伺服器事件。
+- **一勞永逸。**它永遠不會阻塞 UI，永遠不會拋出並吞掉網路錯誤。
+- **經過驗證，僅限第一方。** 該路由需要工作階段和同來源/CSRF 標記（由幫助程序自動設定），因此它不能用作開放分析中繼。 `name` 的上限為 200 個字符，`properties` 的上限為 ~16KB；過大或格式錯誤的有效負載將被拒絕。
+
+這與框架的內部瀏覽器遙測（`trackEvent()` /自動頁面瀏覽量 - 請參閱下面的 [Browser defaults](#browser-defaults)）不同，後者為 Agent Native 自己的產品分析提供支持。將 `track()` 用於您的應用自己的分析事件，這些事件應到達您設定的提供者。
+
+## 高級：自訂提供程序和內部結構 {#advanced}
+
+大多數應用程式只需要 `track()` / `identify()` 和內置提供程序。表面的其餘部分 - 註冊自訂提供程序、`TrackingProvider` 介面、批處理內部結構以及框架自己的瀏覽器遙測 - 如下。
+
+<details>
+<summary><strong>Provider-registry API、介面、內部結構和瀏覽器預設值</strong></summary>
+
+### `registerTrackingProvider(provider)` {#register}
+
+為任何分析後端註冊自訂提供者。
+
+```ts
+import { registerTrackingProvider } from "@agent-native/core/tracking";
+
+registerTrackingProvider({
+  name: "my-analytics",
+  track(event) {
+    // Send event to your backend
+    fetch("https://analytics.example.com/events", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(event),
+    }).catch(() => {});
+  },
+  identify(userId, traits) {
+    // Optional — link user identity to future events
+  },
+  flush() {
+    // Optional — called on graceful shutdown
+  },
+});
+```
+
+### `flushTracking()` {#flush}
+
+刷新所有提供者。在進程退出之前調用以確保發送待處理事件。
+
+```ts
+import { flushTracking } from "@agent-native/core/tracking";
+
+await flushTracking();
+```
+
+### `unregisterTrackingProvider(name)` {#unregister}
+
+按名稱刪除提供者。如果找到並刪除了提供者，則返回 `true`。
+
+### `listTrackingProviders()` {#list}
+
+返回所有已註冊提供者的名稱。
+
+### TrackingProvider 介面 {#provider-interface}
+
+```ts
+interface TrackingProvider {
+  name: string;
+  track(event: TrackingEvent): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+interface TrackingEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp?: string;
+  userId?: string;
+}
+```
+
+僅需要 `name` 和 `track`。 `identify` 和 `flush` 是可選的 - 如果您的後端支持使用者身分和批量交付，請實現它們。
+
+### 它是如何工作的 {#internals}
+
+- **批處理 HTTP** — 內置提供程序將事件排隊並每 10 秒或累積 50 個事件時刷新（以先到者為準）。這可以最大限度地減少出站請求，而不會丟失資料。
+- **無 SDK 依賴項** — 所有內置提供程序都使用原始 `fetch()`。沒有 PostHog SDK，沒有 Mixpanel SDK，沒有 Amplitude SDK。保持框架輕量級。
+- **盡力交付** - 捕獲並紀錄提供者錯誤。失敗的分析整合絕不會導致調用者當機或阻止請求處理。
+- **全域單例** - 註冊表在 `globalThis` 上使用 `Symbol.for` 金鑰，因此多個 ESM 圖形執行個體（開發模式 Vite + Nitro、符號連結）共用一個提供程序集。
+
+### 瀏覽器預設值 {#browser-defaults}
+
+這涵蓋了框架自己的內部遙測——主要與框架貢獻者和高級範本作者相關。
+
+範本根在啟動時調用 `configureTracking()` 一次。當應用程式可以解析它時，使用 `trackEvent()` 發送的瀏覽器事件會自動包含應用程式/範本上下文以及目前的 LLM 連線：
+
+- `llm_connection` — 標準化提供者標籤，例如 `builder`、`anthropic`、`openai`、`google` 或 `none`
+- `llm_engine` — 引擎 ID，例如 `builder` 或 `ai-sdk:openai`
+- `llm_model` — 已知時選取/預設的模型
+- `llm_connection_source` — `app_secrets`、`settings` 或 `env`
+- `llm_connection_configured` — LLM 連線是否可用
+
+該框架還跟蹤來自 Connect Builder CTA 的 `builder connect clicked`，伺服器端 Builder 連線路由跟蹤已啟動/成功/失敗的生命週期事件。 `configureTracking()`由框架自動調用；您不需要在自己的範本程式碼中調用它。
+
+</details>
+
+## 下一步是什么
+
+- [**Actions**](/docs/actions) — 大多數跟蹤調用的發起位置
+- [**Server Plugins**](/docs/server) - `registerBuiltinProviders()` 在啟動時在 core-routes 外掛中執行
+- [**Secrets**](/docs/security) — 管理用於跟蹤提供者的 API 金鑰

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

@@ -0,0 +1,71 @@
+---
+title: "使用您的代理"
+description: "與代理合作的日常循環：它看到您正在檢視的內容，您指導它，嵌入它，使用 輕 UI，並與它一起共同編輯。"
+---
+
+# 使用您的代理
+
+agent-native 背後的定義思想是，agent 和 UI 是**平等的伙伴** - 請參閱 [What Is Agent-Native?](/docs/what-is-agent-native) 了解原因。本節介紹該承諾的另一半：一旦代理停靠在您的應用旁邊，實際使用該代理的感覺如何。
+
+有一條簡單的直通線。代理**看到**您正在檢視的內容，您**將其引導**到您想要的內容，您可以**嵌入**它在任何地方，您可以在更合適的情況下完全**輕 UI**，並且您可以同時**共同編輯**相同的檔案。其中每一個都是本節中的一個頁面。
+
+```an-diagram title="日複一日的循環" summary="使用對接代理的五種方式 - 每種方式都是本節中的一個頁面。"
+{
+  "html": "<div class=\"diagram-loop\"><div class=\"diagram-card\"><strong>Sees</strong><small class=\"diagram-muted\">your view &amp; selection</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Direct</strong><small class=\"diagram-muted\">@-mentions &amp; voice</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>Embed</strong><small class=\"diagram-muted\">drop into any app</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><strong>輕 UI</strong><small class=\"diagram-muted\">chat is the product</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent-card\"><span class=\"diagram-pill accent\">協同編輯</span><small class=\"diagram-muted\">實時，並排</small></div></div>",
+  "css": ".diagram-loop{display:flex;align-items:stretch;gap:10px;flex-wrap:wrap}.diagram-loop .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:130px;flex:1}.diagram-loop .diagram-arrow{align-self:center;font-size:22px;line-height:1}"
+}
+```
+
+## 它能看到你在看什么 {#it-sees}
+
+代理不會對您的螢幕視而不見。開啟一封電子郵件，它就知道是哪個線程。選取一個圖表，它就知道是哪個圖表。突出顯示一個段落，它可以只作用於該範圍。這種共同的意識讓您可以說“回複此內容”或“總結選取”，而無需每次都拼寫出上下文。
+
+這是有效的，因為目前的導覽和選取位於 `application_state` SQL 中，代理將其作為其上下文的一部分讀取。代理還可以驅動相同的狀態 - 開啟視圖，選取一行 - 這樣你就可以看到它在真實的 UI 中而不是在腳本中工作。
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Shared awareness is two-way.** You and the agent both read and write `application_state`, so \"reply to this\" or \"summarize the selection\" just works — and when the agent navigates, the real UI moves with it."
+}
+```
+
+→ [**Context Awareness**](/docs/context-awareness) — 導覽狀態、視圖螢幕、導覽指令以及代理如何與您的螢幕保持同步。
+
+## 你指揮 {#you-direct-it}
+
+大多數時候，您通過在聊天中輸入內容來引導代理。有兩件事可以讓速度更快。
+
+**提及。** 使用 `@` 標記自訂代理、連線的代理或檔案，將其拉入對話中 — “讓 `@analytics` 拉取上週的資料，然後起草摘要。”提及是您如何在不離開作曲家的情況下找到合適的專家或附加正確的上下文。
+
+**聲音。**作曲家有麥克風。口述請求而不是鍵入請求，提供程序選項範圍從 Builder 的託管轉錄到自帶金鑰到瀏覽器後備。
+
+→ [**Agent Mentions**](/docs/agent-mentions) - `@` - 在聊天中提及自訂代理、連線的代理和檔案。
+→ [**Voice Input**](/docs/voice-input) — 聊天編輯器中的听寫以及轉錄的路由方式。
+
+## 您嵌入它 {#you-embed-it}
+
+代理不是您通過 Tab 鍵切換到的單獨應用程式。它以幾個 React 元件的形式提供——一個側邊欄、一個原始面板和一個 `sendToAgentChat()` 調用——您可以將它們放入任何應用程式中。渲染 `<AgentSidebar>` 為每個螢幕提供一個可切換代理，或連線一個按鈕將特定工作交給聊天，而不是執行一次性 LLM 調用。
+
+→ [**Drop-in Agent**](/docs/drop-in-agent) — 將 `<AgentPanel>`、`<AgentSidebar>` 和 `sendToAgentChat()` 安裝到任何 React 應用程式中。
+→ [**Agent Surfaces**](/docs/agent-surfaces) — 選取工作流程是否應為無頭、聊天優先、嵌入式或完整應用程式。
+
+## 你可以去輕 UI {#ui-light}
+
+並非每個應用程式都需要完整的儀表板。當代理*是*產品時，您可以跳過大部分自訂UI：開啟應用程式，詢問您想要的內容，然後讓代理完成其餘的工作。代理仍然有其管理介面——歷史紀錄、工作區、設定——但主要互動是對話而不是點擊。
+
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — 代理是整個產品的應用。
+
+## 您與它共同編輯 {#you-co-edit}
+
+當您和代理處理同一份檔案時，你們不會輪流處理。通過實時協作，代理的編輯可以與您的編輯一起傳輸 - 實時光標，不會覆蓋 - 與隊友的編輯方式相同。您可以在它工作時繼續輸入，並且它會在發生更改時看到您的更改。
+
+→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — 在同一檔案中使用實時光標和代理編輯進行多使用者協作編輯。
+
+## 下一步是什么 {#whats-next}
+
+- [**Context Awareness**](/docs/context-awareness) — 代理知道您在看什么
+- [**Agent Mentions**](/docs/agent-mentions) — 使用 `@` 提及來引導
+- [**Voice Input**](/docs/voice-input) — 通過說話進行指導
+- [**Drop-in Agent**](/docs/drop-in-agent) — 將其嵌入任何 React 應用
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) — 當代理是產品時，采用 輕 UI
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — 共同編輯同一檔案

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

@@ -0,0 +1,81 @@
+---
+title: "語音輸入"
+description: "代理聊天編輯器中的語音听寫 - Builder Gemini、BYOK 提供程序和瀏覽器 Web 語音後備。"
+---
+
+# 語音輸入
+
+每個代理本機應用程式的聊天編輯器中都有一個麥克風。點選它，說話，您的話就會被轉錄到提示中。在行動設備上很有用，對於長提示很有用，當您的手放在其他東西上時很有用。
+
+框架會自動處理所有這些。 Builder連線的使用者預設獲得Builder託管的Gemini Flash-Lite；否則，使用者可以攜帶自己的提供者金鑰或退回到瀏覽器語音識別。
+
+## 它是如何工作的 {#how-it-works}
+
+作曲家的語音按鈕在瀏覽器中錄製音訊，然後選取提供者：
+
+1. **Builder Gemini Flash-Lite（連線 Builder 時預設）。**瀏覽器將音訊 POST 到 `/_agent-native/transcribe-voice`，`/_agent-native/transcribe-voice` 使用 Gemini Flash-Lite 通過 Builder.io 進行代理。無需 Google API 金鑰。
+2. **BYOK 雲端提供者。** 使用者可以從“設定”中選取 Google Gemini、Groq Whisper 或 OpenAI Whisper。該路由在共用部署憑證之前解析使用者範圍的加密機密。
+3. **瀏覽器網路語音 API（後備）。** 如果沒有可用的伺服器提供者，作曲家可以使用瀏覽器的內置語音識別。適用於基於 Chromium 的瀏覽器（Chrome、Edge、Arc）和 Safari。不太準確；直播。
+
+提供者選取存儲在 `voice-transcription-prefs` 下的應用程式狀態中，因此使用者可以在側邊欄設定中強制使用 `"auto"`（預設 — 選取最佳的可用提供者）、`"builder-gemini"`、`"builder"`、`"gemini"`、`"groq"`、`"openai"` 或 `"browser"`。
+
+```an-diagram title="語音轉錄提供者後備方案" summary="作曲家錄製音訊，然後按順序遍歷伺服器提供程序，僅當沒有可用的伺服器提供程序時才轉到瀏覽器 Web Speech API。"
+{
+  "html": "<div class=\"diagram-voice\"><div class=\"diagram-node\">麥克風按鈕<br><small class=\"diagram-muted\">錄製 webm/opus</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill accent\">1 &middot; Builder Gemini</div><small class=\"diagram-muted\">連線 Builder 後預設使用</small><div class=\"diagram-pill\">2 &middot; BYOK cloud</div><small class=\"diagram-muted\">Gemini &middot; Groq &middot; OpenAI Whisper</small></div><div class=\"diagram-arrow diagram-warn\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box diagram-warn\" data-rough>3 &middot; Browser Web Speech<br><small class=\"diagram-muted\">fallback on 400 &middot; streams live</small></div></div>",
+  "css": ".diagram-voice{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-voice .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-voice .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+該路由**僅限同來源** - 跨站點 POST 被拒絕，因此攻擊者無法從外部頁面燒毀轉錄積分。
+
+## 啟用提供者 {#enabling-providers}
+
+Builder 是最簡單的路徑：從“設定”連線 Builder.io，預設提供者變為 Builder Gemini Flash-Lite。對於 BYOK 提供者，請在“設定”→“API 金鑰”中新增匹配的金鑰。
+
+### 每使用者（推薦用於 SaaS）
+
+使用者通過代理側邊欄設定 UI 設定自己的金鑰。它存儲為使用者範圍的加密秘密（通過 `readAppSecret`）。每個使用者為自己的轉錄付費；主機零成本。
+
+### 共用（用於內部工具）
+
+將 `GEMINI_API_KEY`、`GROQ_API_KEY` 或 `OPENAI_API_KEY` 設定為環境變數或在 `settings` 表中。每個使用者的轉錄都會命中共用金鑰。
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**憑證解析順序：**路由首先檢查使用者自己的加密金鑰，然後檢查共用部署金鑰。擁有自己金鑰的高級使用者始終會覆蓋共用金鑰。如果兩者都不存在，則路由將返回作曲家識別的 400，並默默地退回到瀏覽器 Web 語音。"
+}
+```
+
+## 路線 {#route}
+
+```an-api title="語音轉錄路線"
+{
+  "method": "POST",
+  "path": "/_agent-native/transcribe-voice",
+  "summary": "將錄製的音訊片段轉錄為提示文本",
+  "auth": "Active session (Better Auth cookie). Same-origin only.",
+  "description": "The composer POSTs the recorded clip here; the route resolves a provider and returns the transcribed text. You should not call this directly.",
+  "params": [
+    { "name": "audio", "in": "body", "type": "file", "required": true, "description": "The recorded clip, webm/opus by default. Max 25 MB." },
+    { "name": "provider", "in": "body", "type": "string", "required": false, "description": "Optional override, e.g. gemini, groq, openai, builder." }
+  ],
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "Transcription succeeded", "example": "{ \"text\": \"reply to Sara that I'll be there by 3\" }" },
+    { "status": "400", "description": "No server provider configured — the composer recognizes this and falls back to Web Speech", "example": "{ \"error\": \"no_provider\" }" }
+  ]
+}
+```
+
+您不需要直接調用它——作曲家會這樣做。如果您正在建置自訂輸入介面，請首先重用 `@agent-native/core/client` 中的共用作曲家/語音用戶端片段。將此路由視為需要發送多部分音訊的自訂助手的低級傳輸邊界。
+
+## 自訂提供程序 {#customizing}
+
+提供者欄位是一個普通的應用程式狀態金鑰，因此代理可以根據請求更改它（`"use the browser speech recognizer instead"`）。如果您正在建置具有不同要求的範本（例如，本機 Whisper 部署），請在框架安裝預設路由之前通過註冊您自己的 `transcribe-voice` 路由來交換路由處理程序。
+
+## 下一步是什么
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — 公開語音按鈕的作曲家
+- [**Onboarding**](/docs/onboarding) — 註冊提供者金鑰作為設定步驟
+- [**Security & Data Scoping**](/docs/security) — 每個使用者如何存儲加密秘密

package/corpus/core/docs/content/locales/zh-TW/what-is-agent-native.md

@@ -0,0 +1,202 @@
+---
+title: "Agent-Native是什么？"
+description: "為什么大多數人工智能應用感覺是半成品，是什么讓應用真正成為代理原生的，以及最終的結果是你的日常體驗。"
+---
+
+# Agent-Native是什么？
+
+原生代理是一種建置軟件的方式，其中人工智能代理及其週圍的產品表面是**平等的合作伙伴**。該表面可以是具有一個自訂操作的無頭代理、丰富的聊天或完整的 UI。重要的是代理和人類共用相同的 actions、資料庫和狀態。
+
+如果您只記得本頁面中的一件事，請記住這一點：當今大多數人工智能應用程式都離實用性差一步，而這一差距是目前該領域最大的錯誤。
+
+## 作為一個使用者是什么樣的 {#what-it-looks-like}
+
+想象一個後台工作人員、收件箱、行事曆、表單生成器或分析儀表板。有時還沒有自訂螢幕：您執行一項操作或一項無頭應用程式代理提示。有時，第一個螢幕是聊天：您詢問您想要什么，代理指導設定，顯示表格或圖表，並開啟正確的應用程式視圖。有時聊天會停靠在完整應用程式的右側。通過這些形狀，您可以：
+
+- **從實際操作開始。**一個持久操作可以從 CLI、HTTP、MCP、A2A、應用程式代理循環以及稍後的 UI 執行。
+- **點選存在 UI 時通常點選的任何內容。**所有按鈕、列表、儀表板、鍵盤快速鍵 - 它們都調用代理可以調用的相同操作。
+- **或者只是詢問。** 在代理中輸入“回複 Sara 的電子郵件，說我會在 3 點前到達”。它會開啟正確的線程，起草回複，然後將其顯示給您以供批準 - 就像您手動完成的一樣。
+- **檢視它看到的內容。** 開啟一封電子郵件，代理就知道是哪一封。選取一個圖表，代理就知道是哪個圖表。突出顯示一個段落並按 Cmd+I，代理將僅對該段落執行操作。
+- **觀察它的工作。** 當代理執行操作（開啟視圖、編輯草稿、執行報告）時，UI 會實時更新。您可以隨時停止它、重新導向它或用滑鼠接管。
+- **像隊友一樣引導它。**提供意見回饋、排隊另一個工作、編輯其指令、審核它昨天做了什么。它會記住，並且隨著時間的推移，它會更好地適應您的工作流程。
+
+這就是 agent-native 的設計初衷。這就是大多數產品無法實現這一目標的原因。
+
+## 為什么大多數“人工智能應用程式”都達不到要求（階梯原理） {#the-ladder}
+
+大多數團隊都在攀登，就像梯子一樣，而且大多數人過早地停止了一級。
+
+### 第 1 階 — 單個 LLM 調用（反模式） {#rung-one}
+
+文本框發送提示，AI 返回字串，然後您顯示它。也許用旋轉器。使用者無法糾正路線，人工智能無法采取行動，無法了解發生了什么或為什么。
+
+您隨處可見：“AI 功能”基本上是固定在 SaaS 產品上的“總結”按鈕。它們在演示中看起來令人印象深刻，並在現實變得混亂時打破了這一點。那不是一個產品；而是一個產品。那是一個玩具。
+
+### 梯級 2 — 使用工具聊天 {#rung-two}
+
+現在人工智能可以*做事*。它有工具——“電子郵件草稿”、“搜尋聯系人”、“執行查詢”——以及一個聊天介面，它在你面前工作，顯示工具調用和結果。這就是 Claude、ChatGPT 和 Cursor 在底層的樣子。
+
+這是真正的進步。但就其本身而言，它仍然是一個聊天窗口。沒有正確的 UI。沒有儀表板、沒有列表、沒有表單、沒有鍵盤快速鍵、沒有團隊協作。如果人工智能感到困惑，你就會陷入重新輸入的困境，而不僅僅是點擊正確的按鈕。非開發人員很難以這種格式完成真正的工作。
+
+### 第 3 級 — 代理人 + UI 作為平等合伙人 {#rung-three}
+
+這是代理原生的。您可以在代理週圍新增一個真實的、功能齊全的應用程式 - 至關重要的是，代理可以執行的每個操作也是 UI 中的一個按鈕，並且使用者點選的每個按鈕都執行代理使用的相同邏輯。一種實現，兩種方式。
+
+當您到達第 3 級時，三件事會發生變化：
+
+- **您停止向聊天機器人新增按鈕。您向應用程式新增了代理。** 這對雙方來說都是品質更高的產品。
+- **代理具有真實的上下文。**它可以看到您正在檢視的內容、您選取的內容以及您剛剛執行的操作。它寫入 UI 讀取的同一個資料庫，因此它的工作會立即顯示。
+- **外部代理也可以使用它。**其他代理本機應用程式可以通過 [A2A protocol](/docs/a2a-protocol) 調用此 actions。 Claude程式碼、Codex、ChatGPT自訂MCP應用程式、光標和其他MCP主機可以將其作為[MCP server](/docs/mcp-protocol)驅動。一個應用程式，多個入口點。
+
+這是第 3 級。這是代理本機的。
+
+```an-diagram title="階梯原理" summary="大多數團隊停在第 1 級或第 2 級。原生代理是第 3 級——一個真實的應用程式和一個共用操作介面上的真實代理。"
+{
+  "html": "<div class=\"diagram-ladder\"><div class=\"diagram-card rung rung-3\"><span class=\"diagram-pill accent\">第 3 階 · agent-native</span><strong>代理 + UI 作為平等伙伴</strong><small class=\"diagram-muted\">One action surface. Every agent tool is also a button; every button runs the same logic the agent uses.</small></div><div class=\"diagram-card rung rung-2\"><span class=\"diagram-pill\">第 2 階</span><strong>帶工具的聊天</strong><small class=\"diagram-muted\">代理可以行動，但它仍只是聊天窗口。沒有儀表盤、列表或快速鍵。</small></div><div class=\"diagram-card rung rung-1\"><span class=\"diagram-pill warn\">第 1 階</span><strong>一次 LLM 調用</strong><small class=\"diagram-muted\">Prompt in, string out. Impressive in a demo; breaks the moment reality gets messy.</small></div></div>",
+  "css": ".diagram-ladder{display:flex;flex-direction:column;gap:14px}.diagram-ladder .rung{display:flex;flex-direction:column;gap:6px;padding:16px 18px}.diagram-ladder .rung-2{margin-inline-end:48px}.diagram-ladder .rung-1{margin-inline-end:96px}"
+}
+```
+
+請參閱 [Key Concepts — Protocols](/docs/key-concepts#protocols)，了解所有這些如何掛在同一操作定義上。
+
+## 為什么每個代理都需要 UI {#why-every-agent-needs-a-ui}
+
+即使代理完成了所有繁重的工作，人類仍然需要：
+
+- **看看它在做什么** - 進度、中間輸出、它觸及了什么
+- **引導它** — 提供意見回饋、中斷、對下一個工作進行排隊
+- **管理它** - 編輯其指令、skills、內存、計畫作業、連線的帳戶
+- **檢查其工作**——審查草稿、審核歷史紀錄、回滾錯誤
+- **分享其輸出** - 儀表板、報告、表單、發送給隊友的連結
+
+至少，“代理的 UI”是一個可觀察性和管理儀表板。最多，它是一個完整的 SaaS 應用程式，其中嵌入了代理作為副駕駛。兩端都算作原生代理，並且表面可以從一端增長而無需重寫。
+
+您不必預先選取形狀。代理可以無頭執行，坐在丰富的聊天後面，或者住在圍繞同一操作介面的完整應用程式中 - 請參閱 [Agent Surfaces](/docs/agent-surfaces) 了解具體形狀和 API。
+
+## 為什么每個應用都受益於代理 {#why-every-app-benefits-from-an-agent}
+
+另一面也同樣重要。現有的 SaaS 產品總是遇到同樣的問題：80% 的產品你需要的效果很好，而 20% 的產品你就是無法改變。新增聊天側邊欄很少能解決這個問題——聊天通常無法真正\_做\_UI 可以做的事情。
+
+代理本機翻轉了這一點。由於應用程式中的每個操作都定義一次，並作為按鈕和代理工具公開，因此代理可以執行按鈕可以執行的所有操作（甚至更多），而無需維護單獨的“AI 世界”。自然語言與點擊一起成為一流的輸入。
+
+這個論點不是“代理取代 UI”。它是“**代理屬於應用程式內部，頂部有 UI，作為平等的合作伙伴**。”即使代理是產品的應用程式仍然需要 UI 供人類監督、設定和引導 - 請參閱 [Agent Surfaces — Headless](/docs/agent-surfaces#headless)。
+
+## 代理與 UI 對等 {#agent-ui-parity}
+
+這是定義原則。
+
+> **來自 UI** — 點選按鈕、填寫表格、導覽視圖。 UI寫入資料庫；代理看到結果。
+>
+> **來自代理** — 自然語言，其他代理通過 A2A、Slack、Telegram。代理寫入資料庫； UI 自動更新。
+
+```an-diagram title="一套系統，兩種方式" summary="代理和 UI 寫入相同的操作和相同的資料庫。無論一個人做什么，另一個人都會看到。"
+{
+  "html": "<div class=\"diagram-parity\"><div class=\"diagram-col\"><div class=\"diagram-node\">Human<br><small class=\"diagram-muted\">點擊、表單、快速鍵</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">自然語言 · A2A · Slack</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defined once</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">SQL 資料庫</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">介面實時更新</div></div>",
+  "css": ".diagram-parity{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-parity .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-parity .diagram-arrow{font-size:22px;line-height:1}.diagram-parity .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+當代理建立電子郵件草稿時，它會顯示在 UI 中。當您點選“發送”時，代理就知道它已發送。沒有單獨的“代理世界”和“UI 世界”——它是一個系統。請參閱 [Key Concepts](/docs/key-concepts) 了解實現此功能的架構。
+
+## 通常為電動工具保留定制 {#workspace-customization}
+
+像 Claude Code 這樣的工具之所以如此強大，並不是因為模型，而是**定制層**：每個專案的指令、skills、內存、子代理、連線的服務。您可以根據您的程式碼庫、您的偏好、您的團隊來塑造代理。
+
+Agent-native 為每個使用者提供相同的自訂層 - 無需離開應用程式。每個應用程式都附帶一個個人**工作區**，您（或團隊中的任何人）可以：
+
+- 編輯每個代理都會讀取的團隊範圍規則
+- 讓代理在您更正時自動記住偏好
+- 將可重用的操作指南編寫為 `/slash` 指令
+- 為特定工作保留自訂子代理（使用 `@mentions` 調用）
+- 安排作業在 cron 上執行（例如“每週一早上，總結上週”）
+- 通過每使用者 MCP 伺服器連線外部服務（Gmail、Stripe、Slack、內部 API）
+
+不同之處：它全部存儲在資料庫中，而不是檔案系統中。沒有需要啟動的開發環境，每個使用者沒有容器。每個使用者都可以獲得自己的完整工作空間 - 個人內存、個人聯系、個人 skills - 基本上免費，因為它是表中的所有行。這就是 Claude 程式碼級靈活性在真正的多租戶 SaaS 產品中可行的原因。
+
+請參閱 [Workspace](/docs/workspace) 了解完整概念。
+
+## 有何不同 {#what-makes-it-different}
+
+| 方法                                | 描述                                                                                                   |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| **搭載人工智能的傳統應用**          | 人工智能是事後的想法。僅限於自動完成、摘要或聊天側邊欄，實際上無法在應用程式中執行任何操作。           |
+| **純聊天/代理介面**                 | 強大但難以接近。沒有儀表板，沒有工作流程，沒有持久性。非開發人員無法有效使用它們。                     |
+| **Claude 程式碼 / Codex 用於 SaaS** | 非常適合開發者在自己的機器上使用。不會轉化為多租戶 SaaS — 開發盒上每個使用者一個程式碼庫無法擴充功能。 |
+| **代理本機應用**                    | 代理人是一等公民。它共用相同的資料庫、相同的狀態，並且可以執行 UI 可以執行的所有操作 - 反之亦然。      |
+
+## 整個團隊的發展 {#whole-team-development}
+
+Agent-native 不僅僅適合開發人員。由於代理可以編輯應用程式自己的程式碼，因此開發應用程式不再是僅限開發人員的活動：
+
+- **設計師**通過代理直接在執行的應用程式中更新設計
+- **產品經理**通過描述來新增功能和更新流程
+- **QA** 測試應用並要求代理修複損壞的內容
+- **團隊中的任何人**通過自然語言做出貢獻
+
+願景：減少交接，一個人完成小團隊的工作。
+
+## 分叉並自訂 {#fork-and-customize}
+
+代理本機應用程式遵循分叉和自訂模型。您從**範本**開始 - 行事曆、內容、幻燈片、分析、郵件、剪輯、設計、表單、調度 - 並將其變成您的。每一個都是一個完整的、可工作的 SaaS 產品，您可以批量分叉，而不是一個空白的腳手架：
+
+1. 在[agent-native.com/templates](/templates)上選取範本
+2. 立即將其用作託管應用程式（例如 mail.agent-native.com）
+3. 當您想要自訂時分叉它 - “連線我們的 Stripe 帳戶”、“新增同類圖表”
+4. 代理修改程式碼以滿足您的需求
+5. 將您的分叉部署到您自己的域 - 或留在agent-native.com
+
+因為它是*您的*應用程式，而不是共用基礎設施，所以代理可以安全地改進程式碼。您的應用程式會隨著您的使用而不斷改進。完整故事請參見 [Templates](/docs/cloneable-saas)。
+
+尚未準備好分叉整個範本？您還可以通過向已使用的編碼代理新增**技能**來嘗試代理原生 - 使用 `npx @agent-native/core@latest skills add visual-plan` 安裝計畫技能。請參閱 [Skills Guide](/docs/skills-guide#app-backed-skills)。
+
+## 可組合代理 {#composable-agents}
+
+代理本機應用程式可以相互通信。在郵件應用程式內部，您可以標記分析代理以查詢資料並將結果包含在草稿電子郵件中。代理會發現其他可用代理，在彼此之間移交工作，並在您已經所在的 UI 中顯示結果。
+
+這由 [A2A](/docs/a2a-protocol) 和 [MCP](/docs/mcp-protocol) 提供支持 - 相同的定義，多個表面 - 但作為使用者，您所需要知道的是“我可以向我的任何應用程式尋求任何他們可以做的事情的幫助。”
+
+## 這在程式碼中是什么樣的？ {#what-does-it-look-like-in-code}
+
+如果您正在建置或擴充功能代理本機應用程式，那么中心模式如下：應用程式中的每個操作都是一個**操作** - 定義一次，可供代理和 UI 使用。
+
+```an-annotated-code title="一個動作，定義一次"
+{
+  "filename": "actions/reply-to-email.ts",
+  "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\",\n  schema: z.object({ emailId: z.string(), body: z.string() }),\n  run: async ({ emailId, body }) => {\n    // db and schema come from your app's server/db setup\n    await db.insert(schema.replies).values({ emailId, body });\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "工具表面", "note": "`description` 是代理讀取的內容，以決定何時將其調用為工具。" },
+    { "lines": "6", "label": "型別化契約", "note": "一個 zod `schema` 會驗證來自**每個**介面的輸入：代理、UI、HTTP、MCP 和 A2A。" },
+    { "lines": "7-10", "label": "一次實施", "note": "`run` 主體是唯一的事實來源。 UI 按鈕和代理工具都執行此操作。" }
+  ]
+}
+```
+
+```tsx
+// In any React component — same action, called from a button
+const { mutate } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+```tsx
+// And the agent panel mounted anywhere in your app
+import { AgentSidebar } from "@agent-native/core/client";
+
+<AgentSidebar />;
+```
+
+一個操作，多個表面：代理將其稱為工具，UI 將其稱為型別安全突變，[native chat](/docs/native-chat-ui) 可以呈現顯式小部件結果，外部代理通過 [A2A](/docs/a2a-protocol) 存取它，MCP 主機通過應用程式的 [MCP server](/docs/mcp-protocol) 調用它，可選地使用 MCP 應用程式 UI 資源和標準遠端 MCP OAuth由框架處理。完整參考請參見 [Actions](/docs/actions)。
+
+## 下一步是什么 {#whats-next}
+
+- [**Getting Started**](/docs/getting-started) — 從一個操作開始，選取一個範本，或安裝一項技能
+- [**Agent Surfaces**](/docs/agent-surfaces) — 選取無頭、丰富的聊天、嵌入式邊車或完整應用
+- [**Key Concepts**](/docs/key-concepts) — 架構：SQL、actions、輪詢同步、上下文感知、可移植性
+- [**Templates**](/docs/cloneable-saas) — 範本作為您擁有的完整產品
+- [**Workspace**](/docs/workspace) - 由 SQL 支持的每使用者自訂層（skills、內存、指令、MCP），而不是檔案
+- [**Dispatch**](/docs/dispatch) — 工作區控制平面：秘密庫、Slack/電子郵件收件箱、跨應用委派
+- [**Extensions**](/docs/extensions) - 代理立即建立的沙盒迷你應用程式，無需更改程式碼
+- [**Drop-in Agent**](/docs/drop-in-agent) — 將 `<AgentPanel>` 安裝到任何 React 應用中