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

package/dist/index.esm.js

@@ -236,8 +236,9 @@ class MiniProgramBridgeClient {
         this.eventBus.off(eventName, handler);
     }
     /** 调用父容器开放能力。 */
-    async request(method, payload) {
+    async request(method, ...args) {
         await this.ready();
+        const payload = args[0];
         const id = createMessageId();
         const message = {
             namespace: MINI_PROGRAM_MESSAGE_NAMESPACE,
@@ -884,4 +885,4 @@ const hbSDK = {
     network,
 };
 
-export { AUTH_LOGIN_METHOD, HbMiniProgramNetworkError, HbMiniProgramSDKError, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MiniProgramSDK, NETWORK_REQUEST_METHOD, SDK_HANDSHAKE_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, USER_GET_INFO_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, auth, createMiniProgramSDK, hbSDK as default, isMiniProgramBridgeMessage, network, off, on, ready, share, storage, user, viewport };
+export { HbMiniProgramNetworkError, HbMiniProgramSDKError, MiniProgramSDK, auth, createMiniProgramSDK, hbSDK as default, network, off, on, ready, share, storage, user, viewport };

package/dist/miniapp-publish.cjs.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const PUBLISH_VERSION_RE = /^\d+\.\d+\.\d+$/;
+function isValidMiniappManifestVersion(version) {
+    return PUBLISH_VERSION_RE.test(String(version || '').trim());
+}
+
+const MINIAPP_UPLOAD_SCOPE = 'activity';
+const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
+const PUBLISH_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/publish';
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+function normalizeRelativePath(relativePath) {
+    return String(relativePath || '')
+        .replace(/\\/g, '/')
+        .replace(/^\/+/, '')
+        .replace(/\/+/g, '/');
+}
+function relativePathContainsNodeModulesSegment(relativePath) {
+    return normalizeRelativePath(relativePath)
+        .split('/')
+        .some((segment) => segment.length > 0 && segment.toLowerCase() === 'node_modules');
+}
+function getMiniProgramUploadAlias(miniProgramId) {
+    let hash = FNV_OFFSET;
+    const input = String(miniProgramId || '');
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    }
+    return hash.toString(36);
+}
+function getMiniappUploadKey(input) {
+    const alias = getMiniProgramUploadAlias(input.miniProgramId);
+    const normalized = normalizeRelativePath(input.relativePath);
+    return `/u/${alias}/${input.version}/${normalized}`;
+}
+function validateUploadPaths(items, options) {
+    const limit = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
+    for (const item of items) {
+        const key = getMiniappUploadKey({
+            miniProgramId: options.miniProgramId,
+            version: options.version,
+            relativePath: item.relativePath,
+        });
+        if (key.length > limit) {
+            return `文件路径过长，请缩短构建产物文件名或目录层级：${item.relativePath}`;
+        }
+    }
+    return undefined;
+}
+function shouldUploadDistFile(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    if (!normalized) {
+        return false;
+    }
+    if (normalized === 'manifest.json') {
+        return false;
+    }
+    if (normalized === '.DS_Store' || normalized.endsWith('/.DS_Store')) {
+        return false;
+    }
+    if (normalized.toLowerCase().endsWith('.map')) {
+        return false;
+    }
+    return true;
+}
+
+exports.ACTIVITY_UPLOAD_KEY_MAX_LENGTH = ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
+exports.MINIAPP_UPLOAD_SCOPE = MINIAPP_UPLOAD_SCOPE;
+exports.PUBLISH_USER_MINIPROGRAM_API_PATH = PUBLISH_USER_MINIPROGRAM_API_PATH;
+exports.getMiniProgramUploadAlias = getMiniProgramUploadAlias;
+exports.getMiniappUploadKey = getMiniappUploadKey;
+exports.isValidVersion = isValidMiniappManifestVersion;
+exports.normalizeRelativePath = normalizeRelativePath;
+exports.relativePathContainsNodeModulesSegment = relativePathContainsNodeModulesSegment;
+exports.shouldUploadDistFile = shouldUploadDistFile;
+exports.validateUploadPaths = validateUploadPaths;

package/dist/miniapp-publish.esm.js

@@ -0,0 +1,67 @@
+const PUBLISH_VERSION_RE = /^\d+\.\d+\.\d+$/;
+function isValidMiniappManifestVersion(version) {
+    return PUBLISH_VERSION_RE.test(String(version || '').trim());
+}
+
+const MINIAPP_UPLOAD_SCOPE = 'activity';
+const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
+const PUBLISH_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/publish';
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+function normalizeRelativePath(relativePath) {
+    return String(relativePath || '')
+        .replace(/\\/g, '/')
+        .replace(/^\/+/, '')
+        .replace(/\/+/g, '/');
+}
+function relativePathContainsNodeModulesSegment(relativePath) {
+    return normalizeRelativePath(relativePath)
+        .split('/')
+        .some((segment) => segment.length > 0 && segment.toLowerCase() === 'node_modules');
+}
+function getMiniProgramUploadAlias(miniProgramId) {
+    let hash = FNV_OFFSET;
+    const input = String(miniProgramId || '');
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    }
+    return hash.toString(36);
+}
+function getMiniappUploadKey(input) {
+    const alias = getMiniProgramUploadAlias(input.miniProgramId);
+    const normalized = normalizeRelativePath(input.relativePath);
+    return `/u/${alias}/${input.version}/${normalized}`;
+}
+function validateUploadPaths(items, options) {
+    const limit = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
+    for (const item of items) {
+        const key = getMiniappUploadKey({
+            miniProgramId: options.miniProgramId,
+            version: options.version,
+            relativePath: item.relativePath,
+        });
+        if (key.length > limit) {
+            return `文件路径过长，请缩短构建产物文件名或目录层级：${item.relativePath}`;
+        }
+    }
+    return undefined;
+}
+function shouldUploadDistFile(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    if (!normalized) {
+        return false;
+    }
+    if (normalized === 'manifest.json') {
+        return false;
+    }
+    if (normalized === '.DS_Store' || normalized.endsWith('/.DS_Store')) {
+        return false;
+    }
+    if (normalized.toLowerCase().endsWith('.map')) {
+        return false;
+    }
+    return true;
+}
+
+export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, MINIAPP_UPLOAD_SCOPE, PUBLISH_USER_MINIPROGRAM_API_PATH, getMiniProgramUploadAlias, getMiniappUploadKey, isValidMiniappManifestVersion as isValidVersion, normalizeRelativePath, relativePathContainsNodeModulesSegment, shouldUploadDistFile, validateUploadPaths };

