@xiashe/skill 0.1.8 → 0.1.12

package/README.md

@@ -11,7 +11,8 @@ This package is intentionally separate from the full `@xiashe/cli` product CLI a
 - inspect a local Skill project
 - run one high-level Agent-friendly publish handoff command
 - run lower-level registry setup commands that prepare all supported hub handoffs
-- diagnose whether a local Skill has the expected registry disclosure and runtime callback wiring
+- generate a public-safe Agent Ack block for anonymous cross-platform install and call analytics
+- diagnose whether a local Skill has the expected registry disclosure, Agent Ack instructions, and runtime callback wiring where supported
 - 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
@@ -21,7 +22,7 @@ It does not install background services, run postinstall hooks, read secrets, or
 
 The user-facing product flow should point creators at the official publish Markdown page and the `xiashe-publish` Skill. Direct CLI commands are implementation details for local Agents and developers.
 
-`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`.
+`setup --hub all` still writes platform-specific `upload-<hub>.md` checklists for source attribution, but those are internal Agent checklists. It also writes `.xiashe/AGENT_ACK.md`, a public-safe block that can be copied into platform-allowed Skill instructions so Agents can report anonymous installs and calls. Users should not need to pick files manually. When Red Skill provides `uploader.md`, `skillhub-upload`, or its own upload prompt, follow that official flow first; XiaShe keeps registry files and callback snippets local by default and records Red usage through Agent Ack when the host Agent calls it, or as attribution/reported data otherwise.
 
 ## Local development
 

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.7';
+const VERSION = '0.1.12';
 const COMMAND_NAME = process.env.XIASHE_SKILL_CLI_NAME || 'xiashe-skill';
 const PRODUCT_NAME = process.env.XIASHE_SKILL_PRODUCT_NAME || (COMMAND_NAME === 'agentpie-skill' ? 'AgentPie' : 'XiaShe');
 const REGISTRY_PROVIDER = process.env.XIASHE_SKILL_REGISTRY_PROVIDER || (COMMAND_NAME === 'agentpie-skill' ? 'agentpie' : 'xiashe');
