@heybox/hb-sdk 0.8.1-alpha.3 → 0.8.1-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.1-alpha.3",
+  "version": "0.8.1-alpha.7",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -62,7 +62,7 @@
     "skills": "1.5.23",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.8.1-alpha.3"
+    "@heybox/hb-sdk-protocol": "0.8.1-alpha.7"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -113,13 +113,13 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
+    "@heybox/hb-api": "~1.28.3",
     "@heybox-domain/heybox-theme": "~0.1.0",
+    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.7",
+    "@heybox/runtime-policy": "~0.2.0",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.3",
-    "@heybox/hb-api": "~1.28.2",
-    "@heybox/runtime": "~0.2.0",
     "@heybox/runtime-transport-fetch": "~0.2.0",
-    "@heybox/runtime-policy": "~0.2.0"
+    "@heybox/runtime": "~0.2.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -175,7 +175,7 @@
     "test:types:characterization": "tsc -p tsconfig.characterization.json --noEmit --pretty false",
     "test:types:browser-dev-host": "vue-tsc -p tsconfig.browser-dev-host.json --noEmit --pretty false",
     "test:types": "pnpm run test:types:characterization && pnpm run test:types:browser-dev-host",
-    "test:e2e:browser-dev-host": "pnpm run build:browser-dev-host && NODE_OPTIONS='--conditions=heybox' vitest run --config vitest.browser-dev-host-e2e.config.ts",
+    "test:e2e:browser-dev-host": "pnpm run build:lib && pnpm run build:cli:bundle && NODE_OPTIONS='--conditions=heybox' vitest run --config vitest.browser-dev-host-e2e.config.ts",
     "test:create-template:artifact": "node scripts/test-create-template-artifact.mjs",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",
     "test:vite": "pnpm run build:hb-sdk-protocol && pnpm run build:hb-api-contract && vitest run --config vitest.vite.config.ts",

package/skill/SKILL.md

@@ -21,6 +21,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 1. For root SDK imports, singleton usage, modules, and errors, read `references/api-root.md`.
 2. For host/runtime protocol contracts only, read `references/api-protocol.md`. Do not use this reference for mini-program business code.
 3. For common business flows, read `references/recipes.md`.
+   For managed desktop programs, read the `Managed Companion` section and preserve its trust boundaries.
 4. For CLI commands, production builds, local debugging, device debugging, CLI login, 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 Vite build manifest behavior, read `references/api-root.md` and `references/safety-boundaries.md`.
@@ -52,14 +53,16 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 12. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the mini-program share link. `share.showShareMenu()` always uses the platform `common_share` landing page and does not accept a custom `url`. Read the JSON-compatible page state synchronously with `share.getExtra()` after launch, validate the developer-defined fields, and fall back to the default page when it returns `undefined`.
 13. New PC enables the retained `files` and `network.download()` contract with persistent sandbox storage, single-file/directory pickers, exact File saving, and public-network streaming downloads. Mobile, Web, Browser Dev Host, and legacy PC return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Call `files.pickFiles()` / `pickDirectory()` / `saveFile()` only from trusted user actions; `saveFile()` accepts only `suggestedName`, `remove()` only deletes sandbox objects, and non-empty directories require `remove({ recursive: true })`.
 14. Use `network.download()` only with an SDK-created File/Directory target. It is GET-only, does not follow redirects, and exposes local `AbortSignal` / progress callbacks without sending functions over the bridge. Abort is a cancellation intent; a Host commit that already won still resolves successfully.
