}` 引用。页面通过服务执行文件操作，不直接访问主应用源码或 Node API。
## 页面 API 速查
以当前宿主实现和锁定的 SDK 类型为准。先注册事件，再 `connect()`；连接后读取 `getHostCapabilities()`，按返回的能力启用功能。官方 API 文档描述 SDK 的完整表面，宿主支持范围还要看下表。
### 官方 MCP Apps API
| API / 事件 | 用途 | ZCode 行为与注意事项 |
| --------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `new App(info, capabilities, options)`、`connect()` | 创建页面连接并完成握手 | 每个活页面只建一个 App；不要同时访问会触发另一连接的 `window.zcode` |
| `getHostVersion()`、`getHostCapabilities()`、`getHostContext()` | 读取宿主、能力、主题、语言和展示模式 | 在连接完成后使用；不要只按宿主版本号猜能力 |
| `ontoolinput`、`ontoolresult`、`ontoolcancelled` | 接收完整输入、结果和取消 | 大 UI 延迟加载时，保留初始结果再交给 UI，避免丢通知 |
| `onhostcontextchanged` | 响应主题、语言、尺寸或模式变化 | 更新显示；不要因此重复执行业务操作 |
| `callServerTool({ name, arguments }, options)` | 调用当前插件服务的工具 | 沿用 Agent 的权限和审批；`options.signal` 可取消；返回真实 `CallToolResult` |
| `readServerResource({ uri })` | 读取当前服务的资源 | 返回 MCP `contents`；二进制是 base64；不能用它访问其他插件或任意本地文件 |
| `listServerResources({ cursor })` | 分页列出服务资源 | 资源模板列表用后表中的 `resources/templates/list` 请求 |
| `sendMessage({ role: "user", content })` | 发出主对话后续消息 | 需要 `message` 能力；有用户手势时发送，无手势时进入确认流程 |
| `updateModelContext({ content, structuredContent })` | 给下一轮对话附加选区等上下文 | 需要 `updateModelContext` 能力；在输入区可见、可删，不立即发消息，不是持久存储 |
| `createSamplingMessage(params, { signal })` | App 内调用当前任务模型 | 需要 `sampling` 能力；支持文本与符合限制的图片输入，返回文本；对话历史由 App 提供 |
| `registerTool(name, config, handler)` | 页面提供可被模型调用的工具 | 握手前登记；声明 App 的 `tools` 能力；随活页面登记/撤销并遵守既有审批 |
| `onlisttools`、`oncalltool`、`sendToolListChanged()` | 手动管理页面工具目录 | 是另一种页面工具实现方式；取消信号在回调 `extra.mcpReq?.signal` 中；Showcase 提供完整例子 |
| `requestDisplayMode({ mode })` | 请求切换展示位置 | `inline` 为内联，`fullscreen` 为侧栏；以返回模式为准；`pip` 当前保持原模式 |
| `sendSizeChanged({ height })` | 报告内容高度 | 可用 SDK 自动测量；手动测量内容容器，避免把视口高度反馈给宿主 |
| `openLink({ url })` | 通过宿主打开外链 | 仅允许 `http:` / `https:` |
| `downloadFile({ contents })` | 调用原生保存对话框 | 需要 `downloadFile` 能力；支持嵌入资源或当前服务的资源链接；取消/写入失败返回 `isError: true` |
| `sendLog({ level, data })` | 发送可观察的页面诊断 | 不向 stdio 服务的 stdout 写调试日志；不要记录密钥或用户内容 |
| `onteardown` | 释放页面监听器等资源 | 宿主做有时限的 teardown，不应把唯一保存操作留到此时 |
| `requestTeardown()` | 请求宿主释放页面 | 当前 ZCode 只记录请求；实际生命周期跟随卡片/面板，不能把它当关闭按钮 |
Sampling 使用接纳请求时的任务模型，不读取主聊天历史；只有 App 明确传入的历史进入请求。当前不接受 `temperature`、`tools`、原生 audio 等未实现参数，`includeContext` 只支持 `none`。回答和取消不应被自动追加为主对话回合。
### ZCode 扩展与低层 MCP 请求
下面的 `app.request()` 是官方 App 的低层接口。请求结果应使用 `@modelcontextprotocol/core` 的对应 schema 校验。
| 接口 / 字段 | 调用或声明方式 | 适用范围 |
| ------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 会话视图状态 | `ui/set-widget-state`，参数 `{ widgetState }`，结果 `EmptyResultSchema` | 先检查 `experimental["zcode/widgetState"]`；初值来自 hostContext 同名键；仅宿主内存，会话内重建可恢复，应用重启不保证 |
| 资源模板列表 | `resources/templates/list`，结果 `ListResourceTemplatesResultSchema` | 当前服务的 MCP 模板目录；不要假定 App 存在 `listServerResourceTemplates()` 便捷方法 |
| 资源订阅 | `resources/subscribe` / `resources/unsubscribe`，参数 `{ uri }`，结果 `EmptyResultSchema` | 先检查 `experimental["zcode/resourceSubscribe"]`；服务端也须支持订阅 |
| 资源变更通知 | `notifications/resources/updated` / `notifications/resources/list_changed` | 先用 `setNotificationHandler()` 注册处理器；收到 URI 后自行重新读取资源 |
| 当前侧栏面板 | `app.getHostCapabilities()?.experimental?.["zcode/surface"]` 返回 `{ id }` | 清单 `ui.surfaces[].id` 与工具 `_meta.ui.surface` 保持一致 |
| CSP 放宽 | 资源 `_meta["zcode/csp"]` 中 `unsafeEval`、`wasmUnsafeEval` | 检查 `experimental["zcode/csp"]` 返回的支持标记；不等于获得文件或网络权限 |
### 现有 `window.zcode` 页面
已有兼容页面可以继续使用以下别名。新页面优先使用官方 App；这两种连接方式选一种即可。
| 类别 | 可用成员 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 连接与观察 | `ready()`、`subscribe(listener)`，后者返回取消订阅函数 |
| 输入与宿主信息 | `toolInput`、`toolOutput`、`toolResponseMetadata`、`toolCancelled`、`hostInfo`、`hostCapabilities`、`hostContext`、`protocolVersion` |
| 展示信息 | `theme`、`locale`、`displayMode`、`maxHeight`、`safeArea`、`userAgent` |
| 工具与资源 | `callTool(name, args)`、`readResource(uri)`、`listResources()`、`listResourceTemplates()` |
| 资源订阅 | `subscribeResource(uri)`、`unsubscribeResource(uri)`、`onResourceUpdated(listener)`、`onResourceListChanged(listener)` |
| 会话视图状态 | `widgetState`、`setWidgetState(state)` |
| 对话协作 | `sendFollowUpMessage({ prompt, structuredContent })`、`updateModelContext({ content, structuredContent })` |
| 展示与文件 | `requestDisplayMode({ mode })`、`notifyIntrinsicHeight(height)`、`openExternal({ href })`、`downloadFile(contents)` |
别名没有 sampling 或页面工具的便捷接口；需要这些能力时使用官方 App。`openExternal` 的参数叫 `href`，官方 `openLink` 的参数叫 `url`，不要混用。
### 最小页面连接示例
这是需要打包到插件 HTML 中的页面代码，不是可直接在普通浏览器标签页中连接宿主的脚本。
```ts
import { App } from "@modelcontextprotocol/ext-apps";
import { EmptyResultSchema } from "@modelcontextprotocol/core";
const app = new App(
{ name: "my-panel", version: "0.1.0" },
{ availableDisplayModes: ["inline", "fullscreen"] },
);
let latestResult: unknown;
app.ontoolresult = (result) => {
latestResult = result.structuredContent;
document.querySelector("pre")!.textContent = JSON.stringify(latestResult);
};
function applyTheme() {
document.documentElement.dataset.theme = app.getHostContext()?.theme ?? "light";
}
app.onhostcontextchanged = applyTheme;
await app.connect();
applyTheme();
async function saveViewState(state: unknown) {
if (!app.getHostCapabilities()?.experimental?.["zcode/widgetState"]) return;
await app.request(
{ method: "ui/set-widget-state", params: { widgetState: state } },
EmptyResultSchema,
);
}
```
页面 HTML 需提供示例中的 ``；实际组件应在挂载后消费已经收到的 `latestResult`。这段代码只处理通信，文档保存仍通过插件服务执行。
## 平台、数据与能力边界
| 数据 / 能力 | 应放在哪里或如何使用 |
| -------------------------------- | ------------------------------------------------------------------------------------------ |
| 业务文档、清理计划、场景版本 | 插件服务持有；文件或数据库写入插件数据目录，按业务规则确认和恢复 |
| 当前活页面输入、滚动和运行中请求 | 同一活页面切内联/侧栏时保留；不重复连接或重发请求 |
| `widgetState` | 临时界面快照；重建、手动重试与进程重启的语义不同，不能用来承诺永久保存 |
| localStorage / IndexedDB | 稳定来源下的浏览器存储，可跨进程；插件身份/工作区/账号隔离，清浏览器数据不等于清插件文档 |
| 网络、字体、WASM、脚本 | 优先随包提供；外部访问受资源 CSP 限制，页面没有 Node 或任意文件系统访问权 |
| 原生权限 | camera / microphone / geolocation / clipboardWrite 需资源声明及宿主/系统授权；不是默认可用 |
当前 HTML 资源上限 **16 MiB**，页面资源读取上限 **8 MiB**；大页面可拆分资源。初始工具结果存在大小限制：`structuredContent` 64 KiB、页面元数据 16 KiB、`content` 32 KiB；超限字段会被省略并标记，页面应从服务重新读取完整数据。
**尚未实现的范围：**纯图片/资源链接的完整消息内容扩展、App 工具双向进度（Showcase SC51/SC52）。已有的文本附图、资源读取、模型工具行进度不能视为这些能力已经齐备。
官方 SDK 的概念与接口入口见 [MCP Apps API](https://apps.extensions.modelcontextprotocol.io/api/) 和 [Quickstart](https://apps.extensions.modelcontextprotocol.io/api/documents/quickstart.html)。宿主行为以本文对应的当前源码和实际能力协商为准，不据此承诺某个已发布版本的兼容范围。
## 宿主源码导航
| 排查目标 | 当前源码入口 |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 能力声明 | [buildPluginUiHostCapabilities.ts](packages/ui/src/plugin-ui/domain/buildPluginUiHostCapabilities.ts) |
| 会话消息、上下文和 widgetState | [pluginUiInteractionPorts.ts](packages/ui/src/plugin-ui/app/pluginUiInteractionPorts.ts) |
| 工具、外链和展示模式 | [pluginUiHostAppHandlers.ts](packages/ui/src/plugin-ui/app/pluginUiHostAppHandlers.ts) |
| 资源订阅 | [pluginUiResourceSubscriptions.ts](packages/ui/src/plugin-ui/app/pluginUiResourceSubscriptions.ts) |
| 页面保留、回收与恢复规则 | [plugin-ui/CONTRACT.md](packages/ui/src/plugin-ui/CONTRACT.md) |
| HTML、资源与 Host 边界 | [plugin-ui-bridge/CONTRACT.md](packages/services/src/plugin-ui-bridge/CONTRACT.md) |
| Electron 沙箱与浏览器存储 | [pluginSandbox/CONTRACT.md](packages/desktop/src/main/pluginSandbox/CONTRACT.md) |
| API 限额、sampling 参数与别名类型 | [MCP Apps 契约](packages/shared/src/mcp-apps/contract.ts)、[sampling.ts](packages/shared/src/mcp-apps/sampling.ts)、[aliasApi.ts](packages/desktop/src/renderer/src/plugin-sandbox/aliasApi.ts) |
| 实际桌面集成测试 | [mcp-apps-host-e2e.mjs](packages/desktop/scripts/mcp-apps-host-e2e.mjs) |
五个插件的业务源码位于独立 `zcode-plugins` 仓库，其根目录也提供 `UI_PLUGIN.md`。本仓库负责宿主，不复制插件成品；宿主 API 变化时同步维护两边文档中英文版的能力与 API 表。
**3. 带着选区继续提问**
输入区出现 **插件上下文** 后，补充“箭头方向是指什么？”，再点击发送。引用选区会先添加待发送的上下文；发送问题时，Agent 才会收到问题和选区信息，理解用户问的是画布中的哪一部分。
### 五分钟演示路线
安装并启用 `excalidraw` 后，在一个桌面本地工作区的新会话里依次操作：
1. 发送：“用 Excalidraw 画一个 API、缓存和数据库的架构图，标出请求方向。”模型调用 `create_diagram`，侧栏打开可编辑画板。
2. 拖动节点、改颜色或文字，等待页面显示“已保存”。这表示后端已确认保存。
3. 选中“缓存”节点，右键选择“引用选区到对话”；发送：“把选中的缓存改成双节点，保留其他布局。”未选中元素时也可以引用整图。
4. Agent 用 `read_scene` 读取最新版本，再用稳定元素 ID 执行 `apply_operations`，无需重画整个画布。用户编辑和工具编辑共用当前页面的撤销/重做。
5. 点击画板标题切换或导入文档；通过“导出”保存 `.excalidraw`、PNG、SVG 到工作区，覆盖已有文件需要明确选择覆盖。
```mermaid
sequenceDiagram
participant U as 用户 / 画板
participant A as Agent
participant S as 插件 MCP 服务与文档库
A->>S: create_diagram
S-->>U: 文档 ID、revision 与页面
U->>S: commit_scene（手工编辑）
S-->>U: 确认保存、新 revision
U->>A: 引用选区 + 修改要求
A->>S: read_scene → apply_operations
S-->>U: 最新文档
U->>S: 导出到工作区
```
### Excalidraw 工具表
下面是插件自己的 MCP 工具，和后文的通用页面 API 是两个层次。“仅页面”工具不会暴露到模型工具列表。
| 工具 | 调用方 | 用途与关键参数 |
| ------------------ | ---------- | -------------------------------------------------------------------- |
| `create_diagram` | 模型、页面 | 用 `title`、`elements` 新建画板；返回文档 ID 和版本 |
| `open_diagram` | 模型、页面 | 用 `id` 打开已保存文档，或用 `path` 导入工作区 `.excalidraw`；二选一 |
| `read_scene` | 模型、页面 | 读取当前版本和元素摘要；可用 `elementIds` 限定选区 |
| `apply_operations` | 模型、页面 | 按元素 ID 增、改、删；携带 `expectedRevision` 与 `operationId` |
| `export_diagram` | 模型、页面 | 导出原生 `.excalidraw`；检查版本，覆盖需 `overwrite: true` |
| `commit_scene` | 仅页面 | 提交完整编辑草稿，执行版本冲突检查 |
| `list_diagrams` | 仅页面 | 列出当前工作区文档 |
| `save_copy` | 仅页面 | 将草稿或导入内容另存为新文档 |
| `save_image` | 仅页面 | 将页面渲染的 PNG / SVG 写入工作区 |
业务文档在插件数据目录内以 SQLite 保存，按工作区隔离。版本冲突会保留本页草稿，可另存副本或重载；相同操作重试复用 `operationId`。`widgetState` 只保存视图信息，不能代替文档库。
当前每份文档最多 5000 个元素、6 MiB。编辑器和字体随包提供，不依赖 CDN。撤销历史只属于当前活编辑器，不跨应用重启保存；当前未提供多人实时协作、系统剪贴板权限或云分享。
## Gen UI：按需生成可交互的回答
Gen UI（生成式界面）让 Agent 针对当前问题生成 HTML / JavaScript 页面，直接嵌入对话。你可以拖动滑块、切换条件、勾选项目，观察结果，再带着当前参数继续提问。每个页面按需生成，无需先为它创建和安装插件。
### Gen UI 界面示例
下面是一组按需生成的能力演示页面。分组和内容展示了页面可以如何组织，不是应用里的固定界面。点击图片可查看原图。
| 组件与信息组织 | 控件驱动计算 |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 
|
| 用摘要卡片、进度条、表格和图标，把回答组织成可浏览的面板。 | 通过增长率滑块、复利开关和基线选项，对比不同参数下的计算结果。 |
| 图表与数据对比 | 日历与日程 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 
| 
|
| 折线图对比 P50 / P95 趋势，柱状图展示各分位；图中为示例数据。 | `viz-calendar` 按时间段展示日程，并支持查看事件详情；这里是页面内的日程演示。 |
| 状态保存与追问 | 设计预览与调整 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 
| 
|
| 将偏好和参数组织成 `modelContent` / `privateContent` 快照。画面展示待保存状态；页面可保存参数，再通过按钮发起追问。 | `viz-carousel` 展示多种播放器设计，配合 Tweak 调整样式；这是界面原型。 |
在支持 Gen UI 的 ZCode Desktop 会话中，可以直接提出下面这样的请求。具体控件和交互由 Agent 根据任务生成：
| 场景 | 示例提示词 | 可以如何交互 |
| ------------ | --------------------------------------------------------------------------------------------- | --------------------------------------------- |
| 理解概念 | “用 Gen UI 解释正弦波，让我拖动滑块调整振幅和频率，观察曲线变化。” | 调整参数、比较曲线，理解变量之间的关系 |
| 探索算法 | “用 Gen UI 做一个二分查找演示，能输入目标值、单步执行，并标出当前搜索区间。” | 修改输入、前进和重置，观察每一步的状态 |
| 调整界面方案 | “用 Gen UI 做一张课程卡片，提供 Tweak 控件调整圆角、配色和布局密度，再按我选的参数继续完善。” | 即时预览样式，明确提交调整后让 Agent 继续修改 |
```mermaid
flowchart LR
A[用户提出问题] --> B[Agent 生成 HTML 页面]
B --> C[桌面端在对话中展示]
C --> D[用户操作控件并保存状态]
D --> E[用户明确发送后续问题]
E --> F[Agent 结合当前参数继续回答]
```
### 能力与页面接口
| 能力 | 当前行为 |
| ---------- | ------------------------------------------------------------------------------------------ |
| 对话内交互 | 页面随回答完成后展示，可包含图表、表单、模拟器和轻量原型 |
| 展开与分享 | 可以展开预览、收起，并复制当前界面为图片；展开和收起保留同一个活页面 |
| 状态与追问 | 页面可保存控件状态，并在用户触发后发送后续问题；仅调整控件或保存状态不会自动启动 Agent |
| Tweak 调整 | 页面注册控件后，宿主提供滑块、颜色、开关和选项等调整入口，支持重置、原始效果预览和明确提交 |
生成页面使用宿主注入的 Gen UI 接口：
| 接口 | 用途 |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `window.zcode.widgetState` | 读取已保存的页面状态，初始值可能为 `null` |
| `window.zcode.setWidgetState({ modelContent, privateContent })` | 替换整个 JSON 状态快照，合计不超过 16 KiB；只有 `modelContent` 会进入下一轮模型上下文 |
| `window.zcode.sendFollowUpMessage({ prompt, title })` | 发送后续问题，`title` 可选；没有有效用户操作时需要确认，失效或只读会话不能发送 |
| `zcode:set_globals` | 监听状态或主题更新，从事件的 `detail.globals` 读取新值 |
桌面端会向 Agent 提供当前会话的专用输出目录。生成的 HTML 保存在该目录，由宿主加载，不写入项目工作区；页面状态按工作区和会话隔离。页面桥接由宿主注入，作者不用再创建 MCP Apps 连接。Gen UI 页面不提供 `callTool`、MCP 资源读取、Node 或任意文件访问；需要插件服务执行操作时使用 UI Plugin。
### Gen UI 与 UI Plugin 怎么选
| 对比项 | Gen UI | UI Plugin |
| -------- | ------------------------------------------------ | --------------------------------------------------- |
| 来源 | Agent 围绕当前问题即时生成页面 | 开发者维护和发布插件，用户安装、启用 |
| 适合什么 | 概念讲解、交互图表、模拟器、临时计算器和界面原型 | 持续使用的编辑器、文件工具和带业务数据的应用 |
| 页面能力 | Gen UI 状态、追问与 Tweak 接口 | MCP Apps API、插件 MCP 工具与资源，遵循宿主支持范围 |
| 数据归属 | 宿主管理生成文件和会话页面状态 | 插件服务管理业务文件或数据库，页面管理视图 |
上面的 Excalidraw 截图展示的是 **UI Plugin**。如果需要按当前问题生成一个可调参数的小页面，使用 **Gen UI**；如果要分发一个长期使用、带服务和文档管理的工具，开发 UI Plugin。两者虽都可能出现 `window.zcode`，可用方法和状态结构不同，不能混用。UI Plugin 的开发与 API 见[开发与调试](#开发与调试)和[页面 API 速查](#页面-api-速查)。
实现与页面示例：[Gen UI 契约](packages/ui/src/gen-ui/CONTRACT.md)、[页面 API 示例](apps/zcode-cli/packages/visualize-plugin/skills/visualize/references/api.md)、[Tweak 指南](apps/zcode-cli/packages/visualize-plugin/skills/visualize/tweak.md)。桌面集成验证入口为 `node packages/desktop/scripts/gen-ui-e2e.mjs`。
## 其他示例插件
| 插件 | 功能与演示指令 | 适合参考什么 | 当前边界 |
| ----------------------------- | -------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Excalidraw** `excalidraw` | “画一张系统架构图，再按选区修改” | 画布、自动保存、局部编辑、上下文引用和导出，建议作为首个完整示例 | 本地工作区；持久文档与临时视图分开 |
| **OpenPencil** `openpencil` | “新建设计稿 designs/landing.fig，放一个 hero 区块” | `.fig` 设计稿、设计工具、选区引用与按稿生成代码 | 一个工作区一个活编辑器；`.pen` 只读导入；导出到 `exports/` |
| **Blender** `blender` | “新建一个 Blender 场景，放置物体并渲染预览” | `.blend` 场景、3D 预览、材质、相机、灯光和渲染资源 | 真实操作需要 Blender 引擎；假引擎仅用于测试 |
| **磁盘清理器** `disk-cleaner` | “看看下载目录里哪些大文件占空间” | 只读扫描、分页筛选、候选选择、确认计划与执行反馈 | 清理工具仅供页面使用；确认后移入回收站，不提供永久删除 |
| **Showcase** `showcase` | “用 Showcase 演示全部 case” | SC01–SC53 目录；资源、消息、状态、sampling、页面工具和失败场景 | 目录项分直接操作、配合操作、自动化专用、待实现；53 项不代表 53 项都已实现或自动验收 |
## 开发与调试
### 两个仓库分别负责什么
| 仓库地址 | 分支 | 修改范围 | 运行位置 |
| ----------------------------------------------------------------- | ---------------- | ---------------------------------------------- | ------------------------------------------------------- |
| [zai-org/ZCode](https://github.com/zai-org/ZCode) | `feat/ui-plugin` | 宿主协议、侧栏和内联展示、沙箱、审批与生命周期 | `pnpm dev:desktop` |
| [zai-org/zcode-plugins](https://github.com/zai-org/zcode-plugins) | `feat/ui-plugin` | 插件清单、MCP 服务、页面、业务数据与资源打包 | `ui-plugins/