miniapp-dev
Generate, operate, and refine OpenBitFun MiniApps. Use when the user wants a new MiniApp, asks the Agent to inspect or operate a running MiniApp, or wants an existing MiniApp redesigned or extended. Typical triggers: "做一个小应用", "操作这个 MiniApp", "查看小应用当前状态", "改造 mini app".
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 4.0k
- Forks
- 305
01 前言 Front Matter
- name
- miniapp-dev
- description
- Generate, operate, and refine OpenBitFun MiniApps. Use when the user wants a new MiniApp, asks the Agent to inspect or operate a running MiniApp, or wants an existing MiniApp redesigned or extended. Typical triggers: "做一个小应用", "操作这个 MiniApp", "查看小应用当前状态", "改造 mini app".
02 资源文件 56
- 参考文档api-reference.md23.6 KB
- 参考文档design-playbook.md13.0 KB
- 参考文档references/examples/builtin-coding-selfie/index.html10.0 KB
- 参考文档references/examples/builtin-coding-selfie/meta.json1.8 KB
- 参考文档references/examples/builtin-coding-selfie/style.css22.6 KB
- 脚本references/examples/builtin-coding-selfie/ui.js52.8 KB
- 脚本references/examples/builtin-coding-selfie/worker.js387 B
- 参考文档references/examples/builtin-daily-divination/index.html5.4 KB
- 参考文档references/examples/builtin-daily-divination/meta.json1.7 KB
- 参考文档references/examples/builtin-daily-divination/style.css45.5 KB
- 脚本references/examples/builtin-daily-divination/ui.js68.9 KB
- 脚本references/examples/builtin-daily-divination/worker.js120 B
- 参考文档references/examples/builtin-gomoku/index.html4.9 KB
- 参考文档references/examples/builtin-gomoku/meta.json1.4 KB
- 参考文档references/examples/builtin-gomoku/style.css13.5 KB
- 脚本references/examples/builtin-gomoku/ui.js18.2 KB
- 脚本references/examples/builtin-gomoku/worker.js110 B
- 参考文档references/examples/builtin-regex-playground/index.html6.2 KB
- 参考文档references/examples/builtin-regex-playground/meta.json1.7 KB
- 参考文档references/examples/builtin-regex-playground/style.css20.7 KB
- 脚本references/examples/builtin-regex-playground/ui.js27.4 KB
- 脚本references/examples/builtin-regex-playground/worker.js120 B
- 参考文档references/examples/demo-git-graph/meta.json671 B
- 参考文档references/examples/demo-git-graph/package.json162 B
- 参考文档references/examples/demo-git-graph/README.md11.6 KB
- 脚本references/examples/demo-git-graph/source/build.js1.3 KB
- 参考文档references/examples/demo-git-graph/source/esm_dependencies.json3 B
- 参考文档references/examples/demo-git-graph/source/index.html7.5 KB
- 参考文档references/examples/demo-git-graph/source/style.css21.9 KB
- 参考文档references/examples/demo-git-graph/source/styles/detail-panel.css6.2 KB
- 参考文档references/examples/demo-git-graph/source/styles/graph.css599 B
- 参考文档references/examples/demo-git-graph/source/styles/layout.css8.5 KB
- 参考文档references/examples/demo-git-graph/source/styles/overlay.css4.9 KB
- 参考文档references/examples/demo-git-graph/source/styles/tokens.css1.5 KB
- 脚本references/examples/demo-git-graph/source/ui.js71.8 KB
- 脚本references/examples/demo-git-graph/source/ui/appearance.js1.1 KB
- 脚本references/examples/demo-git-graph/source/ui/bootstrap.js3.5 KB
- 脚本references/examples/demo-git-graph/source/ui/components/contextMenu.js1.4 KB
- 脚本references/examples/demo-git-graph/source/ui/components/findWidget.js4.0 KB
- 脚本references/examples/demo-git-graph/source/ui/components/modal.js1.2 KB
- 脚本references/examples/demo-git-graph/source/ui/graph/layout.js11.1 KB
- 脚本references/examples/demo-git-graph/source/ui/graph/renderRowSvg.js4.5 KB
- 脚本references/examples/demo-git-graph/source/ui/main.js26.3 KB
- 脚本references/examples/demo-git-graph/source/ui/panels/detailPanel.js11.5 KB
- 脚本references/examples/demo-git-graph/source/ui/panels/remotePanel.js3.6 KB
- 脚本references/examples/demo-git-graph/source/ui/services/gitClient.js304 B
- 脚本references/examples/demo-git-graph/source/ui/state.js3.2 KB
- 脚本references/examples/demo-git-graph/source/worker.js23.5 KB
- 参考文档references/examples/demo-git-graph/storage.json3 B
- 参考文档references/examples/demo-icon-design-system/meta.json806 B
- 参考文档references/examples/demo-icon-design-system/source/esm_dependencies.json143 B
- 参考文档references/examples/demo-icon-design-system/source/index.html272 B
- 参考文档references/examples/demo-icon-design-system/source/style.css17.3 KB
- 脚本references/examples/demo-icon-design-system/source/ui.js22.7 KB
- 脚本references/examples/demo-icon-design-system/source/worker.js6.5 KB
- 参考文档references/examples/README.md945 B
03 SKILL.md 正文
OpenBitFun MiniApp 生成与操作指南
本技能用于为用户生成、操作、改造和完善 MiniApp:
- 做一个新的 OpenBitFun 小应用
- 结合源码理解并操作用户正在使用的 MiniApp,保留当前草稿与状态
- 修改某个 MiniApp 的交互、界面、能力、数据流
- 把一个想法变成可运行的 MiniApp
开始生成新的 MiniApp 前,先读 design-playbook.md;运行时能力和宿主 API 细节再查 api-reference.md。
目标
交付一个能在 OpenBitFun 里运行、风格合适、权限最小、结构清晰的 MiniApp。
成功标准:
- 用户的问题被这个 MiniApp 直接解决
- 生成结果能在 MiniApp 场景里运行
- 只申请必要权限
- 不假设不存在的宿主 API
- 在 light/dark、zh/en 下都可用
- 新建应用默认提供有界业务状态和核心语义动作,Agent 与 UI 操作同一实例、共用业务函数
操作已有应用时直接进入第 4 节的源码与业务操作流程;下面的设计准备适用于新建或改造应用。
先做什么
在写代码前,先完成这 4 件事:
-
明确用户目标 这个 MiniApp 是工具型、展示型,还是混合型?核心动作是什么?
-
找最近的参考 看
references/examples/中最贴近任务形态的内置/示例 MiniApp 目录 -
选运行模式 先判断是否真的需要
worker.js和node.enabled = true。 -
定最小交付面 第一版只做最核心路径,不为了“看起来完整”堆功能。
生成流程
1. 先澄清,再实现
如果下面任一项不清楚,先问清楚,不要替用户脑补:
- 解决什么问题
- 谁使用
- 要读写哪些路径
- 要不要读工作区文件
- 要执行哪些命令
- 要不要执行命令
- 要访问哪些域名
- 要不要联网
- 要不要持久化状态
- 要不要多语言
- 要不要 Tweaks 这类运行时可调变体
- 有没有现成视觉参考
2. 优先复用现有 MiniApp 语言
不要从零发明一套 OpenBitFun 风格。先从已有 MiniApp 中借鉴:
- 布局密度
- 圆角和间距
- 卡片和面板结构
- 主题变量使用方式
- i18n 组织方式
默认优先做工具型设计:冷静、克制、信息密度高、操作路径短。
3. 优先选“无 Node 模式”
如果需求只靠这些能力就能完成:
app.fs.*app.shell.execapp.net.fetchapp.os.infoapp.storage.*
那么优先使用:
{
"permissions": {
"node": { "enabled": false }
}
}
只有在这些场景下才启用 node.enabled = true:
- 需要自定义
worker.js方法 - 需要 npm 依赖
- 需要较长链路或较复杂的后台逻辑
4. 选择正确的编辑流程
操作已有 MiniApp 的主路径是:inspect-app 读源码理解业务函数和参数 →
MiniAppBrowser.open 连接当前实例 → observe_bridge 读取当前业务状态 →
act_bridge 调用语义动作 → 用动作返回的状态确认结果,必要时再次观察。
源码说明实现,不能代替当前状态;观察必须包含用户尚未保存的输入和选择。
日常操作不要通过修改源码、update-app、FinalizeMiniApp、重载或切换呈现来获得控制能力。
这些动作可能重建文档并丢失内存状态。旧应用缺少接口时,先读源码确认已有能力,使用可用的
DOM/输入作为兼容路径;不可用就说明具体限制,不猜动作名称。
补接口属于应用改造:先明确当前状态如何保存与恢复;无法保留时说明中断并征得用户同意。
改造完成后重新观察业务状态、获取 targetId,不能假设旧草稿或选中项仍存在。
先判断当前任务属于哪一种,不要混用:
已打包客户端的直接管理(优先)
用 OpenBitFunControl 的 get 查询 feature.miniapps,按返回的 schema
调用 list-apps、inspect-app、create-app、update-app、delete-app。
这些操作直接在持有应用的产品宿主编译、保存和通知界面,不需要源码仓库、
Node.js 或本地目录。更新前先读取应用,使用它的 appId 和 expectedVersion;
只传要修改的字段,省略的源码、权限和用户存储保持原样。
删除只用于用户明确要求删除,不能用删除重建来实现修改。
远程工作区或控制端不要用本地文件工具编辑宿主路径,使用以上结构化操作;
目标不支持时报告具体限制。
文件较多且当前是本地工作区时,可使用下面的文件编辑流程。
新建 MiniApp
- 调用
InitMiniApp,保存返回的app_id和根目录。 - 只在返回的根目录中编辑
source/index.html、source/style.css、source/ui.js、按需编辑source/worker.js,以及确有必要的meta.json产品字段。 - 编辑完成后必须调用
FinalizeMiniApp,传入刚才的app_id。 - 只有
FinalizeMiniApp成功后才算交付完成。
更新已有 MiniApp
- 复用已有应用的
app_id和根目录,不要再次调用InitMiniApp创建副本。 - 在已有根目录中完成修改。
- 每一批文件修改完成后必须调用一次
FinalizeMiniApp。 - 如果预期有修改但返回
changed: false,检查文件是否写进了正确的应用根目录; 不要靠手动增加版本号掩盖问题。
FinalizeMiniApp 会重新从磁盘读取源码、编译 compiled.html、持久化内容修订,
并通知已经打开的 MiniApp 刷新。版本号由它管理;不要手改 version、
created_at、updated_at、runtime 或 compiled.html。
定制草稿
如果当前提示明确给出了 Draft root / 草稿目录:
- 只编辑草稿目录
- 不调用
InitMiniApp - 不调用
FinalizeMiniApp - 由定制面板负责“刷新草稿预览”和“应用草稿”
5. 用 InitMiniApp 创建骨架
创建后,围绕这些文件工作:
index.htmlstyle.cssui.jsworker.js(只有需要时)meta.json
默认做法:
index.html只放清晰结构style.css先声明设计系统ui.js负责状态、渲染、事件、i18nworker.js只承载真正需要后台执行的逻辑
默认生成业务状态与语义动作
InitMiniApp 骨架包含一个最小 set-text 示例。实现应用时替换为真实业务接口,
不要保留无意义示例,也不要为 Agent 复制一套业务逻辑:
- 恢复持久化状态后注册
app.agent?.expose?.({ observe, actions, act }),兼容没有此 API 的旧宿主。 observe返回当前业务状态,包括相关草稿、选择、处理进度、结果或错误;只读,无保存/重载副作用。- 返回值有界;长文本或列表提供长度与截断标记,不让 Agent 把摘要当完整数据。
actions声明核心用户意图,如应用筛选、选择记录、更新草稿。参数及返回值在源码中说明。- UI 事件和
act调用相同业务函数,沿用原有校验、权限、持久化和渲染逻辑。 - 修改前验证全部参数;拒绝未知动作;省略字段保持原值。动作完成后返回真实结果或当前状态。
- 异步动作等待业务完成后返回;长任务返回明确的运行状态并可观察进度,不把“收到请求”当“完成”。
- 纯展示应用至少提供只读状态和空动作列表,不伪造可执行动作。
参考 references/examples/builtin-regex-playground/ui.js:
set-input 局部更新、apply-pattern 保留用户文本、select-match 复用 UI 选择函数。
协议兼容允许旧应用没有接口;新应用的交付默认包含这些能力。
窗口控制栏也属于 MiniApp 定制点:在 meta.json 的 chrome.titlebar
中声明外观、布局和应用动作;在 source/ui.js 通过 app.chrome?.onAction
处理动作。草稿预览包含独立窗口栏;应用内动作由主顶部栏承载。
系统控件遵循宿主平台:macOS 保留原生红绿灯,Windows 复用主应用右侧窗口按钮。
只定制标题、应用按钮和语义配色,不移动或重绘系统控件。
配置字段与图标列表见 api-reference.md 的 MiniApp window chrome。
不要在应用内容中再复制原生窗口按钮,也不要直接调用 Tauri。
6. 只使用真实存在的宿主能力
MiniApp 里可用的是 window.app。
默认可依赖的能力:
app.fs.*app.shell.execapp.net.fetchapp.os.infoapp.storage.get/setapp.agent.ensureSession / run / cancel / turnText / cancelStaleRuns / onEventapp.dialog.*app.clipboard.*app.ai.*app.appearanceModeapp.localeapp.onAppearanceChangeapp.onLocaleChangeapp.t(...)app.call(...)仅在node.enabled = true时
详细接口查:
7. 不要假设这些 API 存在
默认不要写这些不存在的接口:
app.openbitfun.*app.workspace.*app.git.*app.session.*app.terminal.*app.browser.*
如果你需要 Git 能力,优先:
await app.shell.exec('git ...', { cwd: app.workspaceDir })
如果你需要工作区数据,优先:
await app.fs.readFile(...)
8. 从第一版就带上 i18n 和 theme
不要把多语言和主题适配留到最后。
至少做到:
meta.json带i18n.locales- 静态文案可重渲染
- 动态文案走
app.t(...)或自有I18N表 - 样式优先使用
--openbitfun-* - 测试 light/dark + zh/en
9. 先做核心体验,不补假内容
如果缺素材、图标、真实数据:
- 用明确占位
- 用 fixture 数据
- 用“待补”标记
不要:
- 硬画劣质插画
- 编造业务数据
- 用装饰性内容填空白
硬约束
交互
- 首屏就要能理解用途
- 主路径操作数尽量少
- 点击区域至少 32px
- 正文不要小于 13px
视觉
- 禁止默认蓝紫渐变 AI 风背景
- 禁止 emoji 充当主图标
- 禁止“每块一个风格”
- 禁止堆无意义 stats、sparkline、装饰 icon
代码
- 不需要
worker.js时不要启用 Node - 不需要的权限不要申请
- 不要把大量逻辑塞进 HTML
ui.js过长时主动拆成模块化结构
内容
- 不为填空白加内容
- 每个 section 都要有明确用途
- 不擅自扩 scope
你应该参考什么
生成前优先阅读最贴近的一两个参考,而不是全看:
references/examples/demo-git-graph/references/examples/demo-icon-design-system/references/examples/builtin-regex-playground/references/examples/builtin-coding-selfie/references/examples/builtin-gomoku/references/examples/builtin-daily-divination/
生成新的 MiniApp 时,默认先读:
如果任务偏运行时调用,再看:
交付前检查
交付前至少确认:
- MiniApp 能运行
- 主路径可操作
- 权限是最小集
node.enabled选择合理- 没有调用不存在的
app.*API - i18n 至少覆盖
zh-CN/en-US - light/dark 没有明显样式问题
- 没有遗留 “TODO / 占位 / Lorem ipsum”
- 普通新建/更新流程已成功调用
FinalizeMiniApp - 预期有改动时
FinalizeMiniApp返回changed: true - 没有手动修改生命周期字段或
compiled.html - 在同一已打开实例中,先由用户输入未保存内容,再经
observe_bridge/act_bridge完成业务任务 - 验证没有源码更新、文档重载或实例替换;未修改的输入、草稿和相关选择保持原样
- 动作结果与可见 UI 一致;非法参数/未知动作失败且不部分修改状态
- 验证可读取标签页与不依赖 DOM 的桥接路径;明确区分测试夹具、原生窗口和远程实测证据
发布到市场
用户明确要求把 MiniApp 发布/上架到市场时,用 PublishMiniApp 工具:
- 传
app_id和 1–5 张截图路径(PNG/JPEG/WebP,单张 ≤ 5 MiB)。 没有截图时先向用户要,或请用户在「市场 → 我的投稿」用「截取当前画面」生成。 - 截图比例用 16:9,推荐 1920×1080。市场网页和 OpenBitFun 桌面端都按 16:9 居中裁剪显示,非 16:9 的图会被切掉边缘。第一张是列表卡片封面,选最能说明 用途的那张,关键信息放画面中部不要贴边。超过 2560px 的边会被服务端缩到 2560,所以 2560×1440 是有效上限。
- 名称、描述、图标、分类、标签自动取自
meta.json;slug 和版本号自动推导。 发布前确认meta.json的description非空、权限是最小集 (市场会拒绝node.enabled=true、宽泛 fs scope 等)。 - 未登录时工具会返回 GitHub 授权链接:把链接给用户,等用户完成授权后 用相同参数再调用一次即可继续。
- 提交后进入人工审核;用户可在「市场 → 我的投稿」查看状态。
- 这是对外动作:只在用户明确要求发布时调用,不要主动发布。
04 同仓库更多 Skills
openbitfun-skin-designer
Create or update an importable OpenBitFun visual skin from reference images or an art brief, using the target product's actual paint contract and checking the result in the existing UI.
openbitfun-frontend-dev
Safely customize the running packaged OpenBitFun desktop frontend through a draft, a provisional hot apply, and a 15-second user-confirmed rollback window. Use only in OpenBitFun Creative mode when the user asks to change OpenBitFun's own client UI.
ppt-design
使用 HTML 设计与生成高质量演讲幻灯片(PPT/Deck)。当用户希望生成、设计、修改幻灯片、deck、slides、presentation、汇报、提案、pitch、课件时触发。主干:1280×720px 可编辑 HTML 幻灯片 + 唯一 editable HTML→EditableSlideScene→OOXML 管线 + 数据/信息可视化意识 + 5 种设计哲学 + 反 AI slop + 单页自包含 `slide-XX.html`。不生图;缺图用可编辑原语或占位并标注建议补图。
create-agent
Create or update OpenBitFun custom modes and subagents. Turn the user's needs into a role prompt and a suitable tool selection, then save an agent definition. Use for reusable roles, not ordinary delegation to an existing subagent.
plan
Research and write an actionable implementation plan without implementing it. Use when the user asks to plan, design an approach, or inspect a change before coding; stop applying the planning restriction once the user explicitly asks to implement.
find-skills
Discover and install reusable agent skills when users ask for capabilities, workflows, or domain-specific help that may already exist as an installable skill.