-15. Use `environment.getInfo()` for the immutable runtime, Host App, canonical Mini-program, operating-system, and SDK version snapshot. It waits for the handshake automatically. Use `environment.getInfoSync()` only after `getHandshakeState().status === 'ready'` or inside a ready-state subscription; before that it throws `ENVIRONMENT_NOT_READY`.
-16. Treat missing environment strings as `null` and unknown enum values as `unknown`. Only `sdk.version` is SemVer; do not compare the other opaque version strings or use any environment field for authentication, authorization, or risk control.
+15. Use `companion.prepare()` and `companion.launch()` only from separate trusted user actions. Launch does not prepare implicitly. Treat stdio as raw `Uint8Array` with at-least-once output delivery, and implement business framing and sequence de-duplication explicitly.
+16. Use `environment.getInfo()` for the immutable runtime, Host App, canonical Mini-program, operating-system, and SDK version snapshot. It waits for the handshake automatically. Use `environment.getInfoSync()` only after `getHandshakeState().status === 'ready'` or inside a ready-state subscription; before that it throws `ENVIRONMENT_NOT_READY`.
+17. Treat missing environment strings as `null` and unknown enum values as `unknown`. Only `sdk.version` is SemVer; do not compare the other opaque version strings or use any environment field for authentication, authorization, or risk control.
 
 ## Step 5: Use CLI workflows
 
 1. Use `hb-sdk create <project-name>` to scaffold a workshop mini-program.
 2. Use `hb-sdk dev` for Browser Mock and Mobile App debugging. Browser debugging can start without CLI login, project binding, or a remote Dev Context; capabilities that need those inputs fail explicitly. Mobile uses the single QR entry with the `open_inapp` and `heybox://` `openWindow` wrapper around a LAN short URL, then opens `heybox-mini-dev://sandbox` with the complete launch context.
 3. The debugging page does not edit permissions. Treat the validated remote permission snapshot as canonical Runtime input. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
+   For real PC Companion debugging, configure local artifacts in `package.json#heybox.companions`, keep `miniappManifest()` enabled, bind the project, and ensure COA has approved `companion`. `hb-sdk dev` validates immutable snapshots without requiring an upload; config or artifact changes rotate the snapshot while existing Sessions retain their original artifact. Prepare and launch the new artifact explicitly. Check separate Browser, Mobile and PC Companion readiness in the debugging workbench. Without a local declaration, use Browser Fake only for state/UI integration.
 4. Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry. It directly owns the Vite build, always cleans and writes `dist/`, and works without CLI login, project binding, or network access.
 5. Declare the actual supported platforms in `package.json#heybox.platforms` and keep the no-argument `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the declaration, Manifest, or Runtime gate output is missing or inconsistent.
 6. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
@@ -90,7 +93,8 @@ For workshop mini-program business code:
 7. Do not use `network.request()` to reach platform-reserved runtime auth or OpenAPI internal paths.
 8. Do not expose credentials or describe internal Host authorization state machines and routes in app-facing guidance.
 9. Do not invent string paths, File System Access API handles, Blob downloads, uploads, Range/resume, external deletion, move, append, or persistent external grants. Public file operations use only SDK-created handles; deletion is limited to SDK sandbox handles.
-10. Do not treat `environment.*` as a device-fingerprint or trusted backend signal. It intentionally excludes account data, device identifiers, model, UA, CPU, and memory; use `viewport.getWindowInfo()` for screen geometry.
+10. Do not pass executable paths, dynamic args, cwd, environment variables, shell commands, URLs, hashes, PID, or native handles through `companion`; reviewed Manifest declarations are the only launch source.
+11. Do not treat `environment.*` as a device-fingerprint or trusted backend signal. It intentionally excludes account data, device identifiers, model, UA, CPU, and memory; use `viewport.getWindowInfo()` for screen geometry.
 
 For CLI and local development:
 
@@ -101,6 +105,7 @@ For CLI and local development:
 5. Do not suggest changing or resetting permissions in the `hb-sdk dev` debugging page; that UI does not exist. Diagnose permission behavior from the remote snapshot and capability result.
 6. Treat browser Mock results as development feedback only. Validate permissions, identity flows, and user interactions again in a real Heybox client before publishing.
 7. The Browser Dev Host offers iPhone 16 Pro Max (`440 x 956`) and Pixel 9 Pro (`410 x 914`) presets. Switching a preset must preserve the iframe, Runtime session, and page state. Authorization/action dialogs, Toast, Loading, and vibration feedback render inside the preview. Use the upper-right QR popover as the only Mobile QR entry.
+8. Companion Fake scenarios do not execute a local program and are not Windows/macOS release evidence. V1 only supports normal-privilege launch and rejects `elevation: 'required'` at build time. Require target-platform new PC validation for archive integrity, stdio, exit, and process-tree cleanup.
 
 For host/runtime/protocol-maintenance code:
 

package/skill/references/api-protocol.md

@@ -299,12 +299,12 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 4 | 67 | 62 | 2 |
+| Root API | 2 | 4 | 75 | 73 | 3 |
 | Protocol API | 0 | 13 | 58 | 90 | 47 |
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
-| Vite API | 0 | 1 | 4 | 1 | 1 |
+| Vite API | 0 | 1 | 5 | 1 | 2 |
 
-<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=a8018ebd23e4d885efbe08f622a6cf4780dd152d5f90cc4a78d2eb7e15eca2e2 -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=a80eea1bb8b0d64255afcb4a664911f025aeae33f3f766c9b126f55668400178 -->
 
 ## SDK API
 

package/skill/references/api-root.md

@@ -12,6 +12,7 @@
 - apps/docs/hb-sdk/guide/environment.md
 - apps/docs/hb-sdk/guide/error-handling.md
 - apps/docs/hb-sdk/guide/lifecycle.md
+- apps/docs/hb-sdk/guide/companion.md
 - apps/docs/hb-sdk/guide/cli.md
 
 ## Contents
@@ -26,7 +27,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.1-alpha.3`
+- Version at generation time: `0.8.1-alpha.7`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -52,10 +53,32 @@ export {
   environment,
   navigation,
   cloud,
+  companion,
 } from './core/singleton';
 export type { MiniProgramSDKHandshakeState, MiniProgramSDKHandshakeStateHandler } from './core/handshake-state';
 export type { MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap } from './protocol/types';
 export type { LoginOptions, LoginPayload, LoginResult, LoginScope, MiniProgramAuthModule } from './modules/auth';
