@agent-native/core 0.79.2 → 0.79.5

package/corpus/core/docs/content/locales/zh-TW/local-file-mode.md

@@ -0,0 +1,433 @@
+---
+title: "本機檔案模式"
+description: "使用本機 Markdown、MDX 和其他儲存庫檔案作為事實來源執行代理本機應用 - 包括帶有自訂元件的黑曜石風格 MDX 檔案。"
+---
+
+# 本機檔案模式
+
+本機檔案模式允許代理本機應用程式附加其正常的 UI 和操作介面
+直接到儲存庫或工作區中的檔案。該應用程式仍然感覺像是託管的
+產品，但其列表視圖、編輯器和代理工具可讀寫本機檔案
+而不是 SQL 支持的應用紀錄。
+
+第一個實現是在內容範本中：左側邊欄是
+從本機 `.md` 和 `.mdx` 檔案填充，選取一個頁面開啟標準
+內容編輯器，並儲存寫回到所選檔案。相同的檔案可以
+也可以由 Codex、Claude 程式碼、Agent-Native 側邊欄代理或普通編輯
+編輯器。
+
+對於內容，這使得該產品感覺像是 MDX 的開來源黑曜石：
+您的檔案以檔案形式存在，而應用程式新增了可視化編輯器、代理 actions，
+可共用的副本，以及丰富的互動式 MDX 元件。
+
+當您想要回購優先的工作流程時，請使用本機檔案模式：
+
+- `docs/*.mdx` 的檔案儲存庫
+- `blog/*.mdx` 的博客
+- `resources/*.md` 中的定位、訊息傳遞或團隊筆記等資源
+- 個人黑曜石風格的知識庫，具有更丰富的MDX編輯器
+- 需要從本機 React 程式碼生成的互動式自訂 MDX 塊的檔案
+- 應用程式工件應該易於編碼代理檢查和修補
+
+當您需要託管協作應用程式體驗時，請使用資料庫模式：
+多使用者共用、SQL 支持的權限、評論、版本歷史紀錄和
+沒有本機檔案系統存取權限的正式環境託管。
+
+## 心智模型
+
+有兩種真相來源模式：
+
+| 模式         | 事實來源                          | 最適合                                                  |
+| ------------ | --------------------------------- | ------------------------------------------------------- |
+| 資料庫模式   | SQL 行至 Drizzle                  | 託管應用、協作、共用、評論、版本歷史紀錄                |
+| 本機檔案模式 | `agent-native.json`聲明的Repo檔案 | 本機/開發工作流程、Git 審核、編碼代理編輯、檔案本機內容 |
+
+UI 和特工 actions 在兩種模式下都應保持相同的形狀。內容
+編輯器仍然編輯檔案；區別在於這些檔案是否解析
+到 SQL 行或本機檔案。
+
+```an-diagram title="相同的行為，兩個事實來源" summary="UI 和代理在兩種模式下調用相同的操作。操作層決定每個調用是否解析為 SQL 行或儲存庫檔案。"
+{
+  "html": "<div class=\"diagram-mode\"><div class=\"diagram-col entry\"><div class=\"diagram-node\">內容 UI</div><div class=\"diagram-node\">代理 + actions<br><small class=\"diagram-muted\">list/get/update-document</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-row resolve\"><div class=\"diagram-panel\" data-rough><span class=\"diagram-pill accent\">資料庫模式</span><small class=\"diagram-muted\">SQL rows via Drizzle</small><small class=\"diagram-muted\">託管 · 分享 · 評論 · 歷史</small></div><div class=\"diagram-panel\" data-rough><span class=\"diagram-pill ok\">Local File Mode</span><small class=\"diagram-muted\">repo files via agent-native.json</small><small class=\"diagram-muted\">Git 評審 · 編碼代理編輯</small></div></div></div>",
+  "css": ".diagram-mode{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-mode .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-mode .diagram-arrow{font-size:22px;line-height:1}.diagram-mode .resolve{display:flex;gap:12px;flex-wrap:wrap}.diagram-mode .diagram-panel{display:flex;flex-direction:column;gap:4px;padding:12px 14px}"
+}
+```
+
+## 範例儲存庫
+
+內容工作區可以像這樣小：
+
+```an-file-tree title="一個 Content workspace repo"
+{
+  "entries": [
+    { "path": "agent-native.json", "note": "聲明哪些資料夾是內容根以及它們的型別" },
+    { "path": "docs/", "note": "內容根：在側邊欄中顯示為頁面" },
+    { "path": "docs/getting-started.mdx" },
+    { "path": "docs/guides/custom-components.mdx" },
+    { "path": "blog/", "note": "內容根" },
+    { "path": "blog/launch-post.mdx" },
+    { "path": "resources/", "note": "內容根" },
+    { "path": "resources/messaging/positioning.md" },
+    { "path": "components/", "note": "不是內容根：MDX 可匯入的 preview 元件庫" },
+    { "path": "components/FrameworkTabs.tsx" },
+    { "path": "components/Callout.tsx" },
+    { "path": "extensions/", "note": "不是內容根：本機 extension 庫（沙盒 widgets）" },
+    { "path": "extensions/doc-status/extension.json" },
+    { "path": "extensions/doc-status/index.html" }
+  ]
+}
+```
+
+在本機檔案模式下，內容側邊欄顯示 `docs/`、`blog/` 和
+`resources/` 樹為頁面。選取 `docs/getting-started.mdx` 開啟
+標準內容編輯器中的檔案；在 UI 中編輯寫回
+`docs/getting-started.mdx`.
+
+`components/` 不是內容根。 MDX
+檔案可以匯入或引用。編輯器可以渲染簡單的本機MDX元件
+無需您克隆或分叉整個內容應用。
+
+`extensions/` 也不是內容根。它是一個本機擴充功能庫：
+小型沙盒小部件，可以在應用程式槽中呈現，同時其來源保留在
+儲存庫。
+
+## 將內容安裝到儲存庫中
+
+對於現有檔案、博客或 MDX 工作區，安裝內容本機檔案
+技能：
+
+```bash
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+```
+
+這會將 `content` 技能複製到儲存庫的代理技能資料夾中並寫入
+或使用內容預設值更新 `agent-native.json`：
+
+- 工作區級別的 `mode: "local-files"`
+- `apps.content.mode: "local-files"`
+- `docs/`、`blog/`、`content/` 和 `resources/` 的內容根
+- `components/` 用於本機 MDX 元件
+- `extensions/` 用於本機擴充功能小部件
+
+安裝的技能告訴編碼代理使用內容actions
+(`list-documents`, `get-document`, `edit-document`, `update-document`,
+`share-local-file-document` 和元件檔案 actions）（當本機內容應用時）
+或 Agent Native 桌面橋公開它們。如果沒有橋在執行，則該技能
+退回到安全的直接儲存庫編輯，同時保留 frontmatter、匯入、JSX，
+和未知的 MDX。
+
+## 設定
+
+將 `agent-native.json` 新增到儲存庫或工作區根目錄：
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "roots": [
+        {
+          "name": "Docs",
+          "path": "docs",
+          "kind": "docs",
+          "extensions": [".md", ".mdx"]
+        },
+        {
+          "name": "Blog",
+          "path": "blog",
+          "kind": "blog",
+          "extensions": [".md", ".mdx"]
+        },
+        {
+          "name": "Resources",
+          "path": "resources",
+          "kind": "resources",
+          "extensions": [".md", ".mdx"]
+        }
+      ],
+      "components": "components",
+      "extensions": "extensions",
+      "hide": ["**/_*.md", "**/_*.mdx"]
+    }
+  }
+}
+```
+
+您還可以使用 `AGENT_NATIVE_MODE=local-files` 或啟用本機檔案
+`AGENT_NATIVE_DATA_MODE=local-files`；清單是首選，因為它
+在儲存庫本身中紀錄資料夾合同。
+
+## 內容檔案格式
+
+內容為 Markdown 和 MDX。 Frontmatter 儲存頁面元資料，內文為
+可編輯檔案：
+
+```mdx
+---
+title: "開始使用"
+icon: "sparkles"
+isFavorite: true
+updatedAt: "2026-06-12T20:00:00.000Z"
+---
+
+# 開始使用
+
+Use <FrameworkTabs value="react" /> to show framework-specific code.
+```
+
+標題來自 `title` frontmatter（如果存在），否則來自
+檔案名。編輯器保留了 MDX 來源程式碼，但尚無法進行可視化編輯，因此
+編碼代理和普通文本編輯器仍然是安全的逃生艙口。
+
+## 自訂 MDX 元件
+
+內容可以從設定的 `components` 資料夾中預覽本機元件。
+這適用於檔案樣式的 MDX 元件，例如分頁、標注、包
+安裝片段或特定於框架的程式碼塊。
+
+例如，在您的內容旁邊新增一個互動式元件：
+
+```tsx
+// components/ImpactCounter.tsx
+import { useState } from "react";
+
+export function ImpactCounter({
+  label = "points",
+  accent = "blue",
+  featured = false,
+}: {
+  label?: string;
+  accent?: "blue" | "green" | "purple";
+  featured?: boolean;
+}) {
+  const [count, setCount] = useState(3);
+  const accentClass =
+    accent === "green"
+      ? "border-green-300 bg-green-50"
+      : accent === "purple"
+        ? "border-purple-300 bg-purple-50"
+        : "border-blue-300 bg-blue-50";
+
+  return (
+    <div className={`rounded-md border p-4 ${accentClass}`}>
+      <div className="text-sm text-muted-foreground">Launch impact</div>
+      <div className="mt-1 text-3xl font-semibold">
+        {count} {label}
+      </div>
+      {featured ? <div className="mt-1 text-sm">Featured metric</div> : null}
+      <button
+        type="button"
+        className="mt-3 rounded border px-3 py-1 text-sm"
+        onClick={() => setCount((value) => value + 1)}
+      >
+        Add point
+      </button>
+    </div>
+  );
+}
+
+export const ImpactCounterInputs = {
+  label: {
+    type: "string",
+    label: "Metric label",
+    default: "points",
+  },
+  accent: {
+    type: "select",
+    label: "Accent",
+    options: ["blue", "green", "purple"],
+    default: "blue",
+  },
+  featured: {
+    type: "boolean",
+    label: "Featured",
+    default: false,
+  },
+};
+```
+
+然後從任何本機 MDX 檔案使用它：
+
+```mdx
+---
+title: "發布說明"
+---
+
+# 發布說明
+
+<ImpactCounter label="wins" />
+```
+
+內容開發伺服器發現 PascalCase 命名匯出和 PascalCase 預設
+從 `components/` 下的 `.tsx`、`.jsx`、`.ts` 和 `.js` 檔案匯出。那些
+元件在編輯器內呈現並出現在
+**本機元件**。斜線插入建立一個最小的標籤，例如
+`<ImpactCounter />`；需要時在 MDX 來源中新增 props。
+
+元件執行有意成為本機開發/桌面橋接功能，而不是
+普通託管瀏覽器資料夾存取。如果你開啟`content.agent-native.com`，
+選取**本機檔案**，並在Chrome中選取一個資料夾，應用程式可以讀寫
+通過瀏覽器檔案系統存取`.md`和`.mdx`檔案API，但是
+Chrome 不會公開 Vite 編譯的絕對資料夾路徑
+`components/*.tsx`。要預覽和熱重載自訂 React 元件，請執行
+本機內容或使用 Agent Native Desktop，以便受信任的本機網橋可以
+將所選工作區註冊到本機內容開發伺服器。在該模式下，
+通過Vite編輯現有元件檔案熱重載，並新增或
+刪除元件檔案會重新載入元件註冊表和斜杠選單。
+
+代理還可以使用這些已註冊的元件檔案。使用
+`list-local-component-files` 找到註冊的工作空間id，然後
+`write-local-component-file` 建立或更新 `.tsx`、`.jsx`、`.ts` 或
+`.js` 檔案位於工作區的 `components/` 資料夾下。 MDX 檔案仍然是
+元件使用的真實來源；元件檔案保持正常倉庫
+使用 Git 審核來源檔案。
+
+如果元件匯出輸入元資料，則在編輯器中選取該元件
+在元件的右上角顯示一個編輯按鈕。支持的輸入型別
+為 `string`、`textarea`、`number`、`boolean` 和 `select`。表格寫
+更改回 MDX 標籤，因此本機檔案仍然是事實來源。
+元資料可以匯出為 `ComponentNameInputs`、`ComponentNameConfig.inputs`、
+`Component.inputs`，或`agentNative.inputs`。
+
+帶有文字屬性的簡單元件標籤可以內聯預覽：
+
+```mdx
+<FrameworkTabs value="react" />
+
+<Callout type="warning">This setting affects production deploys.</Callout>
+```
+
+複雜的 JSX 表達式保留在來源程式碼中。如果編輯者不能安全
+預覽元件道具，它顯示一個警告預留位置而不是
+默默地丟棄資料。
+
+## 共用本機檔案
+
+本機檔案不會直接共用，因為其他使用者無法讀取路徑
+你的機器。內容工具列的共用按鈕建立或刷新
+所選檔案的資料庫支持副本，導覽到該副本，然後開啟
+正常共用快顯窗口。原始本機檔案保留在本機檔案下；
+資料庫副本出現在本機檔案模式下的共用副本下，並使用
+標準檔案共用模型。
+
+## 本機擴充功能
+
+本機檔案模式還可以從設定中載入儲存庫支持的擴充功能
+`extensions` 資料夾。每個擴充功能都是一個帶有 `extension.json`
+清單和 HTML 條目檔案：
+
+```text
+extensions/
+  doc-status/
+    extension.json
+    index.html
+```
+
+```json
+{
+  "id": "doc-status",
+  "name": "Doc Status",
+  "description": "Shows metadata for the selected Content file.",
+  "entry": "index.html",
+  "slots": ["content.sidebar.bottom"],
+  "permissions": {
+    "appActions": ["list-documents"],
+    "extensionData": true
+  }
+}
+```
+
+`index.html` 與普通使用的 Alpine/Tailwind 擴充功能主體格式相同
+資料庫支持的擴充功能。當內容應用看到本機擴充功能時
+聲明了 `content.sidebar.bottom`，它在底部呈現該擴充功能
+內容側邊欄。主機通過選取的`window.slotContext`
+檔案 ID、標題、來源元資料以及內容是否處於本機檔案模式。
+
+本機擴充功能由應用程式預覽，但作為檔案進行編輯。擴充功能
+列表顯示它們帶有本機檔案徽章，整頁面檢視器指向
+入口檔案。 SQL 支持的擴充功能 actions，例如更新、刪除、共用和
+歷史紀錄不適用；使用您的編輯器、Codex、Claude 程式碼或 Git 歷史紀錄
+來源程式碼更改。
+
+對於 v1，本機擴充功能有意保守：
+
+- 他們可以將 `extensionData` 用於自己的小型執行時狀態
+- 他們只能調用`extension.json`中列出的`appAction`
+- 原始 SQL 助手和外部 `extensionFetch` 已停用
+- slot 目標在 `extension.json` 中聲明，而不是通過 SQL 安裝
+
+這為本機工作空間提供了類似黑曜石的外掛介面，而無需讓
+任意儲存庫檔案繼承資料庫支持的擴充功能的所有功能。
+
+## 應用程式如何使用它
+
+本機檔案模式是通過框架的本機工件助手實現的。
+應用程式聲明其擁有的工件型別的根，然後讀取和寫入
+通過 UI 和代理已經使用的相同操作介面。
+
+對於內容，這意味著：
+
+- `list-documents` 列出設定的 `.md` 和 `.mdx` 檔案。
+- `get-document` 讀取選定的本機檔案。
+- `update-document` 寫入選定的本機檔案。
+- `create-document` 在所選資料夾中建立新的本機 `.mdx` 檔案。
+- `delete-document`刪除本機檔案。
+- 搜尋在設定的本機檔案中執行。
+
+不能從內容 UI 中行動、重命名和重新排序本機檔案頁面
+尚支持。在工作區或使用編碼代理執行這些操作；
+內容側邊欄將反映生成的檔案樹。
+
+這使代理合約變得簡單：代理可以繼續使用內容 actions，
+而這些 actions 決定目標是 SQL 支持的還是檔案支持的。
+
+隨著時間的推移，其他應用程式可以采用相同的模式。幻燈片應用程式可以對應
+`slides/*.mdx` 到甲板，計畫應用程式可以將 `plans/*` 對應到計畫檔案，以及
+儀表板應用程式可以將 `dashboards/*.mdx` 對應到儀表板。那些特定於應用程式的
+資料夾是位於同一本機工件合約之上的約定。
+
+## 本機檔案與匯出/匯入
+
+內容有兩種不同的檔案工作流程：
+
+| 工作流程                 | 發生了什么                                                               |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `/local-files` 匯出/匯入 | 資料庫模式仍然是事實來源。檔案是您匯出、編輯、預覽和匯入的顯式同步表面。 |
+| 本機檔案模式             | 檔案是真相的來源。內容側邊欄和編輯器直接對本機檔案進行操作。             |
+
+當您需要偶爾檢視託管工作區的檔案時，請使用匯出/匯入。
+當儲存庫本身是工作區時，使用本機檔案模式。
+
+## 歷史與合作
+
+本機檔案模式依賴於檔案本機歷史紀錄：
+
+- 向 Git 提交重要更改
+- 使用拉取請求進行審核
+- 讓編碼代理直接編輯相同的檔案
+- 使用普通檔案差異來了解更改
+
+資料庫模式仍然更適合託管協作功能，例如
+共用、評論、SQL 支持的版本歷史紀錄和實時多使用者編輯。
+
+提供者同步可以分層在任一模式之上。例如，檔案儲存庫可以
+新增 actions，將內容從 CMS 提取到本機 MDX 檔案或推送所選內容
+本機檔案返回到那個CMS。
+
+## 安全正式環境
+
+本機檔案模式為應用程式 actions 提供對設定的工作區的直接寫入存取權限
+檔案。這適合本機開發和可信單租戶檔案
+橋梁，但它不是預設的正式環境安全模型。
+
+當 `NODE_ENV=production` 時，框架拒絕 `local-files` 模式，除非您
+設定：
+
+```bash
+AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION=true
+```
+
+僅針對受信任的單租戶部署進行設定，其中每個人都可以使用
+應用程式可以讀取和寫入設定的檔案。對於普通託管，
+多使用者應用程式，使用資料庫模式和SQL支持的共用。

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

@@ -0,0 +1,147 @@
+---
+title: "MCP 應用程式"
+description: "使用真實應用路由、嵌入橋和主機橋 API，在 Claude、ChatGPT 和其他兼容主機中編寫和嵌入互動式 MCP 應用 UI。"
+---
+
+# MCP 應用程式
+
+**此頁面：Claude/ChatGPT 中的內聯 UI。** 創作 MCP 應用程式資源以及在兼容主機的聊天中呈現真實應用程式路由的嵌入橋。此頁面也是**客戶支持矩陣** ([below](#client-support)) 的單一主頁面。
+
+| 如果你想……                                        | 閱讀                                     |
+| ------------------------------------------------- | ---------------------------------------- |
+| 將外部代理/主機連線到您的應用                     | [External Agents](/docs/external-agents) |
+| 為您的代理提供更多工具（使用其他 MCP 伺服器）     | [MCP Clients](/docs/mcp-clients)         |
+| 建置在 Claude/ChatGPT 中渲染的內聯 UI             | **此頁面** — MCP 應用                    |
+| 較低級別的 MCP 伺服器參考（驗證、工具、自訂掛載） | [MCP Protocol](/docs/mcp-protocol)       |
+
+MCP 應用程式是官方的 `io.modelcontextprotocol/ui` 擴充功能，可讓兼容主機（Claude、Claude Desktop、ChatGPT、VS Code GitHub Copilot、Goose、Postman、MCPJam 和 Cursor）在聊天中渲染互動式 UI。在代理原生應用程式中，每個 MCP 應用程式都是**真正的 React 路由**，而不是單獨的普通 HTML 小部件。
+
+在 Agent-Native 應用自己的聊天中，首選 [native chat renderers](/docs/native-chat-ui) 作為第一方小部件，例如表格、圖表、鍵入的結果和批準功能可供性。在 Claude、ChatGPT、Copilot、Cursor 和其他兼容主機中使用 MCP 應用程式進行外部/跨主機內聯 UI，並使用操作 `link` 作為通用深層連結回退。
+
+## 創作：可選的 MCP 應用 UI {#mcp-apps}
+
+對於支持 MCP 應用擴充功能的主機，操作還可以使用 `mcpApp` 通告內聯 UI 資源。這是對流程的漸進增強，外部代理應向使用者提供互動式介面而不僅僅是文本，例如檢視電子郵件草稿、編輯行事曆邀請或在生成的儀表板變體之間進行選取。
+
+每當使用者需要 UI 時，將真正的 React 應用程式與 `embedRoute()` 或 `embedApp()` 一起使用。思維模型很簡單：操作的 `link` 目標也是 MCP 應用程式嵌入目標。將操作公開為正常操作/工具，返回與 `link` 相關的深層連結，並新增 `mcpApp.resource = embedApp(...)`，以便有能力的主機內聯載入相同的路由，而不是開啟新分頁。當兩者都應該從同一路由建置時，更喜歡 `embedRoute({ title, openLabel, path })`：它是一種方便的包裝器，可以從一次調用中返回匹配的 `link` 和 `mcpApp` 欄位，而 `embedApp(...)` 是您直接分配給 `mcpApp.resource` 的較低級別資源。
+
+這意味著完整的應用程式嵌入可以執行路由開啟後可以執行的任何操作：檢視或編輯電子郵件草稿、顯示過濾的收件箱/搜尋、開啟行事曆事件或事件草稿、載入擴充功能頁面、檢查完整的分析儀表板或儲存的分析、在幻燈片編輯器中繼續幻燈片或開啟設計專案/編輯器。優先選取 URL/深層連結參數和現有的 `/_agent-native/open` 導覽/應用程式狀態橋，而不是為 MCP 應用程式發明第二個狀態協議。
+
+在極少數情況下，正確的目標是渲染一個共用 React 元件而不是整個應用程式 shell 的集中應用程式路徑。 Analytics 的 `/chart` 路線就是模型：它在 URL 中采用緊湊的 `SqlPanel` 有效負載，並呈現儀表板使用的相同圖表元件。這仍然是一個應用程式嵌入，而不是一個普通的 HTML MCP 應用程式。通過正常操作 / `open_app({ path, embed: true })` 公開或調用它，保持 URL 的確定性，並讓 `embedApp()` 內聯渲染該路由。
+
+請勿為產品 UI 手寫一次性普通 HTML MCP 應用程式；如果操作需要自訂介面，請首先新增或重用真實的應用程式路由/元件並嵌入該路由。
+
+```an-diagram title="MCP 應用程式嵌入往返" summary="該操作的連結目標也是嵌入目標。有能力的主機內聯載入相同的簽名應用程式路由；其他人都回到深層連結。"
+{
+  "html": "<div class=\"diagram-embed\"><div class=\"diagram-card\" data-rough><strong>Action</strong><small class=\"diagram-muted\">`link` target = MCP App embed target</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\" data-rough><strong>embedApp()</strong><span class=\"diagram-pill accent\">create_embed_session</span><small class=\"diagram-muted\">mints short-lived embed session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\" data-rough><strong>/_agent-native/embed/start</strong><small class=\"diagram-muted\">交換一次性 SQL ticket</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\" data-rough><strong>Signed app route</strong><span class=\"diagram-pill ok\">真實 React 路由</span><small class=\"diagram-muted\">short-lived browser session</small></div><div class=\"diagram-fallback\"><span class=\"diagram-pill warn\">不支持 MCP Apps</span><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>&quot;Open in … &rarr;&quot; deep link</div></div></div>",
+"css": ".diagram-embed{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-embed .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:140px}.diagram-embed .diagram-arrow{font-size:22px;line-height:1}.diagram-embed .diagram-fallback{display:flex;flex-direction:column;align-items:center;gap:6px;margin-inline-start:8px}"
+}
+
+```
+
+```ts
+import { embedApp } from "@agent-native/core";
+
+export default defineAction({
+  // ...description, schema, run, link...
+  mcpApp: {
+    resource: embedApp({
+      title: "Review draft",
+      description: "Open the generated draft in the real Mail compose UI.",
+      iframeTitle: "Agent-Native Mail",
+      openLabel: "Open in Mail",
+    }),
+  },
+});
+```
+
+```an-annotated-code title="mcpApp 資源設定"
+{
+  "filename": "actions/review-draft.ts",
+  "language": "ts",
+  "code": "import { embedApp } from \"@agent-native/core\";\n\nexport default defineAction({\n  // ...description, schema, run, link...\n  mcpApp: {\n    resource: embedApp({\n      title: \"Review draft\",\n      description: \"Open the generated draft in the real Mail compose UI.\",\n      iframeTitle: \"Agent-Native Mail\",\n      openLabel: \"Open in Mail\",\n    }),\n  },\n});",
+  "annotations": [
+    { "lines": "6", "label": "漸進增強", "note": "`mcpApp.resource` 為支持 MCP 應用擴充功能的主機宣傳內聯 UI。也保留操作的 `link` 建置器 - 僅 CLI 和較舊的主機會忽略 UI 元資料，但仍然需要深層連結。" },
+    { "lines": "7", "label": "Embed = the link target", "note": "`embedApp()` uses the action's `link` as its launch target: it calls `create_embed_session`, exchanges a one-time SQL ticket at `/_agent-native/embed/start`, and navigates the MCP App frame to the same signed app route." },
+    { "lines": "11", "label": "通用後備標籤", "note": "`openLabel` is the visible `\"Open in … →\"` text used as the deep-link escape hatch when a host does not render the inline iframe." }
+  ]
+}
+```
+
+MCP 伺服器通告擴充功能 `io.modelcontextprotocol/ui`，將 `_meta.ui.resourceUri` 和 `_meta["ui/resourceUri"]` 新增到 `tools/list`，並且還發出 ChatGPT 應用 SDK 兼容性元資料（`openai/outputTemplate`、小部件 CSP/描述/可存取性）。它通過 `resources/list`、`resources/templates/list` 和 `resources/read` 使用 MIME `text/html;profile=mcp-app` 公開 HTML。 stdio 代理從實時應用程式轉發這些資源處理程序，因此桌面和 CLI 用戶端可以看到與 HTTP 用戶端相同的資源。
+
+即使新增 `mcpApp` 也保留現有的 `link` 建置器。僅 CLI 的用戶端、較舊的主機以及任何不呈現 MCP 應用程式的主機將忽略 UI 元資料，並且仍然需要 `"Open in … →"` 連結。 `embedApp()` 使用該連結作為其啟動目標，調用僅應用程式的 `create_embed_session` 幫助程序，在 `/_agent-native/embed/start` 交換一次性 SQL 票證，並通過短暫的瀏覽器工作階段以及同來源提取的承載回退將 MCP 應用程式框架導覽到目標路由。 `open_app({ app, path, embed: true })` 是用於完整儀表板、過濾收件箱、行事曆草稿視圖、分析和擴充功能頁面等路線的通用逃生口，當完整應用程式是最清晰的審查/編輯介面時，應廣泛使用。
+
+`embedApp()` 在資源 CSP 中包含 MCP 請求來源，以便啟動器可以獲取並在明確請求時建置已簽名的第一方應用程式路由。 Dispatch 將授予的應用程式的確切來源新增到其 `open_app` 資源中，以便單個 Dispatch 連線器可以內聯郵件、行事曆、幻燈片和其他內容，而無需允許每個 HTTPS 來源。僅為真正嵌入第三方播放器或載入第三方資源的自訂 MCP 應用傳遞額外的框架或資源域。
+
+在這些 `embedApp()` 路由中，`sendToAgentChat()` 是嵌入感知的。自動提交的提示會以 `ui/update-model-context` 加 `ui/message` 的形式中繼到 MCP 主機，因此嵌入式應用程式中的按鈕可以有意從所選應用程式狀態繼續 Claude/ChatGPT 對話。隱藏上下文作為模型上下文發送；可見的使用者轉向僅保留應用程式的提示，這避免了圍繞內部應用程式狀態檔案路徑的可怕的主機同意。 `submit: false` 保留本機預填充/審核行為。
+
+## 一流的MCP應用橋 {#mcp-app-bridge}
+
+MCP 應用嵌入是路線嵌入，而不是單獨的迷你產品。 `embedApp()` 從操作的 `link` 目標開始，建立一個短暫的嵌入工作階段，並啟動該簽名的應用程式路由。當主機可以直接水合路線時，標準 MCP 應用程式主機可以自行導覽 MCP 應用程式框架。
+
+```an-diagram title="兩條主橋路徑，一條簽名路由" summary="克勞德移植了水合路線，使用直接ui/_bridge； ChatGPT 通過 window.openai 獲取受控 iframe，並通過 postMessage 中繼主機操作。兩者都指向同一個簽名的應用程式路由。"
+{
+  "html": "<div class=\"diagram-bridge\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><strong>Claude web</strong><span class=\"diagram-pill accent\">single-frame transplant</span><small class=\"diagram-muted\">在 Claude iframe 中激活已簽名的應用 HTML，然後使用直接 `ui/_` 主機橋</small></div><div class=\"diagram-card\" data-rough><strong>ChatGPT web</strong><span class=\"diagram-pill accent\">controlled route iframe</span><small class=\"diagram-muted\">`window.openai`host APIs ·`agentNative.mcpHost.*` postMessage relay</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Same signed app route<br><small class=\"diagram-muted\">普通路由 + React 元件</small></div></div>",
+"css": ".diagram-bridge{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-bridge .diagram-col{display:flex;flex-direction:column;gap:12px}.diagram-bridge .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;max-width:300px}.diagram-bridge .diagram-arrow{font-size:22px;line-height:1}.diagram-bridge .diagram-box{padding:16px 18px;text-align:center}"
+}
+
+```
+
+Claude Web 使用單框架移植路徑：資源檔案獲取已簽名的應用程式 HTML 並將其水合到 Claude 的 MCP 應用程式 iframe 中，因為 Claude 無法可靠地允許應用程式擁有的子 iframe 或外部框架導覽。 ChatGPT Web 獲得受控路由 iframe，因為它的 Apps 橋為我們提供了穩定的 `window.openai` 主機 API 和有界高度控制。所有路徑都指向相同的簽名應用程式路由並渲染正常路由和 React 元件。設計嵌入式路由，以便使用相同簽名的 URL 重新載入可以重建相同的視圖。
+
+對於同一應用程式 `open_app({ embed: true })`，框架在原始工具調用期間建立嵌入啟動票證，並將簽名的啟動 URL 存儲在隱藏的工具元資料中。定制actions可以返回`embedStartUrl`相同的快速路徑； MCP 層將票證 URL 從模型可見的 `structuredContent` 和正常的開放連結元資料中剝離。當不存在嵌入啟動 URL 時，資源將回退到僅應用程式的 `create_embed_session` 幫助程序。這使得正式環境主機能夠在直接路由上限制 iframe 發起的工具調用，而不會將一次性應用程式工作階段 URL 泄漏到紀錄中。如果使用者在一次性啟動票過期後重新開啟舊聊天，啟動路由將返回一個小刷新頁面並將 `agentNative.embedSessionExpired` 發布到包裝器； `embedApp()` 清除陳舊的開始 URL，並在仍具有原始應用程式路由的情況下通過 `create_embed_session` 鑄造新票。
+
+ChatGPT通過`window.openai`獲得專用的兼容路徑：啟動檔案直接讀取`toolInput`、`toolOutput`和`toolResponseMetadata`，然後通過`window.openai.callTool(...)`調用`create_embed_session`。標準 MCP 應用程式主機使用 `ui/*` JSON-RPC 橋接器。直接水合路由可以通過主橋助手調用`ui/update-model-context`、`ui/message`、`ui/open-link`和`ui/request-display-mode`。 Claude的移植路線在水合後使用相同的直接`ui/*`主橋。當使用 ChatGPT 或顯式診斷 iframe 路徑時，包裝器通過 `agentNative.mcpHost.*` postMessage 請求中繼同一主機 actions。保持兩條路徑的結果形狀相同：返回集中的 `link` 和簡潔的結構化內容。
+
+請勿將標準 `_meta.ui.domain` 設定為應用程式 URL。 MCP Apps 將該欄位視為特定於主機的欄位：Claude 驗證 `{hash}.claudemcpcontent.com` 樣式的沙箱域，而 ChatGPT 使用自己的 `openai/widgetDomain` 元資料。除非您故意發出特定於主機的值，否則請省略 `ui.domain`；主機將選取預設沙箱來源。
+
+擴充功能頁面將其沙箱保留在 MCP 聊天嵌入中，而無需導覽第二個路由 iframe。正常應用程式使用會將 `/_agent-native/extensions/:id/render` 呈現為沙盒子 iframe。在 MCP 聊天橋模式下，框架在路由 iframe 內呈現與沙箱 `srcDoc` 相同的擴充功能檔案，避免主機 `frame-ancestors` / `X-Frame-Options` 故障，同時保留 `sandbox="allow-scripts allow-forms"`。
+
+資源 shell 擁有外部主機大小。 `embedApp({ height })`預設為`560px`，將外殼夾到`320-900px`，並為小工具列保留`44px`，因此路線視口為`height - 44px`。保持嵌入式應用程式路由內部可滾動，並讓啟動器報告有界的固有高度而不是完整的檔案高度；否則主機自動調整大小可以將一個普通的應用頁面變成一個很高的聊天神器。更改的 shell 僅影響新的 MCP App 資源和新的工具調用。舊的 ChatGPT/Claude 對話框架可以保留以前的資源行為，因此在判斷修複之前使用新的內聯渲染驗證大小。
+
+### 嵌入模式 {#embed-modes}
+
+Claude預設使用單幀移植路徑。在偵錯主機模塊載入行為時，您還可以在具有 `embedMode: "transplant"` 或 `frame: "transplant"` 的其他主機中強制使用它。您可以使用 `embedMode: "iframe"`、`renderMode: "iframe"`、`nested: true` 或 `frame: "iframe"` 強制嵌套診斷 iframe。如果 iframe 被阻止，`embedApp()` 會將其替換為開放應用後備：使用者可以重試內聯、通過主機開啟新建立的嵌入工作階段，或使用可見路由 URL。保持動作的 `link` 目標本身有用，因為它仍然是通用逃生艙口。
+
+通過 ngrok 測試 Claude 時，請使用正式環境版本（`npx @agent-native/core@latest build` 然後 `npx @agent-native/core@latest start`）或已部署的預覽/正式環境 URL。 Claude的單幀移植路徑適用於正式環境資產塊；原始 Vite 開發模塊（例如 `/app/root.tsx`）可以受到應用程式驗證的保護，並且無法從 Claude 資源來源進行動態匯入。
+
+## 主橋API {#host-bridge}
+
+主橋故意很小：
+
+| 模式                  | 訊息型別                              | 使用它                            |
+| --------------------- | ------------------------------------- | --------------------------------- |
+| 直接主機路由          | `ui/update-model-context`             | 宿主模型的隱藏上下文              |
+| 直接主機路由          | `ui/message`                          | 將可見使用者轉入主機              |
+| 直接主機路由          | `ui/open-link`                        | 通過主機開啟外部或應用程式URL     |
+| 直接主機路由          | `ui/request-display-mode`             | 請求`inline`、`fullscreen`或`pip` |
+| Claude移植            | `ui/*`                                | 水合後相同的直接主橋              |
+| ChatGPT / iframe 路由 | `agentNative.mcpHostContext`          | 主題、區域設定、主機平台、維度    |
+| ChatGPT / iframe 路由 | `agentNative.embeddedAppReady`        | 確認路由iframe載入                |
+| ChatGPT / iframe 路由 | `agentNative.mcpHost.*` / `.response` | 主機請求的包裝中繼                |
+
+嵌入式路由可以使用 `@agent-native/core/client` 中的 `updateMcpAppModelContext()`、`openMcpAppHostLink()`、`requestMcpAppDisplayMode()`、`getMcpAppHostContext()` 和 `useMcpAppHostContext()`。 `sendToAgentChat()` 使用完整應用程式嵌入中的相同路徑來自動提交提示。
+
+顯示模式是盡力而為。應用內 `McpAppRenderer` 目前報告內聯 Web 主機上下文和僅內聯顯示模式；外部主機可能會接受較大的顯示請求、忽略它們或回複不支持模式的錯誤。始終保持內聯路由可用。
+
+## 用戶端支持和快取 {#client-support}
+
+目前MCP Apps官方用戶端列表包括Claude、Claude Desktop、VS Code GitHub Copilot、Goose、Postman、MCPJam、ChatGPT、Cursor；主機支持仍然因計畫、發布渠道和用戶端版本而異，因此請檢查 [MCP extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix)。 ChatGPT 自訂 MCP 應用程式可通過 ChatGPT Web 上的商業和企業/教育工作區的開發人員模式使用；請參閱 OpenAI 的 [developer mode and MCP apps](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-apps-in-chatgpt-beta) 注釋。
+
+Claude Code、Codex 和其他 CLI/程式碼編輯器用戶端在支持 MCP 應用程式時仍會收到相同的資源和元資料，但將它們視為連結輸出主機，除非您已在該確切表面中驗證了內聯 iframe 渲染。當主機選取不渲染 iframe 時，深層連結仍然是可靠的後備方案。實際上，每個代理本機應用程式都應使用以下兩種方式編寫：用於在有能力的主機中進行內聯審核/編輯的 MCP 應用程式，以及用於通用往返返回完整應用程式的 `link` 應用程式。
+
+Claude 和 ChatGPT 可以快取現有自訂連線器的工具和資源元資料。更改MCP App元資料後，使用新的工具調用進行驗證；如果主機仍使用舊描述符，請重新連線 Claude 連線器或重新掃描/檢查 ChatGPT 連線器，以便刷新目錄。如果部署後 Claude 在工具描述符上紀錄了有關 `_meta.ui.csp` 或 `_meta.ui.permissions` 的警告，則該連線器正在使用過時的元資料：刪除/重新連線 Claude 連線器並開始新的聊天。
+
+## 測試 {#testing}
+
+使用`embedApp()`和`McpAppRenderer`週圍的輕量級夾具測試MCP應用程式；它們涵蓋 CSP、主機上下文、應用程式啟動和橋接訊息行為，而無需真正的外部主機。驗證 ChatGPT 或 Claude Web 時，在 shell 更改後觸發新的工具調用並測量可見的 iframe。同一對話中先前渲染的幀可能仍會顯示快取的高度或啟動行為。
+
+## 相關 {#related}
+
+- [External Agents](/docs/external-agents) — 將 Claude、ChatGPT、Codex 和 Cursor 連線到託管應用程式； MCP 應用程式兼容性矩陣；目錄層；深層連結。
+- [MCP Protocol](/docs/mcp-protocol) — 自動安裝的 MCP 伺服器、驗證、工具和 `ask-agent`。
+- [Actions](/docs/actions) — `defineAction`，`link` 建置者，`publicAgent`。
+
+```
+
+```