什么是小程序工坊

工坊小程序是运行在小黑盒 APP 内的官方小程序。开发者可以使用标准 Web 技术开发受控沙箱应用，并通过 @heybox/hb-sdk 使用平台开放的用户、登录、分享、存储等能力。

工坊小程序由外部开发者独立开发和运营，适合提供游戏工具、数据查询、互动体验等符合平台规则的轻量应用。开发者需要对小程序的代码安全、内容、数据来源、第三方服务和用户隐私负责。

与普通小程序的区别

工坊小程序提供轻量的应用体验，但运行环境和开放能力会受到更多限制。它运行在小黑盒 APP 的受控沙箱中，只能使用小程序工坊公开的 SDK 能力，并需要遵循平台的审核与发布流程。

使用限制

• 运行环境：工坊小程序运行在小黑盒客户端提供的受控沙箱中。生产构建不能作为普通网页直接运行。
• 开放平台入口：小程序工坊已进入公测，不需要额外申请开发者资格。请直接访问小黑盒开放平台小程序列表，登录后创建、提交审核、发布和管理工坊小程序。
• 能力边界：工坊小程序只能使用 @heybox/hb-sdk 提供的公开能力。
• 项目配置：版本名称、简介与图片、目标平台、权限、窗口、关联游戏、桌面辅助应用和远端绑定统一写在 package.json#heybox，完整字段见 package.json 项目配置。
• 权限声明：受保护能力必须在 package.json#heybox.permissions 声明；network、companion、workspaceCards 需要平台批准；appProtocol 权限及 device.executeProtocol() 暂不对外开放，不提供开发者申请入口。完整目录、配置与迁移规则见权限声明。
• 网络请求：network 仅约束公开 network.request()、network.download() 与 network.upload()，不约束 auth、user、cloud 等模块内部的 Host 受信请求。平台保留的 runtime auth 与 OpenAPI 内部路径始终不可访问。
• 文件能力：声明 filesystem 后，新 PC 支持隔离 sandbox、单文件/目录 picker 与 saveFile()；同时声明并获准 network 后可使用公网流式下载。pickFiles() 默认单文件，显式传入 multiple: true 时允许 Host 返回多个文件（实际返回数量由宿主 picker 决定）；小黑盒域名流式下载暂不支持。Android/iOS 1.3.396+ 还需 Host 通过 system.describe 宣告对应 Native operations 后才逐项启用；已适配 Android 客户端支持 saveFile() 和精确 SAF 文件写入，具体取决于系统授权及实际 operation。Web 与 Browser Dev Host 返回 METHOD_FORBIDDEN，所有 Host 均不提供 Blob 或内存假实现。完整用法、沙箱模型、路径规则、配额与错误码见文件能力与沙箱。
• 本地存储：少量配置与缓存使用 storage，大体积数据使用文件沙箱；配额、历史数据与用户清理行为见本地存储。
• 桌面辅助应用：声明并获准 companion 后，新 PC 可准备和启动审核版本携带的固定桌面程序；不能传动态路径或参数，Browser Fake 也不能替代真机验收。完整边界见受管桌面程序。
• 审核与合规：版本上线前必须经过平台审核，并遵守内容、隐私、商业化和运行质量要求。完整要求见小程序工坊上架规则。

开始开发

• 推荐：按用 AI Agent 开发工坊小程序完成环境准备、创建项目、调试和提交前检查。
• 手动开发：先读安装，再按快速开始完成 SDK 初始化。
• 提交前：检查小程序工坊上架规则。