@xiashe/skill 0.1.1 → 0.1.4

package/bin/xiashe-skill.mjs

@@ -1,24 +1,27 @@
 #!/usr/bin/env node
 
-import { createHash } from 'node:crypto';
+import { createHash, createHmac } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-const VERSION = '0.1.1';
+const VERSION = '0.1.4';
 const COMMAND_NAME = process.env.XIASHE_SKILL_CLI_NAME || 'xiashe-skill';
 const PRODUCT_NAME = process.env.XIASHE_SKILL_PRODUCT_NAME || (COMMAND_NAME === 'agentpie-skill' ? 'AgentPie' : 'XiaShe');
 const REGISTRY_PROVIDER = process.env.XIASHE_SKILL_REGISTRY_PROVIDER || (COMMAND_NAME === 'agentpie-skill' ? 'agentpie' : 'xiashe');
 const DEFAULT_BASE_URL = process.env.XIASHE_SKILL_DEFAULT_BASE_URL || (COMMAND_NAME === 'agentpie-skill'
-  ? 'https://api.agentpie.app'
-  : 'https://api.xiashe.chat');
+  ? 'https://actions.agentpie.app'
+  : 'https://actions.xiashe.chat');
 const MANIFEST_FILE = process.env.XIASHE_SKILL_MANIFEST_FILE || (COMMAND_NAME === 'agentpie-skill'
   ? 'agentpie.skill.json'
   : 'xiashe.skill.json');
 const WORK_DIR = process.env.XIASHE_SKILL_WORK_DIR || (COMMAND_NAME === 'agentpie-skill' ? '.agentpie' : '.xiashe');
 const DEFAULT_REGISTRY_URL = process.env.XIASHE_SKILL_REGISTRY_URL || `${DEFAULT_BASE_URL}/registry/skill-events`;
 const DEFAULT_CLAIM_URL = process.env.XIASHE_SKILL_CLAIM_URL || `${DEFAULT_BASE_URL}/registry/skill/claim`;
+const 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',
@@ -41,11 +44,11 @@ function usage() {
 
 Usage:
   ${COMMAND_NAME} inspect [skill-dir] [--json]
-  ${COMMAND_NAME} setup [skill-dir] --code <dynamic-code> --hub <red|clawhub|skillhub|generic>
-  ${COMMAND_NAME} setup [skill-dir] --public-token <token> --skill-id <id> --hub <red|clawhub|skillhub|generic>
+  ${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} prompt [skill-dir] --hub <red|clawhub|skillhub|generic> [--source-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>]
 
@@ -57,7 +60,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, or generic.
+  --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.
@@ -67,10 +70,13 @@ Options:
   --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}/.
+  --embed-skill-md            Also write a clearly marked registry section into SKILL.md.
+  --no-skill-md               Do not write registry text into SKILL.md. Red hub embeds by default.
   --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.
