| name | metabot-create-metaapp |
| description | MetaBot 专属的 MetaApp 开发与交付套件。基于 IDFramework (No-Build, MVC) 架构,支持从零构建链上前端应用、编写业务指令 (Commands)、组件开发 (Web Components) 以及最终的打包交付 (Zip)。 |
| dependencies | python >= 3.x, alpine.js, unocss |
metabot-create-metaapp
赋予 MetaBot 开发 MetaWeb 链上原生应用 (MetaApp) 的能力。集成了架构设计、代码生成与发布打包的全流程。
核心工作流 (Workflows)
1. 应用开发 (Development)
当用户指令涉及“创建 MetaApp”、“开发前端”、“增加功能”时,MetaBot 必须严格遵循 IDFramework 架构。
1.0 硬检查清单门禁 (生成前/交付前,强制执行)
为避免“生成产物看似可运行但不符合 MetaApp 规范”的问题,必须执行如下两阶段门禁。任一失败即停止,不得继续生成或交付。
-
生成前门禁 (pregen,强制)
在仓库根目录执行:
python3 metabot-create-metaapp/scripts/validate_metaapp_checklist.py --phase pregen --project ./<project_name>
通过条件:目标目录位置合规、模板/基线文件完整、开发指南文件存在。
-
交付前门禁 (predeliver,强制)
在仓库根目录执行:
python3 metabot-create-metaapp/scripts/validate_metaapp_checklist.py --phase predeliver --project ./<project_name>
通过条件:最小可运行文件集齐全、index.html 核心脚本与 id-connect-button 渲染存在、app.js 基础命令注册齐全、登录核心文件与 idframework/ 基线对齐、无上级运行依赖引用。
-
启动验收门禁 (smoke test,强制)
在通过 predeliver 后,必须执行“可启动 + 控制台无报错”验收,未通过不得交付:
- 在仓库根目录启动本地服务:
npx http-server . -a 127.0.0.1 -p 5602 -o /<project_name>/index.html -c-1
- 打开页面后执行首屏验证:页面能正常渲染、
id-connect-button 显示正常、业务主组件可见。
- 打开浏览器控制台检查:不得出现会影响运行的错误(如
No command registered for event: ...、模块加载失败、脚本 404、未定义对象异常等)。
- 若发现报错:必须先定位并修复(例如补齐
app.js 命令注册、补齐缺失文件引用、修正加载顺序),然后重复 1)-3) 直到控制台无阻塞性错误。
- 仅当
predeliver + smoke test 均通过,才允许告知用户本地启动命令并交付。
-
打包门禁联动 (强制)
scripts/package_metaapp.py 已内置 predeliver 硬检查;若检查失败,打包必须中止。
-
前置阅读 (Critical): 开发前必须读取并理解 references/MetaApp-Development-Guide.md。
-
脚手架基线 (强制): 必须以 templates/ 作为生成基线,不允许绕过模板从零散文件拼装生成。
-
项目目录位置 (强制): 使用 metabot-create-metaapp 生成 MetaApp 时,目标项目目录必须创建在仓库根目录(与 metabot-create-metaapp 同级),禁止将生成产物放在 metabot-create-metaapp/ 目录内。示例:应生成到 ./Simple-ID-Buzz/,而不是 ./metabot-create-metaapp/Simple-ID-Buzz/。
-
index.html 基线继承 (强制): 目标项目 index.html 必须以 templates/index.html 为基础生成,默认应完整保留其中与登录态初始化、localStorage 持久化、Metalet 事件监听、App/WebView 兼容处理相关的核心逻辑;仅允许做业务区块插入或必要配置调整,禁止删改导致这些能力失效。
-
依赖独立化 (强制): 基于 idframework 生成 MetaApp 时,所有运行依赖文件(idframework.js、idconfig.js、idutils.js、metaid.js、crypto.js、socket-client.js、commands/、idcomponents/、stores/ 等)必须放置在目标项目目录内并使用项目内相对路径引用。禁止通过 ../ 或其它上级目录路径引用 metabot-create-metaapp 下文件作为运行依赖。
-
多 MetaApp 并存隔离 (强制): 当本地同时存在多个 MetaApp 项目时,生成器必须保证每个项目为“完全独立版”。运行时依赖只允许来自当前目标项目目录,严禁引用任意其它 MetaApp 目录文件(例如 ../Snake-Score-MetaApp/*、../IDChat/*、../<other-metaapp>/*)。若发现跨项目引用,视为生成失败,必须改为将所需文件复制到当前项目内并改为项目内相对路径。
-
最小可运行文件集 (强制): 生成任何 MetaApp 至少应包含并正确接线以下文件:index.html、app.css、app.js、idframework.js、idconfig.js、idutils.js、bootstrap-stores.js、app-env-compat.js、idcomponents/id-connect-button.js、commands/FetchUserCommand.js、commands/CheckWebViewBridgeCommand.js、commands/CheckBtcAddressSameAsMvcCommand.js。缺少任一项视为生成不合格。
-
按业务白名单引入 (强制): 除“最小可运行文件集”外,其余 commands/、idcomponents/、stores/ 文件必须根据当前业务需求按需引入,禁止整包复制模板样例。
-
默认禁带无关业务模块 (强制): 生成某一具体业务 MetaApp(例如 Snake)时,若需求未涉及 Buzz/Chat/支付审批,不得默认引入或注册 FetchBuzzCommand.js、PostBuzzCommand.js、SendChatMessageCommand.js、GetPinDetailCommand.js、id-buzz-list.js、id-post-buzz.js、id-chat-input-box.js、stores/useApprovedStore.js 等无关模块。
-
命令注册时序防竞态 (强制): app.js 中所有基础命令与业务命令(至少包含 fetchUser、checkWebViewBridge、checkBtcAddressSameAsMvc 及业务新增命令)必须在模块加载阶段完成注册(例如顶层立即注册或“框架就绪后立即重试注册”);禁止仅在 DOMContentLoaded 内延后注册,避免首屏阶段出现 No command registered for event: ...。
-
早期 dispatch 保护 (强制): 若 idcomponents/* 或 app-env-compat.js 在 connectedCallback/首屏初始化期间会触发 IDFramework.dispatch(...),必须先确保对应命令已注册(例如轮询 IDController.commands.has(cmd)、封装 waitForCommand),再执行 dispatch。
-
目录结构对齐 (强制): 生成结果必须对齐 templates/ 的目录组织(入口文件 + commands/ + idcomponents/,以及按需 stores/)。禁止生成与模板结构明显不一致的“扁平化”或“缺目录”项目。
-
基线文件强一致 (强制): 凡使用 metabot-create-metaapp/ 下文件开发 MetaApp 业务(包括但不限于 idframework.js、commands/FetchUserCommand.js、idcomponents/id-connect-button.js、bootstrap-stores.js、app-env-compat.js 等),目标项目实现必须与 metabot-create-metaapp/ 对应基线文件保持能力与行为一致;禁止由 LLM 自主决策进行阉割、简化、删减关键流程或弱化异常处理。
-
核心依赖七件套强制代码平移 (最高优先级): 生成任意 MetaApp 时,以下 7 个文件必须从 metabot-create-metaapp/idframework/ 同路径文件进行强制性代码平移(作为唯一真值来源),只允许在其上做增量扩展,不允许任何删减/阉割/简化:
idframework.js、bootstrap-stores.js、app-env-compat.js、commands/FetchUserCommand.js、commands/CheckWebViewBridgeCommand.js、commands/CheckBtcAddressSameAsMvcCommand.js、idcomponents/id-connect-button.js。
若业务无需某些扩展逻辑,可保持与基线一致;但不得以“精简版/改写版”替代。
-
核心依赖七件套交付前验收 (强制): 交付前必须完成并通过以下自检:
- 目标项目上述 7 文件均存在,且路径与命名完全一致;
app.js 已注册 fetchUser、checkWebViewBridge、checkBtcAddressSameAsMvc 三个基础命令;
index.html 已按基线引入 bootstrap-stores.js、idframework.js、idcomponents/id-connect-button.js、app-env-compat.js;
- 七件套文件能力完整,不存在删除关键流程、删除异常处理、删除监听链路等“减配”行为(允许新增,但不允许减少);
任一未通过即视为不合格,不得交付。
-
命令注册时序交付验收 (强制): 交付前必须确认:
app.js 可在不依赖 DOMContentLoaded 的情况下完成命令注册(包含基础命令与业务命令);
- 首屏初始化链路(含
app-env-compat.js、业务组件 connectedCallback)中所有 dispatch 的命令均已可用;
- 浏览器控制台不得出现
No command registered for event: ...。
-
架构模式:
- View:
idcomponents/*.js (Web Components + Alpine.js)。禁止在组件内写业务逻辑。
- Logic:
commands/*.js (Command Pattern)。所有 API 调用、状态变更必须在此完成。
- Core:
idframework.js (MVC 核心) + app.js (配置与注册)。
2. 应用打包 (Packaging)
当用户指令涉及“打包应用”、“生成 Zip”、“准备发布”时,必须直接执行以下脚本。
- 脚本:
python3 scripts/package_metaapp.py <project_path> [options]
- 功能: 自动校验项目结构 -> 过滤开发文件 (.git, node_modules) -> 生成发布包。
- 输出:
dist-<timestamp>.zip (位于项目根目录)。
- 校验规则: 目标目录必须包含
index.html, app.js, app.css, idframework.js 及 idcomponents/, commands/ 目录,否则脚本会报错。
文件结构与职责 (Architecture)
MetaBot 在编写代码时需严格遵守以下文件职责:
| 文件/目录 | 核心职责 | AI 编写规范 |
|---|
index.html | 入口 | 必须声明并按顺序引入 bootstrap-stores.js、idconfig.js、idutils.js、idframework.js、idcomponents/id-connect-button.js、app.js、app-env-compat.js;当业务命令需要 mvc/TxComposer 时按需引入 metaid.js;当组件/命令需要加密能力时按需引入 crypto.js(提供 window.CryptoJS);当聊天能力启用时按需引入 socket-client.js 与对应 stores;禁止把核心业务流程直接写在页面脚本中。 |
app.js | 配置 | 注册 ServiceLocator,注册 Models,注册 Commands。 |
commands/ | 业务逻辑 | export default class XxxCommand。调用 Delegate,更新 Store。 |
idcomponents/ | 视图组件 | Shadow DOM 隔离。只负责渲染 Store 数据和 Dispatch 事件。 |
stores/ | 状态中台 | 承载复杂领域状态(如聊天分页、socket 缓存、支付审批状态),由 Commands 与组件共同消费。 |
app.css | 样式 | 定义 CSS 变量 (Theming)。支持深色模式。 |
idframework.js | 框架核心 | 仅承载跨业务通用能力(Model/Delegate/Controller/dispatch 机制)。禁止塞入聊天、Buzz、具体业务协议细节。 |
当前 IDFramework 依赖层级 (按需引入)
以下为 metabot-create-metaapp/idframework/ 当前可复用能力。生成 MetaApp 时应根据业务启用,不做“一刀切全引入”。
A. 基础必引入 (所有 MetaApp)
index.html、app.css、app.js: 入口与应用配置。
idframework.js: MVC 核心、dispatch、命令执行。
idconfig.js、idutils.js: 默认服务配置与通用工具。
bootstrap-stores.js、app-env-compat.js: store 持久化与 App/WebView 兼容桥接。
idcomponents/id-connect-button.js: 登录入口组件。
commands/FetchUserCommand.js: 登录后用户资料拉取命令。
commands/CheckWebViewBridgeCommand.js、commands/CheckBtcAddressSameAsMvcCommand.js: WebView/地址一致性基础校验命令(必须存在并在 app.js 注册)。
B. 业务按需引入
- 总原则
- 下列能力均为“按需模块”,只有当需求明确涉及该业务时才允许引入与注册。
- 未被需求覆盖的模块禁止出现在目标项目目录、
index.html 引用和 app.js 命令注册中。
- 身份与链上能力
metaid.js: MetaIDJs、TxComposer、mvc 等链上能力。
- 仅当命令涉及交易构建/签名/上链时启用;例如业务代码需要
TxComposer、mvc 对象时必须引入。
- 加密能力
crypto.js: 提供 window.CryptoJS。
- 仅当命令或组件存在 AES/ECDH 等加解密逻辑时启用。
- 聊天能力
socket-client.js(注意:当前为 .js,非 .ts):聊天 websocket 客户端封装。
idcomponents/id-chat-box.js 与 idcomponents/id-chat-bubble.js 通常应成组引入;涉及发言输入时同时引入 idcomponents/id-chat-input-box.js。
commands/SendChatMessageCommand.js 为聊天发送必要命令;结合用户资料展示/会话资料时配套 commands/FetchUserInfoCommand.js。
stores/simple-talk.js、stores/ws-new.js、stores/useApprovedStore.js 与聊天相关组件/命令强关联,启用聊天业务时应一并评估并按需引入。
- 支付审批能力
stores/useApprovedStore.js: smallPay 自动支付能力状态。
- Buzz 能力
idcomponents/id-buzz-list.js、id-post-buzz.js、id-attachments.js
commands/FetchBuzzCommand.js、PostBuzzCommand.js
哪些新增逻辑应写入 idframework.js (核心边界)
为了保持“核心稳定 + 业务可插拔”,新增逻辑按以下规则处理:
应写入 idframework.js 的逻辑
- 通用机制增强:不依赖具体业务协议、可被任意 MetaApp 复用的能力。
- store 自动注入策略扩展:如 dispatch 的通用 store 发现策略(在不破坏兼容的前提下扩展常见 store 名单)。
- Delegate 通用抽象:统一请求/鉴权/错误处理能力,但不绑定某一业务接口语义。
- Built-in Command 的基础能力:钱包连接、通用 createPin 这类跨业务基础命令。
不应写入 idframework.js 的逻辑
- 任何具体业务域流程:聊天拉取、Buzz 时间线、帖子协议字段拼装等。
- 具体 API path、特定后端字段映射、业务路由约束。
- UI 交互细节(dropdown、mention、scroll、socket 重连策略等)。
新增能力推荐落点
app.js:按业务注册命令(如 fetchBuzz、sendChatMessage、fetchUserInfo)。
commands/*.js:协议体拼装、业务校验、服务调用。
stores/*.js:复杂状态与缓存。
idcomponents/*.js:纯视图渲染与事件派发。
代码生成规范 (Coding Constraints)
- No-Build 哲学: 使用原生 ES Modules。严禁引入 Webpack/Vite/Babel 或
require() 语法。
- 路径引用: 所有 import 必须使用相对路径 (如
./commands/Auth.js),严禁使用绝对路径 (/src/...)。
- 生成项目时,业务运行依赖只允许引用目标项目目录内文件;严禁引用上级目录(如
../metabot-create-metaapp/...)。
- 本规则同样适用于“其它同级 MetaApp 目录”:严禁出现
../<other-metaapp>/... 的模块引用(包含 index.html 的 <script src>、import、动态加载路径、命令注册路径等)。
- Command 模式:
- 组件不直接调 API,必须
IDFramework.dispatch('cmdName', payload)。
- Command 不直接操作 DOM,必须修改 Alpine Store (
stores.user.name = ...) 触发响应式更新。
- 所有上链相关逻辑(如
createPin、签名、支付、UTXO 处理、文件上链)必须先做登录态校验:若 wallet 未连接、user 为空对象或钱包注入不可用,则立即中断并提示“请先登录钱包后再进行上链操作”。
app.js 中命令注册必须优先于首屏可能触发的 dispatch 链路(如 app-env-compat.js、组件 connectedCallback);严禁把“首次注册命令”的唯一入口放在 DOMContentLoaded 回调中。
- 样式隔离: 组件内使用 Shadow DOM 和 CSS 变量 (
var(--id-color-bg)),确保样式不污染。
- 必要脚本声明:
./idconfig.js、./idutils.js 为基础必引入脚本。
./bootstrap-stores.js 为强制引入脚本,负责在 alpine:init 时注册并持久化 wallet/app/user stores;禁止省略,且必须与 idframework/bootstrap-stores.js 基线一致(可增不可减)。
./app-env-compat.js 为强制引入脚本,负责 Metalet 事件监听、WebView 兼容与账户状态巡检;禁止省略,且必须与 idframework/app-env-compat.js 基线一致(可增不可减)。
./idcomponents/id-connect-button.js 为登录基础组件,默认 MetaApp 必须引入并渲染;生成时其实现必须与 metabot-create-metaapp/idframework/idcomponents/id-connect-button.js 保持对齐(以 idframework 版本为唯一基线来源,可增不可减)。
./commands/FetchUserCommand.js 为登录后用户信息拉取基础命令,默认 MetaApp 必须在 app.js 中注册(如 fetchUser),并与 idframework/commands/FetchUserCommand.js 基线保持一致(可增不可减)。
./commands/CheckWebViewBridgeCommand.js、./commands/CheckBtcAddressSameAsMvcCommand.js 为基础命令,默认 MetaApp 必须存在并在 app.js 中注册(如 checkWebViewBridge、checkBtcAddressSameAsMvc),并分别与 idframework/commands/ 对应基线保持一致(可增不可减)。
./metaid.js 为按需引入:仅当业务逻辑需要使用 MetaIDJs(例如 mvc、TxComposer)时才引入。
./crypto.js 为按需引入:仅当组件或 Command 需要 CryptoJS(如群聊/私聊消息加密)时才引入,并通过 window.CryptoJS 使用,禁止再通过远程 CDN 动态 import。
./socket-client.js 与 ./stores/*.js 为按需引入:仅当业务涉及实时通信、复杂分页缓存、支付审批状态等时启用。聊天业务场景下应优先按“组件 + 命令 + stores”成组引入。
- 除基础命令/组件外,其他
commands/*.js、idcomponents/*.js、stores/*.js 必须按具体业务需求启用,禁止“默认全量引入”。
常用开发模板
Command 模板
export default class FetchDataCommand {
async execute({ payload, stores, delegate }) {
const data = await delegate('service_name', `/api/resource/${payload.id}`);
stores.appData.currentList = data;
}
}
Component 模板
class IdCard extends HTMLElement {
constructor() { super(); this.attachShadow({ mode: 'open' }); }
connectedCallback() {
const store = Alpine.store('appData');
this.shadowRoot.innerHTML = `<div>${store.currentList.name}</div>`;
}
}
customElements.define('id-card', IdCard);
模板目录约束 (templates/)
templates/ 是开发 MetaApp 的参考模板目录,用于快速起步和能力复用。
templates/index.html、templates/app.js、templates/app.css、templates/idframework.js 为标准入口模板。
templates/bootstrap-stores.js、templates/app-env-compat.js 为入口强制依赖脚本,用于承载原先 index.html 的关键初始化逻辑(store 持久化 + App/WebView 兼容)。
templates/idcomponents/、templates/commands/、templates/stores/ 仅提供可复用样例;生成时必须按业务白名单挑选,禁止整目录拷贝到目标项目。
templates/index.html 为默认唯一入口基线模板:生成目标项目时应复制并在此基础上修改,禁止使用“最简手写 index.html”替代,避免丢失用户信息持久化与 App 打开 MetaApp 的兼容逻辑。
templates/index.html 中这两段关键逻辑(store 持久化初始化、App 环境兼容)已被外置到 bootstrap-stores.js 与 app-env-compat.js。生成项目时必须一并复制并保持 script 引用,禁止回退为缺失逻辑的精简版入口页。
- 登录基础能力模板要求:以下七件套必须以
idframework/ 同路径文件为基线并保持对齐,生成目标项目时执行“强制代码平移(可增不可减)”:idframework.js、bootstrap-stores.js、app-env-compat.js、idcomponents/id-connect-button.js、commands/FetchUserCommand.js、commands/CheckWebViewBridgeCommand.js、commands/CheckBtcAddressSameAsMvcCommand.js。若 templates/ 与 idframework/ 存在差异,上述七件套一律以 idframework/ 为准同步到目标项目,禁止保留任何简化版实现。
- 当
templates/ 中暂未覆盖某个 idframework/ 新能力文件时,允许按业务从 idframework/ 同步拷贝到目标项目,并保持相对路径与命名一致(idconfig.js、idutils.js 属基础依赖,若模板缺失应优先从 idframework/ 补齐)。
- 模板同步原则:优先保持“可运行最小集 + 常用业务模块”,避免把全部实验性文件强制塞入模板。
- 目标项目目录位置要求:目标项目应位于仓库根目录并与
metabot-create-metaapp 同级,禁止放置在 metabot-create-metaapp/ 内。
- 目标项目产物要求:从模板/框架同步到目标项目后,目标项目应可独立运行;入口脚本与模块 import 仅引用项目内路径(例如
./idframework.js、./commands/*.js、./idcomponents/*.js),不得保留对上级目录的运行时引用。
- 多项目并存验收要求(强制):在交付前必须检查目标项目
index.html、app.js、idcomponents/*.js、commands/*.js 中所有脚本与模块路径,确保不包含任何 ../<other-metaapp>/ 或其它跨项目目录引用;发现即不合格,必须修复为当前项目内自包含依赖。
- 生成验收要求:必须检查
index.html 是否已引入并渲染 id-connect-button,且 app.css 文件存在并可被页面成功加载(非 404)。
- 本地启动验证要求(强制):生成后必须给出并校验正确启动方式,默认在仓库根目录执行
npx http-server . -a 127.0.0.1 -p 5602 -o /<project>/index.html -c-1。其中 <project> 必须是仓库根目录下与 metabot-create-metaapp 同级的项目目录名。若出现 http://127.0.0.1:5602/<project>/index.html 404,先排查是否在错误目录启动(例如子目录启动导致路由根不一致),并给出可直接复现的修正命令。除页面可访问外,还必须完成控制台无报错检查(尤其是命令未注册、脚本加载失败、运行时未定义异常),否则不得交付。
测试目录约束 (test/)
test/ 目录仅用于放置测试页面(如 test/index.html、test/chat.html)。
- 测试页面可用于组件联调、命令联调、钱包连接验证、路由与 socket 验证。
- 生产打包时,测试文件不应作为业务入口;仅在开发验证阶段使用。
脚本索引 (Script Index)
- scripts/package_metaapp.py: 打包工具。用法: python3 scripts/package_metaapp.py ./my-app
- scripts/validate_metaapp_checklist.py: 规范硬检查工具。用法: python3 scripts/validate_metaapp_checklist.py --phase pregen --project ./my-app;python3 scripts/validate_metaapp_checklist.py --phase predeliver --project ./my-app
- templates/: 标准项目模板 (Reference ONLY)。
- test/: 调试与联调用测试页面目录。
**注意: ** MetaApp 是运行在 MetaWeb 上的去中心化应用,代码质量直接决定用户资产安全。MetaBot 必须确保逻辑严密,并优先使用 commands/ 封装业务。