@heybox/hb-sdk 0.8.0-alpha.2 → 0.8.0-alpha.9

package/README.md

@@ -2,6 +2,8 @@
 
 小黑盒 APP 小程序工坊的前端 SDK 与开发 CLI，用于创建、调试、构建和发布工坊小程序，并在业务页面中调用小黑盒开放能力。
 
+运行环境要求 Node.js `>=22.20.0`。`@heybox/hb-sdk` npm 包同时包含与当前 SDK 版本严格对应的 Agent Skill；Skill 不再依赖 Open 远端分发。
+
 SDK 只提供面向小程序开发者的稳定接口，不提供客户端内部协议、登录凭据或私有实现入口。本地浏览器调试请使用 `hb-sdk dev` 提供的 Mock 环境，发布前仍需在小黑盒 APP 中完成真机验收。
 
 宿主集成边界：`@heybox/hb-sdk-runtime` 运行在 iframe 外并负责 bridge/Host Port；跨 iframe 的 wire contract 唯一维护在零依赖 `@heybox/hb-sdk-protocol`。业务页面不需要创建 Runtime、实现 Host Port 或导入协议包；客户端 SDK 只依赖已兼容 re-export 的 `@heybox/hb-sdk/protocol`。
@@ -11,7 +13,7 @@ SDK 只提供面向小程序开发者的稳定接口，不提供客户端内部
 ### 创建新项目
 
 ```bash
-npx @heybox/hb-sdk@latest create my-miniapp
+npx @heybox/hb-sdk@alpha create my-miniapp
 cd my-miniapp
 npm install
 npm run dev
@@ -19,12 +21,32 @@ npm run dev
 
 脚手架已包含 SDK、Vite 配置和常用开发命令。浏览器调试通过后，再从调试台的二维码入口使用手机小黑盒 APP 验收。
 
+当前 `0.8` 模板位于 alpha 发布线；稳定版本发布后，创建命令会恢复使用 `@latest`。
+
 ### 接入已有项目
 
 ```bash
 npm install @heybox/hb-sdk
 ```
 
+### 安装 Agent Skill
+
+在项目目录安装到项目 Agent 目录：
+
+```bash
+hb-sdk skill install
+```
+
+安装到当前用户目录，或指定 Agent：
+
+```bash
+hb-sdk skill install --global
+hb-sdk skill install --agent codex cursor
+hb-sdk skill install --all-agents
+```
+
+使用 `hb-sdk doctor` 或 `hb-sdk doctor --json` 检查各 Agent 的 Skill 是否与当前 npm 包匹配；已有内容被修改时，使用 `--force` 才会覆盖。
+
 SDK 会在导入时启动握手，能力调用会自动等待 SDK 就绪。未开通网络权限的小程序通过 `user.getInfo()` 静默读取当前小程序内的隔离身份和公开资料：
 
 需要可信用户手势的按钮不能在点击回调里等待握手。页面加载时先用 `getHandshakeState()` 读取当前状态，再用 `onHandshakeStateChange()` 订阅并立即接收当前状态；仅在 `status === 'ready'` 时启用按钮，并在组件或页面销毁时调用订阅返回的取消函数。`ready` 生命周期事件只是握手成功瞬间派发、不会重放的边沿通知，不能用来判断当前状态。
@@ -192,7 +214,7 @@ SDK 还提供 `getHandshakeState()` / `onHandshakeStateChange()` 管理持久握
 
 ## 分享扩展数据
 
-默认分享和复制链接可以携带小程序自行定义的页面状态：
+`share.showShareMenu()` 的落地页固定为当前小程序的 `common_share`，不接受自定义 `url`。分享和复制链接可以携带小程序自行定义的页面状态：
 
 ```ts
 await hbSDK.share.showShareMenu({
@@ -250,6 +272,8 @@ hb-sdk remote deploy --release-note "本次更新说明"
 | `hb-sdk build`         | 执行生产构建与产物校验，不包含类型检查 |
 | `hb-sdk remote deploy` | 构建、上传并提交当前版本审核           |
 
+`hb-sdk create` 默认生成可直接删除的 Vanilla JavaScript + Vite HelloWorld，只保留 SDK Toast 示例、三端 Manifest 和开发/构建/部署命令，不绑定业务框架或项目内测试工具。
+
 `hb-sdk dev` 会启动 Vue 3 Browser Dev Host。左侧诊断面板集中展示调用日志、当前小程序作用域内的 Storage 快照和问题，右侧设备预览可在 iPhone 16 Pro Max（`440 x 956`）与 Pixel 9 Pro（`410 x 914`）间切换。切换预设只改变设备外框和 viewport，不会重新加载 iframe 或重启 Runtime；授权与操作弹窗、Toast、Loading 和振动反馈都限制在预览框内。
 
 浏览器调试入口不要求 CLI 登录或项目绑定；需要账号或远端配置的能力会按当前可用上下文返回结果或明确失败。调试台不提供权限修改入口，远端权限快照始终是 Runtime 的规范输入。手机验收统一从右上角二维码入口进入，选择手机可达的局域网网卡后扫码；二维码使用 `open_inapp` 与 `heybox://` `openWindow` 包装的短链。完整操作见 [CLI 指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cli)，实现与安全边界由 [Runtime Host 迁移](./docs/runtime-host-migration.md) 维护。

package/dist/cli-chunks/{build-CCLWgXyA.cjs → build-DkokKVNy.cjs}

@@ -5,8 +5,8 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
 var runtimeGate = require('./runtime-gate-DFjw66kF.cjs');
-var index = require('./index-BL5eEPap.cjs');
-var projectVite = require('./project-vite-Qu6Xe9Dn.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
+var projectVite = require('./project-vite-BIPrOtRO.cjs');
 require('node:async_hooks');
 require('node:module');
 require('path');

package/dist/cli-chunks/{context-Brh56h56.cjs → context-CKzZxKbF.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var session = require('./session-D-_N3WVL.cjs');
+var session = require('./session-B6Mo9eYW.cjs');
 var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
 var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');

package/dist/cli-chunks/{create-BZ-hi2s1.cjs → create-BQy5Jdmu.cjs}

@@ -5,7 +5,7 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var require$$0 = require('fs');
 var require$$1 = require('path');
-var index = require('./index-BL5eEPap.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
 require('node:module');
 require('os');
 require('readline');
@@ -1238,7 +1238,7 @@ function requireEjs () {
 
 var ejsExports = requireEjs();
 
-const TEMPLATE_NAME = 'vue3-vite-ts';
+const TEMPLATE_NAME = 'vanilla-vite-js';
 const TEMPLATE_ROOT_CANDIDATES = [
     path.resolve(__dirname, 'templates', TEMPLATE_NAME),
     path.resolve(__dirname, '..', 'templates', TEMPLATE_NAME),

package/dist/cli-chunks/{dev-CoSXtEYa.cjs → dev-Dik2zr5R.cjs}

@@ -8,15 +8,16 @@ var node_crypto = require('node:crypto');
 var promises = require('node:dns/promises');
 var node_http = require('node:http');
 var node_module = require('node:module');
-var context = require('./context-Brh56h56.cjs');
+var context = require('./context-CKzZxKbF.cjs');
 var undici = require('undici');
 var fs$1 = require('node:fs/promises');
-var index = require('./index-BL5eEPap.cjs');
+var index = require('./index-BwGBr1ZA.cjs');
 var require$$0$1 = require('crypto');
 var require$$0 = require('buffer');
-var session = require('./session-D-_N3WVL.cjs');
+var session = require('./session-B6Mo9eYW.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var projectVite = require('./project-vite-Qu6Xe9Dn.cjs');
+var projectVite = require('./project-vite-BIPrOtRO.cjs');
+var version = require('./version-DDB_btOG.cjs');
 var runtimePermissionEnv = require('./runtime-permission-env-CjsCe5bp.cjs');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -1604,7 +1605,7 @@ async function selectAvailablePort(options) {
         port: createPortCandidates(options.startPort, maxAttempts),
     });
     if (port < options.startPort || port >= options.startPort + maxAttempts) {
-        throw new Error(`无法找到可用 ${options.label} 端口，起始端口: ${options.startPort}`);
+        throw new Error(`无法找到可用端口（${options.label}），起始端口：${options.startPort}`);
     }
     return port;
 }
@@ -1850,8 +1851,8 @@ const DEFAULT_CHANNEL_TRANSPORT = {
 };
 const IPV4_LOOPBACK_ADDRESSES = new net.BlockList();
 IPV4_LOOPBACK_ADDRESSES.addSubnet('127.0.0.0', 8, 'ipv4');
-const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-CoSXtEYa.cjs', document.baseURI).href)))('ws');
-const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-CoSXtEYa.cjs', document.baseURI).href)))('parse5');
+const { WebSocket, WebSocketServer } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-Dik2zr5R.cjs', document.baseURI).href)))('ws');
+const { parse: parseHtml } = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/dev-Dik2zr5R.cjs', document.baseURI).href)))('parse5');
 const BROWSER_DEV_HOST_ROOT_CANDIDATES = [
     path.resolve(__dirname, 'devtools/browser-dev-host'),
     path.resolve(__dirname, '../devtools/browser-dev-host'),
@@ -2967,7 +2968,7 @@ async function listenHttpServer(server, options, getPortImpl, listen) {
         const port = await selectAvailablePort({
             getPort: getPortImpl,
             host: DEV_PORT_PROBE_HOST,
-            label: 'browser dev host',
+            label: '浏览器调试页服务',
             maxAttempts: lastCandidate - nextCandidate + 1,
             startPort: nextCandidate,
         });
@@ -2986,7 +2987,7 @@ async function listenHttpServer(server, options, getPortImpl, listen) {
             nextCandidate = port + 1;
         }
     }
-    throw lastAddressInUseError ?? new Error(`无法找到可用 browser dev host 端口，起始端口: ${options.port}`);
+    throw lastAddressInUseError ?? new Error(`无法找到可用浏览器调试页服务端口，起始端口：${options.port}`);
 }
 const listenBrowserDevHostServer = (server, options) => new Promise((resolve, reject) => {
     const onError = (error) => {
@@ -10894,7 +10895,7 @@ function assertNodeRuntimeCapabilities(ctx, settings) {
 function createNodeRealtimeDriverRegistry() {
     const registry = createRuntimeRealtimeDriverRegistry();
     registry.registerLazy('node-websocket', async () => {
-        const mod = await Promise.resolve().then(function () { return require('./index.esm-BoBHPfpq.cjs'); });
+        const mod = await Promise.resolve().then(function () { return require('./index.esm-BYifBABc.cjs'); });
         return mod.createNodeWebSocketRuntimeDriver();
     });
     return registry;
@@ -14954,17 +14955,12 @@ function writeLaunchResponse(response, status, body) {
     response.end(body ?? '');
 }
 
-/** 构建时替换为当前发布包的实际版本。 */
-const HB_SDK_VERSION = typeof undefined === 'string'
-    ? undefined
-    : '0.8.0-alpha.2';
-
 const DEFAULT_APP_PORT = 5173;
 const DEFAULT_BROWSER_DEV_HOST_PORT = 5174;
 const DEFAULT_DEV_CONTEXT_TIMEOUT_MS = 3000;
 const DEV_LISTEN_HOST = '0.0.0.0';
 const LOCAL_DEV_URL_HOST = '127.0.0.1';
-// Shared with Heybox H5 Vite plugins so hb-sdk can own the launch output.
+// 与 Heybox H5 Vite 插件共享，让 hb-sdk 统一管理启动输出。
 const MANAGED_DEV_OUTPUT_ENV = 'HEYBOX_DEV_SERVER_MANAGED_OUTPUT';
 const VITE_LOG_LEVEL = 'warn';
 async function runDevCommand(options, runtime = {}) {
@@ -14979,7 +14975,7 @@ async function runDevCommand(options, runtime = {}) {
     const appPort = await selectAvailablePort({
         getPort: getPortImpl,
         host: DEV_LISTEN_HOST,
-        label: 'Vite dev server',
+        label: 'Vite 开发服务器',
         startPort: options.port ?? DEFAULT_APP_PORT,
     });
     const resolvedOptions = {
@@ -14996,8 +14992,8 @@ async function runDevCommand(options, runtime = {}) {
         timeoutMs: runtime.devContextTimeoutMs ?? DEFAULT_DEV_CONTEXT_TIMEOUT_MS,
     });
     const launchRuntimePermissions = context.createBrowserDevRuntimePermissions(context.createBrowserDevPermissionState(devLaunchContext));
-    const vite = await logger.task('正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), { successText: '已加载项目 Vite' });
-    const appServer = await logger.task('正在创建 Vite dev server', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions)), runtime.env), runtime.env), { successText: '已创建 Vite dev server' });
+    const vite = await runDevStartupTask(logger, '正在加载项目 Vite', () => projectVite.loadProjectVite(projectRoot), '已加载项目 Vite');
+    const appServer = await runDevStartupTask(logger, '正在创建 Vite 开发服务器', () => runtimePermissionEnv.withMiniappPlatformCspEnv(context.shouldSkipMiniappPlatformCsp(devLaunchContext.runtimePermissions), () => withManagedDevOutputEnv(() => vite.createServer(createViteServerOptions(projectRoot, resolvedOptions)), runtime.env), runtime.env), '已创建 Vite 开发服务器');
     const mobileDevContextUrlsByOrigin = new Map();
     let currentLocalDevLaunchToken = devLaunchContext.localDevLaunchToken;
     appServer.middlewares.use((request, response, next) => {
@@ -15006,17 +15002,13 @@ async function runDevCommand(options, runtime = {}) {
             localDevLaunchToken: currentLocalDevLaunchToken,
             miniProgramId: devLaunchContext.miniProgramId,
             runtimePermissions: launchRuntimePermissions,
-            sdkVersion: HB_SDK_VERSION,
+            sdkVersion: version.HB_SDK_VERSION,
         }));
         if (!handled)
             next();
     });
-    await logger.task('正在启动 Vite dev server', () => appServer.listen(appPort), {
-        successText: 'Vite dev server 已启动',
-    });
-    const appUrl = await logger.task('正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), {
-        successText: '已确定小程序入口',
-    });
+    await runDevStartupTask(logger, '正在启动 Vite 开发服务器', () => appServer.listen(appPort), 'Vite 开发服务器已启动');
+    const appUrl = await runDevStartupTask(logger, '正在探测小程序入口', () => resolveViteAppUrl(appServer, resolvedOptions, fetchImpl), '已确定小程序入口');
     const buildLanAddresses = () => createLanAddressCandidates({
         appUrl,
         devContextUrlsByMiniUrlOrigin: mobileDevContextUrlsByOrigin,
@@ -15024,14 +15016,14 @@ async function runDevCommand(options, runtime = {}) {
         interfaces: networkInterfaceSnapshot,
         localDevLaunchToken: currentLocalDevLaunchToken,
         miniProgramId: devLaunchContext.miniProgramId,
-        sdkVersion: HB_SDK_VERSION,
+        sdkVersion: version.HB_SDK_VERSION,
         viteNetworkUrls: appServer.resolvedUrls?.network ?? [],
     });
     const lanAddresses = buildLanAddresses();
     const closers = [() => appServer.close()];
     let browserDevHost;
     try {
-        browserDevHost = await logger.task('正在启动 Browser Dev Host', () => startBrowserDevHostServer({
+        browserDevHost = await runDevStartupTask(logger, '正在启动浏览器调试页服务', () => startBrowserDevHostServer({
             appUrl,
             devContext: devLaunchContext,
             fetchImpl,
@@ -15052,7 +15044,7 @@ async function runDevCommand(options, runtime = {}) {
             root: runtime.browserDevHostRoot,
             rootCandidates: runtime.browserDevHostRootCandidates,
             runtimePermissions: devLaunchContext.runtimePermissions,
-        }), { successText: 'Browser Dev Host 已启动' });
+        }), '浏览器调试页服务已启动');
     }
     catch (error) {
         await closeAll(closers);
@@ -15083,23 +15075,29 @@ async function runDevCommand(options, runtime = {}) {
         });
         closers.push(tokenSession.close);
     }
-    logger.success('Browser Dev Host 已就绪');
-    logger.info(`Browser Dev Host: ${browserDevHost.url}`);
-    logger.info(`Mini program URL: ${appUrl}`);
-    logger.info('Mobile APP: scan the QR code in Browser Dev Host');
+    logger.success('本地调试已启动');
+    logger.info(`调试页：${browserDevHost.url}`);
+    logger.info(`小程序地址：${appUrl}`);
+    logger.info('手机调试：请在调试页扫码');
     if (options.open !== false) {
         logger.debug('正在打开浏览器调试页');
         void openUrl(browserDevHost.url);
     }
     installShutdownHandlers(closers, runtime.process ?? process);
 }
+function runDevStartupTask(logger, text, action, successText) {
+    if (!logger.verbose) {
+        return action();
+    }
+    return logger.task(text, () => action(), { successText });
+}
 async function loadDevLaunchContext(options) {
     const miniProgramId = await context.readBoundMiniProgramId(options.projectRoot);
     if (!miniProgramId) {
         throw new Error('hb-sdk dev 需要绑定小程序。请先运行 hb-sdk remote create 或 hb-sdk remote bind <mini-program-id>。');
     }
     try {
-        const { detail, miniProgramId: verifiedMiniProgramId } = await options.logger.task('正在读取远端小程序权限', () => loadRemoteDevContextWithTimeout({
+        const { detail, miniProgramId: verifiedMiniProgramId } = await runDevStartupTask(options.logger, '正在读取远端小程序权限', () => loadRemoteDevContextWithTimeout({
             fetchImpl: options.fetchImpl,
             load: (fetchImpl) => context.getBoundMiniProgram({
                 cwd: options.projectRoot,
@@ -15107,7 +15105,7 @@ async function loadDevLaunchContext(options) {
                 fetchImpl,
             }),
             timeoutMs: options.timeoutMs,
-        }), { successText: '已读取远端小程序权限' });
+        }), '已读取远端小程序权限');
         return {
             context: {
                 source: 'remote',
@@ -15307,25 +15305,30 @@ async function closeAll(closers) {
 function startLocalDevLaunchTokenSession(options) {
     let closed = false;
     let expirationTimer;
+    let hasReportedTokenFailure = false;
     let refreshTimer;
     const refresh = async () => {
         try {
             const issued = await issueLocalDevLaunchToken(options);
             if (closed)
                 return;
-            if (!issued) {
-                schedule(options.timeoutMs);
-                return;
-            }
             options.onToken(issued.token);
             const ttl = Math.max(0, issued.expiresAt - Date.now());
             scheduleExpiration(ttl);
             schedule(Math.max(1_000, Math.floor(ttl * 0.8)));
+            if (hasReportedTokenFailure) {
+                hasReportedTokenFailure = false;
+                options.logger.success('手机扫码调试已恢复');
+            }
         }
         catch (error) {
             if (closed)
                 return;
-            options.logger.warn(`刷新本地调试启动票失败，将自动重试：${index.readRedactedErrorMessage(error)}`);
+            if (!hasReportedTokenFailure) {
+                options.logger.warn('手机扫码调试凭证获取失败，将自动重试');
+            }
+            hasReportedTokenFailure = true;
+            options.logger.debug(`手机扫码调试凭证获取失败，详细原因：${index.readRedactedErrorMessage(error, { verbose: true })}`);
             schedule(options.timeoutMs);
         }
     };
@@ -15356,31 +15359,25 @@ function startLocalDevLaunchTokenSession(options) {
     };
 }
 async function issueLocalDevLaunchToken(options) {
-    try {
-        const issued = await loadRemoteDevContextWithTimeout({
-            fetchImpl: options.fetchImpl,
-            timeoutMs: options.timeoutMs,
-            load: (fetchImpl) => context.createLocalDevLaunchToken({
-                cwd: options.projectRoot,
-                env: options.env,
-                fetchImpl,
-                miniProgramId: options.miniProgramId,
-            }),
-        });
-        const token = typeof issued.token === 'string' ? issued.token.trim() : '';
-        if (!token) {
-            throw new Error('响应缺少 token');
-        }
-        const expiresAt = normalizeExpiresAt(issued.expires_at);
-        if (!expiresAt || expiresAt <= Date.now()) {
-            throw new Error('响应缺少有效 expires_at');
-        }
-        return { expiresAt, token };
+    const issued = await loadRemoteDevContextWithTimeout({
+        fetchImpl: options.fetchImpl,
+        timeoutMs: options.timeoutMs,
+        load: (fetchImpl) => context.createLocalDevLaunchToken({
+            cwd: options.projectRoot,
+            env: options.env,
+            fetchImpl,
+            miniProgramId: options.miniProgramId,
+        }),
+    });
+    const token = typeof issued.token === 'string' ? issued.token.trim() : '';
+    if (!token) {
+        throw new Error('响应缺少 token');
     }
-    catch (error) {
-        options.logger.warn(`未能签发本地调试启动票，扫码后公开详情可能仍拿不到未发布小程序身份：${index.readRedactedErrorMessage(error)}`);
-        return undefined;
+    const expiresAt = normalizeExpiresAt(issued.expires_at);
+    if (!expiresAt || expiresAt <= Date.now()) {
+        throw new Error('响应缺少有效 expires_at');
     }
+    return { expiresAt, token };
 }
 function normalizeExpiresAt(value) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)

package/dist/cli-chunks/doctor-Byr4uwKG.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+var fs = require('node:fs/promises');
+var os = require('node:os');
+var path = require('node:path');
+var index = require('./index-BwGBr1ZA.cjs');
+require('node:module');
+require('node:fs');
+require('path');
+require('os');
+require('readline');
+require('tty');
+require('assert');
+require('events');
+require('stream');
+require('buffer');
+require('util');
+
+const CANDIDATES = [path.resolve(__dirname, '..', 'package.json'), path.resolve(__dirname, '..', '..', 'package.json'), path.resolve(__dirname, '..', '..', '..', 'package.json')];
+const AGENTS = ['codex', 'claude', 'cursor'];
+async function runDoctorCommand(runtime = {}) {
+    const logger = runtime.logger ?? index.createCliLogger();
+    const result = await logger.task('正在检查本地 Agent Skill', () => getDoctorResult(runtime), { successText: 'Agent Skill 检查完成' });
+    if (runtime.json)
+        logger.raw(JSON.stringify(result));
+    else {
+        logger.section('Doctor');
+        logger.info(`SDK version: ${result.currentSdkVersion}`);
+        for (const a of result.agents)
+            logger.info(`${a.agent}: ${a.status}${a.skillVersion ? ` (${a.skillVersion})` : ''}`);
+        logger.info(`Status: ${result.status}`);
+        if (result.status !== 'OK')
+            logger.warn('请运行 hb-sdk skill install 安装或更新对应 Skill。');
+    }
+    return result;
+}
+async function getDoctorResult(runtime = {}) {
+    const version = await readVersion(runtime.packageJsonFiles);
+    const results = await Promise.all((runtime.agentNames ?? AGENTS).map(a => inspect(a, version, runtime)));
+    const status = results.every(a => a.status === 'OK') ? 'OK' : results.find(a => a.status !== 'OK').status;
+    return { currentSdkVersion: version, status, agents: results, localSkillJsonPath: results[0]?.path ?? '', localSkillVersion: results[0]?.skillVersion };
+}
+async function inspect(agent, version, runtime) {
+    const home = runtime.agentRoots?.[agent] ?? runtime.env?.[`${agent.toUpperCase()}_HOME`] ?? process.env[`${agent.toUpperCase()}_HOME`] ?? path.join(os.homedir(), `.${agent}`);
+    const file = path.join(home, 'skills', index.HB_SDK_SKILL_NAME, 'skill.json');
+    try {
+        const m = JSON.parse(await fs.readFile(file, 'utf8'));
+        const ok = m.name === index.HB_SDK_SKILL_NAME && m.sdk?.package === index.HB_SDK_PACKAGE_NAME && m.sdk?.version === version && m.distribution?.type === 'npm' && m.distribution?.package === index.HB_SDK_PACKAGE_NAME && m.distribution?.version === version && m.skillVersion?.startsWith(`${version}+skill.`);
+        return { agent, path: file, status: ok ? 'OK' : 'SKILL_OUTDATED', skillVersion: m.skillVersion };
+    }
+    catch {
+        return { agent, path: file, status: 'SKILL_MISSING' };
+    }
+}
+async function readVersion(files = CANDIDATES) { for (const file of files) {
+    try {
+        const m = JSON.parse(await fs.readFile(file, 'utf8'));
+        if (typeof m.version === 'string' && m.version)
+            return m.version;
+    }
+    catch { }
+} throw new Error(`未能读取 ${index.HB_SDK_PACKAGE_NAME} 当前版本号`); }
+
+exports.getDoctorResult = getDoctorResult;
+exports.runDoctorCommand = runDoctorCommand;

package/dist/cli-chunks/{index-BL5eEPap.cjs → index-BwGBr1ZA.cjs}

@@ -234,19 +234,19 @@ function requireArgument () {
 
 var command = {};
 
-const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BL5eEPap.cjs', document.baseURI).href)));
+const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BwGBr1ZA.cjs', document.baseURI).href)));
 function __require$4() { return require$5("node:events"); }
 
-const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BL5eEPap.cjs', document.baseURI).href)));
+const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BwGBr1ZA.cjs', document.baseURI).href)));
 function __require$3() { return require$4("node:child_process"); }
 
-const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BL5eEPap.cjs', document.baseURI).href)));
+const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BwGBr1ZA.cjs', document.baseURI).href)));
 function __require$2() { return require$3("node:path"); }
 
-const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BL5eEPap.cjs', document.baseURI).href)));
+const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BwGBr1ZA.cjs', document.baseURI).href)));
 function __require$1() { return require$2("node:fs"); }
 
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BL5eEPap.cjs', document.baseURI).href)));
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BwGBr1ZA.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -3883,10 +3883,6 @@ var envPaths = /*@__PURE__*/getDefaultExportFromCjs(envPathsExports);
 
 const HB_SDK_PACKAGE_NAME = '@heybox/hb-sdk';
 const HB_SDK_SKILL_NAME = 'hb-sdk';
-const HB_SDK_AGENT_SKILLS_BASE_URL = 'https://open.xiaoheihe.cn/agent-skills';
-const HB_SDK_SKILL_SOURCE = `${HB_SDK_AGENT_SKILLS_BASE_URL}/${HB_SDK_SKILL_NAME}`;
-const HB_SDK_SKILL_INDEX_URL = `${HB_SDK_AGENT_SKILLS_BASE_URL}/.well-known/agent-skills/index.json`;
-const HB_SDK_SKILL_INSTALL_COMMAND = `npx skills add ${HB_SDK_SKILL_SOURCE}`;
 
 var ora$1 = {exports: {}};
 
@@ -12837,6 +12833,7 @@ const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_TIMEOUT_MS = 1500;
 const UPDATE_CHECK_CACHE_FILE = 'update-check.json';
 const NPM_REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(HB_SDK_PACKAGE_NAME)}`;
+const PUBLIC_CHANGELOG_URL = 'https://docs.xiaoheihe.cn/hb_sdk/changelog/';
 const paths = envPaths('hb-sdk', { suffix: '' });
 const PACKAGE_JSON_CANDIDATES$1 = [
     path.resolve(__dirname, '..', 'package.json'),
@@ -12891,14 +12888,23 @@ async function getUpdateReminder(options = {}) {
     return createUpdateReminder(currentVersion, latestVersion);
 }
 function formatUpdateReminder(reminder) {
-    return `发现新版 ${HB_SDK_PACKAGE_NAME}: ${reminder.currentVersion} -> ${reminder.latestVersion}。升级命令: npm i -D ${HB_SDK_PACKAGE_NAME}@latest`;
+    const latestVersion = parseSemver(reminder.latestVersion);
+    const anchor = latestVersion
+        ? `v${latestVersion.major}-${latestVersion.minor}-${latestVersion.patch}`
+        : `v${reminder.latestVersion.replaceAll('.', '-')}`;
+    const changelogUrl = `${PUBLIC_CHANGELOG_URL}#${anchor}`;
+    return `发现新版 ${HB_SDK_PACKAGE_NAME}: ${reminder.currentVersion} -> ${reminder.latestVersion}。升级命令: npm i -D ${HB_SDK_PACKAGE_NAME}@latest；更新内容: ${changelogUrl}`;
 }
 function isVersionGreater(version, baseline) {
     const compared = compareSemver(version, baseline);
     return compared !== null && compared > 0;
 }
 function createUpdateReminder(currentVersion, latestVersion) {
-    if (!latestVersion || !isVersionGreater(latestVersion, currentVersion)) {
+    const parsedLatestVersion = latestVersion ? parseSemver(latestVersion) : null;
+    if (!latestVersion ||
+        !parsedLatestVersion ||
+        parsedLatestVersion.prerelease.length > 0 ||
+        !isVersionGreater(latestVersion, currentVersion)) {
         return null;
     }
     return {
@@ -13347,7 +13353,7 @@ function getPathname(pathWithQuery) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.8.0-alpha.2';
+const BUILT_CLI_VERSION = '0.8.0-alpha.9';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13412,6 +13418,7 @@ function createCliProgram(overrides = {}) {
         runDevCommand: defaultRunDevCommand,
         runDoctorCommand: defaultRunDoctorCommand,
         runRemoteCommand: defaultRunRemoteCommand,
+        runSkillInstallCommand: defaultRunSkillInstallCommand,
         ...overrides,
     };
     const program = new Command();
@@ -13432,10 +13439,11 @@ function createCliProgram(overrides = {}) {
     }, handlers.printUpdateReminder, resolveLogger));
     addVerboseOption(program
         .command('dev')
-        .description('启动当前小程序项目的 Vite dev server 和 Browser Dev Host')
-        .option('--port <port>', 'App dev server 端口', parsePositivePort)
-        .option('--browser-dev-host-port <port>', 'Browser Dev Host 端口', parsePositivePort)
-        .option('--no-open', '不自动打开浏览器调试页')).action(withUpdateReminder(async (options, command) => {
+        .description('启动当前小程序项目的 Vite 开发服务器和浏览器调试页服务')
+        .option('--port <port>', '小程序开发服务器端口', parsePositivePort)
+        .option('--browser-dev-host-port <port>', '浏览器调试页服务端口', parsePositivePort)
+        .option('--no-open', '不自动打开浏览器调试页')
+        .helpOption('-h, --help', '显示命令帮助')).action(withUpdateReminder(async (options, command) => {
         const logger = resolveLogger(command);
         await handlers.runDevCommand(options, { logger });
     }, handlers.printUpdateReminder, resolveLogger));
@@ -13451,9 +13459,20 @@ function createCliProgram(overrides = {}) {
         await handlers.runBuildCommand({}, { logger });
     });
     installRemoteCommands(program, handlers, resolveLogger);
-    addVerboseOption(program.command('doctor').description('诊断 hb-sdk 本地环境和 Agent Skill 版本')).action(async (...args) => {
-        const logger = resolveLogger(readCommandFromActionArgs(args));
-        const result = await handlers.runDoctorCommand({ logger });
+    const skill = addVerboseOption(program.command('skill').description('管理 Agent Skill'));
+    skill.command('install')
+        .option('--global', '安装到用户级 Agent 目录')
+        .option('--agent <agents...>', '指定 Agent')
+        .option('--all-agents', '安装到所有检测到的 Agent')
+        .option('--force', '覆盖已存在且被修改的 Skill')
+        .action(async (options, command) => {
+        const logger = resolveLogger(command);
+        await handlers.runSkillInstallCommand({ ...options, logger });
+    });
+    addVerboseOption(program.command('doctor').description('诊断 hb-sdk 本地环境和 Agent Skill 版本').option('--json', '以 JSON 格式输出诊断结果')).action(async (...args) => {
+        const command = readCommandFromActionArgs(args);
+        const logger = resolveLogger(command);
+        const result = await handlers.runDoctorCommand({ logger, json: Boolean(command?.opts().json) });
         if (result.status !== 'SDK_MISMATCH') {
             await handlers.printUpdateReminder({ logger });
         }
@@ -13682,35 +13701,39 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-CILLxGuf.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-Dr9lclu3.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-CILLxGuf.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-Dr9lclu3.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-CILLxGuf.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-Dr9lclu3.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunBuildCommand = async (...args) => {
-    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-CCLWgXyA.cjs'); });
+    const { runBuildCommand } = await Promise.resolve().then(function () { return require('./build-DkokKVNy.cjs'); });
     return runBuildCommand(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-BZ-hi2s1.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-BQy5Jdmu.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-CoSXtEYa.cjs'); }).then(function (n) { return n.dev; });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-Dik2zr5R.cjs'); }).then(function (n) { return n.dev; });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-EsCYJGhV.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-Byr4uwKG.cjs'); });
     return runDoctorCommand(...args);
 };
+const defaultRunSkillInstallCommand = async (...args) => {
+    const { runSkillInstallCommand } = await Promise.resolve().then(function () { return require('./skill-f90sxv28.cjs'); });
+    return runSkillInstallCommand(...args);
+};
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-DRuTQ51u.cjs'); });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-DXxyA14a.cjs'); });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {
@@ -13804,10 +13827,7 @@ function parseNonNegativeInteger(value) {
 
 exports.CliError = CliError;
 exports.HB_SDK_PACKAGE_NAME = HB_SDK_PACKAGE_NAME;
-exports.HB_SDK_SKILL_INDEX_URL = HB_SDK_SKILL_INDEX_URL;
-exports.HB_SDK_SKILL_INSTALL_COMMAND = HB_SDK_SKILL_INSTALL_COMMAND;
 exports.HB_SDK_SKILL_NAME = HB_SDK_SKILL_NAME;
-exports.HB_SDK_SKILL_SOURCE = HB_SDK_SKILL_SOURCE;
 exports.applyServiceTagIfNeeded = applyServiceTagIfNeeded;
 exports.commonjsGlobal = commonjsGlobal;
 exports.createCliLogger = createCliLogger;