@heybox/hb-sdk 0.8.0-alpha → 0.8.0-alpha.3

package/skill/scripts/check-references.mjs

@@ -1,14 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import process from 'node:process';
-
-const scriptPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'sync-references.mjs');
-const result = spawnSync(process.execPath, [scriptPath, '--check'], {
-  cwd: process.cwd(),
-  encoding: 'utf8',
-  stdio: 'inherit',
-});
-
-process.exit(result.status ?? 1);

package/skill/scripts/markdown-sections.mjs

@@ -1,36 +0,0 @@
-export function extractSection(markdown, heading) {
-  const lines = markdown.split('\n');
-  const start = lines.findIndex((line) => line.trim() === heading);
-  if (start === -1) return '';
-  const level = heading.match(/^#+/)?.[0].length ?? 2;
-  const out = [lines[start]];
-  let fenceChar = '';
-  for (let index = start + 1; index < lines.length; index += 1) {
-    const line = lines[index];
-    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
-
-    if (fenceChar) {
-      out.push(line);
-      if (fenceMatch?.[1]?.startsWith(fenceChar)) fenceChar = '';
-      continue;
-    }
-
-    if (fenceMatch) {
-      fenceChar = fenceMatch[1][0];
-      out.push(line);
-      continue;
-    }
-
-    const headingMatch = line.match(/^(#+)\s/);
-    if (headingMatch && headingMatch[1].length <= level) break;
-    out.push(line);
-  }
-  return out.join('\n').trimEnd();
-}
-
-export function replaceRequiredSection(markdown, heading, replacement) {
-  const section = extractSection(markdown, heading);
-  if (!section) throw new Error(`sync-references: 未找到待覆盖章节 ${heading}`);
-  const start = markdown.indexOf(section);
-  return `${markdown.slice(0, start)}${replacement.trimEnd()}${markdown.slice(start + section.length)}`;
-}

package/skill/scripts/package-skill.mjs

@@ -1,60 +0,0 @@
-#!/usr/bin/env node
-import { cpSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import process from 'node:process';
-import { HB_SDK_SKILL_NAME } from './skill-metadata.mjs';
-
-const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const skillDir = path.resolve(scriptDir, '..');
-const packageRoot = path.resolve(skillDir, '..');
-const skillName = HB_SDK_SKILL_NAME;
-const repoRoot = findRepoRoot(process.cwd()) ?? packageRoot;
-const zipPath = path.join(packageRoot, `${skillName}.zip`);
-
-function findRepoRoot(startDir) {
-  let dir = path.resolve(startDir);
-  while (true) {
-    if (existsSync(path.join(dir, 'package.json')) && existsSync(path.join(dir, 'packages/hb-sdk/package.json'))) {
-      return dir;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-
-if (!existsSync(path.join(skillDir, 'SKILL.md'))) {
-  console.error(`Missing ${path.relative(repoRoot, path.join(skillDir, 'SKILL.md'))}.`);
-  process.exit(1);
-}
-
-if (existsSync(zipPath)) rmSync(zipPath);
-
-const tempRoot = mkdtempSync(path.join(tmpdir(), 'hb-sdk-skill-'));
-const packagedSkillRoot = path.join(tempRoot, skillName);
-
-try {
-  cpSync(skillDir, packagedSkillRoot, { recursive: true });
-
-  const result = spawnSync(
-    'zip',
-    ['-r', zipPath, skillName, '-x', `${skillName}/README.md`, '-x', `${skillName}/**/.DS_Store`],
-    {
-      cwd: tempRoot,
-      encoding: 'utf8',
-    },
-  );
-
-  if (result.status !== 0) {
-    process.stderr.write(result.stderr || result.stdout);
-    process.exit(result.status ?? 1);
-  }
-
-  console.error(result.stdout.trim());
-  console.log(JSON.stringify({ ok: true, zip: path.relative(repoRoot, zipPath).split(path.sep).join('/') }));
-} finally {
-  rmSync(tempRoot, { recursive: true, force: true });
-}

package/skill/scripts/package-skill.sh

@@ -1,6 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-echo "Packaging hb-sdk skill" >&2
-node "$SCRIPT_DIR/package-skill.mjs"

package/skill/scripts/skill-metadata.mjs

@@ -1,77 +0,0 @@
-import { createHash } from 'node:crypto';
-
-export const HB_SDK_SKILL_NAME = 'hb-sdk';
-export const HB_SDK_PACKAGE_NAME = '@heybox/hb-sdk';
-export const HB_SDK_AGENT_SKILLS_BASE_URL = 'https://open.xiaoheihe.cn/agent-skills';
-export const HB_SDK_SKILL_SOURCE = `${HB_SDK_AGENT_SKILLS_BASE_URL}/${HB_SDK_SKILL_NAME}`;
-export const HB_SDK_SKILL_INDEX_URL = `${HB_SDK_AGENT_SKILLS_BASE_URL}/.well-known/agent-skills/index.json`;
-export const HB_SDK_SKILL_INSTALL_COMMAND = `npx skills add ${HB_SDK_SKILL_SOURCE}`;
-
-export function createSkillContentHash(fileEntries) {
-  const hash = createHash('sha256');
-
-  for (const entry of [...fileEntries].sort((left, right) => left.path.localeCompare(right.path))) {
-    hash.update(entry.path);
-    hash.update('\0');
-    hash.update(entry.content);
-    hash.update('\0');
-  }
-
-  return {
-    hex: hash.digest('hex'),
-  };
-}
-
-export function createSkillManifest({ contentHash, sdkVersion }) {
-  const shortHash = contentHash.hex.slice(0, 12);
-
-  return {
-    name: HB_SDK_SKILL_NAME,
-    skillVersion: `${sdkVersion}+skill.${shortHash}`,
-    sdk: {
-      package: HB_SDK_PACKAGE_NAME,
-      version: sdkVersion,
-      compatibility: sdkVersion,
-    },
-    source: HB_SDK_SKILL_SOURCE,
-    integrity: `sha256-${contentHash.hex}`,
-  };
-}
-
-export function validateSkillManifest({ manifest, sdkVersion }) {
-  const errors = [];
-
-  if (manifest?.name !== HB_SDK_SKILL_NAME) {
-    errors.push(`skill.json name must be \`${HB_SDK_SKILL_NAME}\`.`);
-  }
-
-  if (manifest?.sdk?.package !== HB_SDK_PACKAGE_NAME) {
-    errors.push(`skill.json sdk.package must be \`${HB_SDK_PACKAGE_NAME}\`.`);
-  }
-
-  if (manifest?.sdk?.version !== sdkVersion) {
-    errors.push('skill.json sdk.version must match packages/hb-sdk/package.json version.');
-  }
-
-  if (manifest?.sdk?.compatibility !== sdkVersion) {
-    errors.push('skill.json sdk.compatibility must match packages/hb-sdk/package.json version.');
-  }
-
-  if (typeof manifest?.skillVersion !== 'string' || !manifest.skillVersion.startsWith(`${sdkVersion}+skill.`)) {
-    errors.push('skill.json skillVersion must be derived from the current SDK version.');
-  }
-
-  if (manifest?.source !== HB_SDK_SKILL_SOURCE) {
-    errors.push('skill.json source must be the public hb-sdk skill URL.');
-  }
-
-  if (typeof manifest?.integrity !== 'string' || !/^sha256-[0-9a-f]{64}$/.test(manifest.integrity)) {
-    errors.push('skill.json integrity must be a sha256 hex digest.');
-  }
-
-  return errors;
-}
-
-export function normalizeSkillManifest(manifest) {
-  return `${JSON.stringify(manifest, null, 2)}\n`;
-}

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

@@ -1,359 +0,0 @@
-#!/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;
-  });
-}