@agent-native/core 0.79.1 → 0.79.5

package/docs/content/locales/zh-TW/cloneable-saas.md

@@ -0,0 +1,114 @@
+---
+title: "範本"
+description: "分叉一個可用的 SaaS 產品並使其成為您的產品 - 包括代理。"
+---
+
+# 範本
+
+想要發布您自己的人工智能分析工具嗎？郵件用戶端？表格生成器？選取一個範本，您只需幾分鐘即可獲得一個可執行的 SaaS — 代理、資料庫、驗證和部署管道已連線完畢。
+
+大多數“範本”都會為您提供一個空白的腳手架和一個很長的 TODO 列表。代理本機翻轉了這一點。每一個都是**完整的 SaaS 級產品** - 在第一天就已經可以執行，已經可以發貨，並且完全由您來定制、品牌化和部署。將它們視為可克隆的 SaaS，而不是入門工具包：您正在分叉成品，而不是盯著樣板檔案。
+
+## 可用範本 {#catalog}
+
+每一個都是您今天可以使用的真實應用程式，以及您自己版本的啟動板。
+
+| 範本                                      | 它是什么                                                                                      |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------- |
+| [**Chat**](/docs/template-chat)           | 最小的聊天優先應用程式，具有持久線程、actions、驗證以及通往自訂 UI 或您自己的後端的幹淨路徑。 |
+| [**Mail**](/docs/template-mail)           | 特工本機超人。收件箱、標籤、人工智能分類、鍵盤優先、通過代理起草和發送。                      |
+| [**Calendar**](/docs/template-calendar)   | 本機代理 Google Calendar。活動、同步、公開預訂連結、代理驅動的調度。                          |
+| [**Content**](/docs/template-content)     | MDX 的開來源黑曜石。本機Markdown/MDX、Tiptap編輯器、Notion同步、實時多使用者協作。            |
+| [**Brain**](/docs/template-brain)         | 幹淨的公司聊天由引用的機構記憶、批準的來源、審查門和引文支持。                                |
+| [**Assets**](/docs/template-assets)       | 用於品牌庫、上傳、參考和品牌圖片/影片生成的數字資產管理器。                                   |
+| [**Slides**](/docs/template-slides)       | 代理原生 Google 幻燈片。基於React的套牌由代理直接生成和編輯。                                 |
+| [**Video**](/docs/template-videos)        | Remotion 上的程序化動態圖形和產品演示影片。                                                   |
+| [**Analytics**](/docs/template-analytics) | 代理本機振幅/混合面板。連線資料來源、提示圖表、固定到儀表板。                                 |
+| [**Clips**](/docs/template-clips)         | 非同步螢幕+攝像頭錄製，包含轉錄、章節和 AI 摘要。                                             |
+| [**Design**](/docs/template-design)       | Agent 原生 HTML 原型工作室，用於互動式 Alpine/Tailwind 設計。                                 |
+| [**Forms**](/docs/template-forms)         | 代理原生 Typeform。建置、共用、收集提交內容並將其路由到 Slack、表格、webhooks 或 Discord。    |
+| [**Plan**](/docs/template-plan)           | 帶有圖表、線框圖和注釋的視覺計畫和公關概述。                                                  |
+| [**Dispatch**](/docs/template-dispatch)   | 工作區控制平面：共用秘密、可重用整合、Slack/Telegram、計畫作業。                              |
+
+不需要域範本？當您想要一個使用者可以立即交談的基本應用程式時，請使用 [Chat](/docs/template-chat)，或者使用 [Pure-Agent Apps](/docs/pure-agent-apps) 首先開始操作。
+
+檢視 [Templates](/templates) 下的完整目錄，或直接跳到其中一個 - 例如，如果您想要一款工作區風格的應用，[Dispatch](/docs/template-dispatch) 是一個很好的起點。
+
+## 開箱即用的東西 {#what-you-get}
+
+每個範本都附帶通常需要數月才能建置的部件：
+
+- **工作代理** — 已經連線到應用程式，已經能夠在您的資料上獲取 actions，已經能夠了解您正在檢視的內容。請參閱 [Messaging the agent](/docs/messaging) 了解其工作原理。
+- **Auth** — 登入、工作階段、組織、多租戶隔離。已經完成了。
+- **資料庫** — 每個範本都有其架構、查詢和遷移準備就緒。帶上您自己的 SQL 資料庫（Postgres、SQLite、Turso、D1）——框架會進行調整。
+- **實時 UI** — 螢幕與代理的操作保持同步。在聊天中點擊“草稿電子郵件”，草稿立即出現在您的收件箱中。
+- **部署就緒** — 推送到 Netlify、Vercel、Cloudflare、AWS 或執行 Node.js 的任何其他地方。沒有供應商鎖定。
+- **品牌掛鉤** - 名稱、顏色、徽標、文案都很容易更改。
+
+這不是理論上的主張。該框架的作者在郵件範本上執行他的實際收件箱，在行事曆範本上執行他的實際行事曆，在分析範本上執行他的實際分析。範本是日常驅動軟件。
+
+## 你做什么 {#what-you-do}
+
+從“我想要自己的 SaaS”到“我擁有自己的 SaaS”的路徑很短：
+
+```an-diagram title="分叉並定制" summary="選取一個成品，對其進行品牌化，用簡單的英語對其進行改進，然後將其發送到您自己的域。"
+{
+  "html": "<div class=\"diagram-fork\"><div class=\"diagram-card\"><span class=\"diagram-pill\">1</span><strong>Pick</strong><small class=\"diagram-muted\">a complete template</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2</span><strong>Brand</strong><small class=\"diagram-muted\">名稱、顏色、Logo、文案</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">3</span><strong>Customize</strong><small class=\"diagram-muted\">ask the agent &#8635;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">4</span><strong>Ship</strong><small class=\"diagram-muted\">your own domain</small></div></div>",
+  "css": ".diagram-fork{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-fork .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:130px}.diagram-fork .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **選取一個範本。**使用 CLI 選取器，或瀏覽檔案並選取一個開始。
+2. **打造品牌。**更改名稱、顏色、徽標和文案。大多數範本都將其公開在單個設定檔案中。
+3. **自訂它。** 要求代理新增您需要的列，更改收件箱分組的方式，連線到您的內部 API，新增新視圖。代理編輯程式碼；您檢視差異。
+4. **發貨。**執行部署指令。您現在在自己的域中擁有自己的正式環境 SaaS。
+
+步驟 2-4 通常需要幾天而不是幾個月的時間。第 3 步是開放式的 - 通過與代理交談，用簡單的英語來說，您的分叉 SaaS 會隨著時間的推移而發展。
+
+## 為什么這是實用的 {#why}
+
+傳統的程式碼庫分叉模型會大規模當機：每個使用者維護自己的收件箱听起來像是一場維護噩夢。兩個框架決策使其發揮作用：
+
+1. **代理進行維護。**您無需編寫程式碼來新增列或連線新的整合 - 您可以詢問代理。所以“你自己的分叉收件箱”是一個功能，而不是一個負擔。
+2. **每使用者自訂，無需每使用者程式碼。** Skills、內存、指令、連線的 MCP 伺服器和子代理都位於 SQL 中。每個使用者都有自己的定制層；共用程式碼庫同時託管所有這些內容。
+
+結果：Claude - 每個使用者的程式碼級靈活性，以及正常的 SaaS 部署經濟性。
+
+```an-diagram title="為什么每使用者分叉規模" summary="有兩個想法使分叉和定制模型保持實用：代理進行維護，每個使用者的定制位於 SQL 中，而不是每個使用者的程式碼中。"
+{
+  "html": "<div class=\"diagram-why\"><div class=\"diagram-panel\" data-rough><strong>分享d codebase</strong><small class=\"diagram-muted\">一個應用，一次部署</small><div class=\"diagram-pill accent\">agent does the maintenance</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-panel\" data-rough><strong>SQL 中的使用者層</strong><small class=\"diagram-muted\">skills · 記憶 · 指令 · MCP · 子代理</small><div class=\"diagram-pill ok\">no per-user code</div></div></div>",
+  "css": ".diagram-why{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-why .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px 18px;min-width:240px;flex:1}.diagram-why .diagram-arrow{font-size:24px;line-height:1}"
+}
+```
+
+## 不想分叉？ {#hosted}
+
+你不必這樣做。每個範本還可以作為 `agent-native.com` 上的託管應用程式使用 - `mail.agent-native.com`、`calendar.agent-native.com` 等。免費或付費使用託管版本；僅當您想要更改託管版本未公開的內容時才進行分叉。
+
+## 嘗試一下技巧 {#try-with-a-skill}
+
+還沒有準備好搭建腳手架嗎？您可以使用單個指令將代理本機超級功能新增到已使用的編碼代理中 - 無需應用程式。請參閱 [Skills Guide](/docs/skills-guide#app-backed-skills)。
+
+## 在此基礎上建置
+
+- [**Getting Started**](/docs/getting-started) - 建立一個最小的聊天應用程式或無頭代理
+- [**Messaging the agent**](/docs/messaging) - 使用者（和您）如何與每個範本附帶的代理對話
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — 將多個範本捆綁到一個共用驗證、品牌和代理的工作區
+- [**Dispatch**](/docs/template-dispatch) — 工作區控制平面範本
+- [**Creating Templates**](/docs/creating-templates) — 創作並發布您自己的範本
+
+### 對於開發者 {#dev-details}
+
+如果您現在正在搭建腳手架，則 CLI 指令為：
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+您將獲得一個多選選取器。選取一個應用程式（獨立）或多個應用程式（工作區 - 應用程式共用驗證、品牌、代理設定和資料庫）。每個挑選的範本都與您需要的每個檔案一起建置到 `apps/<name>/` 中。對於僅限操作的應用程式而不是範本 UI，請使用 `npx @agent-native/core@latest create my-agent --headless`。
+
+填寫`.env`（主要是`ANTHROPIC_API_KEY`和`DATABASE_URL`）、`pnpm install`、`pnpm dev`，就可以了。沒有“TODO：實現登入”，沒有預留位置路由。
+
+部署目標：任何 Nitro 兼容主機（Node、Cloudflare、Netlify、Vercel、Deno、Lambda、Bun）和任何 Drizzle 兼容 SQL 資料庫（SQLite、Postgres、Turso、D1、Supabase、Neon）。對於工作區，`npx @agent-native/core@latest deploy` 一次建置每個應用程式並將它們發送到單個來源。參見[Deployment](/docs/deployment)。
+
+要創作和發布您自己的範本，請參閱 [Creating Templates](/docs/creating-templates)。

package/docs/content/locales/zh-TW/code-agents-ui.md

@@ -0,0 +1,436 @@
+---
+title: "Agent-Native 程式碼 UI"
+description: "使用共用的 UI 包、桌面主機橋和 CLI 執行存儲建置和自訂 Agent-Native 程式碼表面。"
+---
+
+# Agent-Native 程式碼 UI
+
+> **這是誰的：** 建置或自訂編碼工作空間的主機作者
+> 共用程式碼 UI 包上的表面（CLI、桌面或瀏覽器範本）。
+
+## 我需要哪個編碼檔案？ {#which-doc}
+
+| 你想要……                                                 | 使用                                   |
+| -------------------------------------------------------- | -------------------------------------- |
+| 渲染 Claude-Code/Codex-style **編碼工作區 UI**           | **Agent-Native 程式碼 UI**（本頁面）   |
+| 使用自己的循環+工具**作為代理**執行Claude程式碼/Codex/Pi | [Harness Agents](/docs/harness-agents) |
+| 交換執行代理 **`run-code` 工具**的後端                   | [Adapters](/docs/sandbox-adapters)     |
+| 封裝一個CLI工具（`gh`、`ffmpeg`）供代理調用              | [Adapters](/docs/sandbox-adapters)     |
+
+Agent-Native Code 是 Agent-Native 編碼介面：本機 Claude Code/Codex 風格的工作區，用於編碼工作階段、斜線指令、遷移、審計、轉錄、執行控制和後續操作。一個簡單的 `npx @agent-native/core@latest` 指令可以開啟這個工作區； `npx @agent-native/core@latest code` 是相同體驗的顯式子指令。
+
+共有三層：
+
+- **CLI**：`npx @agent-native/core@latest` 和 `npx @agent-native/core@latest code` 啟動、恢復、檢查和停止執行。
+- **桌面**：左側邊欄“程式碼”分頁新增本機終端啟動、應用程式 Web 視圖和桌面深層連結，同時使用相同的執行模型。
+- **共用 UI**：`@agent-native/code-agents-ui` 渲染可重用的 React 表面。
+
+```an-diagram title="一間經營商店三層" summary="CLI、Desktop 和共用 UI 是同一檔案支持的執行存儲和執行器上的不同表面；主機通過 CodeAgentsHost 合約對其進行調整。"
+{
+  "html": "<div class=\"diagram-layers\"><div class=\"diagram-row\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">CLI</span><small class=\"diagram-muted\">啟動 · 恢復 · 狀態 · 停止</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Desktop</span><small class=\"diagram-muted\">原生終端 · webviews · 深連結</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">分享d UI</span><small class=\"diagram-muted\">@agent-native/code-agents-ui</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill\">CodeAgentsHost</span><small class=\"diagram-muted\">host contract</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>檔案支持的執行存儲 + 執行器<br><small class=\"diagram-muted\">@agent-native/core/code-agents</small></div></div>",
+  "css": ".diagram-layers{display:flex;flex-direction:column;gap:10px;align-items:center}.diagram-layers .diagram-row{display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.diagram-layers .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-layers .diagram-arrow{font-size:22px;line-height:1}.diagram-layers .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+目前的拆分是有意融合的：標準代理側邊欄和代理團隊在核心 `run-manager` 生命週期上執行，而 Agent-Native Code 使用由基於檔案的程式碼執行存儲和共用後台執行控制器詞匯表支持的本機長時間執行工作階段。
+
+共用的 UI 是主機驅動的。它不知道自己是在 Electron、瀏覽器範本還是未來的託管 shell 中執行。主機提供 `CodeAgentsHost` 實現。
+
+```ts
+import { CodeAgentsApp, type CodeAgentsHost } from "@agent-native/code-agents-ui";
+import "@agent-native/code-agents-ui/styles.css";
+
+const host: CodeAgentsHost = {
+  listRuns: (goalId) => listRunsSomehow(goalId),
+  listCodePacks: () => listCodePacksSomehow(),
+  createRun: (request) => createRunSomehow(request),
+  subscribeTranscript: (request, callback) =>
+    subscribeToTranscriptSomehow(request, callback),
+  readTranscript: (request) => readTranscriptSomehow(request),
+  appendFollowUp: (request) => appendFollowUpSomehow(request),
+  updateRun: (request) => updateRunSomehow(request),
+  retryRun: (request) => retryRunSomehow(request),
+  rerunRun: (request) => rerunRunSomehow(request),
+  controlRun: (goalId, runId, command, permissionMode) =>
+    controlRunSomehow({ goalId, runId, command, permissionMode }),
+};
+
+export function CodeSurface() {
+  return <CodeAgentsApp apps={[]} host={host} />;
+}
+```
+
+主機可以在同一列表中混合執行來源。本機 Agent-Native 程式碼工作階段
+可以出現在代理團隊或其他後台執行的適配器旁邊，只要每個適配器的長度相同
+條目標準化為`CodeAgentRun`。當主機提供`sourceLabel`時，
+`source`或`kind`，集線器呈現一個小的來源標籤，例如“本機程式碼”
+或執行列表和選定工作階段標題中的“代理團隊”。省略這些欄位
+對於單來源表面；空狀態和基本布局保持不變。
+
+## 桌面主機
+
+桌面使用共用的 UI 但保留 Electron 中的特權功能：
+
+- 開啟本機終端
+- 使用 `AppWebview` 渲染可選的應用程式支持的表面
+- 處理 `agentnative://open?...` 連結
+- 跟蹤本機執行進程
+- 紀錄主動執行的轉向與排隊後續操作
+- 重試並重新執行本機程式碼工作階段，包括 `/migrate` 和 `/audit`
+- 停止它啟動的進程
+
+分離很重要。 UI 可以被範本重用，但本機流程控制應保留在 Desktop 或 CLI 中。
+
+## Codex CLI 授權 {#codex-cli-auth}
+
+Agent-Native 程式碼可以使用本機 Codex CLI 登入名，而不是 OpenAI API 金鑰。
+在 `PATH` 上安裝 Codex CLI，登入一次，然後重新啟動 Desktop 或
+程式碼 UI（如果已開啟）：
+
+```bash
+npm install -g @openai/codex@latest
+codex login
+codex login status
+```
+
+桌面和 CLI 讀取 `codex login status` 並執行 `codex exec`，因此它們
+重用您安裝的 Codex CLI 的任何 ChatGPT 訂閱或 API 金鑰驗證
+報告。這與使用的 `@ai-sdk/harness-codex` 包是分開的
+[Harness Agents](/docs/harness-agents)；線束適配器可以複製本機
+僅當 `codexCliAuth: true` 為時，Codex CLI 才授權進入可信沙箱
+顯式啟用。
+
+## 瀏覽器主機
+
+舊的隱藏 `code` 範本已被刪除。要建置瀏覽器託管的程式碼表面，請建立一個普通應用程式並使用主機實現掛載共用 UI 包：
+
+```bash
+npx @agent-native/core@latest create my-code-ui --template chat
+cd my-code-ui
+pnpm add @agent-native/code-agents-ui
+pnpm install
+pnpm dev
+```
+
+您的主機可以通過正常的 actions 包裝本機執行存儲。這些是
+主機擁有的 actions 您可以自己定義 - 它們不是附帶的框架
+actions — 將每個 `CodeAgentsHost` 方法對應到執行存儲，例如：
+
+- 支持 `listRuns` 的“列表執行”操作
+- 支持 `listCodePacks` 的“列出程式碼包”操作
+- 支持 `createRun` 的“建立執行”操作
+- 支持 `readTranscript` 的“閱讀紀錄”操作
+- 支持 `appendFollowUp` 的“追加後續”操作
+- 支持 `updateRun` 的“更新執行”操作
+- 支持`controlRun`的“控制執行”動作
+
+每個都調用 `@agent-native/core/code-agents`，它公開相同的內容
+CLI 使用的檔案支持的執行存儲和執行器。
+
+## CLI 執行控件
+
+頂級 CLI 的行為類似於 Claude 程式碼或 Codex：
+
+```bash
+npx @agent-native/core@latest
+npx @agent-native/core@latest "fix the failing auth tests"
+npx @agent-native/core@latest code
+```
+
+當您需要顯式命名空間時，請使用 `npx @agent-native/core@latest code`。內置斜線
+目標和專案指令可以在互動式工作區中執行或直接執行
+來自外殼：
+
+```bash
+npx @agent-native/core@latest code /migrate ./legacy-app --emit ./migration-dossier
+npx @agent-native/core@latest code /audit --url https://example.com
+npx @agent-native/core@latest code /release-check
+```
+
+這裡`/migrate`和`/audit`是內置目標（內置目標是
+`task`、`migrate` 和 `audit`）。 `/release-check` 作為範例顯示
+專案指令 - 在 `.agents/commands/` 中定義，不是內置目標。專案
+指令來自`.agents/commands/*.md`；專案skills來自
+`.agents/skills/*/SKILL.md`。控制指令在同一執行中執行
+紀錄桌面程式碼分頁和共用UI顯示：
+
+```bash
+npx @agent-native/core@latest code list
+npx @agent-native/core@latest code status --last
+npx @agent-native/core@latest code attach --last
+npx @agent-native/core@latest code logs --last
+npx @agent-native/core@latest code resume --last
+npx @agent-native/core@latest code stop --last
+npx @agent-native/core@latest code ui
+```
+
+`resume` 附加上下文並繼續執行，`status` 報告最新執行
+狀態，`stop`要求主動控制器停止工作，`ui`開啟本機
+程式碼表面。這些是執行控制，而不是單獨的實施路徑。如果一個
+高風險指令暫停等待批準，`approve --last` 執行該指令
+指令，然後指示您返回以恢復工作階段。
+
+執行模式使每個工作階段的編輯策略變得明確：
+
+| 模式         | CLI 標志 | 行為                                                                      |
+| ------------ | -------- | ------------------------------------------------------------------------- |
+| **計畫模式** | `--plan` | 檢查、計畫和解釋，無需編寫檔案或執行突變。                                |
+| **自動模式** | `--auto` | 僅針對真正具有破壞性的檔案、git、發布或資料操作編輯檔案、執行檢查和暫停。 |
+
+自動模式是本機 Agent-Native 程式碼工作階段的預設模式。使用計畫模式用於
+評估、架構、審核或您之前需要提案的任何工作
+編輯。
+
+對於跨表面列表、儀表板或監控窗格，首選共用
+通過讀取程式碼從 `@agent-native/core/code-agents` 後台執行匯出
+直接執行檔案。他們將本機程式碼工作階段標準化為相同的詞匯表
+由託管後台工作使用：執行 ID、狀態、cwd、需求輸入，
+需求批準、轉錄事件和工件根。
+
+託管代理團隊也會從瀏覽器的代理聊天路由中公開
+需要程式碼中心兼容列表而不直接伺服器匯入的主機：
+`GET /_agent-native/agent-chat/runs/list?goalId=agent-team` 返回
+`{ status: "ok", goalId, runs }`，其中每次執行都包含 `kind`，
+`source`、`sourceLabel`、`status`、`title`、時間戳和工作元資料。
+`GET /_agent-native/agent-chat/runs/:id/background-events` 返回
+為代理團隊執行共用後台轉錄事件。
+
+適配器支持的主機還可以附加來源元資料：
+
+```ts
+{
+  id: run.id,
+  goalId: "task",
+  title: run.title,
+  source: "agent-teams",
+  sourceLabel: "Agent Teams",
+  kind: "background-run",
+  status: run.status,
+  createdAt: run.createdAt,
+  updatedAt: run.updatedAt,
+}
+```
+
+## 執行商店
+
+本機 Agent-Native 程式碼執行存儲在：
+
+```text
+~/.agent-native/code-agents
+```
+
+設定 `AGENT_NATIVE_CODE_AGENTS_HOME` 以隔離範本或測試執行存儲。
+
+```bash
+AGENT_NATIVE_CODE_AGENTS_HOME=./data/code-agents pnpm dev
+```
+
+## 主機合約
+
+`CodeAgentsHost` 故意很小：
+
+| 方法                                                  | 目的                                     |
+| ----------------------------------------------------- | ---------------------------------------- |
+| `listRuns(goalId?)`                                   | 列出所選目標的工作階段                   |
+| `listCodePacks?()`                                    | 列出`.agents/commands`和`.agents/skills` |
+| `createRun(request)`                                  | 開始新的執行                             |
+| `subscribeTranscript?(request, callback)`             | 將紀錄更新推送到共用對話                 |
+| `readTranscript(request)`                             | 輪詢紀錄事件作為兼容性回退               |
+| `appendFollowUp(request)`                             | 新增後續工作，引導活動工作或排隊         |
+| `updateRun(request)`                                  | 更新模式或執行元資料                     |
+| `retryRun?(request)`                                  | 就地重試所選執行                         |
+| `rerunRun?(request)`                                  | 從先前的提示開始新的執行                 |
+| `controlRun(goalId, runId, command, permissionMode?)` | 恢復、批準、刷新或停止                   |
+| `openTerminal?(request)`                              | 可選的本機終端掛鉤                       |
+
+瀏覽器主機應該返回一個正常的 `openTerminal` 錯誤，而不是嘗試模擬本機終端啟動。
+
+## 共用作曲家
+
+Agent-Native 程式碼使用相同的 `AgentComposerFrame` + `PromptComposer` /
+從 `@agent-native/core/client/composer` 匯出的 `TiptapComposer` 堆堆疊作為
+框架代理側邊欄。不要分叉單獨的
+文本區域、編碼工具選取器、上傳選取器、語音按鈕、模型選取器或 Enter-to-submit
+類似程式碼表面的實現。如果主機需要一個額外的控制，請傳遞
+它通過共用的composer擴充功能點，所以側邊欄，程式碼UI，和
+大腦聊天保持相同的互動模型和視野。
+
+Brain 的 Ask 路線使用 `AgentChatSurface`，該路線已得到支持
+標準側邊欄編輯器。程式碼直接使用`PromptComposer`，因為主機
+擁有執行建立、成績單和後續交付。
+
+## 共用編碼工具
+
+側邊欄開發代理和Agent-Native程式碼都使用相同的最小值
+編碼工具設定檔案：`bash`、`read`、`edit` 和 `write`。預設為`bash`
+用於列出/搜尋檔案、執行測試以及調用專案 CLIs； `read`
+顯示行編號的檔案切片； `edit` 應用精確的文本替換；和
+`write` 保留用於新檔案或有意完全重寫。舊別名
+例如`shell`、`read-file`、`write-file`、`list-files`和`search-files`
+僅兼容，不屬於預設廣告表面的一部分。
+
+特定於程式碼的 UI 屬於作曲家週圍，而不是分叉的聊天欄位內。
+共用程式碼 UI 可能會新增插槽：
+
+- 自動/計畫模式控件。
+- 選定的 cwd、專案選取器和執行元資料。
+- 僅限主機的功能，例如開啟終端。
+
+其他所有內容都保留在共用編輯器中：附件、引用、斜杠和
+技能插入、貼上文本處理、語音听寫、草稿、鍵盤
+快捷方式和提交語義。
+
+面向使用者的文字紀錄應保持工作階段式。程式碼主機標準化原始
+將轉錄/狀態/工具事件寫入共用對話渲染器：助手
+文本合並為一圈，低信號生命週期噪音遠離主線
+表面和工具活動呈現為帶有詳細資訊的緊湊內聯摘要
+需要時可用。
+
+## 斜線指令
+
+Agent-Native 程式碼將遷移視為一種功能，而不是單獨的應用程式類別。 `/migrate` 可以是內置目標、專案指令或同一主機合約之上的自訂指令包。
+
+### 使用`/migrate`遷移到Agent-Native {#migrate}
+
+`/migrate` 是將現有應用程式、URL 或描述的產品行動到 Agent-Native 的內置目標。它是程式碼工作區中的一個斜線目標 - 不是一個單獨的腳手架範本，也不是一次性產品 - 因此它與其他所有程式碼工作階段共用相同的工作階段存儲、腳本、執行控件和桌面中心，並且您可以以相同的方式恢復、附加、檢查和停止它。
+
+```bash
+npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
+npx @agent-native/core@latest code /migrate https://example.com --describe "marketing site plus dashboard"
+npx @agent-native/core@latest code /migrate --describe "A Rails admin app with reports and CSV imports" --emit
+npx @agent-native/core@latest migrate ./my-next-app --out ../migrated-app   # shortcut into the same goal
+```
+
+本機來源路徑是唯讀的；生成的輸出必須位於來源樹之外。使用 `--emit <dir>` 編寫便攜式遷移檔案（`AGENTS.md`、`MIGRATION_PLAYBOOK.md`、評估和 `ir.json` 庫存（如果可用））並將其交給另一個編碼代理，而不是開啟內部執行表面。 `/migrate` 重用框架的正常憑證系統 - 沒有特定於遷移的金鑰存儲。 `@agent-native/migrate` 包公開了一個用於自訂工作流程的可重用引擎（`createMigrationRun`、`discoverMigration`、`planMigration`、來源/目標適配器）。
+
+特定於專案的指令位於：
+
+```text
+.agents/commands/*.md
+```
+
+將它們用於團隊工作流程，例如版本檢查、遷移變體、框架升級或審核。
+
+專案 skills 位於：
+
+```text
+.agents/skills/*/SKILL.md
+```
+
+當主機實現`listCodePacks`時，共用的UI在導軌中顯示專案指令和skills。指令行插入 `/<command>`，技能行插入重點“使用 <skill> 技能...”提示，以便導軌保持可操作性。內置斜線目標 `/migrate` 和 `/audit` 保留為全域 Agent-Native 程式碼控件保留，執行控制名稱（例如 `status` 和 `resume`）也是如此 — 這些是不帶斜線調用的子指令（`npx @agent-native/core@latest code status`、`npx @agent-native/core@latest code resume`），而不是斜線目標。
+
+不要為新的程式碼主機建立單獨的斜杠指令註冊表。專案
+指令和skills是從`.agents/commands/*.md`發現的
+`.agents/skills/*/SKILL.md`； UI 應該渲染這些包並插入提示
+通過共用作曲家。
+
+## 後台代理執行管理器
+
+後台編碼代理工作應重用與執行管理器相同的基礎
+Agent-Native 的其餘部分：
+
+- 使用程式碼執行存儲/執行器進行本機程式碼工作階段。
+- 當表面需要列出時，使用共用後台執行適配器/基礎，
+  檢查或橋接本機程式碼工作階段以及其他後台工作。
+- 使用核心 `run-manager` 進行託管代理執行，以便進行流式傳輸、中止、心跳，
+  可恢復性、軟超時和卡住執行清理的行為一致。
+- 當 UI 將工作委派給 a 時使用 `agent-teams` / `spawnTask()`
+  來自普通應用聊天的後台子代理。
+
+不要僅僅因為新表面需要一個並行的後台代理執行程序
+不同的布局。在共用頂部建置主機適配器或 UI 插槽
+改為執行管理器基礎。
+
+## 後續行動
+
+主動執行的後續支持兩種交付模式：
+
+- 按 Enter 或點選發送會紀錄立即轉向提示
+  活躍跑步者在下一個安全繼續點申請。
+- 在 macOS 上按 Cmd+Enter 或在其他地方按 Ctrl+Enter 會將提示排隊執行
+  目前回合結束後。
+
+非活動執行保持兼容行為：追加後續操作並立即恢復執行。
+
+這為程式碼提供了與代理團隊相同的面向使用者的雙向訊息傳遞形式：
+使用者可以繼續與活動工作對話，但執行僅消耗該內容
+在安全繼續點的訊息。如果跑步者無法立即轉向，
+必須將後續工作保留為排隊工作，而不是丟棄或搶占它。
+
+## 遠端調度
+
+桌面可以將本機程式碼代理執行程序公開給已部署的調度中繼，因此
+電話或 Telegram 聊天可以啟動、監控和繼續工作階段，而
+計算機已喚醒。
+
+連線僅從桌面出站：
+
+1. 桌面與 Dispatch 配對並在本機存儲設備權杖。
+2. 桌面長輪詢 `/_agent-native/integrations/remote/poll`。
+3. 行動工作階段和 Telegram `/code` 在中繼資料庫中排隊指令。
+4. 桌面聲明指令、驅動本機執行存儲並發布結果
+   將事件紀錄回 Dispatch。
+5. 行動設備從 Dispatch 讀取 `hosts`、`runs` 和 `transcript`；它從不說話
+   直接到桌面。
+
+```an-diagram title="遠端 Dispatch 僅限出站" summary="行動設備從不直接與桌面對話。 Desktop 長輪詢 Dispatch，聲明指令，驅動本機執行存儲，並將結果鏡像回來。"
+{
+  "html": "<div class=\"diagram-remote\"><div class=\"diagram-node\" data-rough>行動端 / Telegram<br><small class=\"diagram-muted\">/code · 工作階段</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Dispatch 中繼<br><small class=\"diagram-muted\">主機 · 執行 · 轉錄</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div><div class=\"diagram-node\" data-rough>Desktop<br><small class=\"diagram-muted\">長輪詢 · 領取 · 驅動執行存儲</small></div></div>",
+  "css": ".diagram-remote{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-remote .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+規範的遠端中繼端點是：
+
+```an-api title="桌面聲明排隊的工作"
+{
+  "method": "POST",
+  "path": "/_agent-native/integrations/remote/poll",
+  "summary": "桌面長輪詢中繼以聲明排隊的指令",
+  "description": "Outbound-only from a paired Desktop host. Desktop authenticates with its device token and claims work that mobile or Telegram enqueued.",
+  "auth": "Desktop device token",
+  "responses": [
+    { "status": "200", "description": "Claimed commands for this host (may be empty after the long-poll window)." }
+  ]
+}
+```
+
+| 方法       | 路線                                                     | 呼叫者            | 目的                       |
+| ---------- | -------------------------------------------------------- | ----------------- | -------------------------- |
+| `POST`     | `/_agent-native/integrations/remote/register`            | 桌面工作階段      | 配對桌面主機並返回權杖一次 |
+| `GET`      | `/_agent-native/integrations/remote/hosts`               | 行動/工作階段     | 列出配對的主機             |
+| `DELETE`   | `/_agent-native/integrations/remote/devices/:id`         | 行動/工作階段     | 撤銷配對主機               |
+| `POST`     | `/_agent-native/integrations/remote/devices/:id/revoke`  | 行動設備/工作階段 | 撤銷配對主機               |
+| `POST/GET` | `/_agent-native/integrations/remote/poll`                | 桌面權杖          | 領取工作                   |
+| `POST`     | `/_agent-native/integrations/remote/result`              | 桌面權杖          | 完成或失敗工作             |
+| `POST`     | `/_agent-native/integrations/remote/run-events`          | 桌面權杖          | 鏡像轉錄事件               |
+| `GET`      | `/_agent-native/integrations/remote/runs`                | 行動設備/工作階段 | 列出工作階段               |
+| `GET`      | `/_agent-native/integrations/remote/runs/:id`            | 行動設備/工作階段 | 閱讀會議摘要               |
+| `GET`      | `/_agent-native/integrations/remote/runs/:id/transcript` | 行動設備/工作階段 | 讀取鏡像轉錄本             |
+| `POST`     | `/_agent-native/integrations/remote/push/register`       | 行動設備/工作階段 | 註冊博覽會/行動推送權杖    |
+
+Telegram 通過 Dispatch 使用相同的中繼。支持的指令有：
+
+```text
+/code <prompt>
+/code list
+/code status <run>
+/code continue <run> <text>
+/code approve <id>
+/code deny <id>
+/code stop <run>
+```
+
+## 樣式
+
+匯入包樣式表：
+
+```ts
+import "@agent-native/code-agents-ui/styles.css";
+```
+
+樣式表使用與範本和桌面 shell 相同的 shadcn 樣式 HSL 自訂屬性。在分叉共用的 UI 之前，最好在主機應用程式中更改權杖或小類覆蓋。
+
+## 限制
+
+瀏覽器範本是本機優先的。當其本機節點伺服器處於活動狀態時，它可以啟動和恢復執行。對於本機進程生命週期、終端啟動和應用程式 Web 視圖，請使用桌面。