@alipay/alipay-aipay 1.7.0 → 1.7.2

package/skill-pre/references/normal/scripts/runtime.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { applyTelemetrySession, currentRunContext, startTelemetryRun } from './telemetry.mjs';
+import { applyAgentPlatform } from './agent_platform.mjs';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const referencesDir = path.resolve(scriptDir, '../..');
+const flowDirs = Object.freeze({
+  integration: path.join(referencesDir, 'integration'),
+  onboarding: path.join(referencesDir, 'onboarding')
+});
+
+const shellEntrypoints = Object.freeze({
+  sandbox: ['integration', 'sandbox_config.sh'],
+  mcc: ['onboarding', 'mcc.sh'],
+  auth: ['onboarding', 'auth.sh'],
+  screenshots: ['onboarding', 'upload_screenshots.sh'],
+  'special-license': ['onboarding', 'upload_special_license.sh'],
+  sign: ['onboarding', 'ar_sign_apply.sh'],
+  service: ['onboarding', 'service.sh'],
+  app: ['onboarding', 'app.sh']
+});
+
+const nodeEntrypoints = Object.freeze({
+  preview: ['preview_runtime.mjs', 'runPreviewCli'],
+  'key-tool': ['preview_runtime.mjs', 'runManualKeyToolCli'],
+  telemetry: ['telemetry.mjs', 'runTelemetryCli'],
+  flow: ['flow_loader.mjs', 'runFlowCli'],
+  'onboarding-message': ['onboarding_message_runner.mjs', 'runOnboardingMessageCli'],
+  'integration-message': ['integration_message_runner.mjs', 'runIntegrationMessageCli'],
+  render: ['render_customer_message.mjs', 'runRenderCustomerMessageCli'],
+  reply: ['interaction_reply.mjs', 'runInteractionReplyCli'],
+  'integration-context': ['integration_context_runner.mjs', 'runIntegrationContextCli'],
+  'onboarding-discovery': ['onboarding_discovery_runner.mjs', 'runOnboardingDiscoveryCli'],
+  'onboarding-recovery': ['onboarding_recovery_runner.mjs', 'runOnboardingRecoveryCli']
+});
+
+export const runtimeDomains = Object.freeze([
+  'self-update',
+  'integration-bootstrap',
+  'onboarding-bootstrap',
+  'onboarding-execute-ready',
+  ...Object.keys(nodeEntrypoints),
+  'env',
+  ...Object.keys(shellEntrypoints),
+  'a2m'
+]);
+
+function cliArgv(args) {
+  return [process.execPath, fileURLToPath(import.meta.url), ...args];
+}
+
+function runShell(script, cwd, args) {
+  const result = spawnSync('bash', [script, ...args], {
+    cwd,
+    env: process.env,
+    stdio: 'inherit',
+    shell: false
+  });
+  if (result.error) throw result.error;
+  process.exitCode = Number.isInteger(result.status) ? result.status : 1;
+}
+
+function shellPath(domain) {
+  const [flow, basename] = shellEntrypoints[domain];
+  const cwd = flowDirs[flow];
+  return [path.join(cwd, 'modules/scripts', basename), cwd];
+}
+
+function runtimeError(domain, error) {
+  const message = String(error?.message || error).replace(/[\r\n]/gu, ' ');
+  if (domain === 'self-update') return process.stderr.write('SELF_UPDATE:CHECK_FAILED\n');
+  if (domain === 'render') {
+    process.stderr.write('当前步骤的标准消息无法安全生成，已停止后续动作。请按 MESSAGE_RENDER_ERROR 的具体原因修正输入；若消息目录或脚本缺失，再检查 Skill 文件完整性。\n');
+    process.stderr.write(`MESSAGE_RENDER_ERROR:${message}\n`);
+    return;
+  }
+  const prefixes = {
+    flow: 'FLOW_LOADER_ERROR:',
+    'onboarding-message': 'ONBOARDING_MESSAGE_ERROR:',
+    'integration-message': 'INTEGRATION_MESSAGE_ERROR:',
+    reply: 'ALIPAY_AIPAY_INTERNAL:REPLY_VALIDATION_ERROR=',
+    'integration-context': 'ALIPAY_AIPAY_INTERNAL:INTEGRATION_CONTEXT_ERROR=',
+    'onboarding-discovery': 'ALIPAY_AIPAY_INTERNAL:DISCOVERY_RUNNER_ERROR=',
+    'onboarding-recovery': 'ALIPAY_AIPAY_INTERNAL:RECOVERY_RUNNER_ERROR=',
+    a2m: 'PYTHON_RUNNER_ERROR:'
+  };
+  process.stderr.write(`${prefixes[domain] || 'ALIPAY_AIPAY_INTERNAL:RUNTIME_ERROR='}${message}\n`);
+}
+
+function parseRuntimeArgs(args) {
+  const parsed = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith('--')) throw new Error(`未知参数 ${token}`);
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--')) throw new Error(`参数 ${token} 缺少取值`);
+    const name = token.slice(2);
+    if (Object.prototype.hasOwnProperty.call(parsed, name)) throw new Error(`参数 ${token} 重复`);
+    parsed[name] = value;
+    index += 1;
+  }
+  return parsed;
+}
+
+function requiredOption(options, name) {
+  const value = options[name];
+  if (typeof value !== 'string' || value.length === 0) throw new Error(`缺少参数 --${name}`);
+  return value;
+}
+
+function assertOnlyOptions(options, allowedNames) {
+  const allowed = new Set(allowedNames);
+  const unknown = Object.keys(options).filter((name) => !allowed.has(name));
+  if (unknown.length > 0) throw new Error(`未知参数 --${unknown[0]}`);
+}
+
+function assertEnumOption(options, name, allowedValues, { required = true } = {}) {
+  if (!Object.prototype.hasOwnProperty.call(options, name)) {
+    if (required) throw new Error(`缺少参数 --${name}`);
+    return '';
+  }
+  const value = requiredOption(options, name);
+  if (!allowedValues.includes(value)) {
+    throw new Error(`参数 --${name} 非法，仅支持 ${allowedValues.join('、')}`);
+  }
+  return value;
+}
+
+function applyTelemetryContext(domain, args) {
+  if (domain === 'telemetry') return args;
+  const remaining = [];
+  const values = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token !== '--telemetry-run-id' && token !== '--telemetry-history-count') {
+      remaining.push(token);
+      continue;
+    }
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--')) throw new Error(`参数 ${token} 缺少取值`);
+    if (Object.prototype.hasOwnProperty.call(values, token)) throw new Error(`参数 ${token} 重复`);
+    values[token] = value;
+    index += 1;
+  }
+  if (values['--telemetry-run-id'] !== undefined) {
+    process.env.ALIPAY_AIPAY_TELEMETRY_RUN_ID = values['--telemetry-run-id'];
+  } else {
+    const activeRun = currentRunContext(process.env);
+    if (activeRun && !activeRun.terminal) process.env.ALIPAY_AIPAY_TELEMETRY_RUN_ID = activeRun.run_id;
+  }
+  if (values['--telemetry-history-count'] !== undefined) {
+    const historyCount = values['--telemetry-history-count'];
+    if (historyCount !== 'null' && !/^(?:0|[1-9]\d*)$/u.test(historyCount)) {
+      throw new Error('--telemetry-history-count 只支持非负整数或 null');
+    }
+    process.env.ALIPAY_AIPAY_TELEMETRY_HISTORY_COUNT = historyCount;
+  } else if (!process.env.ALIPAY_AIPAY_TELEMETRY_HISTORY_COUNT) {
+    process.env.ALIPAY_AIPAY_TELEMETRY_HISTORY_COUNT = 'null';
+  }
+  return remaining;
+}
+
+async function runIntegrationBootstrap(args) {
+  const options = parseRuntimeArgs(args);
+  assertOnlyOptions(options, ['root-intent', 'product-type']);
+  const rootIntent = assertEnumOption(options, 'root-intent', ['integration_only']);
+  const productType = assertEnumOption(options, 'product-type', ['aipay', 'webpay', 'apppay'], { required: false });
+  process.env.ALIPAY_AIPAY_ROOT_INTENT = rootIntent;
+  await startTelemetryRun(rootIntent, productType);
+  const { runFlowCli } = await import('./flow_loader.mjs');
+  runFlowCli(cliArgv(['integration', 'entry']));
+}
+
+async function runOnboardingBootstrap(args) {
+  const options = parseRuntimeArgs(args);
+  assertOnlyOptions(options, ['root-intent', 'product-type']);
+  const rootIntent = assertEnumOption(options, 'root-intent', ['onboarding_only']);
+  const productType = assertEnumOption(options, 'product-type', ['aipay', 'webpay', 'apppay'], { required: false });
+  process.env.ALIPAY_AIPAY_ROOT_INTENT = rootIntent;
+  await startTelemetryRun(rootIntent, productType);
+  const { runOnboardingMessageCli } = await import('./onboarding_message_runner.mjs');
+  const platformEntryArgs = ['platform-entry'];
+  await runOnboardingMessageCli(cliArgv(platformEntryArgs));
+  const { isWindowsPlatform } = await import('./platform_compat.mjs');
+  if (isWindowsPlatform()) return;
+  const { runFlowCli } = await import('./flow_loader.mjs');
+  runFlowCli(cliArgv(['onboarding', 'entry']));
+}
+
+async function runOnboardingExecuteReady(args) {
+  const options = parseRuntimeArgs(args);
+  assertOnlyOptions(options, ['product-type']);
+  const productType = assertEnumOption(options, 'product-type', ['aipay', 'webpay', 'apppay']);
+  const { runFlowCli } = await import('./flow_loader.mjs');
+  runFlowCli(cliArgv(['onboarding', 'execute', '--product-type', productType]));
+  return dispatch('env', ['check', '--product-type', productType]);
+}
+
+async function dispatch(domain, args) {
+  if (domain === 'integration-bootstrap') return runIntegrationBootstrap(args);
+  if (domain === 'onboarding-bootstrap') return runOnboardingBootstrap(args);
+  if (domain === 'onboarding-execute-ready') return runOnboardingExecuteReady(args);
+  if (domain === 'auth') {
+    const [script, cwd] = shellPath(domain);
+    const { runAuthRuntime } = await import('./auth_runtime_runner.mjs');
+    process.exitCode = runAuthRuntime(script, cwd, args);
+    return;
+  }
+  if (shellEntrypoints[domain]) {
+    const [script, cwd] = shellPath(domain);
+    return runShell(script, cwd, args);
+  }
+  if (nodeEntrypoints[domain]) {
+    const [moduleName, exportName] = nodeEntrypoints[domain];
+    const result = await (await import(`./${moduleName}`))[exportName](cliArgv(args));
+    if (domain === 'telemetry') process.exitCode = result;
+    return;
+  }
+  if (domain === 'env') {
+    if (args[0] === 'refresh-alipay-cli') {
+      if (args.length !== 1) throw new Error('用法: runtime.mjs env refresh-alipay-cli');
+      const { runAlipayCliRefreshCli } = await import('./alipay_cli_refresh.mjs');
+      return runAlipayCliRefreshCli(cliArgv(['refresh-alipay-cli']));
+    }
+    if (args[0] === 'prepare-jq') {
+      if (args.length !== 1) throw new Error('用法: runtime.mjs env prepare-jq');
+      const { runManagedJqCli } = await import('./managed_jq.mjs');
+      process.exitCode = await runManagedJqCli(cliArgv(['prepare']));
+      return;
+    }
+    const { isWindowsPlatform } = await import('./platform_compat.mjs');
+    if (!isWindowsPlatform()) {
+      return runShell(path.join(scriptDir, 'alipay_cli_env.sh'), path.dirname(scriptDir), args);
+    }
+    const { runAlipayCliEnvCli } = await import('./alipay_cli_env.mjs');
+    return runAlipayCliEnvCli(cliArgv(args));
+  }
+  if (domain === 'self-update') {
+    const { runSelfUpdateCli } = await import('./self_update.mjs');
+    const outcome = await runSelfUpdateCli(cliArgv(args));
+    const version = outcome.version ? `=${outcome.version.raw}` : '';
+    process.stderr.write(`SELF_UPDATE:${outcome.kind}${version}\n`);
+    return;
+  }
+  if (domain === 'a2m') {
+    const { runPythonScriptCli } = await import('./python_script_runner.mjs');
+    const script = path.join(flowDirs.integration, 'modules/scripts/local_402_sandbox_pay.py');
+    return runPythonScriptCli(cliArgv([script, ...args]));
+  }
+  throw new Error(`用法: runtime.mjs <${runtimeDomains.join('|')}> ...`);
+}
+
+export async function runRuntimeCli(argv = process.argv) {
+  const domain = argv[2] || '';
+  try {
+    await dispatch(domain, applyTelemetryContext(domain, applyTelemetrySession(applyAgentPlatform(argv.slice(3)))));
+  } catch (error) {
+    runtimeError(domain, error);
+    process.exitCode = domain === 'self-update' ? 0 : 1;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runRuntimeCli();
+}

package/skill-pre/references/normal/scripts/self_update.mjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const defaultSkillDir = path.resolve(scriptDir, '../../..');
+const npmQueryTimeoutMs = 5 * 1000;
+const installTimeoutMs = 60 * 1000;
+const outputLimitBytes = 64 * 1024;
+const selfUpdateTargetEnv = 'ALIPAY_AIPAY_SELF_UPDATE_TARGET';
+const selfUpdateTransactionEnv = 'ALIPAY_AIPAY_SELF_UPDATE_TRANSACTION';
+
+function installTimeoutBudget() {
+  if (process.env.ALIPAY_AIPAY_TEST_MODE !== '1') return installTimeoutMs;
+  const value = Number(process.env.ALIPAY_AIPAY_SELF_UPDATE_TEST_INSTALL_TIMEOUT_MS);
+  return Number.isInteger(value) && value >= 50 && value <= installTimeoutMs ? value : installTimeoutMs;
+}
+
+function appendBounded(current, chunk) {
+  const combined = current + chunk.toString('utf8');
+  return combined.length > outputLimitBytes ? combined.slice(-outputLimitBytes) : combined;
+}
+
+async function terminateProcessTree(child) {
+  if (!child.pid) return;
+  if (process.platform === 'win32') {
+    spawnSync('taskkill.exe', ['/pid', String(child.pid), '/t', '/f'], {
+      stdio: 'ignore',
+      timeout: 2 * 1000,
+      windowsHide: true,
+    });
+    try { child.kill('SIGKILL'); } catch {}
+    return;
+  }
+
+  try { process.kill(-child.pid, 'SIGTERM'); } catch {}
+  await delay(250);
+  try { process.kill(-child.pid, 'SIGKILL'); } catch {}
+}
+
+function packageManagerCommand(command, args) {
+  if (process.platform !== 'win32') return { command, args, detached: true };
+
+  const allowedCommands = new Set(['npm', 'npx']);
+  const safeToken = /^[A-Za-z0-9@./=+_-]+$/u;
+  if (!allowedCommands.has(command) || args.some((arg) => !safeToken.test(arg))) {
+    throw new Error('unsafe Windows package-manager command');
+  }
+  return {
+    command: process.env.ComSpec || 'cmd.exe',
+    args: ['/d', '/s', '/c', [`${command}.cmd`, ...args].join(' ')],
+    detached: false,
+  };
+}
+
+function spawnPackageManager(command, args, { timeout, env = process.env }) {
+  return new Promise((resolve) => {
+    let invocation;
+    try {
+      invocation = packageManagerCommand(command, args);
+    } catch (error) {
+      resolve({ status: null, signal: null, stdout: '', stderr: '', error });
+      return;
+    }
+
+    let child;
+    try {
+      child = spawn(invocation.command, invocation.args, {
+        detached: invocation.detached,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+    } catch (error) {
+      resolve({ status: null, signal: null, stdout: '', stderr: '', error });
+      return;
+    }
+
+    let stdout = '';
+    let stderr = '';
+    let finished = false;
+    let timedOut = false;
+    let closed = false;
+    let timer;
+    let closeResolve;
+    const closedPromise = new Promise((done) => { closeResolve = done; });
+
+    child.stdout?.on('data', (chunk) => { stdout = appendBounded(stdout, chunk); });
+    child.stderr?.on('data', (chunk) => { stderr = appendBounded(stderr, chunk); });
+
+    const finish = (result) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      resolve({ ...result, stdout, stderr });
+    };
+
+    child.once('error', (error) => {
+      if (!timedOut) finish({ status: null, signal: null, error });
+    });
+    child.once('close', (status, signal) => {
+      closed = true;
+      closeResolve();
+      if (!timedOut) finish({ status, signal, error: null });
+    });
+
+    timer = setTimeout(() => {
+      timedOut = true;
+      void (async () => {
+        await terminateProcessTree(child);
+        if (!closed) await Promise.race([closedPromise, delay(2 * 1000)]);
+        const error = new Error(`package manager timed out after ${timeout}ms`);
+        error.code = 'ETIMEDOUT';
+        finish({ status: null, signal: 'SIGKILL', error });
+      })();
+    }, timeout);
+  });
+}
+
+function isRegularFile(file) {
+  try {
+    const stat = fs.lstatSync(file);
+    return stat.isFile() && !stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function isRecoverableSkillRoot(skillDir) {
+  try {
+    const root = fs.lstatSync(skillDir);
+    return root.isDirectory()
+      && !root.isSymbolicLink()
+      && isRegularFile(path.join(skillDir, 'SKILL.md'))
+      && isRegularFile(path.join(skillDir, 'references', 'normal', 'scripts', 'self_update.mjs'));
+  } catch {
+    return false;
+  }
+}
+
+function parseArgs(argv) {
+  if (argv[2] !== 'check') throw new Error('用法: self_update.mjs check [--skill-dir <absolutePath>]');
+  let skillDir = defaultSkillDir;
+  for (let index = 3; index < argv.length; index += 1) {
+    if (argv[index] === '--skill-dir' && argv[index + 1]) {
+      skillDir = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    throw new Error(`未知参数 ${argv[index]}`);
+  }
+  if (!path.isAbsolute(skillDir)) throw new Error('--skill-dir 必须是绝对路径');
+  const resolved = fs.realpathSync(skillDir);
+  const currentRoot = fs.realpathSync(defaultSkillDir);
+  if (resolved !== currentRoot || !isRecoverableSkillRoot(resolved)) {
+    throw new Error('--skill-dir 必须绑定当前运行中的 Skill 根目录');
+  }
+  return resolved;
+}
+
+function parseVersion(value) {
+  const raw = value.trim().replace(/^v/u, '');
+  const match = raw.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u);
+  if (!match || raw.length > 256) return null;
+  const prerelease = match[4]?.split('.') || [];
+  const build = raw.includes('+') ? raw.split('+')[1].split('.') : [];
+  if (![match[1], match[2], match[3]].every((value) => Number.isSafeInteger(Number(value)))) return null;
+  if (prerelease.some((value) => !value || (/^\d+$/u.test(value) && value.length > 1 && value[0] === '0'))) return null;
+  if (build.some((value) => !value)) return null;
+  return { raw, major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), prerelease };
+}
+
+function compareIdentifiers(left, right) {
+  const leftNumeric = /^\d+$/u.test(left);
+  const rightNumeric = /^\d+$/u.test(right);
+  if (leftNumeric && rightNumeric) return Number(left) - Number(right);
+  if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+  return left.localeCompare(right);
+}
+
+function compareVersions(left, right) {
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] - right[key];
+  }
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    return left.prerelease.length === right.prerelease.length ? 0 : left.prerelease.length === 0 ? 1 : -1;
+  }
+  for (let index = 0; index < Math.max(left.prerelease.length, right.prerelease.length); index += 1) {
+    if (left.prerelease[index] === undefined) return -1;
+    if (right.prerelease[index] === undefined) return 1;
+    const compared = compareIdentifiers(left.prerelease[index], right.prerelease[index]);
+    if (compared !== 0) return compared;
+  }
+  return 0;
+}
+
+export function skillVersionKind(value, channel) {
+  if (typeof value !== 'string') return null;
+  const parsed = parseVersion(value);
+  if (!parsed) return null;
+  const suffix = parsed.prerelease.join('.');
+  if (suffix === (channel === 'pre' ? 'pre' : '')) return 'release';
+  const pattern = channel === 'pre' ? /^pre-beta(?:\d+|\.\d+)?$/u : /^beta(?:\d+|\.\d+)?$/u;
+  return pattern.test(suffix) ? 'beta' : null;
+}
+
+function readVersionFile(skillDir) {
+  try {
+    const file = path.join(skillDir, 'VERSION');
+    return isRegularFile(file) ? parseVersion(fs.readFileSync(file, 'utf8')) : null;
+  } catch {
+    return null;
+  }
+}
+
+function readLocalVersion(skillDir) {
+  try {
+    const versionFile = path.join(skillDir, 'VERSION');
+    const skillFile = path.join(skillDir, 'SKILL.md');
+    const runtimeEntry = path.join(skillDir, 'references', 'runtime-entry.md');
+    if (![versionFile, skillFile, runtimeEntry].every(isRegularFile)) return null;
+    return parseVersion(fs.readFileSync(versionFile, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function selfUpdateNetworkRestricted() {
+  return /^(1|true|yes|on)$/iu.test(process.env.ALIPAY_AIPAY_SELF_UPDATE_NETWORK_RESTRICTED || '');
+}
+
+function packageManagerFailureKind(result) {
+  if (result?.error?.code === 'ENOENT') return 'local';
+  const raw = [
+    result?.error?.code,
+    result?.error?.message,
+    result?.stderr,
+    result?.stdout,
+  ].filter(Boolean).join('\n');
+  if (/ETIMEDOUT|ESOCKETTIMEDOUT|ENOTFOUND|EAI_AGAIN|ECONN(?:RESET|REFUSED|ABORTED)|EHOSTUNREACH|ENETUNREACH|network access[^]*(?:denied|blocked)|getaddrinfo|could not resolve|fetch failed|socket hang up|TLS handshake|503 Service Unavailable|502 Bad Gateway|504 Gateway Timeout/iu.test(raw)) {
+    return 'network';
+  }
+  return 'check';
+}
+
+function readChannel(skillDir) {
+  const source = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+  const declaredName = source.match(/^name:\s*(\S+)\s*$/m)?.[1];
+  const identity = declaredName === 'alipay-aipay-pre' ? 'pre' : 'stable';
+  const channelFile = path.join(skillDir, 'references', 'normal', 'json', 'release-channel.json');
+  if (!fs.existsSync(channelFile) && identity === 'stable') return 'stable';
+  if (!isRegularFile(channelFile)) throw new Error('invalid release channel');
+  const channel = JSON.parse(fs.readFileSync(channelFile, 'utf8')).channel;
+  if (!['stable', 'pre'].includes(channel) || channel !== identity) throw new Error('invalid release channel');
+  return channel;
+}
+
+async function npmLatest(channel) {
+  if (selfUpdateNetworkRestricted()) return { ok: false, reason: 'skipped-network-restricted' };
+  try {
+    const result = await spawnPackageManager('npm', ['view', '@alipay/alipay-aipay@latest', 'version', 'alipayAipayChannels', '--json'], {
+      timeout: npmQueryTimeoutMs,
+    });
+    if (result.status !== 0 || result.error) return { ok: false, reason: packageManagerFailureKind(result) };
+    const decoded = JSON.parse(result.stdout);
+    const packageVersion = typeof decoded?.version === 'string' ? parseVersion(decoded.version) : null;
+    const value = decoded?.alipayAipayChannels?.[channel];
+    const version = typeof value === 'string' ? parseVersion(value) : null;
+    return packageVersion && version && skillVersionKind(version.raw, channel) === 'release' ? { ok: true, version, packageVersion } : { ok: false, reason: 'check' };
+  } catch {
+    return { ok: false, reason: 'check' };
+  }
+}
+
+function transactionArtifacts(skillDir, transactionId, channel) {
+  const parent = path.dirname(skillDir);
+  const skillName = channel === 'pre' ? 'alipay-aipay-pre' : 'alipay-aipay';
+  return {
+    staging: path.join(parent, `.${skillName}-install-${transactionId}`),
+    backup: path.join(parent, `.${skillName}-backup-${transactionId}`),
+  };
+}
+
+function removeTransactionPath(target) {
+  try { fs.rmSync(target, { recursive: true, force: true }); } catch {}
+}
+
+function reconcileInstallTransaction(skillDir, transactionId, channel) {
+  const artifacts = transactionArtifacts(skillDir, transactionId, channel);
+  let current = readLocalVersion(skillDir);
+  if (!current && isRecoverableSkillRoot(artifacts.backup)) {
+    try {
+      removeTransactionPath(skillDir);
+      fs.renameSync(artifacts.backup, skillDir);
+    } catch {}
+    current = readLocalVersion(skillDir);
+  }
+  removeTransactionPath(artifacts.staging);
+  if (isRecoverableSkillRoot(skillDir)) removeTransactionPath(artifacts.backup);
+  return current;
+}
+
+async function installVersion(skillDir, packageVersion, channel) {
+  const transactionId = randomUUID();
+  const timeout = installTimeoutBudget();
+  let result;
+  try {
+    result = await spawnPackageManager(
+      'npx',
+      ['-y', `@alipay/alipay-aipay@${packageVersion.raw}`, 'install-current', '--channel', channel],
+      {
+        timeout,
+        env: {
+          ...process.env,
+          [selfUpdateTargetEnv]: skillDir,
+          [selfUpdateTransactionEnv]: transactionId,
+        },
+      },
+    );
+  } catch {
+    result = { status: null, error: new Error('package manager check failed'), stdout: '', stderr: '' };
+  }
+  return {
+    ok: result.status === 0 && !result.error,
+    reason: result.status === 0 && !result.error ? 'ok' : packageManagerFailureKind(result),
+    version: reconcileInstallTransaction(skillDir, transactionId, channel),
+  };
+}
+
+function reportOutcome(outcome) {
+  const version = outcome.version ? `=${outcome.version.raw}` : '';
+  process.stderr.write(`SELF_UPDATE:${outcome.kind}${version}\n`);
+}
+
+export async function runSelfUpdateCli(argv = process.argv) {
+  const skillDir = parseArgs(argv);
+  const channel = readChannel(skillDir);
+  const local = readLocalVersion(skillDir);
+  const installedVersion = readVersionFile(skillDir);
+  const kind = skillVersionKind(installedVersion?.raw, channel);
+  // A developer-installed beta is pinned, including when its entry is damaged.
+  if (kind === 'beta') return local ? { kind: 'CURRENT', version: local } : { kind: 'VERIFY_FAILED' };
+  if (installedVersion && !kind) return { kind: 'CHECK_FAILED' };
+  const checked = await npmLatest(channel);
+  if (!checked.ok) {
+    const current = readLocalVersion(skillDir);
+    if (current && (!local || compareVersions(current, local) > 0)) return { kind: 'UPDATED', version: current };
+    if (checked.reason === 'skipped-network-restricted') return { kind: 'SKIPPED_NETWORK_RESTRICTED' };
+    if (checked.reason === 'network') return { kind: 'RETRY_WITH_NETWORK' };
+    return { kind: 'CHECK_FAILED' };
+  }
+
+  const latest = checked.version;
+  if (local && compareVersions(local, latest) >= 0) return { kind: 'CURRENT', version: local };
+
+  const installed = await installVersion(skillDir, checked.packageVersion, channel);
+  const updated = installed.version || readLocalVersion(skillDir);
+  if (updated && readChannel(skillDir) === channel && compareVersions(updated, latest) >= 0) return { kind: 'UPDATED', version: updated };
+  if (installed.reason === 'network') return { kind: 'RETRY_WITH_NETWORK' };
+  if (installed.reason === 'local') return { kind: 'CHECK_FAILED' };
+  return { kind: installed.ok ? 'VERIFY_FAILED' : 'INSTALL_FAILED' };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    reportOutcome(await runSelfUpdateCli());
+  } catch {
+    reportOutcome({ kind: 'CHECK_FAILED' });
+  }
+}