@heybox/hb-sdk 0.8.0-alpha.3 → 0.8.0

package/dist/vite.esm.js

@@ -5,7 +5,30 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0-alpha.3';
+    : '0.8.0';
+
+/**
+ * iframe 与调试台页面的开发期 console 捕获转发。
+ *
+ * 双条件门控（iframe 转发）：
+ * 1. 构建期：`hb-sdk dev`（vite serve）注入 `false`；`hb-sdk build` /
+ *    `vite build`（生产）永不注入或替换为 `false`，本模块被死代码消除。
+ * 2. 运行期：仅在 `window.name` 为 `__hb_sdk_mini_dev__` 的调试 iframe 中激活，
+ *    用户设备上的正式运行环境没有该标记。
+ *
+ * 无侵入 patch `console.log/debug/info/warn/error`：原样放行（DevTools 不受影响）+
+ * 通过 `window.parent.postMessage` 转发给调试台（CSP 的 connect-src 不约束 postMessage，
+ * 网络上报由调试台页面代理）。发送全程静默：失败不得回打 console，避免自触发死循环。
+ *
+ * 激活时机：由 SDK 默认单例初始化时调用（业务 `import '@heybox/hb-sdk'` 即生效）；
+ * iframe 标记由调试台 `iframe.name` 与 vite dev 注入的无依赖 bootstrap 共同设置。
+ * 调试台页面自身（runtime 跑在这里，`[hb-sdk-runtime]` 日志不经过 iframe）另用
+ * `installMiniDevConsoleSelfCapture` 接入「日志」页签（source: 'host'）。
+ */
+const MINI_DEV_IFRAME_WINDOW_NAME = '__hb_sdk_mini_dev__';
+const MINI_DEV_CONSOLE_EVENT_TYPE = 'hb-sdk:mini-dev-console';
+/** 调试台页面与 iframe bootstrap 共用的已安装标记（window/console 上的属性名）。 */
+const MINI_DEV_CONSOLE_INSTALL_FLAG = '__hb_sdk_mini_dev_console_installed__';
 
 var re = {exports: {}};
 
