@heybox/hb-sdk 0.2.0-alpha.1 → 0.3.1

package/README.md

@@ -221,14 +221,45 @@ try {
 | --- | --- |
 | `hb-sdk create <project-name>` | 创建外部小程序模板。 |
 | `hb-sdk dev` | 启动当前项目的 Vite dev server 和浏览器 mock 宿主环境，并默认打开调试页。 |
+| `hb-sdk deploy [--skip-build]` | 构建并发布当前小程序到 Heybox 后台。`--skip-build` 跳过 build 直接上传 `dist/` 并 publish。 |
 | `hb-sdk login` | 登录 Heybox，并把 CLI 自己需要的登录态保存在本地缓存中。 |
 | `hb-sdk login status` | 查看脱敏后的 CLI 登录态。 |
 | `hb-sdk login clear` | 清理 CLI 登录态。 |
 | `hb-sdk doctor` | 检查本机 `hb-sdk` Agent Skill 是否匹配当前 SDK，并输出手动安装/刷新命令。 |
 
+## hb-sdk deploy
+
+`hb-sdk deploy` 把 build、CDN 上传、发布 API 串成单条命令。命令前置要求：
+
+1. `package.json` 必须含 `heybox.miniProgramId` 字段，CLI 只从这里读 mini program id：
+   ```json
+   {
+     "heybox": {
+       "miniProgramId": "mp_xxxxxxxx"
+     }
+   }
+   ```
+2. 已运行过 `hb-sdk login` 登录 Heybox。
+3. 项目根有 `scripts.build`，会被 CLI 通过 lockfile 自动选用的 `pnpm`、`yarn` 或 `npm` 触发；无 lockfile 时回退 `npm`。
+4. 构建产物落在 `dist/`，包含 `index.html` 和 `manifest.json`。
+
+执行流程：
+
+1. 校验 `heybox.miniProgramId` 和登录态。
+2. 触发 `<pm> run build`，除非使用 `--skip-build`。
+3. 解析 `dist/manifest.json`，校验 `version` 为 `x.y.z`，自动剥离 BOM。
+4. 遍历 `dist/` 文件，跳过 `manifest.json`、`.DS_Store`、`.map`；遇到 symlink 或 `node_modules` 直接报错。
+5. 校验所有上传路径长度不超过 64。
+6. 4 并发上传到 COS。任一文件失败立刻 abort，不调 publish。
+7. 全部上传成功后调发布 API，原样透传后端 msg。
+
+`--skip-build` 用于 CI 双阶段：上一步已经 build 完缓存好了 `dist/`，本步只做上传和 publish。`dist/manifest.json` 或 `dist/index.html` 缺失会立即报错。
+
+`manifest.json` 不会上传到 CDN，只作为 publish 请求的 `manifest` 字段提交。这与 Vite 插件文档中的契约一致。
+
 CLI 登录态只供 CLI 命令访问黑盒接口时复用，不会注入 iframe SDK，也不会改变 `auth.login()`、`user.getInfo()`、`network.request()` 或 mock 宿主中的用户状态。
 
-CLI 会在成功执行命令后检查 npm registry 上的 `@heybox/hb-sdk@latest`。如果发现新版本，会在 stderr 打印升级提醒；检查失败会静默跳过，不影响当前命令。可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用版本提醒。
+`create`、`dev`、`login`、`login status`、`login clear` 这些 CLI 命令会在成功执行后检查 npm registry 上的 `@heybox/hb-sdk@latest`。如果发现新版本，会在 stderr 打印升级提醒；检查失败会静默跳过，不影响当前命令。`doctor` 不会附带版本提醒，避免把 skill 诊断输出和升级提示混在一起。可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用版本提醒；`CI=true` 时也会自动跳过检查。
 
 ## SDK 与 Runtime
 
@@ -244,6 +275,37 @@ CLI 会在成功执行命令后检查 npm registry 上的 `@heybox/hb-sdk@latest
 - `network.request()` 的 `validateStatus` 只在 SDK 本地执行，不会被序列化给父容器。
 - `on()` 返回取消监听函数；组件卸载或页面销毁时应主动取消监听。
 - 使用 `createMiniProgramSDK()` 创建独立实例后，不再需要时应调用 `destroy()`。
+- 构建产物可以包含 `dist/manifest.json`，业务代码不应自行 fetch 已部署的 manifest；这个文件由发布流水线读取并上送后台。
+
+## Manifest
+
+`@heybox/hb-sdk/vite` 提供构建时插件 `miniappManifest()`。Vite 项目完成 `vite build` 后，会在输出目录写入 `manifest.json`：
+
+```json
+{
+  "version": "1.2.3"
+}
+```
+
+`version` 来自小程序项目自身的 `package.json.version`。`hb-sdk create` 生成的模板默认已注册插件；现有 Vite 项目可以在 `vite.config.ts` 中手动接入：
+
+```ts
+import { miniappManifest } from '@heybox/hb-sdk/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [miniappManifest()],
+});
+```
+
+失败与警告语义：
+
+- 读取 `package.json` 失败或 JSON 解析失败：`vite build` 直接失败，并输出具体原因。
+- `package.json.version` 不是非空字符串：`vite build` 直接失败。
+- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 输出 warning 并写入 manifest；`hb-sdk deploy` 会拒绝发布，必须改成实际 `x.y.z` 版本。
+- 版本号不满足极简 semver 形态 `x.y.z`：只输出 Rollup/Vite warning，仍会写入 manifest。
+
+`manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
 
 ## 导出
 
@@ -257,7 +319,9 @@ CLI 会在成功执行命令后检查 npm registry 上的 `@heybox/hb-sdk@latest
 - `HbMiniProgramSDKError`、`HbMiniProgramNetworkError`
 - 各模块公开类型，例如 `MiniProgramNetworkRequestConfig`、`MiniProgramNetworkResponse`、`MiniProgramUserInfoResult`
 
-协议常量、消息类型和守卫仍通过根入口与 `@heybox/hb-sdk/protocol` 子入口导出。宿主运行时等非业务页面代码应优先使用 `@heybox/hb-sdk/protocol`。
+协议常量、消息类型、能力目录、payload/result 映射和守卫只通过 `@heybox/hb-sdk/protocol` 子入口导出。iframe 小程序业务代码不应构造 raw bridge message，也不应直接处理 nonce 或 `postMessage` 信封；宿主运行时等非业务页面代码使用 `@heybox/hb-sdk/protocol`。
+
+构建时插件 `miniappManifest` 通过 `@heybox/hb-sdk/vite` 子入口导出，仅供 `vite.config.ts` 使用，不应在小程序业务代码里 import。
 
 ## 本仓库开发
 
@@ -265,6 +329,9 @@ CLI 会在成功执行命令后检查 npm registry 上的 `@heybox/hb-sdk@latest
 pnpm --filter @heybox/hb-sdk run test:unit
 pnpm --filter @heybox/hb-sdk run build:package
 pnpm --filter @heybox/hb-sdk run check:boundary
+pnpm --filter @heybox/hb-sdk run check:docs-sync
 ```
 
 `check:boundary` 用于保护 SDK、CLI、mock host 与 runtime 之间的依赖边界。调整 CLI、mock 或协议导出时应一起运行。
+
+`check:docs-sync` 用于校验 `README`、文档站 llms 镜像、skill references 与公开 `agent-skills` payload 没有漏同步。维护清单见 `packages/hb-sdk/DOC_SYNC_CHECKLIST.md`。