package/dist/templates/vue3-vite-ts/README.md.ejs

@@ -10,12 +10,14 @@ npm run dev
 npm run typecheck
 npm run test:unit
 npm run build
+npm run deploy
 ```
 
 ## 开发模式
 
 - `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
 - `npm run build`：先执行 TypeScript 检查，再构建生产产物。
+- `npm run deploy`：构建并发布当前小程序。发布前需要先把 `package.json` 中的 `heybox.miniProgramId` 改成后台分配的真实小程序 id，并执行过 `npx hb-sdk login`。
 
 ## 更多能力
 

package/dist/templates/vue3-vite-ts/package.json.ejs

@@ -3,8 +3,13 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
+  "heybox": {
+    "miniProgramId": ""
+  },
   "scripts": {
+    "hb-sdk": "hb-sdk",
     "dev": "hb-sdk dev",
+    "deploy": "hb-sdk deploy",
     "build": "vue-tsc --noEmit && vite build",
     "preview": "vite preview",
     "typecheck": "vue-tsc --noEmit",

package/dist/templates/vue3-vite-ts/vite.config.ts

@@ -1,6 +1,7 @@
 import vue from '@vitejs/plugin-vue';
+import { miniappManifest } from '@heybox/hb-sdk/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
-  plugins: [vue()],
+  plugins: [vue(), miniappManifest()],
 });