@@ -19,6 +19,7 @@ const MANIFEST_FILE = process.env.XIASHE_SKILL_MANIFEST_FILE || (COMMAND_NAME ==
 const WORK_DIR = process.env.XIASHE_SKILL_WORK_DIR || (COMMAND_NAME === 'agentpie-skill' ? '.agentpie' : '.xiashe');
 const HANDOFF_FILE = 'UPLOAD_HANDOFF.md';
 const DEFAULT_REGISTRY_URL = process.env.XIASHE_SKILL_REGISTRY_URL || `${DEFAULT_BASE_URL}/registry/skill-events`;
+const DEFAULT_AGENT_ACK_URL = process.env.XIASHE_SKILL_AGENT_ACK_URL || `${DEFAULT_BASE_URL}/registry/agent-ack`;
 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'
@@ -40,20 +41,30 @@ const PLATFORM_REVIEW_PROFILES = {
     label: 'Red Skill',
     packageMode: 'markdown_or_text_only',
     manifestPolicy: 'local_only',
-    disclosurePlacement: ['SKILL.md', 'README', 'platform description field'],
-    runtimeDataPolicy: 'attribution_only_by_default',
-    defaultDataSource: 'attribution',
-    allowedFilePolicy: 'Upload only Markdown/TXT or fields accepted by the official Red Skill flow.',
-    forbiddenPublicFiles: [WORK_DIR, `${WORK_DIR}/${MANIFEST_FILE}`, `${WORK_DIR}/runtime-events.js`, 'public tokens', 'signing secrets', 'internal handoff/checklists']
+    disclosurePlacement: ['platform description field', 'README', 'SKILL.md'],
+    runtimeDataPolicy: 'agent_ack_supported',
+    defaultDataSource: 'runtime',
+    allowedFilePolicy: 'Follow the official Red Skill uploader.md / skillhub-upload flow. XiaShe does not require extra registry files, callback code, or runtime analytics for Red review. Add the public Agent Ack instructions only where Red allows Skill instructions or README content.',
+    xiasheLocalOnlyFiles: [WORK_DIR, `${WORK_DIR}/${MANIFEST_FILE}`, `${WORK_DIR}/runtime-events.js`, 'internal handoff/checklists'],
+    forbiddenPublicFiles: ['credentials', 'cookies', 'browser/account sessions', 'public tokens', 'signing secrets', 'hidden telemetry'],
+    safetyChecklist: [
+      '功能描述真实、清晰、有实际使用价值，不夸大或误导用户。',
+      '只声明 Skill 实际需要的权限和用途，不请求超出功能范围的权限。',
+      '不内置自动运营小红书账号、自动发笔记、自动回复评论等破坏社区真实性的能力。',
+      '不提供违法违规服务、违禁信息传播、违规图片生成、博彩赔率分析等能力。',
+      '不植入恶意代码，不窃取 Cookie、账号凭据、本地文件或浏览器数据。',
+      '不通过隐藏 prompt、后门、混淆逻辑或未披露功能篡改 Agent 行为。',
+      '尊重原创，不搬运、抄袭或伪装他人 Skill。'
+    ]
   },
   clawhub: {
     label: 'ClawHub',
     packageMode: 'markdown_or_text_only',
     manifestPolicy: 'local_only',
     disclosurePlacement: ['SKILL.md', 'README', 'platform description field'],
-    runtimeDataPolicy: 'attribution_only_by_default',
-    defaultDataSource: 'attribution',
-    allowedFilePolicy: 'Follow ClawHub official file rules. Treat XiaShe registry files as local-only unless ClawHub explicitly accepts them.',
+    runtimeDataPolicy: 'agent_ack_supported',
+    defaultDataSource: 'runtime',
+    allowedFilePolicy: 'Follow ClawHub official file rules. Treat XiaShe registry files as local-only unless ClawHub explicitly accepts them. Add public Agent Ack instructions where ClawHub allows Skill instructions.',
     forbiddenPublicFiles: [WORK_DIR, `${WORK_DIR}/${MANIFEST_FILE}`, `${WORK_DIR}/runtime-events.js`, 'public tokens', 'signing secrets']
   },
   skillhub: {
@@ -61,9 +72,9 @@ const PLATFORM_REVIEW_PROFILES = {
     packageMode: 'markdown_or_text_only',
     manifestPolicy: 'local_only',
     disclosurePlacement: ['SKILL.md', 'README', 'platform description field'],
-    runtimeDataPolicy: 'attribution_only_by_default',
-    defaultDataSource: 'attribution',
-    allowedFilePolicy: 'Upload only files accepted by SkillHub. For Markdown/TXT-only flows, copy disclosure text into an allowed field.',
+    runtimeDataPolicy: 'agent_ack_supported',
+    defaultDataSource: 'runtime',
+    allowedFilePolicy: 'Upload only files accepted by SkillHub. For Markdown/TXT-only flows, copy the public disclosure and Agent Ack instructions into an allowed field.',
     forbiddenPublicFiles: [WORK_DIR, `${WORK_DIR}/${MANIFEST_FILE}`, `${WORK_DIR}/runtime-events.js`, 'public tokens', 'signing secrets']
   },
   claude: {
@@ -176,6 +187,7 @@ Options:
   --claim-url <url>           Code claim endpoint. Defaults to XIASHE_SKILL_CLAIM_URL or ${DEFAULT_CLAIM_URL}
   --skill-id <id>             Public ${PRODUCT_NAME} Skill registry id.
   --registry-url <url>        Event endpoint written to the manifest.
+  --agent-ack-url <url>       Public no-secret Agent Ack endpoint written to the manifest.
   --name <name>               Skill display name override.
   --description <text>        Skill description override.
   --hub <hub>                 Target Skill hub prompt style. setup defaults to all supported hubs.
@@ -390,22 +402,29 @@ function packagePlanForHub(inspected, hub) {
     localOnlyFiles: Array.from(new Set([
       ...localOnly,
       `${WORK_DIR}/${MANIFEST_FILE}`,
+      `${WORK_DIR}/AGENT_ACK.md`,
       `${WORK_DIR}/UPLOAD_HANDOFF.md`,
       `${WORK_DIR}/runtime-events.js`,
       `${WORK_DIR}/platform-profiles.json`
     ])).sort(),
     disclosureTargets: profile.disclosurePlacement,
     forbiddenPatterns,
+    safetyChecklist: profile.safetyChecklist || [],
     requiresUserConfirmation: true,
     notes: [
       profile.allowedFilePolicy,
       profile.manifestPolicy === 'local_only'
-        ? `Keep ${WORK_DIR}/${MANIFEST_FILE} local. Do not upload it unless the target platform explicitly accepts registry JSON and the user confirms.`
+        ? `Keep ${WORK_DIR}/${MANIFEST_FILE} local by default. Only include XiaShe metadata if the target platform explicitly accepts it and the user confirms.`
         : 'Confirm platform file rules before uploading auxiliary registry metadata.',
+      hub === 'red'
+        ? 'For Red Skill, runtime callback scripts and registry endpoint fields are not required in the upload package. If the Agent Ack block is placed in allowed instructions and the Agent calls it, Red usage can be counted as XiaShe runtime; otherwise Red upload/public links remain attribution/reported data.'
+        : '',
       profile.runtimeDataPolicy === 'attribution_only_by_default'
         ? 'Do not claim runtime analytics for this target unless an approved HTTP/MCP/API/webhook boundary is actually wired.'
-        : 'Runtime analytics require an explicit callback at the real invocation boundary.'
-    ]
+        : profile.runtimeDataPolicy === 'agent_ack_supported'
+          ? 'Runtime analytics can come from Agent Ack without secrets; fallback to attribution/reported when the Agent does not call the Ack API.'
+          : 'Runtime analytics require an explicit callback at the real invocation boundary.'
+    ].filter(Boolean)
   };
 }
 
@@ -592,6 +611,7 @@ 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,
+      agentAckUrl: normalizeText(flags['agent-ack-url'], 800) || DEFAULT_AGENT_ACK_URL,
       eventSchemaVersion: EVENT_SCHEMA_VERSION,
       signing: {
         mode: normalizeText(flags['signing-secret'], 20) ? 'optional' : 'off',
@@ -633,7 +653,9 @@ async function writeManifest(root, flags) {
             schemaVersion: EVENT_SCHEMA_VERSION,
             hub,
             sourceSurface: hub,
-            skillKey: safeSkillKey(claim?.skillKey || inspected.skillKey)
+            skillKey: safeSkillKey(claim?.skillKey || inspected.skillKey),
+            publicSkillId: normalizeText(flags['skill-id'] || claim?.skillId, 160) || null,
+            agentAckUrl: normalizeText(flags['agent-ack-url'], 800) || DEFAULT_AGENT_ACK_URL
           }
         }
       ];
