@xiashe/skill 0.1.4 → 0.1.7

package/README.md

@@ -9,22 +9,30 @@ 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
+- diagnose whether a local Skill has the expected registry disclosure and runtime callback wiring
+- send labeled local verification events so the Dashboard can confirm integration health
 - 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 doctor .
+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 verify . --hub red --dry-run --json
+node packages/xiashe-skill-cli/bin/xiashe-skill.mjs verify . --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.7';
 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,13 @@ 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} doctor [skill-dir] [--json]
+  ${COMMAND_NAME} verify [skill-dir] [--hub <hub>] [--scenario <label>] [--dry-run]
   ${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 +65,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 +155,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 +376,7 @@ async function writeManifest(root, flags) {
       },
       analytics: {
         enabled: true,
+        supportedHubs: [...SUPPORTED_HUBS],
         allowedEvents: [
           'upload_prompt_generated',
           'hub_upload_attempted',
@@ -353,6 +390,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 +437,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 +459,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 +565,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);
@@ -582,8 +639,10 @@ async function uploadPrompt(inspected, flags) {
     '- 不要新增 postinstall hook、后台常驻进程、隐藏脚本或混淆逻辑。',
     `- 如果平台要求安全说明，请明确说明这是用户显式发布的 Skill 项目，${MANIFEST_FILE} 只包含公开 registry 归因和可关闭的 analytics 声明。`,
     `- 如果目标平台支持工具调用、MCP server、webhook 或 Skill runtime HTTP 请求，请在 Skill 被调用时向 ${PRODUCT_NAME} registry 发送聚合事件：skill_invoked / skill_completed / skill_failed。`,
+    `- 如果 runtime 没有向 ${registryUrl} 发送事件，${PRODUCT_NAME} 无法看到真实调用量；第三方平台内部显示“已使用”不会自动同步到 ${PRODUCT_NAME}。`,
     '- 事件里只放公开元数据、聚合状态和简短场景标签，不要发送用户输入原文、私密业务内容、账号凭据或文件内容。',
     '- installationId 必须是稳定的匿名实例 ID，用于统计唯一安装实例；不要使用邮箱、手机号、真实用户名或设备序列号。',
+    '- 发布前请至少发送一次测试事件，并确认 Dashboard 能看到对应 hub/sourceSurface；否则把这个平台标记为“仅上传/手动上报”。',
     '',
     `发布成功后，请把公开链接和平台返回的信息回传给${PRODUCT_NAME} registry。只发送公开元数据和聚合事件，不发送用户内容、私密输入或账号凭据。`,
     '',
@@ -605,7 +664,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 +677,94 @@ 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.',
+    '',
+    `No runtime callback means no live ${PRODUCT_NAME} analytics. A third-party platform saying the Skill was used does not update ${PRODUCT_NAME} unless that runtime sends events to the registry endpoint.`,
+    '',
+    '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>`,
+    '```',
+    '',
+    'Before submitting to a hub that supports runtime HTTP/API calls, verify analytics with:',
+    '',
+    '```bash',
+    `${COMMAND_NAME} track . --event skill_invoked --hub <hub> --installation-id <anonymous-install-id> --invocation-id <test-call-id> --scenario test`,
+    '```',
+    '',
+    'If the hub cannot run callbacks, keep upload attribution and use campaign links or manual imports. Do not fake runtime events.',
+    ''
+  ].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 +874,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,
@@ -758,8 +905,211 @@ async function submitTrackEvent(root, flags) {
   return { ok: true, registryUrl, payload, result };
 }
 
+async function readSmallTextFile(filePath) {
+  const info = await stat(filePath).catch(() => null);
+  if (!info?.isFile() || info.size > MAX_FILE_BYTES) return '';
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+async function findReadmePath(root) {
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+  const readme = entries
+    .filter((entry) => entry.isFile() && /^readme(\.|$)/i.test(entry.name))
+    .map((entry) => path.join(root, entry.name))
+    .sort((a, b) => a.localeCompare(b))[0];
+  return readme || path.join(root, 'README.md');
+}
+
+function registryBlockPresent(text) {
+  return /<!--\s*(?:xiashe|agentpie)-registry:start\s*-->[\s\S]*?<!--\s*(?:xiashe|agentpie)-registry:end\s*-->/i.test(text || '');
+}
+
+function hasEntryInstructions(text, packageJson) {
+  if (packageJson?.main || packageJson?.bin || packageJson?.scripts) return true;
+  return /(入口|使用|安装|运行|调用|命令|Usage|Install|Quick start|Getting started|CLI|MCP|API|Entrypoint|Run)/i.test(text || '');
+}
+
+function hasRuntimeCallbackText(text) {
+  return /(\/registry\/skill-events|trackSkillEvent|runtime_install_seen|skill_invoked|skill_completed|skill_failed|XIASHE_SKILL_REGISTRY_URL|AGENTPIE_SKILL_REGISTRY_URL)/i.test(text || '');
+}
+
+function doctorCheck(id, label, status, message, fix = '') {
+  return { id, label, status, message, fix };
+}
+
+async function runDoctor(root, flags) {
+  const inspected = await inspectSkill(root, flags);
+  const skillMdPath = path.join(inspected.root, 'SKILL.md');
+  const readmePath = await findReadmePath(inspected.root);
+  const manifestPath = path.join(inspected.root, MANIFEST_FILE);
+  const localManifestPath = path.join(inspected.root, WORK_DIR, MANIFEST_FILE);
+  const disclosurePath = path.join(inspected.root, WORK_DIR, 'REGISTRY_DISCLOSURE.md');
+  const handoffPath = path.join(inspected.root, WORK_DIR, HANDOFF_FILE);
+  const snippetPath = path.join(inspected.root, WORK_DIR, 'runtime-events.js');
+  const packageJson = await readJsonFile(path.join(inspected.root, 'package.json')).catch(() => null);
+  const skillMd = await readSmallTextFile(skillMdPath);
+  const readme = await readSmallTextFile(readmePath);
+  const snippet = await readSmallTextFile(snippetPath);
+  const scannedCallbackFiles = [];
+  let scannedCallbackText = '';
+  for (const file of inspected.package.files.slice(0, 160)) {
+    if (!/\.(md|mdx|txt|json|ya?ml|toml|js|mjs|cjs|ts|tsx|jsx|py|go|rs|java|rb|php|sh)$/i.test(file.path)) continue;
+    const absolute = path.join(inspected.root, file.path);
+    const text = await readSmallTextFile(absolute);
+    if (hasRuntimeCallbackText(text)) {
+      scannedCallbackFiles.push(file.path);
+      scannedCallbackText += `\n${text}`;
+    }
+  }
+  const manifest = inspected.registry
+    ? await readJsonFile(manifestPath).catch(() => null) || await readJsonFile(localManifestPath).catch(() => null)
+    : null;
+  const textBundle = `${skillMd}\n${readme}`;
+  const hasManifest = Boolean(manifest);
+  const registry = manifest?.registry || inspected.registry || {};
+  const runtimeCallbackPresent = hasRuntimeCallbackText(snippet) || hasRuntimeCallbackText(textBundle) || hasRuntimeCallbackText(scannedCallbackText);
+  const riskyRootEntries = ['.env', '.env.local', '.env.production', 'node_modules', 'dist', 'build']
+    .filter((name) => existsSync(path.join(inspected.root, name)));
+  const checks = [
+    existsSync(skillMdPath)
+      ? doctorCheck('skill_md', 'SKILL.md', 'pass', 'Found SKILL.md.')
+      : doctorCheck('skill_md', 'SKILL.md', 'fail', 'SKILL.md is missing.', 'Create SKILL.md with the Skill purpose, usage, and safety notes.'),
+    existsSync(readmePath)
+      ? doctorCheck('readme', 'README', 'pass', `Found ${path.basename(readmePath)}.`)
+      : doctorCheck('readme', 'README', 'warn', 'README is missing.', 'Add README.md if the target hub expects public documentation.'),
+    hasEntryInstructions(textBundle, packageJson)
+      ? doctorCheck('entry_instructions', 'Entry instructions', 'pass', 'Usage or entry instructions are present.')
+      : doctorCheck('entry_instructions', 'Entry instructions', 'warn', 'No clear usage/entry instructions detected.', 'Add usage, install, MCP/API, or command instructions to SKILL.md or README.'),
+    hasManifest && registry.publicToken && registry.registryUrl
+      ? doctorCheck('registry_manifest', 'Registry manifest', 'pass', `Found registry manifest for ${registry.provider || REGISTRY_PROVIDER}.`)
+      : doctorCheck('registry_manifest', 'Registry manifest', 'fail', `Missing usable registry manifest (${MANIFEST_FILE} or ${WORK_DIR}/${MANIFEST_FILE}).`, `Run ${COMMAND_NAME} setup . --code <dashboard-code> or ${COMMAND_NAME} attach . --public-token <token> --skill-id <id>.`),
+    registryBlockPresent(skillMd)
+      ? doctorCheck('registry_block', 'Registry block', 'pass', 'SKILL.md contains the explicit registry disclosure block.')
+      : doctorCheck('registry_block', 'Registry block', 'warn', 'SKILL.md does not contain a registry block.', `Run ${COMMAND_NAME} setup . --code <code> --embed-skill-md, especially for restrictive hubs such as Red Skill.`),
+    runtimeCallbackPresent
+      ? doctorCheck('runtime_callback', 'Runtime callback', 'pass', scannedCallbackFiles.length > 0 ? `Runtime callback references found in ${scannedCallbackFiles.slice(0, 5).join(', ')}.` : 'Runtime callback snippet/reference detected.')
+      : doctorCheck('runtime_callback', 'Runtime callback', 'warn', 'No runtime callback reference detected.', `Use ${COMMAND_NAME} snippet . --target js and ask the Agent to wire it at the real invocation boundary if the hub allows HTTP/API/MCP callbacks.`),
+    existsSync(disclosurePath)
+      ? doctorCheck('disclosure', 'Read-only disclosure', 'pass', `Found ${path.relative(inspected.root, disclosurePath)}.`)
+      : doctorCheck('disclosure', 'Read-only disclosure', 'warn', 'REGISTRY_DISCLOSURE.md is missing.', `Run ${COMMAND_NAME} setup . --code <code> to generate platform review disclosure.`),
+    existsSync(handoffPath)
+      ? doctorCheck('handoff', 'Agent handoff', 'pass', `Found ${path.relative(inspected.root, handoffPath)}.`)
+      : doctorCheck('handoff', 'Agent handoff', 'warn', 'Unified upload handoff is missing.', `Run ${COMMAND_NAME} setup . --code <code> --hub all.`),
+    riskyRootEntries.length === 0
+      ? doctorCheck('risky_files', 'Risky local files', 'pass', 'No common risky root files/directories detected.')
+      : doctorCheck('risky_files', 'Risky local files', 'warn', `Found ${riskyRootEntries.join(', ')} in the Skill root.`, 'Do not upload secrets, node_modules, dist/build output, or unrelated local files unless the target hub explicitly requires them.')
+  ];
+  const failed = checks.filter((check) => check.status === 'fail').length;
+  const warned = checks.filter((check) => check.status === 'warn').length;
+  const passed = checks.filter((check) => check.status === 'pass').length;
+  const score = Math.max(0, Math.round((passed / checks.length) * 100) - failed * 15 - warned * 4);
+  return {
+    ok: failed === 0,
+    score,
+    root: inspected.root,
+    skillKey: inspected.skillKey,
+    name: inspected.name,
+    package: inspected.package,
+    checks,
+    next: checks
+      .filter((check) => check.status !== 'pass' && check.fix)
+      .map((check) => check.fix)
+      .slice(0, 6)
+  };
+}
+
+function formatDoctor(result) {
+  const statusIcon = { pass: 'PASS', warn: 'WARN', fail: 'FAIL' };
+  const lines = [
+    `${COMMAND_NAME} doctor`,
+    `Skill: ${result.name} (${result.skillKey})`,
+    `Score: ${result.score}/100`,
+    ''
+  ];
+  for (const check of result.checks) {
+    lines.push(`${statusIcon[check.status] || check.status} ${check.label}: ${check.message}`);
+    if (check.status !== 'pass' && check.fix) lines.push(`  Fix: ${check.fix}`);
+  }
+  if (result.next.length > 0) {
+    lines.push('', 'Next:');
+    for (const item of result.next) lines.push(`- ${item}`);
+  }
+  return lines.join('\n');
+}
+
+async function verifyRegistry(root, flags) {
+  const inspected = await inspectSkill(root, flags);
+  const hub = normalizeHub(flags.hub || 'generic') || 'generic';
+  const scenario = normalizeText(flags.scenario || `${REGISTRY_PROVIDER}-skill-verify`, 120);
+  const timestamp = Date.now();
+  const installationId = normalizeText(flags['installation-id'] || `verify-${REGISTRY_PROVIDER}-${timestamp}`, 220);
+  const invocationId = normalizeText(flags['invocation-id'] || `verify-call-${timestamp}`, 160);
+  const events = normalizeText(flags.events || '', 400)
+    ? normalizeText(flags.events, 400).split(',').map((item) => normalizeText(item, 80)).filter(Boolean)
+    : ['runtime_install_seen', 'skill_invoked', 'skill_completed'];
+  const results = [];
+  for (const eventType of events) {
+    const eventResult = await submitTrackEvent(root, {
+      ...flags,
+      event: eventType,
+      hub,
+      'event-source': 'runtime',
+      'runtime-kind': 'cli-verify',
+      'source-surface': hub,
+      scenario,
+      'installation-id': installationId,
+      'invocation-id': invocationId,
+      'idempotency-key': `verify:${inspected.skillKey}:${hub}:${invocationId}:${eventType}`
+    });
+    results.push({ eventType, ...eventResult });
+  }
+  return {
+    ok: results.every((result) => result.ok),
+    dryRun: Boolean(flags.dryRun),
+    skillKey: inspected.skillKey,
+    hub,
+    scenario,
+    installationId,
+    invocationId,
+    registryUrl: results[0]?.registryUrl || inspected.registry?.registryUrl || DEFAULT_REGISTRY_URL,
+    events: results,
+    next: [
+      'Open the creator dashboard and check 接入健康度 / Integration health.',
+      'Verified should become active after these cli-verify events are indexed.',
+      'If runtime remains inactive later, the third-party platform is not calling /registry/skill-events from real Skill execution.'
+    ]
+  };
+}
+
+function formatVerify(result) {
+  const lines = [
+    `${COMMAND_NAME} verify`,
+    `Skill key: ${result.skillKey}`,
+    `Hub: ${result.hub}`,
+    `Scenario: ${result.scenario}`,
+    `Installation: ${result.installationId}`,
+    `Invocation: ${result.invocationId}`,
+    `Endpoint: ${result.registryUrl}`,
+    ''
+  ];
+  for (const item of result.events) {
+    if (item.dryRun) {
+      lines.push(`DRY ${item.eventType}: ${JSON.stringify(item.payload)}`);
+    } else {
+      lines.push(`OK ${item.eventType}: ${item.result?.eventId || item.result?.status || 'accepted'}`);
+    }
+  }
+  lines.push('', 'Next:');
+  for (const item of result.next) lines.push(`- ${item}`);
+  return lines.join('\n');
+}
+
 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 +1119,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 +1150,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.'
@@ -858,6 +1227,19 @@ async function main() {
       print(result, flags.json);
       return;
     }
+    if (command === 'doctor') {
+      const result = await runDoctor(root, flags);
+      print(flags.json ? result : formatDoctor(result), flags.json);
+      if (!result.ok) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    if (command === 'verify') {
+      const result = await verifyRegistry(root, flags);
+      print(flags.json ? result : formatVerify(result), flags.json);
+      return;
+    }
     if (command === 'setup' || command === 'handoff') {
       const result = await setupAgentWorkflow(root, flags);
       if (flags.json) {
@@ -865,7 +1247,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.7",
   "type": "module",
   "bin": {
     "xiashe-skill": "bin/xiashe-skill.mjs"