@xiashe/skill 0.1.24 → 0.1.26

package/README.md

@@ -44,7 +44,9 @@ node packages/xiashe-skill-cli/bin/xiashe-skill.mjs snippet . --target js
 node packages/xiashe-skill-cli/bin/xiashe-skill.mjs track . --event skill_invoked --hub red --dry-run --json
 ```
 
-Use the `claimUrl` returned with a dashboard dynamic code exactly as issued. `publish` runs the same preflight automatically before it consumes a code: it verifies the exact registry origin, protocol version, and environment id exposed by that deployment. A dynamic code without an explicit `--claim-url` is rejected before the code is consumed, so development, CN, and global codes cannot accidentally be sent to the production registry. For a resumed upload, the CLI uses the registry origin stored in the local private manifest and preflights it again.
+Use the `claimUrl` returned with a dashboard dynamic code exactly as issued. `publish` runs the same preflight automatically before it consumes a code: it verifies the exact registry origin, protocol version, and environment id exposed by that deployment. A dynamic code without an explicit `--claim-url` is rejected before the code is consumed, so development, CN, and global codes cannot accidentally be sent to the production registry. For an existing Skill update, use the single public `--registry-origin https://<registry-host>` option. The CLI derives its routes, compares that origin and the registry environment id with the local private manifest, and stops before writing or uploading when they differ. Do not copy individual internal endpoint overrides into an update task.
+
+When an existing project was originally linked through XiaShe, `@agentpie/skill publish` may adopt its `.xiashe/xiashe.skill.json` only for an update without a dynamic code or explicit public token. The legacy manifest must identify itself as XiaShe and contain its saved registry origin and environment. The CLI verifies both, then writes a separate `.agentpie/agentpie.skill.json`; the XiaShe manifest is retained. A missing value or mismatch stops before a manifest write or package upload, so development, CN, and global Skill identities stay isolated.
 
 ## Reliable publish and recovery
 

package/bin/xiashe-skill.mjs

@@ -68,7 +68,7 @@ function isTransportError(error) {
 }
 
 const LOCAL_ENV_DEFAULTS = loadLocalEnvDefaults();
-const VERSION = process.env.XIASHE_SKILL_CLI_VERSION || '0.1.24';
+const VERSION = process.env.XIASHE_SKILL_CLI_VERSION || '0.1.25';
 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');
@@ -97,6 +97,14 @@ const MANIFEST_FILE = process.env.XIASHE_SKILL_MANIFEST_FILE || (COMMAND_NAME ==
   ? 'agentpie.skill.json'
   : 'xiashe.skill.json');
 const WORK_DIR = process.env.XIASHE_SKILL_WORK_DIR || (COMMAND_NAME === 'agentpie-skill' ? '.agentpie' : '.xiashe');
+// A Skill that was first linked through XiaShe may later be updated through
+// AgentPie. AgentPie can adopt that local link only for an update, never for a
+// new claim. The registry origin and environment are still checked before we
+// write the AgentPie manifest or upload anything.
+const CAN_ADOPT_LEGACY_XIASHE_MANIFEST = REGISTRY_PROVIDER === 'agentpie' &&
+  process.env.XIASHE_SKILL_LEGACY_MANIFEST_COMPAT !== '0';
+const LEGACY_XIASHE_WORK_DIR = '.xiashe';
+const LEGACY_XIASHE_MANIFEST_FILE = 'xiashe.skill.json';
 const PUBLIC_PROTOCOL_DIR = process.env.XIASHE_SKILL_PUBLIC_PROTOCOL_DIR || (REGISTRY_PROVIDER === 'agentpie' ? 'agentpie' : 'xiashe');
 const PUBLIC_PACKAGE_MANIFEST_FILE = 'package-manifest.json';
 const HANDOFF_FILE = 'UPLOAD_HANDOFF.md';
