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

package/dist/miniapp-publish.cjs.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const MINIAPP_UPLOAD_SCOPE = 'activity';
+const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
+const PUBLISH_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/publish';
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+function isValidVersion(version) {
+    return VERSION_PATTERN.test(String(version || '').trim());
+}
+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 = isValidVersion;
+exports.normalizeRelativePath = normalizeRelativePath;
+exports.relativePathContainsNodeModulesSegment = relativePathContainsNodeModulesSegment;
+exports.shouldUploadDistFile = shouldUploadDistFile;
+exports.validateUploadPaths = validateUploadPaths;

package/dist/miniapp-publish.esm.js

@@ -0,0 +1,66 @@
+const MINIAPP_UPLOAD_SCOPE = 'activity';
+const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
+const PUBLISH_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/publish';
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+function isValidVersion(version) {
+    return VERSION_PATTERN.test(String(version || '').trim());
+}
+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, isValidVersion, normalizeRelativePath, relativePathContainsNodeModulesSegment, shouldUploadDistFile, validateUploadPaths };

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,62 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var path = require('node:path');
+
+const TEMPLATE_VERSION = '0.0.0';
+const SEMVER_LIKE_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+const TEMPLATE_VERSION_ERROR = '@heybox/hb-sdk 提示：请把 package.json.version 从模板默认的 0.0.0 改成实际版本号再发布';
+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 = readMiniappVersion(root);
+            if (!SEMVER_LIKE_RE.test(version)) {
+                this.warn(`package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`);
+            }
+            const manifestPath = path.resolve(root, outDir, 'manifest.json');
+            node_fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+            node_fs.writeFileSync(manifestPath, `${JSON.stringify({ version }, null, 2)}\n`);
+        },
+    };
+}
+function readMiniappVersion(root) {
+    const packageJsonPath = path.join(root, 'package.json');
+    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 必须是非空字符串');
+    }
+    const version = packageJson.version.trim();
+    if (version === TEMPLATE_VERSION) {
+        throw new Error(TEMPLATE_VERSION_ERROR);
+    }
+    return version;
+}
+function formatReason(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+
+exports.miniappManifest = miniappManifest;

package/dist/vite.esm.js

@@ -0,0 +1,60 @@
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const TEMPLATE_VERSION = '0.0.0';
+const SEMVER_LIKE_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+const TEMPLATE_VERSION_ERROR = '@heybox/hb-sdk 提示：请把 package.json.version 从模板默认的 0.0.0 改成实际版本号再发布';
+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 = readMiniappVersion(root);
+            if (!SEMVER_LIKE_RE.test(version)) {
+                this.warn(`package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`);
+            }
+            const manifestPath = path.resolve(root, outDir, 'manifest.json');
+            mkdirSync(path.dirname(manifestPath), { recursive: true });
+            writeFileSync(manifestPath, `${JSON.stringify({ version }, null, 2)}\n`);
+        },
+    };
+}
+function readMiniappVersion(root) {
+    const packageJsonPath = path.join(root, 'package.json');
+    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 必须是非空字符串');
+    }
+    const version = packageJson.version.trim();
+    if (version === TEMPLATE_VERSION) {
+        throw new Error(TEMPLATE_VERSION_ERROR);
+    }
+    return version;
+}
+function formatReason(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+
+export { miniappManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.2",
   "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,17 @@
   "keywords": [],
   "author": "",
   "license": "ISC",
+  "dependencies": {
+    "cos-nodejs-sdk-v5": "2.15.4"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-json": "^6.1.0",
@@ -53,6 +77,7 @@
     "rollup": "^4.52.4",
     "typescript": "^5.9.3",
     "vue": "2.7.16",
+    "vite": "^8.0.12",
     "vitest": "^3.2.4"
   },
   "publishConfig": {
@@ -86,9 +111,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`

package/skill/references/api-root.md

@@ -6,20 +6,23 @@
 
 - packages/hb-sdk/package.json
 - packages/hb-sdk/src/index.ts
+- packages/hb-sdk/src/vite/index.ts
 - packages/hb-sdk/README.md
 
 ## Contents
 
 - [Package metadata](#package-metadata)
 - [Public root entrypoint](#public-root-entrypoint)
+- [Vite plugin export](#vite-plugin-export)
 - [App-facing concepts](#app-facing-concepts)
 - [Public modules](#public-modules)
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.2.0-alpha.1`
+- Version at generation time: `0.2.0-alpha.2`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
+- Vite plugin export: `@heybox/hb-sdk/vite`
 
 ## Public root entrypoint
 
@@ -130,6 +133,131 @@ const hbSDK = {
 export default hbSDK;
 ```
 
+## Vite plugin export
+
+Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe mini-program business code.
+
+```ts
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const TEMPLATE_VERSION = '0.0.0';
+const SEMVER_LIKE_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+const TEMPLATE_VERSION_ERROR = '@heybox/hb-sdk 提示：请把 package.json.version 从模板默认的 0.0.0 改成实际版本号再发布';
+
+type MiniappManifestPlugin = {
+  name: string;
+  apply: 'build';
+  configResolved: (resolved: MiniappManifestResolvedConfig) => void;
+  writeBundle: (this: MiniappManifestPluginContext) => void;
+};
+
+interface MiniappManifestPluginContext {
+  warn: (message: string) => void;
+}
+
+interface MiniappManifestResolvedConfig {
+  root: string;
+  build: {
+    outDir: string;
+  };
+}
+
+export function miniappManifest(): MiniappManifestPlugin {
+  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 = readMiniappVersion(root);
+
+      if (!SEMVER_LIKE_RE.test(version)) {
+        this.warn(`package.json.version "${version}" 不是标准 semver，仍会写入 manifest.json`);
+      }
+
+      const manifestPath = path.resolve(root, outDir, 'manifest.json');
+      mkdirSync(path.dirname(manifestPath), { recursive: true });
+      writeFileSync(manifestPath, `${JSON.stringify({ version }, null, 2)}\n`);
+    },
+  };
+}
+
+function readMiniappVersion(root: string): string {
+  const packageJsonPath = path.join(root, 'package.json');
+  let content: string;
+
+  try {
+    content = readFileSync(packageJsonPath, 'utf8');
+  } catch (error) {
+    throw new Error(`@heybox/hb-sdk 读取 package.json 失败：${formatReason(error)}`);
+  }
+
+  let packageJson: { version?: unknown };
+
+  try {
+    packageJson = JSON.parse(content) as { version?: unknown };
+  } 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 必须是非空字符串');
+  }
+
+  const version = packageJson.version.trim();
+
+  if (version === TEMPLATE_VERSION) {
+    throw new Error(TEMPLATE_VERSION_ERROR);
+  }
+
+  return version;
+}
+
+function formatReason(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return String(error);
+}
+```
+
+## 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` 直接失败，并提示把模板默认版本改成实际版本号再发布。
+- 版本号不满足极简 semver 形态 `x.y.z`：只输出 Rollup/Vite warning，仍会写入 manifest。
+
+`manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
+
 ## App-facing concepts
 
 ## 快速开始

package/skill/references/cli.md

@@ -37,6 +37,7 @@ The CLI, templates, and mock host are owned by `@heybox/hb-sdk`. Do not create a
 ```ts
 import { Command, CommanderError, InvalidArgumentError } from 'commander';
 import { runCreateCommand as defaultRunCreateCommand } from './commands/create';
+import { runDeployCommand as defaultRunDeployCommand } from './commands/deploy';
 import { runDevCommand as defaultRunDevCommand } from './commands/dev';
 import { runDoctorCommand as defaultRunDoctorCommand } from './commands/doctor';
 import {
@@ -54,6 +55,7 @@ export interface CliCommandHandlers {
   printLoginStatus: typeof defaultPrintLoginStatus;
   printUpdateReminder: typeof defaultPrintUpdateReminder;
   runCreateCommand: typeof defaultRunCreateCommand;
+  runDeployCommand: typeof defaultRunDeployCommand;
   runDevCommand: typeof defaultRunDevCommand;
   runDoctorCommand: typeof defaultRunDoctorCommand;
 }
@@ -90,6 +92,7 @@ export function createCliProgram(overrides: Partial<CliCommandHandlers> = {}) {
     printLoginStatus: defaultPrintLoginStatus,
     printUpdateReminder: defaultPrintUpdateReminder,
     runCreateCommand: defaultRunCreateCommand,
+    runDeployCommand: defaultRunDeployCommand,
     runDevCommand: defaultRunDevCommand,
     runDoctorCommand: defaultRunDoctorCommand,
     ...overrides,
@@ -126,6 +129,16 @@ export function createCliProgram(overrides: Partial<CliCommandHandlers> = {}) {
       }, handlers.printUpdateReminder),
     );
 
+  program
+    .command('deploy')
+    .description('构建并发布当前小程序到 Heybox 后台')
+    .option('--skip-build', '跳过 build，直接读 dist 目录上传并发布')
+    .action(
+      withUpdateReminder(async (options) => {
+        await handlers.runDeployCommand({ skipBuild: Boolean(options.skipBuild) });
+      }, handlers.printUpdateReminder),
+    );
+
   program
     .command('doctor')
     .description('诊断 hb-sdk 本地环境和 Agent Skill 版本')
@@ -298,7 +311,7 @@ Agent rules:
 
 ## 版本提醒
 
-`hb-sdk` CLI 会在命令成功执行后检查 npm registry 上 `@heybox/hb-sdk` 的 `latest` 版本。检查结果会缓存 24 小时；检查失败会静默跳过；`CI=true` 时会跳过检查，避免污染 CI 日志。本地可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用检查。
+`hb-sdk create`、`hb-sdk dev`、`hb-sdk login`、`hb-sdk login status`、`hb-sdk login clear` 会在命令成功执行后检查 npm registry 上 `@heybox/hb-sdk` 的 `latest` 版本。检查结果会缓存 24 小时；检查失败会静默跳过；`CI=true` 时会跳过检查，避免污染 CI 日志。`hb-sdk doctor` 不会附带版本提醒，避免把 skill 诊断输出和升级提示混在一起。本地可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用检查。
 
 ## Repository validation commands
 
@@ -308,10 +321,13 @@ Agent rules:
 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`。
+
 ## Generated template README
 
 ````md

package/skill/references/examples.md

@@ -96,6 +96,17 @@ hb-sdk login status
 hb-sdk login clear
 ```
 
+### Vite manifest plugin
+
+```ts
+import { miniappManifest } from '@heybox/hb-sdk/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [miniappManifest()],
+});
+```
+
 ## Negative examples
 
 - Do not import from internal hb-sdk implementation paths.
@@ -105,3 +116,4 @@ hb-sdk login clear
 - Do not pass raw internal share/network protocol fields from mini-program code.
 - Do not treat `hb-sdk login` as iframe SDK authentication state.
 - Do not create a second mock runtime package when `hb-sdk dev` is the supported local mock workflow.
+- Do not import `@heybox/hb-sdk/vite` from iframe business code or fetch a deployed `manifest.json` directly.