@heybox/hb-sdk 0.5.9 → 0.5.10

package/dist/cli-chunks/{create-zJEmBOvP.cjs → create-D1W2pkHZ.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-BpVGoWHu.cjs');
+var index = require('./index-BBatNb1l.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-DsqPSgeJ.cjs → dev-DwbE-c1x.cjs}

@@ -9,7 +9,7 @@ var node_url = require('node:url');
 var net = require('node:net');
 var node_http = require('node:http');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-BpVGoWHu.cjs');
+var index = require('./index-BBatNb1l.cjs');
 require('node:process');
 require('node:buffer');
 require('node:util');

package/dist/cli-chunks/{doctor-DZkEwLT9.cjs → doctor-Bx71WFjM.cjs}

@@ -4,7 +4,7 @@ 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-BpVGoWHu.cjs');
+var index = require('./index-BBatNb1l.cjs');
 require('node:module');
 require('path');
 require('os');

package/dist/cli-chunks/{index-BpVGoWHu.cjs → index-BBatNb1l.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-BpVGoWHu.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-BBatNb1l.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-BpVGoWHu.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-BBatNb1l.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-BpVGoWHu.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-BBatNb1l.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-BpVGoWHu.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-BBatNb1l.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-BpVGoWHu.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-BBatNb1l.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13094,7 +13094,7 @@ function readErrorMessage(error, options = {}) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.5.9';
+const BUILT_CLI_VERSION = '0.5.10';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13374,31 +13374,31 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-DhKNZpl4.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-BX0YmVyi.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-DhKNZpl4.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-BX0YmVyi.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-DhKNZpl4.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-BX0YmVyi.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-zJEmBOvP.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-D1W2pkHZ.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DsqPSgeJ.cjs'); });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DwbE-c1x.cjs'); });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DZkEwLT9.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-Bx71WFjM.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-D0izsd5c.cjs'); }).then(function (n) { return n.remote; });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-YDmSxyYi.cjs'); }).then(function (n) { return n.remote; });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{index-CU-8dVKo.cjs → index-D5bZjpH9.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-BpVGoWHu.cjs');
+var index$2 = require('./index-BBatNb1l.cjs');
 var require$$0$2 = require('fs');
 var require$$2$1 = require('crypto');
 var require$$1$2 = require('path');
 var require$$0$3 = require('assert');
 var require$$4$2 = require('events');
 var require$$1$1 = require('util');
-var remote = require('./remote-D0izsd5c.cjs');
+var remote = require('./remote-YDmSxyYi.cjs');
 var require$$0$5 = require('net');
 var require$$0$4 = require('url');
 var require$$2$2 = require('http');

package/dist/cli-chunks/{login-DhKNZpl4.cjs → login-BX0YmVyi.cjs}

@@ -3,9 +3,9 @@
 var promises = require('node:readline/promises');
 var node_crypto = require('node:crypto');
 var node_http = require('node:http');
-var session = require('./session-O_NdH1Z2.cjs');
+var session = require('./session-BxZBXDZ-.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-BpVGoWHu.cjs');
+var index = require('./index-BBatNb1l.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{remote-D0izsd5c.cjs → remote-YDmSxyYi.cjs}

@@ -1,12 +1,12 @@
 'use strict';
 
 var promises = require('node:readline/promises');
-var session = require('./session-O_NdH1Z2.cjs');
+var session = require('./session-BxZBXDZ-.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
 var path = require('node:path');
-var index = require('./index-BpVGoWHu.cjs');
+var index = require('./index-BBatNb1l.cjs');
 
 var re = {exports: {}};
 
@@ -3111,7 +3111,7 @@ async function createDefaultCosClient(uploadToken) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-CU-8dVKo.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-D5bZjpH9.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {

package/dist/cli-chunks/{session-O_NdH1Z2.cjs → session-BxZBXDZ-.cjs}

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

package/dist/cli.cjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "",
   "exports": {
     ".": {
@@ -117,6 +117,8 @@
     "build:types": "tsc -p tsconfig.dts.json",
     "check:boundary": "node scripts/check-boundary.cjs",
     "check:docs-sync": "node scripts/check-docs-sync.cjs",
+    "sync:agent-skills-payload": "node skill/scripts/sync-agent-skills-payload.mjs",
+    "check:agent-skills-payload": "node skill/scripts/sync-agent-skills-payload.mjs --check",
     "clean": "rimraf ./dist && rimraf ./types",
     "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hb-sdk
-description: Uses @heybox/hb-sdk and its hb-sdk CLI for Heybox external mini-program iframe pages, local mock development, template creation, skill version checks, and host/runtime protocol integration. Use for ready/auth/user/share/viewport/storage/network APIs, lifecycle events, hb-sdk create/dev/login/doctor, mock runtime debugging, custom SDK instances, or @heybox/hb-sdk/protocol contracts. Don't use for raw postMessage bridge construction in app code, direct cookie/token access, internal Heybox client protocols, separate mock runtimes, or non-Heybox SDKs.
+description: Uses @heybox/hb-sdk and its hb-sdk CLI for Heybox external mini-program iframe pages, local mock development, template creation, skill version checks, host/runtime protocol integration, and mini-program listing/audit/compliance review. Use for ready/auth/user/share/viewport/storage/network APIs, lifecycle events, hb-sdk create/dev/login/doctor, mock runtime debugging, custom SDK instances, or @heybox/hb-sdk/protocol contracts. Don't use for raw postMessage bridge construction in app code, direct cookie/token access, internal Heybox client protocols, separate mock runtimes, or non-Heybox SDKs.
 ---
 
 # hb-sdk Agent Procedure
@@ -12,8 +12,9 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 1. If the task is iframe mini-program business code, use the root package import path `@heybox/hb-sdk`.
 2. If the task is parent-container runtime, bridge-server, protocol contract, or `@heybox/hb-sdk-runtime` work, use `@heybox/hb-sdk/protocol` only for shared constants and types.
 3. If the task is project scaffolding, local Vite startup, browser mock runtime, CLI login cache, Agent Skill version diagnosis, or CLI troubleshooting, use the `hb-sdk` CLI workflow.
-4. If the task asks for direct login-state extraction, cookies, tokens, raw Heybox client protocols, or internal hb-sdk package paths, refuse that approach and use the public SDK or CLI boundary instead.
-5. If the task is not about Heybox external mini-program SDK usage, CLI usage, mock runtime, or protocol contracts, do not apply this skill.
+4. If the task is reviewing a mini-program for submission, listing, audit, publishing, content compliance, data/privacy compliance, runtime quality, or icon/cover design requirements, use the online publishing rules workflow.
+5. If the task asks for direct login-state extraction, cookies, tokens, raw Heybox client protocols, or internal hb-sdk package paths, refuse that approach and use the public SDK or CLI boundary instead.
+6. If the task is not about Heybox external mini-program SDK usage, CLI usage, mock runtime, protocol contracts, or mini-program listing/audit/compliance review, do not apply this skill.
 
 ## Step 2: Load only the needed reference
 
@@ -26,6 +27,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 7. For generated documentation provenance and deeper API lookup paths, read `references/llms-index.md`.
 8. For smoke-test expectations, positive examples, and anti-examples, read `references/examples.md`.
 9. For evaluating whether another agent followed this skill, read `references/smoke-evaluation.md`.
+10. For mini-program listing/audit/compliance review, fetch the online rules Markdown from `https://open.xiaoheihe.cn/docs/hb_sdk/llms/guide/mini-program-publishing-rules.md`. Do not rely on a bundled `references/` copy of this document; if the URL is unavailable or returns the docs app shell instead of Markdown, report that the online rules are unavailable and do not complete the review from stale local text.
 
 ## Step 3: Follow import rules
 

package/skill/references/llms-index.md

@@ -35,6 +35,7 @@ This site documents the iframe-side SDK for external mini programs. For AI retri
 - [错误处理](./llms/guide/error-handling.md): SDK 对外抛出的标准错误类型是 `HbMiniProgramSDKError`。
 - [安装与运行环境](./llms/guide/installation.md): 如果工坊小程序只是普通展示页面，不调用黑盒开放能力，也不监听 SDK 生命周期事件，可以不安装、不引用、不初始化 `@heybox/hb-sdk`。父容器仍可能在 URL 上注入 `hb_mini_bridge_nonce`，业务页可以直接忽略。
 - [事件与生命周期](./llms/guide/lifecycle.md): SDK 通过 `on` 监听父容器派发的小程序生命周期和业务事件。
+- [小程序工坊上架规则 v2（试行）](./llms/guide/mini-program-publishing-rules.md): 本规则用于说明小程序工坊的小程序发布、上架和持续在线要求。通过审核不等于获得推荐或公开展示；工坊广场、推荐位、搜索等流量分发规则另行制定。
 - [快速开始](./llms/guide/quick-start.md): 如果页面不需要黑盒开放能力，可以不接入 SDK。这是一条需要用户能力时的最短接入路径：等待 SDK 完成握手，然后读取当前用户登录态。
 ## Recipes
 - [独立 SDK 实例](./llms/recipes/custom-instance.md): 大多数业务页使用默认单例即可。只有在需要隔离上下文时，再创建独立实例。

package/skill/scripts/sync-agent-skills-payload.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+import { Buffer } from 'node:buffer';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { HB_SDK_PACKAGE_NAME } from './skill-metadata.mjs';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const HB_SDK_ROOT = path.resolve(SCRIPT_DIR, '../..');
+const REPO_ROOT = path.resolve(HB_SDK_ROOT, '../..');
+const WELL_KNOWN_ROOT = path.join('.well-known', 'agent-skills');
+const AGENT_SKILL_PACKAGES = [
+  {
+    packageName: HB_SDK_PACKAGE_NAME,
+    skillDir: 'skill',
+  },
+];
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+const TEXT_FILE_RE = /\.(?:md|mjs|js|cjs|ts|tsx|json|txt|sh|yaml|yml)$/i;
+const PREFERRED_ORDER = new Map([
+  ['SKILL.md', 0],
+  ['skill.json', 1],
+  ['references/api-root.md', 100],
+  ['references/api-protocol.md', 101],
+  ['references/cli.md', 102],
+  ['references/recipes.md', 103],
+  ['references/safety-boundaries.md', 104],
+  ['references/llms-index.md', 105],
+  ['references/examples.md', 106],
+  ['references/smoke-evaluation.md', 107],
+  ['scripts/sync-references.mjs', 200],
+  ['scripts/check-references.mjs', 201],
+  ['scripts/validate-skill.mjs', 202],
+  ['scripts/package-skill.mjs', 203],
+  ['scripts/package-skill.sh', 204],
+]);
+
+function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  let outDir = path.resolve(process.cwd(), '.agent-skills-payload');
+  let check = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--check') {
+      check = true;
+      continue;
+    }
+    if (arg === '--out-dir') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error('--out-dir requires a path argument');
+      }
+      outDir = path.resolve(process.cwd(), value);
+      index += 1;
+    }
+  }
+
+  return { outDir, check };
+}
+
+function toPosixPath(value) {
+  return value.split(path.sep).join('/');
+}
+
+function assertSafeRelativePath(relativePath, context) {
+  const normalized = path.posix.normalize(relativePath);
+
+  if (path.isAbsolute(relativePath) || normalized.startsWith('../') || normalized === '..') {
+    throw new Error(`${context} has unsafe path: ${relativePath}`);
+  }
+
+  if (normalized !== relativePath) {
+    throw new Error(`${context} must be normalized: ${relativePath}`);
+  }
+
+  if (relativePath.includes('/../') || relativePath.endsWith('/..')) {
+    throw new Error(`${context} cannot contain parent traversal: ${relativePath}`);
+  }
+
+  if (/\.zip$/i.test(relativePath)) {
+    throw new Error(`${context} must not include zip archives: ${relativePath}`);
+  }
+}
+
+function parseFrontmatter(skillText, skillPath) {
+  const match = skillText.match(FRONTMATTER_RE);
+  if (!match) {
+    throw new Error(`${skillPath} is missing YAML frontmatter`);
+  }
+
+  const metadata = {};
+  for (const rawLine of match[1].split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#') || line.startsWith('metadata:')) {
+      continue;
+    }
+
+    const keyValue = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!keyValue) {
+      continue;
+    }
+
+    const [, key, rawValue] = keyValue;
+    metadata[key] = rawValue.replace(/^['"]|['"]$/g, '').trim();
+  }
+
+  return metadata;
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonFile(filePath) {
+  return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+
+async function resolvePackageRoot(packageSource) {
+  if (packageSource.packageName !== HB_SDK_PACKAGE_NAME) {
+    throw new Error(`Unsupported agent skill package: ${packageSource.packageName}`);
+  }
+
+  if (!(await exists(path.join(HB_SDK_ROOT, 'package.json')))) {
+    throw new Error(`Cannot resolve ${packageSource.packageName}: missing package root at ${toPosixPath(HB_SDK_ROOT)}`);
+  }
+
+  return HB_SDK_ROOT;
+}
+
+async function listFilesRecursive(rootDir, relativeBase = '', options = {}) {
+  if (!(await exists(rootDir))) {
+    return [];
+  }
+
+  const entries = await fs.readdir(rootDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (!options.includeHidden && entry.name.startsWith('.')) {
+      continue;
+    }
+
+    const absolutePath = path.join(rootDir, entry.name);
+    const relativePath = path.posix.join(relativeBase, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await listFilesRecursive(absolutePath, relativePath, options)));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(relativePath);
+    }
+  }
+
+  return files;
+}
+
+function sortSkillFiles(files) {
+  return [...files].sort((left, right) => {
+    const leftOrder = PREFERRED_ORDER.get(left) ?? 10_000;
+    const rightOrder = PREFERRED_ORDER.get(right) ?? 10_000;
+    return leftOrder - rightOrder || left.localeCompare(right);
+  });
+}
+
+async function discoverSkill(packageSource) {
+  const packageRoot = await resolvePackageRoot(packageSource);
+  const skillDir = path.join(packageRoot, packageSource.skillDir);
+  const skillMarkdownPath = path.join(skillDir, 'SKILL.md');
+
+  if (!(await exists(skillMarkdownPath))) {
+    throw new Error(`${packageSource.packageName} must provide ${packageSource.skillDir}/SKILL.md.`);
+  }
+
+  const skillMarkdown = await fs.readFile(skillMarkdownPath, 'utf8');
+  const frontmatter = parseFrontmatter(skillMarkdown, skillMarkdownPath);
+  const skillName = frontmatter.name;
+
+  if (!skillName) {
+    throw new Error(`${skillMarkdownPath} frontmatter must include name`);
+  }
+
+  if (!frontmatter.description) {
+    throw new Error(`${skillMarkdownPath} frontmatter must include description`);
+  }
+
+  const files = ['SKILL.md'];
+  const skillJsonPath = path.join(skillDir, 'skill.json');
+  let metadata = null;
+
+  if (await exists(skillJsonPath)) {
+    const relativeFile = 'skill.json';
+    assertSafeRelativePath(relativeFile, `${skillName} source file`);
+    files.push(relativeFile);
+    metadata = await readJsonFile(skillJsonPath);
+    if (metadata.name !== skillName) {
+      throw new Error(`${skillJsonPath} name (${metadata.name}) must match SKILL.md frontmatter (${skillName})`);
+    }
+  }
+
+  for (const topLevelDir of ['references', 'scripts', 'assets']) {
+    const nestedFiles = await listFilesRecursive(path.join(skillDir, topLevelDir), topLevelDir);
+    for (const relativeFile of nestedFiles) {
+      if (!TEXT_FILE_RE.test(relativeFile)) {
+        continue;
+      }
+      assertSafeRelativePath(relativeFile, `${skillName} source file`);
+      files.push(relativeFile);
+    }
+  }
+
+  return {
+    sourceDir: skillDir,
+    name: skillName,
+    description: frontmatter.description,
+    files: sortSkillFiles(files),
+    metadata,
+  };
+}
+
+async function discoverSkills() {
+  const skills = [];
+
+  for (const packageSource of AGENT_SKILL_PACKAGES) {
+    skills.push(await discoverSkill(packageSource));
+  }
+
+  if (skills.length === 0) {
+    throw new Error('No configured agent skills found.');
+  }
+
+  return skills;
+}
+
+export function createSkillIndex(skills) {
+  return {
+    skills: skills.map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+      ...(skill.metadata
+        ? {
+            version: skill.metadata.skillVersion,
+            sdk: skill.metadata.sdk,
+            source: skill.metadata.source,
+            integrity: skill.metadata.integrity,
+          }
+        : {}),
+      files: skill.files,
+    })),
+  };
+}
+
+async function addIndexFile(outputFiles, baseDir, skills) {
+  const indexPath = path.join(baseDir, WELL_KNOWN_ROOT, 'index.json');
+  const index = createSkillIndex(skills);
+
+  outputFiles.set(indexPath, Buffer.from(`${JSON.stringify(index, null, 2)}\n`, 'utf8'));
+}
+
+async function addSkillFiles(outputFiles, baseDir, skills) {
+  for (const skill of skills) {
+    for (const relativeFile of skill.files) {
+      assertSafeRelativePath(relativeFile, `${skill.name} generated file`);
+      const sourcePath = path.join(skill.sourceDir, ...relativeFile.split('/'));
+      const targetPath = path.join(baseDir, WELL_KNOWN_ROOT, skill.name, ...relativeFile.split('/'));
+      outputFiles.set(targetPath, await fs.readFile(sourcePath));
+    }
+  }
+}
+
+async function buildExpectedOutput(skills, targetRoot) {
+  const outputFiles = new Map();
+
+  await addIndexFile(outputFiles, targetRoot, skills);
+  await addSkillFiles(outputFiles, targetRoot, skills);
+
+  return outputFiles;
+}
+
+async function listExistingGeneratedFiles(targetRoot) {
+  if (!(await exists(targetRoot))) {
+    return [];
+  }
+
+  const relativeFiles = await listFilesRecursive(targetRoot, '', { includeHidden: true });
+  return relativeFiles.map((relativeFile) => path.join(targetRoot, ...relativeFile.split('/')));
+}
+
+async function syncFiles(expectedOutput, targetRoot) {
+  await fs.rm(targetRoot, { recursive: true, force: true });
+
+  for (const [targetPath, content] of [...expectedOutput.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content);
+  }
+}
+
+async function checkFiles(expectedOutput, targetRoot) {
+  const expectedPaths = new Set(expectedOutput.keys());
+  const existingPaths = new Set(await listExistingGeneratedFiles(targetRoot));
+  const problems = [];
+
+  for (const expectedPath of [...expectedPaths].sort()) {
+    if (!existingPaths.has(expectedPath)) {
+      problems.push(`missing ${path.relative(REPO_ROOT, expectedPath)}`);
+      continue;
+    }
+
+    const actual = await fs.readFile(expectedPath);
+    const expected = expectedOutput.get(expectedPath);
+    if (!actual.equals(expected)) {
+      problems.push(`stale ${path.relative(REPO_ROOT, expectedPath)}`);
+    }
+  }
+
+  for (const existingPath of [...existingPaths].sort()) {
+    if (!expectedPaths.has(existingPath)) {
+      problems.push(`extra ${path.relative(REPO_ROOT, existingPath)}`);
+    }
+  }
+
+  if (problems.length > 0) {
+    throw new Error(`Agent skills payload is out of sync:\n${problems.map((problem) => `- ${problem}`).join('\n')}`);
+  }
+}
+
+async function main() {
+  const { outDir, check } = parseCliArgs(process.argv);
+  const skills = await discoverSkills();
+  const expectedOutput = await buildExpectedOutput(skills, outDir);
+
+  if (check) {
+    await checkFiles(expectedOutput, outDir);
+    console.log(
+      `Agent skills payload is in sync at ${toPosixPath(path.relative(REPO_ROOT, outDir))} (${expectedOutput.size} files, ${skills.length} skills).`,
+    );
+    return;
+  }
+
+  await syncFiles(expectedOutput, outDir);
+  console.log(
+    `Synced ${skills.length} skills to ${toPosixPath(path.relative(REPO_ROOT, outDir))} (${expectedOutput.size} files).`,
+  );
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.5.9+skill.06627017a5ee",
+  "skillVersion": "0.5.9+skill.02be68ce07ce",
   "sdk": {
     "package": "@heybox/hb-sdk",
     "version": "0.5.9",
     "compatibility": "0.5.9"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-06627017a5ee6a42c9d684c5d498bd255857a256139547fc5683f9a0af269f9a"
+  "integrity": "sha256-02be68ce07ce1cf0ecba354d764a47977e4fc3c189b5e4aed3cee1f844fddfd4"
 }