@agent-native/core 0.79.2 → 0.79.5

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

@@ -0,0 +1,142 @@
+---
+title: "FAQ"
+description: "有關原生代理的常見問題 - 它是什么、它的用途、您可以建置什么以及它如何工作。"
+---
+
+# FAQ
+
+有關代理原生的常見問題，從“我只是在尋找”到“我現在正在連線驗證”。
+
+## 基礎知識 {#general}
+
+### 什么是代理原生？ {#what-is-agent-native}
+
+Agent-native 是一個用於建置應用程式的框架，其中 AI 代理及其週圍的產品表面是平等的合作伙伴。該介面可以從一個無頭代理開始，通過一個自訂操作，發展成為丰富的聊天，或者成為一個完整的 UI。不變的是智能體和人類共用相同的 actions、資料庫和狀態。完整解釋請參見 [What Is Agent-Native?](/docs/what-is-agent-native)。
+
+### 這是給誰的？ {#who-is-this-for}
+
+Agent-native 適合那些想要真正的應用程式和 AI 代理使用相同資料和 actions 工作的人。常見的路徑是：
+
+- **如果您需要郵件、行事曆、表單、計畫或其他無需設定的成品範本，請使用託管應用程式** - 從 [template gallery](/templates) 開始。
+- **從聊天開始**如果您想要一個使用者可以立即交談的基本應用程式，然後使用 actions 和螢幕進行擴充功能 - 從 [Getting Started](/docs/getting-started) 或 [Chat](/docs/template-chat) 開始。
+- **如果您想要在提交到 UI 之前執行一個操作和一個無頭應用程式代理循環，請先啟動原語優先** — 從 [Getting Started](/docs/getting-started) 開始。
+- **分叉並自訂範本**如果您想要自己的 SaaS 產品，並且已連線驗證、資料庫、UI 和代理 actions — 請參閱 [Templates](/docs/cloneable-saas)。
+- **從頭開始建置**如果您想要新的代理驅動產品的框架原語 - 從 [Getting Started](/docs/getting-started) 開始。
+- **如果您希望 Claude、ChatGPT、Codex、Cursor 或 GitHub Copilot / VS Code 使用代理本機應用程式，請連線另一個代理或程式碼工具** - 請參閱 [External Agents](/docs/external-agents) 和 [Skills Guide](/docs/skills-guide)。
+
+### 這與向現有應用新增 AI 有何不同？ {#how-is-this-different}
+
+大多數應用程式將人工智能作為事後的想法，實際上無法在應用程式中*做*事情。在代理原生應用程式中，代理是一等公民，與 UI 共用相同的 actions、資料庫和狀態，因此它可以執行按鈕可以執行的任何操作 - 並修改應用程式自己的程式碼。參見[What Is Agent-Native?](/docs/what-is-agent-native#the-ladder)。
+
+```an-diagram title="附加人工智能與 agent-native" summary="螺栓固定的聊天側邊欄有自己的世界。 agent-native 代理與 UI 共用相同的操作、資料庫和狀態。"
+{
+  "html": "<div class=\"diagram-vs\"><div class=\"diagram-col\"><span class=\"diagram-pill warn\">外掛式 AI</span><div class=\"diagram-node\">聊天側邊欄</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>獨立的 AI 世界<br><small class=\"diagram-muted\">無法操作應用</small></div><div class=\"diagram-box diagram-muted\">App UI &amp; data</div></div><div class=\"diagram-divider\" aria-hidden=\"true\"></div><div class=\"diagram-col\"><span class=\"diagram-pill ok\">Agent-native</span><div class=\"diagram-row2\"><div class=\"diagram-node\">UI</div><div class=\"diagram-node\">Agent</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>shared actions, DB &amp; state</div></div></div>",
+  "css": ".diagram-vs{display:flex;align-items:stretch;gap:18px;flex-wrap:wrap}.diagram-vs .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:center;flex:1;min-width:200px}.diagram-vs .diagram-row2{display:flex;gap:8px}.diagram-vs .diagram-arrow{font-size:20px;line-height:1}.diagram-vs .diagram-divider{width:1px;align-self:stretch;background:currentColor;opacity:.15}"
+}
+```
+
+### 它是開來源的嗎？ {#is-this-open-source}
+
+是的。該框架和所有範本都是開來源的。您可以在本機執行所有內容、自行託管或使用 Builder.io 的雲端來實現託管、協作和團隊功能。
+
+### 需要多少錢？ {#how-much}
+
+框架本身是免費的。您在實踐中會看到的兩種成本：
+
+- **AI 使用。** 您攜帶自己的 API 金鑰（Anthropic、OpenAI 等）並直接向模型提供者付款。我們沒有加價。
+- **託管。** 無論您的主機收費多少。對於小型工作負載，大多數範本都可以在免費套餐（Netlify、Vercel、Cloudflare）上正常執行。
+
+如果您不想管理其中任何內容，`agent-native.com` 上的託管版本（由 Builder.io 運營）可將推理和託管捆綁到每席位計畫中。
+
+### 我可以自己主持嗎？ {#can-i-self-host}
+
+是的。選取執行 Node 的任何主機 — Netlify、Vercel、Cloudflare、AWS、Deno Deploy、您自己的伺服器 — 以及任何 SQL 資料庫（Postgres、SQLite、Turso、D1）。該框架是為了可移植而建置的。參見[Deployment](/docs/deployment)。
+
+### 支持哪些AI模型？ {#what-models}
+
+Anthropic Claude、OpenAI（GPT-5 系列）、Google Gemini 以及使用 OpenAI API 形狀的任何提供者（包括通過 Ollama 的本機模型）。您可以在設定中設定模型；切換是設定更改，而不是程式碼重寫。該框架最重的測試路徑是 Claude，因此這是預設推薦。
+
+### 我需要了解人工智能/機器學習嗎？ {#do-i-need-to-know-ai}
+
+沒有。您不需要訓練模型、微調或處理嵌入。您建置了一個常規的 Web 應用程式 - 在託管版本上，您幾乎不需要建置任何東西。該框架處理代理整合：路由訊息、執行 actions、同步狀態。
+
+### 我可以將現有應用遷移到代理原生嗎？ {#can-i-use-existing-code}
+
+可以，但是從頭開始建置原生代理效果最好。架構——共用資料庫、輪詢同步、actions、應用程式狀態——需要始終整合。從範本開始並自訂它是推薦的路徑。可以把它想象成從桌面優先到行動優先的轉變：你*可以*改造，但建置原生更好。
+
+## 範本以及您可以建置的內容 {#templates}
+
+### 有哪些範本可用？ {#what-templates-are-available}
+
+該框架附帶了可用於正式環境的範本，包括 [Chat](/docs/template-chat)、[Mail](/docs/template-mail)、[Calendar](/docs/template-calendar)、[Forms](/docs/template-forms)、[Plan](/docs/template-plan)（視覺計畫和 PR 回顧）、[Analytics](/docs/template-analytics)、[Dispatch](/docs/template-dispatch) 等。每個都是一個完整的應用程式，包含 UI、代理 actions、資料庫架構和 AI 指令。完整目錄請參見 [Templates](/docs/cloneable-saas)。
+
+### 我可以自訂範本嗎？ {#can-i-customize-templates}
+
+這就是重點。分叉一個範本並通過詢問代理來自訂它。 “向表單新增優先級欄位。” “連線到我們的 Salesforce 執行個體。” “更改配色方案以匹配我們的品牌。”代理修改程式碼，您的應用程式會隨著時間的推移而發展。
+
+### 我可以建置範本未涵蓋的內容嗎？ {#build-from-scratch}
+
+是的。如果你想要一個基本的聊天應用程式，請執行`npx @agent-native/core@latest create my-chat-app --template chat`；您可以獲得持久的聊天線程、actions、驗證、SQL 支持的執行時狀態以及新增您自己的螢幕的空間。如果您想要沒有 UI 的最小操作優先應用程式，請執行 `npx @agent-native/core@latest create my-agent --headless`。請參閱 [Getting Started](/docs/getting-started)、[Pure-Agent Apps](/docs/pure-agent-apps) 和 [Chat](/docs/template-chat)。
+
+### 我可以在不分叉範本的情況下嘗試它嗎？ {#try-with-a-skill}
+
+是的——通過一個指令將一項技能安裝到您已經使用的編碼代理中，不需要腳手架。請參閱 [Skills Guide](/docs/skills-guide#app-backed-skills) 了解演練。
+
+## 代理能力 {#agent-capabilities}
+
+### 代理真的可以修改應用程式自己的程式碼嗎？ {#can-the-agent-modify-code}
+
+是的，這是一個功能。代理可以安全地編輯元件、路線、樣式和 actions。您要求“新增群組分析圖表”，代理就會建置它。您詢問“連線到我們的 Stripe 帳戶”，然後代理會編寫整合。一切都是正常的 Git 跟蹤程式碼，因此不良更改很容易恢復。
+
+### 使用者可以從應用程式外部與代理交談嗎？ {#external-channels}
+
+是的。相同的代理在您的網路 UI、Slack、Telegram、通過電子郵件以及其他代理（通過 [A2A](/docs/a2a-protocol)）中執行。這是同一個特工，具有相同的內存和相同的 actions，只是通過不同的渠道到達。參見[Messaging the agent](/docs/messaging)。
+
+### 代理可以互相交談嗎？ {#can-agents-talk-to-each-other}
+
+是的，通過 [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol)。每個代理本機應用程式都會自動獲取 A2A 端點。從郵件應用程式中，您可以標記分析代理以查詢資料。代理發現其他可用代理，通過協議調用它們，並在 UI 中顯示結果。無需設定 - 代理卡是根據範本的 actions 自動生成的。
+
+### 客服人員可以在應用程式中看到什么？ {#what-can-the-agent-see}
+
+代理始終知道使用者目前正在檢視的內容。 UI 在每次路線更改時將導覽狀態寫入資料庫 - 開啟哪個視圖、選取哪個專案。代理在采取行動之前會閱讀此內容。如果電子郵件已開啟，代理就知道是哪封電子郵件。如果選取了一張幻燈片，代理就知道是哪張幻燈片。參見[Context Awareness](/docs/context-awareness)。
+
+## 開發問題 {#development}
+
+### 哪些人工智能編碼工具可與代理原生配合使用？ {#which-ai-tools-work}
+
+任何讀取專案指令的人工智能編碼工具。該框架使用 AGENTS.md 作為通用標準，並自動為特定工具建立符號連結：
+
+- **Claude 程式碼** — 讀取 CLAUDE.md（通過 CLI 設定從 AGENTS.md 進行符號連結）
+- **光標** - 直接讀取 AGENTS.md，或者如果專案中存在 `.cursorrules`（光標的舊位置）
+- **Windsurf** — 讀取 .windsurfrules（通過 CLI 設定從 AGENTS.md 進行符號連結）
+- **Codex、Gemini 等** — 通過嵌入式代理面板工作
+- **Builder.io** — 具有可視化編輯和協作功能的雲端託管代理
+
+### 我可以使用自己的資料庫嗎？ {#can-i-use-my-own-database}
+
+是的。設定 `DATABASE_URL` ，框架會自動檢測它。支持的資料庫包括 SQLite、Postgres（Neon、Supabase、plain）、Turso (libSQL) 和 Cloudflare D1。所有 SQL 通過 Drizzle ORM 都是與方言無關的 - 相同的程式碼在任何地方都可以工作。
+
+### 我可以在哪裡部署？ {#where-can-i-deploy}
+
+任何地方。伺服器在 Nitro 上執行，可編譯為任何部署目標：Node.js、Cloudflare Workers/Pages、Netlify、Vercel、Deno Deploy、AWS Lambda 和 Bun。您還可以使用 Builder.io 的託管進行託管部署。請參閱 [Deployment guide](/docs/deployment)。
+
+## 架構 {#architecture}
+
+### 為什么是 SSE 加輪詢而不是 WebSocket？ {#why-polling-not-websockets}
+
+SSE 為同進程寫入提供了到瀏覽器的直接路徑，而輕量級版本計數器輪詢仍然是後備方案，因為它適用於每個部署環境 - 包括無伺服器和邊缘，其中持久套接字可能不可用。參見[Key Concepts — 實時同步](/docs/key-concepts#polling-sync)。
+
+```an-diagram title="SSE 首先，輪詢後備" summary="同進程即時寫流；版本計數器輪詢使無伺服器、邊缘和跨進程寫入保持收斂。"
+{
+  "html": "<div class=\"diagram-transport\"><div class=\"diagram-box\" data-rough>資料庫寫入</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">SSE<br><small class=\"diagram-muted\">/_agent-native/events &middot; instant</small></div><div class=\"diagram-node\">輪詢<br><small class=\"diagram-muted\">/_agent-native/poll &middot; universal fallback</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>瀏覽器重新獲取</div></div>",
+  "css": ".diagram-transport{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-transport .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-transport .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+### 為什么UI不能直接調用LLM？ {#why-no-inline-llm-calls}
+
+人工智能是非確定性的，因此您需要對話流來提供意見回饋和迭代 - 而不是一次性按鈕 - 並且代理已經擁有內聯調用所缺乏的程式碼庫、指令、skills 和歷史紀錄。通過代理路由所有內容還可以讓應用程式從 Slack、Telegram 或其他代理驅動。參見[Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge)。
+
+### 為什么這是一個框架而不是一個庫？ {#why-framework-not-library}
+
+共用資料庫、實時同步、actions 系統和應用程式狀態之所以有效，是因為它們從頭開始連線在一起 - UI 立即對代理更改做出反應，代理進行通信，並且代理了解使用者正在檢視的內容。圖書館為你提供作品；這是一個架構。參見[Key Concepts](/docs/key-concepts)。

package/docs/content/locales/zh-TW/file-uploads.md

@@ -0,0 +1,122 @@
+---
+title: "檔案上傳"
+description: "設定檔案上傳存儲 - 用於開發的 SQL 後備、Builder.io 或用於正式環境的自訂提供程序。"
+---
+
+# 檔案上傳
+
+該框架提供了一個檔案上傳抽象，可通過可設定的提供程序路由上傳。範本調用 `uploadFile()` 並返回 URL — 存儲後端可交換，無需更改應用程式程式碼。
+
+## 它是如何工作的 {#how-it-works}
+
+上傳請求發送至 `POST /_agent-native/file-upload`，後者分派至活動提供者。您可以在`GET /_agent-native/file-upload/status`處檢視設定了哪個提供者。
+
+提供者解析順序是：
+
+1. **使用者註冊的提供程序** — 通過 `registerFileUploadProvider()` 註冊的自訂提供程序
+2. **Builder.io 提供程序** — 內置，連線 Builder.io 時自動激活
+3. **SQL 後備** - 將檔案作為 base64 存儲在資料庫中（適合開發，不適用於正式環境）
+
+```an-diagram title="提供者決議順序" summary="uploadFile() 按順序選取第一個設定的提供程序。 SQL 後備始終存在，因此上傳可以零設定進行。"
+{
+  "html": "<div class=\"diagram-upload\"><div class=\"diagram-box\" data-rough>uploadFile()<br><small class=\"diagram-muted\">POST /_agent-native/file-upload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-step\"><span class=\"diagram-pill accent\">1</span><div class=\"diagram-node\">使用者註冊<br><small class=\"diagram-muted\">registerFileUploadProvider() — S3, R2, GCS…</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><div class=\"diagram-node\">Builder.io<br><small class=\"diagram-muted\">連線後自動啟用——由 CDN 提供</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill warn\">3</span><div class=\"diagram-node\">SQL 兜底<br><small class=\"diagram-muted\">資料庫中的 base64——僅開發使用</small></div></div></div></div>",
+  "css": ".diagram-upload{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-upload .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-upload .diagram-step{display:flex;align-items:center;gap:8px}.diagram-upload .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="上傳端點" method="POST" path="/_agent-native/file-upload"
+{
+  "method": "POST",
+  "path": "/_agent-native/file-upload",
+  "summary": "通過活動提供者上傳檔案並返回公開URL。",
+  "description": "Dispatches to the first configured provider in resolution order. Check the active provider at `GET /_agent-native/file-upload/status`.",
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "{ url, id?, provider } — the public URL and which provider handled it." }
+  ]
+}
+```
+
+## 預設：SQL 後備 {#sql-fallback}
+
+當沒有設定提供者時，檔案通過資源系統以base64資料存儲在SQL資料庫中。這對於本機開發來說是開箱即用的，但不建議用於正式環境——大檔案會使資料庫膨脹，而且沒有 CDN。
+
+使用後備時會紀錄一次性警告。
+
+## Builder.io 託管 {#builder-hosting}
+
+當您的應用連線到 Builder.io 時，檔案上傳會自動路由到 Builder 的資產託管。檔案由 CDN 提供，無需設定。這是推薦的正式環境設定。
+
+## 自訂提供者 {#custom-providers}
+
+在伺服器外掛中註冊自訂提供程序以使用任何存儲後端（S3、Cloudflare R2、GCS 等）：
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## 上傳API {#upload-api}
+
+`FileUploadProvider`介面：
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+在 actions 或伺服器程式碼中使用 `@agent-native/core/file-upload` 中的 `uploadFile()`：
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL 兜底 yourself, or skip
+}
+```

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

@@ -0,0 +1,153 @@
+---
+title: "框架"
+description: "本機開發框架、嵌入式代理面板和雲端框架 - AI 代理與您的應用程式一起執行的方式。"
+---
+
+# 框架
+
+每個代理本機應用程式都與應用程式 UI 旁邊的 AI 代理一起執行。 **框架**是
+承載兩者的包裝器：它顯示您的應用程式並為代理提供一個地方
+聊天、執行和（在開發中）編輯程式碼。一共有三個框架，共用一個執行時：
+
+- **嵌入式代理面板** - 內置於 `@agent-native/core` 的每個應用程式中。
+  這是您的應用在開發和正式環境過程中自行呈現的側邊欄。
+- **本機開發框架** - 在 iframe 中載入正在執行的應用程式的薄包裝器
+  並新增相同的代理面板以及旁邊的整合 CLI 終端。使用過
+  用於此儲存庫中範本的本機開發。
+- **Builder.io 雲端框架** — 具有協作功能的託管託管框架，
+  可視化編輯，並行代理執行。
+
+無論託管哪個框架，您的應用程式碼都是相同的。代理說話
+在每種情況下都通過相同的 actions 和應用程式狀態連線到您的應用程式。
+
+```an-diagram title="三幀，一個執行時間" summary="您的應用程式和代理面板在每一幀中都是相同的；只有它們週圍的包裝發生變化。"
+{
+  "html": "<div class=\"diagram-frames\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">嵌入面板</span><small class=\"diagram-muted\">隨每個應用提供 · 開發 + 正式環境</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">本機開發框架</span><small class=\"diagram-muted\">iframe 中的應用 + 面板 + CLI 終端</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Builder.io 雲端框架</span><small class=\"diagram-muted\">託管：協作 · 可視編輯 · 並行執行</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>同一 runtime<br><small class=\"diagram-muted\">你的應用 · 操作 · 應用狀態</small></div></div>",
+  "css": ".diagram-frames{display:flex;flex-direction:column;gap:10px;align-items:stretch}.diagram-frames .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-frames .diagram-arrow{font-size:22px;line-height:1;align-self:center}"
+}
+```
+
+## 嵌入式代理面板 {#embedded-agent}
+
+嵌入式面板是您的應用程式呈現的代理側邊欄。它附帶
+`@agent-native/core` - 沒有單獨的軟件包需要安裝 - 並且是相同的
+開發和正式環境中的元件。
+
+- 從 `@agent-native/core/client` 匯出為 `AgentPanel`，帶有
+  僅限正式環境的變體 `ProductionAgentPanel`。
+- 提供完整的聊天/CLI/工作空間介面，因此座席輸入保持開啟
+  框架中其他地方使用的共用 撰寫r 堆堆疊。
+- 每回合都會讀取 `application_state.navigation`，因此它已經知道是哪個
+  檢視您所在的位置以及選取的內容 - 您無需重新解釋“此”。
+
+### 應用程式與程式碼工具模式 {#tool-modes}
+
+面板以兩種工具模式之一執行：
+
+- **應用程式模式** - 代理只有您的應用程式自己的工具：您的 actions
+  使用 `defineAction` 定義，加上導覽和上下文。沒有檔案系統或
+  外殼存取。這就是最終使用者得到的。
+- **程式碼模式** — 新增共用編碼工具（`bash`、`read`、`edit`、`write`）
+  以及應用程式工具之上的資料庫存取，因此代理可以更改應用程式的
+  自己的來源。程式碼請求被門控：當訊息需要程式碼時
+  (`type: "code"`)並且沒有連線支持程式碼的框架，面板顯示
+  解釋程式碼更改需要 Agent Native Desktop 或 Builder 的對話框；
+  當連線框架時，請求將路由到它和程式碼代理
+  工作時指示燈顯示 (`useSendToAgentChat`)。對於規範
+  編碼工具列表和共用UI合約，參見
+  [Agent-Native Code UI](/docs/code-agents-ui).
+
+```an-diagram title="程式碼請求門控" summary="程式碼型別訊息需要支持程式碼的幀。一旦連線，請求就會路由到那裡；如果沒有，面板會解釋程式碼更改需要 Desktop 或 Builder。"
+{
+  "html": "<div class=\"diagram-gate\"><div class=\"diagram-node\" data-rough>message<br><small class=\"diagram-muted\">type: \\\"code\\\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>code-capable frame connected?</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">yes &rarr; route to frame, show code-agent indicator</div><div class=\"diagram-pill warn\">no &rarr; dialog: needs Desktop or Builder</div></div></div>",
+  "css": ".diagram-gate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-gate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-gate .diagram-arrow{font-size:22px;line-height:1}.diagram-gate .center{text-align:center}"
+}
+```
+
+“程式碼模式”是代理功能切換 - 與環境開發模式不同
+（`NODE_ENV` / Vite）。用戶端鉤子是`useCodeMode()`。 （參見
+[Compatibility notes](#compatibility) 用於向後兼容別名。）
+
+在本機開發框架中，設定齒輪在這些模式之間切換。切換
+關閉程式碼模式隱藏框架自己的側邊欄並顯示應用程式的應用內代理
+側邊欄位於 iframe 內，因此您可以準確預覽最終使用者所看到的內容。
+
+## 整合終端和CLI切換 {#cli-terminal}
+
+正在開發中，面板包括一個嵌入式終端（`AgentTerminal`，也
+來自 `@agent-native/core/client`），由 PTY 伺服器支持。你可以執行一個真正的
+在應用程式旁邊編碼 CLI 並在它們之間切換；終端重新啟動
+與選定的 CLI。
+
+支持的 CLI 來自核心 CLI 註冊表
+(`packages/core/src/terminal/cli-registry.ts`)。僅允許這些指令
+生成 - PTY 伺服器根據註冊表驗證請求的指令
+允許列表以防止注入：
+
+| CLI          | 指令       | 安裝包                      |
+| ------------ | ---------- | --------------------------- |
+| Claude程式碼 | `claude`   | `@anthropic-ai/claude-code` |
+| Builder.io   | `builder`  | （內置）                    |
+| Codex        | `codex`    | `@openai/codex`             |
+| 雙子座CLI    | `gemini`   | `@google/gemini-cli`        |
+| 開放程式碼   | `opencode` | `opencode-ai`               |
+
+如果在 `PATH` 上找不到所選的 CLI，終端將回退到執行它
+通過 `npx --yes <install-package>@latest`（存在安裝包的地方）。
+預設指令是`claude`。隨時從代理面板設定切換 CLI
+時間。
+
+## Builder.io雲端框 {#cloud-frame}
+
+[Builder.io](https://www.builder.io) 提供託管框架
+相同的應用程式和相同的代理面板，在雲端端：
+
+- 實時協作 - 多個使用者可以同時觀看和互動。
+- 可視化編輯、角色和權限。
+- 並行代理執行以加快迭代速度。
+- 適合團隊使用，每個人共用一個託管環境。
+
+來自嵌入式面板的程式碼請求以相同的方式路由到 Builder 框架
+它們路由到本機開發框架，因此上面的 dev-vs-prod 行為是
+兩者一致。
+
+## 執行時 APIs {#runtime-apis}
+
+這些隨 `@agent-native/core` 一起提供，是您的應用用來與
+代理，無論哪個框架託管它：
+
+1. **發送訊息** — `sendToAgentChat()` 向代理發送訊息。
+   `useSendToAgentChat()` 鉤子用描述的程式碼請求門控包裝它
+   並返回一個 `codeRequiredDialog` 元素進行渲染。參見
+   [Drop-in Agent](/docs/drop-in-agent) 的完整用法和選項。
+2. **生成狀態** - `useAgentChatGenerating()` 跟蹤代理何時
+   正在執行，因此 UI 可以顯示進度，而無需直接輪詢代理。
+3. **輪詢同步** - 資料庫支持的同步在代理時保持 UI 快取最新
+   更改資料或應用程式狀態。
+4. **操作系統** - `pnpm action <name>` 分派到相同的可調用
+   actions 代理作為工具調用，因此代理能做的任何事情，您都可以
+   腳本。
+
+## 執行它 {#running}
+
+嵌入式代理面板是每個應用程式的一部分 - 搭建一個範本，它是
+已經在那裡：
+
+```bash
+npx @agent-native/core@latest create my-app --template mail --standalone
+cd my-app
+pnpm dev
+```
+
+本機開發框架（框架儲存庫中的私人 `@agent-native/frame` 包）是未發布到 npm 的內部工具包。它將活動應用程式的開發伺服器載入到 iframe 中，並在其旁邊安裝嵌入式面板，通過 `app` 查詢參數選取應用程式。整合CLI終端需要Agent Native Desktop，提供終端所需的本機程式碼和PTY存取；如果沒有它，面板將顯示聊天介面並提示您開啟桌面以使用 CLI。
+
+## 兼容性說明 {#compatibility}
+
+“程式碼模式”概念以前被稱為“開發模式”，因此有一些向後兼容
+名稱仍然存在。您可以忽略這些，除非您正在維護舊的整合
+程式碼：
+
+- 底層 `AGENT_MODE` 環境變數，`/_agent-native/agent-chat/mode`
+  端點（其負載金鑰仍然是`devMode`），以及`agent-chat.mode`
+  設定鍵未更改。
+- `useDevMode()` 仍然是 `useCodeMode()` 的已棄用別名。

package/docs/content/locales/zh-TW/getting-started.md

@@ -0,0 +1,199 @@
+---
+title: "開始使用"
+description: "建立代理應用，了解說明、skills 和 actions，然後觀看代理調用其第一個操作。"
+---
+
+# 開始使用
+
+Agent-Native 應用程式為 AI 代理和您的 UI 提供相同的 actions、資料和
+狀態。基本代理是由指導它的指令（skills 進行教學）組成的
+可重複的行為，以及讓它做實際工作的 actions。
+
+**想要一個完整的應用程式開始嗎？**克隆我們丰富的範本之一 -
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics) 和 [many more](/docs/cloneable-saas) —
+每個都是您自訂的全功能應用程式。
+
+從頭開始建置？唯一的選取是您是否想要 UI —
+之後的一切（編寫指令、新增 skills、定義 actions、執行
+代理）無論哪種方式都是相同的。
+
+```an-file-tree title="一個基礎 Agent-Native 代理"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "始終生效的指令：目的、規則、語氣以及代理能力地圖" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "工作匹配時代理會載入的可複用 playbook" },
+    { "path": "actions/summarize-week.ts", "note": "代理、UI、CLI、HTTP、MCP、A2A、jobs 和 webhooks 都能執行的型別化程式碼" }
+  ]
+}
+```
+
+無論您是從聊天 UI、無頭代理還是完整應用程式開始，都是如此。
+UI改變表面；指令、skills 和 actions 為代理提供
+指導和行為。
+
+## 1。建立您的應用
+
+您需要 [Node.js 22+](https://nodejs.org) 和 [pnpm](https://pnpm.io)。
+
+在沒有標志的情況下執行 `create`，它會詢問您要如何開始（完整的範本，
+聊天，或無頭）先於其他：
+
+```bash
+npx @agent-native/core@latest create my-app
+```
+
+或者傳遞一個標志來跳過提示：
+
+**想要 UI？** 從聊天範本開始。您將獲得一名工作代理人以及
+可自訂的聊天UI，您新增的每個操作都會自動顯示在其中：
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**只是無頭原語？**開始無頭 - 相同的 actions 和代理
+循環，無 UI shell：
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+然後從您建立的資料夾安裝：
+
+```bash
+cd my-agent # 或 my-app（如果您選取聊天範本）
+pnpm install
+```
+
+從現在開始，兩者是相同的。
+
+## 2。新增操作
+
+操作是您的代理（以及您的 UI）可以調用的一項操作。兩個腳手架
+附帶此範例：
+
+```an-annotated-code title="你的第一個 action"
+{
+  "filename": "actions/hello.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"從本機代理問好。\",\n  schema: z.object({\n    name: z.string().default(\"world\"),\n  }),\n  http: { method: \"GET\" },\n  readOnly: true,\n  run: async ({ name }) => {\n    return { message: `Hello, ${name}!` };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "工具描述", "note": "代理會讀取 `description`，判斷何時把它作為工具調用。" },
+    { "lines": "6-8", "label": "型別化契約", "note": "一個 zod `schema` 會校驗來自每個入口的輸入：代理、UI、HTTP、MCP 和 A2A。" },
+    { "lines": "9", "label": "HTTP 動詞", "note": "將此操作接入自動掛載的 HTTP 端點。" },
+    { "lines": "10", "label": "唯讀", "note": "`readOnly` 表示該操作無需批準即可安全調用，並且可作為查詢快取。" },
+    { "lines": "11-13", "label": "單一實現", "note": "`run` 主體是所有介面都會執行的唯一真實來源。" }
+  ]
+}
+```
+
+將 `hello` 替換為您域中的第一個實際操作。您定義一次；
+每個表面都會吸收它。
+
+使用 `AGENTS.md` 作為每回合都適用的指導。使用技能時
+代理需要可重用的工作流程或域過程。在以下情況下使用操作
+代理需要一種型別化、可測試的方式來讀取資料、寫入資料、調用 API 或
+執行批準。
+
+## 3。執行它
+
+直接調用操作：
+
+```bash
+pnpm action hello --name Steve
+```
+
+或請代理為您致電：
+
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
+
+如果您從聊天範本開始，請執行該應用並在
+瀏覽器 - 它已經可以調用您定義的每個操作：
+
+```bash
+pnpm dev
+```
+
+現在可以通過聊天 UI、CLI、HTTP、MCP、A2A 存取該操作
+計畫作業和 webhooks。定義一次，從任何地方調用。
+
+```an-diagram title="一個動作，每個表面" summary="單個 defineAction 檔案扇出到每個消費者，無需額外接線。"
+{
+  "html": "<div class=\"diagram-fan\"><div class=\"diagram-box\" data-rough>defineAction</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-surfaces\"><span class=\"diagram-pill\">聊天介面</span><span class=\"diagram-pill\">CLI</span><span class=\"diagram-pill\">HTTP</span><span class=\"diagram-pill\">MCP</span><span class=\"diagram-pill\">A2A</span><span class=\"diagram-pill\">計畫工作</span><span class=\"diagram-pill\">Webhooks</span></div></div>",
+  "css": ".diagram-fan{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fan .diagram-surfaces{display:flex;flex-wrap:wrap;gap:8px;max-width:420px}.diagram-fan .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 狀態是內置的
+
+無頭並不意味著無狀態。 Actions，工作階段，應用程式狀態，線程，
+執行歷史紀錄和憑證均位於 SQL 中。本機地址為 SQLite
+`data/app.db`；在正式環境中您設定 `DATABASE_URL`。請參閱
+[Deployment](/docs/deployment).
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Headless 仍然是一個真正的應用程式。**應用程式代理循環在 SQL 中保留工作階段、線程、執行、設定和憑證 - 它不是無狀態提示。您可以稍後新增 UI，而無需更改操作或狀態。"
+}
+```
+
+## 自訂UI
+
+如果您從聊天範本開始，則可以編輯 UI。聊天本身
+是基於 `<AgentChatSurface>` 元件建置的一條小路線：
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
+```
+
+- **`app/routes/_index.tsx`** — 聊天頁面。更改建議，空
+  狀態和布局。
+- **`app/root.tsx`** — 應用程式外殼。在週圍新增您自己的路線和螢幕
+  代理。
+- 使用 `<AgentSidebar>` 將代理放入任何螢幕，從 a 手動操作它
+  使用 `sendToAgentChat()` 按鈕，或直接使用
+  `useActionMutation()`.
+
+請參閱 [Drop-in Agent](/docs/drop-in-agent) 了解完整的元件集，並且
+[Native 聊天介面](/docs/native-chat-ui) 將操作結果呈現為表格，
+圖表和打字卡片而不是純文本。
+
+**開始無頭，稍後想要 UI？** 聊天範本*是* UI 入口 -
+它的`app/`層（React Router + Vite）正是無頭腳手架
+省略。最幹淨的舉動是從聊天開始（或重新搭建支架）
+範本；您的 `actions/`、代理和 SQL 狀態保持不變。請參閱
+[Agent Surfaces](/docs/agent-surfaces) 代表其間的每個表面。
+
+## 專案結構
+
+```text
+my-app/
+  actions/         # 代理可調用的操作
+  app/             # React 前端（僅 UI 範本；無頭模式會省略）
+  server/          # Nitro API 伺服器（路由、外掛）
+  AGENTS.md        # 始終生效的代理指令
+  .agents/         # 代理可按需引入的技能
+  data/app.db      # 未設定 DATABASE_URL 時的本機 SQLite 狀態
+```
+
+## 下一步去哪裡
+
+- **[Key Concepts](/docs/key-concepts)** — 核心架構：SQL、actions，
+  同步和上下文感知。
+- **[Actions](/docs/actions)** — 完整操作 API：架構、HTTP、驗證和
+  批準。
+- **[Agent Surfaces](/docs/agent-surfaces)** — 無頭、聊天、嵌入式 sidecar，
+  和完整的應用程式。
+- **[Drop-in Agent](/docs/drop-in-agent)** — 將代理聊天新增到任何 React 應用程式。
+- **[Deployment](/docs/deployment)** — 將您的應用放在您自己的域中。
+- **[FAQ](/docs/faq)** — 設定和產品問題。