@xiashe/skill 0.1.5 → 0.1.7

package/README.md

@@ -10,6 +10,8 @@ This package is intentionally separate from the full `@xiashe/cli` product CLI a
 
 - inspect a local Skill project
 - 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 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
@@ -23,8 +25,11 @@ It does not create upload packages, copy source directories, install background
 ```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

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.5';
+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');
@@ -49,6 +49,8 @@ Usage:
   ${COMMAND_NAME} inspect [skill-dir] [--json]
   ${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|coze|generic> [--source-url <url>] [--out <file>]
@@ -637,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。只发送公开元数据和聚合事件，不发送用户内容、私密输入或账号凭据。`,
     '',
@@ -719,6 +723,8 @@ async function writeUnifiedHandoff(root, args) {
     '',
     '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.',
@@ -744,6 +750,14 @@ async function writeUnifiedHandoff(root, args) {
     '```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);
@@ -891,6 +905,209 @@ 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 hubs = setupHubsFromFlags(flags);
   const absoluteRoot = path.resolve(root || '.');
@@ -1010,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) {

package/package.json

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