package/dist/vite.cjs.js

@@ -0,0 +1,86 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var path = require('node:path');
+
+const MINIAPP_TEMPLATE_VERSION = '0.0.0';
+const BUILD_VERSION_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+function getMiniappManifestBuildWarning(version) {
+    if (version === MINIAPP_TEMPLATE_VERSION) {
+        return '@heybox/hb-sdk 提示：package.json.version 仍是模板默认的 0.0.0；manifest 会写入，但发布前必须改成实际 x.y.z 版本';
+    }
+    if (!BUILD_VERSION_RE.test(version)) {
+        return `package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`;
+    }
+    return undefined;
+}
+function renderMiniappManifest(manifest) {
+    return `${JSON.stringify({ version: manifest.version }, null, 2)}\n`;
+}
+
+function findNearestPackageJsonPath(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const packageJsonPath = path.join(current, 'package.json');
+        if (node_fs.existsSync(packageJsonPath)) {
+            return packageJsonPath;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return path.join(path.resolve(startDir), 'package.json');
+        }
+        current = parent;
+    }
+}
+function readMiniappVersionFromPackageJson(root) {
+    const packageJsonPath = findNearestPackageJsonPath(root);
+    let content;
+    try {
+        content = node_fs.readFileSync(packageJsonPath, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 读取 package.json 失败：${formatReason(error)}`);
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 解析 package.json 失败：${formatReason(error)}`);
+    }
+    if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+        throw new Error('@heybox/hb-sdk 提示：package.json.version 必须是非空字符串');
+    }
+    return packageJson.version.trim();
+}
+function formatReason(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+
+function miniappManifest() {
+    let root = process.cwd();
+    let outDir = 'dist';
+    return {
+        name: 'heybox-miniapp-manifest',
+        apply: 'build',
+        configResolved(resolved) {
+            root = resolved.root;
+            outDir = resolved.build.outDir;
+        },
+        writeBundle() {
+            const version = readMiniappVersionFromPackageJson(root);
+            const warning = getMiniappManifestBuildWarning(version);
+            if (warning) {
+                this.warn(warning);
+            }
+            const manifestPath = path.resolve(root, outDir, 'manifest.json');
+            node_fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+            node_fs.writeFileSync(manifestPath, renderMiniappManifest({ version }));
+        },
+    };
+}
+
+exports.miniappManifest = miniappManifest;

package/dist/vite.esm.js

@@ -0,0 +1,84 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const MINIAPP_TEMPLATE_VERSION = '0.0.0';
+const BUILD_VERSION_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+function getMiniappManifestBuildWarning(version) {
+    if (version === MINIAPP_TEMPLATE_VERSION) {
+        return '@heybox/hb-sdk 提示：package.json.version 仍是模板默认的 0.0.0；manifest 会写入，但发布前必须改成实际 x.y.z 版本';
+    }
+    if (!BUILD_VERSION_RE.test(version)) {
+        return `package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`;
+    }
+    return undefined;
+}
+function renderMiniappManifest(manifest) {
+    return `${JSON.stringify({ version: manifest.version }, null, 2)}\n`;
+}
+
+function findNearestPackageJsonPath(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const packageJsonPath = path.join(current, 'package.json');
+        if (existsSync(packageJsonPath)) {
+            return packageJsonPath;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return path.join(path.resolve(startDir), 'package.json');
+        }
+        current = parent;
+    }
+}
+function readMiniappVersionFromPackageJson(root) {
+    const packageJsonPath = findNearestPackageJsonPath(root);
+    let content;
+    try {
+        content = readFileSync(packageJsonPath, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 读取 package.json 失败：${formatReason(error)}`);
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 解析 package.json 失败：${formatReason(error)}`);
+    }
+    if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+        throw new Error('@heybox/hb-sdk 提示：package.json.version 必须是非空字符串');
+    }
+    return packageJson.version.trim();
+}
+function formatReason(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+
+function miniappManifest() {
+    let root = process.cwd();
+    let outDir = 'dist';
+    return {
+        name: 'heybox-miniapp-manifest',
+        apply: 'build',
+        configResolved(resolved) {
+            root = resolved.root;
+            outDir = resolved.build.outDir;
+        },
+        writeBundle() {
+            const version = readMiniappVersionFromPackageJson(root);
+            const warning = getMiniappManifestBuildWarning(version);
+            if (warning) {
+                this.warn(warning);
+            }
+            const manifestPath = path.resolve(root, outDir, 'manifest.json');
+            mkdirSync(path.dirname(manifestPath), { recursive: true });
+            writeFileSync(manifestPath, renderMiniappManifest({ version }));
+        },
+    };
+}
+
+export { miniappManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.2.0-alpha.1",
+  "version": "0.3.1",
   "description": "",
   "exports": {
     ".": {
@@ -16,6 +16,19 @@
       "node": "./dist/protocol.cjs.js",
       "browser": "./dist/protocol.esm.js",
       "default": "./dist/protocol.esm.js"
+    },
+    "./miniapp-publish": {
+      "types": "./types/miniapp-publish/index.d.ts",
+      "heybox": "./src/miniapp-publish/index.ts",
+      "node": "./dist/miniapp-publish.cjs.js",
+      "browser": "./dist/miniapp-publish.esm.js",
+      "default": "./dist/miniapp-publish.esm.js"
+    },
+    "./vite": {
+      "types": "./types/vite/index.d.ts",
+      "import": "./dist/vite.esm.js",
+      "require": "./dist/vite.cjs.js",
+      "default": "./dist/vite.esm.js"
     }
   },
   "bin": {
@@ -30,6 +43,15 @@
   "keywords": [],
   "author": "",
   "license": "ISC",
+  "dependencies": {},
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-json": "^6.1.0",
@@ -42,6 +64,7 @@
     "@types/node": "24.10.1",
     "@vitest/coverage-v8": "^3.2.4",
     "commander": "^12.1.0",
+    "cos-nodejs-sdk-v5": "2.15.4",
     "ejs": "^3.1.10",
     "env-paths": "^2.2.1",
     "fs-extra": "^11.3.0",
@@ -53,6 +76,7 @@
     "rollup": "^4.52.4",
     "typescript": "^5.9.3",
     "vue": "2.7.16",
+    "vite": "^8.0.12",
     "vitest": "^3.2.4"
   },
   "publishConfig": {
@@ -86,9 +110,11 @@
     "build:templates": "node scripts/copy-cli-templates.cjs",
     "build:types": "tsc -p tsconfig.dts.json",
     "check:boundary": "node scripts/check-boundary.cjs",
+    "check:docs-sync": "node scripts/check-docs-sync.cjs",
     "clean": "rimraf ./dist && rimraf ./types",
     "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",
+    "test:vite": "vitest run --config vitest.vite.config.ts",
     "test:watch": "NODE_OPTIONS='--conditions=heybox' vitest"
   }
 }

package/skill/SKILL.md

@@ -22,9 +22,10 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 3. For common business flows, read `references/recipes.md`.
 4. For CLI commands, local mock runtime, generated templates, CLI login cache, Agent Skill doctor, and update reminders, read `references/cli.md`.
 5. For allowed/forbidden capabilities and security boundaries, read `references/safety-boundaries.md`.
-6. For generated documentation provenance and deeper API lookup paths, read `references/llms-index.md`.
-7. For smoke-test expectations, positive examples, and anti-examples, read `references/examples.md`.
-8. For evaluating whether another agent followed this skill, read `references/smoke-evaluation.md`.
+6. For Vite build manifest behavior, read `references/api-root.md` and `references/safety-boundaries.md`.
+7. For generated documentation provenance and deeper API lookup paths, read `references/llms-index.md`.
+8. For smoke-test expectations, positive examples, and anti-examples, read `references/examples.md`.
+9. For evaluating whether another agent followed this skill, read `references/smoke-evaluation.md`.
 
 ## Step 3: Follow import rules
 
@@ -47,14 +48,18 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 
 1. Use `hb-sdk create <project-name>` to scaffold a standalone external mini-program template.
 2. Use `hb-sdk dev` for local browser debugging through the built-in mock runtime host.
-3. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container.
-4. Use `--port`, `--mock-port`, `--host`, and `--no-open` when the default Vite/mock ports, host, or browser opening behavior need to be controlled.
-5. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache.
-6. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
-7. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
-8. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
-9. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
-10. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
+3. Use `hb-sdk deploy` to build and publish the current project. It reads `package.json.heybox.miniProgramId`, runs the project's `build` script via the package manager auto-detected by lockfile, then uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`) and calls the publish API.
+4. Use `hb-sdk deploy --skip-build` only when the `dist/` directory is already prepared by an upstream CI stage. Missing `dist/manifest.json` or `dist/index.html` aborts the run.
+5. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container.
+6. Use `--port`, `--mock-port`, `--host`, and `--no-open` when the default Vite/mock ports, host, or browser opening behavior need to be controlled.
+7. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache.
+8. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
+9. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
+10. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+11. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
+12. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
+13. Do not pass `mini_program_id` as a CLI flag or environment variable; it must come from `package.json.heybox.miniProgramId`.
+14. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publishing is `@heybox/hb-sdk/miniapp-publish`.
 
 ## Step 6: Preserve capability boundaries
 
@@ -65,6 +70,7 @@ For iframe mini-program business code:
 3. Do not use unsupported storage operations such as delete, clear, info listing, or global client storage access.
 4. Do not pass raw host protocol fields through `network.request`; use only the public axios-like request config.
 5. Do not construct bridge envelopes, nonce logic, or raw `postMessage` calls.
+6. Build artifacts may include `dist/manifest.json`; business code should not fetch a deployed manifest directly because it is not a CDN asset.
 
 For CLI and local development:
 
@@ -81,15 +87,20 @@ For host/runtime/protocol-maintenance code:
 ## Step 7: Validate changes
 
 1. Run the nearest package tests and builds with repo-native commands when editing this repository.
-2. When modifying this repo's source skill at `packages/hb-sdk/skill`, run:
-   - `node packages/hb-sdk/skill/scripts/check-references.mjs`
-   - `node packages/hb-sdk/skill/scripts/validate-skill.mjs`
+2. When modifying docs, skill instructions, CLI guidance, or public agent-skill sync points, start with:
+   - `pnpm --filter @heybox/hb-sdk run check:docs-sync`
+   - `cat packages/hb-sdk/DOC_SYNC_CHECKLIST.md`
+3. When modifying this repo's source skill at `packages/hb-sdk/skill` and preparing distributable artifacts, also run:
    - `node packages/hb-sdk/skill/scripts/package-skill.mjs`
-3. When modifying CLI, mock runtime, package exports, or package dependency direction, also run:
+4. When modifying CLI, mock runtime, package exports, or package dependency direction, also run:
    - `pnpm --filter @heybox/hb-sdk run check:boundary`
    - `pnpm --filter @heybox/hb-sdk run test:unit`
-4. Inspect the generated zip before distribution:
+5. Inspect the generated zip before distribution:
    - `unzip -l packages/hb-sdk/hb-sdk.zip | sed -n '1,120p'`
-5. Verify public payload sync before publishing:
+6. When adding or modifying the deploy command or its upload pipeline, also run:
+   - `pnpm --filter @heybox/hb-sdk run check:boundary`
+   - `pnpm --filter @heybox/hb-sdk run test:unit`
+   - Verify `dist/cli.cjs` does not have any `require('cos-nodejs-sdk-v5')` left after `build:cli`; the boundary check enforces this automatically.
+6. Verify public payload sync before publishing:
    - `pnpm --filter @heybox-spa/open run sync:agent-skills`
    - `pnpm --filter @heybox-spa/open run check:agent-skills`