@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/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="Same actions, two sources of truth" summary="The UI and agent call identical actions in both modes. The action layer decides whether each call resolves to SQL rows or repo files."
+{
+  "html": "<div class=\"diagram-mode\"><div class=\"diagram-col entry\"><div class=\"diagram-node\">Content UI</div><div class=\"diagram-node\">Agent + 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\">Database mode</span><small class=\"diagram-muted\">SQL rows via Drizzle</small><small class=\"diagram-muted\">hosted · sharing · comments · history</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 review · coding-agent edits</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="A Content workspace repo"
+{
+  "entries": [
+    { "path": "agent-native.json", "note": "declares which folders are content roots and their kinds" },
+    { "path": "docs/", "note": "content root — shows in the sidebar as pages" },
+    { "path": "docs/getting-started.mdx" },
+    { "path": "docs/guides/custom-components.mdx" },
+    { "path": "blog/", "note": "content root" },
+    { "path": "blog/launch-post.mdx" },
+    { "path": "resources/", "note": "content root" },
+    { "path": "resources/messaging/positioning.md" },
+    { "path": "components/", "note": "NOT a content root — preview component library MDX can import" },
+    { "path": "components/FrameworkTabs.tsx" },
+    { "path": "components/Callout.tsx" },
+    { "path": "extensions/", "note": "NOT a content root — local extension library (sandboxed 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: "Getting Started"
+icon: "sparkles"
+isFavorite: true
+updatedAt: "2026-06-12T20:00:00.000Z"
+---
+
+# Getting Started
+
+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: "Launch Notes"
+---
+
+# Launch Notes
+
+<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/docs/content/locales/zh-CN/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 App embed round-trip" summary="The action's link target is also the embed target. Capable hosts load the same signed app route inline; everyone else falls back to the deep link."
+{
+  "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\">exchanges one-time 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\">real React route</span><small class=\"diagram-muted\">short-lived browser session</small></div><div class=\"diagram-fallback\"><span class=\"diagram-pill warn\">no MCP Apps support</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="The mcpApp resource config"
+{
+  "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": "Progressive enhancement", "note": "`mcpApp.resource` advertises an inline UI for hosts that support the MCP Apps extension. Keep the action's `link` builder too — CLI-only and older hosts ignore the UI metadata and still need the deep link." },
+    { "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": "Universal fallback 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="Two host bridge paths, one signed route" summary="Claude transplants the hydrated route and uses the direct ui/_bridge; ChatGPT gets a controlled iframe via window.openai and relays host actions over postMessage. Both point at the same signed app route."
+{
+  "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\">hydrates signed app HTML in Claude's iframe, then direct`ui/_` host bridge</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\">normal route + React components</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`。
+
+```
+
+```