package.json 项目配置

工坊小程序在项目 package.json 的 heybox 对象中声明小程序类别、版本资料、目标平台、受保护能力、窗口、关联游戏和桌面辅助应用，并记录当前项目绑定的远端小程序。

heybox 是项目声明，不是运行时权限或 Host 能力探测结果。构建成功只表示声明格式有效；需要平台批准、用户授权或特定 Host 支持的能力，仍会在运行时分别检查。

最小配置

把 heybox 写在小程序项目自己的 package.json 中，并保持它是 JSON 对象。下面是包含类别的最小声明；还需在对应路径放置符合要求的图片，并在发布前按实际适配平台调整 platforms：

json

{
  "name": "my-miniapp",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "heybox": {
    "name": "我的小程序",
    "category": "tool",
    "icon": "assets/icon.png",
    "coverImages": ["assets/cover.png"],
    "platforms": ["android", "ios", "ohos", "windows", "macos"],
    "permissions": {}
  }
}

miniappManifest() 从 Vite root 开始向上查找最近的 package.json。
hb-sdk remote 从命令当前目录开始向上查找最近的 package.json。
在 monorepo 中，应从小程序项目目录运行 CLI，并让 Vite root 与同一个项目对应，避免构建和远端命令读取不同文件。
package.json.version 不属于 heybox，但仍是 Manifest 的版本来源；生产构建要求它符合 Semantic Versioning 2.0.0 的 canonical MAJOR.MINOR.PATCH[-PRERELEASE] 形式。首尾空白会被去除，但 build metadata（例如 1.2.3+build.1）、0.0.0 和 0.0.0-alpha 都会被拒绝。

package.json.name 是 npm 包名，heybox.name 是随审核版本发布的小程序展示名称，两者不是同一字段。heybox 写成数组、字符串或 null 会失败。版本资料、平台、权限、窗口和 Companion 声明不要复制到 Vite options、环境变量或页面代码中；Vite 只需要无参注册一次 miniappManifest()。

字段总览

字段	类型	要求
`name`	`string`	`0.8.2` 起必填；规范化后为 1–40 个 Unicode 字符
`desc`	`string`	可选；`0.9.1` 起支持，去除首尾空白后最多 200 个 Unicode 字符
`icon`	`string`	`0.8.2` 起必填；指向项目内 200×200 图片
`coverImages`	`string[]`	`0.8.2` 起必填；包含 1–5 个不重复的项目内图片路径
`category`	`string`	新上传版本必填；仅接受 `tool`、`game` 或 `other`
`platforms`	`string[]`	必填、非空、不能重复
`permissions`	`object`	`0.8.x` 缺失时兼容告警；`0.9.0` 预发布版和稳定版均必填，无权限需求时用 `{}`
`window`	`object`	可选；存在时至少包含一个受支持字段
`bindAppIds`	`string[]`	可选；缺失或空数组表示当前构建无关联游戏
`companions`	`object`	可选；存在时必须是非空对象
`workspaceCards`	`string`	可选；项目内的单一 TypeScript Controller 入口，需声明卡片权限、桌面平台及关联游戏
`miniProgramId`	`string`	真机调试与作用于当前小程序的远端命令需要；通常由 CLI 管理

`name`、`icon` 与 `coverImages`

这三个字段是一组随版本审核的展示资料，当前 0.8.2 项目必须全部配置：只写一部分会直接失败。name 会先做 NFKC 规范化并去除首尾 Unicode 空白，结果须为 1–40 个字符、包含文字或数字，且不能包含控制字符或 <>&"'。

icon 与 coverImages 都使用相对当前 package.json 的项目内图片路径，只接受 JPEG、PNG、GIF 或 WebP；不接受 URL、绝对路径、上级目录、依赖目录、构建目录或逃逸项目的符号链接。icon 必须是 200×200，封面需要 1–5 张且路径不能重复；每张图片不超过 10 MiB 和 4000 万像素。

miniappManifest() 会原样复制图片并把产物路径写入 Manifest，不会压缩、裁剪或重新编码。官方模板的占位图只用于开发和构建，提交审核前必须替换。已有项目的自动迁移条件、版本审核语义、产物预算和 pnpm sharp 安装要求统一见版本名称与图片。

`desc`：小程序简介

SDK 0.9.1 起可在 heybox.desc 声明简介，与 name 同级：

json

{
  "heybox": {
    "desc": "查询游戏数据，记录自己的游玩进度。"
  }
}

该字段可省略。构建会去除首尾 Unicode 空白，空字符串不写入 Manifest；非空内容最多 200 个 Unicode code point，允许换行，但不接受其他控制字符、格式控制字符或 Unicode 行/段分隔符。null、数组和其他非字符串值会报错。

miniappManifest() 将规范化后的内容写入 dist/manifest.json 的 desc；构建和部署均会校验。使用支持该字段的简介页时展示当前发布资料中的简介，未声明时不展示。修改简介后需重新构建并随版本提交，发布流程见版本名称与图片。

小程序类别

在项目根 package.json 的 heybox.category 声明类别，与 permissions 同级，示例见最小配置。