+export type {
+  CompanionAttachments,
+  CompanionCapability,
+  CompanionExit,
+  CompanionExitHandler,
+  CompanionInfo,
+  CompanionNotification,
+  CompanionNotificationCategory,
+  CompanionNotifications,
+  CompanionOutputHandler,
+  CompanionOwnershipLostHandler,
+  CompanionPreparationStatus,
+  CompanionPrepareOptions,
+  CompanionPrepareProgress,
+  CompanionSession,
+  CompanionStdio,
+  CompanionState,
+  CompanionStateChangeHandler,
+  CompanionTarget,
+  MiniProgramCompanionModule,
+} from './modules/companion';
 export type {
   DeleteCurrentUserLeaderboardEntryPayload,
   DeleteCurrentUserLeaderboardEntryResult,
@@ -197,6 +220,7 @@ export type {
 import {
   auth,
   cloud,
+  companion,
   device,
   environment,
   getHandshakeState,
@@ -230,6 +254,7 @@ const hbSDK = {
   environment,
   navigation,
   cloud,
+  companion,
 };
 
 export default hbSDK;
@@ -240,226 +265,59 @@ 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 { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import { HB_SDK_VERSION } from '../core/version';
-import { MINI_DEV_CONSOLE_EVENT_TYPE, MINI_DEV_IFRAME_WINDOW_NAME, MINI_DEV_CONSOLE_INSTALL_FLAG } from '../core/mini-dev-console';
-import {
-  MINIAPP_PLATFORM_VALUES,
-  renderMiniappManifest,
-  validateMiniappPackageVersionForBuild,
-  type MiniappPlatform,
-} from '../miniapp-manifest/schema';
-import {
-  readMiniappPermissionsFromPackageJson,
-  readMiniappPlatformsFromPackageJson,
-  readMiniappVersionFromPackageJson,
-} from '../miniapp-manifest/node';
-import { getMissingPermissionsWarning } from '../miniapp-manifest/permissions';
-import { enforceMiniappHtmlPolicy } from './html-policy';
-import { shouldSkipMiniappPlatformCspFromEnv } from './runtime-permission-env';
-
 export interface MiniappManifestPlugin {
-  name: string;
-  config: (config: MiniappManifestUserConfig, env?: { command: 'build' | 'serve' }) => MiniappManifestUserConfig | void;
-  configResolved: (resolved: MiniappManifestResolvedConfig) => void;
-  /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
-  buildEnd: (error?: Error) => void;
-  transformIndexHtml: (html: string) => string;
-  closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
+    name: string;
+    config: (config: MiniappManifestUserConfig, env?: {
+        command: 'build' | 'serve';
+    }) => MiniappManifestUserConfig | void;
+    configResolved: (resolved: MiniappManifestResolvedConfig) => void;
+    configureServer: (server: MiniappManifestDevServer) => void;
+    /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
+    buildEnd: (error?: Error) => void;
+    transformIndexHtml: (html: string) => string;
+    closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
+}
+
+export interface MiniappManifestDevServer {
+    httpServer?: Server | null;
+    restart?: (forceOptimize?: boolean) => Promise<void>;
+    middlewares: {
+        use: (handler: (request: IncomingMessage, response: ServerResponse, next: () => void) => void) => void;
+    };
 }
 
 export interface MiniappManifestUserConfig {
-  base?: string;
-  define?: Record<string, string>;
+    base?: string;
+    define?: Record<string, string>;
 }
 
 export interface MiniappManifestPluginContext {
-  warn: (message: string) => void;
+    warn: (message: string) => void;
 }
 
 export interface MiniappManifestResolvedConfig {
-  root: string;
-  command: 'build' | 'serve';
-  build: {
-    outDir: string;
-  };
-  server: {
-    host?: string | boolean;
-    https?: boolean | Record<string, unknown>;
-    port?: number;
-    hmr?:
-      | boolean
-      | {
-          clientPort?: number;
-          host?: string;
-          port?: number;
-          protocol?: 'ws' | 'wss';
+    root: string;
+    command: 'build' | 'serve';
+    build: {
+        outDir: string;
+    };
+    server: {
+        host?: string | boolean;
+        https?: boolean | Record<string, unknown>;
+        port?: number;
+        hmr?: boolean | {
+            clientPort?: number;
+            host?: string;
+            port?: number;
+            protocol?: 'ws' | 'wss';
         };
-  };
-  plugins?: readonly { name?: string }[];
+    };
+    plugins?: readonly {
+        name?: string;
+    }[];
 }
 
-export { MINIAPP_PLATFORM_VALUES };
-export type { MiniappPlatform };
-
-/**
- * dev serve 时在入口 HTML 最早位置注入无依赖 console 捕获 bootstrap。
- *
- * 必须内联完整 patch 逻辑而非等 SDK 模块加载：vite client、业务代码的 console 调用
- * 都可能早于 SDK 单例初始化（如 [vite] connecting）。捕获条件：
- * 1. 构建期只有 vite serve 走到本分支（生产构建无此代码，双保险之 define 常量仍注入给 SDK 侧）；
- * 2. 运行期仅调试 iframe（window.name 标记由调试台 iframe.name 与本 bootstrap 设置）激活。
- * 转发经 window.parent.postMessage（CSP connect-src 不约束 postMessage），失败静默，
- * 严禁回打 console 造成自触发循环。SDK 侧 installMiniDevConsoleForwarding 安装时
- * 检测同款 INSTALL_FLAG，不会重复 patch。
- */
-function injectMiniDevConsoleBootstrap(html: string): string {
-  const bootstrap = `<script>(function(){var LEVELS=['log','debug','info','warn','error'];var FLAG='${MINI_DEV_CONSOLE_INSTALL_FLAG}';var TYPE='${MINI_DEV_CONSOLE_EVENT_TYPE}';if(window.name!=='${MINI_DEV_IFRAME_WINDOW_NAME}')window.name='${MINI_DEV_IFRAME_WINDOW_NAME}';if(window[FLAG])return;var patched=false;for(var i=0;i<LEVELS.length;i++)(function(level){var original=console[level];if(typeof original!=='function')return;console[level]=function(){try{parent.postMessage({type:TYPE,detail:{level:level,args:Array.prototype.slice.call(arguments),timestamp:Date.now()}},'*')}catch(e){}return original.apply(this,arguments)};patched=true})(LEVELS[i]);if(patched)window[FLAG]=true})();</script>`;
-  const headIndex = html.indexOf('<head>');
-  if (headIndex < 0) {
-    return html;
-  }
-  const insertAt = headIndex + '<head>'.length;
-  return `${html.slice(0, insertAt)}${bootstrap}${html.slice(insertAt)}`;
-}
-
-const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
-const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
-const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
-
-export function miniappManifest(): MiniappManifestPlugin {
-  const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
-  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',
-    config(config, env) {
-      assertMiniappViteBase(config.base);
-      // command 在本钩子时序早于 configResolved，必须取自 env 命令而非闭包；
-      // 旧调用方（测试等）未传 env 时按 build 处理。
-      const isServe = env?.command === 'serve';
-      return {
-        ...(config.base === undefined ? { base: './' } : {}),
-        define: {
-          [sdkVersionBuildConstant]: JSON.stringify(resolveSdkVersion()),
-          // 仅 vite serve（hb-sdk dev）注入；vite build / hb-sdk build 永不注入，捕获模块被死代码消除。
-          ...(isServe ? { [miniDevLoggingConstant]: 'true' } : {}),
-        },
-      };
-    },
-    configResolved(resolved) {
-      if (resolved.plugins) {
-        const manifestPluginCount = resolved.plugins.filter((plugin) => plugin.name === 'heybox-miniapp-manifest').length;
-        if (manifestPluginCount !== 1) {
-          throw new Error(`Vite 配置必须且只能包含一个 miniappManifest() 插件，当前数量：${manifestPluginCount}`);
-        }
-      }
-      root = resolved.root;
-      outDir = resolved.build.outDir;
-      command = resolved.command;
-      hmrWebSocketUrl = resolveHmrWebSocketUrl(resolved);
-    },
-    buildEnd(error) {
-      if (error) {
-        priorBuildError = priorBuildError ?? toError(error);
-      }
-    },
-    transformIndexHtml(html) {
-      const enforced = enforceMiniappHtmlPolicy(html, {
-        ...(command === 'serve' ? { hmrWebSocketUrl } : {}),
-        skipPlatformCsp,
-      });
-      return command === 'serve' ? injectMiniDevConsoleBootstrap(enforced) : enforced;
-    },
-    async closeBundle() {
-      // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
-      // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
-      if (priorBuildError) {
-        throw priorBuildError;
-      }
-
-      const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
-      const sdkVersion = resolveSdkVersion();
-      const platforms = readMiniappPlatformsFromPackageJson(root);
-      const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
-      if (!parsedPermissions.declared) this.warn(getMissingPermissionsWarning());
-      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'), { skipPlatformCsp }));
-
-      const manifestPath = path.join(outputRoot, 'manifest.json');
-      mkdirSync(path.dirname(manifestPath), { recursive: true });
-      writeFileSync(
-        manifestPath,
-        renderMiniappManifest({
-          version,
-          sdkVersion,
-          platforms,
-          ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
-        }),
-      );
-    },
-  };
-}
-
-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 ?? (resolved.server.https ? 'wss' : '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}` : ''}`;
-}
+export declare function miniappManifest(): MiniappManifestPlugin;
 ```
 
 ## 生产构建
@@ -789,6 +647,10 @@ try {
 - `ENVIRONMENT_NOT_READY` 表示在 SDK 完成握手前调用了 `environment.getInfoSync()`；一般改用会自动等待的 `environment.getInfo()`。
 - `FILE_PICKER_CANCELLED` 表示用户取消了外部文件或目录选择，应正常结束当前操作。
 - `DOWNLOAD_CANCELLED` 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。`DOWNLOAD_TIMEOUT` 表示网络空闲超时，失败不会改动原目标。
+- `COMPANION_NOT_PREPARED` 表示启动前尚未显式准备；应由新的用户操作调用 `companion.prepare()`，不要在 `launch()` 中自动重试。
+- `COMPANION_SESSION_OWNERSHIP_LOST` 表示 Session controller 已由新的 Runtime generation 接管；停止旧 controller 写入，需要继续取得控制权时重新取得活动 Session。
+- `COMPANION_DESCRIPTOR_UNAVAILABLE` 表示授权或描述符暂时不可用，Runtime 会保留 `retryable: true`。
+- `COMPANION_INTEGRITY_FAILED`、`COMPANION_ARCHIVE_INVALID` 或操作系统拦截都不能绕过；停止重试并修正归档后提交新审核版本。
 - `DOWNLOAD_HTTP_STATUS` 的 `data` 只包含脱敏后的 `status`、可选 `statusText` 和安全响应头。
 - 超时或运行环境不可用时，允许用户重试或退出当前流程。
 - 上报 `code`、`message` 和必要的业务上下文，不要上报用户凭据或敏感数据。
@@ -842,6 +704,8 @@ function reportSDKError(errorCode: string, message: string, data?: unknown) {
 picker 取消、授权撤销、文件缺失、quota、下载状态或取消，不依赖 `message` 文案，也不要记录
 真实路径、内部 handle 或响应凭据头。
 
+Companion 失败仍使用 `HbMiniProgramSDKError`。prepare 与 launch 的授权取消属于两次独立用户决定；业务不得在一次点击中自动串联授权，也不得用 Browser Fake 成功替代 Windows/macOS 真机错误处理验证。完整状态机见[受管桌面程序](https://docs.xiaoheihe.cn/hb_sdk/guide/companion)。
+
 ## Public modules
 
 ## 能力概览
@@ -862,6 +726,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 | `files`      | 声明受控 sandbox 与用户选择授权的文件、目录操作 |
 | `cloud`      | 使用小程序云端排行榜                            |
 | `network`    | 发起经过平台授权的网络请求，并声明受控流式下载  |
+| `companion`  | 准备、启动并控制当前版本审核过的桌面辅助应用    |
 
 具体方法、参数和返回值以 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/) 为准，常见组合写法见 [Recipes](https://docs.xiaoheihe.cn/hb_sdk/recipes/)。
 
@@ -920,6 +785,157 @@ onUnmounted(stopLifecycleEvents)
 - 组件或页面销毁时清理 `on` 注册的监听，避免重复响应。
 - 生命周期事件只派发给注册当时存在的监听器，不会重放；一次性 `launch` 信息应在页面启动阶段通过业务能力调用处理。
 - 收到 `unload` 后，当前 SDK 上下文不可恢复，未完成请求会失败；不要在同一页面上下文继续重试能力调用。
+- Companion preparation 与进程 Session 由 Host 持有，页面 `hide` 或 reload 不会自动取消或终止；新页面分别通过 `getPreparationStatus()` 与 `getActiveSession()` 恢复观察和控制。
+- 新 Runtime generation 取得活动 Companion Session 后，旧 controller 会收到 ownership-lost 并失去写权限；stdio 输出可能 at-least-once 重放，业务必须按自身协议去重。
+
+
+# 受管桌面程序
+
+`companion` 用于准备和启动随当前小程序审核版本发布的桌面辅助应用。V1 仅支持新 PC Host 的
+`windows-x64` 与 `macos-arm64`；老 PC、Mobile、Web 和 Linux 不在支持范围内。
+
+## 声明与构建
+
+项目必须在 `package.json` 显式声明高风险权限：
+
+```json
+{
+  "heybox": {
+    "permissions": {
+      "companion": { "enabled": true }
+    },
+    "companions": {
+      "runner": {
+        "displayName": "桌面辅助程序",
+        "capabilities": ["stdio"],
+        "targets": {
+          "windows-x64": {
+            "source": "companion/runner-windows-x64",
+            "entrypoint": { "kind": "executable", "path": "runner.exe" },
+            "elevation": "none",
+            "args": []
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+归档统一通过 `package.json#heybox.companions` 配置，`source` 相对该 `package.json` 所在目录解析。
+Vite 中使用 `miniappManifest({ platforms: ['windows'] })` 等构建配置；不要在 Vite 配置中复制 Companion 声明。
+构建和本地调试读取同一份声明。构建会检查 ZIP 结构和固定入口，复制到
+`dist/companions/<alias>/<target>.zip`，并生成大小与 SHA-256；Web 文件和 Companion 文件进入同一上传
+session 与同一审核版本。页面不能读取部署后的 `manifest.json`，也不能取得真实 CDN URL 或本机安装路径。
+
+`hb-sdk dev` 的真实 PC 联调可以直接使用这里声明的本地 ZIP，不要求先上传版本，但项目必须已绑定且 COA
+批准 `companion`。dev server 只向 loopback 提供固定 Manifest/ZIP 路由，CLI 用短期票据绑定当前 dev
+进程的 canonical snapshot。ZIP 或配置变化后会校验并切换到新快照，已有 Session 保持原有产物；
+新产物必须重新准备并启动。校验失败时调试台显示阻塞原因，不会悄悄使用旧文件或线上产物。
+单次开发服务最多保留 32 份快照、累计 ZIP 大小 1 GiB；达到上限后停止接纳新快照，
+请先结束调试 Session，再重启开发服务，已有快照不会被自动逐出。
+未配置本地 Companion 时使用 Browser Fake 做状态联调，真实 PC 不会回退到线上 candidate。
+
+构建与 PC 安装都会检查真实二进制格式：Windows 为 AMD64 PE，macOS 为包含 arm64 的 Mach-O；
+脚本即使改名或有执行权限也会被拒绝。授权弹窗展示产物来源与签名状态，本地 ZIP 明确标记
+“本地开发产物，未经过版本审核”。
+`.app` 从 XML 或 binary Info.plist 的 `CFBundleExecutable` 精确选择主入口。
+
+Manifest 只接受固定入口和固定 args。V1 仅支持普通权限启动，`elevation` 只能省略或设为 `none`；
+`required` 会在构建时明确失败，管理员权限启动留待后续版本。公开 API 不接受 executable path、动态 args、
+cwd、environment、shell 或任意命令；不要把 `files.sandbox` 中的普通文件当作可执行对象。
+`displayName` 最多 120 个 Unicode code point；args 最多 64 项，单项最多 1024 UTF-8 bytes、总计最多
+16384 UTF-8 bytes，并拒绝 NUL、CR 和 LF。
+
+## 准备与启动
+
+```ts
+import { companion } from '@heybox/hb-sdk'
+
+// 分别绑定到「准备」与「启动」按钮，不能在一个点击中串联。
+function prepareFromUserAction() {
+  return companion.prepare('runner', {
+    onProgress(progress) {
+      renderProgress(progress)
+    },
+  })
+}
+
+function launchFromUserAction() {
+  return companion.launch('runner')
+}
+```
+
+`prepare()` 和 `launch()` 必须分别由新的可信用户手势触发。每次真正开始新的准备操作前，Runtime 展示一次
+Host 可信授权；已 ready 或加入同一在途准备时不会重复授权。每次真正创建新进程前，`launch()` 再展示独立
+授权，不能复用 prepare 的手势或授权。`launch()` 不会隐式调用 `prepare()`，未准备时稳定失败。
+
+准备操作属于 Host：页面 reload、最小化或进入后台不会取消。新页面可用
+`getPreparationStatus()` 查询状态，并通过相同 alias 加入在途操作；显式取消使用
+`cancelPreparation(alias)` 或 `AbortSignal`。页面 reload 只断开观察者，不会向 Host 发送取消；原子提交已经开始时，最终提交结果优先于取消意图。
+
+## Session 与 stdio
+
+同一小程序 identity 与 alias 同时最多有一个活动 Session。`getActiveSession(alias)` 会取得当前活动 Session
+的控制权；新 Runtime generation 接管后，旧 controller 的写入、关闭 stdin、终止、附件和通知操作都会失败。
+进程退出后 `getActiveSession()` 返回 `undefined`，业务结果应由小程序自行持久化。
+
+stdio 仅在 Manifest 声明 `stdio` 时存在，输入输出都是原始 `Uint8Array`。SDK 不做 UTF-8、换行、NDJSON、
+RPC 或业务状态解析。输出采用 at-least-once 投递，收到 chunk 后 SDK 会确认 sequence；断连与重取控制权可能
+导致重复，因此业务 framing 必须携带可去重标识，并能处理拆包、粘包和重放。
+
+```ts
+const session = await companion.getActiveSession('runner')
+if (session?.stdio) {
+  const stop = session.stdio.onStdout(bytes => decodeBusinessFrame(bytes))
+  await session.stdio.write(encodeBusinessFrame({ type: 'status' }))
+  // 组件销毁时调用 stop()；业务退出协议可先写入，再 closeStdin()。
+}
+```
+
+平台不提供语义跨平台不稳定的 request-close。业务可先通过自身 stdio 协议请求正常退出，或关闭 stdin；
+`terminate()` 是强制结束完整受管进程树。页面隐藏或 reload 不结束 Session，用户真正关闭小程序窗口时由 Host
+处理完整进程树生命周期。
+
+## 可选能力
+
+- `attachments`：`session.attachments.open(id)` 返回只读 `FileHandle`；opaque id 来自桌面程序自身业务协议，页面无法指定物理路径。
+- `notifications`：页面解析业务协议后，可请求 Host 展示固定类别通知；页面完全断开时不承诺业务通知。
+- `stdio`：仅提供原始字节双向流，不提供文本编码或 RPC。
+
+只有 Manifest 声明且 Host 实现的能力才出现在 Session。不要根据操作系统或属性存在性猜测支持情况。
+
+## 调试与验收
+
+调试台分别显示浏览器、手机与 PC Companion 的就绪状态，以及本地 alias、平台和产物摘要短前缀。
+PC 会在页面闲置时继续复核授权；明确撤销权限会结束进程树，临时网络故障只允许有时限的宽限，
+不会让已失去授权的进程无限运行。关闭开发服务前请先停止调试进程。
+
+Browser Dev Host 只提供确定性的 Fake 场景，用于开发准备进度、Session 状态、stdio framing、错误 UI 与恢复逻辑。
+Fake 不选择、不下载、不解压、不启动本机程序，也不经过操作系统安全检查或真实进程组。
+因此 Browser Fake、Mobile 或 Web 的结果不能作为桌面发布证据；发布前必须分别在目标 Windows/macOS 新 PC Host
+完成归档摘要、准备取消、启动、stdio、退出与进程树清理验收。
+
+## 失败处理
+
+- `USER_GESTURE_REQUIRED`：当前 prepare 或 launch 缺少新的可信用户手势。
+- `USER_CANCELLED`：用户拒绝或关闭本次 Host 授权，应正常结束流程。
+- `COMPANION_NOT_PREPARED`：先由新的用户操作显式调用 `prepare()`。
+- `COMPANION_INTEGRITY_FAILED` / `COMPANION_ARCHIVE_INVALID`：停止重试并提交新审核版本，不能绕过摘要或系统安全检查。
+- `COMPANION_SESSION_OWNERSHIP_LOST`：当前 Runtime 已失去 controller；需要时重新调用 `getActiveSession()`。
+- `COMPANION_DESCRIPTOR_UNAVAILABLE`：授权或描述符暂时不可用，可在有界重试策略下重试。
+- `COMPANION_ELEVATION_DENIED`：为未来管理员权限启动保留的兼容错误码；V1 构建不接受 `elevation: 'required'`。
+- `METHOD_FORBIDDEN` / `COMPANION_UNSUPPORTED`：当前 Host 或平台未实现，不要循环重试或用任意执行替代。
+
+完整类型与方法见 [API Reference](https://docs.xiaoheihe.cn/hb_sdk/reference/)。
+
+## 完成检查
+
+- 权限、目标 ZIP、固定入口和固定参数都随同一版本提交审核。
+- prepare 与 launch 使用两次独立可信用户操作和 Host 授权。
+- stdio 业务协议处理了原始字节 framing、at-least-once 去重和断连恢复。
+- 未向页面暴露或传入 URL、物理路径、动态 args、环境变量、shell 或 PID。
+- Browser Fake 只用于开发，目标平台均已完成新 PC 真机验收。
 
 ## 云端排行榜