@heybox/hb-sdk 0.5.18 → 0.6.0

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.5.18",
+  "version": "0.6.0",
+  "sideEffects": [
+    "./src/index.ts",
+    "./src/core/singleton.ts",
+    "./dist/index.esm.js",
+    "./dist/index.cjs.js"
+  ],
   "description": "",
   "exports": {
     ".": {
@@ -44,7 +50,9 @@
   "keywords": [],
   "author": "",
   "license": "ISC",
-  "dependencies": {},
+  "dependencies": {
+    "parse5": "^7.3.0"
+  },
   "peerDependencies": {
     "vite": ">=5"
   },
@@ -83,7 +91,8 @@
     "typescript": "^5.9.3",
     "vue": "^2.7.16",
     "vite": "^8.0.12",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@heybox/hb-api": "~1.25.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -108,10 +117,13 @@
   },
   "scripts": {
     "dev": "vite",
-    "build:package": "nx exec -- sh -c \"pnpm run clean && pnpm run build:lib && pnpm run build:cli && pnpm run build:templates && pnpm run build:types\"",
+    "build:package": "nx exec -- sh -c \"pnpm run clean && pnpm run build:lib:bundle && pnpm run build:cli:bundle && pnpm run build:templates && pnpm run build:types\"",
     "build:watch": "pnpm run build:lib -w & pnpm run build:types -w",
-    "build:lib": "rollup -c rollup.config.ts  --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
-    "build:cli": "rollup -c rollup.config.ts --environment HB_SDK_BUILD:cli --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}' && pnpm run build:mock-host",
+    "build:hb-api-contract": "pnpm --dir ../hb-api run build:lib",
+    "build:lib": "pnpm run build:hb-api-contract && pnpm run build:lib:bundle",
+    "build:lib:bundle": "rollup -c rollup.config.ts  --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
+    "build:cli": "pnpm run build:hb-api-contract && pnpm run build:cli:bundle",
+    "build:cli:bundle": "rollup -c rollup.config.ts --environment HB_SDK_BUILD:cli --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}' && pnpm run build:mock-host",
     "build:mock-host": "node scripts/copy-mock-host.cjs",
     "build:templates": "node scripts/copy-cli-templates.cjs",
     "build:types": "tsc -p tsconfig.dts.json",
@@ -120,7 +132,7 @@
     "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:vite": "pnpm run build:hb-api-contract && vitest run --config vitest.vite.config.ts",
     "test:watch": "NODE_OPTIONS='--conditions=heybox' vitest",
     "changelog:draft": "node scripts/changelog-draft.cjs",
     "check:changelog": "node scripts/check-changelog.cjs",

package/skill/SKILL.md

@@ -44,7 +44,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 4. Handle `HbMiniProgramSDKError` for bridge/runtime/protocol failures.
 5. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
 6. Cancel lifecycle/event subscriptions returned by `on()` when the page or component unmounts.
-7. Call `destroy()` on independent instances created by `createMiniProgramSDK()` when they are no longer needed.
+7. Import the root package eagerly; version 0.6 exposes only the unique default SDK instance and starts its handshake as a required import side effect.
 
 ## Step 5: Use CLI workflows
 
@@ -54,28 +54,27 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 4. Use `hb-sdk remote entity list`, `hb-sdk remote entity current`, and `hb-sdk remote entity switch <entity-id>` to inspect or change the developer platform server-side current entity before remote management commands.
 5. Use `hb-sdk remote create` to create a remote mini-program under the server-side current entity and bind the returned id into `package.json.heybox.miniProgramId`; use `hb-sdk remote bind <mini-program-id>` to bind an existing remote mini-program after current-entity manageability is verified. Mini-program name, icon, and cover images belong in `package.json.heybox.miniProgramProfile` and are submitted with version audit.
 6. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for read/basic/preview management workflows. Mini-program name and image changes must go through version audit, so the CLI must not expose a basic-info update command.
-7. Use `hb-sdk remote deploy --release-note <text>` to build, upload, and submit the current project for audit. It reads `package.json.heybox.miniProgramId`, validates that the bound mini-program belongs to the server-side current entity before precheck/build/upload, prechecks `package.json.version` before build, runs the project's `build` script via the package manager auto-detected by lockfile, uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`), then calls the submit-audit API. The deploy upload pipeline rejects actual upload artifacts over 100MiB before any upload request, processes CDN upload metadata and callback confirmation at 50 files per batch, keeps 4-way upload concurrency within each batch, and validates CDN-returned keys exactly against the local expected upload keys.
-8. Use `hb-sdk remote deploy --skip-build --release-note <text>` only when the `dist/` directory is already prepared by an upstream CI stage. In this mode the CLI reads `dist/manifest.json.version` before precheck. Missing `dist/manifest.json` or `dist/index.html` aborts the run.
-9. Use `hb-sdk remote deploy --from-version <version> --release-note <text>` to reuse a previously uploaded remote version artifact and submit a new audit version without reading local `dist/`, building, or uploading. Do not combine `--from-version` with `--skip-build`.
-10. Always provide a concise release note before deploy. Non-interactive environments must pass `--release-note`; interactive terminals may prompt for it. The default is manual release after approval with `hb-sdk remote release <version>`; use `--auto-publish` when the audited version should automatically release after approval.
-11. Use `hb-sdk remote release <version>`, `hb-sdk remote withdraw <version>`, `hb-sdk remote take-down`, and `hb-sdk remote reopen` for dangerous remote changes. Interactive terminals should confirm after showing enough context; non-interactive environments must pass `--yes`.
-12. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk remote ... --api-base-url <url>` for remote platform APIs, and `HB_SDK_LOGIN_BASE_URL` or `hb-sdk login --login-base-url <url>` for browser login. CLI flags override env vars. API base URLs must be Heybox trusted HTTPS origins by default; use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging. Do not include path, query, or hash in these URLs.
-13. For development routing or gray validation, configure `packages/hb-sdk/src/cli/config.ts` with `@heybox/hb-types` `RylaiServiceTagConfig` (`default_tag` / path-specific `special_tag`) to attach `x-rylai-service-tag` and the matching `special_tag` query parameter to Heybox backend API requests.
-14. If a remote command targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; remote commands reject cached CLI login state from a different login origin.
-15. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
-16. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
-17. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
-18. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; the phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
-19. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
-20. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
-21. Treat `selectedEntity` in the CLI auth cache as a non-authoritative hint snapshot only. Every remote command must use the server-side current entity as the source of truth.
-22. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
-23. 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`.
-24. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
-25. 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.
-26. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
-27. Do not pass `mini_program_id` or `entity_id` as general CLI flags or environment variables; the mini-program id must come from `package.json.heybox.miniProgramId`, and the entity must come from the server-side current entity.
-28. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publish-pipeline helpers is `@heybox/hb-sdk/miniapp-publish`.
+7. Use `hb-sdk remote deploy --release-note <text>` to build, upload, and submit the current project for audit. It reads `package.json.heybox.miniProgramId`, validates that the bound mini-program belongs to the server-side current entity before precheck/build/upload, prechecks `package.json.version` before build, runs the project's `build` script via the package manager auto-detected by lockfile, uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`), then calls the submit-audit API. When `--env <name>` or `HB_SDK_ENV=<name>` selects an environment preset, deploy also passes the same name to the project build as its Vite mode. The deploy upload pipeline rejects actual upload artifacts over 100MiB before any upload request, processes CDN upload metadata and callback confirmation at 50 files per batch, keeps 4-way upload concurrency within each batch, and validates CDN-returned keys exactly against the local expected upload keys.
+8. Use `hb-sdk remote deploy --from-version <version> --release-note <text>` to reuse a previously uploaded remote version artifact and submit a new audit version without reading local `dist`, building, or uploading.
+9. Always provide a concise release note before deploy. Non-interactive environments must pass `--release-note`; interactive terminals may prompt for it. The default is manual release after approval with `hb-sdk remote release <version>`; use `--auto-publish` when the audited version should automatically release after approval.
+10. Use `hb-sdk remote release <version>`, `hb-sdk remote withdraw <version>`, `hb-sdk remote take-down`, and `hb-sdk remote reopen` for dangerous remote changes. Interactive terminals should confirm after showing enough context; non-interactive environments must pass `--yes`.
+11. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk remote ... --api-base-url <url>` for remote platform APIs, and `HB_SDK_LOGIN_BASE_URL` or `hb-sdk login --login-base-url <url>` for browser login. CLI flags override env vars. API base URLs must be Heybox trusted HTTPS origins by default; use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging. Do not include path, query, or hash in these URLs.
+12. For development routing or gray validation, use `HB_SDK_SERVICE_TAG` to attach `x-rylai-service-tag` and the matching `special_tag` query parameter to CLI backend requests and the Vite minimum-SDK-version gate. Repository-local path-specific routing can still be configured in `packages/hb-sdk/src/cli/config.ts` with `@heybox/hb-types` `RylaiServiceTagConfig` (`default_tag` / path-specific `special_tag`).
+13. If a remote command targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; remote commands reject cached CLI login state from a different login origin.
+14. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
+15. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
+16. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
+17. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; the phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
+18. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
+19. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
+20. Treat `selectedEntity` in the CLI auth cache as a non-authoritative hint snapshot only. Every remote command must use the server-side current entity as the source of truth.
+21. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
+22. 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`.
+23. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+24. 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.
+25. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
+26. Do not pass `mini_program_id` or `entity_id` as general CLI flags or environment variables; the mini-program id must come from `package.json.heybox.miniProgramId`, and the entity must come from the server-side current entity.
+27. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publish-pipeline helpers is `@heybox/hb-sdk/miniapp-publish`.
 
 ## Step 6: Preserve capability boundaries
 
@@ -93,6 +92,7 @@ For CLI and local development:
 1. Do not print, persist in templates, or pass through pkey, cookies, tokens, or private credentials.
 2. Do not use `hb-sdk login` as a workaround for iframe SDK authentication.
 3. Do not bypass `hb-sdk dev` by adding a second browser mock host.
+4. Keep the Vite `miniappManifest()` plugin enabled so builds only start in a compatible APP Runtime. Normal deploy always runs the project build.
 
 For host/runtime/protocol-maintenance code:
 

package/skill/references/api-protocol.md

@@ -25,7 +25,10 @@ export {
   MINI_PROGRAM_BRIDGE_NONCE_PARAM,
   MINI_PROGRAM_MESSAGE_NAMESPACE,
   MINI_PROGRAM_MESSAGE_VERSION,
+  RUNTIME_LOCATION_PROBE_METHOD,
+  SDK_CSP_VIOLATION_METHOD,
   SDK_HANDSHAKE_METHOD,
+  SDK_LOCATION_REPORT_METHOD,
 } from './protocol/constants';
 export { isMiniProgramBridgeMessage } from './protocol/guards';
 export type {
@@ -35,6 +38,12 @@ export type {
   MiniProgramEventHandler,
   MiniProgramEventName,
   MiniProgramEventPayloadMap,
+  RuntimeLocationProbePayload,
+  SDKCSPBlockedResourceType,
+  SDKCSPViolationPayload,
+  SDKHandshakePayload,
+  SDKLocationReportPayload,
+  SDKLocationReportTrigger,
 } from './protocol/types';
 export {
   AUTH_LOGIN_METHOD,
@@ -214,5 +223,5 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 3 | 4 | 67 | 57 | 4 |
-| Protocol API | 0 | 1 | 39 | 66 | 32 |
+| Root API | 2 | 3 | 66 | 57 | 4 |
+| Protocol API | 0 | 1 | 43 | 68 | 35 |

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.5.17`
+- Version at generation time: `0.6.0`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -27,9 +27,7 @@
 ## Public root entrypoint
 
 ```ts
-export { createMiniProgramSDK, MiniProgramSDK } from './core/sdk';
 export { HbMiniProgramSDKError, HbMiniProgramNetworkError } from './core/errors';
-export type { MiniProgramSDKOptions } from './core/client';
 export { ready, on, off, auth, user, share, viewport, storage, network, ui, device, navigation, cloud } from './core/singleton';
 export type {
   MiniProgramEventHandler,
@@ -199,24 +197,37 @@ export default hbSDK;
 Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe mini-program business code.
 
 ```ts
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { HB_SDK_VERSION } from '../core/version';
 import {
   renderMiniappManifest,
   validateMiniappPackageVersionForBuild,
 } from '../miniapp-manifest/schema';
 import { readMiniappVersionFromPackageJson } from '../miniapp-manifest/node';
+import { enforceMiniappHtmlPolicy } from './html-policy';
+import { enforceViteSdkVersion as defaultEnforceRemoteSdkVersion } from './sdk-version-gate';
+import { resolveHeyboxApiBaseUrl } from '../cli/auth/base-url';
 
 type MiniappManifestPlugin = {
   name: string;
-  apply: 'build';
   config: (config: MiniappManifestUserConfig) => MiniappManifestUserConfig | void;
   configResolved: (resolved: MiniappManifestResolvedConfig) => void;
-  writeBundle: (this: MiniappManifestPluginContext) => void;
+  buildStart: () => Promise<void>;
+  /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
+  buildEnd: (error?: Error) => void;
+  transformIndexHtml: (html: string) => string;
+  closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
 };
 
+export interface MiniappManifestOptions {
+  /** 仅供平台测试和自托管 Remote Environment adapter 使用。 */
+  enforceSdkVersion?: typeof defaultEnforceRemoteSdkVersion;
+}
+
 interface MiniappManifestUserConfig {
   base?: string;
+  define?: Record<string, string>;
 }
 
 interface MiniappManifestPluginContext {
@@ -225,36 +236,144 @@ interface MiniappManifestPluginContext {
 
 interface MiniappManifestResolvedConfig {
   root: string;
+  command: 'build' | 'serve';
   build: {
     outDir: string;
   };
+  server: {
+    host?: string | boolean;
+    port?: number;
+    hmr?: boolean | {
+      clientPort?: number;
+      host?: string;
+      port?: number;
+      protocol?: 'ws' | 'wss';
+    };
+  };
 }
 
-export function miniappManifest(): MiniappManifestPlugin {
+const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
+const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
+
+export function miniappManifest(options: MiniappManifestOptions = {}): MiniappManifestPlugin {
   let root = process.cwd();
   let outDir = 'dist';
+  let command: 'build' | 'serve' = 'build';
+  let hmrWebSocketUrl: string | undefined;
+  /** 构建链路中更早的失败原因；closeBundle 不得再用产物校验覆盖它。 */
+  let priorBuildError: Error | undefined;
 
   return {
     name: 'heybox-miniapp-manifest',
-    apply: 'build',
     config(config) {
-      if (config.base === undefined) {
-        return { base: './' };
-      }
+      assertMiniappViteBase(config.base);
+      return {
+        ...(config.base === undefined ? { base: './' } : {}),
+        define: {
+          [sdkVersionBuildConstant]: JSON.stringify(resolveSdkVersion()),
+        },
+      };
     },
     configResolved(resolved) {
       root = resolved.root;
       outDir = resolved.build.outDir;
+      command = resolved.command;
+      hmrWebSocketUrl = resolveHmrWebSocketUrl(resolved);
+    },
+    async buildStart() {
+      if (command !== 'build') return;
+      try {
+        await (options.enforceSdkVersion ?? defaultEnforceRemoteSdkVersion)({
+          sdkVersion: resolveSdkVersion(),
+          environment: resolveHeyboxApiBaseUrl({ env: process.env }),
+          serviceTag: process.env.HB_SDK_SERVICE_TAG,
+          allowPrerelease: true,
+        });
+      } catch (error) {
+        priorBuildError = toError(error);
+        throw priorBuildError;
+      }
     },
-    writeBundle() {
+    buildEnd(error) {
+      if (error) {
+        priorBuildError = priorBuildError ?? toError(error);
+      }
+    },
+    transformIndexHtml(html) {
+      return enforceMiniappHtmlPolicy(html, command === 'serve' ? { hmrWebSocketUrl } : undefined);
+    },
+    async closeBundle() {
+      // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
+      // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
+      if (priorBuildError) {
+        throw priorBuildError;
+      }
+
       const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
+      const sdkVersion = resolveSdkVersion();
+      const outputRoot = path.resolve(root, outDir);
+      const htmlFiles = collectHtmlFiles(outputRoot);
+      const unexpectedHtmlFiles = htmlFiles.filter(file => path.relative(outputRoot, file) !== 'index.html');
+      if (unexpectedHtmlFiles.length > 0) {
+        throw new Error(
+          `工坊小程序只支持单页应用，构建产物不允许额外 HTML：${unexpectedHtmlFiles
+            .map(file => path.relative(outputRoot, file).split(path.sep).join('/'))
+            .join(', ')}`,
+        );
+      }
+      const indexHtmlPath = path.join(outputRoot, 'index.html');
+      if (!htmlFiles.includes(indexHtmlPath)) {
+        throw new Error('构建产物必须包含入口 dist/index.html');
+      }
+      writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8')));
 
-      const manifestPath = path.resolve(root, outDir, 'manifest.json');
+      const manifestPath = path.join(outputRoot, 'manifest.json');
       mkdirSync(path.dirname(manifestPath), { recursive: true });
-      writeFileSync(manifestPath, renderMiniappManifest({ version }));
+      writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion }));
     },
   };
 }
+
+function assertMiniappViteBase(base: string | undefined) {
+  if (base !== undefined && base !== '' && base !== './') {
+    throw new Error(`工坊小程序 Vite base 仅支持空字符串或 "./"，当前值：${base}`);
+  }
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function collectHtmlFiles(root: string) {
+  const files: string[] = [];
+  if (!existsSync(root)) return files;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) files.push(...collectHtmlFiles(fullPath));
+    else if (entry.isFile() && path.extname(entry.name).toLowerCase() === '.html') files.push(fullPath);
+  }
+  return files;
+}
+
+function resolveSdkVersion() {
+  if (HB_SDK_VERSION !== sdkVersionPlaceholder) return HB_SDK_VERSION;
+  const packageJson = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as { version?: unknown };
+  if (typeof packageJson.version !== 'string' || !packageJson.version) {
+    throw new Error('未能读取 @heybox/hb-sdk 当前版本号');
+  }
+  return packageJson.version;
+}
+
+function resolveHmrWebSocketUrl(resolved: MiniappManifestResolvedConfig) {
+  const hmr = resolved.server.hmr;
+  if (hmr === false) return undefined;
+  const options = typeof hmr === 'object' ? hmr : {};
+  const protocol = options.protocol ?? 'ws';
+  const configuredHost = options.host ?? resolved.server.host;
+  const host = typeof configuredHost === 'string' && configuredHost !== '0.0.0.0' ? configuredHost : '127.0.0.1';
+  const port = options.clientPort ?? options.port ?? resolved.server.port;
+  return `${protocol}://${host}${port ? `:${port}` : ''}`;
+}
 ```
 
 ## Manifest
@@ -263,11 +382,12 @@ export function miniappManifest(): MiniappManifestPlugin {
 
 ```json
 {
-  "version": "1.2.3"
+  "version": "1.2.3",
+  "sdkVersion": "0.6.0"
 }
 ```
 
-`version` 来自小程序项目自身的 `package.json.version`。`hb-sdk create` 生成的模板默认已注册插件；现有 Vite 项目可以在 `vite.config.ts` 中手动接入：
+`version` 来自小程序项目自身的 `package.json.version`，`sdkVersion` 来自当前安装 SDK 的构建版本且不能由业务覆盖。`hb-sdk create` 生成的模板默认已注册插件；现有 Vite 项目可以在 `vite.config.ts` 中手动接入：
 
 ```ts
 import { miniappManifest } from '@heybox/hb-sdk/vite';
@@ -281,12 +401,18 @@ export default defineConfig({
 
 `base: './'` 用于让构建产物里的 JS/CSS/图片资源以 `./assets/...` 相对路径引用，避免小程序资源目录不是站点根路径时访问 `/assets/...` 失败。若没有显式配置 `base`，`miniappManifest()` 也会在 build 时默认补成 `./`。
 
+工坊小程序构建产物只能在兼容的小黑盒 Runtime 中启动。普通浏览器直接打开时不会执行标准业务脚本，并会提示在小黑盒 APP 内打开。项目应使用标准 Vite module 入口。
+
+插件只接受单页应用：输出目录只能存在入口 `index.html`。build 会用结构化 HTML parser 校验入口，并把平台 CSP 插入 `<head>` 首位；已有 CSP 会原样保留，两份策略按浏览器交集生效。正式策略禁止 `fetch`、XHR、WebSocket、EventSource、Beacon、Worker、iframe、表单和对象加载等浏览器原生出口；业务网络请求应使用 `network.request()`。dev 使用相同策略，只额外放行当前 Vite 的精确 HMR WebSocket 地址。
+
+meta refresh、外部 anchor、`dns-prefetch`、`preconnect`、`prerender`、外部资源 URL 和额外 HTML 会使 build 失败。内联 script/style 允许，但 `unsafe-eval` 不允许。`dev`、build 和 deploy 会读取 `/user_miniprogram/public/sdk_config` 的 `minimumSdkVersion`；最新请求失败时只回退当前 Remote Environment 下 24 小时内的有效缓存，无缓存则默认阻断并提示升级 `@heybox/hb-sdk@latest`。
+
 失败与警告语义：
 
 - 读取 `package.json` 失败或 JSON 解析失败：`vite build` 直接失败，并输出具体原因。
 - `package.json.version` 不是非空字符串：`vite build` 直接失败。
-- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 输出 warning 并写入 manifest；`hb-sdk remote deploy` 会拒绝发布，必须改成实际 `x.y.z` 版本。
-- 版本号不满足极简 semver 形态 `x.y.z`：只输出 Rollup/Vite warning，仍会写入 manifest。
+- `package.json.version` 仍是模板默认值 `0.0.0`：`vite build` 直接失败，必须改成实际 SemVer。
+- 版本号不是严格 SemVer、包含 build metadata 或缺少 `sdkVersion`：build/deploy 直接失败。
 
 `manifest.json` 不部署到 CDN，只交给发布流水线读取后上送后台；Host 通过后台 API 间接读取版本信息。第一阶段只支持 Vite 项目，非 Vite 打包器未来通过其他子入口扩展。
 
@@ -642,7 +768,7 @@ await network.request({
 
 ## 生命周期事件
 
-SDK 实例创建后会自动开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时，默认单例会被懒创建并自动开始握手；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
+导入 SDK 根包时会 eager 创建唯一默认实例并立即开始与父容器握手。使用 `on()` 监听父容器派发的小程序事件时不会创建第二个实例；`on()` 会返回取消监听函数，组件卸载或页面销毁时应及时调用。
 
 ```ts
 import { on } from '@heybox/hb-sdk';

package/skill/references/cli.md

@@ -56,7 +56,7 @@ hb-sdk remote allowlist list
 hb-sdk remote allowlist add <heybox-id...>
 hb-sdk remote allowlist remove <heybox-id...>
 hb-sdk remote allowlist set <heybox-id...>
-hb-sdk remote deploy --release-note <text> [--skip-build | --from-version <version>] [--auto-publish]
+hb-sdk remote deploy --release-note <text> [--from-version <version>] [--auto-publish]
 hb-sdk remote versions
 hb-sdk remote preview <version>
 hb-sdk remote release <version> [--yes]
@@ -131,7 +131,6 @@ Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "
 ```bash
 hb-sdk remote deploy --release-note "修复登录状态展示，补充异常提示"
 hb-sdk remote deploy --release-note "审核通过后自动发布" --auto-publish
-hb-sdk remote deploy --skip-build --release-note "复用已有 dist 构建产物"
 hb-sdk remote deploy --from-version 1.2.3 --release-note "复用 1.2.3 历史产物"
 hb-sdk remote deploy --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "测试环境验证"
 hb-sdk remote deploy --verbose --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "排查预检失败"
@@ -145,15 +144,14 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 3. 如果需要以公司的名义发布小程序，需先找 @秦浩东 申请小程序开发权限。
 4. 读取并校验 `--release-note`；TTY 环境缺失时会提示输入，CI / 非 TTY 环境缺失时直接失败。建议让 AI 生成 1-5 条简短发布日志。
 5. 普通 remote deploy 先读取 `package.json.version`，登录后、build 前调用版本预检接口；预检通过后才执行 `<pm> run build`。
-6. `--skip-build` 跳过构建，但会先读取已有 `dist/manifest.json.version`，再调用版本预检接口。
-7. `--from-version <version>` 跳过本地构建、`dist/` 读取和上传，复用指定历史版本产物提交审核；它与 `--skip-build` 互斥。
-8. 解析 `dist/manifest.json`，自动剥离 BOM，并校验 `version` 是合法 SemVer：允许 prerelease，例如 `1.2.3-rc.1`；拒绝 build metadata，例如 `1.2.3+build.1`；拒绝 `0.0.0`。
-9. 普通 remote deploy 的 `dist/manifest.json.version` 必须与预检使用的 `package.json.version` 一致，否则失败且不上传。
-10. 遍历 `dist/` 文件，过滤掉 `manifest.json`、`.DS_Store`、`*.map`；遇到 symbolic link 或 `node_modules` 路径直接报错。
-11. 校验上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
-12. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 CDN。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
-13. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
-14. 全部上传成功后调用提交审核接口；`--from-version` 路径会直接提交 `source_version`。CLI 输出提交审核成功、发布策略和可用的 preview URL。
+6. `--from-version <version>` 跳过本地构建、`dist/` 读取和上传，复用指定历史版本产物提交审核。
+7. 解析 `dist/manifest.json`，自动剥离 BOM，并校验 `version` 是合法 SemVer：允许 prerelease，例如 `1.2.3-rc.1`；拒绝 build metadata，例如 `1.2.3+build.1`；拒绝 `0.0.0`。
+8. 普通 remote deploy 的 `dist/manifest.json.version` 必须与预检使用的 `package.json.version` 一致，否则失败且不上传。
+9. 遍历 `dist/` 文件，过滤掉 `manifest.json`、`.DS_Store`、`*.map`；遇到 symbolic link 或 `node_modules` 路径直接报错。
+10. 校验上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
+11. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 CDN。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
+12. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
+13. 全部上传成功后调用提交审核接口；`--from-version` 路径会直接提交 `source_version`。CLI 输出提交审核成功、发布策略和可用的 preview URL。
 
 `mini_program_id` 没有 CLI flag，必须落在 `package.json` 里：
 
@@ -165,15 +163,15 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 }
 ```
 
-`manifest.json` 仅作为提交审核接口的 `manifest` 字段提交，不会上传到 CDN。Vite 项目通过 `miniappManifest()` 插件生成；CLI 不会自动注入插件，请在 `vite.config.ts` 中显式挂载。小程序构建产物需要使用相对资源路径；`hb-sdk create` 模板会显式配置 `base: './'`，未配置 `base` 的项目也会由 `miniappManifest()` 在 build 时默认补成 `./`。
+`manifest.json` 仅作为提交审核接口的 `manifest` 字段提交，不会上传到 CDN。Vite 项目通过 `miniappManifest()` 插件生成；CLI 不会自动注入插件，请在 `vite.config.ts` 中显式挂载。小程序构建产物需要使用相对资源路径；`hb-sdk create` 模板会显式配置 `base: './'`，未配置 `base` 的项目也会由 `miniappManifest()` 在 build 时默认补成 `./`。构建产物只能在兼容的小黑盒 Runtime 中启动，普通浏览器直接打开时不会执行标准业务脚本。
 
 默认发布策略是 `auto_publish=false`：运营审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布。需要审核通过后自动发布并下架旧线上版本时，使用 `--auto-publish`。如需让指定用户预览未发布候选版本，使用 `hb-sdk remote allowlist add <heybox_id>` 管理预览白名单。
 
-内部测试或预发环境可通过 `HB_SDK_API_BASE_URL` / `HB_SDK_LOGIN_BASE_URL` 设置默认后台环境，也可以用 `--api-base-url` / `--login-base-url` 覆盖单次命令。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。`apiBaseUrl` 影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`loginBaseUrl` 用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。开发环境如需给后台请求带 `x-rylai-service-tag` 和 `special_tag`，优先用 `--service-tag <tag>` 或 `HB_SDK_SERVICE_TAG`；path-prefix 级 `special_tag` 仍可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。
+内部测试或预发环境可通过 `HB_SDK_API_BASE_URL` / `HB_SDK_LOGIN_BASE_URL` 设置默认后台环境，也可以用 `--api-base-url` / `--login-base-url` 覆盖单次命令。自定义地址只接受 origin，不允许包含 path、query 或 hash；API origin 默认还必须是 Heybox 受信 HTTPS 域名，只有本地联调等场景可显式使用 `--allow-unsafe-api-base-url` 或 `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` 放开。`apiBaseUrl` 影响 `hb-sdk remote` 里的远端平台后台 API，包括预检、CDN 上传凭证/回调、提交审核、版本、发布、撤回、下架、重新上架、详情和白名单等调用；`loginBaseUrl` 用于 `hb-sdk login` 的登录入口，以及 remote 命令前校验当前 CLI 登录态是否属于同一个登录环境。开发环境如需给后台请求带 `x-rylai-service-tag` 和 `special_tag`，优先用 `--service-tag <tag>` 或 `HB_SDK_SERVICE_TAG`；deploy 子构建会继承 `.env.<name>` 中的 `HB_SDK_SERVICE_TAG`，Vite 最低 SDK 版本门禁请求也会同时携带该 header 和 query。path-prefix 级 `special_tag` 仍可在 `packages/hb-sdk/src/cli/config.ts` 里按 `@heybox/hb-types` 的 `RylaiServiceTagConfig` 配置。日志只输出 origin，不输出带身份和签名参数的完整请求 URL。
 
 `hb-sdk doctor`、npm latest 检查、mock host 的 `network.request()` 不受这些配置影响。
 
-切换测试环境时往往需要同时配置后台 host、登录 host 和 service tag。CLI 支持加载 `.env.<name>` 预设，把其中的 `HB_SDK_*` 变量一次性注入当前进程（不覆盖已有值）：`--env <name>` 读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级更高，也可用 `HB_SDK_ENV=<name>` 触发。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。
+切换测试环境时往往需要同时配置后台 host、登录 host 和 service tag。CLI 支持加载 `.env.<name>` 预设，把其中的 `HB_SDK_*` 变量一次性注入当前进程（不覆盖已有值）：`--env <name>` 读取项目根下的 `.env.<name>`，`--env-file <path>` 显式指定路径且优先级更高，也可用 `HB_SDK_ENV=<name>` 触发。使用 `--env <name>` 或 `HB_SDK_ENV=<name>` 执行 `remote deploy` 时，CLI 还会把同一个 `name` 作为 `--mode <name>` 传给项目 build，使 CLI 后端环境与 Vite mode 保持一致。文件仅支持 `KEY=VALUE`、空行和 `#` 注释，不做变量插值；文件不存在时静默跳过。
 
 ```bash
 # 项目根准备 .env.test
@@ -195,7 +193,7 @@ Before precheck, build, upload, or submit audit, `hb-sdk remote deploy` must ver
 Agent rules:
 
 - Use `hb-sdk remote deploy --release-note <text>` for normal build, upload, and submit-audit flows.
-- Use `hb-sdk remote deploy --from-version <version> --release-note <text>` to reuse a remote history artifact. Do not combine `--from-version` with `--skip-build`.
+- Use `hb-sdk remote deploy --from-version <version> --release-note <text>` to reuse a remote history artifact.
 - Verify remote deploy guidance says current-entity mismatch fails before precheck/build/upload/submit and never auto-switches the developer entity.
 - Never recommend top-level `hb-sdk deploy`; it has been removed rather than retained as a compatibility alias.
 - After non-auto deploy succeeds, suggest `hb-sdk remote versions` and then `hb-sdk remote release <version>` after approval. Do not send the user to Open for manual publish when the CLI command exists.

package/skill/references/recipes.md

@@ -76,7 +76,7 @@ stopAuthChange()
 
 默认单例适合一个页面只有一个 SDK 上下文的情况。大多数小程序页面都应该使用默认单例，因为它可以避免重复握手和重复维护事件监听。
 
-需要控制 `timeout`、注入测试 window 或隔离多个上下文时，再使用 [独立实例](#custom-instance-recipe)。
+0.6 起根入口只提供唯一默认实例并在导入时立即握手，不再允许业务创建独立实例。测试需要隔离 bridge 时应在应用边界替换公开模块。
 
 ## User and login
 
@@ -260,15 +260,7 @@ function reportSDKError(code: string, message: string, data?: unknown) {
 
 ## 超时时间
 
-默认超时时间是 10000ms。需要调整时，使用独立实例：
-
-```ts
-import { createMiniProgramSDK } from '@heybox/hb-sdk'
-
-const sdk = createMiniProgramSDK({
-  timeout: 15000,
-})
-```
+默认握手超时时间是 10000ms。0.6 起业务不能通过独立实例修改该值；超时应作为 Host/Runtime 启动异常处理。
 
 ## Login gate recipe
 
@@ -325,50 +317,26 @@ async function handleSubmit() {
 ## Custom instance recipe
 
 
-# 独立 SDK 实例
+# 默认 SDK 单例
 
-大多数业务页使用默认单例即可。只有在需要隔离上下文时，再创建独立实例。
+0.6 起 SDK 根入口会 eager 创建唯一默认实例并立即握手，不再公开独立实例工厂。
 
-## 自定义 timeout
+## 业务接入
 
 ```ts
-import { createMiniProgramSDK } from '@heybox/hb-sdk'
-
-const sdk = createMiniProgramSDK({
-  timeout: 15000,
-})
+import hbSDK from '@heybox/hb-sdk'
 
-await sdk.ready()
+await hbSDK.ready()
 ```
 
 ## 测试环境注入 window
 
-单元测试可以注入 `selfWindow`、`targetWindow` 和 `nonce`，避免依赖真实 iframe。
-
-```ts
-import { createMiniProgramSDK } from '@heybox/hb-sdk'
-
-const sdk = createMiniProgramSDK({
-  nonce: 'test_nonce',
-  selfWindow: window,
-  targetWindow: null,
-})
-
-sdk.destroy()
-```
-
-## 清理实例
-
-独立实例不再使用时调用 `destroy`。
+测试需要替换 bridge 或 window 时，应在应用测试边界 mock `@heybox/hb-sdk` 公开模块，不要从业务代码访问内部构造器。
 
 ```ts
-const sdk = createMiniProgramSDK()
-
-try {
-  await sdk.ready()
-} finally {
-  sdk.destroy()
-}
+vi.mock('@heybox/hb-sdk', () => ({
+  default: { ready: vi.fn(async () => undefined) },
+}))
 ```
 
-`destroy` 会移除 message 监听，并拒绝尚未完成的请求。销毁后不要继续复用该实例。
+默认实例由页面生命周期管理，业务不调用 `destroy()`。

package/skill/references/safety-boundaries.md

@@ -10,14 +10,13 @@
 
 ## 能力边界
 
-- SDK 实例创建后会自动开始握手；默认单例仍按需懒创建，`ready()`、`on()` 或任意模块能力调用都会创建默认单例并开始握手。
+- 导入 SDK 根包时会 eager 创建唯一默认实例并立即开始握手；`ready()` 只等待这次握手结果。
 - `ready()` 只等待已有握手结果，不主动触发新的握手；调用模块能力前会自动等待 `ready()`，但业务仍建议在页面启动阶段显式 `await ready()`，便于集中处理握手失败。
 - `user.getInfo()`、`user.getCurrentUserDetail()`、`user.getCurrentUserProfile()`、`user.getPlatformAccountOverview()`、`user.getPlatformAccountInfo(platform)` 和 `user.getSteamGameList(options)` 不会触发登录；登录必须由业务在用户操作后调用 `auth.login()`。
 - 当前用户详情和平台账号 API 只允许读取当前登录用户，不支持传入 `userid` 查询其他人，也不透传 `/account/home_v2/` 原始响应。
 - 分享、截图、UI、设备、导航、storage 和网络请求只开放稳定窄接口，不透传黑盒客户端内部协议参数。
 - `network.request()` 的 `validateStatus` 只在 SDK 本地执行，不会被序列化给父容器。
 - `on()` 返回取消监听函数；组件卸载或页面销毁时应主动取消监听。
-- 使用 `createMiniProgramSDK()` 创建独立实例后，不再需要时应调用 `destroy()`。
 - 构建产物可以包含 `dist/manifest.json`，业务代码不应自行 fetch 已部署的 manifest；这个文件由发布流水线读取并上送后台。
 
 ## Agent rules