@@ -2792,6 +2815,197 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+const MINI_PROGRAM_MESSAGE_VERSION = 2;
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+
+const MINI_PROGRAM_PERMISSION_KEYS = [
+    'userInfo',
+    'steamLibrary',
+    'share',
+    'storage',
+    'filesystem',
+    'clipboard',
+    'leaderboard',
+    'network',
+];
+const MINI_PROGRAM_PERMISSION_CATALOG = [
+    {
+        key: 'userInfo',
+        name: '用户信息',
+        description: '登录小程序并读取当前用户的授权信息。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['auth.login', 'user.getInfo'],
+        conditions: ['继续执行黑盒登录、用户授权和可信手势规则。'],
+    },
+    {
+        key: 'steamLibrary',
+        name: 'Steam 游戏库',
+        description: '读取当前用户授权的 Steam 游戏库。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: ['user.getSteamGameList'],
+        conditions: ['继续执行账号绑定和数据可用性规则。'],
+    },
+    {
+        key: 'share',
+        name: '分享',
+        description: '使用小程序分享、分享菜单和截图能力。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['share.copyLink', 'share.showShareMenu', 'share.screenshot'],
+        conditions: ['继续执行分享参数校验和 Host 支持检查。'],
+    },
+    {
+        key: 'storage',
+        name: '键值存储',
+        description: '读写按小程序隔离的简单键值数据。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['storage.getStorage', 'storage.setStorage'],
+        conditions: ['仅用于简单键值存储，不包含文件系统。'],
+    },
+    {
+        key: 'filesystem',
+        name: '文件系统',
+        description: '访问小程序沙盒文件和用户选择的外部文件。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: [
+            'network.download',
+            'files.pickFiles',
+            'files.pickDirectory',
+            'files.saveFile',
+            'file.create',
+            'file.remove',
+            'file.exists',
+            'file.readText',
+            'file.writeText',
+            'file.readBytes',
+            'file.writeBytes',
+            'file.stat',
+            'directory.create',
+            'directory.remove',
+            'directory.exists',
+            'directory.list',
+        ],
+        conditions: ['外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。'],
+    },
+    {
+        key: 'clipboard',
+        name: '剪贴板',
+        description: '向系统剪贴板写入文本。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['device.setClipboard'],
+        conditions: ['继续执行文本长度和 Host 支持限制。'],
+    },
+    {
+        key: 'leaderboard',
+        name: '排行榜',
+        description: '读写小程序云排行榜。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: [
+            'cloud.leaderboard.submit',
+            'cloud.leaderboard.getList',
+            'cloud.leaderboard.getCurrentUserEntry',
+            'cloud.leaderboard.deleteCurrentUserEntry',
+            'cloud.leaderboard.getInfo',
+        ],
+        conditions: ['排行榜必须已创建，用户和资源规则保持不变。'],
+    },
+    {
+        key: 'network',
+        name: '网络',
+        description: '通过 network 模块请求或下载外部资源。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {
+            useOfficialDomain: {
+                type: 'boolean',
+                required: false,
+                default: false,
+                description: '是否申请访问小黑盒官方域名。',
+            },
+        },
+        methods: ['network.request', 'network.download'],
+        conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
+    },
+];
+new Set(MINI_PROGRAM_PERMISSION_KEYS);
+
+new Set(MINI_PROGRAM_PERMISSION_KEYS);
+
+const MINIAPP_PERMISSION_KEYS = MINI_PROGRAM_PERMISSION_KEYS;
+function parseMiniappPermissions(value, options) {
+    const sourceLabel = options.sourceLabel ?? 'package.json#heybox.permissions';
+    if (!options.present) {
+        if (requiresExplicitPermissions(options.sdkVersion)) {
+            throw new Error(`${sourceLabel} 在 @heybox/hb-sdk ${options.sdkVersion} 中必须声明；无权限需求时请配置空对象 {}`);
+        }
+        return { declared: false };
+    }
+    if (!isRecord$1(value)) {
+        throw new Error(`${sourceLabel} 必须是 JSON 对象`);
+    }
+    const knownKeys = new Set(MINIAPP_PERMISSION_KEYS);
+    for (const key of Object.keys(value)) {
+        if (!knownKeys.has(key))
+            throw new Error(`${sourceLabel} 包含未知权限：${key}`);
+    }
+    const permissions = {};
+    for (const key of MINIAPP_PERMISSION_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(value, key))
+            continue;
+        const declaration = value[key];
+        const itemLabel = `${sourceLabel}.${key}`;
+        if (!isRecord$1(declaration))
+            throw new Error(`${itemLabel} 必须是 JSON 对象`);
+        const definition = MINI_PROGRAM_PERMISSION_CATALOG.find((item) => item.key === key);
+        if (!definition)
+            throw new Error(`权限目录缺少定义：${key}`);
+        const allowedFields = new Set(['enabled', ...Object.keys(definition.config)]);
+        for (const field of Object.keys(declaration)) {
+            if (!allowedFields.has(field))
+                throw new Error(`${itemLabel} 包含未知字段：${field}`);
+        }
+        if (typeof declaration.enabled !== 'boolean')
+            throw new Error(`${itemLabel}.enabled 必须是 boolean`);
+        let useOfficialDomain = false;
+        if (key === 'network') {
+            if (declaration.useOfficialDomain !== undefined && typeof declaration.useOfficialDomain !== 'boolean') {
+                throw new Error(`${itemLabel}.useOfficialDomain 必须是 boolean`);
+            }
+            useOfficialDomain = declaration.useOfficialDomain === true;
+        }
+        if (!declaration.enabled)
+            continue;
+        permissions[key] = key === 'network' ? { enabled: true, useOfficialDomain } : { enabled: true };
+    }
+    return { declared: true, permissions: permissions };
+}
+function requiresExplicitPermissions(sdkVersion) {
+    const parsed = semverExports.parse(sdkVersion);
+    if (!parsed)
+        throw new Error(`sdkVersion 必须是合法 SemVer：${sdkVersion}`);
+    return parsed.major > 0 || parsed.minor >= 9;
+}
+function getMissingPermissionsWarning(sourceLabel = 'package.json#heybox.permissions') {
+    return `${sourceLabel} 尚未声明。当前按 0.8 兼容行为构建；0.9.0 起将拒绝构建，请尽快补充权限声明（无权限需求时配置 {}）。`;
+}
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 function validateMiniappPackageVersionForBuild(version) {
     return validateMiniappManifestVersion(version, 'package.json.version');
@@ -2805,7 +3019,13 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
 }
 function renderMiniappManifest(manifest) {
     const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
-    return `${JSON.stringify({ version: manifest.version, sdkVersion: manifest.sdkVersion, platforms }, null, 2)}\n`;
+    const output = {
+        version: manifest.version,
+        sdkVersion: manifest.sdkVersion,
+        platforms,
+        ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
+    };
+    return `${JSON.stringify(output, null, 2)}\n`;
 }
 function validateMiniappPlatforms(platforms, sourceLabel = 'platforms') {
     if (!Array.isArray(platforms) || platforms.length === 0) {
@@ -2860,6 +3080,21 @@ function findNearestPackageJsonPath(startDir) {
     }
 }
 function readMiniappVersionFromPackageJson(root) {
+    return readMiniappPackageJson(root, true).version;
+}
+function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = packageJson.heybox;
+    if (heybox !== undefined && !isRecord(heybox)) {
+        throw new Error('@heybox/hb-sdk 提示：package.json#heybox 必须是 JSON 对象');
+    }
+    const present = isRecord(heybox) && Object.prototype.hasOwnProperty.call(heybox, 'permissions');
+    return parseMiniappPermissions(isRecord(heybox) ? heybox.permissions : undefined, {
+        present,
+        sdkVersion,
+    });
+}
+function readMiniappPackageJson(root, requireVersion) {
     const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
     try {
@@ -2875,10 +3110,13 @@ function readMiniappVersionFromPackageJson(root) {
     catch (error) {
         throw new Error(`@heybox/hb-sdk 解析 package.json 失败：${formatReason(error)}`);
     }
-    if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+    if (requireVersion && (typeof packageJson.version !== 'string' || packageJson.version.trim() === '')) {
         throw new Error('@heybox/hb-sdk 提示：package.json.version 必须是非空字符串');
     }
-    return packageJson.version.trim();
+    return { packageJson, version: typeof packageJson.version === 'string' ? packageJson.version.trim() : '' };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function formatReason(error) {
     if (error instanceof Error && error.message) {
@@ -11317,10 +11555,6 @@ function parse(html, options) {
     return Parser.parse(html, options);
 }
 
-const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
-const MINI_PROGRAM_MESSAGE_VERSION = 2;
-const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
-
 const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
 const RUNTIME_GATE_MARKER = 'data-heybox-runtime-gate';
 const RUNTIME_GATE_STYLE_MARKER = 'data-heybox-runtime-gate-style';
@@ -11643,8 +11877,29 @@ function shouldSkipMiniappPlatformCspFromEnv(env = process.env) {
     return env[HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV] === VERIFIED_RUNTIME_PERMISSION_CONTEXT && env[HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV] === '1';
 }
 
+/**
+ * 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) {
+    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('_');
 function miniappManifest(options) {
     const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
     const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
@@ -11656,12 +11911,17 @@ function miniappManifest(options) {
     let priorBuildError;
     return {
         name: 'heybox-miniapp-manifest',
-        config(config) {
+        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' } : {}),
                 },
             };
         },
@@ -11683,12 +11943,12 @@ function miniappManifest(options) {
             }
         },
         transformIndexHtml(html) {
-            return enforceMiniappHtmlPolicy(html, {
+            const enforced = enforceMiniappHtmlPolicy(html, {
                 ...(command === 'serve' ? { hmrWebSocketUrl } : {}),
                 skipPlatformCsp,
             });
-        },
-        async closeBundle() {
+            return command === 'serve' ? injectMiniDevConsoleBootstrap(enforced) : enforced;
+        }, async closeBundle() {
             // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
             // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
             if (priorBuildError) {
@@ -11696,6 +11956,9 @@ function miniappManifest(options) {
             }
             const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
             const sdkVersion = resolveSdkVersion();
+            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');
@@ -11711,7 +11974,12 @@ function miniappManifest(options) {
             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 }));
+            writeFileSync(manifestPath, renderMiniappManifest({
+                version,
+                sdkVersion,
+                platforms,
+                ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
+            }));
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.0-alpha.3",
+  "version": "0.8.0",
   "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.0-alpha.3"
+    "@heybox/hb-sdk-protocol": "0.8.0"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -97,6 +97,7 @@
     "get-port": "^7.1.0",
     "happy-dom": "^19.0.2",
     "lucide-vue-next": "1.0.0",
+    "markdown-it": "^14.1.0",
     "open": "^10.2.0",
     "ora": "^5.4.1",
     "picocolors": "^1.1.1",
@@ -113,12 +114,12 @@
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
     "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.8.0-alpha.3",
-    "@heybox/hb-api": "~1.25.23",
+    "@heybox/hb-api": "~1.28.2",
+    "@heybox/hb-sdk-runtime": "~0.8.0",
+    "@heybox/runtime": "~0.2.0",
     "@heybox/runtime-policy": "~0.2.0",
-    "@heybox/runtime-transport-fetch": "~0.2.0",
-    "@heybox/runtime": "~0.2.0"
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
+    "@heybox/runtime-transport-fetch": "~0.2.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -175,18 +176,21 @@
     "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: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",
     "test:watch": "NODE_OPTIONS='--conditions=heybox' vitest",
     "changelog:draft": "node scripts/changelog-draft.cjs",
     "check:changelog": "node scripts/check-changelog.cjs",
     "release:verify-tarball": "node scripts/skill/verify-tarball-install.mjs",
-    "test:release": "node --test scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs ../../ops/jobs/release-hb-sdk/docs-release-contract.test.cjs",
+    "test:release": "node --test scripts/public-changelog.test.mjs scripts/public-changelog-workflow.test.cjs scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs ../../ops/jobs/release-hb-sdk/docs-release-contract.test.cjs ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.test.cjs",
     "test:compatibility-evidence": "node --test scripts/validate-compatibility-evidence.test.mjs",
     "release:prepare": "node scripts/release-prepare.cjs",
     "release:tag": "node scripts/release-tag.cjs",
     "release:family:dry-run": "node ../../ops/jobs/publish-changed-packages/publish.cjs --dry-run",
     "release:family:promote": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action promote",
-    "release:family:rollback": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action rollback"
+    "release:family:rollback": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action rollback",
+    "release:stable:promote": "node ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.cjs --action promote",
+    "release:stable:rollback": "node ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.cjs --action rollback"
   }
 }

package/skill/SKILL.md

@@ -39,20 +39,19 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 ## Step 4: Implement workshop mini-program code
 
 1. Import the root package eagerly; the SDK starts its handshake automatically and capability calls wait for it internally.
-2. For a network-enabled mini-program, use `auth.login({ scopes? })` to obtain `{ code, expiresIn: 300, scopes }`. Identity is always implicit; request only optional scopes the business actually needs.
-3. Send the code only to the developer's backend. That backend follows the backend OpenAPI documentation to exchange it for a token; mini-program code must never exchange application credentials itself.
-4. For a network-disabled mini-program, call `user.getInfo()` to read the current login state, `userInfo.app_user_id`, and `userInfo.profile`. The Host silently grants the current local user scopes (`identity` and `profile`), so this call does not require a trusted user action or authorization UI. It still cannot obtain a code or call OpenAPI.
+2. Declare protected capabilities in `package.json#heybox.permissions`. `auth.login()` and `user.getInfo()` require `userInfo`; `user.getSteamGameList()` requires `steamLibrary`; none of them implicitly require the public `network` permission.
+3. Use `auth.login({ scopes? })` to obtain `{ code, expiresIn: 300, scopes }`. Identity is always implicit; request only optional scopes the business actually needs.
+4. Send the code only to the developer's backend. That backend follows the backend OpenAPI documentation to exchange it for a token; mini-program code must never exchange application credentials itself.
 5. Handle `HbMiniProgramSDKError` for SDK initialization and capability failures.
 6. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
 7. Use `getHandshakeState()` for the current persistent handshake state and `onHandshakeStateChange()` for an immediate replay plus future changes. Cancel the returned subscription when the page or component unmounts.
 8. Treat the non-replayed `ready` lifecycle event only as an edge notification. After a duplicate handshake it may repeat, so never use it as state or as the source for enabling a late-mounted control.
 9. Use the default SDK instance exposed by the root package. For gesture-gated controls, initialize from the current handshake state, subscribe to changes, and enable the control only when `status === 'ready'`. Keep calls such as `auth.login()` in the original user-action callback; do not wait for handshake inside that callback.
 10. When authorization UI is required, call `auth.login()` from a trusted user action. Missing gesture returns `USER_GESTURE_REQUIRED`; cancelling, rejecting, or closing returns `AUTHORIZATION_CANCELLED` and does not confirm or change authorization. An already-authorized `auth.login()` request may return a new code silently.
-11. `user.getSteamGameList()` is available only to network-disabled mini-programs. In a network-enabled mini-program it returns `SERVER_API_REQUIRED`, and there is no Steam library authorization scope or OpenAPI resource. Treat `user.getInfo()` returning `SERVER_API_REQUIRED` as a server-boundary signal, not as logged-out state.
-12. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
-13. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the default mini-program share link. 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`.
-14. Treat `files` and `network.download()` as a retained public contract that is not yet enabled by a current Host. The legacy PC adapter was dropped because the new PC will implement the Host ports directly. Until then, legacy PC, Mobile, Web, and Browser Dev Host return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Once a supporting Host is available, 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 })`.
-15. 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.
+11. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
+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.
 
 ## Step 5: Use CLI workflows
 
@@ -68,7 +67,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 10. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
 11. 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 remote inspection and preview management.
 12. Use `hb-sdk remote deploy --release-note <text>` to run the project's `scripts.build`, upload, and submit the current project for audit. Do not recommend the removed top-level `hb-sdk deploy` alias.
-13. `hb-sdk dev` and `hb-sdk remote deploy` skip the platform CSP only when the validated remote permission snapshot has `network.request.status=enabled`. `useOfficialDomain` does not participate in CSP skip decisions. Direct `hb-sdk build`, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
+13. `hb-sdk dev` and `hb-sdk remote deploy` skip the platform CSP only when the current version declares and the platform approves `network`. `useOfficialDomain` does not participate in CSP skip decisions. Direct `hb-sdk build`, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
 14. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
 15. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
 16. Use `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and square visibility commands only after showing the target and obtaining required confirmation.

package/skill/references/api-protocol.md

@@ -284,13 +284,11 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 | [Protocol API](#public-protocol-entrypoint) | `@heybox/hb-sdk/protocol` 的协议常量、消息类型与 method 契约。 |
 | [Miniapp Publish API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/miniapp-publish/) | `@heybox/hb-sdk/miniapp-publish` 的构建产物发布前的公开校验工具。 |
 | [Vite API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/vite/) | `@heybox/hb-sdk/vite` 的Vite 工坊小程序插件。 |
-| [Host Runtime 集成](https://docs.xiaoheihe.cn/hb_sdk/reference/runtime/) | `@heybox/hb-sdk-runtime` 的 Host Port、Web Host 与 Runtime 集成入口；声明 Reference 在 Runtime package 内生成。 |
 
 ## 查询建议
 
 - 想查业务接入路径：先看 [Guide](recipes.md)。
 - 想查导出符号：从上方对应公开入口进入分类页。
-- 想接入详情页或 Browser Dev Host：先看 [Host Runtime 集成](https://docs.xiaoheihe.cn/hb_sdk/reference/runtime/)，再查 Runtime package 的声明 Reference。
 - 想看场景化用法：优先看 Guide / Recipes 页面中的“进一步阅读”。
 
 ## 统计
@@ -302,7 +300,7 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
 | Vite API | 0 | 1 | 5 | 1 | 1 |
 
-<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=2; fingerprint=cb985ad876f7066639ee3b72d545185f251ed6ad597b8276425e02615bb608ba -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=3; fingerprint=660a21ad77c32f30dbc7ebb02b053ebce2a7c6e7301cc805a5cdd1a75572fbb2 -->
 
 ## SDK API