@@ -305,6 +313,12 @@ 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;
+// Update tasks are frequently run from a chat workspace that contains the
+// original Skill folder one level below the current directory. Look only in a
+// small, project-local area: this is helpful without turning a publish command
+// into a machine-wide search for credentials or manifests.
+const MAX_LOCAL_LINK_DISCOVERY_DEPTH = 4;
+const MAX_LOCAL_LINK_DISCOVERY_DIRECTORIES = 160;
 const gzipAsync = promisify(gzip);
 
 function usage() {
@@ -316,7 +330,7 @@ Usage:
   ${COMMAND_NAME} setup [skill-dir] --code <dynamic-code> [--hub all|${FIRST_PARTY_HUB}|red]
   ${COMMAND_NAME} setup [skill-dir] --public-token <token> --skill-id <id> [--hub all|${FIRST_PARTY_HUB}|red]
   ${COMMAND_NAME} doctor [skill-dir] [--json]
-  ${COMMAND_NAME} preflight --claim-url <url> [--json]
+  ${COMMAND_NAME} preflight (--claim-url <url> | --registry-origin <url>) [--json]
   ${COMMAND_NAME} verify [skill-dir] [--hub <hub>] [--scenario <label>] [--dry-run]
   ${COMMAND_NAME} attach [skill-dir] --code <dynamic-code> [--name <name>]
   ${COMMAND_NAME} attach [skill-dir] --public-token <token> [--skill-id <id>] [--name <name>]
@@ -327,6 +341,7 @@ Usage:
 Options:
   --public-token <token>      Public write token issued by ${PRODUCT_NAME} registry.
   --code <dynamic-code>       One-time ${PRODUCT_NAME} dashboard code used to claim registry identity.
+  --registry-origin <url>     Existing Skill update origin. Derives all registry routes and verifies the saved environment.
   --claim-url <url>           Code claim endpoint. Defaults to XIASHE_SKILL_CLAIM_URL or ${DEFAULT_CLAIM_URL}
   --registry-doctor-url <url> Registry preflight endpoint. Defaults to the claim URL origin.
   --skill-id <id>             Public ${PRODUCT_NAME} Skill registry id.
@@ -525,6 +540,10 @@ function latestVersionEndpoint(inspectedOrRegistry = {}) {
   const skillKey = safeSkillKey(inspectedOrRegistry.skillKey || registry.skillKey || '');
   const creatorCardUrl = normalizeText(registry.creatorCardUrl || registry.creatorProfile?.cardUrl, 800);
   const publicSkillId = normalizeText(registry.skillId || registry.publicSkillId, 160);
+  // Existing Skills must keep checking the registry that originally issued
+  // their manifest. Falling back to a CLI default here would make a dev
+  // package discover Global/CN updates after a machine-level config change.
+  const registryOrigin = normalizeBaseUrl(registry.registryOrigin) || DEFAULT_BASE_URL;
   const params = new URLSearchParams();
   if (publicSkillId) {
     params.set('publicSkillId', publicSkillId);
@@ -532,7 +551,7 @@ function latestVersionEndpoint(inspectedOrRegistry = {}) {
     params.set('skillKey', skillKey);
     params.set('creatorCardUrl', creatorCardUrl);
   }
-  return `${DEFAULT_BASE_URL}/registry/skill/latest${params.toString() ? `?${params.toString()}` : ''}`;
+  return `${registryOrigin}/registry/skill/latest${params.toString() ? `?${params.toString()}` : ''}`;
 }
 
 function creatorFooterTemplate(inspected, language = 'zh') {
@@ -808,12 +827,51 @@ async function readJsonFile(filePath) {
   }
 }
 
+function localManifestPath(root) {
+  return path.join(root, WORK_DIR, MANIFEST_FILE);
+}
+
+function legacyXiaSheManifestPath(root) {
+  if (!CAN_ADOPT_LEGACY_XIASHE_MANIFEST) return null;
+  return path.join(root, LEGACY_XIASHE_WORK_DIR, LEGACY_XIASHE_MANIFEST_FILE);
+}
+
+function canAdoptLegacyXiaSheManifest(flags = {}) {
+  // A dynamic code or a supplied public token starts/resumes an explicit
+  // identity flow. Never let it silently attach to a legacy local identity.
+  return CAN_ADOPT_LEGACY_XIASHE_MANIFEST &&
+    !normalizeText(flags.code, 80) &&
+    !normalizeText(flags['public-token'], 512) &&
+    (!flags['manifest-path'] || Boolean(flags['local-manifest']));
+}
+
+async function readSkillManifest(root, flags = {}) {
+  const explicitManifestPath = normalizeText(flags['manifest-path'], 2_000);
+  const legacyManifestPath = canAdoptLegacyXiaSheManifest(flags)
+    ? legacyXiaSheManifestPath(root)
+    : null;
+  const candidates = [
+    explicitManifestPath ? path.resolve(explicitManifestPath) : path.join(root, MANIFEST_FILE),
+    localManifestPath(root),
+    legacyManifestPath
+  ].filter(Boolean);
+  const uniqueCandidates = [...new Set(candidates)];
+
+  for (const manifestPath of uniqueCandidates) {
+    const manifest = await readJsonFile(manifestPath);
+    if (!manifest) continue;
+    return {
+      manifest,
+      manifestPath,
+      source: manifestPath === legacyManifestPath ? 'legacy_xiashe' : 'current'
+    };
+  }
+  return { manifest: null, manifestPath: null, source: null };
+}
+
 async function inferSkillMetadata(root, flags = {}) {
-  const manifestPath = flags['manifest-path']
-    ? path.resolve(flags['manifest-path'])
-    : path.join(root, MANIFEST_FILE);
-  const localManifestPath = path.join(root, WORK_DIR, MANIFEST_FILE);
-  const manifest = await readJsonFile(manifestPath) || await readJsonFile(localManifestPath);
+  const manifestLookup = await readSkillManifest(root, flags);
+  const manifest = manifestLookup.manifest;
   const packageJson = await readJsonFile(path.join(root, 'package.json'));
   const skillMdPath = path.join(root, 'SKILL.md');
   const readmePath = path.join(root, 'README.md');
@@ -835,10 +893,113 @@ async function inferSkillMetadata(root, flags = {}) {
     billingModel: normalizeText(flags['billing-model'] || manifest?.billingModel || manifest?.registry?.billingModel, 80) || null,
     monetizationMode: normalizeText(flags['monetization-mode'] || manifest?.monetizationMode || manifest?.registry?.monetizationMode, 80) || null,
     accessMode: normalizeText(flags['access-mode'] || manifest?.accessMode || manifest?.registry?.accessMode, 80) || null,
+    manifestPath: manifestLookup.manifestPath,
+    manifestSource: manifestLookup.source,
     registry: manifest?.registry || null
   };
 }
 
+function hasSkillProjectMarker(root) {
+  return ['SKILL.md', 'package.json', 'README.md'].some((fileName) => existsSync(path.join(root, fileName)));
+}
+
+async function readExistingSkillLink(root, flags = {}) {
+  const manifestLookup = await readSkillManifest(root, flags);
+  const manifest = manifestLookup.manifest;
+  const registry = manifest?.registry;
+  const publicToken = normalizeText(registry?.publicToken, 512);
+  const publicSkillId = normalizeText(registry?.publicSkillId || registry?.skillId, 160);
+  if (!manifest || !registry || (!publicToken && !publicSkillId)) return null;
+  return {
+    root,
+    manifestPath: manifestLookup.manifestPath,
+    manifestSource: manifestLookup.source,
+    manifest,
+    skillKey: safeSkillKey(manifest.skillKey || registry.skillKey || manifest.name || path.basename(root))
+  };
+}
+
+async function resolveExistingSkillRoot(root, flags = {}) {
+  const requestedRoot = path.resolve(root || '.');
+  const info = await stat(requestedRoot).catch(() => null);
+  if (!info?.isDirectory()) {
+    throw new Error(`Skill directory not found: ${requestedRoot}`);
+  }
+
+  // A fresh claim or an explicit manifest path is intentional. Do not replace
+  // either with automatic discovery, which could attach the wrong Skill.
+  if (flags.code || flags['public-token'] || flags['manifest-path']) {
+    return { root: requestedRoot, discovered: false };
+  }
+
+  const directLink = await readExistingSkillLink(requestedRoot, flags);
+  if (directLink) return { root: requestedRoot, discovered: false };
+
+  const requestedRootHasMarker = hasSkillProjectMarker(requestedRoot);
+  const expectedSkillKey = normalizeText(flags['skill-key'], 120)
+    ? safeSkillKey(flags['skill-key'])
+    : requestedRootHasMarker
+      ? (await inferSkillMetadata(requestedRoot, flags)).skillKey
+      : '';
+  const candidates = [];
+  const candidateRoots = new Set();
+
+  const addCandidate = async (candidateRoot) => {
+    const canonicalRoot = path.resolve(candidateRoot);
+    if (candidateRoots.has(canonicalRoot) || !hasSkillProjectMarker(canonicalRoot)) return;
+    candidateRoots.add(canonicalRoot);
+    const candidate = await readExistingSkillLink(canonicalRoot, flags);
+    if (!candidate) return;
+    if (expectedSkillKey && candidate.skillKey !== expectedSkillKey) return;
+    candidates.push(candidate);
+  };
+
+  // Only walk upward when the requested folder identifies the Skill. Without
+  // that key, an unrelated parent workspace with one linked Skill could be
+  // selected accidentally. A generic chat workspace is handled by the bounded
+  // child search below instead.
+  if (expectedSkillKey) {
+    let ancestor = path.dirname(requestedRoot);
+    for (let index = 0; index < MAX_LOCAL_LINK_DISCOVERY_DEPTH; index += 1) {
+      if (ancestor === path.dirname(ancestor)) break;
+      await addCandidate(ancestor);
+      ancestor = path.dirname(ancestor);
+    }
+  }
+
+  // Then look through a small subtree, covering the common case where a chat
+  // task attaches the original Skill directory as a child of its workspace.
+  const queue = [{ directory: requestedRoot, depth: 0 }];
+  const visited = new Set();
+  while (queue.length > 0 && visited.size < MAX_LOCAL_LINK_DISCOVERY_DIRECTORIES) {
+    const { directory, depth } = queue.shift();
+    const canonicalDirectory = path.resolve(directory);
+    if (visited.has(canonicalDirectory)) continue;
+    visited.add(canonicalDirectory);
+    if (depth > 0) await addCandidate(canonicalDirectory);
+    if (depth >= MAX_LOCAL_LINK_DISCOVERY_DEPTH) continue;
+    const entries = await readdir(canonicalDirectory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (!entry.isDirectory() || shouldIgnore(entry.name)) continue;
+      queue.push({ directory: path.join(canonicalDirectory, entry.name), depth: depth + 1 });
+    }
+  }
+
+  if (candidates.length === 1) {
+    return { root: candidates[0].root, discovered: true };
+  }
+  if (candidates.length > 1) {
+    throw new Error(
+      'CREATOR_SKILL_MANIFEST_AMBIGUOUS: more than one matching local Skill connection was found. ' +
+      'The CLI did not update or create any Skill. Run the command from the intended Skill folder.'
+    );
+  }
+  throw new Error(
+    'CREATOR_SKILL_MANIFEST_NOT_FOUND: no matching local Skill connection was found in this project. ' +
+    'The CLI did not update or create any Skill. Run the command from the original Skill folder.'
+  );
+}
+
 function shouldIgnore(name) {
   return DEFAULT_IGNORE.has(name) ||
     name.startsWith('.env.') ||
@@ -969,6 +1130,49 @@ function claimUrlForExistingManifest(flags = {}, registry = {}) {
   );
 }
 
+function normalizeRegistryOrigin(value) {
+  const raw = normalizeText(value, 1_000);
+  if (!raw) return '';
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error('CREATOR_SKILL_REGISTRY_ORIGIN_INVALID: registry origin is not a valid URL.');
+  }
+  const host = url.hostname.toLowerCase();
+  const isLocalhost = host === 'localhost' || host === '127.0.0.1' || host === '::1' || host.endsWith('.localhost');
+  if (url.pathname !== '/' || url.search || url.hash || url.username || url.password) {
+    throw new Error('CREATOR_SKILL_REGISTRY_ORIGIN_INVALID: registry origin must not contain a path, query, fragment, or credentials.');
+  }
+  if (url.protocol !== 'https:' && !(isLocalhost && process.env.XIASHE_SKILL_ALLOW_INSECURE_LOCALHOST === '1')) {
+    throw new Error('CREATOR_SKILL_REGISTRY_ORIGIN_INSECURE: only HTTPS registry origins are accepted.');
+  }
+  return url.origin.replace(/\/+$/, '');
+}
+
+function registryOriginFromFlags(flags = {}) {
+  return normalizeRegistryOrigin(flags['registry-origin']);
+}
+
+function applyRegistryOriginFlags(flags = {}) {
+  const registryOrigin = registryOriginFromFlags(flags);
+  if (!registryOrigin) return flags;
+  if (normalizeText(flags.code, 80)) {
+    throw new Error('CREATOR_SKILL_REGISTRY_ORIGIN_WITH_CODE_FORBIDDEN: dynamic codes must use the exact dashboard --claim-url, not --registry-origin.');
+  }
+  for (const key of ['claim-url', 'registry-url', 'agent-ack-url', 'registry-doctor-url']) {
+    if (normalizeText(flags[key], 1_000)) {
+      throw new Error(`CREATOR_SKILL_REGISTRY_ORIGIN_CONFLICT: --registry-origin cannot be combined with --${key}.`);
+    }
+  }
+  return {
+    ...flags,
+    'claim-url': `${registryOrigin}/registry/skill/claim`,
+    'registry-url': `${registryOrigin}/registry/skill-events`,
+    'agent-ack-url': `${registryOrigin}/registry/agent-ack`
+  };
+}
+
 function configuredRegistryOrigins() {
   const supplied = [
     process.env.XIASHE_SKILL_TRUSTED_REGISTRY_ORIGINS,
@@ -1509,15 +1713,42 @@ async function writeManifest(root, flags) {
   const inspected = await inspectSkill(root, flags);
   const code = normalizeText(flags.code, 80);
   const existingRegistry = inspected.registry || {};
+  const savedRegistryOrigin = normalizeBaseUrl(existingRegistry.registryOrigin);
+  const savedEnvironmentId = normalizeText(existingRegistry.environmentId, 160);
+  const requestedRegistryOrigin = registryOriginFromFlags(flags);
   const suppliedPublicToken = normalizeText(flags['public-token'], 512);
+  const isLegacyXiaSheMigration = inspected.manifestSource === 'legacy_xiashe';
+  if (
+    isLegacyXiaSheMigration &&
+    (existingRegistry.provider !== 'xiashe' || !savedRegistryOrigin || !savedEnvironmentId)
+  ) {
+    throw new Error(
+      'CREATOR_SKILL_LEGACY_MANIFEST_UNVERIFIABLE: this XiaShe local connection does not contain a verifiable registry origin and environment. ' +
+      'No AgentPie manifest was written. Update from the original XiaShe connection or attach the Skill explicitly.'
+    );
+  }
   if (!code && suppliedPublicToken && !explicitClaimUrl(flags) && !claimUrlFromRegistryOrigin(existingRegistry.registryOrigin)) {
     throw new Error(
       'CREATOR_SKILL_CLAIM_URL_REQUIRED: a new manifest created from --public-token must include --claim-url. ' +
       'Existing manifests resume through their saved registry origin.'
     );
   }
+  if (!code && !savedRegistryOrigin && !requestedRegistryOrigin) {
+    throw new Error(
+      'CREATOR_SKILL_REGISTRY_ORIGIN_REQUIRED: existing Skill updates must include --registry-origin so the CLI can verify the original environment before writing or uploading.'
+    );
+  }
+  if (!code && savedRegistryOrigin && requestedRegistryOrigin && savedRegistryOrigin !== requestedRegistryOrigin) {
+    throw new Error('CREATOR_SKILL_REGISTRY_ENVIRONMENT_MISMATCH: the supplied registry origin differs from the original Skill manifest. No files were changed.');
+  }
   const claimUrl = code ? claimUrlForCode(flags) : claimUrlForExistingManifest(flags, existingRegistry);
-  const registryPreflight = code ? await preflightRegistryClaim(claimUrl, flags) : null;
+  const registryPreflight = await preflightRegistryClaim(claimUrl, flags);
+  if (!code && savedRegistryOrigin && savedRegistryOrigin !== registryPreflight.registryOrigin) {
+    throw new Error('CREATOR_SKILL_REGISTRY_ENVIRONMENT_MISMATCH: the saved Skill manifest belongs to a different registry origin. No files were changed.');
+  }
+  if (!code && savedEnvironmentId && savedEnvironmentId !== registryPreflight.environmentId) {
+    throw new Error('CREATOR_SKILL_REGISTRY_ENVIRONMENT_MISMATCH: the saved Skill manifest belongs to a different registry environment. No files were changed.');
+  }
   const claim = code
     ? await postJson(
         registryPreflight.claimUrl,
@@ -1583,9 +1814,9 @@ async function writeManifest(root, flags) {
     accessMode: normalizeText(flags['access-mode'] || inspected.accessMode || existingRegistry.accessMode, 80) || null,
     registry: {
       provider: REGISTRY_PROVIDER,
-      protocolVersion: normalizeText(claim?.registry?.protocolVersion || registryPreflight?.protocolVersion, 120) || null,
-      environmentId: normalizeText(claim?.registry?.environmentId || registryPreflight?.environmentId, 160) || null,
-      registryOrigin: normalizeBaseUrl(claim?.registry?.registryOrigin || registryPreflight?.registryOrigin) || null,
+      protocolVersion: normalizeText(claim?.registry?.protocolVersion || registryPreflight?.protocolVersion || existingRegistry.protocolVersion, 120) || null,
+      environmentId: normalizeText(claim?.registry?.environmentId || registryPreflight?.environmentId || existingRegistry.environmentId, 160) || null,
+      registryOrigin: normalizeBaseUrl(claim?.registry?.registryOrigin || registryPreflight?.registryOrigin || existingRegistry.registryOrigin) || null,
       skillId: normalizeText(flags['skill-id'] || claim?.skillId || existingRegistry.skillId, 160) || null,
       publicToken,
       isPaid: Boolean(flags['paid-skill'] || flags['protected-skill'] || inspected.isPaid || existingRegistry.isPaid || existingRegistry.paidAccess),
@@ -1593,8 +1824,8 @@ async function writeManifest(root, flags) {
       billingModel: normalizeText(flags['billing-model'] || inspected.billingModel || existingRegistry.billingModel, 80) || null,
       monetizationMode: normalizeText(flags['monetization-mode'] || inspected.monetizationMode || existingRegistry.monetizationMode, 80) || null,
       accessMode: normalizeText(flags['access-mode'] || inspected.accessMode || existingRegistry.accessMode, 80) || null,
-      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,
+      registryUrl: normalizeText(flags['registry-url'] || claim?.registryUrl || existingRegistry.registryUrl, 800) || `${registryPreflight.registryOrigin}/registry/skill-events`,
+      agentAckUrl: normalizeText(flags['agent-ack-url'] || existingRegistry.agentAckUrl, 800) || `${registryPreflight.registryOrigin}/registry/agent-ack`,
       creatorCardUrl,
       creatorProfile,
       eventSchemaVersion: EVENT_SCHEMA_VERSION,
@@ -1642,7 +1873,7 @@ async function writeManifest(root, flags) {
             sourceSurface: hub,
             skillKey: safeSkillKey(claim?.skillKey || inspected.skillKey),
             publicSkillId: normalizeText(flags['skill-id'] || claim?.skillId || existingRegistry.skillId, 160) || null,
-            agentAckUrl: normalizeText(flags['agent-ack-url'] || existingRegistry.agentAckUrl, 800) || DEFAULT_AGENT_ACK_URL,
+            agentAckUrl: normalizeText(flags['agent-ack-url'] || existingRegistry.agentAckUrl, 800) || `${registryPreflight.registryOrigin}/registry/agent-ack`,
             creatorCardUrl,
             creatorProfile
           }
@@ -1667,6 +1898,7 @@ async function writeManifest(root, flags) {
     ok: true,
     manifestPath,
     manifest,
+    adoptedLegacyXiaSheManifest: inspected.manifestSource === 'legacy_xiashe',
     claimPackageArtifactUpload: claim?.packageArtifactUpload ?? null,
     registryPreflight
   };
@@ -1948,6 +2180,10 @@ function redPublicTrackingContractBlock(inspected) {
     `- Latest version endpoint: ${updateEndpoint}`,
     '- 如果联网可用，首次使用前或每日第一次使用前检查一次。',
     '- 如果 latestVersion 与 Current version 不同，先提示用户有新版本，并询问是否更新；未经确认，不要修改本地文件。',
+    ...(protectedPaidSkill ? [
+      `- 对这个受保护包，公开 latest version endpoint 只能用于发现更新，不能用于下载。先通过 ${PRODUCT_NAME} Gateway 调用 \`xiashe.check_skill_update\`；用户明确同意后，调用 \`xiashe.get_skill_update\` 并传 \`userConfirmed=true\`。`,
+      '- 更新交付到当前 Agent 的一次性私有地址：先保留旧包备份，在临时目录下载、校验 SHA-256、解压并阅读 SKILL.md，全部成功后再原子替换；任一步失败都保留旧包。已购账户更新不再次收费。'
+    ] : []),
     '- 如果 endpoint 返回 blocked / paused / disabled，提示当前版本已停用，不要静默继续。',
     '- 如果无法联网，继续完成用户任务，并简单说明更新状态未检查。',
     '',
@@ -2000,6 +2236,10 @@ function skillMdRegistryBlock(inspected, hub) {
     `- Latest version endpoint: ${updateEndpoint}`,
     '- When network access is available, check the latest version endpoint before first use or once per day.',
     '- If a newer latestVersion is returned, show it and ask the user before changing local files.',
+    ...(protectedPaidSkill ? [
+      `- For this protected package, the public latest-version endpoint is discovery-only and must not be used as a download URL. Call ${PRODUCT_NAME} Gateway \`xiashe.check_skill_update\`, then after explicit approval call \`xiashe.get_skill_update\` with \`userConfirmed=true\`.`,
+      '- Keep the installed package as backup; download the one-time private delivery into a temporary directory, verify SHA-256, unpack and read SKILL.md, then atomically replace. Keep the old package on any failure. An entitled account is not charged again for updates.'
+    ] : []),
     '- If the endpoint returns blocked / paused / disabled, tell the user this installed version is disabled and do not continue silently.',
     '- If the network is unavailable, continue the user task and briefly state that update status was not checked.',
     '',
@@ -2100,6 +2340,7 @@ function buildRuntimeYaml(inspected, hub = 'red') {
     "  when: 'before_first_use_or_daily_when_network_available'",
     "  noNetwork: 'continue_and_state_update_status_unchecked'",
     "  updateAvailable: 'show_latest_version_and_ask_user_before_changing_files'",
+    `  protectedDelivery: ${yamlString(protectedPaidSkill ? 'gateway_check_then_confirmed_one_time_delivery; backup_verify_extract_read_skill_md_then_atomic_replace; no_second_charge_for_entitled_account' : 'not_required')}`,
     "  blocked: 'tell_user_current_version_is_disabled_and_do_not_continue_silently'",
     'creator:',
     `  displayName: ${yamlString(creatorName)}`,
@@ -2212,6 +2453,7 @@ async function writePublicProtocolFiles(root, inspected, hub = 'red') {
   const disclosurePath = path.join(protocolDir, 'REGISTRY_DISCLOSURE.md');
   const runtimePath = path.join(protocolDir, 'runtime.yaml');
   const registry = inspected.registry || {};
+  const protectedPaidSkill = isProtectedPaidSkill(inspected);
   const publicSkillId = registry.skillId || registry.publicSkillId || `<public skill id from ${PRODUCT_NAME} registry>`;
   const agentAck = [
     agentAckInstructionBlock(inspected, hub),
@@ -2220,7 +2462,9 @@ async function writePublicProtocolFiles(root, inspected, hub = 'red') {
     '',
     '1. Install the Skill through the target platform official flow.',
     `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. When network is available, check `runtime.yaml` `updateCheck.latestVersionEndpoint` before first use or once per day. If a newer version exists, ask the user whether to update before modifying local files.',
+    protectedPaidSkill
+      ? `3. When network is available, check \`runtime.yaml\` \`updateCheck.latestVersionEndpoint\` before first use or once per day. If a newer version exists, use ${PRODUCT_NAME} Gateway \`xiashe.check_skill_update\`, ask the user, then call \`xiashe.get_skill_update\` with \`userConfirmed=true\`. Preserve the old local package until the new private archive is verified, unpacked, and its SKILL.md read.`
+      : '3. When network is available, check `runtime.yaml` `updateCheck.latestVersionEndpoint` before first use or once per day. If a newer version exists, ask the user whether to update before modifying local files.',
     '4. Send `installed` once after installation succeeds. If first use happens before the install event, backfill `installed` first with the same anonymous `installationId`.',
     '5. Send `used` when the Skill starts, then `completed` or `failed` when the task ends.',
     '6. End every completed Skill turn with the localized footer from `runtime.yaml`. Use the recommendation slot only when the Ack response returns one.',
@@ -2602,7 +2846,9 @@ async function writeUnifiedHandoff(root, args) {
     `Event schema: ${registry.eventSchemaVersion || EVENT_SCHEMA_VERSION}`,
     '',
     `The simplest cross-platform runtime path is Agent Ack. For Red Skill, the host Agent should read ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md or private runtime config first, then report \`installed\`, \`used\`, \`completed\`, or \`failed\` with publicSkillId, anonymous installationId, and invocationId. Do not paste endpoint/publicSkillId into marketing descriptions, screenshots, or user-visible replies. No public token or account login is required for Agent Ack.`,
-    `For user-side updates, the simplest path is prompt-based: read ${PUBLIC_PROTOCOL_DIR}/runtime.yaml \`updateCheck.latestVersionEndpoint\` or the SKILL.md latest version endpoint before first use/daily use; if a newer version exists, show it and ask the user before changing local files. If blocked, do not continue silently.`,
+    protectedPaidSkill
+      ? `For user-side protected updates, use ${PUBLIC_PROTOCOL_DIR}/runtime.yaml \`updateCheck.latestVersionEndpoint\` only to discover the latest version. The Agent must call ${PRODUCT_NAME} Gateway \`xiashe.check_skill_update\`, show the version and get explicit user approval, then call \`xiashe.get_skill_update\` with \`userConfirmed=true\`. Its one-time archive must be verified, unpacked, and read before atomically replacing the local package; keep the old package on failure. Do not use a public registry link as a package download or charge an entitled account again.`
+      : `For user-side updates, the simplest path is prompt-based: read ${PUBLIC_PROTOCOL_DIR}/runtime.yaml \`updateCheck.latestVersionEndpoint\` or the SKILL.md latest version endpoint before first use/daily use; if a newer version exists, show it and ask the user before changing local files. If blocked, do not continue silently.`,
     'The creator card link is public attribution and should remain visible in allowed platform instructions and user-facing Skill replies. It is not a secret and should not be replaced by registry ids or tokens.',
     `Before sending Agent Ack, read ${PUBLIC_PROTOCOL_DIR}/AGENT_ACK.md, ${WORK_DIR}/AGENT_ACK.md, or the private registry manifest and use the exact \`publicSkillId\`. Never guess it from the Skill title, package name, directory name, or marketplace slug.`,
     'For `installationId`, use a stable anonymous value for this installed copy/runtime connection. If the platform does not provide one, hash `publicSkillId + platform name + install directory or session id`, store only the opaque hash locally, and never send raw paths, emails, phone numbers, real names, prompts, or account identifiers.',
@@ -2895,12 +3141,11 @@ function doctorCheck(id, label, status, message, fix = '') {
 
 async function runDoctor(root, flags) {
   const inspected = await inspectSkill(root, flags);
+  const manifestLookup = await readSkillManifest(inspected.root, flags);
   const hub = normalizeHub(flags.hub || flags.to || 'generic') || 'generic';
   const redHub = hub === 'red';
   const skillMdPath = path.join(inspected.root, 'SKILL.md');
   const readmePath = await findReadmePath(inspected.root);
-  const manifestPath = path.join(inspected.root, MANIFEST_FILE);
-  const localManifestPath = path.join(inspected.root, WORK_DIR, MANIFEST_FILE);
   const disclosurePath = path.join(inspected.root, WORK_DIR, 'REGISTRY_DISCLOSURE.md');
   const publicAgentAckPath = path.join(inspected.root, PUBLIC_PROTOCOL_DIR, 'AGENT_ACK.md');
   const publicDisclosurePath = path.join(inspected.root, PUBLIC_PROTOCOL_DIR, 'REGISTRY_DISCLOSURE.md');
@@ -2926,9 +3171,7 @@ async function runDoctor(root, flags) {
       scannedCallbackText += `\n${text}`;
     }
   }
-  const manifest = inspected.registry
-    ? await readJsonFile(manifestPath).catch(() => null) || await readJsonFile(localManifestPath).catch(() => null)
-    : null;
+  const manifest = inspected.registry ? manifestLookup.manifest : null;
   const textBundle = `${skillMd}\n${readme}`;
   const hasManifest = Boolean(manifest);
   const registry = manifest?.registry || inspected.registry || {};
@@ -2949,7 +3192,15 @@ async function runDoctor(root, flags) {
       ? doctorCheck('registry_manifest', 'Registry manifest', 'pass', `Found registry manifest for ${registry.provider || REGISTRY_PROVIDER}.`)
       : redHub
         ? doctorCheck('registry_manifest', 'Registry manifest', 'warn', `No local registry manifest found. This does not block Red Skill safety review, but ${PRODUCT_NAME} Agent Ack reporting will be unavailable until setup runs.`, `Run ${COMMAND_NAME} setup . --code <dashboard-code> --hub red if ${PRODUCT_NAME} tracking 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>.`),
+        : doctorCheck(
+            'registry_manifest',
+            'Registry manifest',
+            'fail',
+            CAN_ADOPT_LEGACY_XIASHE_MANIFEST
+              ? `Missing usable registry manifest (${MANIFEST_FILE}, ${WORK_DIR}/${MANIFEST_FILE}, or a compatible XiaShe local manifest).`
+              : `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.')
       : redHub
@@ -3138,7 +3389,8 @@ function formatVerify(result) {
 
 async function setupAgentWorkflow(root, flags) {
   const hubs = setupHubsFromFlags(flags);
-  const absoluteRoot = path.resolve(root || '.');
+  const rootResolution = await resolveExistingSkillRoot(root, flags);
+  const absoluteRoot = rootResolution.root;
   const outDir = path.resolve(flags['out-dir'] || path.join(absoluteRoot, WORK_DIR));
   await mkdir(outDir, { recursive: true });
   const manifestResult = await writeManifest(absoluteRoot, {
@@ -3236,6 +3488,8 @@ async function setupAgentWorkflow(root, flags) {
   return {
     ok: true,
     hubs,
+    linkedSkillDiscovered: rootResolution.discovered,
+    adoptedLegacyXiaSheManifest: manifestResult.adoptedLegacyXiaSheManifest,
     manifestPath: manifestResult.manifestPath,
     handoffPath,
     promptPaths: promptResults,
@@ -3250,6 +3504,12 @@ async function setupAgentWorkflow(root, flags) {
     warnings,
     publicProtocol,
     next: [
+      rootResolution.discovered
+        ? 'An existing local Skill connection was found automatically; no new registry entry was created.'
+        : null,
+      manifestResult.adoptedLegacyXiaSheManifest
+        ? 'A compatible XiaShe local connection was reused after the registry origin and environment check; a separate AgentPie manifest was created.'
+        : null,
       firstPartyPackageArtifact?.skipped
         ? `${PRODUCT_NAME} complete package upload was skipped (${firstPartyPackageArtifact.reason}).`
         : `${PRODUCT_NAME} complete package uploaded: ${path.relative(absoluteRoot, firstPartyPackageArtifact.artifactPath)} (${firstPartyPackageArtifact.publishStatus || 'queued'}).`,
@@ -3287,8 +3547,9 @@ async function main() {
   if (commandArgs[0] && !commandArgs[0].startsWith('--')) {
     root = commandArgs.shift();
   }
-  const flags = parseArgs(commandArgs);
+  let flags = parseArgs(commandArgs);
   try {
+    flags = applyRegistryOriginFlags(flags);
     if (command === 'inspect') {
       const result = await inspectSkill(root, flags);
       print(result, flags.json);

package/package.json

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