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

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. `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`.
+13. 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`.
 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.
 
@@ -114,17 +114,16 @@ For host/runtime/protocol-maintenance code:
    - `cat packages/hb-sdk/DOC_SYNC_CHECKLIST.md`
 3. When preparing a package release, run `pnpm --filter @heybox/hb-sdk run release:prepare -- --bump patch` or `pnpm --filter @heybox/hb-sdk run release:prepare -- --version <x.y.z>`. The release assistant updates the Protocol/Runtime/SDK family versions, inserts `packages/hb-sdk/CHANGELOG.md`, and runs `check:changelog`. Use `--ai-command "<command>"` or `HB_SDK_CHANGELOG_AI_COMMAND` when an AI writer should rewrite the Conventional Commit draft. Review the entry for Mini-program developers and Host/Runtime integration maintainers, and do not expose Runtime internal adapter, state-machine, or security-policy details.
 4. When modifying this repo's source skill at `packages/hb-sdk/skill` and preparing distributable artifacts, also run:
-   - `node packages/hb-sdk/skill/scripts/package-skill.mjs`
+   - `node packages/hb-sdk/scripts/skill/sync-references.mjs`
+   - `node packages/hb-sdk/scripts/skill/validate-skill.mjs`
 5. When modifying CLI, local debugging, package exports, or package dependency direction, also run:
    - `pnpm --filter @heybox/hb-sdk run check:boundary`
    - `pnpm --filter @heybox/hb-sdk run test:unit`
-6. Inspect the generated zip before distribution:
-   - `unzip -l packages/hb-sdk/hb-sdk.zip | sed -n '1,120p'`
-7. When adding or modifying the deploy command or its upload pipeline, also run:
+6. When adding or modifying the deploy command or its upload pipeline, also run:
    - `pnpm --filter @heybox/hb-sdk run check:boundary`
    - `pnpm --filter @heybox/hb-sdk run test:unit`
    - Verify `dist/cli.cjs` does not have any `require('cos-nodejs-sdk-v5')` left after `build:cli`; the boundary check enforces this automatically.
-8. Verify the canonical payload before publishing:
-   - `pnpm exec hbexec hb-sdk sync`
-   - `pnpm exec hbexec hb-sdk check`
-   - For a release artifact, run `pnpm exec hbexec hb-sdk sync --out-dir <payload-dir>` and then `pnpm exec hbexec hb-sdk check-artifact --artifact-dir <payload-dir>`.
+7. Verify the canonical payload before publishing:
+   - `node packages/hb-sdk/scripts/skill/sync-references.mjs`
+   - `node packages/hb-sdk/scripts/skill/validate-skill.mjs`
+   - For a release artifact, run `npm pack --dry-run` and `node packages/hb-sdk/scripts/skill/verify-tarball-install.mjs`.

package/skill/references/api-protocol.md

@@ -1,6 +1,6 @@
 # Protocol API reference
 
-> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+> Generated by `node packages/hb-sdk/scripts/skill/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
 
 ## Sources
 
@@ -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=904f09f0012164f5d6b18c0f93477bb2bd541a41b99da8f270d0a40b93e96602 -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=2; fingerprint=336b8f72066321af3104fc51e5922f63eee5f3076c2e5c4d84384da7b9008032 -->
 
 ## SDK API
 

package/skill/references/api-root.md

@@ -1,6 +1,6 @@
 # Root API reference
 
-> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+> Generated by `node packages/hb-sdk/scripts/skill/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
 
 ## Sources
 
@@ -24,7 +24,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.8.0-alpha.2`
+- Version at generation time: `0.8.0-alpha.9`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -439,6 +439,8 @@ hb-sdk build [--env <name>] [--verbose]
 
 # 快速开始
 
+新项目可先运行 `hb-sdk create my-miniapp` 获得 Vanilla JavaScript + Vite HelloWorld；模板只演示 Toast，业务代码可以直接替换。
+
 如果页面不需要小黑盒开放能力，可以不接入 SDK。SDK 导入时会自动启动握手，能力调用会自动等待；业务只需根据小程序是否开通网络权限选择身份流程。
 
 ## 交互控件与握手状态

package/skill/references/cli.md

@@ -1,6 +1,6 @@
 # CLI reference
 
-> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+> Generated by `node packages/hb-sdk/scripts/skill/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
 
 ## Sources
 
@@ -40,7 +40,8 @@ hb-sdk build [--env <name>] [--verbose]
 hb-sdk login
 hb-sdk login status
 hb-sdk login clear
-hb-sdk doctor
+hb-sdk skill install [--global] [--agent <agent>] [--all-agents] [--force]
+hb-sdk doctor [--agent <agent>] [--all-agents] [--json]
 hb-sdk remote access
 hb-sdk remote entity list
 hb-sdk remote entity current
@@ -75,12 +76,16 @@ Top-level `hb-sdk deploy` has been hard-cut and must not be documented as a vali
 新项目可以直接从模板开始：
 
 ```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
 ```
 
+默认产物是 Vanilla JavaScript + Vite HelloWorld，只演示一次 `ui.showToast()` 调用，并预填 `android`、`ios`、`ohos` 三个平台。Demo 可以整体删除，项目不绑定 Vue、TypeScript 或测试框架。
+
+当前 `0.8` 模板位于 alpha 发布线；稳定版本发布后，本页会将创建命令切回 `@latest`。
+
 已有项目则在项目目录运行 `npm run dev` 或 `hb-sdk dev`。
 
 Agent rules:
@@ -102,6 +107,8 @@ hb-sdk dev
 
 CLI 会启动页面服务并自动打开 Vue 3 本地调试台。左侧集中放置调用日志、Storage 和问题三个诊断页签，右侧保持稳定的小程序内容与设备预览。
 
+默认终端只显示启动结果、调试页地址、小程序地址和手机调试入口。排查启动问题时使用 `hb-sdk dev --verbose` 查看完整启动阶段；手机扫码调试凭证连续重试失败时，默认只在失败和恢复两次状态变化时提示。
+
 <img src="/assets/browser-dev-host-workbench.png" alt="小程序工坊 Vue 3 调试台" style="width: 100%; max-width: 1120px;" />
 
 浏览器调试入口不要求 CLI 登录或项目绑定。没有账号、绑定小程序或远端 Dev Context 时，页面和基础 Browser Mock 仍可启动；依赖这些上下文的能力会返回明确失败。远端管理、部署和发布仍要求完成登录与绑定。
@@ -137,7 +144,7 @@ Browser Mock 会自动在实时与兼容链路间切换。手机调试使用 `op
 | 参数                             | 用途                             |
 | -------------------------------- | -------------------------------- |
 | `--port <port>`                  | 指定页面开发服务端口。           |
-| `--browser-dev-host-port <port>` | 指定 Browser Dev Host 端口。     |
+| `--browser-dev-host-port <port>` | 指定浏览器调试页服务端口。       |
 | `--no-open`                      | 启动后不自动打开浏览器。         |
 | `--verbose`                      | 出现问题时输出更详细的诊断信息。 |
 
@@ -272,8 +279,14 @@ Agent rules:
 
 Agent rules:
 
-- Use `hb-sdk doctor` for read-only diagnosis of local SDK, remote latest skill metadata, and local skill metadata.
-- Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
-- If doctor reports `SDK_MISMATCH`, tell the user to upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+- Use `hb-sdk doctor [--agent <agent>] [--all-agents] [--json]` for read-only diagnosis of the locally installed SDK and its bundled Skill.
+- Use `hb-sdk skill install` to install or refresh the Skill bundled with the matching npm package. Add `--global` for user scope, `--agent <agent>` for one Agent, or `--all-agents` for every supported Agent.
+- If doctor reports `SDK_MISMATCH`, upgrade the project dependency to the matching @heybox/hb-sdk version before reinstalling the skill.
 
 ## Update reminders
