用 AI Agent 开发工坊小程序

你可以把 AI Agent 当成开发搭子：让它创建项目、实现页面、启动预览、检查配置，并在发布前帮你确认登录态、小程序 ID、版本号和构建结果。

推荐流程

1. 首次准备环境。
2. 创建工坊小程序项目。
3. 告诉 AI Agent 你要做什么。
4. 打开小黑盒开放平台小程序列表，登录后创建或绑定小程序 ID，再登录 CLI。
5. 使用浏览器 Mock 完成本地预览。
6. 使用手机真机验收。
7. 让 AI Agent 帮你提交审核，审核通过后发布。

首次准备环境

第一次使用、换电脑、换 Agent 环境，或 doctor 检查失败时，先复制这段给 AI Agent：

请帮我完成一次性环境准备：
1. 检查 Node.js 和 npm 是否可用。
2. 运行 `hb-sdk skill install` 安装或刷新 hb-sdk Agent Skill。
3. 运行 npx @heybox/hb-sdk@latest doctor。
4. 告诉我是否可以开始创建工坊小程序项目。

如果 doctor 发现版本不匹配，按输出提示刷新 Skill 或升级 SDK。

创建项目

把 my-miniapp 换成你的项目名，然后交给 AI Agent：

请创建一个小黑盒工坊小程序项目，项目名用 my-miniapp。
请使用 hb-sdk create 创建模板。
创建后进入项目目录安装依赖，并告诉我项目绝对路径。

创建后，打开项目目录。看到 package.json 和 src/ 后，就可以继续说需求。手动创建命令见安装。

把需求讲清楚

不需要一开始就指定 SDK 方法。你只要把“做什么、有哪些页面、需要哪些小程序开放能力、怎么验收”讲清楚。

推荐提示词：

我想做一个小黑盒工坊小程序，用来【填写用途】。

请在当前项目里实现页面，并启动本地预览。
页面需要【登录 / 分享 / 本地保存 / 云端排行榜】。
接口信息是【没有就先用 mock 数据】。
如果需要网络请求，请提醒我在 `package.json#heybox.permissions` 声明 `network`，
并确认平台已开通；未获得平台开通时使用 mock 数据或无网络方案。

完成后请告诉我：
1. 预览入口；
2. 你改了哪些文件；
3. 我应该怎么验收。

修改已有项目时，直接告诉 AI Agent 要改什么，并要求它使用 hb-sdk Agent Skill、运行本地预览、给出验收步骤。

本地预览和验收

本地开发时，先让页面跑起来，再看主要流程是否顺：

请帮我启动这个工坊小程序的本地调试服务。
如果启动命令会自动打开浏览器，请提前告诉我。

启动后请把这些信息发给我：
1. 预览地址；
2. 当前页面是否正常打开；
3. 我应该按什么步骤验收。

先完成 hb-sdk login、hb-sdk remote create 或 hb-sdk remote bind <mini-program-id>。hb-sdk dev 校验登录、绑定与远端配置后启动 Browser Mock；未满足前置条件时退出并给出修复指引。真实手机/PC 调试还需要有效启动票；启动后的签票失败或临时断网不关闭浏览器服务。完整启动与重试规则见CLI 与本地 mock 调试。

调试台左侧提供日志、Storage 和问题，右侧可切换 iPhone 16 Pro Max 与 Pixel 9 Pro 预设。授权弹窗、Toast 和 Loading 都显示在设备预览内；手机二维码只在右上角入口提供。

提交审核与发布

页面验收没问题后，让 AI Agent 检查开放平台登录状态、小程序 ID、版本号和构建结果。

访问开放平台并创建或绑定小程序 ID

小程序工坊已进入公测，不需要额外申请开发者资格。请直接打开小黑盒开放平台小程序列表，登录后创建、查看和管理小程序。

创建或绑定小程序 ID

打开开放平台后，可以从小程序列表进入管理界面。

可以在管理界面查看小程序，也可以让 AI Agent 用 CLI 创建或绑定。

已有小程序时，把它绑定到当前项目即可。

绑定后可以在详情页确认小程序信息和版本。

通常只需要把以下命令交给 AI Agent：

npx @heybox/hb-sdk login
npx @heybox/hb-sdk remote create
# 或绑定已有小程序
npx @heybox/hb-sdk remote bind mp_xxxxxxxx

手机真机验收

完成 CLI 登录和项目绑定后，打开调试台右上角唯一的二维码入口，选择局域网网卡，再用手机小黑盒 APP 扫码。手机和电脑需要处于同一局域网；远端 Dev Context 不可用时，hb-sdk dev 会直接失败。

让 AI Agent 提交审核

复制这段给 AI Agent：

请帮我发布这个工坊小程序。

发布前检查开放平台登录状态、CLI 登录、小程序 ID、版本号、基础资料和本地构建。
缺少小程序 ID 时，先引导我创建或绑定。
如果需要我在浏览器里登录、扫码或确认，请停下来告诉我。
发布失败时，请解释关键错误和下一步处理方式。
不要输出任何 cookie、pkey、token 或私密请求头。

模板项目里的 npm run deploy 会执行 hb-sdk remote deploy：

npm run deploy -- --release-note "首次提交：完成页面搭建和基础交互"

hb-sdk login 只是发布工具的登录，不是小程序用户登录。提交审核后，可以通过预览白名单让指定用户验收未发布版本。

审核通过后，可以让 AI Agent 查看版本并发布：

npx @heybox/hb-sdk remote versions
npx @heybox/hb-sdk remote release <version>

发布不等于已在工坊广场、搜索或推荐位公开展示。公开展示还需要满足正式资料和平台分发要求，详见小程序工坊上架规则。

相关文档

• 安装与运行环境
• 快速开始
• CLI 与本地 mock 调试
• Agent Skill 安装
• 小程序工坊上架规则
• API Reference

完成检查

• 已运行 npx @heybox/hb-sdk@latest doctor，没有阻塞问题。
• 已用 hb-sdk create 创建项目，完成 CLI 登录与项目绑定，并能通过 npm run dev 打开本地调试页。
• 已先用浏览器 Mock 完成本地流程，再用手机小黑盒 APP 验收。
• 如果使用网络能力，已确认当前小程序获得平台开通，没有把本地 Mock 当成线上权限。
• 提交审核前已确认开放平台登录态、CLI 登录态、小程序 ID、版本号和基础资料。
• 审核通过后已按需要执行 hb-sdk remote release <version>。