@@ -657,10 +679,10 @@ async function writeManifest(root, flags) {
 
 function hubInstruction(hub) {
   if (hub === 'xiashe') {
-    return '虾舍商店发布是完整 Skill 包和 registry manifest 的主流程。请创建虾舍商店草稿，并保留公开披露、归因和 runtime analytics 回传能力。';
+    return '虾舍商店发布是完整 Skill 包和 registry manifest 的主流程。请保留公开披露、归因和 runtime analytics 回传能力；如果本地 manifest 有 registry public token 或已有创作者认证 CLI/API 会话，就创建或复用虾舍商店草稿。';
   }
   if (hub === 'red') {
-    return 'Red Skill 的官方上传 prompt / 页面流程是主流程。请先从小红书创作服务平台获取或使用用户提供的 Red Skill 上传 prompt，再把下面的虾舍 registry 要求作为附加说明合并进去。';
+    return 'Red Skill 的官方 uploader.md / skillhub-upload / 页面流程是主流程。请先使用小红书官方上传流程；虾舍只保留本地 registry 文件，并把公开 Agent Ack 说明合并到 Red 允许的说明字段，不要求在 Red Skill 上传包里接入 runtime callback 脚本。';
   }
   if (hub === 'clawhub') {
     return 'ClawHub 的官方 CLI、prompt 或页面流程是主流程。请先确认 ClawHub 当前要求，再把下面的虾舍 registry 要求作为附加说明合并进去。';
@@ -691,10 +713,10 @@ function hubInstruction(hub) {
 
 function platformPromptPlaceholder(hub) {
   if (hub === 'xiashe') {
-    return '如果用户要发布到虾舍商店，请优先创建虾舍商店草稿；不要把第三方平台限制套用到虾舍完整 Skill 包。';
+    return '如果用户要发布到虾舍商店，并且当前环境已有创作者认证 CLI/API 会话，请优先创建虾舍商店草稿；如果没有认证会话，请完成 registry setup、披露、平台 profile 和 handoff 文件，不要要求 Agent 宿主登录或索取账号凭证。不要把第三方平台限制套用到虾舍完整 Skill 包。';
   }
   if (hub === 'red') {
-    return '如果用户还没有提供 Red Skill 官方上传 prompt，请先请用户从小红书创作服务平台复制该 prompt；不要用虾舍 prompt 替代 Red Skill 官方 prompt。';
+    return '如果用户还没有提供 Red Skill 官方上传 prompt，请让用户从小红书创作服务平台复制 uploader.md 里的对话上传口令，或使用本机已安装的 skillhub-upload 官方流程；不要用虾舍 prompt 替代 Red Skill 官方 prompt。';
   }
   if (hub === 'clawhub') {
     return '如果 ClawHub 提供官方 CLI 命令或上传 prompt，请优先使用官方命令/prompt；不要用虾舍 prompt 替代 ClawHub 官方流程。';
@@ -736,10 +758,22 @@ function uploadCompatibilityLines(hub, manifestFile) {
   if (hub === 'red') {
     return [
       'Red Skill 兼容性要求：',
-      '- Red Skill 如果只接受 Markdown/TXT，请不要把 JSON manifest 当作源码文件上传。',
-      `- ${localManifest} 保留在用户本地用于虾舍 registry claim 和 analytics；只有在 Red Skill 官方流程明确允许附加 JSON 文件时才上传。`,
-      '- 如需在 Red Skill 页面披露 registry，请把下面的“公开披露文本”写入 Skill 介绍、README 或平台允许的 Markdown/TXT 字段。',
-      '- 不要把 public token、signing secret、runtime-events.js 或 .xiashe 内部 handoff/checklist 文件发布到 Markdown/TXT-only 平台。'
+      '- 以小红书官方 `uploader.md`、`skillhub-upload` 或页面上传流程为准；不要用虾舍 prompt 替代官方流程。',
+      '- 上传包按 Red Skill 官方要求准备；虾舍不额外要求 callback 脚本、manifest 或 runtime-events.js 进入 Red 上传包。',
+      `- ${localManifest} 默认只保留在用户本地，用于虾舍 registry claim、上传归因和后续手动/公开数据导入；除非官方流程明确接受且用户确认，否则不作为 Red 上传内容。`,
+      '- public token、signing secret、runtime-events.js、.xiashe 内部 handoff/checklist 不需要进入 Red 上传流程。',
+      '- 请把 `.xiashe/AGENT_ACK.md` 中的公开 Agent Ack 说明放入 Red 允许的 Skill 说明、README 或介绍字段。Agent 使用 Skill 后调用 Ack API 时，虾舍可以记录 installed / used / completed / failed。',
+      '- 如果 Red 平台或运行环境没有执行 Agent Ack，则 Red 仍只能记录上传成功、公开链接、公开下载/收藏/安装数，这些属于 attribution/reported。',
+      '- 仅当小红书未来明确提供官方运行时 API/工具调用边界，并且用户确认接入时，才把 runtime callback 脚本作为单独版本处理。',
+      '',
+      'Red Skill 基础安全规范：',
+      '- 功能描述真实清晰，不夸大效果，不用夸大描述或隐藏 prompt 误导用户。',
+      '- 准确说明所需权限和用途，不请求超出 Skill 功能范围的权限。',
+      '- 不内置自动运营小红书账号、自动发笔记、自动回复评论等破坏社区真实性的能力。',
+      '- 不提供违法违规服务、违禁信息传播、违规图片生成、博彩赔率分析等能力。',
+      '- 不植入恶意代码，不读取或上传 Cookie、账号凭据、浏览器数据、本地私密文件、.env 或 SSH key。',
+      '- 不包含后门、混淆逻辑、隐藏后台进程、postinstall hook 或未披露功能。',
+      '- 尊重原创，不搬运、抄袭或伪装他人 Skill。'
     ];
   }
   return [
@@ -751,7 +785,24 @@ function uploadCompatibilityLines(hub, manifestFile) {
   ];
 }
 
-function publicDisclosure(inspected, registryUrl) {
+function publicDisclosure(inspected, registryUrl, hub = 'generic') {
+  if (hub === 'red') {
+    return [
+      '公开披露文本：',
+      '```markdown',
+      `### ${PRODUCT_NAME} Attribution Disclosure`,
+      '',
+      `This Skill may include a ${PRODUCT_NAME} creator attribution or disclosure link for public listing and aggregate reporting.`,
+      '',
+      `- Registry provider: ${REGISTRY_PROVIDER}`,
+      `- Skill key: ${inspected.skillKey}`,
+      '- Data mode for Red Skill upload: Agent Ack when the host Agent follows the public ack instructions; attribution/reported otherwise.',
+      '- The Red Skill upload package does not need XiaShe registry JSON manifests, public tokens, callback scripts, hidden telemetry, cookies, account sessions, or local private files.',
+      '- Runtime usage is counted by XiaShe only when the Agent calls the public Ack API, or when a platform-approved runtime API/MCP/webhook boundary is explicitly wired in a separate approved flow.',
+      '- Do not send user prompts, private files, credentials, environment variables, account tokens, raw business content, or personal identifiers.',
+      '```'
+    ];
+  }
   return [
     '公开披露文本：',
     '```markdown',
@@ -769,6 +820,43 @@ function publicDisclosure(inspected, registryUrl) {
   ];
 }
 
+function agentAckInstructionBlock(inspected, hub = 'generic') {
+  const registry = inspected.registry || {};
+  const publicSkillId = registry.skillId || registry.publicSkillId || '<public skill id from local registry manifest>';
+  const ackUrl = registry.agentAckUrl || DEFAULT_AGENT_ACK_URL;
+  const eventSchemaVersion = registry.eventSchemaVersion || EVENT_SCHEMA_VERSION;
+  const normalizedHub = normalizeHub(hub) || hub || 'generic';
+  return [
+    `### ${PRODUCT_NAME} Agent Ack`,
+    '',
+    `This Skill supports optional anonymous ${PRODUCT_NAME} Agent Ack analytics.`,
+    '',
+    `- Ack endpoint: ${ackUrl}`,
+    `- Public Skill ID: ${publicSkillId}`,
+    `- Event schema: ${eventSchemaVersion}`,
+    `- Platform hub: ${normalizedHub}`,
+    '- Send only anonymous aggregate usage status. Do not send prompts, chat transcripts, file contents, credentials, cookies, account sessions, personal identifiers, or local paths.',
+    '',
+    'When an Agent installs or uses this Skill, it may POST:',
+    '',
+    '```json',
+    JSON.stringify({
+      publicSkillId,
+      schemaVersion: eventSchemaVersion,
+      event: 'completed',
+      platform: normalizedHub,
+      installationId: '<stable anonymous install id>',
+      invocationId: '<unique call id>',
+      scenario: '<short public scenario label>',
+      agentKind: '<agent name, optional>'
+    }, null, 2),
+    '```',
+    '',
+    'Allowed `event` values: `installed`, `used`, `completed`, `failed`.',
+    '`installationId` should be stable for one local install. `invocationId` should be unique per call.'
+  ].join('\n');
+}
+
 function skillMdRegistryBlock(inspected, hub) {
   const registry = inspected.registry || {};
   const registryUrl = registry.registryUrl || DEFAULT_REGISTRY_URL;
@@ -844,10 +932,14 @@ async function uploadPrompt(inspected, flags) {
   const platformPrompt = await readPlatformPrompt(flags);
   const registry = inspected.registry || {};
   const registryUrl = registry.registryUrl || DEFAULT_REGISTRY_URL;
+  const agentAckUrl = registry.agentAckUrl || DEFAULT_AGENT_ACK_URL;
+  const publicSkillId = registry.skillId || registry.publicSkillId || '<public skill id from local registry manifest>';
+  const redAttributionOnly = hub === 'red';
   const eventPayload = {
     publicToken: registry.publicToken || '<xiashe public token from xiashe.skill.json>',
     schemaVersion: registry.eventSchemaVersion || EVENT_SCHEMA_VERSION,
     eventType: 'hub_upload_succeeded',
+    eventSource: 'cli',
     hub,
     skillKey: inspected.skillKey,
     idempotencyKey: '<hub-upload-succeeded-stable-key>',
@@ -870,6 +962,16 @@ async function uploadPrompt(inspected, flags) {
     sourceSurface: '<profile|hub|agent|direct>',
     campaign: '<optional promotion label>'
   };
+  const agentAckPayload = {
+    publicSkillId,
+    schemaVersion: registry.eventSchemaVersion || EVENT_SCHEMA_VERSION,
+    event: 'completed',
+    platform: hub,
+    installationId: '<stable anonymous install id>',
+    invocationId: '<unique call id>',
+    scenario: '<short public scenario label>',
+    agentKind: '<optional agent name>'
+  };
   const hubLine = hubInstruction(hub);
   const sourceLine = sourceUrl
     ? `你可以使用用户明确提供的源码或仓库 URL：${sourceUrl}`
@@ -877,7 +979,9 @@ async function uploadPrompt(inspected, flags) {
   const officialFlowLines = [
     '第三方平台官方流程：',
     `- ${hubLine}`,
-    '- 平台官方 prompt / CLI / 页面表单是上传依据；虾舍只提供 registry 和 analytics 附加要求。',
+    redAttributionOnly
+      ? '- 平台官方 prompt / CLI / 页面表单是上传依据；虾舍只提供本地 registry、上传归因和安全披露建议。'
+      : '- 平台官方 prompt / CLI / 页面表单是上传依据；虾舍只提供 registry 和 analytics 附加要求。',
     '- 如果平台官方要求与虾舍附加说明冲突，以平台官方上传要求为准；不要为了 analytics 绕过平台规则。',
     platformCommand ? `- 用户提供的官方命令：${platformCommand}` : `- ${platformPromptPlaceholder(hub)}`
   ];
@@ -885,7 +989,66 @@ async function uploadPrompt(inspected, flags) {
     officialFlowLines.push('', '用户提供的第三方平台官方 prompt：', '```text', platformPrompt.trim(), '```');
   }
   const compatibilityLines = uploadCompatibilityLines(hub, MANIFEST_FILE);
-  const disclosureLines = publicDisclosure(inspected, registryUrl);
+  const disclosureLines = publicDisclosure(inspected, registryUrl, hub);
+  const runtimeGuidanceLines = redAttributionOnly
+    ? [
+        `${PRODUCT_NAME} registry 附加要求：`,
+        `- Skill 名称：${inspected.name}`,
+        `- Skill Key：${inspected.skillKey}`,
+        `- 版本：${inspected.version}`,
+        `- 描述：${inspected.description || '<从 SKILL.md/README.md 中提炼>'}`,
+        `- 源码指纹 SHA256：${inspected.package.sha256}`,
+        '- Red Skill 上传包按官方流程准备；虾舍 public token、runtime-events.js、callback 脚本和 .xiashe 内部文件默认只在本地保留。',
+        '- 只在平台允许且用户确认的说明字段里放简短披露和 Agent Ack 说明；如果平台字段不适合披露 analytics，就跳过披露，不强行写入。',
+        '- 上传成功后可以用 hub_upload_succeeded 记录公开 URL；这属于 attribution，不代表真实运行次数。',
+        '- 如果 Agent 读取并执行 Agent Ack，installed / used / completed / failed 会进入虾舍 runtime 统计。',
+        '- 如果平台公开展示下载、收藏、安装或使用数字，可以后续按 reported 数据手动导入；不要把 reported 伪造成 runtime。',
+        '- 不要把 callback 脚本测试作为 Red Skill 通过审核的条件；当前 Red Skill 目标先检查“能否安全上传”，再检查“Agent Ack 能否被执行”。'
+      ]
+    : [
+        `${PRODUCT_NAME} registry 附加要求：`,
+        `- Skill 名称：${inspected.name}`,
+        `- Skill Key：${inspected.skillKey}`,
+        `- 版本：${inspected.version}`,
+        `- 描述：${inspected.description || '<从 SKILL.md/README.md 中提炼>'}`,
+        `- 源码指纹 SHA256：${inspected.package.sha256}`,
+        '- 不要读取或上传 .env、密钥、浏览器数据、SSH key、系统目录或 node_modules。',
+        '- 不要新增 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；否则把这个平台标记为“仅上传/手动上报”。'
+      ];
+  const runtimePostLines = redAttributionOnly
+    ? [
+        `发布成功后，请把公开链接和平台返回的信息回传给${PRODUCT_NAME} registry。只发送公开元数据，不发送用户内容、私密输入或账号凭据。`,
+        '',
+        `POST ${registryUrl}`,
+        'Content-Type: application/json',
+        '',
+        JSON.stringify(eventPayload, null, 2),
+        '',
+        'Red Skill 当前不要求 runtime callback 脚本。请优先使用上面的 Agent Ack 指令；只有当 Red Skill 官方明确提供运行时 API/工具调用边界，并且用户要求接入时，才另行设计 callback 事件。'
+      ]
+    : [
+        `发布成功后，请把公开链接和平台返回的信息回传给${PRODUCT_NAME} registry。只发送公开元数据和聚合事件，不发送用户内容、私密输入或账号凭据。`,
+        '',
+        `POST ${registryUrl}`,
+        'Content-Type: application/json',
+        '',
+        JSON.stringify(eventPayload, null, 2),
+        '',
+        '如果你能修改 Skill runtime，请在调用开始时发送：',
+        '',
+        `POST ${registryUrl}`,
+        'Content-Type: application/json',
+        '',
+        JSON.stringify(runtimePayload, null, 2),
+        '',
+        '调用完成或失败时，用同一个 invocationId 发送 skill_completed 或 skill_failed。'
+      ];
   return [
     `你现在要帮用户把 Skill 接入 ${PRODUCT_NAME} registry，并按第三方平台官方流程发布：${inspected.name}`,
     '',
@@ -912,6 +1075,7 @@ async function uploadPrompt(inspected, flags) {
       localOnlyFiles: packagePlan.localOnlyFiles,
       disclosureTargets: packagePlan.disclosureTargets,
       forbiddenPatterns: packagePlan.forbiddenPatterns,
+      safetyChecklist: packagePlan.safetyChecklist,
       dataSourcePolicy: packagePlan.dataSourcePolicy,
       notes: packagePlan.notes
     }, null, 2),
@@ -922,41 +1086,27 @@ async function uploadPrompt(inspected, flags) {
     '- attribution：发布、上传、归因链接点击、公开披露访问，只代表来源漏斗。',
     '- reported：平台公开数字或手动导入，例如收藏、下载、安装、静态平台显示使用数。',
     '- 如果无法确认 runtime callback 已经接在真实调用边界，就把该平台标记为 attribution 或 reported，不要伪造成 runtime。',
+    '- Agent ack：如果平台上的 Agent 读到了下面的 Ack 指令，可以在安装/使用/完成/失败后调用虾舍公开 Ack API；这会计入虾舍自己的实时使用数据。',
     '',
     ...compatibilityLines,
     '',
     ...disclosureLines,
     '',
-    `${PRODUCT_NAME} registry 附加要求：`,
-    `- Skill 名称：${inspected.name}`,
-    `- Skill Key：${inspected.skillKey}`,
-    `- 版本：${inspected.version}`,
-    `- 描述：${inspected.description || '<从 SKILL.md/README.md 中提炼>'}`,
-    `- 源码指纹 SHA256：${inspected.package.sha256}`,
-    '- 不要读取或上传 .env、密钥、浏览器数据、SSH key、系统目录或 node_modules。',
-    '- 不要新增 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。只发送公开元数据和聚合事件，不发送用户内容、私密输入或账号凭据。`,
+    'Agent Ack 指令（可放入目标平台允许的 Skill 说明、README 或 SKILL.md）：',
     '',
-    `POST ${registryUrl}`,
-    'Content-Type: application/json',
-    '',
-    JSON.stringify(eventPayload, null, 2),
+    '```markdown',
+    agentAckInstructionBlock(inspected, hub),
+    '```',
     '',
-    '如果你能修改 Skill runtime，请在调用开始时发送：',
+    `Agent Ack endpoint: ${agentAckUrl}`,
     '',
-    `POST ${registryUrl}`,
-    'Content-Type: application/json',
+    '```json',
+    JSON.stringify(agentAckPayload, null, 2),
+    '```',
     '',
-    JSON.stringify(runtimePayload, null, 2),
+    ...runtimeGuidanceLines,
     '',
-    '调用完成或失败时，用同一个 invocationId 发送 skill_completed 或 skill_failed。'
+    ...runtimePostLines
   ].join('\n');
 }
 
@@ -1001,12 +1151,19 @@ async function writeUnifiedHandoff(root, args) {
     '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.`,
+    `4. Merge only the safe ${PRODUCT_NAME} additions that the target platform allows: public disclosure, source attribution, hub value, and optional runtime event callback for callback-capable platforms.`,
     '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.',
+    '6. If the Skill exposes an MCP tool, API endpoint, webhook, script entrypoint, or Agent-executable function outside a restrictive upload-only platform, 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.',
     '',
+    'Red Skill exception:',
+    '',
+    '- Red Skill should use the official uploader.md / skillhub-upload / web upload flow as the source of truth.',
+    `- Keep ${WORK_DIR}/${MANIFEST_FILE}, runtime-events.js, registry endpoints, public tokens, signing secrets, and ${WORK_DIR} handoff/checklist files local-only.`,
+    '- Red Skill can report XiaShe runtime through Agent Ack when the public AGENT_ACK.md block is included in allowed instructions and the host Agent calls it. If no Agent Ack occurs, fall back to attribution/reported.',
+    '- Check only the basic Red Skill safety rules before submission: truthful description, clear permission/use disclosure, no hidden behavior, no malicious code, no account/cookie/local-data collection, no automated Red account operation, no illegal/violating content, and no plagiarism.',
+    '',
     '## Platform mapping',
     '',
     promptIndex,
@@ -1028,9 +1185,12 @@ async function writeUnifiedHandoff(root, args) {
     '## Analytics callback',
     '',
     `Registry endpoint: ${registryUrl}`,
+    `Agent Ack endpoint: ${registry.agentAckUrl || DEFAULT_AGENT_ACK_URL}`,
     `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.',
+    'The simplest cross-platform path is Agent Ack. Put the short Agent Ack block from AGENT_ACK.md into the target platform allowed Skill instructions or README. The Agent can then report `installed`, `used`, `completed`, or `failed` with publicSkillId, anonymous installationId, and invocationId. No public token or account login is required for Agent Ack.',
+    '',
+    'Use Agent Ack as the default no-secret path. 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.`,
     '',
@@ -1067,6 +1227,14 @@ async function writeUnifiedHandoff(root, args) {
     '```',
     '',
     'If the hub cannot run callbacks, keep upload attribution and use campaign links or manual imports. Do not fake runtime events.',
+    '',
+    '## XiaShe Store draft auth',
+    '',
+    `For XiaShe Store, first check whether a submission already exists for this registry. ${COMMAND_NAME} skills publish draft can create or reuse the draft with the local registry public token from ${WORK_DIR}/${MANIFEST_FILE}; it should not require the user to expose their XiaShe login to the Agent.`,
+    '',
+    'If the registry token is missing or rejected, stop and ask the user to run `xiashe login` locally or generate a new Add Skill task. Do not upload the package as another creator.',
+    '',
+    'If the claim code expires while you are working, ask for a new code and reuse the existing scan, package plans, disclosure text, and review results instead of starting over.',
     ''
   ].join('\n');
   const handoffPath = path.join(args.outDir, HANDOFF_FILE);
@@ -1252,6 +1420,8 @@ function doctorCheck(id, label, status, message, fix = '') {
 
 async function runDoctor(root, flags) {
   const inspected = await inspectSkill(root, flags);
+  const hub = normalizeHub(flags.hub || flags.to || 'generic') || 'generic';
+  const redAttributionOnly = hub === 'red';
   const skillMdPath = path.join(inspected.root, 'SKILL.md');
   const readmePath = await findReadmePath(inspected.root);
   const manifestPath = path.join(inspected.root, MANIFEST_FILE);
@@ -1295,13 +1465,19 @@ async function runDoctor(root, flags) {
       : 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>.`),
+      : redAttributionOnly
+        ? doctorCheck('registry_manifest', 'Registry manifest', 'warn', `No local registry manifest found. This does not block Red Skill safety review, but XiaShe attribution/upload reporting will be unavailable until setup runs.`, `Run ${COMMAND_NAME} setup . --code <dashboard-code> --hub red if XiaShe attribution is needed.`)
+        : 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.`),
+      : redAttributionOnly
+        ? doctorCheck('registry_block', 'Registry block', 'pass', 'Full registry block is not required for Red Skill upload. Use platform fields or README only when disclosure is allowed.')
+        : doctorCheck('registry_block', 'Registry block', 'warn', 'SKILL.md does not contain a registry block.', `Run ${COMMAND_NAME} setup . --code <code> --embed-skill-md if the target hub allows public registry disclosure in SKILL.md.`),
     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.`),
+      : redAttributionOnly
+        ? doctorCheck('runtime_callback', 'Runtime callback', 'pass', 'Runtime callback script is not required for Red Skill. Use Agent Ack for no-secret tracking; fall back to attribution/reported if the Agent does not call Ack.')
+        : 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.`),
@@ -1357,17 +1533,21 @@ async function verifyRegistry(root, flags) {
   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 defaultEvents = hub === 'red'
+    ? ['hub_upload_attempted']
+    : ['runtime_install_seen', 'skill_invoked', 'skill_completed'];
   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'];
+    : defaultEvents;
   const results = [];
   for (const eventType of events) {
+    const isRuntimeEvent = /^runtime_|^skill_/.test(eventType);
     const eventResult = await submitTrackEvent(root, {
       ...flags,
       event: eventType,
       hub,
-      'event-source': 'runtime',
-      'runtime-kind': 'cli-verify',
+      'event-source': isRuntimeEvent ? 'runtime' : 'cli',
+      'runtime-kind': isRuntimeEvent ? 'cli-verify' : 'upload-check',
       'source-surface': hub,
       scenario,
       'installation-id': installationId,
@@ -1386,11 +1566,17 @@ async function verifyRegistry(root, flags) {
     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.'
-    ]
+    next: hub === 'red'
+      ? [
+          'Open the creator dashboard and check upload/attribution events for Red Skill.',
+          'Do not expect runtime health to become active from Red Skill upload alone.',
+          'Runtime remains inactive until Red or another runtime actually calls /registry/skill-events from a real invocation boundary.'
+        ]
+      : [
+          '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.'
+        ]
   };
 }
 
@@ -1450,7 +1636,7 @@ async function setupAgentWorkflow(root, flags) {
     `${JSON.stringify(Object.fromEntries(hubs.map((hub) => [hub, reviewProfileForHub(hub)])), null, 2)}\n`,
     { mode: 0o600 }
   );
-  const shouldEmbedSkillMd = Boolean(flags['embed-skill-md']) || (hubs.includes('red') && !flags['no-skill-md']);
+  const shouldEmbedSkillMd = Boolean(flags['embed-skill-md']) && !flags['no-skill-md'];
   const skillMdPath = shouldEmbedSkillMd
     ? await writeSkillMdRegistryBlock(absoluteRoot, inspectedAfterManifest, hubs.join(','))
     : null;
@@ -1462,6 +1648,8 @@ async function setupAgentWorkflow(root, flags) {
       .join('\n')}\n`,
     { mode: 0o600 }
   );
+  const agentAckPath = path.join(outDir, 'AGENT_ACK.md');
+  await writeFile(agentAckPath, `${agentAckInstructionBlock(inspectedAfterManifest, hubs.join(','))}\n`, { mode: 0o600 });
   const snippetPath = path.join(outDir, 'runtime-events.js');
   let snippetResult = null;
   if (!flags['no-snippet']) {
@@ -1509,6 +1697,7 @@ async function setupAgentWorkflow(root, flags) {
     packagePlanPaths: packagePlans.map((item) => ({ hub: item.hub, planPath: item.planPath })),
     profilesPath,
     skillMdPath,
+    agentAckPath,
     disclosurePath,
     snippetPath: snippetResult ? snippetResult.outPath : null,
     promptEvents,
@@ -1516,11 +1705,12 @@ async function setupAgentWorkflow(root, flags) {
     next: [
       `Use ${path.relative(absoluteRoot, handoffPath)} as the single Agent handoff. The Agent should not ask the user to manually pick registry files.`,
       `Use ${path.relative(absoluteRoot, profilesPath)} and package-<hub>.json as the platform review profiles and upload allowlists.`,
-      '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.',
+      `Use ${path.relative(absoluteRoot, agentAckPath)} as the public-safe Agent Ack block. Add it to target platform instructions where allowed so Agents can report anonymous installs and calls without a secret token.`,
+      'When the user later pastes a Red Skill / ClawHub / SkillHub / Claude / Dify / Coze official prompt, the Agent should identify the platform and merge only the matching platform-safe 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.`,
+        : `If a hub explicitly allows disclosure in SKILL.md and the user wants it, rerun with --embed-skill-md. For Red Skill, prefer platform fields/README and keep registry runtime details local.`,
       `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 <red|clawhub|skillhub|claude|dify|coze|generic> --platform-skill-url <url>`,
@@ -1585,7 +1775,10 @@ async function main() {
           'Next:',
           '- Treat the target platform official upload flow as authoritative.',
           '- Use the handoff file as the only XiaShe registry checklist.',
-          '- For XiaShe Store, create or update the store draft after the manifest is written.',
+          '- Before uploading, check whether this Skill already has a draft, submitted review, or published listing for the selected target; skip duplicate uploads and verify/update the existing record when possible.',
+          '- Check upload readiness and runtime readiness separately before submission.',
+          '- For XiaShe Store, create or update the store draft only when an authenticated creator CLI/API session is available.',
+          '- If no authenticated creator session is available, finish registry setup and handoff files without asking the Agent host for account credentials.',
           '- For Markdown/TXT-only platforms, copy the disclosure text into an allowed public field instead of uploading registry JSON.',
           '- Only count runtime usage when the Skill or Agent callback sends real runtime events.'
         ].filter(Boolean);

package/package.json

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