@xiashe/skill 0.1.0 → 0.1.2

package/README.md

@@ -9,19 +9,22 @@ This package is intentionally separate from the full `@xiashe/cli` product CLI a
 `xiashe-skill` helps creators prepare a Skill folder for third-party Skill hubs:
 
 - inspect a local Skill project
+- run one Agent-friendly registry setup command
 - 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
+- generate an upload handoff prompt that the creator can hand to an Agent
+- generate optional runtime analytics snippets
 
-It does not install background services, run postinstall hooks, read secrets, or upload to third-party hubs.
+It does not create upload packages, copy source directories, install background services, run postinstall hooks, read secrets, or upload to third-party hubs. The creator's Agent is responsible for packaging and uploading according to the target Skill hub's official rules.
 
 ## 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 setup . --code XS-XXXX-XXXX --hub red
 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
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs prompt . --hub red --source-url https://example.com/my-skill-repo
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs snippet . --target js
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs track . --event skill_invoked --dry-run --json
 ```

package/bin/xiashe-skill.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
-import { createHash } from 'node:crypto';
+import { createHash, createHmac } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { 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 VERSION = '0.1.2';
 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');
@@ -19,6 +19,9 @@ const MANIFEST_FILE = process.env.XIASHE_SKILL_MANIFEST_FILE || (COMMAND_NAME ==
 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 EVENT_SCHEMA_VERSION = process.env.XIASHE_SKILL_EVENT_SCHEMA_VERSION || (REGISTRY_PROVIDER === 'agentpie'
+  ? 'agentpie.skill.event.v1'
+  : 'xiashe.skill.event.v1');
 const DEFAULT_IGNORE = new Set([
   '.git',
   '.xiashe',
@@ -34,17 +37,20 @@ const DEFAULT_IGNORE = new Set([
   'coverage'
 ]);
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
-const MAX_PACKAGE_BYTES = 30 * 1024 * 1024;
+const MAX_SOURCE_BYTES = 30 * 1024 * 1024;
 
 function usage() {
   return `${COMMAND_NAME} ${VERSION}
 
 Usage:
   ${COMMAND_NAME} inspect [skill-dir] [--json]
+  ${COMMAND_NAME} setup [skill-dir] --code <dynamic-code> --hub <red|clawhub|skillhub|claude|dify|generic>
+  ${COMMAND_NAME} setup [skill-dir] --public-token <token> --skill-id <id> --hub <red|clawhub|skillhub|claude|dify|generic>
   ${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>]
+  ${COMMAND_NAME} prompt [skill-dir] --hub <red|clawhub|skillhub|claude|dify|generic> [--source-url <url>] [--out <file>]
+  ${COMMAND_NAME} snippet [skill-dir] [--target js|curl] [--out <file>]
+  ${COMMAND_NAME} track [skill-dir] --event <event> [--hub <hub>] [--installation-id <id>] [--invocation-id <id>]
 
 Options:
   --public-token <token>      Public write token issued by ${PRODUCT_NAME} registry.
@@ -54,10 +60,24 @@ Options:
   --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.
+  --hub <hub>                 Target Skill hub prompt style: red, clawhub, skillhub, claude, dify, or generic.
+  --event <event>             Runtime event to submit for testing.
+  --installation-id <id>      Stable anonymous install id for runtime analytics.
+  --invocation-id <id>        Unique invocation id for one skill call.
+  --scenario <label>          Short scenario label.
+  --campaign <label>          Campaign or promotion label.
+  --platform-skill-url <url>  Published Skill URL for hub_upload_succeeded events.
+  --platform-prompt-file <p>  Official third-party hub prompt file to embed in the handoff.
+  --platform-command <cmd>    Official third-party hub CLI/upload command to include.
+  --manifest-path <path>      Registry manifest output path. Defaults to ${MANIFEST_FILE} for attach, ${WORK_DIR}/${MANIFEST_FILE} for setup.
+  --signing-secret <secret>   Optional HMAC secret for signed runtime events.
+  --source-url <url>          User-provided source URL an Agent can use during third-party upload.
+  --package-url <url>         Deprecated alias for --source-url.
+  --out <path>                Output prompt or snippet file.
+  --out-dir <path>            Output directory for setup artifacts. Defaults to ${WORK_DIR}/.
+  --no-snippet                Setup should skip writing the runtime analytics snippet.
+  --no-track                  Setup should skip sending upload_prompt_generated.
+  --dry-run                   Print planned event payloads without network writes.
   --json                      Print machine-readable JSON.
   --help                      Show help.
   --version                   Show version.
