1# 工作台模块运行时与交互规范调研：小组件、声明式卡片与代码沙箱
2
3> **日期**：2026-09-25。**性质**：技术调研（事实带出处，推断单独标注），不是裁决。**起因**：白晨 0925 提出 AI 工作台底座要像 iOS 界定小组件交互那样，规定插件模块支持的尺寸、交互与能力（点击、流式输出、动画等），保证第三方插件装上后稳定；不同顶层应用风格各异，顶层应用里的 AI 还能基于数据接口生成新的展示模块（皮肤）并上架。本文由子代理只读调研一手文档产出，维护者未改写结论。姊妹篇：[插件宿主调研：Dify plugin daemon](2026-09-25-插件宿主调研-Dify-plugin-daemon.md)。前序：[苹果小组件开发者规范演进与 AI 工作台借鉴（0913）](2026-09-13-苹果小组件开发者规范演进与AI工作台借鉴.md)、[插件定义与工作台交互（0912 附件一）](2026-09-12-个人AI工作台两条路径能力拆解-附件-插件定义与工作台交互.md)。
4>
5> **本轮白晨已定（0925 会话，口头）**：**声明式＋代码档都做**（维护者原建议 10 月只做声明式、代码档只留位置，白晨未采纳）；10 月隔离取第一档，只接自有与共建方插件。下文第一节第 7 条的「建议」是调研时的推断，与此裁决不一致处以裁决为准。
6
7调研方式：tavily 当日额度用尽，改用 crawl4ai 直读页面、Apple 与飞书官方文档的 JSON 接口、GitHub API；firecrawl 只用于找链接。数据截止 2026-09-25。
8
9## 一、一页结论
10
111. **业界分两条路**。「声明式」：插件只给数据，从宿主提供的有限组件集里拼界面，宿主负责渲染与样式——WidgetKit、Glance、飞书卡片、钉钉互动卡片、Adaptive Cards、Raycast、A2UI。「代码沙箱式」：插件或 AI 给任意 HTML／JS，跑在 iframe 沙箱里、经消息桥与宿主通信——MCP Apps、OpenAI Apps SDK、Figma 插件界面。
122. **iOS 的稳定靠「宿主渲染、插件不在场」**（事实）：小组件代码在独立进程，系统先把视图归档再自行渲染，渲染时不运行插件代码；交互只能是 Button／Toggle 触发 App Intent，执行后系统重载时间线；刷新另受每日预算约束。
133. **普遍允许**：点击跳转、按钮动作、开关、刷新、限时动画；声明式卡片额外允许表单输入与选择器；飞书、钉钉允许流式文本（打字机效果）。
144. **普遍限制**：任意手势、嵌套滚动、深层导航、视频（小组件场景）、宿主外网络与域名访问（沙箱场景要逐个声明白名单）。
155. **宿主风格适配两派都有答案**：声明式由宿主定样式、插件只写语义值（Adaptive Cards 的 HostConfig，原则「内容归作者，外观归宿主」）；沙箱式由宿主下发一组标准 CSS 变量、插件自带兜底值（MCP Apps）。
166. **AI 生成皮肤两条路都有实证**：Google A2UI 专为模型生成声明式 JSON 设计；Google Research 论文证明模型直接生成 HTML 能稳定产出高质量界面，但单次可能一分钟以上、偶有错误。
177. **建议（推断，已被白晨 0925 裁决部分取代，见页首）**：声明式为默认档，AI 生成的皮肤默认只产出声明式描述（可机器校验、可审核、可套顶层应用主题）；代码沙箱作「高级档」只开放给审核过的插件，照搬 MCP Apps 的沙箱、CSP（内容安全策略，限定页面能加载哪些来源）与消息桥做法。尺寸用网格单位＋宿主最终裁决（同 Android）。
18
19## 二、各对象要点
20
21**Apple WidgetKit**（事实）
22- 尺寸族：systemSmall／Medium／Large／ExtraLarge／ExtraLargePortrait，外加 accessoryCircular／Corner／Rectangular／Inline。https://developer.apple.com/documentation/widgetkit/widgetfamily
23- iPhone 点数随机型变，如 430×932 屏上 Small 170×170、Medium 364×170、Large 364×382；官方要求弹性布局、不用固定值。https://developer.apple.com/design/human-interface-guidelines/widgets
24- 刷新预算：通常每天 40～70 次（约 15～60 分钟一次），时间线条目间隔至少约 5 分钟；宿主应用在前台、用户点按钮／开关、播放动画等不计预算。https://developer.apple.com/documentation/widgetkit/keeping-a-widget-up-to-date
25- 交互：iOS 17 起只有 Button 与 Toggle，绑定 App Intent（应用把动作暴露给系统的接口），每次交互保证重载时间线；Toggle 先乐观更新、以结果为准；按钮之外一律「打开 App」。https://developer.apple.com/documentation/widgetkit/adding-interactivity-to-widgets-and-live-activities
26- 限制的原因原文写明：代码在独立进程，系统归档视图后渲染，渲染时「无法运行你的代码或更新数据绑定」（同上）。
27- 不支持："don't generally support interactive elements such as scrolling lists or text input"；小组件不做实时更新，实时场景改用 Live Activities。https://developer.apple.com/documentation/widgetkit/creating-a-widget-extension
28- 动画：单次最长 2 秒；常亮显示下不播放（省电）。https://developer.apple.com/documentation/widgetkit/animating-data-updates-in-widgets-and-live-activities
29
30**Android App Widgets／Jetpack Glance**（事实）
31- 手势只有「触摸」和「竖向滑动」（横滑被桌面翻页占用）。https://developer.android.com/develop/ui/views/appwidgets/overview
32- 尺寸按桌面网格单元（targetCellWidth／targetCellHeight），用户在 min 与 max resize 之间拖；手机常见 5×4 网格。https://developer.android.com/develop/ui/views/appwidgets/layouts
33- updatePeriodMillis 最短 30 分钟。https://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo
34- Glance 只给 Box／Row／Column／LazyColumn 等受限组件；尺寸策略 SizeMode.Single／Exact／Responsive 三选一，系统挑最贴合的布局。https://developer.android.com/develop/ui/compose/glance/build-ui
35- 交互：点击回调（clickable 接 lambda 或 actionRunCallback）或启动 Activity。https://developer.android.com/develop/ui/compose/glance/user-interaction
36
37**飞书**（事实）
38- 卡片 JSON 2.0 组件分三类：容器（分栏、表单、交互容器、折叠面板）、展示（文本、markdown、图片、人员、图表〈VChart〉、表格）、交互（输入框、按钮、下拉单选／多选、人员选择、日期／时间选择等）。https://open.feishu.cn/document/feishu-cards/card-json-v2-components/component-json-v2-overview （2025-01 更新）
39- 每卡最多 200 个元素；宽度三档：默认 600px、compact 400px、fill 撑满；颜色分浅／深两套，字号分端配置。https://open.feishu.cn/document/feishu-cards/card-json-v2-structure （2025-06）
40- 回调：用户交互后开发者服务端须 3 秒内响应（弹 Toast、更新卡片或不变）。https://open.feishu.cn/document/feishu-cards/card-callback-communication
41- 流式：`streaming_mode` 打字机效果，可配频率与步长；单卡接口上限 10 次／秒。https://open.feishu.cn/document/feishu-cards/streaming-updates-openapi-overview
42- 工作台小组件（Block）走代码型：小程序式 DSL（ttml／ttss／js），上传后服务端编译，发布需管理员审核；「标准小组件」高度固定 150px、宽度随工作台拉伸，「非标准小组件」尺寸由开发者定。https://open.feishu.cn/document/client-docs/block/hosting-scenario-introduction/workplace 、https://open.feishu.cn/document/client-docs/block/block-frame/directory-structure
43
44**钉钉**（事实）
45- 互动卡片由「模板＋数据」驱动，有回调地址，并有「AI 卡片流式更新」接口（打字机效果）；类型含消息卡片、标准卡片（跨场景自适应但组件较少）、吊顶卡片（尺寸固定）、工作台卡片。https://open.dingtalk.com/document/development/overview-card （2026-07 更新）
46
47**Microsoft Adaptive Cards**（事实）
48- 原则「无 code behind」：宿主永不运行第三方代码，交互只靠声明式标记；「内容归作者，外观归宿主」：作者只写语义色、语义尺寸；宿主可以不渲染输入与动作。https://learn.microsoft.com/en-us/adaptive-cards/resources/principles
49- HostConfig（宿主配置对象）统一规定字体、字号档、语义色、间距档、最多几个动作（默认 5）、是否允许交互（supportsInteractivity）。https://learn.microsoft.com/en-us/adaptive-cards/rendering-cards/host-config
50- Action.Execute 加 refresh 可在展示时自动刷新；Teams 限定最多对 60 个用户自动刷新，其余手动点——防服务端被同时打爆。https://learn.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model
51
52**MCP Apps（SEP-1865）**（事实）
53- 已有稳定版 `specification/2026-01-26`，draft 仍在更新（最近提交 2026-07-22），本文读的是 draft。https://github.com/modelcontextprotocol/ext-apps/tree/main/specification
54- 界面预先声明为 `ui://` 资源，MIME `text/html;profile=mcp-app`；要求预声明而非随结果内联，是为了宿主能预取、审核、做哈希白名单。
55- 沙箱：必须 iframe 沙箱，Web 宿主要多套一层不同源的沙箱代理；CSP 由宿主按声明的域名构造，未声明时用严格默认值。
56- 通信：一律可审计的 JSON-RPC over postMessage（经浏览器跨框消息接口传递的结构化调用）。
57- 显示模式 inline／fullscreen／pip（画中画）；容器尺寸 fixed（宿主定）／flexible（插件定、有上限）／unbounded 三种，插件用 size-changed 上报尺寸。
58- 主题：宿主下发标准 CSS 变量（颜色、字体、圆角），插件自带兜底值；有意不含间距变量（「间距一变布局就坏」），也不提供组件库（「没有一个库能适配所有宿主」）。
59- 流式：tool-input-partial 让界面随模型流式参数渐进渲染，但规范要求不得据此执行关键操作。
60- 出处：https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx
61
62**OpenAI Apps SDK**（事实）
63- 已改为以 MCP Apps 为底座，`window.openai` 只作扩展（结账、文件、状态持久化等）；CSP 必须逐域声明，嵌套 iframe 默认禁止，审核核对声明与实际行为是否一致。https://developers.openai.com/plugins/build/chatgpt-ui
64- 设计约束：inline 卡片最多 2 个动作；卡内不做深层导航或多视图；禁止嵌套滚动；轮播 3～8 项；不许改系统色、不许用自定义字体。https://developers.openai.com/plugins/concepts/ui-guidelines
65
66**Figma 插件**（事实）
67- 插件逻辑跑在主线程的最小 JS 沙箱（无 DOM、fetch、setTimeout），界面另开 iframe，两边只能互传消息；网络访问可在 manifest 里限定域名。https://developers.figma.com/docs/plugins/how-plugins-run/
68
69**其他**（事实）
70- **A2UI**：v0.9.1 为当前生产版，v1.0 为候选版；模型输出扁平 JSON 组件列表，客户端只从自己的可信 catalog（可用组件目录）取组件、用原生组件渲染，不用 iframe；设计上照顾模型生成：可增量、可流式、可局部纠错。https://a2ui.org/ 、https://a2ui.org/introduction/what-is-a2ui/
71- **Raycast**：扩展用 React 写，但只能用 List／Grid／Detail／Form＋ActionPanel，由 Raycast 渲染成原生界面。https://developers.raycast.com/api-reference/user-interface
72- **Vercel AI SDK**：生成式 UI 是「工具调用结果 → 开发者预写的 React 组件」；RSC 路线（streamUI）标实验性，官方建议生产不用。https://ai-sdk.dev/docs/ai-sdk-ui/generative-user-interfaces
73
74## 三、两类做法对照
75
76| 维度 | 声明式（组件集＋数据） | 代码沙箱式（HTML／JS 进 iframe） |
77|---|---|---|
78| 稳定性 | 高：宿主渲染，插件崩了不影响渲染（WidgetKit 归档机制） | 中：靠隔离兜底，页内卡死、白屏仍会发生 |
79| 安全 | 高：没有第三方代码执行（Adaptive Cards 原则） | 靠沙箱＋CSP＋消息校验＋审计层层把关（MCP Apps 威胁模型） |
80| 宿主风格适配 | 天然：宿主掌握主题（HostConfig） | 靠 CSS 变量＋插件自觉；间距这类难统一 |
81| AI 生成 | 按 Schema 结构化输出、可机器校验（A2UI） | 表现力强、有实证，但慢（可一分钟以上）、偶有错误 |
82| 审核 | 可静态校验全部字段 | 静态看代码＋对照 CSP 抽查实际行为，成本高 |
83| 表现力上限 | 受组件集限制 | 几乎不设限（地图、画布、游戏） |
84| 性能 | 原生组件，轻 | 每模块一个 iframe，内存与启动开销大（推断） |
85
86## 四、交互能力清单（业界共识）
87
88- **普遍允许**：整体点击跳转（WidgetKit widgetURL、飞书 card_link）；按钮动作回调（App Intent、飞书 3 秒内响应、Adaptive Cards Action.Execute）；开关（Toggle、飞书勾选器）；刷新（定时或推送，受预算与频率限制）；限时动画（Apple 单次 ≤ 2 秒）；表单与选择器（只在卡片类，小组件类不支持）；流式文本（飞书、钉钉、MCP Apps partial）。
89- **普遍限制**：横滑与任意手势（Android 只给触摸和竖滑）；滚动（Apple 限制、OpenAI 禁嵌套滚动）；深层导航与多视图（OpenAI 明确禁止）；文本输入（小组件类限制）；实时连续更新（Apple 引导改用 Live Activities）；动作数量（HostConfig 默认 5、OpenAI 最多 2）；未声明的网络域与嵌套 iframe（Figma、MCP Apps、OpenAI）；宿主可整体关交互（supportsInteractivity=false）。
90
91## 五、尺寸体系
92
93- 两种定义：iOS 用「命名尺寸族」、点数交给系统按设备定；Android 用「网格单元＋最小最大可拖范围」。卡片类只定宽度档（飞书 400／600／撑满），高度自适应；MCP Apps 用 fixed／flexible／unbounded 协商。
94- 对我们 1×1～4×4 网格的启发（推断）：插件在清单里声明「支持哪些档位＋最小／默认／最大」，像素换算留给宿主；每个档位一份专门布局，不把小尺寸内容拉伸去填大格（Apple HIG 原文要求）；拖动调整大小时宿主从声明的档位里选最贴合的布局（Glance Responsive 思路）；模块内部禁止滚动，尺寸才有意义。
95
96## 六、对 AI 生成皮肤的含义
97
98- **生成声明式描述**：受 Schema 约束，可校验、可自动纠错、可流式渲染（A2UI 设计要点）；上架审核可纯机器做，天然继承顶层应用主题。风险：表现力被组件集封顶；组件集太小 AI 做不出差异化，一扩张又会遇到 Adaptive Cards 式「宿主支持版本不一」的兼容问题（推断）。
99- **生成代码**：Google 论文（arXiv 2604.09577）评测，生成的 HTML 在人类评审中远优于 markdown 输出，约 50% 与专家作品相当，但评测未计速度，单次可一分钟以上、偶有错误。https://arxiv.org/abs/2604.09577 、https://research.google/blog/generative-ui-a-rich-custom-visual-interactive-user-experience-for-any-prompt/ 风险：每份生成物都要走沙箱＋审核，风格一致性只能靠提示词与 CSS 变量。
100- **业界实践**：Gemini「dynamic view」上线的是代码路线；A2UI、Vercel AI SDK 是「模型选组件、开发者预写组件」；MCP Apps 为可审核要求界面预声明、不许运行时内联。
101
102## 七、规范章节骨架（只列每章要定的事）
103
1041. **术语与分层**：插件、数据接口、模块、皮肤、宿主（顶层应用）各指什么。
1052. **模块清单（manifest）**：标识、版本、绑定哪些数据接口的 Schema、支持档位、所需能力、权限声明。
1063. **尺寸与布局**：网格档位集合；最小／默认／最大；每档一份布局；安全边距；禁内部滚动。
1074. **渲染档位**：声明式档（组件目录与版本）、沙箱档（准入条件）；两档的降级与兜底。
1085. **组件目录**：展示／容器／交互类清单；每组件属性与语义取值；目录版本与兼容策略。
1096. **交互能力**：允许的交互清单；动作数量上限；动作到数据接口的绑定；乐观更新与回执时限；禁止的手势。
1107. **数据与刷新**：拉取与推送；刷新预算与频率上限；缓存与过期展示；离线态、加载态、错误态。
1118. **流式与动画**：流式文本节流参数；动画时长上限；「减少动态效果」下的降级。
1129. **主题与风格适配**：宿主主题令牌表（HostConfig 或 CSS 变量）；插件可用的语义值；禁止覆盖项。
11310. **沙箱运行时（代码档）**：iframe 隔离方式、CSP 与域名白名单、消息桥方法表、尺寸上报、生命周期（初始化到销毁）、崩溃与超时处理。
11411. **AI 皮肤生成**：输出格式约束、校验流程、回退规则、生成物与数据接口 Schema 的对应。
11512. **审核与上架**：静态校验项、沙箱档人工审核项、哈希或签名、下架与熔断。
11613. **性能与可观测**：每模块资源上限、首屏时限、日志与审计。
11714. **版本与兼容**：规范版本号、宿主能力协商、弃用流程。
118
119## 八、未核实项
120
121- WidgetKit 不支持视频与任意手势：只找到「通常不支持滚动列表与文本输入」原文，视频与手势的明确禁止未找到一手出处。
122- 飞书工作台小组件（Block）可用组件集、交互限制、刷新机制未读到对应文档。
123- 钉钉工作台卡片尺寸与组件清单未深读。
124- Adaptive Cards 的 fallback／requires 降级机制：一手页面需登录，未读到。
125- MCP Apps 读的是 draft，未逐条比对 2026-01-26 稳定版差异。
126- Glance 底层转 RemoteViews、各家性能开销的量化：未核实，文中凡涉及处标推断。