@xiashe/skill 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @xiashe/skill
+
+Creator-facing XiaShe Skill registry helper.
+
+This package is intentionally separate from the full `@xiashe/cli` product CLI and from `@xiashe/agent-skill`, which is the runtime feed helper for external Agents.
+
+## Purpose
+
+`xiashe-skill` helps creators prepare a Skill folder for third-party Skill hubs:
+
+- inspect a local Skill project
+- write an explicit `xiashe.skill.json` registry manifest
+- copy a clean package directory
+- generate an upload prompt that the creator can hand to an Agent
+
+It does not install background services, run postinstall hooks, read secrets, or upload to third-party hubs.
+
+## Local development
+
+```bash
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs --help
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs inspect .
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs attach . --code XS-XXXX-XXXX
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs attach . --public-token pub_xxx --skill-id sk_xxx
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs pack . --out .xiashe/package
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs prompt . --hub red --package-url https://example.com/my-skill.zip
+```

package/bin/xiashe-skill.mjs

@@ -0,0 +1,475 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const VERSION = '0.1.0';
+const COMMAND_NAME = process.env.XIASHE_SKILL_CLI_NAME || 'xiashe-skill';
+const PRODUCT_NAME = process.env.XIASHE_SKILL_PRODUCT_NAME || (COMMAND_NAME === 'agentpie-skill' ? 'AgentPie' : 'XiaShe');
+const REGISTRY_PROVIDER = process.env.XIASHE_SKILL_REGISTRY_PROVIDER || (COMMAND_NAME === 'agentpie-skill' ? 'agentpie' : 'xiashe');
+const DEFAULT_BASE_URL = process.env.XIASHE_SKILL_DEFAULT_BASE_URL || (COMMAND_NAME === 'agentpie-skill'
+  ? 'https://api.agentpie.app'
+  : 'https://api.xiashe.chat');
+const MANIFEST_FILE = process.env.XIASHE_SKILL_MANIFEST_FILE || (COMMAND_NAME === 'agentpie-skill'
+  ? 'agentpie.skill.json'
+  : 'xiashe.skill.json');
+const WORK_DIR = process.env.XIASHE_SKILL_WORK_DIR || (COMMAND_NAME === 'agentpie-skill' ? '.agentpie' : '.xiashe');
+const DEFAULT_REGISTRY_URL = process.env.XIASHE_SKILL_REGISTRY_URL || `${DEFAULT_BASE_URL}/registry/skill-events`;
+const DEFAULT_CLAIM_URL = process.env.XIASHE_SKILL_CLAIM_URL || `${DEFAULT_BASE_URL}/registry/skill/claim`;
+const DEFAULT_IGNORE = new Set([
+  '.git',
+  '.xiashe',
+  '.agentpie',
+  'node_modules',
+  '.DS_Store',
+  '.env',
+  '.env.local',
+  '.env.production',
+  '.env.development',
+  'dist',
+  'build',
+  'coverage'
+]);
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_PACKAGE_BYTES = 30 * 1024 * 1024;
+
+function usage() {
+  return `${COMMAND_NAME} ${VERSION}
+
+Usage:
+  ${COMMAND_NAME} inspect [skill-dir] [--json]
+  ${COMMAND_NAME} attach [skill-dir] --code <dynamic-code> [--name <name>]
+  ${COMMAND_NAME} attach [skill-dir] --public-token <token> [--skill-id <id>] [--name <name>]
+  ${COMMAND_NAME} pack [skill-dir] [--out <dir>] [--dry-run] [--json]
+  ${COMMAND_NAME} prompt [skill-dir] --hub <red|generic> [--package-url <url>] [--out <file>]
+
+Options:
+  --public-token <token>      Public write token issued by ${PRODUCT_NAME} registry.
+  --code <dynamic-code>       One-time ${PRODUCT_NAME} dashboard code used to claim registry identity.
+  --claim-url <url>           Code claim endpoint. Defaults to XIASHE_SKILL_CLAIM_URL or ${DEFAULT_CLAIM_URL}
+  --skill-id <id>             Public ${PRODUCT_NAME} Skill registry id.
+  --registry-url <url>        Event endpoint written to the manifest.
+  --name <name>               Skill display name override.
+  --description <text>        Skill description override.
+  --hub <red|generic>         Target Skill hub prompt style.
+  --package-url <url>         URL an Agent can use when uploading by URL.
+  --out <path>                Output package directory or prompt file.
+  --dry-run                   Print planned files without writing package files.
+  --json                      Print machine-readable JSON.
+  --help                      Show help.
+  --version                   Show version.
+`;
+}
+
+function fail(message, code = 1) {
+  console.error(message);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const args = { _: [], json: false, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    if (value === '--help' || value === '-h') {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (value === '--version' || value === '-v') {
+      console.log(VERSION);
+      process.exit(0);
+    }
+    if (value === '--json') {
+      args.json = true;
+      continue;
+    }
+    if (value === '--dry-run') {
+      args.dryRun = true;
+      continue;
+    }
+    if (value.startsWith('--')) {
+      const key = value.slice(2);
+      const next = argv[i + 1];
+      if (!next || next.startsWith('--')) {
+        fail(`Missing value for ${value}.`, 2);
+      }
+      args[key] = next;
+      i += 1;
+      continue;
+    }
+    args._.push(value);
+  }
+  return args;
+}
+
+function print(value, json = false) {
+  if (json || typeof value !== 'string') {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  console.log(value);
+}
+
+function normalizeText(value, maxLength = 240) {
+  return String(value || '').trim().replace(/\s+/g, ' ').slice(0, maxLength);
+}
+
+function safeSkillKey(value) {
+  return normalizeText(value, 120)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'skill';
+}
+
+async function readJsonFile(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    throw new Error(`Invalid JSON: ${filePath}`);
+  }
+}
+
+async function inferSkillMetadata(root, flags = {}) {
+  const manifest = await readJsonFile(path.join(root, MANIFEST_FILE));
+  const packageJson = await readJsonFile(path.join(root, 'package.json'));
+  const skillMdPath = path.join(root, 'SKILL.md');
+  const readmePath = path.join(root, 'README.md');
+  const skillMd = existsSync(skillMdPath) ? await readFile(skillMdPath, 'utf8') : '';
+  const readme = !skillMd && existsSync(readmePath) ? await readFile(readmePath, 'utf8') : '';
+  const firstHeading = [...skillMd.matchAll(/^#\s+(.+)$/gm), ...readme.matchAll(/^#\s+(.+)$/gm)][0]?.[1];
+  const firstParagraph = (skillMd || readme)
+    .split(/\n{2,}/)
+    .map((item) => item.trim())
+    .find((item) => item && !item.startsWith('#') && !item.startsWith('---'));
+  const name = normalizeText(flags.name || manifest?.name || packageJson?.name || firstHeading || path.basename(root), 120);
+  return {
+    name,
+    skillKey: safeSkillKey(flags['skill-key'] || manifest?.skillKey || packageJson?.name || name),
+    description: normalizeText(flags.description || manifest?.description || packageJson?.description || firstParagraph || '', 500),
+    version: normalizeText(flags.version || manifest?.version || packageJson?.version || '0.1.0', 80),
+    registry: manifest?.registry || null
+  };
+}
+
+function shouldIgnore(name) {
+  return DEFAULT_IGNORE.has(name) || name.endsWith('~') || name.endsWith('.tmp') || name.endsWith('.log');
+}
+
+async function walkFiles(root, current = root, out = []) {
+  const entries = await readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    if (shouldIgnore(entry.name)) continue;
+    const absolute = path.join(current, entry.name);
+    const relative = path.relative(root, absolute).replaceAll(path.sep, '/');
+    if (entry.isDirectory()) {
+      await walkFiles(root, absolute, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const info = await stat(absolute);
+    if (info.size > MAX_FILE_BYTES) continue;
+    out.push({ absolute, relative, size: info.size });
+  }
+  return out.sort((a, b) => a.relative.localeCompare(b.relative));
+}
+
+async function hashFiles(files) {
+  const hash = createHash('sha256');
+  let totalBytes = 0;
+  for (const file of files) {
+    const bytes = await readFile(file.absolute);
+    totalBytes += bytes.length;
+    hash.update(file.relative);
+    hash.update('\0');
+    hash.update(bytes);
+    hash.update('\0');
+  }
+  return {
+    sha256: hash.digest('hex'),
+    totalBytes
+  };
+}
+
+async function postJson(url, body, timeoutMs = 20_000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+    const text = await response.text();
+    let payload = {};
+    try {
+      payload = text ? JSON.parse(text) : {};
+    } catch {
+      throw new Error(`Bad JSON response from ${url}`);
+    }
+    if (!response.ok || payload.ok === false) {
+      throw new Error(payload.error || payload.message || `HTTP ${response.status}`);
+    }
+    return payload;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function inspectSkill(root, flags = {}) {
+  const absoluteRoot = path.resolve(root || '.');
+  const info = await stat(absoluteRoot).catch(() => null);
+  if (!info?.isDirectory()) {
+    throw new Error(`Skill directory not found: ${absoluteRoot}`);
+  }
+  const metadata = await inferSkillMetadata(absoluteRoot, flags);
+  const files = await walkFiles(absoluteRoot);
+  const digest = await hashFiles(files);
+  return {
+    root: absoluteRoot,
+    ...metadata,
+    package: {
+      fileCount: files.length,
+      totalBytes: digest.totalBytes,
+      sha256: digest.sha256,
+      tooLarge: digest.totalBytes > MAX_PACKAGE_BYTES,
+      files: files.map((file) => ({ path: file.relative, size: file.size }))
+    }
+  };
+}
+
+async function writeManifest(root, flags) {
+  const inspected = await inspectSkill(root, flags);
+  const code = normalizeText(flags.code, 80);
+  const claim = code
+    ? await postJson(
+        normalizeText(flags['claim-url'], 800) || DEFAULT_CLAIM_URL,
+        {
+          code,
+          skill: {
+            name: inspected.name,
+            skillKey: inspected.skillKey,
+            description: inspected.description,
+            version: inspected.version,
+            packageSha256: inspected.package.sha256,
+            packageFileCount: inspected.package.fileCount,
+            packageTotalBytes: inspected.package.totalBytes
+          },
+          device: {
+            label: normalizeText(flags['device-label'], 120) || os.hostname(),
+            platform: `${os.platform()}:${os.arch()}`
+          }
+        },
+        Number(flags['timeout-ms'] || 20_000)
+      )
+    : null;
+  const publicToken = normalizeText(flags['public-token'] || claim?.publicToken, 512);
+  if (!publicToken) {
+    throw new Error('Missing --code or --public-token.');
+  }
+  const now = new Date().toISOString();
+  const manifest = {
+    schemaVersion: `${REGISTRY_PROVIDER}.skill.registry.v1`,
+    name: normalizeText(claim?.name, 120) || inspected.name,
+    skillKey: safeSkillKey(claim?.skillKey || inspected.skillKey),
+    description: normalizeText(claim?.description, 500) || inspected.description,
+    version: normalizeText(claim?.version, 80) || inspected.version,
+    registry: {
+      provider: REGISTRY_PROVIDER,
+      skillId: normalizeText(flags['skill-id'] || claim?.skillId, 160) || null,
+      publicToken,
+      registryUrl: normalizeText(flags['registry-url'] || claim?.registryUrl, 800) || DEFAULT_REGISTRY_URL,
+      analytics: {
+        enabled: true,
+        allowedEvents: [
+          'package_created',
+          'upload_prompt_generated',
+          'hub_upload_attempted',
+          'hub_upload_succeeded',
+          'hub_download_reported',
+          'hub_install_reported',
+          'runtime_install_seen',
+          'skill_invoked',
+          'skill_completed',
+          'skill_failed'
+        ]
+      }
+    },
+    package: {
+      sha256: inspected.package.sha256,
+      fileCount: inspected.package.fileCount,
+      totalBytes: inspected.package.totalBytes,
+      generatedAt: now
+    }
+  };
+  const manifestPath = path.join(inspected.root, MANIFEST_FILE);
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  return { ok: true, manifestPath, manifest };
+}
+
+async function packSkill(root, flags) {
+  const inspected = await inspectSkill(root, flags);
+  if (inspected.package.tooLarge) {
+    throw new Error(`Package is too large: ${inspected.package.totalBytes} bytes. Max ${MAX_PACKAGE_BYTES}.`);
+  }
+  const outDir = path.resolve(flags.out || path.join(inspected.root, WORK_DIR, 'skill-package'));
+  if (flags.dryRun) {
+    return { ok: true, dryRun: true, outDir, ...inspected };
+  }
+  await mkdir(outDir, { recursive: true });
+  for (const file of inspected.package.files) {
+    const source = path.join(inspected.root, file.path);
+    const target = path.join(outDir, file.path);
+    await mkdir(path.dirname(target), { recursive: true });
+    await copyFile(source, target);
+  }
+  const packageManifest = {
+    schemaVersion: 'xiashe.skill.package.v1',
+    createdAt: new Date().toISOString(),
+    createdBy: `${os.platform()}:${os.hostname()}`,
+    skill: {
+      name: inspected.name,
+      skillKey: inspected.skillKey,
+      description: inspected.description,
+      version: inspected.version
+    },
+    registry: inspected.registry,
+    package: inspected.package
+  };
+  await writeFile(path.join(outDir, 'xiashe.package.json'), `${JSON.stringify(packageManifest, null, 2)}\n`, { mode: 0o600 });
+  return { ok: true, outDir, manifestPath: path.join(outDir, 'xiashe.package.json'), ...inspected };
+}
+
+function uploadPrompt(inspected, flags) {
+  const hub = normalizeText(flags.hub || 'generic', 40).toLowerCase();
+  const packageUrl = normalizeText(flags['package-url'], 1000);
+  const registry = inspected.registry || {};
+  const registryUrl = registry.registryUrl || DEFAULT_REGISTRY_URL;
+  const eventPayload = {
+    publicToken: registry.publicToken || '<xiashe public token from xiashe.skill.json>',
+    eventType: 'hub_upload_succeeded',
+    hub,
+    skillKey: inspected.skillKey,
+    packageSha256: inspected.package.sha256,
+    platformSkillUrl: '<published skill url>',
+    scenario: '<short usage scenario if the hub asks for one>'
+  };
+  const runtimePayload = {
+    publicToken: registry.publicToken || '<public token from registry manifest>',
+    eventType: 'skill_invoked',
+    eventSource: 'runtime',
+    runtimeKind: '<mcp|api|agent|webhook|platform>',
+    hub,
+    skillKey: inspected.skillKey,
+    installationId: '<stable anonymous install id>',
+    invocationId: '<unique invocation id>',
+    scenario: '<short usage scenario label only>'
+  };
+  const hubLine = hub === 'red'
+    ? '请按照小红书创作服务平台 Red Skill 的上传流程发布。'
+    : '请按照目标 Skill Hub 的上传流程发布。';
+  const sourceLine = packageUrl
+    ? `优先使用这个包或源码 URL 上传：${packageUrl}`
+    : `请使用当前目录或我提供的 Skill 包目录上传，Skill 根目录必须包含 SKILL.md 或 README.md。`;
+  return [
+    `你现在要帮我发布一个 Skill：${inspected.name}`,
+    '',
+    hubLine,
+    sourceLine,
+    '',
+    '发布要求：',
+    `- Skill 名称：${inspected.name}`,
+    `- Skill Key：${inspected.skillKey}`,
+    `- 版本：${inspected.version}`,
+    `- 描述：${inspected.description || '<从 SKILL.md/README.md 中提炼>'}`,
+    `- 包 SHA256：${inspected.package.sha256}`,
+    '- 不要读取或上传 .env、密钥、浏览器数据、SSH key、系统目录或 node_modules。',
+    '- 不要新增 postinstall hook、后台常驻进程、隐藏脚本或混淆逻辑。',
+    `- 如果平台要求安全说明，请明确说明这是用户显式发布的 Skill 包，${MANIFEST_FILE} 只包含公开 registry 归因和可关闭的 analytics 声明。`,
+    `- 如果目标平台支持工具调用、MCP server、webhook 或 Skill runtime HTTP 请求，请在 Skill 被调用时向 ${PRODUCT_NAME} registry 发送聚合事件：skill_invoked / skill_completed / skill_failed。`,
+    '- 事件里只放公开元数据、聚合状态和简短场景标签，不要发送用户输入原文、私密业务内容、账号凭据或文件内容。',
+    '- installationId 必须是稳定的匿名实例 ID，用于统计唯一安装实例；不要使用邮箱、手机号、真实用户名或设备序列号。',
+    '',
+    `发布成功后，请把公开链接和平台返回的信息回传给${PRODUCT_NAME} registry。只发送公开元数据和聚合事件，不发送用户内容、私密输入或账号凭据。`,
+    '',
+    `POST ${registryUrl}`,
+    'Content-Type: application/json',
+    '',
+    JSON.stringify(eventPayload, null, 2),
+    '',
+    '如果你能修改 Skill runtime，请在调用开始时发送：',
+    '',
+    `POST ${registryUrl}`,
+    'Content-Type: application/json',
+    '',
+    JSON.stringify(runtimePayload, null, 2),
+    '',
+    '调用完成或失败时，用同一个 invocationId 发送 skill_completed 或 skill_failed。'
+  ].join('\n');
+}
+
+async function writePrompt(root, flags) {
+  if (!flags.hub) {
+    throw new Error('Missing --hub <red|generic>.');
+  }
+  const inspected = await inspectSkill(root, flags);
+  const prompt = uploadPrompt(inspected, flags);
+  if (flags.out) {
+    const outPath = path.resolve(flags.out);
+    await mkdir(path.dirname(outPath), { recursive: true });
+    await writeFile(outPath, `${prompt}\n`, { mode: 0o600 });
+    return { ok: true, outPath, prompt };
+  }
+  return prompt;
+}
+
+async function main() {
+  const [command = '', ...commandArgs] = process.argv.slice(2);
+  if (!command || command === '--help' || command === '-h') {
+    console.log(usage());
+    return;
+  }
+  if (command === '--version' || command === '-v') {
+    console.log(VERSION);
+    return;
+  }
+  let root = '.';
+  if (commandArgs[0] && !commandArgs[0].startsWith('--')) {
+    root = commandArgs.shift();
+  }
+  const flags = parseArgs(commandArgs);
+  try {
+    if (command === 'inspect') {
+      const result = await inspectSkill(root, flags);
+      print(result, flags.json);
+      return;
+    }
+    if (command === 'attach' || command === 'link') {
+      const result = await writeManifest(root, flags);
+      print(flags.json ? result : `Wrote ${result.manifestPath}`, flags.json);
+      return;
+    }
+    if (command === 'pack') {
+      const result = await packSkill(root, flags);
+      print(flags.json ? result : `Prepared package directory: ${result.outDir}`, flags.json);
+      return;
+    }
+    if (command === 'prompt') {
+      const result = await writePrompt(root, flags);
+      if (typeof result === 'string' || flags.json) {
+        print(result, flags.json);
+      } else {
+        print(`Wrote ${result.outPath}`, false);
+      }
+      return;
+    }
+    fail(`Unknown command: ${command}\n\n${usage()}`, 2);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error || 'xiashe-skill failed'), 1);
+  }
+}
+
+void main();

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@xiashe/skill",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "xiashe-skill": "bin/xiashe-skill.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}