+
+## 版本提醒
+
+CLI 会从 npm 的 `latest` 标签检查稳定版更新，发现新版本时在命令结束后输出一行提醒，包含升级命令和目标版本的[更新日志](https://docs.xiaoheihe.cn/hb_sdk/changelog/)链接。提醒最多每 24 小时检查一次，请求超时或网络异常不会影响原命令；CI 环境默认不检查。
+
+需要临时关闭本地检查时，设置 `HB_SDK_NO_UPDATE_CHECK=1`。版本提醒不会读取 Alpha、Beta 或 RC 等预发布标签。

package/skill/references/examples.md

@@ -1,6 +1,6 @@
 # Smoke examples and anti-examples
 
-> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+> Generated by `node packages/hb-sdk/scripts/skill/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
 
 ## Sources
 

package/skill/references/llms-index.md

@@ -1,6 +1,6 @@
 # LLM documentation index
 
-> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+> Generated by `node packages/hb-sdk/scripts/skill/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
 
 ## Sources
 

package/skill/references/recipes.md

@@ -1,6 +1,6 @@
 # Recipes
 
-> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+> Generated by `node packages/hb-sdk/scripts/skill/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
 
 ## Sources
 
@@ -26,6 +26,8 @@
 
 # 快速开始
 
+新项目可先运行 `hb-sdk create my-miniapp` 获得 Vanilla JavaScript + Vite HelloWorld；模板只演示 Toast，业务代码可以直接替换。
+
 如果页面不需要小黑盒开放能力，可以不接入 SDK。SDK 导入时会自动启动握手，能力调用会自动等待；业务只需根据小程序是否开通网络权限选择身份流程。
 
 ## 交互控件与握手状态
@@ -523,7 +525,7 @@ async function handleSubmit() {
 
 ## 普通分享
 
-普通分享只支持一个默认分区，并且配置 `post` 时不要同时指定站外 `channel`。
+普通分享的落地页固定为当前小程序的 `common_share`，不接受自定义 `url`。普通分享只支持一个默认分区，并且配置 `post` 时不要同时指定站外 `channel`。
 
 ```ts
 import { share } from '@heybox/hb-sdk'
@@ -555,7 +557,7 @@ await share.screenshot({
 
 ## 恢复分享页面状态
 
-使用默认通用分享链接时，可以通过 `extra` 携带由小程序自行定义的页面状态。分享方只负责写入状态，接收方负责决定如何使用：
+通过固定通用分享链接分享时，可以使用 `extra` 携带由小程序自行定义的页面状态。分享方只负责写入状态，接收方负责决定如何使用：
 
 ```ts
 await share.showShareMenu({
@@ -588,7 +590,7 @@ if (sharedState && typeof sharedState === 'object' && !Array.isArray(sharedState
 }
 ```
 
-`getExtra()` 不依赖异步请求；没有有效数据时返回 `undefined`，业务应回退到默认首页。`extra` 只支持 JSON-compatible 数据，最多 8 层，单个数组或对象最多 64 项，内容不超过 128 字节；不能与自定义 `url` 同时使用，也不要存放 token、个人信息等敏感数据。`copyLink()` 不会继承当前启动链接中的 `extra`，只携带本次显式传入的数据。
+`getExtra()` 不依赖异步请求；没有有效数据时返回 `undefined`，业务应回退到默认首页。`extra` 只支持 JSON-compatible 数据，最多 8 层，单个数组或对象最多 64 项，内容不超过 128 字节，也不要存放 token、个人信息等敏感数据。`copyLink()` 不会继承当前启动链接中的 `extra`，只携带本次显式传入的数据。
 
 ## 参数边界
 

package/skill/references/safety-boundaries.md

@@ -1,6 +1,6 @@
 # Safety boundaries
 
-> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+> Generated by `node packages/hb-sdk/scripts/skill/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
 
 ## Sources
 

package/skill/skill.json

@@ -1,11 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.8.0-alpha.2+skill.417e5072238c",
+  "skillVersion": "0.8.0-alpha.9+skill.94bc5bff8aed",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.8.0-alpha.2",
-    "compatibility": "0.8.0-alpha.2"
+    "version": "0.8.0-alpha.9",
+    "compatibility": "0.8.0-alpha.9"
   },
-  "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-417e5072238c0b2a53836824d60639046935ad28ca337a63d82016421c97127b"
+  "distribution": {
+    "type": "npm",
+    "package": "@heybox/hb-sdk",
+    "version": "0.8.0-alpha.9",
+    "path": "skill"
+  },
+  "integrity": "sha256-94bc5bff8aed44fa6e6ca3066e8ccfc864b57631c64e76763717a36e5672f2df"
 }

package/types/modules/share/index.d.ts

@@ -43,7 +43,7 @@ export interface MiniProgramShareModule {
      */
     getExtra(): MiniProgramShareExtraValue | undefined;
     /**
-     * 展示基础分享面板。
+     * 展示以当前小程序通用分享页为落地页的基础分享面板。
      *
      * @since 0.2.0-alpha.0
      * @hbPlatform android

package/types/modules/share/show-share-menu.d.ts

@@ -6,7 +6,7 @@ export type ShowShareMenuPayload = MiniProgramShowShareMenuOptions;
 /** `share.showShareMenu` 返回值由客户端协议决定。 */
 export type ShowShareMenuResult = unknown;
 /**
- * 展示基础分享面板。
+ * 展示以当前小程序通用分享页为落地页的基础分享面板。
  *
  * @param requester - 底层 bridge 请求能力。
  * @param options - 基础分享参数。

package/types/modules/share/types.d.ts

@@ -25,16 +25,14 @@ export interface MiniProgramSharePostOptions {
  * 展示基础分享面板的配置。
  *
  * @remarks
- * 该配置只暴露基础分享字段，不暴露宿主内部上报、回调、自定义按钮等协议参数。
+ * 分享落地页固定为当前小程序的通用分享页。该配置只暴露基础分享字段，不暴露宿主内部上报、回调、自定义按钮等协议参数。
  */
 export interface MiniProgramShowShareMenuOptions {
     /** 分享标题。 */
     title: string;
     /** 分享描述。 */
     desc: string;
-    /** 分享落地页 URL；不传时由宿主 runtime 生成当前小程序的通用分享页。 */
-    url?: string;
-    /** 分享扩展数据；最多 8 层、单层最多 64 项、容量不超过 128 字节，且不能与 `url` 同时使用。 */
+    /** 分享扩展数据；最多 8 层、单层最多 64 项、容量不超过 128 字节。 */
     extra?: MiniProgramShareExtraValue;
     /** 分享缩略图 URL。 */
     imageUrl?: string;

package/types/skill-metadata.d.ts

@@ -1,6 +1,2 @@
 export declare const HB_SDK_PACKAGE_NAME = "@heybox/hb-sdk";
 export declare const HB_SDK_SKILL_NAME = "hb-sdk";
-export declare const HB_SDK_AGENT_SKILLS_BASE_URL = "https://open.xiaoheihe.cn/agent-skills";
-export declare const HB_SDK_SKILL_SOURCE = "https://open.xiaoheihe.cn/agent-skills/hb-sdk";
-export declare const HB_SDK_SKILL_INDEX_URL = "https://open.xiaoheihe.cn/agent-skills/.well-known/agent-skills/index.json";
-export declare const HB_SDK_SKILL_INSTALL_COMMAND = "npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk";

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

@@ -1,204 +0,0 @@
-'use strict';
-
-var fs$1 = require('node:fs');
-var fs = require('node:fs/promises');
-var os = require('node:os');
-var path = require('node:path');
-var index = require('./index-BL5eEPap.cjs');
-require('node:module');
-require('path');
-require('os');
-require('readline');
-require('tty');
-require('assert');
-require('events');
-require('stream');
-require('buffer');
-require('util');
-
-const DEFAULT_TIMEOUT_MS = 3000;
-const PACKAGE_JSON_CANDIDATES = [
-    path.resolve(__dirname, '..', 'package.json'),
-    path.resolve(__dirname, '..', '..', 'package.json'),
-    path.resolve(__dirname, '..', '..', '..', 'package.json'),
-];
-async function runDoctorCommand(runtime = {}) {
-    const logger = runtime.logger ?? index.createCliLogger();
-    const result = await logger.task('正在检查 Agent Skill 元数据', () => getDoctorResult(runtime), {
-        successText: 'Agent Skill 检查完成',
-    });
-    printDoctorResult(result, logger);
-    printDoctorNextStep(result, logger);
-    return result;
-}
-async function getDoctorResult(runtime = {}) {
-    const currentSdkVersion = await readCurrentSdkVersion(runtime.packageJsonFiles);
-    const localSkillJsonPath = await resolveLocalSkillJsonPath(runtime);
-    let remoteSkill;
-    try {
-        remoteSkill = await fetchRemoteSkill(runtime);
-    }
-    catch {
-        return {
-            currentSdkVersion,
-            localSkillJsonPath,
-            status: 'REMOTE_UNAVAILABLE',
-        };
-    }
-    if (remoteSkill?.sdk?.version !== currentSdkVersion) {
-        return {
-            currentSdkVersion,
-            localSkillJsonPath,
-            remoteSkill,
-            status: 'SDK_MISMATCH',
-        };
-    }
-    const localSkill = await readLocalSkillManifest(localSkillJsonPath);
-    if (!localSkill.exists) {
-        return {
-            currentSdkVersion,
-            localSkillJsonPath,
-            remoteSkill,
-            status: 'SKILL_MISSING',
-        };
-    }
-    if (!localSkill.manifest ||
-        localSkill.manifest.name !== index.HB_SDK_SKILL_NAME ||
-        localSkill.manifest.skillVersion !== remoteSkill.version ||
-        localSkill.manifest.sdk?.version !== remoteSkill.sdk?.version) {
-        return {
-            currentSdkVersion,
-            localSkillJsonPath,
-            localSkillVersion: localSkill.manifest?.skillVersion,
-            remoteSkill,
-            status: 'SKILL_OUTDATED',
-        };
-    }
-    return {
-        currentSdkVersion,
-        localSkillJsonPath,
-        localSkillVersion: localSkill.manifest.skillVersion,
-        remoteSkill,
-        status: 'OK',
-    };
-}
-function printDoctorResult(result, logger) {
-    logger.section('Doctor');
-    logger.info(`SDK version: ${result.currentSdkVersion}`);
-    logger.info(`Remote skill: ${result.remoteSkill?.version ? `${result.remoteSkill.version} (sdk ${result.remoteSkill.sdk?.version ?? 'unknown'})` : 'unavailable'}`);
-    logger.info(`Local skill: ${result.localSkillVersion ?? 'missing'}`);
-    logger.debug(`Local skill path: ${result.localSkillJsonPath}`);
-    logger.info(`Status: ${result.status}`);
-}
-function printDoctorNextStep(result, logger) {
-    if (result.status === 'OK') {
-        logger.success('Skill is up to date.');
-        return;
-    }
-    if (result.status === 'SDK_MISMATCH') {
-        logger.warn(`Current SDK does not match the latest skill metadata. Upgrade with: npm i -D ${index.HB_SDK_PACKAGE_NAME}@latest`);
-        logger.info(`Then install or refresh the skill manually: ${formatSkillInstallCommand(result)}`);
-        return;
-    }
-    if (result.status === 'REMOTE_UNAVAILABLE') {
-        logger.warn('Remote skill metadata is unavailable. Try again later.');
-        logger.info(`Manual install command: ${index.HB_SDK_SKILL_INSTALL_COMMAND}`);
-        return;
-    }
-    logger.info(`Install or refresh the skill manually: ${formatSkillInstallCommand(result)}`);
-}
-function formatSkillInstallCommand(result) {
-    return `npx skills add ${result.remoteSkill?.source || index.HB_SDK_SKILL_SOURCE}`;
-}
-async function fetchRemoteSkill(runtime) {
-    const fetchImpl = runtime.fetchImpl ?? fetch;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), runtime.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-    try {
-        const response = await fetchImpl(runtime.remoteIndexUrl ?? index.HB_SDK_SKILL_INDEX_URL, {
-            headers: {
-                accept: 'application/json',
-            },
-            signal: controller.signal,
-        });
-        if (!response.ok) {
-            throw new Error(`remote skill index returned ${response.status}`);
-        }
-        const index$1 = (await response.json());
-        const skill = index$1.skills?.find(item => item.name === index.HB_SDK_SKILL_NAME);
-        if (!skill?.version || skill.sdk?.package !== index.HB_SDK_PACKAGE_NAME || !skill.sdk.version) {
-            throw new Error('remote hb-sdk skill metadata is incomplete');
-        }
-        return skill;
-    }
-    finally {
-        clearTimeout(timeout);
-    }
-}
-async function readLocalSkillManifest(skillJsonPath) {
-    if (!(await pathExists(skillJsonPath))) {
-        return {
-            exists: false,
-        };
-    }
-    try {
-        return {
-            exists: true,
-            manifest: JSON.parse(await fs.readFile(skillJsonPath, 'utf8')),
-        };
-    }
-    catch {
-        return {
-            exists: true,
-        };
-    }
-}
-async function readCurrentSdkVersion(packageJsonCandidates = PACKAGE_JSON_CANDIDATES) {
-    for (const candidate of packageJsonCandidates) {
-        if (!(await pathExists(candidate))) {
-            continue;
-        }
-        const packageJson = JSON.parse(await fs.readFile(candidate, 'utf8'));
-        if (typeof packageJson.version === 'string' && packageJson.version) {
-            return packageJson.version;
-        }
-    }
-    throw new Error('未能读取 @heybox/hb-sdk 当前版本号');
-}
-async function resolveLocalSkillJsonPath(runtime) {
-    if (runtime.localSkillJsonPath) {
-        return runtime.localSkillJsonPath;
-    }
-    const projectSkillJsonPath = await findProjectSkillJsonPath(runtime.cwd ?? process.cwd());
-    if (projectSkillJsonPath) {
-        return projectSkillJsonPath;
-    }
-    const codexHome = runtime.codexHome ?? runtime.env?.CODEX_HOME ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
-    return path.join(codexHome, 'skills', index.HB_SDK_SKILL_NAME, 'skill.json');
-}
-async function findProjectSkillJsonPath(startDir) {
-    let current = path.resolve(startDir);
-    while (true) {
-        const skillJsonPath = path.join(current, '.agents', 'skills', index.HB_SDK_SKILL_NAME, 'skill.json');
-        if ((await pathExists(path.join(current, 'package.json'))) && (await pathExists(skillJsonPath))) {
-            return skillJsonPath;
-        }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            return undefined;
-        }
-        current = parent;
-    }
-}
-async function pathExists(filePath) {
-    try {
-        await fs.access(filePath, fs$1.constants.F_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-
-exports.getDoctorResult = getDoctorResult;
-exports.runDoctorCommand = runDoctorCommand;