@@ -87,7 +93,7 @@ function fail(message, code = 1) {
 
 function parseArgs(argv) {
   const args = { _: [], json: false, dryRun: false };
-  const booleanFlags = new Set(['no-snippet', 'no-track']);
+  const booleanFlags = new Set(['embed-skill-md', 'no-skill-md', 'no-snippet', 'no-track']);
   for (let i = 0; i < argv.length; i += 1) {
     const value = argv[i];
     if (value === '--help' || value === '-h') {
@@ -144,6 +150,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 {
@@ -307,6 +333,11 @@ 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: [
@@ -349,6 +380,12 @@ function hubInstruction(hub) {
   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 要求作为附加说明合并进去。';
 }
 
@@ -362,6 +399,12 @@ function platformPromptPlaceholder(hub) {
   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 替代平台官方流程。';
 }
 
@@ -401,6 +444,55 @@ function publicDisclosure(inspected, registryUrl) {
   ];
 }
 
+function skillMdRegistryBlock(inspected, hub) {
+  const registry = inspected.registry || {};
+  const registryUrl = registry.registryUrl || DEFAULT_REGISTRY_URL;
+  const publicToken = registry.publicToken || '<public token from registry manifest>';
+  const marker = `${REGISTRY_PROVIDER}-registry`;
+  return [
+    `<!-- ${marker}:start -->`,
+    `## ${PRODUCT_NAME} Registry / Analytics`,
+    '',
+    `This Skill is explicitly registered by its creator with ${PRODUCT_NAME} for public attribution and aggregated analytics.`,
+    '',
+    `- Registry provider: ${REGISTRY_PROVIDER}`,
+    `- Skill key: ${inspected.skillKey}`,
+    `- Target hub: ${hub}`,
+    `- Registry event endpoint: ${registryUrl}`,
+    `- Public write token: ${publicToken}`,
+    `- Event schema version: ${registry.eventSchemaVersion || EVENT_SCHEMA_VERSION}`,
+    `- Source fingerprint: ${inspected.package.sha256}`,
+    '',
+    'Analytics boundary:',
+    '- The public token can only submit allowed aggregate analytics events. It cannot read creator data or administer the account.',
+    '- Events should include only public metadata: hub, sourceSurface, campaign, scenario, anonymous installationId, invocationId, and status.',
+    '- Do not send user prompts, private files, credentials, environment variables, account tokens, raw business content, or personal identifiers.',
+    '- The creator can rotate/revoke the token or disable analytics from the dashboard.',
+    '',
+    'Recommended runtime events, if the target platform supports callbacks:',
+    '- `runtime_install_seen` when a stable anonymous installation is first observed.',
+    '- `skill_invoked` when a Skill invocation starts.',
+    '- `skill_completed` when an invocation completes.',
+    '- `skill_failed` when an invocation fails.',
+    '',
+    `<!-- ${marker}:end -->`
+  ].join('\n');
+}
+
+async function writeSkillMdRegistryBlock(root, inspected, hub) {
+  const skillMdPath = path.join(root, 'SKILL.md');
+  const existing = existsSync(skillMdPath)
+    ? await readFile(skillMdPath, 'utf8')
+    : `# ${inspected.name}\n\n${inspected.description || ''}\n`;
+  const block = skillMdRegistryBlock(inspected, hub);
+  const pattern = /<!-- (?:xiashe|agentpie)-registry:start -->[\s\S]*?<!-- (?:xiashe|agentpie)-registry:end -->/m;
+  const next = pattern.test(existing)
+    ? existing.replace(pattern, block)
+    : `${existing.trimEnd()}\n\n${block}\n`;
+  await writeFile(skillMdPath, next, { mode: 0o600 });
+  return skillMdPath;
+}
+
 async function readPlatformPrompt(flags) {
   const promptPath = normalizeText(flags['platform-prompt-file'], 1000);
   if (!promptPath) return '';
@@ -424,15 +516,18 @@ async function uploadPrompt(inspected, flags) {
   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>',
@@ -440,6 +535,7 @@ async function uploadPrompt(inspected, flags) {
     skillKey: inspected.skillKey,
     installationId: '<stable anonymous install id>',
     invocationId: '<unique invocation id>',
+    idempotencyKey: '<unique invocation id>:skill_invoked',
     scenario: '<short usage scenario label only>',
     sourceSurface: '<profile|hub|agent|direct>',
     campaign: '<optional promotion label>'
@@ -527,6 +623,7 @@ async function writeRuntimeSnippet(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'
     ? [
@@ -534,6 +631,7 @@ async function writeRuntimeSnippet(root, flags) {
         "  -H 'content-type: application/json' \\",
         '  -d ' + JSON.stringify(JSON.stringify({
           publicToken,
+          schemaVersion: eventSchemaVersion,
           eventType: 'skill_invoked',
           eventSource: 'runtime',
           runtimeKind: 'mcp',
@@ -541,31 +639,62 @@ async function writeRuntimeSnippet(root, flags) {
           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({',
-        '      publicToken: XIASHE_SKILL_PUBLIC_TOKEN,',
-        '      eventType,',
-        "      eventSource: options.eventSource || 'runtime',",
-        "      runtimeKind: options.runtimeKind || 'mcp',",
-        `      skillKey: ${JSON.stringify(inspected.skillKey)},`,
-        '      hub: options.hub,',
-        '      installationId: options.installationId,',
-        '      invocationId: options.invocationId,',
-        '      scenario: options.scenario,',
-        '      sourceSurface: options.sourceSurface,',
-        '      campaign: options.campaign,',
-        '      packageSha256: options.packageSha256',
-        '    })',
+        '    body: JSON.stringify(payload)',
         '  });',
         '}',
         '',
@@ -595,22 +724,33 @@ async function submitTrackEvent(root, flags) {
   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: normalizeText(flags.hub || 'local-test', 80),
+    hub,
     skillKey: inspected.skillKey,
-    installationId: normalizeText(flags['installation-id'] || 'local-test-install', 220),
-    invocationId: normalizeText(flags['invocation-id'] || `cli-${Date.now()}`, 160),
+    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) || undefined
+    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 };
   }
@@ -631,6 +771,19 @@ async function setupAgentWorkflow(root, flags) {
 
   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 shouldEmbedSkillMd = Boolean(flags['embed-skill-md']) || (hub === 'red' && !flags['no-skill-md']);
+  const skillMdPath = shouldEmbedSkillMd
+    ? await writeSkillMdRegistryBlock(absoluteRoot, inspectedAfterManifest, hub)
+    : null;
+  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']) {
@@ -663,12 +816,18 @@ async function setupAgentWorkflow(root, flags) {
     hub,
     manifestPath: manifestResult.manifestPath,
     promptPath: typeof promptResult === 'string' ? promptPath : promptResult.outPath,
+    skillMdPath,
+    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.`,
+      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>`,
       snippetResult
@@ -707,6 +866,7 @@ async function main() {
         const lines = [
           `Wrote ${result.manifestPath}`,
           `Wrote ${result.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.1",
+  "version": "0.1.4",
   "type": "module",
   "bin": {
     "xiashe-skill": "bin/xiashe-skill.mjs"