@xiashe/skill 0.1.4 → 0.1.5

package/README.md

@@ -9,22 +9,25 @@ 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
+- run one Agent-friendly registry setup command that prepares all supported hub handoffs
 - write an explicit `xiashe.skill.json` registry manifest
-- generate an upload handoff prompt that the creator can hand to an Agent
+- generate one unified `UPLOAD_HANDOFF.md` that the creator's Agent can use after the user pastes a third-party official upload prompt
 - generate optional runtime analytics snippets
 
 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.
 
+`setup --hub all` still writes platform-specific `upload-<hub>.md` checklists for source attribution, but those are internal Agent checklists. Users should not need to pick files manually. When a platform such as Red Skill provides its own upload prompt, paste that official prompt to the Agent and tell it to follow `.xiashe/UPLOAD_HANDOFF.md`.
+
 ## 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 all
 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 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
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs track . --event skill_invoked --hub coze --dry-run --json
 ```

package/bin/xiashe-skill.mjs

@@ -6,7 +6,7 @@ import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-const VERSION = '0.1.4';
+const VERSION = '0.1.5';
 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');
@@ -17,11 +17,14 @@ const MANIFEST_FILE = process.env.XIASHE_SKILL_MANIFEST_FILE || (COMMAND_NAME ==
   ? 'agentpie.skill.json'
   : 'xiashe.skill.json');
 const WORK_DIR = process.env.XIASHE_SKILL_WORK_DIR || (COMMAND_NAME === 'agentpie-skill' ? '.agentpie' : '.xiashe');
+const HANDOFF_FILE = 'UPLOAD_HANDOFF.md';
 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 SUPPORTED_HUBS = ['red', 'clawhub', 'skillhub', 'claude', 'dify', 'coze', 'generic'];
+const DEFAULT_SETUP_HUBS = ['red', 'clawhub', 'skillhub', 'claude', 'dify', 'coze', 'generic'];
 const DEFAULT_IGNORE = new Set([
   '.git',
   '.xiashe',
@@ -44,11 +47,11 @@ function usage() {
 
 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} setup [skill-dir] --code <dynamic-code> [--hub all|red|clawhub|skillhub|claude|dify|coze|generic]
+  ${COMMAND_NAME} setup [skill-dir] --public-token <token> --skill-id <id> [--hub all|red|clawhub|skillhub|claude|dify|coze|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} prompt [skill-dir] --hub <red|clawhub|skillhub|claude|dify|generic> [--source-url <url>] [--out <file>]
+  ${COMMAND_NAME} prompt [skill-dir] --hub <red|clawhub|skillhub|claude|dify|coze|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>]
 
@@ -60,7 +63,7 @@ Options:
   --registry-url <url>        Event endpoint written to the manifest.
   --name <name>               Skill display name override.
   --description <text>        Skill description override.
-  --hub <hub>                 Target Skill hub prompt style: red, clawhub, skillhub, claude, dify, or generic.
+  --hub <hub>                 Target Skill hub prompt style. setup defaults to all supported hubs.
   --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.
@@ -150,6 +153,37 @@ function safeSkillKey(value) {
     .replace(/^-+|-+$/g, '') || 'skill';
 }
 
+function normalizeHub(value) {
+  const hub = normalizeText(value, 40).toLowerCase().replace(/\s+/g, '').replace(/_/g, '-');
+  if (hub === 'redskill' || hub === 'red-skill' || hub === 'xiaohongshu' || hub === 'xhs') {
+    return 'red';
+  }
+  if (hub === 'claw-hub') {
+    return 'clawhub';
+  }
+  if (hub === 'skill-hub') {
+    return 'skillhub';
+  }
+  return hub;
+}
+
+function setupHubsFromFlags(flags) {
+  const raw = normalizeText(flags.hub || 'all', 240).toLowerCase();
+  if (!raw || raw === 'all' || raw === '*') {
+    return [...DEFAULT_SETUP_HUBS];
+  }
+  const hubs = raw
+    .split(',')
+    .map((item) => normalizeHub(item))
+    .filter(Boolean);
+  const unique = Array.from(new Set(hubs));
+  const unsupported = unique.filter((hub) => !SUPPORTED_HUBS.includes(hub));
+  if (unsupported.length > 0) {
+    throw new Error(`Unsupported --hub value: ${unsupported.join(', ')}. Use all, ${SUPPORTED_HUBS.join(', ')}.`);
+  }
+  return unique.length > 0 ? unique : [...DEFAULT_SETUP_HUBS];
+}
+
 function canonicalSignaturePayload(payload) {
   return [
     payload.schemaVersion || EVENT_SCHEMA_VERSION,
@@ -340,6 +374,7 @@ async function writeManifest(root, flags) {
       },
       analytics: {
         enabled: true,
+        supportedHubs: [...SUPPORTED_HUBS],
         allowedEvents: [
           'upload_prompt_generated',
           'hub_upload_attempted',
@@ -353,6 +388,20 @@ async function writeManifest(root, flags) {
         ]
       }
     },
+    platforms: Object.fromEntries(SUPPORTED_HUBS.map((hub) => [
+      hub,
+      {
+        hub,
+        sourceSurface: hub,
+        uploadPromptFile: `${WORK_DIR}/upload-${safeSkillKey(hub)}.md`,
+        eventDefaults: {
+          schemaVersion: EVENT_SCHEMA_VERSION,
+          hub,
+          sourceSurface: hub,
+          skillKey: safeSkillKey(claim?.skillKey || inspected.skillKey)
+        }
+      }
+    ])),
     sourceFingerprint: {
       sha256: inspected.package.sha256,
       fileCount: inspected.package.fileCount,
@@ -386,6 +435,9 @@ function hubInstruction(hub) {
   if (hub === 'dify') {
     return 'Dify Plugin/Tool 的官方打包和发布流程是主流程。请先按 Dify 插件规范处理 manifest 和工具定义，再把下面的 registry 披露文本放入允许的 README/说明字段。';
   }
+  if (hub === 'coze') {
+    return 'Coze Agent/Plugin/Workflow 的官方配置和发布流程是主流程。请先按 Coze 当前工具、插件或知识库要求配置，再把下面的 registry 回调作为可选 HTTP/API 步骤接入。';
+  }
   return '目标 Skill Hub 的官方 CLI、prompt 或页面流程是主流程。请先确认平台当前要求，再把下面的虾舍 registry 要求作为附加说明合并进去。';
 }
 
@@ -405,6 +457,9 @@ function platformPromptPlaceholder(hub) {
   if (hub === 'dify') {
     return '如果 Dify 提供官方插件打包/发布命令，请优先使用官方命令；不要用虾舍 prompt 替代 Dify 官方流程。';
   }
+  if (hub === 'coze') {
+    return '如果 Coze 提供 Agent/Plugin/Workflow 的配置步骤，请优先使用 Coze 官方配置；不要用虾舍 prompt 替代 Coze 官方流程。';
+  }
   return '如果目标平台提供官方 CLI 命令或上传 prompt，请优先使用官方命令/prompt；不要用虾舍 prompt 替代平台官方流程。';
 }
 
@@ -508,7 +563,7 @@ async function readPlatformPrompt(flags) {
 }
 
 async function uploadPrompt(inspected, flags) {
-  const hub = normalizeText(flags.hub || 'generic', 40).toLowerCase();
+  const hub = normalizeHub(flags.hub || 'generic') || 'generic';
   const sourceUrl = normalizeText(flags['source-url'] || flags['package-url'], 1000);
   const platformCommand = normalizeText(flags['platform-command'], 1000);
   const platformPrompt = await readPlatformPrompt(flags);
@@ -605,7 +660,7 @@ async function uploadPrompt(inspected, flags) {
 
 async function writePrompt(root, flags) {
   if (!flags.hub) {
-    throw new Error('Missing --hub <red|generic>.');
+    throw new Error(`Missing --hub <${SUPPORTED_HUBS.join('|')}>.`);
   }
   const inspected = await inspectSkill(root, flags);
   const prompt = await uploadPrompt(inspected, flags);
@@ -618,6 +673,84 @@ async function writePrompt(root, flags) {
   return prompt;
 }
 
+async function writeUnifiedHandoff(root, args) {
+  const relativeOutDir = path.relative(root, args.outDir) || WORK_DIR;
+  const promptIndex = args.promptResults
+    .map((item) => `- ${item.hub}: ${path.relative(root, item.promptPath)}`)
+    .join('\n');
+  const registry = args.inspected.registry || {};
+  const registryUrl = registry.registryUrl || DEFAULT_REGISTRY_URL;
+  const content = [
+    `# ${PRODUCT_NAME} Skill Upload Handoff`,
+    '',
+    `Skill: ${args.inspected.name}`,
+    `Skill Key: ${args.inspected.skillKey}`,
+    `Supported hubs prepared: ${args.hubs.join(', ')}`,
+    '',
+    '## How to use this file',
+    '',
+    'This is the single handoff file for the user\'s Agent. Do not ask the user to manually choose or inspect registry files.',
+    '',
+    'When the user later pastes an official third-party platform upload prompt, CLI command, or page instructions:',
+    '',
+    '1. Identify the target platform from that official prompt, URL, command, or user message.',
+    `2. Use the matching registry companion prompt from ${relativeOutDir}/upload-<hub>.md only as an internal checklist.`,
+    '3. Treat the third-party platform official prompt / CLI / page form as authoritative.',
+    `4. Merge only the safe ${PRODUCT_NAME} registry additions: public disclosure, source attribution, hub value, and optional runtime event callback.`,
+    '5. If the platform rejects extra files, do not upload registry JSON/snippets. Put the disclosure text into SKILL.md, README, or the platform description field only when allowed.',
+    '6. If the Skill exposes an MCP tool, API endpoint, webhook, script entrypoint, or Agent-executable function, add best-effort runtime event callbacks at the real invocation boundary.',
+    '7. Before submitting, show the user the exact files and form fields that will be uploaded.',
+    '8. Never upload .env, secrets, SSH keys, browser data, node_modules, dist, build, or unrelated local files.',
+    '',
+    '## Platform mapping',
+    '',
+    promptIndex,
+    '',
+    '## Official prompt merge rule',
+    '',
+    'If the user gives a Red Skill / ClawHub / SkillHub / Claude / Dify / Coze official prompt, do not replace it. Append these registry requirements as constraints, and follow the official prompt for packaging, file format, and upload steps.',
+    '',
+    'If the target platform is unclear, ask one short question: "Which Skill platform should I upload to?"',
+    '',
+    '## Analytics callback',
+    '',
+    `Registry endpoint: ${registryUrl}`,
+    `Event schema: ${registry.eventSchemaVersion || EVENT_SCHEMA_VERSION}`,
+    '',
+    'Only add runtime event callbacks when the target platform or runtime explicitly supports HTTP/API/MCP/webhook calls. Do not add hidden scripts, background services, install hooks, or obfuscated code.',
+    '',
+    'Best-effort callback placement:',
+    '',
+    '- Send `runtime_install_seen` once when a stable anonymous installation/session is first observed.',
+    '- Send `skill_invoked` at the start of the actual Skill execution, not when the upload prompt is generated.',
+    '- Send `skill_completed` after successful completion and `skill_failed` after handled failure.',
+    '- Use one stable anonymous `installationId` per installed copy/runtime connection. Never use email, phone, real name, device serial, raw prompt text, or private content.',
+    '- Use one `invocationId` per execution and use it in the idempotency key so retries do not double count.',
+    '',
+    'Required source separation:',
+    '',
+    '```json',
+    JSON.stringify({
+      hub: '<red|clawhub|skillhub|claude|dify|coze|generic>',
+      sourceSurface: '<same as hub unless the platform requires another public label>',
+      scenario: '<short public label only>',
+      installationId: '<stable anonymous install id>',
+      invocationId: '<unique invocation id>'
+    }, null, 2),
+    '```',
+    '',
+    'After a successful publication, record the public URL with:',
+    '',
+    '```bash',
+    `${COMMAND_NAME} track . --event hub_upload_succeeded --hub <hub> --platform-skill-url <published-url>`,
+    '```',
+    ''
+  ].join('\n');
+  const handoffPath = path.join(args.outDir, HANDOFF_FILE);
+  await writeFile(handoffPath, content, { mode: 0o600 });
+  return handoffPath;
+}
+
 async function writeRuntimeSnippet(root, flags) {
   const inspected = await inspectSkill(root, flags);
   const registry = inspected.registry || {};
@@ -727,7 +860,7 @@ async function submitTrackEvent(root, flags) {
   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 hub = normalizeHub(flags.hub || 'local-test') || 'local-test';
   const payload = {
     publicToken,
     schemaVersion: normalizeText(flags['schema-version'], 80) || EVENT_SCHEMA_VERSION,
@@ -759,7 +892,7 @@ async function submitTrackEvent(root, flags) {
 }
 
 async function setupAgentWorkflow(root, flags) {
-  const hub = normalizeText(flags.hub || 'generic', 40).toLowerCase();
+  const hubs = setupHubsFromFlags(flags);
   const absoluteRoot = path.resolve(root || '.');
   const outDir = path.resolve(flags['out-dir'] || path.join(absoluteRoot, WORK_DIR));
   await mkdir(outDir, { recursive: true });
@@ -769,12 +902,19 @@ async function setupAgentWorkflow(root, flags) {
     '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 promptResults = [];
+  for (const hub of hubs) {
+    const promptPath = path.join(outDir, `upload-${safeSkillKey(hub)}.md`);
+    const promptResult = await writePrompt(absoluteRoot, { ...flags, hub, out: promptPath });
+    promptResults.push({
+      hub,
+      promptPath: typeof promptResult === 'string' ? promptPath : promptResult.outPath
+    });
+  }
   const inspectedAfterManifest = await inspectSkill(absoluteRoot, flags);
-  const shouldEmbedSkillMd = Boolean(flags['embed-skill-md']) || (hub === 'red' && !flags['no-skill-md']);
+  const shouldEmbedSkillMd = Boolean(flags['embed-skill-md']) || (hubs.includes('red') && !flags['no-skill-md']);
   const skillMdPath = shouldEmbedSkillMd
-    ? await writeSkillMdRegistryBlock(absoluteRoot, inspectedAfterManifest, hub)
+    ? await writeSkillMdRegistryBlock(absoluteRoot, inspectedAfterManifest, hubs.join(','))
     : null;
   const disclosurePath = path.join(outDir, 'REGISTRY_DISCLOSURE.md');
   await writeFile(
@@ -793,43 +933,55 @@ async function setupAgentWorkflow(root, flags) {
       out: snippetPath
     });
   }
+  const handoffPath = await writeUnifiedHandoff(absoluteRoot, {
+    outDir,
+    hubs,
+    inspected: inspectedAfterManifest,
+    promptResults
+  });
 
   const warnings = [];
-  let promptEvent = null;
+  const promptEvents = [];
   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)}`);
+    for (const hub of hubs) {
+      try {
+        const promptEvent = await submitTrackEvent(absoluteRoot, {
+          ...flags,
+          hub,
+          event: 'upload_prompt_generated',
+          'event-source': 'cli',
+          'runtime-kind': 'agent-handoff',
+          scenario: flags.scenario || `third-party-skill-upload:${hub}`,
+          'idempotency-key': `upload_prompt_generated:${hub}:${inspectedAfterManifest.package.sha256}`
+        });
+        promptEvents.push({ hub, promptEvent });
+      } catch (error) {
+        warnings.push(`upload_prompt_generated for ${hub} was not recorded: ${error instanceof Error ? error.message : String(error)}`);
+      }
     }
   }
 
   return {
     ok: true,
-    hub,
+    hubs,
     manifestPath: manifestResult.manifestPath,
-    promptPath: typeof promptResult === 'string' ? promptPath : promptResult.outPath,
+    handoffPath,
+    promptPaths: promptResults,
     skillMdPath,
     disclosurePath,
     snippetPath: snippetResult ? snippetResult.outPath : null,
-    promptEvent,
+    promptEvents,
     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, handoffPath)} as the single Agent handoff. The Agent should not ask the user to manually pick registry files.`,
+      'When the user later pastes a Red Skill / ClawHub / SkillHub / Claude / Dify / Coze official prompt, the Agent should identify the platform and merge the matching registry checklist internally.',
+      'Each prepared upload-<hub>.md pins the correct hub/sourceSurface value so platform analytics stay separated, but those files are internal checklists for the Agent.',
       skillMdPath
         ? `Registry disclosure was also embedded into ${path.relative(absoluteRoot, skillMdPath)} for restrictive hubs.`
         : `If the hub rejects extra files, rerun with --embed-skill-md to place registry disclosure inside SKILL.md.`,
       `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>`,
+      `If the Skill is published, record the public URL with: ${COMMAND_NAME} track . --event hub_upload_succeeded --hub <red|clawhub|skillhub|claude|dify|coze|generic> --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.'
@@ -865,7 +1017,8 @@ async function main() {
       } else {
         const lines = [
           `Wrote ${result.manifestPath}`,
-          `Wrote ${result.promptPath}`,
+          `Wrote ${result.handoffPath}`,
+          ...result.promptPaths.map((item) => `Wrote ${item.promptPath}`),
           `Wrote ${result.disclosurePath}`,
           result.snippetPath ? `Wrote ${result.snippetPath}` : null,
           ...result.warnings.map((warning) => `Warning: ${warning}`),

package/package.json

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