@heybox/hb-sdk 0.8.0-alpha.10 → 0.8.0-alpha.13

package/dist/index.cjs.js

@@ -799,7 +799,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0-alpha.10';
+    : '0.8.0-alpha.13';
 
 const DEFAULT_TIMEOUT = 10000;
 const HANDSHAKE_RETRY_INTERVAL = 250;
@@ -3766,7 +3766,91 @@ function createMiniProgramSDK(options) {
     return new MiniProgramSDK(options);
 }
 
+/**
+ * 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__';
+/** 调试台页面自捕获（source: 'host'）与 iframe 转发共用的已安装标记。 */
+const INSTALL_FLAG = MINI_DEV_CONSOLE_INSTALL_FLAG;
+function isDevLoggingEnabled() {
+    if (typeof false !== 'undefined' && false !== true) {
+        return false;
+    }
+    return typeof window !== 'undefined' && window.name === MINI_DEV_IFRAME_WINDOW_NAME;
+}
+const levels = ['log', 'debug', 'info', 'warn', 'error'];
+function patchConsoleLevels(consoleRef, deliver, owner) {
+    if (!owner || owner[INSTALL_FLAG] === true) {
+        return false;
+    }
+    let patched = false;
+    for (const level of levels) {
+        const original = consoleRef[level];
+        if (typeof original !== 'function') {
+            continue;
+        }
+        const forward = function (...args) {
+            try {
+                deliver(level, args);
+            }
+            catch {
+                /* 转发失败必须静默，禁止回打 console 造成自触发循环。 */
+            }
+            return original.apply(this, args);
+        };
+        try {
+            consoleRef[level] = forward;
+            patched = true;
+        }
+        catch {
+            return patched;
+        }
+    }
+    if (patched) {
+        owner[INSTALL_FLAG] = true;
+    }
+    return patched;
+}
+function installMiniDevConsoleForwarding(consoleRef = console) {
+    if (!isDevLoggingEnabled()) {
+        return;
+    }
+    patchConsoleLevels(consoleRef, (level, args) => {
+        const message = {
+            type: MINI_DEV_CONSOLE_EVENT_TYPE,
+            detail: { level, args, timestamp: Date.now() },
+        };
+        window.parent?.postMessage(message, '*');
+    }, typeof window === 'undefined' ? undefined : window);
+}
+
 let defaultSDK = createMiniProgramSDK();
