上手阶梯 · WorkFly 起飞工作台

不要一次学完 Manifest 的全部字段。按你现在要交付的东西选档，跑通后再升档。官方案例也按同一阶梯：CURL 停在「最小可用 + 可选一张卡」；红火台走到「业务会话 + 查询 Tool + Surface + Skill + MCP」。

三档对照

档位	你要交付	工程里有什么	不必有什么	对照案例
0 · 最小页	可安装完整页，能调 `wf`	`manifest` + 页面 + 真权限	tools、skills、UI Module	Hello 级；CURL 的主体
1 · 会说话	Agent / MCP 能查或打开你的能力	档 0 + `contributes.tools`（+ 可选 Skill）	自定义会话卡/磁贴	红火台的 query/launch 层
2 · 嵌进宿主	会话卡、home/Spotlight 磁贴	档 1 + React UI Module + card/widget 注册	—	红火台 Surface；CURL 的请求摘要卡

脚手架：vanilla / react-ts / vue-ts → 档 0；需要卡/磁贴再选 react-ui-ts（高信任提示）。

目标： 拖进客户端能打开，能发一次 wf.request 或写本地存储。

npm create @workfly/app my-app -- --template react-ts
cd my-app && npm install
npm run dev    # 浏览器内循环
npm run build  # 出 .wfapp.zip，拖进「小程序」面板验证

Manifest 只要： 身份、manifest: 2、ui.standalone（sandbox + full + routing）、launchers、真实用到的 permissions。

硬约束：

验收： 安装后冷启动、刷新、权限拒绝提示符合预期。

目标： 用户对主助手说「查我的订单」时，能走你的只读 query，或打开你的页面入口——而不是只能「请用户自己点开应用」。

推荐在工程根增加（不要预建空目录）：

capabilities/tools/<name>.json
capabilities/skills/<id>/SKILL.md

与内联 contributes.tools 等价，由 @workfly/miniapp-kit 在 build 时合并：

query：固定 HTTPS、readOnly: true、字段白名单；可用 workfly.sessionKey / workfly.expose。
launch：打开已声明 path；可配 workfly.resultCard（内部 Agent 不自动导航）。

Skill 的 id/name/description 只写在 frontmatter。

验收：

目标： 余额/订单等摘要直接出现在会话或 home 磁贴，点击再进完整页。

增加：

ui.modules（workfly-react@1、Shadow CSS）
surfaces/cards.json 与 surfaces/widgets.json（mode: "react" + module + component；也可内联 contributes）
Tool 的 resultCard.kind 指向已注册 kind
可选 suggestions（最多 4 条；查询用 send，有副作用用 fill）

验收： 安装出现高信任确认；卡宽高与主题 token 正常；磁贴随拖拽跨度改布局；来源行可点回应用。

目标： 在群聊/单聊工具栏挂一个图标，打开后读取当前会话历史，用你的提示词调 WorkFly AI 流式输出（例如「总结精彩」「提取待办」）。这是 档 0 完整页 + 贡献点 + 宿主只读/补全 API，不必上 React UI Module。

工程要点：

surfaces/im-entries.json（或 contributes.imEntries）：placement（如 composer.toolbar.end）、icon/label/tooltip、launch.path，建议 presentation: "popover"。
权限：im.chatContext（历史/上下文）、ai.complete（纯补全，无工具）。
打开后读 wf.getLaunchOptionsSync().query（chatId 等）→ wf.im.getHistory → 本地筛选 → wf.ai.complete({ system, prompt, onChunk })。

验收：

明确不做： 裸 ACP/本机 CLI、代发 IM、扫其它会话、把主 Agent 全工具面交给第三方包。