可选值为 tool（工具）、game（游戏）、other（其他）。miniappManifest() 在构建时把它写入 dist/manifest.json 的 category；hb-sdk build 和 hb-sdk remote deploy 会校验配置与产物一致。CLI 提交及 Open 上传均使用包内声明，Open 提审页不展示或提供手动选择类别，审核通过并发布后才更新线上类别。

新上传版本必须声明类别，包括已有小程序发布新版。即使 COA 已设置类别，也不能省略 manifest.category；CLI 构建/部署、Open 上传和后端提审均会校验。早于本版本构建且缺少类别的历史产物不能直接重新上传或提审，旧项目必须补充配置并使用当前 SDK 重新构建；已发布版本不受影响。空字符串、null、非字符串和未知类别会报错。开发者提审接口不再定义独立的 category 参数，类别只从 Manifest 读取。

每次提审都必须从当前项目重新构建并上传，不支持 --from-version 或在 Open 选择历史版本产物。缺少类别的项目需补充配置后重新构建、上传；已发布版本不会因此失效。开发者修改类别需要更新配置并重新构建、上传新版本。COA 运营维护存量分类的入口不受影响。此功能需要部署支持 Manifest 类别的后端与 Open，并使用包含该构建能力的 SDK。

`platforms`

platforms 表示项目实际承诺适配并完成验收的平台，不是客户端自动探测结果。

允许值为：

android
ios
ohos
windows
macos
linux

数组必须非空，不能包含未知值或重复项。构建产物会按上面的固定顺序规范化，而不是保留输入顺序。官方模板默认声明 android、ios、ohos、windows、macos，这只是起始配置；未适配的平台应移除，新增平台后应完成对应真机验收。

声明仍停留在旧模板的移动端默认（android、ios、ohos）时，hb-sdk dev 与 hb-sdk build 会输出一条非阻断提示，提醒项目可以补充桌面平台声明；该提示不影响构建结果，刻意只做移动端的项目可忽略。linux 目前没有客户端基线与 API 兼容声明，暂不建议声明。

Companion 的 windows-x64 target 要求同时声明 windows，macos-arm64 要求同时声明 macos。linux 可以表达桌面平台适配，但当前没有对应的 Companion target。

`permissions`

permissions 是严格对象：每个权限项都必须显式提供 boolean 类型的 enabled，enabled: false 的项目不会写入 Manifest；只有 network 额外接受可选的 useOfficialDomain: boolean。未知权限、未知字段或错误类型都会使构建失败。

具体权限键、覆盖 API、平台批准、用户授权与版本迁移规则统一见权限声明，本页不重复维护权限目录。

`window`

window 是可选的严格对象，用于声明新 PC 的 defaultWidth、defaultHeight、minWidth、minHeight 和 resizable。省略 resizable 时默认 true；窗口位置不开放声明，运行时当前尺寸使用 viewport.getWindowInfo() 读取。

尺寸范围、字段配对和构建期错误规则统一见窗口尺寸与可缩放性。

`bindAppIds`

bindAppIds 关联当前版本对应的小黑盒 PC 游戏 appid，用于已发布版本的 PC 游戏工作区发现。它是版本发布元数据，不是 Runtime 权限，也不会改变 navigation.openAppPage() 的行为。

每项必须是规范十进制字符串，例如 "730"；不接受 number、0、前导零、空白、符号或小数。
数值范围为 1 到 2147483647。
同一数组不能重复，最多 20 项。
构建会按数值升序写入 Manifest，本地校验不联网确认游戏是否真实存在。
缺失或 [] 在普通本地构建中都表示无关联游戏；远端预检和提审会继续校验游戏可用性。

查询关联游戏 ID

bash

hb-sdk remote games search "游戏名" --json
hb-sdk remote games search "游戏名" --offset 10 --limit 10 --json

查询复用平台现有游戏搜索能力，使用 CLI 登录态，不需要位于项目目录或先绑定远端小程序。支持中文或英文游戏名，关键词为 1–100 个字符。--offset 默认为 0（最大 10000），--limit 默认为 10（1–20）。

JSON 输出为 { games: [{ appid, name, name_en?, icon_url? }], has_more, next_offset }，其中 appid 为字符串，英文名和图片可缺省。与资源位申请页一致，每次多请求一条候选，以返回数量推算 has_more，根据 next_offset 翻页；这是客户端分页提示，不是服务端确认的结束标记。无结果时 games 为空；请求失败会报错并以非零状态退出，不作为空结果处理。

CLI 游戏搜索提供请求频率保护。提示操作过于频繁时，请等待后再试，避免连续重复执行。

结果只是候选，请核对具体游戏及平台，不要直接采用第一项或猜测 ID。确认服务于该 PC 游戏后，将对应 appid 写入 heybox.bindAppIds，无需转换；它不是 Steam 用户账号 ID，也不保证所有候选都是 Steam 游戏。游戏是否可绑定仍以部署预检和提审校验为准。该命令只查询，不自动修改配置或提交版本。

资料完善提醒

