WorkFly 把内置功能与第三方应用放在同一套「小程序」模型里：可安装、可权限门控、可向会话与首页贡献界面，也可把只读能力交给内部 Agent 或外部 MCP。本章说明为什么这样拆，以及你在 Manifest 里声明的每一类东西分别服务谁。
一句话模型
完整页在沙箱里跑业务；原子能力用 Tool 声明；过程知识用 Skill 书写；挂进宿主的卡片与磁贴是高信任 Surface；对外给 AI 的只有带
expose的 Tool 数据，不是 UI。
四层能力（L0–L3）
| 层 | 名称 | 你在包里放什么 | 谁消费 |
|---|---|---|---|
| L0 | 壳与完整页 | manifest 身份、权限、ui.standalone、Hash 路由 |
安装器、小程序面板、深链 |
| L1 | Agent 能力 | tools（launch / 只读 query）、skills（SKILL.md） |
内部 Agent；expose: true 的 tool → MCP |
| L2 | 宿主 UI Surface | React UI Module + cardRenderers / widgets |
会话流、home、Spotlight |
| L3 | 桥 | resultCard、summary、openApp、expose、suggestions |
把 L1 结果接到 L2 或外部 AI |
依赖只能单向：Skill 引用 Tool 名；Tool 可选桥到 Card；Card/Widget 可 openApp 进完整页。不要让 Skill 正文绑定某个 React 组件路径。
Skill · Tool · Script
| 概念 | 是什么 | 典型形态 |
|---|---|---|
| Tool | 可调用的原子能力：有名字、参数、确定结果 | 打开某路由；或宿主代发的只读 HTTPS 查询 |
| Skill | 多步玩法：何时调哪些 Tool、业务口径与禁区 | SKILL.md 正文给模型读 |
| Script | 实现零件（可选） | 本地脚本或未来高信任可执行体；默认不等于对外 Tool |
红火台一类业务应用：Skill 几乎是纯说明，Tool 是声明式 query——这是正常形态，不是「缺了 script」。
完整页 vs 宿主 Surface
- Sandbox 完整页（默认）：React / Vue / Vanilla 均可；进程隔离；联网走
wf.request；登录只拿一次性code。 - React UI Module（可选、高信任）：只用于会话卡、home / Spotlight 磁贴等直接嵌进宿主的组件；external 宿主 React 19；安装前风险确认。
- 没有嵌入需求时，省略
ui.modules与自定义 card/widget，仍可做完整应用，并贡献 Skill 与 Tool。
与 AI / MCP 的边界
| 通道 | 得到什么 | 得不到什么 |
|---|---|---|
| 内部 Agent | launch/query Tool；共享卡；Skill 召回；本地 suggestions | 宿主 Token |
| 外部 MCP | expose: true 的 Tool 结果（字段白名单） |
会话卡 DOM、suggestions、业务会话明文 |
| 统一 CLI（规划中） | 更稳的 MCP 桥与诊断命令 | 不是第二套业务 tools 清单 |
| 小程序内宿主 AI | wf.ai.complete 纯补全（用户已配模型）；wf.im.* 当前会话只读 |
主 Agent 全工具面、裸 ACP、任意会话扫库 |
expose 表示「可进入对外 MCP 投影」，还要用户给连接勾选 miniapp:read / miniapp:launch。页面内 wf.login 等权限与 MCP scope 相互独立。
IM 工具栏等固定入口用 contributes.imEntries（有图标）；正文匹配用 contentMatchers。入口打开后注入 chatId 等 query，再配合 im.chatContext / ai.complete 做「自定义提示词 + 会话总结」类产品。见 开发指南 · IM 入口与宿主 AI。
安全默认
- 沙箱禁止页面
fetch与外链脚本；网络经宿主代理。 - 权限分 normal / runtime / operation / restricted，等级由平台固定。
- 声明式 query 必须
readOnly、固定 HTTPS 主机、不跟随重定向、限制体积与字段。 - 宿主原始会话 Token 不对第三方开放。
设计理念摘要
- 渐进复杂度：先能装能开页，再贡献 AI 查询，最后才上高信任 Surface。
- 声明优于暗魔法：路由、权限、贡献点写在 Manifest，打包与安装同一套规则校验。
- 对话优先、打开渐进：Agent 默认出卡或入口，不自动抢走当前会话。
- 双通道结果：给人看的卡与给模型的
summary/ 结构化投影必须同时成立。 - 一处声明、多端消费：同一 Tool 可服务内部 Agent 与外部 MCP，UI 是可选增强。
下一步
- 按档位搭工程 → 上手阶梯
- 字段与调试细节 → 开发指南
- 对照真实包 → CURL 与红火台
- 会话卡与建议 → 会话与 Surface