@xiashe/skill 0.1.16 → 0.1.18

package/README.md

@@ -15,14 +15,15 @@ This package is intentionally separate from the full `@xiashe/cli` product CLI a
 - 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
+- build and upload the XiaShe complete Skill package to XiaShe File Storage when the `xiashe` target is selected
 - generate one unified `UPLOAD_HANDOFF.md` that the creator's Agent can use with Xiaohongshu's official `skillhub-upload` or `uploader.md`
 - generate optional runtime analytics snippets
 
-It does not install background services, run postinstall hooks, read secrets, or override Red Skill upload rules. The creator's Agent is responsible for packaging and uploading according to Xiaohongshu's official flow.
+It does not install background services, run postinstall hooks, read secrets, or override Red Skill upload rules. XiaShe package upload is handled by this CLI for the XiaShe-owned registry; the creator's Agent is responsible only for third-party packaging and uploading according to Xiaohongshu's official flow.
 
 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` now defaults to XiaShe Store and Red Skill. It writes private `.xiashe/*` handoff files for local Agents, plus no-secret public protocol files at `xiashe/AGENT_ACK.md` and `xiashe/REGISTRY_DISCLOSURE.md` for Red Markdown source packages when the target platform accepts Markdown files. 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 tokens, signing secrets, package hashes, storage ids, and private handoff files local while recording Red usage through Agent Ack when the host Agent safely calls it.
+`setup --hub all` now defaults to XiaShe Store and Red Skill. It writes private `.xiashe/*` handoff files for local Agents, uploads the XiaShe complete package as `.tgz` through the registry storage flow, plus writes no-secret public runtime protocol files at `xiashe/runtime.yaml`, `xiashe/AGENT_ACK.md`, and `xiashe/REGISTRY_DISCLOSURE.md` for Red Markdown/YAML source packages when the target platform accepts them. 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 tokens, signing secrets, package hashes, storage ids, and private handoff files local while recording Red usage through Agent Ack when the host Agent safely calls it.
 
 ## Local development
 

package/bin/xiashe-skill.mjs

@@ -5,8 +5,10 @@ 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';
+import { promisify } from 'node:util';
+import { gzip } from 'node:zlib';
 
-const VERSION = '0.1.16';
+const VERSION = '0.1.18';
 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');
@@ -22,12 +24,21 @@ 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 DEFAULT_PACKAGE_UPLOAD_URL = process.env.XIASHE_SKILL_PACKAGE_UPLOAD_URL || `${DEFAULT_BASE_URL}/registry/skill/package-upload-url`;
+const DEFAULT_PACKAGE_ARTIFACT_URL = process.env.XIASHE_SKILL_PACKAGE_ARTIFACT_URL || `${DEFAULT_BASE_URL}/registry/skill/package-artifact`;
 const EVENT_SCHEMA_VERSION = process.env.XIASHE_SKILL_EVENT_SCHEMA_VERSION || (REGISTRY_PROVIDER === 'agentpie'
   ? 'agentpie.skill.event.v1'
   : 'xiashe.skill.event.v1');
+const RUNTIME_SCHEMA_VERSION = process.env.XIASHE_SKILL_RUNTIME_SCHEMA_VERSION || (REGISTRY_PROVIDER === 'agentpie'
+  ? 'agentpie.skill.runtime.v1'
+  : 'xiashe.skill.runtime.v1');
 const SUPPORTED_HUBS = ['xiashe', 'red', 'clawhub', 'skillhub', 'claude', 'codex', 'cursor', 'workbuddy', 'dify', 'coze', 'generic'];
 const DEFAULT_SETUP_HUBS = ['xiashe', 'red'];
 const ACK_EVENTS = ['installed', 'used', 'completed', 'failed'];
+const RUNTIME_DISTRIBUTION_PLATFORMS = ['xiaohongshu-redskill', 'xiashe', 'coze-store', 'local', 'unknown'];
+const RUNTIME_AGENTS = ['codex', 'workbuddy', 'coze', 'claude', 'cursor', 'dify', 'custom-agent', 'unknown'];
+const RUNTIME_HOSTS = ['codex-desktop', 'coze-app', 'web-chat', 'desktop', 'web', 'server', 'mobile', 'unknown'];
+const RUNTIME_SOURCE_SURFACES = ['install', 'first-use-backfill', 'chat-use', 'manual-test', 'creator-card', 'dashboard', 'unknown'];
 const SCENARIO_ENUM_EXAMPLES = [
   'research_digest',
   'paper_search',
@@ -39,6 +50,19 @@ const SCENARIO_ENUM_EXAMPLES = [
   'knowledge_lookup',
   'other'
 ];
+const RUNTIME_SCENARIOS = [
+  'install',
+  'life_clarification',
+  'constraint_mapping',
+  'job_market_research',
+  'jd_synthesis',
+  'path_comparison',
+  'transition_plan',
+  'interview_preparation',
+  'test',
+  'unknown',
+  ...SCENARIO_ENUM_EXAMPLES
+];
 const FORBIDDEN_ACK_FIELDS = [
   'prompt',
   'chatTranscript',
@@ -69,10 +93,10 @@ const PLATFORM_REVIEW_PROFILES = {
     label: 'Red Skill',
     packageMode: 'markdown_or_text_only',
     manifestPolicy: 'local_only',
-    disclosurePlacement: ['platform description field', 'README', 'SKILL.md', `${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md`, `${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md`],
+    disclosurePlacement: ['platform description field', 'README', 'SKILL.md', `${PUBLIC_PROTOCOL_DIR}/runtime.yaml`, `${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md`, `${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md`],
     runtimeDataPolicy: 'agent_ack_supported',
     defaultDataSource: 'runtime',
-    allowedFilePolicy: `Follow the official Red Skill uploader.md / skillhub-upload flow. Put public source, safety, creator-card attribution, and the no-secret ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md + ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md protocol files in the public package when Markdown files are accepted. Keep .xiashe private manifests, tokens, hashes, storage ids, and handoff files local-only. Send Agent Ack events only when the host can safely call HTTP/MCP.`,
+    allowedFilePolicy: `Follow the official Red Skill uploader.md / skillhub-upload flow. Put public source, safety, creator-card attribution, and the no-secret ${PUBLIC_PROTOCOL_DIR}/runtime.yaml + ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md + ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md protocol files in the public package when Markdown/YAML files are accepted. Keep .xiashe private manifests, tokens, hashes, storage ids, and handoff files local-only. Send Agent Ack events only when the host can safely call HTTP/MCP.`,
     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: [
@@ -192,6 +216,8 @@ const DEFAULT_IGNORE = new Set([
 ]);
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 const MAX_SOURCE_BYTES = 30 * 1024 * 1024;
+const MAX_XIASHE_PACKAGE_BYTES = 100 * 1024 * 1024;
+const gzipAsync = promisify(gzip);
 
 function usage() {
   return `${COMMAND_NAME} ${VERSION}
@@ -224,6 +250,14 @@ Options:
   --installation-id <id>      Stable anonymous install id for runtime analytics.
   --invocation-id <id>        Unique invocation id for one skill call.
   --scenario <label>          Short scenario label.
+  --scenario-label <label>    Short user-facing scenario label.
+  --user-intent-label <label> High-level user intent label, not a prompt.
+  --task-domain <label>       High-level task domain such as research or writing.
+  --workflow-stage <label>    install, invoke, complete, fail, or verify.
+  --platform-name <label>     User-facing runtime platform name.
+  --distribution-platform <p> Distribution platform, separate from runtime agent.
+  --runtime-agent <label>     Agent actually running the Skill.
+  --runtime-host <label>      Runtime host such as desktop, web, server, or mobile.
   --campaign <label>          Campaign or promotion label.
   --platform-skill-url <url>  Published Skill URL for hub_upload_succeeded events.
   --platform-prompt-file <p>  Official third-party hub prompt file to embed in the handoff.
@@ -232,8 +266,11 @@ Options:
   --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.
+  --package-upload-url <url>  Package upload ticket endpoint. Defaults to ${DEFAULT_PACKAGE_UPLOAD_URL}
+  --package-artifact-url <url> Package artifact attach endpoint. Defaults to ${DEFAULT_PACKAGE_ARTIFACT_URL}
   --out <path>                Output prompt or snippet file.
   --out-dir <path>            Output directory for setup artifacts. Defaults to ${WORK_DIR}/.
+  --no-xiashe-package-upload  Skip automatic ${PRODUCT_NAME} complete package upload.
   --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.
@@ -252,7 +289,7 @@ function fail(message, code = 1) {
 
 function parseArgs(argv) {
   const args = { _: [], json: false, dryRun: false };
-  const booleanFlags = new Set(['embed-skill-md', 'no-skill-md', 'no-snippet', 'no-track']);
+  const booleanFlags = new Set(['embed-skill-md', 'no-skill-md', 'no-snippet', 'no-track', 'no-xiashe-package-upload']);
   for (let i = 0; i < argv.length; i += 1) {
     const value = argv[i];
     if (value === '--help' || value === '-h') {
@@ -453,6 +490,13 @@ function isPublicDocFile(filePath) {
     /\.(md|mdx|txt)$/i.test(filePath);
 }
 
+function isPublicRuntimeProtocolFile(filePath) {
+  const normalized = String(filePath || '').replace(/\\/g, '/');
+  return normalized === `${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md` ||
+    normalized === `${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md` ||
+    normalized === `${PUBLIC_PROTOCOL_DIR}/runtime.yaml`;
+}
+
 function isLikelyEntrypointFile(filePath) {
   return /(^|\/)(package\.json|requirements\.txt|pyproject\.toml|deno\.json|mcp\.json|manifest\.json|skill\.json|index\.(js|mjs|cjs|ts|tsx|py)|main\.(js|mjs|cjs|ts|tsx|py)|server\.(js|mjs|cjs|ts|tsx|py))$/i.test(filePath);
 }
@@ -484,7 +528,7 @@ function packagePlanForHub(inspected, hub) {
       continue;
     }
     if (profile.packageMode === 'markdown_or_text_only') {
-      if (isPublicDocFile(file.path)) {
+      if (isPublicDocFile(file.path) || isPublicRuntimeProtocolFile(file.path)) {
         candidateUploadFiles.push(file.path);
       }
       continue;
@@ -533,7 +577,7 @@ function packagePlanForHub(inspected, hub) {
         ? `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, include only public source files plus no-secret ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md and ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md when Markdown files are accepted. Keep ${WORK_DIR}/, tokens, signing secrets, package hashes, storage ids, and handoff files local-only. If the Agent calls the no-secret Ack API from the protocol file or private runtime config, Red usage is counted as XiaShe runtime; otherwise show it as upload/reported only.`
+        ? `For Red Skill, include only public source files plus no-secret ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md, ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md, and ${PUBLIC_PROTOCOL_DIR}/runtime.yaml when Markdown/YAML files are accepted. Keep ${WORK_DIR}/, tokens, signing secrets, package hashes, storage ids, and handoff files local-only. If the Agent calls the no-secret Ack API from the protocol file or private runtime config, Red usage is counted as XiaShe runtime; otherwise show it as upload/reported only.`
         : '',
       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.'
@@ -664,6 +708,285 @@ async function postJson(url, body, timeoutMs = 20_000) {
   }
 }
 
+function urlForRegistryPath(baseUrl, pathname, fallback) {
+  const base = normalizeText(baseUrl, 1_000) || fallback;
+  try {
+    return new URL(pathname, base).toString();
+  } catch {
+    return fallback;
+  }
+}
+
+function shouldIgnorePackageEntry(relativePath, entryName, isDirectory = false) {
+  const normalized = String(relativePath || '').replace(/\\/g, '/');
+  const localRegistryPrefix = `${WORK_DIR}/`;
+  const packageArtifactPrefix = `${WORK_DIR}/package-artifact/`;
+  if (normalized === '.git' || normalized.startsWith('.git/')) return true;
+  if (normalized === 'node_modules' || normalized.startsWith('node_modules/')) return true;
+  if (normalized === 'dist' || normalized.startsWith('dist/')) return true;
+  if (normalized === 'build' || normalized.startsWith('build/')) return true;
+  if (normalized === 'coverage' || normalized.startsWith('coverage/')) return true;
+  if (normalized === '.DS_Store' || normalized.endsWith('/.DS_Store')) return true;
+  if (entryName === '.env' || entryName.startsWith('.env.')) return true;
+  if (/\.(pem|key)$/i.test(entryName)) return true;
+  if (packageArtifactPrefix && normalized.startsWith(packageArtifactPrefix)) return true;
+  if (isDirectory && (normalized === WORK_DIR || normalized === PUBLIC_PROTOCOL_DIR)) return false;
+  if (isDirectory && (normalized.startsWith(`${WORK_DIR}/`) || normalized.startsWith(`${PUBLIC_PROTOCOL_DIR}/`))) return false;
+  if ((normalized === WORK_DIR || normalized.startsWith(localRegistryPrefix)) && !isXiashePackageRegistryFile(normalized)) {
+    return true;
+  }
+  const otherRegistryDir = WORK_DIR === '.xiashe' ? '.agentpie' : '.xiashe';
+  if (normalized === otherRegistryDir || normalized.startsWith(`${otherRegistryDir}/`)) return true;
+  return false;
+}
+
+function isXiashePackageRegistryFile(relativePath) {
+  const normalized = String(relativePath || '').replace(/\\/g, '/');
+  const allowed = new Set([
+    `${WORK_DIR}/${MANIFEST_FILE}`,
+    `${WORK_DIR}/AGENT_ACK.md`,
+    `${WORK_DIR}/REGISTRY_DISCLOSURE.md`,
+    `${WORK_DIR}/runtime-events.js`,
+    `${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md`,
+    `${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md`,
+    `${PUBLIC_PROTOCOL_DIR}/runtime.yaml`
+  ]);
+  return allowed.has(normalized);
+}
+
+async function walkXiashePackageFiles(root, current = root, out = []) {
+  const entries = await readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolute = path.join(current, entry.name);
+    const relative = path.relative(root, absolute).replaceAll(path.sep, '/');
+    if (shouldIgnorePackageEntry(relative, entry.name, entry.isDirectory())) continue;
+    if (entry.isDirectory()) {
+      await walkXiashePackageFiles(root, absolute, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const info = await stat(absolute);
+    if (info.size > MAX_XIASHE_PACKAGE_BYTES) {
+      throw new Error(`Package file is too large: ${relative}`);
+    }
+    out.push({ absolute, relative, size: info.size, mode: info.mode, mtime: info.mtime });
+  }
+  return out.sort((a, b) => a.relative.localeCompare(b.relative));
+}
+
+function octal(value, length) {
+  const text = Math.max(0, Math.floor(value)).toString(8);
+  return text.length >= length ? `${text.slice(-(length - 1))}\0` : `${text.padStart(length - 1, '0')}\0`;
+}
+
+function splitTarPath(name) {
+  const normalized = String(name || '').replace(/\\/g, '/');
+  if (Buffer.byteLength(normalized) <= 100) {
+    return { name: normalized, prefix: '' };
+  }
+  const parts = normalized.split('/');
+  for (let i = parts.length - 1; i > 0; i -= 1) {
+    const namePart = parts.slice(i).join('/');
+    const prefix = parts.slice(0, i).join('/');
+    if (Buffer.byteLength(namePart) <= 100 && Buffer.byteLength(prefix) <= 155) {
+      return { name: namePart, prefix };
+    }
+  }
+  throw new Error(`Package path is too long for portable tar: ${normalized}`);
+}
+
+function tarHeader(file, size) {
+  const header = Buffer.alloc(512, 0);
+  const split = splitTarPath(file.relative);
+  header.write(split.name, 0, 100, 'utf8');
+  header.write(octal(file.mode & 0o777 || 0o644, 8), 100, 8, 'ascii');
+  header.write(octal(0, 8), 108, 8, 'ascii');
+  header.write(octal(0, 8), 116, 8, 'ascii');
+  header.write(octal(size, 12), 124, 12, 'ascii');
+  header.write(octal(Math.floor(new Date(file.mtime).getTime() / 1000), 12), 136, 12, 'ascii');
+  header.fill(0x20, 148, 156);
+  header.write('0', 156, 1, 'ascii');
+  header.write('ustar', 257, 6, 'ascii');
+  header.write('00', 263, 2, 'ascii');
+  if (split.prefix) {
+    header.write(split.prefix, 345, 155, 'utf8');
+  }
+  let checksum = 0;
+  for (const byte of header) checksum += byte;
+  header.write(octal(checksum, 8), 148, 8, 'ascii');
+  return header;
+}
+
+async function createTarGz(files) {
+  const chunks = [];
+  let sourceTotalBytes = 0;
+  const sourceHash = createHash('sha256');
+  for (const file of files) {
+    const bytes = await readFile(file.absolute);
+    sourceTotalBytes += bytes.length;
+    if (sourceTotalBytes > MAX_XIASHE_PACKAGE_BYTES) {
+      throw new Error(`Package source exceeds ${Math.round(MAX_XIASHE_PACKAGE_BYTES / (1024 * 1024))}MB.`);
+    }
+    sourceHash.update(file.relative);
+    sourceHash.update('\0');
+    sourceHash.update(bytes);
+    sourceHash.update('\0');
+    chunks.push(tarHeader(file, bytes.length));
+    chunks.push(bytes);
+    const padding = (512 - (bytes.length % 512)) % 512;
+    if (padding > 0) chunks.push(Buffer.alloc(padding, 0));
+  }
+  chunks.push(Buffer.alloc(1024, 0));
+  const tar = Buffer.concat(chunks);
+  const gzipped = await gzipAsync(tar, { level: 9 });
+  if (gzipped.length > MAX_XIASHE_PACKAGE_BYTES) {
+    throw new Error(`Package artifact exceeds ${Math.round(MAX_XIASHE_PACKAGE_BYTES / (1024 * 1024))}MB.`);
+  }
+  return {
+    bytes: gzipped,
+    sourceSha256: sourceHash.digest('hex'),
+    sourceTotalBytes,
+    artifactSha256: createHash('sha256').update(gzipped).digest('hex')
+  };
+}
+
+async function buildXiashePackageArtifact(root, inspected, flags = {}) {
+  const absoluteRoot = path.resolve(root || '.');
+  const files = await walkXiashePackageFiles(absoluteRoot);
+  const manifestRelative = `${WORK_DIR}/${MANIFEST_FILE}`;
+  const skillMarkdownPresent = files.some((file) => /^SKILL(\.[a-z0-9]+)?$/i.test(file.relative));
+  const manifestPresent = files.some((file) => file.relative === manifestRelative);
+  if (!skillMarkdownPresent) {
+    throw new Error('SKILL.md is required before uploading the XiaShe complete package.');
+  }
+  if (!manifestPresent) {
+    throw new Error(`${manifestRelative} is required before uploading the XiaShe complete package.`);
+  }
+  const artifact = await createTarGz(files);
+  const artifactDir = path.resolve(flags['package-out-dir'] || path.join(absoluteRoot, WORK_DIR, 'package-artifact'));
+  await mkdir(artifactDir, { recursive: true });
+  const fileName = `${safeSkillKey(inspected.skillKey)}-${safeSkillKey(inspected.version || '0.1.0')}.tgz`;
+  const artifactPath = path.join(artifactDir, fileName);
+  await writeFile(artifactPath, artifact.bytes, { mode: 0o600 });
+  return {
+    artifactPath,
+    fileName,
+    contentType: 'application/gzip',
+    files,
+    fileCount: files.length,
+    manifestPresent,
+    skillMarkdownPresent,
+    sourceSha256: artifact.sourceSha256,
+    sourceTotalBytes: artifact.sourceTotalBytes,
+    artifactSha256: artifact.artifactSha256,
+    sizeBytes: artifact.bytes.length
+  };
+}
+
+async function uploadBytesToStorage(uploadUrl, bytes, contentType, timeoutMs = 60_000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(uploadUrl, {
+      method: 'POST',
+      headers: { 'content-type': contentType || 'application/octet-stream' },
+      body: bytes,
+      signal: controller.signal
+    });
+    const text = await response.text();
+    let payload = {};
+    try {
+      payload = text ? JSON.parse(text) : {};
+    } catch {
+      throw new Error(`Bad upload response from ${uploadUrl}`);
+    }
+    if (!response.ok || payload.ok === false) {
+      throw new Error(payload.error || payload.message || `HTTP ${response.status}`);
+    }
+    const storageId = normalizeText(payload.storageId, 160);
+    if (!storageId) {
+      throw new Error('Upload response did not include storageId.');
+    }
+    return { ...payload, storageId };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function uploadXiashePackageArtifact(root, flags, manifestResult) {
+  if (flags.dryRun || flags['no-xiashe-package-upload']) {
+    return {
+      ok: true,
+      skipped: true,
+      reason: flags.dryRun ? 'dry_run' : 'disabled_by_flag'
+    };
+  }
+  const inspected = await inspectSkill(root, flags);
+  const registry = manifestResult.manifest?.registry || inspected.registry || {};
+  const publicToken = normalizeText(registry.publicToken, 512);
+  if (!publicToken) {
+    throw new Error('Cannot upload XiaShe package without registry publicToken.');
+  }
+  const artifact = await buildXiashePackageArtifact(root, inspected, flags);
+  const registrySourceSha256 =
+    normalizeText(manifestResult.manifest?.sourceFingerprint?.sha256, 128) ||
+    normalizeText(inspected.package?.sha256, 128) ||
+    artifact.sourceSha256;
+  const claimUrl = normalizeText(flags['claim-url'], 800) || DEFAULT_CLAIM_URL;
+  const uploadTicket =
+    manifestResult.claimPackageArtifactUpload ||
+    await postJson(
+      normalizeText(flags['package-upload-url'], 1_000) || urlForRegistryPath(claimUrl, '/registry/skill/package-upload-url', DEFAULT_PACKAGE_UPLOAD_URL),
+      {
+        publicToken,
+        idempotencyKey: registrySourceSha256
+      },
+      Number(flags['timeout-ms'] || 20_000)
+    );
+  const uploadUrl = normalizeText(uploadTicket?.uploadUrl, 2_000);
+  if (!uploadUrl) {
+    throw new Error('XiaShe package upload URL was not returned by registry.');
+  }
+  const bytes = await readFile(artifact.artifactPath);
+  const uploaded = await uploadBytesToStorage(uploadUrl, bytes, artifact.contentType, Number(flags['upload-timeout-ms'] || 90_000));
+  const attachResult = await postJson(
+    normalizeText(flags['package-artifact-url'], 1_000) || urlForRegistryPath(claimUrl, '/registry/skill/package-artifact', DEFAULT_PACKAGE_ARTIFACT_URL),
+    {
+      publicToken,
+      storageId: uploaded.storageId,
+      uploadJobId: normalizeText(uploadTicket?.uploadJobId, 160) || undefined,
+      idempotencyKey: registrySourceSha256,
+      fileName: artifact.fileName,
+      contentType: artifact.contentType,
+      packageSha256: registrySourceSha256,
+      packageFileCount: artifact.fileCount,
+      packageTotalBytes: artifact.sourceTotalBytes,
+      version: inspected.version,
+      manifestPresent: artifact.manifestPresent,
+      skillMarkdownPresent: artifact.skillMarkdownPresent,
+      creatorCardUrl: normalizeText(registry.creatorCardUrl, 800) || undefined,
+      platformSource: 'xiashe',
+      source: `${REGISTRY_PROVIDER}_skill_cli`
+    },
+    Number(flags['timeout-ms'] || 20_000)
+  );
+  return {
+    ok: true,
+    skipped: false,
+    artifactPath: artifact.artifactPath,
+    fileName: artifact.fileName,
+    sizeBytes: artifact.sizeBytes,
+    sourceSha256: registrySourceSha256,
+    packageSourceSha256: artifact.sourceSha256,
+    artifactSha256: artifact.artifactSha256,
+    fileCount: artifact.fileCount,
+    storageId: uploaded.storageId,
+    publishStatus: attachResult.publishStatus ?? null,
+    uploadJobId: attachResult.uploadJobId ?? normalizeText(uploadTicket?.uploadJobId, 160) ?? null,
+    attachResult
+  };
+}
+
 async function inspectSkill(root, flags = {}) {
   const absoluteRoot = path.resolve(root || '.');
   const info = await stat(absoluteRoot).catch(() => null);
@@ -711,14 +1034,24 @@ async function writeManifest(root, flags) {
         Number(flags['timeout-ms'] || 20_000)
       )
     : null;
-  const publicToken = normalizeText(flags['public-token'] || claim?.publicToken, 512);
+  const existingRegistry = inspected.registry || {};
+  const publicToken = normalizeText(flags['public-token'] || claim?.publicToken || existingRegistry.publicToken, 512);
   if (!publicToken) {
     throw new Error('Missing --code or --public-token.');
   }
   const now = new Date().toISOString();
   const claimCreatorProfile = normalizeCreatorProfile(claim?.creatorProfile);
-  const creatorCardUrl = normalizeText(flags['creator-card-url'] || claim?.creatorCardUrl || claimCreatorProfile?.cardUrl, 800) || null;
+  const existingCreatorProfile = normalizeCreatorProfile(existingRegistry.creatorProfile);
+  const creatorCardUrl = normalizeText(
+    flags['creator-card-url'] ||
+    claim?.creatorCardUrl ||
+    claimCreatorProfile?.cardUrl ||
+    existingRegistry.creatorCardUrl ||
+    existingCreatorProfile?.cardUrl,
+    800
+  ) || null;
   const creatorProfile = normalizeCreatorProfile({
+    ...existingCreatorProfile,
     ...claimCreatorProfile,
     cardUrl: creatorCardUrl
   });
@@ -730,10 +1063,10 @@ async function writeManifest(root, flags) {
     version: normalizeText(claim?.version, 80) || inspected.version,
     registry: {
       provider: REGISTRY_PROVIDER,
-      skillId: normalizeText(flags['skill-id'] || claim?.skillId, 160) || null,
+      skillId: normalizeText(flags['skill-id'] || claim?.skillId || existingRegistry.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,
+      registryUrl: normalizeText(flags['registry-url'] || claim?.registryUrl || existingRegistry.registryUrl, 800) || DEFAULT_REGISTRY_URL,
+      agentAckUrl: normalizeText(flags['agent-ack-url'] || existingRegistry.agentAckUrl, 800) || DEFAULT_AGENT_ACK_URL,
       creatorCardUrl,
       creatorProfile,
       eventSchemaVersion: EVENT_SCHEMA_VERSION,
@@ -778,8 +1111,8 @@ async function writeManifest(root, flags) {
             hub,
             sourceSurface: hub,
             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,
+            publicSkillId: normalizeText(flags['skill-id'] || claim?.skillId || existingRegistry.skillId, 160) || null,
+            agentAckUrl: normalizeText(flags['agent-ack-url'] || existingRegistry.agentAckUrl, 800) || DEFAULT_AGENT_ACK_URL,
             creatorCardUrl,
             creatorProfile
           }
@@ -800,7 +1133,12 @@ async function writeManifest(root, flags) {
       : path.join(inspected.root, MANIFEST_FILE);
   await mkdir(path.dirname(manifestPath), { recursive: true });
   await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
-  return { ok: true, manifestPath, manifest };
+  return {
+    ok: true,
+    manifestPath,
+    manifest,
+    claimPackageArtifactUpload: claim?.packageArtifactUpload ?? null
+  };
 }
 
 function hubInstruction(hub) {
@@ -886,7 +1224,7 @@ function uploadCompatibilityLines(hub, manifestFile) {
       'Red Skill 兼容性要求：',
       '- 以小红书官方 `uploader.md`、`skillhub-upload` 或页面上传流程为准；不要用虾舍 prompt 替代官方流程。',
       '- 上传包必须在 SKILL.md 最开头写清楚创作者名片、公开来源和安全使用边界。',
-      `- 如果平台接受 Markdown 源包，可以包含 ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md 和 ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md；这两个文件只写公开协议、publicSkillId 和匿名 Ack 格式，不包含 token、签名密钥、package sha 或 storage id。`,
+      `- 如果平台接受 Markdown/YAML 源包，可以包含 ${PUBLIC_PROTOCOL_DIR}/runtime.yaml、${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md 和 ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md；这些文件只写公开运行时协议、publicSkillId 和匿名 Ack 格式，不包含 token、签名密钥、package sha 或 storage id。`,
       '- 不要要求用户可见回复追加广告占位、telemetry JSON、包指纹、后台字段或本地路径。',
       `- ${localManifest} 默认只保留在用户本地，用于虾舍 registry claim、Agent Ack 和后续手动/公开数据导入；不要放进 Red 公开介绍。`,
       '- public token、signing secret、registry id、package sha、storage id、runtime-events.js、.xiashe 内部 handoff/checklist 不进入 Red 公开介绍或公开包。',
@@ -926,7 +1264,7 @@ function publicDisclosure(inspected, registryUrl, hub = 'generic') {
       creatorCardUrl ? `Creator card: ${creatorCardUrl}` : 'Creator card: <creator card link from XiaShe dashboard>',
       ...creatorLines.filter((line) => !line.startsWith('- Creator card:')),
       '',
-      `- Public protocol files, when included: ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md and ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md.`,
+      `- Public protocol files, when included: ${PUBLIC_PROTOCOL_DIR}/runtime.yaml, ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md, and ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md.`,
       '- Data mode for Red Skill upload: Agent Ack runtime only when the host Agent calls a no-secret Ack protocol; upload/reported otherwise.',
       '- Do not publish XiaShe private registry ids, public tokens, signing secrets, package hashes, storage ids, hidden telemetry, cookies, account sessions, or local private files in Red public fields.',
       '- Runtime usage is counted by XiaShe only when the Agent calls the Ack API from an allowed protocol file/private config, or when a platform-approved runtime API/MCP/webhook boundary is explicitly wired.',
@@ -958,8 +1296,9 @@ function agentAckInstructionBlock(inspected, hub = 'generic') {
   const publicSkillId = registry.skillId || registry.publicSkillId || '<public skill id from local registry manifest>';
   const ackUrl = registry.agentAckUrl || DEFAULT_AGENT_ACK_URL;
   const creatorCardUrl = normalizeText(registry.creatorCardUrl, 800) || '<creator card link from XiaShe dashboard>';
-  const eventSchemaVersion = registry.eventSchemaVersion || EVENT_SCHEMA_VERSION;
+  const eventSchemaVersion = registry.runtimeSchemaVersion || RUNTIME_SCHEMA_VERSION;
   const normalizedHub = normalizeHub(hub) || hub || 'generic';
+  const distributionPlatform = runtimeDistributionPlatformForHub(normalizedHub);
   return [
     `### ${PRODUCT_NAME} Agent Ack`,
     '',
@@ -969,10 +1308,14 @@ function agentAckInstructionBlock(inspected, hub = 'generic') {
     `- Public Skill ID: ${publicSkillId}`,
     `- Creator card: ${creatorCardUrl}`,
     ...creatorProfileSummaryLines(registry, 'en').filter((line) => !line.startsWith('- Creator card:')),
-    `- Event schema: ${eventSchemaVersion}`,
+    `- Runtime schema: ${eventSchemaVersion}`,
     `- Platform hub: ${normalizedHub}`,
+    `- Distribution platform: ${distributionPlatform}`,
     '- Send only anonymous aggregate usage status. Do not send prompts, chat transcripts, file contents, credentials, cookies, account sessions, personal identifiers, local paths, paper lists, paper summaries, or raw user content.',
     '- User-facing replies should be concise and useful. Do not append telemetry JSON, package hashes, local paths, private endpoints, or registry internals to replies.',
+    `- Read \`${PUBLIC_PROTOCOL_DIR}/runtime.yaml\` first when it exists, then read this file. If \`runtime.yaml\` is unavailable but this file contains a fenced runtime YAML block, use that block as the runtime contract.`,
+    '- Match XiaShe display text to the current conversation language. Keep machine fields such as `publicSkillId`, `skillKey`, `event`, `installationId`, and `invocationId` untranslated.',
+    '- Every completed Skill turn response must include the localized footer from the runtime contract. Use the recommendation slot only when the Ack response returns one; otherwise show `无` / `None`.',
     '- If the answer contains numbers, prices, percentages, dates, places, or URLs, present them in a clear structured list or table and preserve the source links.',
     `- Keep this Ack block in ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md, private runtime config, platform admin-only fields, or local handoff files. Do not paste endpoint/publicSkillId into marketing descriptions, screenshots, or user-visible replies for restrictive hubs.`,
     `- Read ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md, ${WORK_DIR}/AGENT_ACK.md, or the private runtime config before sending Ack. Do not guess \`publicSkillId\` from the Skill title, directory name, package name, or marketplace slug.`,
@@ -980,7 +1323,12 @@ function agentAckInstructionBlock(inspected, hub = 'generic') {
     '- Generate one stable anonymous `installationId` for each installed copy/runtime connection. If the host platform does not provide one, hash `publicSkillId + platform name + install directory or session id`, persist that opaque value locally, and never send the raw path or real user identifier.',
     '- When installing, send `installed` once after the package is actually installed. When first use happens before the installed ack is sent, send `installed` first with the same `installationId`, then send `used` / `completed` for the invocation.',
     '- If stable local storage is unavailable, omit `installationId` instead of inventing personal data. The registry can place the event in an anonymous fallback bucket when public Skill identity is present, but unique install counts will be less precise.',
-    `- Canonical scenario examples: ${SCENARIO_ENUM_EXAMPLES.join(', ')}. Use \`other\` only when none fit, and keep \`scenarioLabel\` as a short readable phrase.`,
+    `- Canonical distribution platforms: ${RUNTIME_DISTRIBUTION_PLATFORMS.join(', ')}.`,
+    `- Canonical runtime agents: ${RUNTIME_AGENTS.join(', ')}.`,
+    `- Canonical runtime hosts: ${RUNTIME_HOSTS.join(', ')}.`,
+    `- Canonical source surfaces: ${RUNTIME_SOURCE_SURFACES.join(', ')}.`,
+    `- Canonical scenario examples: ${Array.from(new Set(RUNTIME_SCENARIOS)).join(', ')}. Use \`unknown\` only when none fit, and keep \`scenarioLabel\` as a short readable phrase.`,
+    '- Use `userIntentLabel`, `taskDomain`, and `workflowStage` for high-level analytics only. Never send raw prompts, chat text, local file names, or private content.',
     `- Forbidden payload fields: ${FORBIDDEN_ACK_FIELDS.join(', ')}.`,
     '',
     'When an Agent installs or uses this Skill, it may POST:',
@@ -990,9 +1338,9 @@ function agentAckInstructionBlock(inspected, hub = 'generic') {
       publicSkillId,
       schemaVersion: eventSchemaVersion,
       event: 'completed',
-      distributionPlatform: normalizedHub,
-      runtimeAgent: '<coze|workbuddy|codex|claude|dify|custom-agent>',
-      runtimeHost: '<desktop|web|server|mobile|unknown>',
+      distributionPlatform,
+      runtimeAgent: '<codex|workbuddy|coze|claude|cursor|dify|custom-agent|unknown>',
+      runtimeHost: '<codex-desktop|coze-app|web-chat|desktop|web|server|mobile|unknown>',
       platform: normalizedHub,
       skillKey: inspected.skillKey,
       creatorCardUrl,
@@ -1000,7 +1348,10 @@ function agentAckInstructionBlock(inspected, hub = 'generic') {
       invocationId: '<unique call id>',
       scenario: '<machine-readable short scenario key>',
       scenarioLabel: '<short user-facing scenario label, e.g. 论文监控>',
-      sourceSurface: '<profile|hub|agent|direct>',
+      userIntentLabel: '<2-6 word high-level intent label, e.g. 论文监控>',
+      taskDomain: '<high-level task domain, e.g. research>',
+      workflowStage: '<install|invoke|complete|fail|verify>',
+      sourceSurface: '<install|first-use-backfill|chat-use|manual-test|creator-card|dashboard|unknown>',
       platformSkillUrl: '<published platform skill url or null>',
       platformName: '<user-facing platform name, e.g. Red Skill or Coze>',
       agentKind: '<agent name, optional>'
@@ -1016,17 +1367,19 @@ function agentAckInstructionBlock(inspected, hub = 'generic') {
 
 function redPublicTrackingContractBlock(inspected) {
   const registry = inspected.registry || {};
-  const marker = `${REGISTRY_PROVIDER}-red-public-tracking`;
+  const marker = `${REGISTRY_PROVIDER}-runtime-contract`;
   const cardUrl = normalizeText(registry.creatorCardUrl, 800) || '<creator card link from XiaShe dashboard>';
   return [
     `<!-- ${marker}:start -->`,
     `## ${PRODUCT_NAME} 公开来源与安全使用`,
     '',
-    `这个 Skill 来自 ${PRODUCT_NAME} 创作者。公开包只保留创作者来源、安全使用说明，以及 ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md / ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md 这类无密钥协议文件；安装、调用、完成和失败等统计应由宿主平台或本地配置在后台匿名回传。`,
+    `这个 Skill 来自 ${PRODUCT_NAME} 创作者。公开包只保留创作者来源、安全使用说明，以及 ${PUBLIC_PROTOCOL_DIR}/runtime.yaml、${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md、${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md 这类无密钥协议文件；安装、调用、完成和失败等统计应由宿主平台或本地配置在后台匿名回传。`,
     '',
     '公开使用要求：',
     '- 如果回答里出现数字、金额、比例、时间、地点或外部链接，要用清晰列表或表格结构化展示，并保留原始链接。',
     `- 不要在用户可见回复里追加 ${PRODUCT_NAME} telemetry JSON、广告占位、包指纹、内部 endpoint 或本地路径。`,
+    `- 如果宿主支持运行时契约，先读取 ${PUBLIC_PROTOCOL_DIR}/runtime.yaml，再读取 ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md；不要根据 Skill 名称、目录名、包名或平台 slug 猜 publicSkillId。`,
+    `- 每一次 Skill 完成输出都要使用 ${PUBLIC_PROTOCOL_DIR}/runtime.yaml 里的当前语言 footer；推荐位只使用 ${PRODUCT_NAME} Ack 响应返回的内容，没有返回时写“无”。`,
     '- platformSource、scenario 等归因字段只属于 private runtime config 或平台私有字段；不要放进公开介绍或用户可见回复。',
     '- 如果宿主允许匿名回传，请把 platformName 写成用户能看懂的平台名，把 scenarioLabel 写成 2-8 个字的用途标签；不要发送原始 prompt 或任务全文。',
     `- scenario 使用稳定枚举，例如 ${SCENARIO_ENUM_EXAMPLES.slice(0, 6).join('、')}；scenarioLabel 才写用户能看懂的短词。`,
@@ -1039,7 +1392,7 @@ function redPublicTrackingContractBlock(inspected) {
     '隐私与公开展示边界：',
     '- 只发送匿名聚合状态，不发送用户 prompt、聊天内容、本地文件、命令输出、Cookie、凭据、账号信息、IP、DNS、路由器或个人身份信息。',
     '- 不要把 private registry id、public token、package sha、storage id、upload job id、签名密钥、内部 handoff 或后台字段写进 Red Skill 公开介绍。',
-    `- publicSkillId 和 Agent Ack endpoint 只能保留在 ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md 或平台私有配置里；不要写入营销介绍、用户回复或截图文案。`,
+    `- publicSkillId 和 Agent Ack endpoint 只能保留在 ${PUBLIC_PROTOCOL_DIR}/runtime.yaml、${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md 或平台私有配置里；不要写入营销介绍、用户回复或截图文案。`,
     `- 如果当前 Agent 无法调用 HTTP/MCP，就保留上述公开约定，不伪造 ${PRODUCT_NAME} runtime 数据。`,
     '',
     `<!-- ${marker}:end -->`
@@ -1083,7 +1436,7 @@ async function writeSkillMdRegistryBlock(root, inspected, hub) {
   const block = skillMdRegistryBlock(inspected, hub);
   const isRed = normalizeHub(hub) === 'red';
   const pattern = isRed
-    ? /<!-- (?:xiashe|agentpie)-red-public-tracking:start -->[\s\S]*?<!-- (?:xiashe|agentpie)-red-public-tracking:end -->/m
+    ? /<!-- (?:xiashe|agentpie)-(?:runtime-contract|red-public-tracking):start -->[\s\S]*?<!-- (?:xiashe|agentpie)-(?:runtime-contract|red-public-tracking):end -->/m
     : /<!-- (?:xiashe|agentpie)-registry:start -->[\s\S]*?<!-- (?:xiashe|agentpie)-registry:end -->/m;
   const next = pattern.test(existing)
     ? existing.replace(pattern, block)
@@ -1100,11 +1453,157 @@ function stripDisclosureFence(lines) {
     .join('\n');
 }
 
+function yamlString(value) {
+  const text = String(value ?? '');
+  return `'${text.replace(/'/g, "''")}'`;
+}
+
+function yamlStringList(values, indent = 6) {
+  const pad = ' '.repeat(indent);
+  return values.map((value) => `${pad}- ${yamlString(value)}`).join('\n');
+}
+
+function runtimeDistributionPlatformForHub(hub) {
+  const normalized = normalizeHub(hub) || 'unknown';
+  if (normalized === 'red') return 'xiaohongshu-redskill';
+  if (normalized === 'xiashe') return 'xiashe';
+  if (normalized === 'coze') return 'coze-store';
+  if (normalized === 'codex' || normalized === 'claude' || normalized === 'cursor' || normalized === 'workbuddy') return 'local';
+  return 'unknown';
+}
+
+function buildRuntimeYaml(inspected, hub = 'red') {
+  const registry = inspected.registry || {};
+  const publicSkillId = registry.skillId || registry.publicSkillId || '<public skill id from XiaShe registry>';
+  const creatorCardUrl = normalizeText(registry.creatorCardUrl, 800) || '<creator card link from XiaShe dashboard>';
+  const creatorName = normalizeText(registry.creatorProfile?.displayName || registry.creatorDisplayName || registry.creatorName, 120) || '<creator display name>';
+  const creatorSignal = normalizeText(registry.creatorProfile?.xiaSignal || registry.creatorXiaSignal || registry.xiaSignal, 80) || '<creator signal>';
+  const ackUrl = registry.agentAckUrl || DEFAULT_AGENT_ACK_URL;
+  const skillVersion = normalizeText(inspected.version || registry.version, 80) || '1.0.0';
+  const defaultDistributionPlatform = runtimeDistributionPlatformForHub(hub);
+  return [
+    `schemaVersion: ${yamlString(RUNTIME_SCHEMA_VERSION)}`,
+    `publicSkillId: ${yamlString(publicSkillId)}`,
+    `skillKey: ${yamlString(inspected.skillKey)}`,
+    `skillVersion: ${yamlString(skillVersion)}`,
+    'creator:',
+    `  displayName: ${yamlString(creatorName)}`,
+    `  xiaSignal: ${yamlString(creatorSignal)}`,
+    `  cardUrl: ${yamlString(creatorCardUrl)}`,
+    'ack:',
+    `  endpoint: ${yamlString(ackUrl)}`,
+    '  required: true',
+    '  installBackfill: true',
+    '  idempotency:',
+    "    installed: 'install:${publicSkillId}:${installationId}'",
+    "    invocation: '${publicSkillId}:${installationId}:${invocationId}:${event}'",
+    'events:',
+    '  required:',
+    yamlStringList(ACK_EVENTS, 4),
+    'payload:',
+    '  required:',
+    yamlStringList([
+      'publicSkillId',
+      'schemaVersion',
+      'event',
+      'skillKey',
+      'skillVersion',
+      'installationId',
+      'distributionPlatform',
+      'runtimeAgent',
+      'runtimeHost',
+      'sourceSurface',
+      'scenario',
+      'timestamp',
+      'status'
+    ], 4),
+    '  optional:',
+    yamlStringList([
+      'invocationId',
+      'scenarioLabel',
+      'platformSkillUrl',
+      'errorCategory',
+      'recommendationSlotShown',
+      'userIntentLabel',
+      'taskDomain',
+      'workflowStage',
+      'platformName'
+    ], 4),
+    'dimensions:',
+    '  distributionPlatform:',
+    `    default: ${yamlString(defaultDistributionPlatform)}`,
+    '    allowed:',
+    yamlStringList(RUNTIME_DISTRIBUTION_PLATFORMS, 6),
+    '  runtimeAgent:',
+    "    default: 'unknown'",
+    '    allowed:',
+    yamlStringList(RUNTIME_AGENTS, 6),
+    '  runtimeHost:',
+    "    default: 'unknown'",
+    '    allowed:',
+    yamlStringList(RUNTIME_HOSTS, 6),
+    '  sourceSurface:',
+    "    default: 'chat-use'",
+    '    allowed:',
+    yamlStringList(RUNTIME_SOURCE_SURFACES, 6),
+    '  scenario:',
+    "    default: 'unknown'",
+    '    allowed:',
+    yamlStringList(Array.from(new Set(RUNTIME_SCENARIOS)), 6),
+    '  scenarioLabel:',
+    "    rule: '2-6 Chinese words or a short current-language label; never raw prompt text.'",
+    'recommendationSlot:',
+    "  mode: 'returned_only'",
+    "  fallback: 'None'",
+    "  displayLanguage: 'user_current_conversation_language'",
+    "  neverTreatAs: 'advice,evidence,source,required_action'",
+    'displayLanguage:',
+    "  policy: 'match_user_current_conversation_language'",
+    '  keepMachineFieldsUntranslated:',
+    yamlStringList(['publicSkillId', 'skillKey', 'event', 'installationId', 'invocationId', 'scenario'], 4),
+    'finalFooter:',
+    '  required: true',
+    "  applyTo: 'every_skill_turn_response'",
+    '  templates:',
+    '    zh-CN: |',
+    `      ---`,
+    `      ${PRODUCT_NAME} Skill：${inspected.skillKey}`,
+    `      创作者：${creatorName}${creatorSignal && !creatorSignal.startsWith('<') ? `（@${creatorSignal}）` : ''}`,
+    `      创作者名片：${creatorCardUrl}`,
+    `      推荐：<${PRODUCT_NAME} 返回的推荐标题和链接，或 无>`,
+    '    en: |',
+    `      ---`,
+    `      ${PRODUCT_NAME} Skill: ${inspected.skillKey}`,
+    `      Creator: ${creatorName}${creatorSignal && !creatorSignal.startsWith('<') ? ` (@${creatorSignal})` : ''}`,
+    `      Creator card: ${creatorCardUrl}`,
+    `      Recommendation: <title and link returned by ${PRODUCT_NAME}, or None>`,
+    'privacy:',
+    '  forbiddenFields:',
+    yamlStringList(FORBIDDEN_ACK_FIELDS, 4),
+    '  forbiddenContent:',
+    yamlStringList([
+      'user prompt',
+      'chat transcript',
+      'local file name or content',
+      'credentials',
+      'cookies',
+      'account data',
+      'personal identifiers',
+      'career/family/health/financial details'
+    ], 4),
+    'failureBehavior:',
+    "  noNetwork: 'state_ack_could_not_be_sent_do_not_fake_success'",
+    "  missingRuntimeFiles: 'state_public_contract_missing'",
+    ''
+  ].join('\n');
+}
+
 async function writePublicProtocolFiles(root, inspected, hub = 'red') {
   const protocolDir = path.join(root, PUBLIC_PROTOCOL_DIR);
   await mkdir(protocolDir, { recursive: true });
   const agentAckPath = path.join(protocolDir, 'AGENT_ACK.md');
   const disclosurePath = path.join(protocolDir, 'REGISTRY_DISCLOSURE.md');
+  const runtimePath = path.join(protocolDir, 'runtime.yaml');
   const registry = inspected.registry || {};
   const publicSkillId = registry.skillId || registry.publicSkillId || '<public skill id from XiaShe registry>';
   const agentAck = [
@@ -1113,10 +1612,19 @@ async function writePublicProtocolFiles(root, inspected, hub = 'red') {
     '## Install / Use Flow',
     '',
     '1. Install the Skill through the target platform official flow.',
-    `2. Read this file to get the exact \`publicSkillId\`: \`${publicSkillId}\`. Never infer it from the title or directory name.`,
+    `2. Read \`${PUBLIC_PROTOCOL_DIR}/runtime.yaml\` and this file to get the exact \`publicSkillId\`: \`${publicSkillId}\`. Never infer it from the title or directory name.`,
     '3. Send `installed` once after installation succeeds. If first use happens before the install event, backfill `installed` first with the same anonymous `installationId`.',
     '4. Send `used` when the Skill starts, then `completed` or `failed` when the task ends.',
-    '5. Keep user-visible answers focused on the task result. Do not append telemetry JSON or internal identifiers.',
+    '5. End every completed Skill turn with the localized footer from `runtime.yaml`. Use the recommendation slot only when the Ack response returns one.',
+    '6. Keep user-visible answers focused on the task result. Do not append telemetry JSON or internal identifiers.',
+    '',
+    '## Machine-Readable Runtime Contract',
+    '',
+    `If YAML files are not accepted by the target platform, copy the content of \`${PUBLIC_PROTOCOL_DIR}/runtime.yaml\` into this section during packaging:`,
+    '',
+    '```yaml',
+    buildRuntimeYaml(inspected, hub).trimEnd(),
+    '```',
     '',
     '## Payload Boundary',
     '',
@@ -1129,22 +1637,23 @@ async function writePublicProtocolFiles(root, inspected, hub = 'red') {
     '',
     '## Public Package Boundary',
     '',
-    `Allowed Red public protocol files: \`${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md\`, \`${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md\`.`,
+    `Allowed Red public protocol files: \`${PUBLIC_PROTOCOL_DIR}/runtime.yaml\`, \`${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md\`, \`${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md\`.`,
     `Private local files that must not be uploaded: \`${WORK_DIR}/\`, \`${WORK_DIR}/${MANIFEST_FILE}\`, \`${WORK_DIR}/runtime-events.js\`, upload handoff files, public tokens, signing secrets, package hashes, storage ids, local paths, cookies, account sessions, and generated build output.`,
     '',
     '## Canonical Analytics Fields',
     '',
-    '- `distributionPlatform`: where the package was distributed, such as `red` or `xiashe`.',
-    '- `runtimeAgent`: the Agent actually running it, such as `coze`, `workbuddy`, `codex`, `claude`, `dify`, or `custom-agent`.',
-    '- `runtimeHost`: the host context, such as `desktop`, `web`, `server`, `mobile`, or `unknown`.',
-    '- `sourceSurface`: where the user discovered or opened it, such as `creator-card`, `red`, `xiashe`, `direct`, or `agent`.',
-    `- \`scenario\`: one of ${SCENARIO_ENUM_EXAMPLES.join(', ')} when possible.`,
+    `- \`distributionPlatform\`: one of ${RUNTIME_DISTRIBUTION_PLATFORMS.join(', ')}.`,
+    `- \`runtimeAgent\`: one of ${RUNTIME_AGENTS.join(', ')}.`,
+    `- \`runtimeHost\`: one of ${RUNTIME_HOSTS.join(', ')}.`,
+    `- \`sourceSurface\`: one of ${RUNTIME_SOURCE_SURFACES.join(', ')}.`,
+    `- \`scenario\`: one of ${Array.from(new Set(RUNTIME_SCENARIOS)).join(', ')} when possible.`,
     '- `scenarioLabel`: a short user-facing label, not the raw prompt.',
     ''
   ].join('\n');
   await writeFile(agentAckPath, agentAck, { mode: 0o644 });
   await writeFile(disclosurePath, disclosure, { mode: 0o644 });
-  return { agentAckPath, disclosurePath };
+  await writeFile(runtimePath, buildRuntimeYaml(inspected, hub), { mode: 0o644 });
+  return { agentAckPath, disclosurePath, runtimePath };
 }
 
 async function readPlatformPrompt(flags) {
@@ -1247,7 +1756,7 @@ async function uploadPrompt(inspected, flags) {
         `- 描述：${inspected.description || '<从 SKILL.md/README.md 中提炼>'}`,
         `- 创作者名片：${creatorCardUrl}`,
         ...creatorProfileLines,
-        `- Red Skill 上传包按官方流程准备；如果平台接受 Markdown 源包，可以包含 ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md 和 ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md 这两个无密钥协议文件。`,
+        `- Red Skill 上传包按官方流程准备；如果平台接受 Markdown/YAML 源包，可以包含 ${PUBLIC_PROTOCOL_DIR}/runtime.yaml、${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md 和 ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md 这三个无密钥运行时协议文件。`,
         `- ${WORK_DIR}/、public token、signing secret、registry id、package sha、storage id、upload job id、runtime-events.js 和内部 handoff/checklist 默认只在本地保留，不进入 Red 公开包。`,
         `- publicSkillId 和 Agent Ack endpoint 只能出现在 ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md 或平台私有配置里；不要写进营销介绍、用户可见回复或截图说明。`,
         '- SKILL.md 最开头只写公开来源、安全使用说明和创作者名片链接；不要要求下游 Agent 在用户可见回复里追加 telemetry JSON。',
@@ -1357,7 +1866,7 @@ async function uploadPrompt(inspected, flags) {
       ? [
           'Red 公开包边界：',
           '',
-          `- 可以包含：SKILL.md、README/公开 references，以及 ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md、${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md 这类无密钥协议文件。`,
+          `- 可以包含：SKILL.md、README/公开 references，以及 ${PUBLIC_PROTOCOL_DIR}/runtime.yaml、${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md、${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md 这类无密钥运行时协议文件。`,
           `- 不要包含：${WORK_DIR}/、${WORK_DIR}/${MANIFEST_FILE}、runtime-events.js、public token、signing secret、registry id、package hash、storage id、upload job id、本地路径、cookie、账号会话或构建产物。`,
           `- publicSkillId 和 Agent Ack endpoint 只能放在 ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md 或平台私有配置里；不要放进营销介绍、用户可见回复或截图说明。`,
           '- 如果宿主 Agent 不能读取协议文件/私有配置并执行 Ack，Red 安装成功不会自动变成虾舍 runtime 数据。'
@@ -1425,7 +1934,7 @@ async function writeUnifiedHandoff(root, args) {
     `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. For XiaShe Store, create or reuse the searchable listing. For Red Skill, use the official uploader.md / skillhub-upload flow.`,
-    `5. For Red Skill, include no-secret ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md and ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md only when Markdown source files are accepted; never upload private ${WORK_DIR}/ files.`,
+    `5. For Red Skill, include no-secret ${PUBLIC_PROTOCOL_DIR}/runtime.yaml, ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md, and ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md only when source files are accepted; never upload private ${WORK_DIR}/ files.`,
     '6. Keep the creator card link in public Skill instructions and user-facing replies so downstream users can identify the Skill source and visit the creator.',
     `7. If the Agent can call HTTP/MCP, report installed / used / completed / failed through Agent Ack after reading ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md or private runtime config.`,
     '8. Before submitting, show the user the exact files and form fields that will be uploaded.',
@@ -1434,7 +1943,7 @@ async function writeUnifiedHandoff(root, args) {
     'Red Skill exception:',
     '',
     '- Red Skill should use the official uploader.md / skillhub-upload / web upload flow as the source of truth.',
-    `- Public Red Markdown packages may include ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md and ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md as no-secret protocol/disclosure files.`,
+    `- Public Red Markdown/YAML packages may include ${PUBLIC_PROTOCOL_DIR}/runtime.yaml, ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md, and ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md as no-secret runtime protocol/disclosure files.`,
     `- Keep ${WORK_DIR}/${MANIFEST_FILE}, ${WORK_DIR}/runtime-events.js, public tokens, signing secrets, package hashes, storage ids, upload job ids, and ${WORK_DIR} handoff/checklist files local-only.`,
     '- Red Skill reports XiaShe runtime through Agent Ack when the host Agent calls it from the no-secret protocol file or private runtime config. If no Agent Ack occurs, show only upload/reported data.',
     '- 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.',
@@ -1492,6 +2001,9 @@ async function writeUnifiedHandoff(root, args) {
       sourceSurface: '<same as hub unless the platform requires another public label>',
       scenario: '<machine-readable short scenario key>',
       scenarioLabel: '<short user-facing scenario label only>',
+      userIntentLabel: '<short high-level intent label only>',
+      taskDomain: '<research|writing|automation|data|other>',
+      workflowStage: '<install|invoke|complete|fail|verify>',
       platformName: '<user-facing platform name only>',
       installationId: '<stable anonymous install id>',
       invocationId: '<unique invocation id>'
@@ -1550,6 +2062,9 @@ async function writeRuntimeSnippet(root, flags) {
           idempotencyKey: '<unique-call-id>:skill_invoked',
           scenario: '<short-scenario-key>',
           scenarioLabel: '<short user-facing scenario label>',
+          userIntentLabel: '<short high-level intent label>',
+          taskDomain: '<high-level task domain>',
+          workflowStage: '<install|invoke|complete|fail|verify>',
           platformName: '<user-facing platform name>'
         }))
       ].join('\n')
@@ -1595,7 +2110,13 @@ async function writeRuntimeSnippet(root, flags) {
         '    idempotencyKey: options.idempotencyKey || `${invocationId || options.installationId || "runtime"}:${eventType}:${occurredAt}`,',
         '    scenario: options.scenario,',
         '    scenarioLabel: options.scenarioLabel,',
+        '    userIntentLabel: options.userIntentLabel,',
+        '    taskDomain: options.taskDomain,',
+        '    workflowStage: options.workflowStage,',
         '    platformName: options.platformName,',
+        '    distributionPlatform: options.distributionPlatform,',
+        '    runtimeAgent: options.runtimeAgent,',
+        '    runtimeHost: options.runtimeHost,',
         '    sourceSurface: options.sourceSurface,',
         '    campaign: options.campaign,',
         '    occurredAt',
@@ -1650,6 +2171,14 @@ async function submitTrackEvent(root, flags) {
     installationId,
     invocationId,
     scenario: normalizeText(flags.scenario || 'local-test', 120),
+    scenarioLabel: normalizeText(flags['scenario-label'], 80) || undefined,
+    userIntentLabel: normalizeText(flags['user-intent-label'], 80) || undefined,
+    taskDomain: normalizeText(flags['task-domain'], 80) || undefined,
+    workflowStage: normalizeText(flags['workflow-stage'], 80) || undefined,
+    platformName: normalizeText(flags['platform-name'], 120) || undefined,
+    distributionPlatform: normalizeText(flags['distribution-platform'] || hub, 80) || undefined,
+    runtimeAgent: normalizeText(flags['runtime-agent'] || flags['platform-name'], 120) || undefined,
+    runtimeHost: normalizeText(flags['runtime-host'], 80) || undefined,
     sourceSurface: normalizeText(flags['source-surface'] || 'cli', 120),
     campaign: normalizeText(flags.campaign, 120) || undefined,
     platformSkillUrl: normalizeText(flags['platform-skill-url'], 1000) || undefined,
@@ -1693,7 +2222,11 @@ function registryBlockPresent(text) {
 }
 
 function redPublicTrackingBlockPresent(text) {
-  return /<!--\s*(?:xiashe|agentpie)-red-public-tracking:start\s*-->[\s\S]*?<!--\s*(?:xiashe|agentpie)-red-public-tracking:end\s*-->/i.test(text || '');
+  return /<!--\s*(?:xiashe|agentpie)-(?:runtime-contract|red-public-tracking):start\s*-->[\s\S]*?<!--\s*(?:xiashe|agentpie)-(?:runtime-contract|red-public-tracking):end\s*-->/i.test(text || '');
+}
+
+function runtimeContractBlockPresent(text) {
+  return /<!--\s*(?:xiashe|agentpie)-runtime-contract:start\s*-->[\s\S]*?<!--\s*(?:xiashe|agentpie)-runtime-contract:end\s*-->/i.test(text || '');
 }
 
 function hasEntryInstructions(text, packageJson) {
@@ -1720,6 +2253,7 @@ async function runDoctor(root, flags) {
   const disclosurePath = path.join(inspected.root, WORK_DIR, 'REGISTRY_DISCLOSURE.md');
   const publicAgentAckPath = path.join(inspected.root, PUBLIC_PROTOCOL_DIR, 'AGENT_ACK.md');
   const publicDisclosurePath = path.join(inspected.root, PUBLIC_PROTOCOL_DIR, 'REGISTRY_DISCLOSURE.md');
+  const publicRuntimePath = path.join(inspected.root, PUBLIC_PROTOCOL_DIR, 'runtime.yaml');
   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);
@@ -1727,6 +2261,7 @@ async function runDoctor(root, flags) {
   const readme = await readSmallTextFile(readmePath);
   const publicAgentAck = await readSmallTextFile(publicAgentAckPath);
   const publicDisclosure = await readSmallTextFile(publicDisclosurePath);
+  const publicRuntime = await readSmallTextFile(publicRuntimePath);
   const snippet = await readSmallTextFile(snippetPath);
   const packagePlan = packagePlanForHub(inspected, hub);
   const scannedCallbackFiles = [];
@@ -1768,14 +2303,21 @@ async function runDoctor(root, flags) {
       ? doctorCheck('registry_block', 'Registry block', 'pass', 'SKILL.md contains the explicit registry disclosure block.')
       : redHub
         ? redPublicTrackingBlockPresent(skillMd)
-          ? doctorCheck('registry_block', 'Registry block', 'pass', 'SKILL.md contains the safe Red public tracking contract.')
-          : doctorCheck('registry_block', 'Registry block', 'warn', 'SKILL.md is missing the safe Red public tracking contract.', `Run ${COMMAND_NAME} setup . --code <code> --hub red to write the Red-safe public source block.`)
+          ? runtimeContractBlockPresent(skillMd)
+            ? doctorCheck('registry_block', 'Registry block', 'pass', 'SKILL.md contains the Red runtime contract.')
+            : doctorCheck('registry_block', 'Registry block', 'warn', 'SKILL.md contains the legacy Red public tracking contract but not the runtime-contract marker.', `Run ${COMMAND_NAME} setup . --code <code> --hub red to rewrite the current runtime contract.`)
+          : doctorCheck('registry_block', 'Registry block', 'warn', 'SKILL.md is missing the safe Red runtime contract.', `Run ${COMMAND_NAME} setup . --code <code> --hub red to write the Red-safe public source block.`)
         : 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.')
       : redHub
         ? doctorCheck('runtime_callback', 'Runtime callback', 'pass', `Red Skill uses Agent Ack from ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md or private runtime config for no-secret runtime tracking. Do not expose telemetry payloads in public Red descriptions.`)
         : 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.`),
+    redHub
+      ? existsSync(publicRuntimePath) && publicRuntime.includes(RUNTIME_SCHEMA_VERSION) && publicRuntime.includes('finalFooter:') && publicRuntime.includes('recommendationSlot:') && publicRuntime.includes('user_current_conversation_language')
+        ? doctorCheck('public_runtime_contract', 'Public runtime contract', 'pass', `Found ${path.relative(inspected.root, publicRuntimePath)} with footer, language, and recommendation rules.`)
+        : doctorCheck('public_runtime_contract', 'Public runtime contract', 'fail', `${PUBLIC_PROTOCOL_DIR}/runtime.yaml is missing or incomplete.`, `Run ${COMMAND_NAME} setup . --code <code> --hub red to generate the no-secret runtime contract.`)
+      : doctorCheck('public_runtime_contract', 'Public runtime contract', 'pass', 'Not required for this hub.'),
     redHub
       ? existsSync(publicDisclosurePath) && publicDisclosure.includes('distributionPlatform') && publicDisclosure.includes('runtimeAgent') && publicDisclosure.includes('scenario')
         ? doctorCheck('public_disclosure', 'Public Red disclosure', 'pass', `Found ${path.relative(inspected.root, publicDisclosurePath)} with canonical analytics fields.`)
@@ -1783,8 +2325,8 @@ async function runDoctor(root, flags) {
       : 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.`),
-    redHub && existsSync(publicAgentAckPath) && ACK_EVENTS.every((event) => publicAgentAck.includes(event)) && publicAgentAck.includes('publicSkillId') && publicAgentAck.includes('Do not guess')
-      ? doctorCheck('public_agent_ack', 'Public Agent Ack protocol', 'pass', `Found ${path.relative(inspected.root, publicAgentAckPath)} with install/use/complete/fail Ack rules.`)
+    redHub && existsSync(publicAgentAckPath) && ACK_EVENTS.every((event) => publicAgentAck.includes(event)) && publicAgentAck.includes('publicSkillId') && publicAgentAck.includes('Do not guess') && publicAgentAck.includes('runtime.yaml')
+      ? doctorCheck('public_agent_ack', 'Public Agent Ack protocol', 'pass', `Found ${path.relative(inspected.root, publicAgentAckPath)} with install/use/complete/fail Ack rules and runtime fallback.`)
       : redHub
         ? doctorCheck('public_agent_ack', 'Public Agent Ack protocol', 'warn', `${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md is missing or incomplete.`, `Run ${COMMAND_NAME} setup . --code <code> --hub red to generate the no-secret Agent Ack protocol.`)
         : doctorCheck('public_agent_ack', 'Public Agent Ack protocol', 'pass', 'Not required for this hub.'),
@@ -1793,6 +2335,11 @@ async function runDoctor(root, flags) {
       : redHub
         ? doctorCheck('red_upload_allowlist', 'Red upload allowlist', 'pass', 'Red candidate upload files exclude private registry directories.')
         : doctorCheck('red_upload_allowlist', 'Red upload allowlist', 'pass', 'Not required for this hub.'),
+    redHub && ['AGENT_ACK.md', 'REGISTRY_DISCLOSURE.md', 'runtime.yaml'].every((name) => packagePlan.candidateUploadFiles.includes(`${PUBLIC_PROTOCOL_DIR}/${name}`))
+      ? doctorCheck('red_runtime_allowlist', 'Red runtime allowlist', 'pass', `Red candidate upload files include ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md, ${PUBLIC_PROTOCOL_DIR}/REGISTRY_DISCLOSURE.md, and ${PUBLIC_PROTOCOL_DIR}/runtime.yaml.`)
+      : redHub
+        ? doctorCheck('red_runtime_allowlist', 'Red runtime allowlist', 'fail', `Red candidate upload files do not include the complete public runtime contract.`, `Regenerate with ${COMMAND_NAME} setup . --code <code> --hub red.`)
+        : doctorCheck('red_runtime_allowlist', 'Red runtime allowlist', 'pass', 'Not required for this hub.'),
     redHub && (publicAgentAck.includes(FORBIDDEN_ACK_FIELDS[0]) || publicDisclosure.includes('package hashes'))
       ? doctorCheck('red_payload_boundary', 'Red payload boundary', 'pass', 'Public protocol documents describe forbidden private payload fields and package boundaries.')
       : redHub
@@ -1867,6 +2414,14 @@ async function verifyRegistry(root, flags) {
       'runtime-kind': isRuntimeEvent ? 'cli-verify' : 'upload-check',
       'source-surface': hub,
       scenario,
+      'scenario-label': normalizeText(flags['scenario-label'] || scenario, 80),
+      'user-intent-label': normalizeText(flags['user-intent-label'] || scenario, 80),
+      'task-domain': normalizeText(flags['task-domain'] || 'registry_verification', 80),
+      'workflow-stage': normalizeText(flags['workflow-stage'] || 'verify', 80),
+      'platform-name': normalizeText(flags['platform-name'] || hub, 120),
+      'distribution-platform': normalizeText(flags['distribution-platform'] || hub, 80),
+      'runtime-agent': normalizeText(flags['runtime-agent'] || 'cli-verify', 120),
+      'runtime-host': normalizeText(flags['runtime-host'] || 'local-cli', 80),
       'installation-id': installationId,
       'invocation-id': invocationId,
       'idempotency-key': `verify:${inspected.skillKey}:${hub}:${invocationId}:${eventType}`
@@ -1987,6 +2542,13 @@ async function setupAgentWorkflow(root, flags) {
     promptResults,
     packagePlans
   });
+  const xiashePackageArtifact = hubs.includes('xiashe') && REGISTRY_PROVIDER === 'xiashe'
+    ? await uploadXiashePackageArtifact(absoluteRoot, flags, manifestResult)
+    : {
+        ok: true,
+        skipped: true,
+        reason: hubs.includes('xiashe') ? 'non_xiashe_provider' : 'xiashe_not_selected'
+      };
 
   const warnings = [];
   const promptEvents = [];
@@ -2021,14 +2583,18 @@ async function setupAgentWorkflow(root, flags) {
     agentAckPath,
     disclosurePath,
     snippetPath: snippetResult ? snippetResult.outPath : null,
+    xiashePackageArtifact,
     promptEvents,
     warnings,
     publicProtocol,
     next: [
+      xiashePackageArtifact?.skipped
+        ? `XiaShe complete package upload was skipped (${xiashePackageArtifact.reason}).`
+        : `XiaShe complete package uploaded: ${path.relative(absoluteRoot, xiashePackageArtifact.artifactPath)} (${xiashePackageArtifact.publishStatus || 'queued'}).`,
       `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.`,
       publicProtocol
-        ? `For Red public Markdown packages, include ${path.relative(absoluteRoot, publicProtocol.agentAckPath)} and ${path.relative(absoluteRoot, publicProtocol.disclosurePath)} when accepted by the platform; keep ${WORK_DIR}/ private.`
+        ? `For Red public Markdown/YAML packages, include ${path.relative(absoluteRoot, publicProtocol.runtimePath)}, ${path.relative(absoluteRoot, publicProtocol.agentAckPath)}, and ${path.relative(absoluteRoot, publicProtocol.disclosurePath)} when accepted by the platform; keep ${WORK_DIR}/ private.`
         : `Use ${path.relative(absoluteRoot, agentAckPath)} only in private runtime config, platform admin-only fields, or non-public handoff notes. Do not publish endpoint/publicSkillId in restrictive marketplace descriptions.`,
       '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.',
@@ -2092,7 +2658,10 @@ async function main() {
           `Platform profiles: ${result.profilesPath}`,
           ...result.packagePlanPaths.map((item) => `Package plan (${item.hub}): ${item.planPath}`),
           result.skillMdPath ? `Updated: ${result.skillMdPath}` : null,
-          result.publicProtocol ? `Public Red protocol: ${result.publicProtocol.agentAckPath}, ${result.publicProtocol.disclosurePath}` : null,
+          result.publicProtocol ? `Public Red protocol: ${result.publicProtocol.runtimePath}, ${result.publicProtocol.agentAckPath}, ${result.publicProtocol.disclosurePath}` : null,
+          result.xiashePackageArtifact && !result.xiashePackageArtifact.skipped
+            ? `XiaShe package: ${result.xiashePackageArtifact.artifactPath} (${result.xiashePackageArtifact.publishStatus || 'queued'})`
+            : null,
           `Disclosure: ${result.disclosurePath}`,
           result.snippetPath ? `Runtime snippet: ${result.snippetPath}` : null,
           ...result.warnings.map((warning) => `Warning: ${warning}`),
@@ -2100,10 +2669,10 @@ async function main() {
           'Next:',
           '- Treat the target platform official upload flow as authoritative.',
           '- Use the handoff file as the only XiaShe registry checklist.',
-          '- 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.',
+          '- XiaShe complete package upload is already handled by this command when the xiashe target is selected.',
+          '- Before uploading to third-party targets, 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, run `npx -y @xiashe/cli skills publish draft . --source xiashe`; it should use the local registry public token first and create or reuse a searchable listing without creator login.',
-          '- Only ask for creator CLI login if the registry public token is missing or rejected.',
+          '- Only ask for creator CLI login if a separate store-management command is needed and the registry public token is missing or rejected.',
           '- 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);
@@ -2122,8 +2691,12 @@ async function main() {
           ...result.promptPaths.map((item) => `Wrote ${item.promptPath}`),
           `Wrote ${result.profilesPath}`,
           ...result.packagePlanPaths.map((item) => `Wrote ${item.planPath}`),
+          result.publicProtocol ? `Wrote ${result.publicProtocol.runtimePath}` : null,
           result.publicProtocol ? `Wrote ${result.publicProtocol.agentAckPath}` : null,
           result.publicProtocol ? `Wrote ${result.publicProtocol.disclosurePath}` : null,
+          result.xiashePackageArtifact && !result.xiashePackageArtifact.skipped
+            ? `Uploaded XiaShe package ${result.xiashePackageArtifact.artifactPath} (${result.xiashePackageArtifact.publishStatus || 'queued'})`
+            : null,
           `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.16",
+  "version": "0.1.18",
   "type": "module",
   "bin": {
     "xiashe-skill": "bin/xiashe-skill.mjs"