开发服务每次启动检查一次资料，页面刷新与热更新不重复刷屏。构建成功时检查生成的 Manifest；remote deploy 在上传前检查最终 Manifest，内部构建不重复输出同一组提醒。Web 选择构建目录后也会展示相同的完善建议。

MINIAPP_DESC_MISSING：简介未填写或为空白，建议补充 heybox.desc。
MINIAPP_TOOL_GAME_BINDING_MISSING：类别为 tool 且未关联游戏，建议按实际用途查询并填写 heybox.bindAppIds；通用工具可保持为空。

这些提醒不影响构建或提审，不改变退出码。非法值继续按原规则报错；历史项目无需批量迁移。部署命令的提醒输出到 stderr，--json 的 stdout 保持 JSON。模板类别初始为 other，请按实际功能选择类别，不要通过改成 other 绕过提醒。

`companions`

companions 是可选的非空 alias 映射，用于声明随当前小程序版本发布的固定桌面辅助应用。每项定义 displayName、可选 capabilities 和至少一个桌面 targets；source 相对当前 package.json 解析。

Companion target 必须与 platforms 中的桌面平台匹配，并同时声明 permissions.companion.enabled: true、获得平台批准。精确 schema、归档限制、调试和运行边界统一见受管桌面程序。

`workspaceCards`

workspaceCards 是项目内的单一 TypeScript Controller 入口路径，例如 "./src/workspace-cards.ts"。声明后还须启用 permissions.workspaceCards、在 platforms 中包含 windows 或 macos，并提供非空 bindAppIds；构建会检查这些条件。

构建器将入口编译为卡片产物，并在 Manifest 中生成 workspaceCards 对象；不要把生成对象写回项目配置。平台批准、Controller 编写、本地调试与发布验收见工作区卡片。

`miniProgramId`

miniProgramId 把当前本地项目绑定到一个远端工坊小程序。它不进入 dist/manifest.json，也不参与能力或权限判定。

hb-sdk remote create 创建远端小程序后写入该字段。
hb-sdk remote bind <mini-program-id> 验证当前主体可管理目标后写入该字段。
hb-sdk remote list、remote access 与 remote entity ... 可在未绑定时运行；remote create / bind 用于建立绑定。
hb-sdk dev 启动前必须登录 CLI、绑定小程序并成功校验远端配置；未绑定时直接退出并提示创建或绑定命令。remote info、deploy、versions 等作用于当前小程序的命令要求已有绑定。
空字符串或缺失都表示项目未绑定；官方模板初始值为空。
覆盖已有的不同绑定时，remote bind 使用 --force，remote create 使用 --force-bind。

hb-sdk dev 启动 Browser Mock 同样要求 CLI 登录和项目绑定；真实手机、PC 调试还需要有效启动票。所有 remote 子命令都需要 CLI 登录态，是否需要项目绑定取决于具体命令。建议让 CLI 管理 miniProgramId，不要通过构建脚本动态改写。

构建与命令的关系

入口	如何使用 `heybox`
`miniappManifest()` / `vite build`	校验并打包版本资料与其他构建期声明，生成 `dist/manifest.json`；不访问远端服务
`hb-sdk build`	清理并构建 `dist/`，再校验 Manifest 与版本资料、平台、窗口、关联游戏等项目声明一致
`hb-sdk dev`	Browser Mock 无需登录或绑定；真实调试读取当前绑定与远端权限
`remote access` / `entity ...` / `list`	要求登录，不要求项目绑定；查询账号范围和远端小程序
`remote create` / `bind`	要求登录；创建或验证远端小程序后写入 `miniProgramId`
`remote info` / `deploy` / `versions` 等	要求登录与绑定；读取或修改当前绑定的小程序

hb-sdk build 不要求 CLI 登录、项目绑定或网络访问。不要手工修改 dist/manifest.json；配置变化后应重新构建，CLI 会拒绝声明与产物不一致的版本。完整命令流程见CLI 与本地 mock 调试。

完成检查

heybox 是项目 package.json 中的对象，CLI 与 Vite 读取同一个文件。
name、icon 与 coverImages 已全部配置，图片文件符合格式、尺寸、大小和路径要求。
category 已声明为 tool、game 或 other，并通过构建写入 Manifest。
platforms 只包含已适配并完成验收的平台，且没有重复项。
permissions 只声明实际使用的能力；无权限需求时显式配置 {}。
window、bindAppIds 和 companions 的值符合各自 schema。
miniProgramId 由 CLI 管理，并区分无需绑定的发现/建绑命令与需要绑定的当前项目命令。
Vite 中只无参注册一次 miniappManifest()，并通过 hb-sdk build 验证最终产物。

package.json 项目配置 ​

最小配置 ​

字段总览 ​

name、icon 与 coverImages ​

desc：小程序简介 ​

小程序类别 ​

platforms ​

permissions ​

window ​

bindAppIds ​

查询关联游戏 ID ​

资料完善提醒 ​

companions ​

workspaceCards ​

miniProgramId ​

构建与命令的关系 ​

相关文档 ​

完成检查 ​