@@ -71,6 +91,7 @@ function fail(message, code = 1) {
 
 function parseArgs(argv) {
   const args = { _: [], json: false, dryRun: false };
+  const booleanFlags = new Set(['no-snippet', 'no-track']);
   for (let i = 0; i < argv.length; i += 1) {
     const value = argv[i];
     if (value === '--help' || value === '-h') {
@@ -91,6 +112,10 @@ function parseArgs(argv) {
     }
     if (value.startsWith('--')) {
       const key = value.slice(2);
+      if (booleanFlags.has(key)) {
+        args[key] = true;
+        continue;
+      }
       const next = argv[i + 1];
       if (!next || next.startsWith('--')) {
         fail(`Missing value for ${value}.`, 2);
@@ -123,6 +148,26 @@ function safeSkillKey(value) {
     .replace(/^-+|-+$/g, '') || 'skill';
 }
 
+function canonicalSignaturePayload(payload) {
+  return [
+    payload.schemaVersion || EVENT_SCHEMA_VERSION,
+    payload.eventType || '',
+    payload.idempotencyKey || '',
+    Number.isFinite(payload.occurredAt) ? String(Math.floor(payload.occurredAt)) : '',
+    payload.installationId || '',
+    payload.invocationId || '',
+    payload.hub || '',
+    payload.skillKey || ''
+  ].join('\n');
+}
+
+function signEventPayload(payload, signingSecret) {
+  if (!signingSecret) return undefined;
+  return createHmac('sha256', signingSecret)
+    .update(canonicalSignaturePayload(payload))
+    .digest('hex');
+}
+
 async function readJsonFile(filePath) {
   if (!existsSync(filePath)) return null;
   try {
@@ -133,7 +178,11 @@ async function readJsonFile(filePath) {
 }
 
 async function inferSkillMetadata(root, flags = {}) {
-  const manifest = await readJsonFile(path.join(root, MANIFEST_FILE));
+  const manifestPath = flags['manifest-path']
+    ? path.resolve(flags['manifest-path'])
+    : path.join(root, MANIFEST_FILE);
+  const localManifestPath = path.join(root, WORK_DIR, MANIFEST_FILE);
+  const manifest = await readJsonFile(manifestPath) || await readJsonFile(localManifestPath);
   const packageJson = await readJsonFile(path.join(root, 'package.json'));
   const skillMdPath = path.join(root, 'SKILL.md');
   const readmePath = path.join(root, 'README.md');
@@ -235,7 +284,7 @@ async function inspectSkill(root, flags = {}) {
       fileCount: files.length,
       totalBytes: digest.totalBytes,
       sha256: digest.sha256,
-      tooLarge: digest.totalBytes > MAX_PACKAGE_BYTES,
+      tooLarge: digest.totalBytes > MAX_SOURCE_BYTES,
       files: files.map((file) => ({ path: file.relative, size: file.size }))
     }
   };
@@ -282,10 +331,14 @@ async function writeManifest(root, flags) {
       skillId: normalizeText(flags['skill-id'] || claim?.skillId, 160) || null,
       publicToken,
       registryUrl: normalizeText(flags['registry-url'] || claim?.registryUrl, 800) || DEFAULT_REGISTRY_URL,
+      eventSchemaVersion: EVENT_SCHEMA_VERSION,
+      signing: {
+        mode: normalizeText(flags['signing-secret'], 20) ? 'optional' : 'off',
+        secretEnv: `${REGISTRY_PROVIDER.toUpperCase()}_SKILL_SIGNING_SECRET`
+      },
       analytics: {
         enabled: true,
         allowedEvents: [
-          'package_created',
           'upload_prompt_generated',
           'hub_upload_attempted',
           'hub_upload_succeeded',
@@ -298,67 +351,132 @@ async function writeManifest(root, flags) {
         ]
       }
     },
-    package: {
+    sourceFingerprint: {
       sha256: inspected.package.sha256,
       fileCount: inspected.package.fileCount,
       totalBytes: inspected.package.totalBytes,
       generatedAt: now
     }
   };
-  const manifestPath = path.join(inspected.root, MANIFEST_FILE);
+  const manifestPath = flags['manifest-path']
+    ? path.resolve(flags['manifest-path'])
+    : flags['local-manifest']
+      ? path.join(inspected.root, WORK_DIR, MANIFEST_FILE)
+      : path.join(inspected.root, MANIFEST_FILE);
+  await mkdir(path.dirname(manifestPath), { recursive: true });
   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}.`);
+function hubInstruction(hub) {
+  if (hub === 'red') {
+    return 'Red Skill 的官方上传 prompt / 页面流程是主流程。请先从小红书创作服务平台获取或使用用户提供的 Red Skill 上传 prompt，再把下面的虾舍 registry 要求作为附加说明合并进去。';
   }
-  const outDir = path.resolve(flags.out || path.join(inspected.root, WORK_DIR, 'skill-package'));
-  if (flags.dryRun) {
-    return { ok: true, dryRun: true, outDir, ...inspected };
+  if (hub === 'clawhub') {
+    return 'ClawHub 的官方 CLI、prompt 或页面流程是主流程。请先确认 ClawHub 当前要求，再把下面的虾舍 registry 要求作为附加说明合并进去。';
   }
-  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 };
+  if (hub === 'skillhub') {
+    return 'SkillHub 的官方 CLI、prompt 或页面流程是主流程。请先确认 SkillHub 当前要求，再把下面的虾舍 registry 要求作为附加说明合并进去。';
+  }
+  if (hub === 'claude') {
+    return 'Claude Skills 的官方上传/导入流程是主流程。请先确认 Claude 当前 Skill 格式和共享要求，再把下面的 registry 披露文本放入允许的说明文件。';
+  }
+  if (hub === 'dify') {
+    return 'Dify Plugin/Tool 的官方打包和发布流程是主流程。请先按 Dify 插件规范处理 manifest 和工具定义，再把下面的 registry 披露文本放入允许的 README/说明字段。';
+  }
+  return '目标 Skill Hub 的官方 CLI、prompt 或页面流程是主流程。请先确认平台当前要求，再把下面的虾舍 registry 要求作为附加说明合并进去。';
+}
+
+function platformPromptPlaceholder(hub) {
+  if (hub === 'red') {
+    return '如果用户还没有提供 Red Skill 官方上传 prompt，请先请用户从小红书创作服务平台复制该 prompt；不要用虾舍 prompt 替代 Red Skill 官方 prompt。';
+  }
+  if (hub === 'clawhub') {
+    return '如果 ClawHub 提供官方 CLI 命令或上传 prompt，请优先使用官方命令/prompt；不要用虾舍 prompt 替代 ClawHub 官方流程。';
+  }
+  if (hub === 'skillhub') {
+    return '如果 SkillHub 提供官方 CLI 命令或上传 prompt，请优先使用官方命令/prompt；不要用虾舍 prompt 替代 SkillHub 官方流程。';
+  }
+  if (hub === 'claude') {
+    return '如果 Claude 提供官方 Skill 导入/上传说明，请优先使用官方说明；不要用虾舍 prompt 替代 Claude 官方流程。';
+  }
+  if (hub === 'dify') {
+    return '如果 Dify 提供官方插件打包/发布命令，请优先使用官方命令；不要用虾舍 prompt 替代 Dify 官方流程。';
+  }
+  return '如果目标平台提供官方 CLI 命令或上传 prompt，请优先使用官方命令/prompt；不要用虾舍 prompt 替代平台官方流程。';
+}
+
+function uploadCompatibilityLines(hub, manifestFile) {
+  const localManifest = `${WORK_DIR}/${manifestFile}`;
+  if (hub === 'red') {
+    return [
+      'Red Skill 兼容性要求：',
+      '- Red Skill 如果只接受 Markdown/TXT，请不要把 JSON manifest 当作源码文件上传。',
+      `- ${localManifest} 保留在用户本地用于虾舍 registry claim 和 analytics；只有在 Red Skill 官方流程明确允许附加 JSON 文件时才上传。`,
+      '- 如需在 Red Skill 页面披露 registry，请把下面的“公开披露文本”写入 Skill 介绍、README 或平台允许的 Markdown/TXT 字段。'
+    ];
+  }
+  return [
+    '第三方平台兼容性要求：',
+    `- 如果目标平台不接受 ${localManifest} 这类 JSON manifest，请不要强行上传该文件。`,
+    '- 保留本地 registry manifest，并把“公开披露文本”写入平台允许的说明字段、README、SKILL.md 或 Markdown/TXT 附件。',
+    '- 如果平台支持额外 manifest / metadata 文件，可以在提交前向用户确认是否一并上传。'
+  ];
+}
+
+function publicDisclosure(inspected, registryUrl) {
+  return [
+    '公开披露文本：',
+    '```markdown',
+    `### ${PRODUCT_NAME} Registry / Analytics`,
+    '',
+    `This Skill is registered by its creator with ${PRODUCT_NAME} for public attribution and aggregated analytics.`,
+    '',
+    `- Registry provider: ${REGISTRY_PROVIDER}`,
+    `- Skill key: ${inspected.skillKey}`,
+    `- Registry event endpoint: ${registryUrl}`,
+    '- Events, if enabled by the runtime/platform, should contain only public metadata and aggregate status.',
+    '- Do not send user prompts, private files, credentials, environment variables, account tokens, or raw business content.',
+    '- Analytics can be removed by deleting the registry manifest/snippet or disabling it in the creator dashboard.',
+    '```'
+  ];
+}
+
+async function readPlatformPrompt(flags) {
+  const promptPath = normalizeText(flags['platform-prompt-file'], 1000);
+  if (!promptPath) return '';
+  const absolute = path.resolve(promptPath);
+  const info = await stat(absolute).catch(() => null);
+  if (!info?.isFile()) {
+    throw new Error(`Platform prompt file not found: ${absolute}`);
+  }
+  if (info.size > MAX_FILE_BYTES) {
+    throw new Error(`Platform prompt file is too large: ${absolute}`);
+  }
+  return readFile(absolute, 'utf8');
 }
 
-function uploadPrompt(inspected, flags) {
+async function uploadPrompt(inspected, flags) {
   const hub = normalizeText(flags.hub || 'generic', 40).toLowerCase();
-  const packageUrl = normalizeText(flags['package-url'], 1000);
+  const sourceUrl = normalizeText(flags['source-url'] || flags['package-url'], 1000);
+  const platformCommand = normalizeText(flags['platform-command'], 1000);
+  const platformPrompt = await readPlatformPrompt(flags);
   const registry = inspected.registry || {};
   const registryUrl = registry.registryUrl || DEFAULT_REGISTRY_URL;
   const eventPayload = {
     publicToken: registry.publicToken || '<xiashe public token from xiashe.skill.json>',
+    schemaVersion: registry.eventSchemaVersion || EVENT_SCHEMA_VERSION,
     eventType: 'hub_upload_succeeded',
     hub,
     skillKey: inspected.skillKey,
+    idempotencyKey: '<hub-upload-succeeded-stable-key>',
     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>',
+    schemaVersion: registry.eventSchemaVersion || EVENT_SCHEMA_VERSION,
     eventType: 'skill_invoked',
     eventSource: 'runtime',
     runtimeKind: '<mcp|api|agent|webhook|platform>',
@@ -366,29 +484,52 @@ function uploadPrompt(inspected, flags) {
     skillKey: inspected.skillKey,
     installationId: '<stable anonymous install id>',
     invocationId: '<unique invocation id>',
-    scenario: '<short usage scenario label only>'
+    idempotencyKey: '<unique invocation id>:skill_invoked',
+    scenario: '<short usage scenario label only>',
+    sourceSurface: '<profile|hub|agent|direct>',
+    campaign: '<optional promotion label>'
   };
-  const hubLine = hub === 'red'
-    ? '请按照小红书创作服务平台 Red Skill 的上传流程发布。'
-    : '请按照目标 Skill Hub 的上传流程发布。';
-  const sourceLine = packageUrl
-    ? `优先使用这个包或源码 URL 上传：${packageUrl}`
-    : `请使用当前目录或我提供的 Skill 包目录上传，Skill 根目录必须包含 SKILL.md 或 README.md。`;
+  const hubLine = hubInstruction(hub);
+  const sourceLine = sourceUrl
+    ? `你可以使用用户明确提供的源码或仓库 URL：${sourceUrl}`
+    : `请在用户当前 Skill 项目根目录内操作；最终上传形态必须由你按目标 Skill 平台规则生成。`;
+  const officialFlowLines = [
+    '第三方平台官方流程：',
+    `- ${hubLine}`,
+    '- 平台官方 prompt / CLI / 页面表单是上传依据；虾舍只提供 registry 和 analytics 附加要求。',
+    '- 如果平台官方要求与虾舍附加说明冲突，以平台官方上传要求为准；不要为了 analytics 绕过平台规则。',
+    platformCommand ? `- 用户提供的官方命令：${platformCommand}` : `- ${platformPromptPlaceholder(hub)}`
+  ];
+  if (platformPrompt) {
+    officialFlowLines.push('', '用户提供的第三方平台官方 prompt：', '```text', platformPrompt.trim(), '```');
+  }
+  const compatibilityLines = uploadCompatibilityLines(hub, MANIFEST_FILE);
+  const disclosureLines = publicDisclosure(inspected, registryUrl);
   return [
-    `你现在要帮我发布一个 Skill：${inspected.name}`,
+    `你现在要帮用户把 Skill 接入 ${PRODUCT_NAME} registry，并按第三方平台官方流程发布：${inspected.name}`,
+    '',
+    ...officialFlowLines,
     '',
-    hubLine,
     sourceLine,
     '',
-    '发布要求：',
+    `${PRODUCT_NAME} 职责边界：`,
+    `- ${PRODUCT_NAME} 只负责 registry manifest、公开归因和 analytics 回传说明，不负责构建、打包、上传或审核这个 Skill。`,
+    '- 最终上传文件、目录结构、压缩包、表单字段和上线版本，必须由你按照目标 Skill 平台的官方要求处理。',
+    '- 如果目标平台要求重新整理源码、生成 markdown、压缩包或填写表单，请你在用户授权范围内完成，并在提交前向用户展示将上传的文件和字段。',
+    '',
+    ...compatibilityLines,
+    '',
+    ...disclosureLines,
+    '',
+    `${PRODUCT_NAME} registry 附加要求：`,
     `- Skill 名称：${inspected.name}`,
     `- Skill Key：${inspected.skillKey}`,
     `- 版本：${inspected.version}`,
     `- 描述：${inspected.description || '<从 SKILL.md/README.md 中提炼>'}`,
-    `- 包 SHA256：${inspected.package.sha256}`,
+    `- 源码指纹 SHA256：${inspected.package.sha256}`,
     '- 不要读取或上传 .env、密钥、浏览器数据、SSH key、系统目录或 node_modules。',
     '- 不要新增 postinstall hook、后台常驻进程、隐藏脚本或混淆逻辑。',
-    `- 如果平台要求安全说明，请明确说明这是用户显式发布的 Skill 包，${MANIFEST_FILE} 只包含公开 registry 归因和可关闭的 analytics 声明。`,
+    `- 如果平台要求安全说明，请明确说明这是用户显式发布的 Skill 项目，${MANIFEST_FILE} 只包含公开 registry 归因和可关闭的 analytics 声明。`,
     `- 如果目标平台支持工具调用、MCP server、webhook 或 Skill runtime HTTP 请求，请在 Skill 被调用时向 ${PRODUCT_NAME} registry 发送聚合事件：skill_invoked / skill_completed / skill_failed。`,
     '- 事件里只放公开元数据、聚合状态和简短场景标签，不要发送用户输入原文、私密业务内容、账号凭据或文件内容。',
     '- installationId 必须是稳定的匿名实例 ID，用于统计唯一安装实例；不要使用邮箱、手机号、真实用户名或设备序列号。',
@@ -416,7 +557,7 @@ async function writePrompt(root, flags) {
     throw new Error('Missing --hub <red|generic>.');
   }
   const inspected = await inspectSkill(root, flags);
-  const prompt = uploadPrompt(inspected, flags);
+  const prompt = await uploadPrompt(inspected, flags);
   if (flags.out) {
     const outPath = path.resolve(flags.out);
     await mkdir(path.dirname(outPath), { recursive: true });
@@ -426,6 +567,217 @@ async function writePrompt(root, flags) {
   return prompt;
 }
 
+async function writeRuntimeSnippet(root, flags) {
+  const inspected = await inspectSkill(root, flags);
+  const registry = inspected.registry || {};
+  const registryUrl = registry.registryUrl || DEFAULT_REGISTRY_URL;
+  const publicToken = registry.publicToken || '<public token from registry manifest>';
+  const eventSchemaVersion = registry.eventSchemaVersion || EVENT_SCHEMA_VERSION;
+  const target = normalizeText(flags.target || 'js', 20).toLowerCase();
+  const snippet = target === 'curl'
+    ? [
+        `curl -X POST '${registryUrl}' \\`,
+        "  -H 'content-type: application/json' \\",
+        '  -d ' + JSON.stringify(JSON.stringify({
+          publicToken,
+          schemaVersion: eventSchemaVersion,
+          eventType: 'skill_invoked',
+          eventSource: 'runtime',
+          runtimeKind: 'mcp',
+          hub: '<hub>',
+          skillKey: inspected.skillKey,
+          installationId: '<anonymous-stable-install-id>',
+          invocationId: '<unique-call-id>',
+          idempotencyKey: '<unique-call-id>:skill_invoked',
+          scenario: '<short-scenario-label>'
+        }))
+      ].join('\n')
+    : [
+        `const XIASHE_SKILL_REGISTRY_URL = ${JSON.stringify(registryUrl)};`,
+        `const XIASHE_SKILL_PUBLIC_TOKEN = ${JSON.stringify(publicToken)};`,
+        `const XIASHE_SKILL_EVENT_SCHEMA_VERSION = ${JSON.stringify(eventSchemaVersion)};`,
+        `const XIASHE_SKILL_SIGNING_SECRET = ${JSON.stringify(normalizeText(flags['signing-secret'], 512))} || globalThis.process?.env?.XIASHE_SKILL_SIGNING_SECRET || globalThis.process?.env?.AGENTPIE_SKILL_SIGNING_SECRET || '';`,
+        '',
+        'async function hmacSha256(secret, message) {',
+        '  if (!secret || !globalThis.crypto?.subtle) return undefined;',
+        "  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);",
+        '  const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));',
+        "  return Array.from(new Uint8Array(signature)).map((byte) => byte.toString(16).padStart(2, '0')).join('');",
+        '}',
+        '',
+        'function canonicalSignaturePayload(payload) {',
+        '  return [',
+        '    payload.schemaVersion || XIASHE_SKILL_EVENT_SCHEMA_VERSION,',
+        "    payload.eventType || '',",
+        "    payload.idempotencyKey || '',",
+        "    Number.isFinite(payload.occurredAt) ? String(Math.floor(payload.occurredAt)) : '',",
+        "    payload.installationId || '',",
+        "    payload.invocationId || '',",
+        "    payload.hub || '',",
+        "    payload.skillKey || ''",
+        "  ].join('\\n');",
+        '}',
+        '',
+        'export async function trackSkillEvent(eventType, options = {}) {',
+        '  const occurredAt = options.occurredAt || Date.now();',
+        '  const invocationId = options.invocationId;',
+        '  const payload = {',
+        '    publicToken: XIASHE_SKILL_PUBLIC_TOKEN,',
+        '    schemaVersion: XIASHE_SKILL_EVENT_SCHEMA_VERSION,',
+        '    eventType,',
+        "    eventSource: options.eventSource || 'runtime',",
+        "    runtimeKind: options.runtimeKind || 'mcp',",
+        `    skillKey: ${JSON.stringify(inspected.skillKey)},`,
+        '    hub: options.hub,',
+        '    installationId: options.installationId,',
+        '    invocationId,',
+        '    idempotencyKey: options.idempotencyKey || `${invocationId || options.installationId || "runtime"}:${eventType}:${occurredAt}`,',
+        '    scenario: options.scenario,',
+        '    sourceSurface: options.sourceSurface,',
+        '    campaign: options.campaign,',
+        '    packageSha256: options.packageSha256,',
+        '    occurredAt',
+        '  };',
+        '  const signature = await hmacSha256(XIASHE_SKILL_SIGNING_SECRET, canonicalSignaturePayload(payload));',
+        '  if (signature) payload.signature = signature;',
+        '  await fetch(XIASHE_SKILL_REGISTRY_URL, {',
+        "    method: 'POST',",
+        "    headers: { 'content-type': 'application/json' },",
+        '    body: JSON.stringify(payload)',
+        '  });',
+        '}',
+        '',
+        '// Call at start/end of a single runtime invocation:',
+        '// await trackSkillEvent("skill_invoked", { installationId, invocationId, scenario });',
+        '// await trackSkillEvent("skill_completed", { installationId, invocationId, scenario });',
+        '// await trackSkillEvent("skill_failed", { installationId, invocationId, scenario });'
+      ].join('\n');
+  if (flags.out) {
+    const outPath = path.resolve(flags.out);
+    await mkdir(path.dirname(outPath), { recursive: true });
+    await writeFile(outPath, `${snippet}\n`, { mode: 0o600 });
+    return { ok: true, outPath, snippet };
+  }
+  return snippet;
+}
+
+async function submitTrackEvent(root, flags) {
+  const inspected = await inspectSkill(root, flags);
+  const registry = inspected.registry || {};
+  const publicToken = normalizeText(flags['public-token'] || registry.publicToken, 512);
+  const registryUrl = normalizeText(flags['registry-url'] || registry.registryUrl, 800) || DEFAULT_REGISTRY_URL;
+  const eventType = normalizeText(flags.event, 80);
+  if (!publicToken) {
+    throw new Error(`Missing public token. Run ${COMMAND_NAME} attach first or pass --public-token.`);
+  }
+  if (!eventType) {
+    throw new Error('Missing --event.');
+  }
+  const occurredAt = Number(flags['occurred-at'] || Date.now());
+  const invocationId = normalizeText(flags['invocation-id'] || `cli-${Date.now()}`, 160);
+  const installationId = normalizeText(flags['installation-id'] || 'local-test-install', 220);
+  const hub = normalizeText(flags.hub || 'local-test', 80);
+  const payload = {
+    publicToken,
+    schemaVersion: normalizeText(flags['schema-version'], 80) || EVENT_SCHEMA_VERSION,
+    eventType,
+    eventSource: normalizeText(flags['event-source'] || 'manual', 40),
+    runtimeKind: normalizeText(flags['runtime-kind'] || 'cli-test', 80),
+    hub,
+    skillKey: inspected.skillKey,
+    installationId,
+    invocationId,
+    scenario: normalizeText(flags.scenario || 'local-test', 120),
+    sourceSurface: normalizeText(flags['source-surface'] || 'cli', 120),
+    campaign: normalizeText(flags.campaign, 120) || undefined,
+    platformSkillUrl: normalizeText(flags['platform-skill-url'], 1000) || undefined,
+    packageSha256: inspected.package.sha256,
+    idempotencyKey: normalizeText(flags.idempotencyKey || flags['idempotency-key'], 220) || `${invocationId}:${eventType}`,
+    occurredAt: Number.isFinite(occurredAt) ? occurredAt : Date.now()
+  };
+  const signingSecret = normalizeText(flags['signing-secret'], 512);
+  const signature = signEventPayload(payload, signingSecret);
+  if (signature) {
+    payload.signature = signature;
+  }
+  if (flags.dryRun) {
+    return { ok: true, dryRun: true, registryUrl, payload };
+  }
+  const result = await postJson(registryUrl, payload, Number(flags['timeout-ms'] || 20_000));
+  return { ok: true, registryUrl, payload, result };
+}
+
+async function setupAgentWorkflow(root, flags) {
+  const hub = normalizeText(flags.hub || 'generic', 40).toLowerCase();
+  const absoluteRoot = path.resolve(root || '.');
+  const outDir = path.resolve(flags['out-dir'] || path.join(absoluteRoot, WORK_DIR));
+  await mkdir(outDir, { recursive: true });
+  const manifestResult = await writeManifest(absoluteRoot, {
+    ...flags,
+    'local-manifest': true,
+    'manifest-path': flags['manifest-path'] || path.join(outDir, MANIFEST_FILE)
+  });
+
+  const promptPath = path.join(outDir, `upload-${safeSkillKey(hub)}.md`);
+  const promptResult = await writePrompt(absoluteRoot, { ...flags, hub, out: promptPath });
+  const inspectedAfterManifest = await inspectSkill(absoluteRoot, flags);
+  const disclosurePath = path.join(outDir, 'REGISTRY_DISCLOSURE.md');
+  await writeFile(
+    disclosurePath,
+    `${publicDisclosure(inspectedAfterManifest, inspectedAfterManifest.registry?.registryUrl || DEFAULT_REGISTRY_URL)
+      .filter((line) => line !== '公开披露文本：' && line !== '```markdown' && line !== '```')
+      .join('\n')}\n`,
+    { mode: 0o600 }
+  );
+  const snippetPath = path.join(outDir, 'runtime-events.js');
+  let snippetResult = null;
+  if (!flags['no-snippet']) {
+    snippetResult = await writeRuntimeSnippet(absoluteRoot, {
+      ...flags,
+      target: flags.target || 'js',
+      out: snippetPath
+    });
+  }
+
+  const warnings = [];
+  let promptEvent = null;
+  if (!flags['no-track']) {
+    try {
+      promptEvent = await submitTrackEvent(absoluteRoot, {
+        ...flags,
+        hub,
+        event: 'upload_prompt_generated',
+        'event-source': 'cli',
+        'runtime-kind': 'agent-handoff',
+        scenario: flags.scenario || 'third-party-skill-upload'
+      });
+    } catch (error) {
+      warnings.push(`upload_prompt_generated was not recorded: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  return {
+    ok: true,
+    hub,
+    manifestPath: manifestResult.manifestPath,
+    promptPath: typeof promptResult === 'string' ? promptPath : promptResult.outPath,
+    disclosurePath,
+    snippetPath: snippetResult ? snippetResult.outPath : null,
+    promptEvent,
+    warnings,
+    next: [
+      `Open ${path.relative(absoluteRoot, promptPath)} and merge it with the official ${hub} upload prompt/CLI flow.`,
+      `If ${hub} provides its own upload prompt or CLI, treat that official flow as authoritative.`,
+      `Use ${path.relative(absoluteRoot, disclosurePath)} as the read-only analytics disclosure for platform review.`,
+      'Do not upload secrets, .env files, browser data, SSH keys, node_modules, dist, build, or unrelated local files.',
+      `If the Skill is published, record the public URL with: ${COMMAND_NAME} track . --event hub_upload_succeeded --hub ${hub} --platform-skill-url <url>`,
+      snippetResult
+        ? `If the runtime supports HTTP/MCP/webhook, adapt ${path.relative(absoluteRoot, snippetPath)} into the Skill runtime.`
+        : 'Runtime snippet was skipped.'
+    ]
+  };
+}
+
 async function main() {
   const [command = '', ...commandArgs] = process.argv.slice(2);
   if (!command || command === '--help' || command === '-h') {
@@ -447,14 +799,38 @@ async function main() {
       print(result, flags.json);
       return;
     }
+    if (command === 'setup' || command === 'handoff') {
+      const result = await setupAgentWorkflow(root, flags);
+      if (flags.json) {
+        print(result, true);
+      } else {
+        const lines = [
+          `Wrote ${result.manifestPath}`,
+          `Wrote ${result.promptPath}`,
+          `Wrote ${result.disclosurePath}`,
+          result.snippetPath ? `Wrote ${result.snippetPath}` : null,
+          ...result.warnings.map((warning) => `Warning: ${warning}`),
+          '',
+          'Next:',
+          ...result.next.map((item) => `- ${item}`)
+        ].filter(Boolean);
+        print(lines.join('\n'), false);
+      }
+      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);
+      const message = `${COMMAND_NAME} no longer creates upload packages. Run "${COMMAND_NAME} inspect ${root}" for a local source fingerprint, then ask your Agent to package and upload according to the target Skill hub rules.`;
+      if (flags.json) {
+        print({ ok: false, error: 'pack_disabled', message }, true);
+        process.exitCode = 2;
+        return;
+      }
+      fail(message, 2);
       return;
     }
     if (command === 'prompt') {
@@ -466,6 +842,20 @@ async function main() {
       }
       return;
     }
+    if (command === 'snippet') {
+      const result = await writeRuntimeSnippet(root, flags);
+      if (typeof result === 'string' || flags.json) {
+        print(result, flags.json);
+      } else {
+        print(`Wrote ${result.outPath}`, false);
+      }
+      return;
+    }
+    if (command === 'track') {
+      const result = await submitTrackEvent(root, flags);
+      print(result, flags.json);
+      return;
+    }
     fail(`Unknown command: ${command}\n\n${usage()}`, 2);
   } catch (error) {
     fail(error instanceof Error ? error.message : String(error || 'xiashe-skill failed'), 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/skill",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "bin": {
     "xiashe-skill": "bin/xiashe-skill.mjs"