@heybox/hb-sdk 0.7.5-alpha.0 → 0.8.0-alpha.10

package/dist/cli-chunks/{runtime-permission-env-D-8_jPG3.cjs → runtime-permission-env-CqsTHeas.cjs}

@@ -1,5 +1,8 @@
 'use strict';
 
+var fs = require('node:fs');
+var path = require('node:path');
+var version = require('./version-DN5jrixS.cjs');
 var node_async_hooks = require('node:async_hooks');
 
 var re = {exports: {}};
@@ -2787,6 +2790,285 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+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);
+
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(MINI_PROGRAM_PERMISSION_KEYS);
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord$2(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord$2(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const inputKey = rawEntry.key.trim();
+        const key = inputKey === 'network.request' ? 'network' : inputKey;
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled')) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key)) {
+            if (!isRecord$2(rawEntry.config))
+                return { valid: false, permissions: {} };
+            continue;
+        }
+        if (key === 'network') {
+            const config = rawEntry.config;
+            if (!isRecord$2(config) || typeof config.useOfficialDomain !== 'boolean') {
+                return { valid: false, permissions: {} };
+            }
+            permissions[key] = {
+                key,
+                status: rawEntry.status,
+                config: { useOfficialDomain: config.useOfficialDomain },
+            };
+            continue;
+        }
+        if (rawEntry.config !== null && rawEntry.config !== undefined && (!isRecord$2(rawEntry.config) || Object.keys(rawEntry.config).length > 0)) {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: {},
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord$2(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+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 composeMiniappRuntimePermissions(local, approvals) {
+    const parsedApprovals = parseMiniProgramRuntimePermissions(approvals);
+    const approvalRevision = isRecord$1(approvals) && Number.isInteger(approvals.revision) ? approvals.revision : undefined;
+    const views = [];
+    const entries = [];
+    for (const definition of MINI_PROGRAM_PERMISSION_CATALOG) {
+        const declaration = local.permissions?.[definition.key];
+        const declared = !local.declared || declaration?.enabled === true;
+        if (definition.access === 'declaration') {
+            views.push({ key: definition.key, access: definition.access, declared, approved: null, effective: declared });
+            if (declared)
+                entries.push({ key: definition.key, status: 'enabled', config: {} });
+            continue;
+        }
+        const approval = parsedApprovals.valid ? parsedApprovals.permissions[definition.key] : undefined;
+        const approved = approval?.status === 'enabled';
+        const requestedOfficialDomain = declaration?.enabled === true && 'useOfficialDomain' in declaration && declaration.useOfficialDomain;
+        const approvedOfficialDomain = approval?.config.useOfficialDomain === true;
+        const effective = declared && approved;
+        const effectiveOfficialDomain = effective && (local.declared ? requestedOfficialDomain : true) && approvedOfficialDomain;
+        views.push({
+            key: definition.key,
+            access: definition.access,
+            declared,
+            approved,
+            requestedConfig: { useOfficialDomain: requestedOfficialDomain },
+            approvedConfig: { useOfficialDomain: approvedOfficialDomain },
+            effective,
+            effectiveConfig: { useOfficialDomain: effectiveOfficialDomain },
+        });
+        if (declared) {
+            entries.push({ key: definition.key, status: effective ? 'enabled' : 'disabled', config: { useOfficialDomain: effectiveOfficialDomain } });
+        }
+    }
+    return {
+        runtimePermissions: { schema_version: 1, ...(approvalRevision === undefined ? {} : { revision: approvalRevision }), entries },
+        views,
+    };
+}
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 const MINIAPP_UPLOAD_SCOPE = 'activity';
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 const MINIAPP_UPLOAD_BATCH_SIZE = 50;
@@ -2869,7 +3151,7 @@ function shouldUploadDistFile(relativePath) {
 /**
  * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
  *
- * @param files 待处理的构建产物文件。
+ * @param files - 待处理的构建产物文件。
  * @returns 保留输入附加字段的有序文件列表。
  * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
  */
@@ -2878,7 +3160,7 @@ function prepareMiniappArtifactFiles(files) {
         throw new Error('构建产物文件数量超出签名协议上限');
     }
     const usedPaths = new Set();
-    const prepared = files.map(file => {
+    const prepared = files.map((file) => {
         const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
         if (usedPaths.has(relativePath)) {
             throw new Error(`构建产物包含重复文件路径：${relativePath}`);
@@ -2892,15 +3174,15 @@ function prepareMiniappArtifactFiles(files) {
 /**
  * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
  *
- * @param files 待上传的构建产物文件。
- * @param options 小程序和长度限制配置。
+ * @param files - 待上传的构建产物文件。
+ * @param options - 小程序和长度限制配置。
  * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
  */
 function validateMiniappUploadPathLengths(files, options) {
     const maxLength = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
     const prefix = `/u/${getMiniProgramUploadAlias(options.miniProgramId)}/${'x'.repeat(MINIAPP_UPLOAD_SESSION_REF_LENGTH)}/`;
     const prefixLength = textEncoder.encode(prefix).length;
-    const tooLongFile = files.find(file => {
+    const tooLongFile = files.find((file) => {
         const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
         return prefixLength + textEncoder.encode(relativePath).length > maxLength;
     });
@@ -2909,7 +3191,7 @@ function validateMiniappUploadPathLengths(files, options) {
 /**
  * 创建 v1 整包签名头。
  *
- * @param fileCount 参与签名的文件数量。
+ * @param fileCount - 参与签名的文件数量。
  * @returns 包含协议标识和文件数量的字节数组。
  * @throws 文件数量超出协议范围时抛出错误。
  */
@@ -2922,7 +3204,7 @@ function createMiniappArtifactSignatureHeader(fileCount) {
 /**
  * 创建单个文件的 v1 framing header。
  *
- * @param file 已规范化或待校验的构建产物文件。
+ * @param file - 已规范化或待校验的构建产物文件。
  * @returns 包含路径长度、路径和文件大小的字节数组。
  * @throws 文件路径或大小非法时抛出错误。
  */
@@ -2935,9 +3217,9 @@ function createMiniappArtifactFileHeader(file) {
 /**
  * 校验服务端 session 文件映射，并计算仍需上传的文件。
  *
- * @param localFiles 本地构建产物文件。
- * @param serverFiles 服务端签发的文件映射。
- * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @param localFiles - 本地构建产物文件。
+ * @param serverFiles - 服务端签发的文件映射。
+ * @param uploadedKeys - 服务端已确认上传成功的 key。
  * @returns 完整映射、待上传文件和已确认 key。
  * @throws 服务端映射与本地产物不一致时抛出错误。
  */
@@ -2969,7 +3251,7 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         serverSizes.set(relativePath, size);
         knownKeys.add(key);
     }
-    const files = preparedFiles.map(file => {
+    const files = preparedFiles.map((file) => {
         const key = mappings.get(file.relativePath);
         if (!key) {
             throw new Error(`上传会话缺少文件映射：${file.relativePath}`);
@@ -2989,7 +3271,7 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
     }
     return {
         files,
-        missingFiles: files.filter(file => !completed.has(file.key)),
+        missingFiles: files.filter((file) => !completed.has(file.key)),
         uploadedKeys: [...completed],
     };
 }
@@ -3007,7 +3289,7 @@ function normalizeMiniappArtifactRelativePath(relativePath) {
     if (containsControlCharacter(value) || UNPAIRED_SURROGATE_PATTERN.test(value)) {
         throw new Error(`构建产物路径包含非法字符：${value}`);
     }
-    if (value.split('/').some(segment => !segment || segment === '.' || segment === '..')) {
+    if (value.split('/').some((segment) => !segment || segment === '.' || segment === '..')) {
         throw new Error(`构建产物路径包含非法目录段：${value}`);
     }
     if (value.includes(',')) {
@@ -3063,6 +3345,68 @@ function compareBytes(left, right) {
     return left.length - right.length;
 }
 
+function findNearestPackageJsonPath(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const packageJsonPath = path.join(current, 'package.json');
+        if (fs.existsSync(packageJsonPath)) {
+            return packageJsonPath;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return path.join(path.resolve(startDir), 'package.json');
+        }
+        current = parent;
+    }
+}
+function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
+    const { packageJson } = readMiniappPackageJson(root);
+    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 resolveMiniappSdkVersion() {
+    if (!version.HB_SDK_VERSION.startsWith('__HB_SDK_'))
+        return version.HB_SDK_VERSION;
+    const packageJson = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', 'package.json'), 'utf8'));
+    if (typeof packageJson.version !== 'string' || !packageJson.version)
+        throw new Error('未能读取 @heybox/hb-sdk 当前版本号');
+    return packageJson.version;
+}
+function readMiniappPackageJson(root, requireVersion) {
+    const packageJsonPath = findNearestPackageJsonPath(root);
+    let content;
+    try {
+        content = fs.readFileSync(packageJsonPath, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 读取 package.json 失败：${formatReason(error)}`);
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`@heybox/hb-sdk 解析 package.json 失败：${formatReason(error)}`);
+    }
+    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) {
+        return error.message;
+    }
+    return String(error);
+}
+
 const HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV = 'HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN';
 const HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV = 'HB_SDK_RUNTIME_PERMISSION_CONTEXT';
 const VERIFIED_RUNTIME_PERMISSION_CONTEXT = 'verified';
@@ -3142,6 +3486,7 @@ exports.LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH = LIST_USER_MINIPROGRAM_LEADE
 exports.LIST_USER_MINIPROGRAM_VERSION_API_PATH = LIST_USER_MINIPROGRAM_VERSION_API_PATH;
 exports.MINIAPP_UPLOAD_BATCH_SIZE = MINIAPP_UPLOAD_BATCH_SIZE;
 exports.MINIAPP_UPLOAD_SCOPE = MINIAPP_UPLOAD_SCOPE;
+exports.MINI_PROGRAM_PERMISSION_KEYS = MINI_PROGRAM_PERMISSION_KEYS;
 exports.PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH = PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH;
 exports.RELEASE_USER_MINIPROGRAM_VERSION_API_PATH = RELEASE_USER_MINIPROGRAM_VERSION_API_PATH;
 exports.REOPEN_USER_MINIPROGRAM_API_PATH = REOPEN_USER_MINIPROGRAM_API_PATH;
@@ -3153,13 +3498,19 @@ exports.USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = USER_MINIPROGRAM_ACCESS_STATUS
 exports.USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH;
 exports.USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH = USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH;
 exports.WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH = WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH;
+exports.composeMiniappRuntimePermissions = composeMiniappRuntimePermissions;
 exports.createMiniappArtifactFileHeader = createMiniappArtifactFileHeader;
 exports.createMiniappArtifactSignatureHeader = createMiniappArtifactSignatureHeader;
 exports.createMiniappPlatformCspEnv = createMiniappPlatformCspEnv;
+exports.getMissingPermissionsWarning = getMissingPermissionsWarning;
 exports.normalizeRelativePath = normalizeRelativePath;
+exports.parseMiniProgramRuntimePermissions = parseMiniProgramRuntimePermissions;
+exports.parseMiniappPermissions = parseMiniappPermissions;
 exports.prepareMiniappArtifactFiles = prepareMiniappArtifactFiles;
+exports.readMiniappPermissionsFromPackageJson = readMiniappPermissionsFromPackageJson;
 exports.relativePathContainsNodeModulesSegment = relativePathContainsNodeModulesSegment;
 exports.requireSemver = requireSemver;
+exports.resolveMiniappSdkVersion = resolveMiniappSdkVersion;
 exports.resolveMiniappUploadSessionFiles = resolveMiniappUploadSessionFiles;
 exports.semverExports = semverExports;
 exports.shouldSkipMiniappPlatformCspFromEnv = shouldSkipMiniappPlatformCspFromEnv;

package/dist/cli-chunks/{session-CJS_SEp9.cjs → session-CnGeZCRZ.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-C9mpajVG.cjs');
+var index = require('./index-BDaeBI_B.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');

package/dist/cli-chunks/skill-B0yAnPOJ.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+var path = require('node:path');
+var version = require('./version-DN5jrixS.cjs');
+var childProcess = require('node:child_process');
+var fs = require('node:fs/promises');
+var index = require('./index-BDaeBI_B.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');
+
+function installSkill(options) {
+    const binary = require.resolve('skills/bin/cli.mjs');
+    const args = ['add', path.join(options.packageRoot, 'skill'), '--copy'];
+    if (options.global)
+        args.push('--global');
+    if (options.allAgents)
+        args.push('--agent', '*');
+    else if (options.agents?.length)
+        args.push('--agent', ...options.agents);
+    if (options.force)
+        args.push('--force');
+    const env = { ...process.env, ...options.env, DISABLE_TELEMETRY: '1', DO_NOT_TRACK: '1' };
+    const run = options.spawnImpl ?? childProcess.spawn;
+    return new Promise((resolve, reject) => {
+        const child = run(process.execPath, [binary, ...args], { cwd: options.cwd, env, stdio: 'inherit' });
+        child.on('error', reject);
+        child.on('close', (code) => resolve({ code: code ?? 1 }));
+    });
+}
+
+async function findProjectPackageJson(cwd = process.cwd()) {
+    let current = path.resolve(cwd);
+    while (true) {
+        const candidate = path.join(current, 'package.json');
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch { /* continue */ }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+async function verifyProjectSdk(cwd, version) {
+    const file = await findProjectPackageJson(cwd);
+    if (!file)
+        throw new Error('未找到项目 package.json，请在项目目录执行');
+    const pkg = JSON.parse(await fs.readFile(file, 'utf8'));
+    const declared = pkg.dependencies?.['@heybox/hb-sdk'] ?? pkg.devDependencies?.['@heybox/hb-sdk'];
+    if (!declared)
+        throw new Error('项目缺少 @heybox/hb-sdk 依赖');
+    if (declared !== version && !String(declared).includes(version)) {
+        throw new Error(`项目 @heybox/hb-sdk 版本 ${declared} 与 CLI ${version} 不一致`);
+    }
+}
+
+async function runSkillInstallCommand(options = {}) {
+    if (options.agent?.length && options.allAgents)
+        throw new Error('--agent 与 --all-agents 互斥');
+    const logger = options.logger ?? index.createCliLogger();
+    const packageRoot = options.packageRoot ?? path.resolve(__dirname, '../../..');
+    const cwd = options.cwd ?? process.cwd();
+    if (!options.global)
+        await verifyProjectSdk(cwd, version.HB_SDK_VERSION);
+    const result = await installSkill({ packageRoot, cwd, global: options.global, agents: options.agent, allAgents: options.allAgents, force: options.force });
+    if (result.code !== 0)
+        throw new Error(`Skill 安装失败（退出码 ${result.code}）`);
+    logger.success('hb-sdk Skill 安装完成');
+    return result;
+}
+
+exports.runSkillInstallCommand = runSkillInstallCommand;

package/dist/cli-chunks/version-DN5jrixS.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+/** 构建时替换为当前发布包的实际版本。 */
+const HB_SDK_VERSION = typeof undefined === 'string'
+    ? undefined
+    : '0.8.0-alpha.10';
+
+exports.HB_SDK_VERSION = HB_SDK_VERSION;

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./cli-chunks/index-C9mpajVG.cjs');
+var index = require('./cli-chunks/index-BDaeBI_B.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');