+// 开发期调试台 console 捕获：双条件门控（vite serve 注入 define + 调试 iframe 标记），
+// 生产构建被死代码消除，正式环境无副作用。失败静默，绝不影响 SDK 初始化。
+try {
+    installMiniDevConsoleForwarding();
+}
+catch {
+    /* 捕获层异常不得阻断 SDK 单例创建。 */
+}
 function getDefaultSDK() {
     if (!defaultSDK) {
         defaultSDK = createMiniProgramSDK();

package/dist/index.esm.js

@@ -795,7 +795,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0-alpha.10';
+    : '0.8.0-alpha.13';
 
 const DEFAULT_TIMEOUT = 10000;
 const HANDSHAKE_RETRY_INTERVAL = 250;
@@ -3762,7 +3762,91 @@ function createMiniProgramSDK(options) {
     return new MiniProgramSDK(options);
 }
 
+/**
+ * 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__';
+/** 调试台页面自捕获（source: 'host'）与 iframe 转发共用的已安装标记。 */
+const INSTALL_FLAG = MINI_DEV_CONSOLE_INSTALL_FLAG;
+function isDevLoggingEnabled() {
+    if (typeof false !== 'undefined' && false !== true) {
+        return false;
+    }
+    return typeof window !== 'undefined' && window.name === MINI_DEV_IFRAME_WINDOW_NAME;
+}
+const levels = ['log', 'debug', 'info', 'warn', 'error'];
+function patchConsoleLevels(consoleRef, deliver, owner) {
+    if (!owner || owner[INSTALL_FLAG] === true) {
+        return false;
+    }
+    let patched = false;
+    for (const level of levels) {
+        const original = consoleRef[level];
+        if (typeof original !== 'function') {
+            continue;
+        }
+        const forward = function (...args) {
+            try {
+                deliver(level, args);
+            }
+            catch {
+                /* 转发失败必须静默，禁止回打 console 造成自触发循环。 */
+            }
+            return original.apply(this, args);
+        };
+        try {
+            consoleRef[level] = forward;
+            patched = true;
+        }
+        catch {
+            return patched;
+        }
+    }
+    if (patched) {
+        owner[INSTALL_FLAG] = true;
+    }
+    return patched;
+}
+function installMiniDevConsoleForwarding(consoleRef = console) {
+    if (!isDevLoggingEnabled()) {
+        return;
+    }
+    patchConsoleLevels(consoleRef, (level, args) => {
+        const message = {
+            type: MINI_DEV_CONSOLE_EVENT_TYPE,
+            detail: { level, args, timestamp: Date.now() },
+        };
+        window.parent?.postMessage(message, '*');
+    }, typeof window === 'undefined' ? undefined : window);
+}
+
 let defaultSDK = createMiniProgramSDK();
+// 开发期调试台 console 捕获：双条件门控（vite serve 注入 define + 调试 iframe 标记），
+// 生产构建被死代码消除，正式环境无副作用。失败静默，绝不影响 SDK 初始化。
+try {
+    installMiniDevConsoleForwarding();
+}
+catch {
+    /* 捕获层异常不得阻断 SDK 单例创建。 */
+}
 function getDefaultSDK() {
     if (!defaultSDK) {
         defaultSDK = createMiniProgramSDK();

package/dist/vite.cjs.js

@@ -8,7 +8,30 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0-alpha.10';
+    : '0.8.0-alpha.13';
+
+/**
+ * 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: {}};
 
@@ -11857,8 +11880,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();
@@ -11870,12 +11914,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' } : {}),
                 },
             };
         },
@@ -11897,12 +11946,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) {

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.10';
+    : '0.8.0-alpha.13';
+
+/**
+ * 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: {}};
 
@@ -11854,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();
@@ -11867,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' } : {}),
                 },
             };
         },
@@ -11894,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.0-alpha.10",
+  "version": "0.8.0-alpha.13",
   "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.10"
+    "@heybox/hb-sdk-protocol": "0.8.0-alpha.13"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -113,13 +113,13 @@
     "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
-    "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.8.0-alpha.10",
     "@heybox/hb-api": "~1.28.2",
     "@heybox/runtime": "~0.2.0",
+    "@heybox/runtime-policy": "~0.2.0",
     "@heybox/runtime-transport-fetch": "~0.2.0",
-    "@heybox/runtime-policy": "~0.2.0"
+    "@heybox/hb-sdk-runtime": "~0.8.0-alpha.13",
+    "@heybox-domain/heybox-theme": "~0.1.0",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/SKILL.md

@@ -50,7 +50,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 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. 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. 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 })`.
+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

package/skill/references/api-protocol.md

@@ -300,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=3; fingerprint=95cbf9ad1d791cfa4133a35e9084252798450930135372e1467931e34226b8ea -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=3; fingerprint=bf58059fc425a0c142ed1d3706d14a0a773f6fe623f99df08dc14e6f0e93461b -->
 
 ## SDK API
 

package/skill/references/api-root.md

@@ -24,7 +24,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.0-alpha.10`
+- Version at generation time: `0.8.0-alpha.13`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -232,6 +232,7 @@ Use `@heybox/hb-sdk/vite` only in `vite.config.ts`. Do not import it from iframe
 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,
@@ -247,7 +248,7 @@ import { shouldSkipMiniappPlatformCspFromEnv } from './runtime-permission-env';
 
 export interface MiniappManifestPlugin {
   name: string;
-  config: (config: MiniappManifestUserConfig) => MiniappManifestUserConfig | void;
+  config: (config: MiniappManifestUserConfig, env?: { command: 'build' | 'serve' }) => MiniappManifestUserConfig | void;
   configResolved: (resolved: MiniappManifestResolvedConfig) => void;
   /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
   buildEnd: (error?: Error) => void;
@@ -289,12 +290,34 @@ export interface MiniappManifestResolvedConfig {
 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)}`;
+}
+
 export interface MiniappManifestOptions {
   platforms: readonly MiniappPlatform[];
 }
 
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
+const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
 
 export function miniappManifest(options: MiniappManifestOptions): MiniappManifestPlugin {
   const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
@@ -308,12 +331,17 @@ export function miniappManifest(options: MiniappManifestOptions): MiniappManifes
 
   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' } : {}),
         },
       };
     },
@@ -335,12 +363,12 @@ export function miniappManifest(options: MiniappManifestOptions): MiniappManifes
       }
     },
     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) {
@@ -560,15 +588,14 @@ try {
 
 | Host             | `files.sandbox` | 外部 picker | `network.download()` |
 | ---------------- | --------------- | ----------- | -------------------- |
-| 旧版 PC          | 不支持          | 不支持      | 不支持               |
+| 新 PC            | 支持            | 支持        | 支持                 |
 | Mobile           | 不支持          | 不支持      | 不支持               |
 | Web              | 不支持          | 不支持      | 不支持               |
 | Browser Dev Host | 不支持          | 不支持      | 不支持               |
 
 当前 Runtime 认识但 Host 未实现时返回 `METHOD_FORBIDDEN`；旧 Runtime 收到新 method 时返回
-`METHOD_NOT_FOUND`。此前曾实现面向旧版小黑盒 PC 的 Host 适配；由于新版 PC 即将启用，该适配
-不再发布。文件/下载 API、协议和 Runtime 体系保持不变，后续直接按照新版 PC Host 架构接入。
-当前任何 Host 都不提供 Blob 或内存假下载。
+`METHOD_NOT_FOUND`。新 PC V1 注入真实文件与流式下载 primitive；其他当前 Host 未实现时仍不
+提供 throwing stub、Blob 或内存假下载。
 
 ### 路径与创建
 
@@ -594,9 +621,10 @@ async function saveFromUserAction(text: string) {
 }
 ```
 
-`saveFile()` 打开系统保存对话框并返回精确 File 授权，不会同时创建或保留 Directory
-授权。V1 不接受 `accept`；扩展名过滤只属于 `pickFiles({ accept: ['.json'] })`。外部授权仅在当前
-Runtime session 有效。
+`saveFile()` 请求 Host 返回精确 File 授权，不会同时创建或保留 Directory 授权。新 PC 当前先让
+用户选择保存目录，再以 `suggestedName` 独占创建空文件；同名文件抛出 `FILE_ALREADY_EXISTS`，
+不会静默覆盖。V1 不接受 `accept`；扩展名过滤只属于 `pickFiles({ accept: ['.json'] })`。外部授权
+仅在当前 Runtime session 有效。
 
 `pickFiles()` / `pickDirectory()` 默认返回 `mode: 'read'` 的授权；只有显式传入
 `multiple: true` 时，`pickFiles()` 才允许 Host 返回多个文件。需要修改文件、在所选目录中创建

package/skill/references/cli.md

@@ -105,7 +105,7 @@ Agent rules:
 hb-sdk dev
 ```
 
-CLI 会启动页面服务并自动打开 Vue 3 本地调试台。左侧集中放置调用日志、Storage 和问题三个诊断页签，右侧保持稳定的小程序内容与设备预览。
+CLI 会启动页面服务并自动打开 Vue 3 本地调试台。左侧集中放置日志、Storage 和问题三个诊断页签，右侧保持稳定的小程序内容与设备预览。
 
 默认终端只显示启动结果、调试页地址、小程序地址和手机调试入口。排查启动问题时使用 `hb-sdk dev --verbose` 查看完整启动阶段；手机扫码调试凭证连续重试失败时，默认只在失败和恢复两次状态变化时提示。
 
@@ -125,7 +125,7 @@ Browser Mock 会自动在实时与兼容链路间切换。手机调试使用 `op
 - SDK 初始化与用户身份授权流程
 - 生命周期、Storage 和排行榜等能力
 
-调试台提供紧凑的调用日志、当前小程序隔离作用域内的 Storage 只读快照和问题聚合。日志与网络记录只保留脱敏的诊断字段，不展示 payload、结果、查询参数、凭据或原始错误信息。工坊小程序默认不能进行网络请求，网络权限暂未开放申请，不要把本地结果当成线上能力。
+调试台提供紧凑的日志、当前小程序隔离作用域内的 Storage 只读快照和问题聚合。日志与网络记录只保留脱敏的诊断字段，不展示 payload、结果、查询参数、凭据或原始错误信息。工坊小程序默认不能进行网络请求，网络权限暂未开放申请，不要把本地结果当成线上能力。
 
 右侧可切换 iPhone 16 Pro Max（`387 x 821`）与 Pixel 9 Pro（`322 x 716`）两个设备预设。尺寸对应固定上游设备外框的真实屏幕 opening；预设同时决定外框、状态栏、安全区和 viewport。切换设备不会重新加载小程序或重启 Runtime，页面状态和调试会话保持不变。授权与操作弹窗、Toast、Loading 和振动反馈均显示在设备预览内部，不会覆盖整个调试台。
 

package/skill/references/examples.md

@@ -105,7 +105,7 @@ try {
 }
 ```
 
-### Sandbox download contract (Host pending)
+### Sandbox download contract (new PC)
 
 ```ts
 import { files, network, HbMiniProgramSDKError } from '@heybox/hb-sdk';
@@ -185,8 +185,8 @@ export default defineConfig({
 - Do not call unsupported storage delete/clear/info operations.
 - Do not pass raw internal share/network protocol fields from mini-program code.
 - Do not send `multipart/form-data` (or handcrafted multipart bodies) through `network.request`; use form-urlencoded string body or a dedicated upload capability.
-- Do not pass string paths, browser File System Access handles, Blob targets, Range/resume fields, or upload bodies to `network.download`; use SDK-created File/Directory handles after a supporting Host is available.
-- Do not treat any current Host, including legacy PC or Browser Dev Host, as evidence for files/download support. They return `METHOD_FORBIDDEN` and provide no memory fallback; the new PC Host will integrate the retained contract separately.
+- Do not pass string paths, browser File System Access handles, Blob targets, Range/resume fields, or upload bodies to `network.download`; use SDK-created File/Directory handles on new PC.
+- Do not treat Mobile, Web, Browser Dev Host, or legacy PC as evidence for files/download support. Only new PC currently implements the retained contract; other Hosts return `METHOD_FORBIDDEN` and provide no memory fallback.
 - Do not treat `hb-sdk login` as iframe SDK authentication state.
 - Do not create a second mock runtime package when `hb-sdk dev` is the supported local mock workflow.
 - Do not import `@heybox/hb-sdk/vite` from iframe business code or fetch a deployed `manifest.json` directly.