@alipay/alipay-aipay 1.7.3 → 1.7.4

package/skill-pre/references/normal/scripts/windows/preflight.mjs

@@ -0,0 +1,182 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+
+export const directory = path.dirname(fileURLToPath(import.meta.url));
+export const policy = JSON.parse(fs.readFileSync(path.join(directory,'policy.json'),'utf8'));
+const slash = p => p.replaceAll('\\','/');
+let invocationContext;
+import {fail, run, powershell, psEnv, protect} from './acl.mjs';
+export {fail, run, protect} from './acl.mjs';
+import {telemetryStoragePaths} from '../telemetry.mjs';
+import {findGitBash} from './git-discovery.mjs';
+
+export function stateRoot() {
+  const root=path.join(process.env.LOCALAPPDATA || path.join(os.homedir(),'AppData/Local'),'alipay-aipay-pre/windows');
+  if(fs.existsSync(root)&&fs.lstatSync(root).isSymbolicLink()) fail('STORAGE_FAILED');
+  fs.mkdirSync(root,{recursive:true}); protect(root); return root;
+}
+export function readState(root) {
+  const file=path.join(root,'environment.json');
+  if(!fs.existsSync(file)) return {schemaVersion:1,repairAttempts:0,prepareAttempts:0};
+  try {
+    const s=JSON.parse(fs.readFileSync(file,'utf8'));
+    if(s.schemaVersion!==1||!Number.isInteger(s.repairAttempts)||!Number.isInteger(s.prepareAttempts)) throw new Error();
+    return s;
+  } catch { fail('ENVIRONMENT_STATE_INVALID'); }
+}
+export function saveState(root,s) {
+  const temporary=path.join(root,'environment-'+crypto.randomUUID()+'.tmp');
+  fs.writeFileSync(temporary,JSON.stringify(s),{flag:'wx'});
+  fs.renameSync(temporary,path.join(root,'environment.json'));
+}
+export function withLock(root,fn) {
+  const lock=path.join(root,'environment.lock'); let fd;
+  // Concurrent discovery children briefly update the same state. Wait for that
+  // short critical section, never replay a check/install/business operation.
+  const deadline=Date.now()+2000;
+  while(fd===undefined) {
+    try { fd=fs.openSync(lock,'wx'); }
+    catch(e) {
+      if(e.code!=='EEXIST'||Date.now()>=deadline)fail('ENVIRONMENT_BUSY');
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,25);
+    }
+  }
+  try { return fn(); } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
+}
+// Match the existing environment policy: reuse a working jq; the managed
+// installer is version-pinned only when jq is absent or unusable.
+export function locateJq() {
+  const systemPath=Object.entries(process.env).find(([k])=>k.toLowerCase()==='path')?.[1]||'';
+  const candidates=[path.join(os.homedir(),'.local/bin/jq.exe'),
+    ...systemPath.split(path.delimiter).filter(p=>path.isAbsolute(p)).map(p=>path.join(p,'jq.exe'))];
+  return candidates.find(file=>fs.existsSync(file) &&
+    run(file,['--version']).status===0 &&
+    run(file,['-n','-e','--arg','value','ok','$value == "ok"']).status===0);
+}
+export function locate() {
+  if(process.platform!=='win32') fail('WINDOWS_ADAPTER_REQUIRES_WINDOWS');
+  if(Number(process.versions.node.split('.')[0])<policy.nodeMinimumMajor) fail('DEPENDENCY_VERSION','Node');
+  // Only a native x64 execution mapping has been implemented. No OS build allowlist.
+  const arch=(process.env.PROCESSOR_ARCHITEW6432||process.env.PROCESSOR_ARCHITECTURE||'').toUpperCase();
+  if(process.arch!=='x64'||arch!=='AMD64') fail('NO_COMPATIBLE_EXECUTION_MAPPING',arch||'unknown');
+  const foundGit=findGitBash();
+  if(!foundGit) fail('DEPENDENCY_MISSING','Git Bash');
+  const {bash,git}=foundGit;
+  const bin=path.join(os.homedir(),'.local/bin');
+  const cli=path.join(bin,'alipay-cli.exe'),jq=locateJq();
+  if(!jq) fail('DEPENDENCY_MISSING','jq');
+  if(!fs.existsSync(cli)) fail('DEPENDENCY_MISSING','alipay-cli');
+  const env={...process.env};
+  const oldPath=Object.entries(env).find(([k])=>k.toLowerCase()==='path')?.[1]||'';
+  for(const k of Object.keys(env)) if(k.toLowerCase()==='path') delete env[k];
+  env.PATH=[path.join(directory,'bin'),path.dirname(bash),path.join(git,'usr/bin'),path.dirname(process.execPath),bin,oldPath].join(path.delimiter);
+  delete env.ALIPAY_AIPAY_TEST_PLATFORM; delete env.ALIPAY_AIPAY_TEST_MODE;
+  delete env.BASH_ENV; delete env.ENV; delete env.SHELLOPTS;
+  env.MSYS_NO_PATHCONV='1';env.MSYS2_ARG_CONV_EXCL='*';
+  env.ALIPAY_WINDOWS_CLI_RUNNER=slash(path.join(directory,'cli-process.mjs'));
+  env.ALIPAY_WINDOWS_NODE=slash(process.execPath);
+  env.ALIPAY_WINDOWS_JQ=slash(jq);
+  env.ALIPAY_WINDOWS_CLI=slash(cli);
+  env.ALIPAY_WINDOWS_CREDENTIALS_DIR=slash(path.join(os.homedir(),'.alipay-cli/credentials'));
+  env.ALIPAY_WINDOWS_LOGS_DIR=slash(path.join(process.env.APPDATA||path.join(os.homedir(),'AppData/Roaming'),'alipay-cli/data/logs'));
+  env.ALIPAY_WINDOWS_CLI_ENTRY=slash(path.join(directory,'bin/alipay-cli'));
+  env.ALIPAY_WINDOWS_ACL_SCRIPT=slash(path.join(directory,'acl-native.mjs'));
+  env.ALIPAY_WINDOWS_POWERSHELL=slash(powershell());
+  env.NODE_BINARY='node';
+  return {bash,git,cli,jq,env};
+}
+function writable(directoryPath) {
+  if(!fs.existsSync(directoryPath)) fs.mkdirSync(directoryPath,{recursive:true});
+  if(fs.lstatSync(directoryPath).isSymbolicLink()) fail('STORAGE_FAILED');
+  const p=path.join(directoryPath,'.aipay-probe-'+crypto.randomUUID());
+  try { fs.writeFileSync(p,'probe',{flag:'wx'});fs.renameSync(p,p+'.moved');fs.unlinkSync(p+'.moved'); }
+  catch { fail('STORAGE_FAILED'); }
+}
+// Pin the existing telemetry location before changing Bash scratch paths. This
+// never changes the gateway environment, consent, session, run or override files.
+export function privateChildEnvironment(env, temporary) {
+  return {...env, ALIPAY_AIPAY_TELEMETRY_DIR: telemetryStoragePaths(env).state_dir,
+    TEMP: temporary, TMP: temporary, TMPDIR: slash(temporary)};
+}
+
+export function inspectLocal(root) {
+  const context=locate();
+  const temporary=path.join(root,'tmp');fs.mkdirSync(temporary,{recursive:true});protect(temporary);
+  context.env = privateChildEnvironment(context.env, temporary);
+  const home=os.homedir();
+  for(const p of [path.join(home,'.alipay-cli/credentials'),path.join(process.env.APPDATA||path.join(home,'AppData/Roaming'),'alipay-cli/data/logs')]) {
+    fs.mkdirSync(p,{recursive:true});protect(p);writable(p);
+  }
+  for(const [exe,args,name] of [[context.cli,['version'],'alipay-cli'],[context.jq,['-n','-e','--arg','v','猫 $HOME "x"','$v == "猫 $HOME \\"x\\""'],'jq']]) {
+    // jq round-trip is checked in the Bash probe below; this native check verifies launch/version.
+    const r=run(exe,name==='jq'?['--version']:args,{env:context.env});
+    if(r.status!==0||!r.stdout.trim()) fail('EXECUTION_FAILED',name);
+  }
+  const r=run(context.bash,['--noprofile','--norc',slash(path.join(directory,'probe.sh'))],{env:context.env});
+  if(r.status!==0||r.stdout.trim()!=='WINDOWS_PROBE:READY') fail('SHELL_TRANSPORT_FAILED');
+  writable(temporary);
+  return context;
+}
+export function ensureReady({retry=false}={}) {
+  // Reuse only within this Node invocation. Each new process performs full checks;
+  // persisted failures never prevent a read-only check after the user fixes a dependency.
+  if(!retry&&invocationContext) {
+    locate();return invocationContext.context;
+  }
+  const root=stateRoot();
+  try {
+    const context=inspectLocal(root);
+    // Diagnostic state is optional after a complete capability check. An
+    // abandoned lock must not add two seconds to every subsequent CLI call.
+    if (!fs.existsSync(path.join(root,'environment.lock'))) {
+      try {
+        withLock(root,()=>{
+          const state=readState(root);
+          if(state.blocked){state.blocked=false;state.reason='';saveState(root,state);}
+        });
+      } catch (error) {
+        if (!['ENVIRONMENT_BUSY','ENVIRONMENT_STATE_INVALID'].includes(error.reason)) throw error;
+      }
+    }
+    invocationContext={root,context};return context;
+  } catch(e) {
+    if (!fs.existsSync(path.join(root,'environment.lock'))) {
+      try {
+        withLock(root,()=>{const state=readState(root);state.blocked=true;state.reason=e.reason||'CHECK_FAILED';saveState(root,state);});
+      } catch (error) {
+        if (!['ENVIRONMENT_BUSY','ENVIRONMENT_STATE_INVALID'].includes(error.reason)) throw error;
+      }
+    }
+    throw e;
+  }
+}
+export function applyReady(options) {
+  // Do not change the gateway's TEMP, telemetry switches or business context.
+  return ensureReady(options);
+}
+export function resultError(error) {
+  const needsSetup = error.reason === 'DEPENDENCY_MISSING' ||
+    (error.reason === 'EXECUTION_FAILED' && error.dependency === 'alipay-cli');
+  return {schemaVersion:1,status:needsSetup?'NEEDS_SETUP':'BLOCKED',reason:error.reason||'CHECK_FAILED',dependency:error.dependency||'',validationCoverage:'NOT_VERIFIED'};
+}
+export function report(error) {
+  const r=resultError(error);
+  process.stderr.write('ALIPAY_AIPAY_INTERNAL:WINDOWS_ENV_RESULT='+JSON.stringify(r)+'\n');
+
+}
+if(process.argv[1]&&path.resolve(process.argv[1])===fileURLToPath(import.meta.url)) {
+  try {
+    const c=ensureReady();
+    if(process.argv[2]==='shell-env') {
+      const quote=s=>"'"+s.replaceAll("'","'\\''")+"'";
+      // Only explicit adapter-owned values. Business context and credentials never appear here.
+      for(const k of ['PATH','TEMP','TMP','TMPDIR','ALIPAY_AIPAY_TELEMETRY_DIR','ALIPAY_WINDOWS_NODE','ALIPAY_WINDOWS_JQ','ALIPAY_WINDOWS_CLI','ALIPAY_WINDOWS_CREDENTIALS_DIR','ALIPAY_WINDOWS_LOGS_DIR','ALIPAY_WINDOWS_CLI_ENTRY','ALIPAY_WINDOWS_CLI_RUNNER','ALIPAY_WINDOWS_ACL_SCRIPT','ALIPAY_WINDOWS_POWERSHELL','NODE_BINARY','MSYS_NO_PATHCONV','MSYS2_ARG_CONV_EXCL']) {
+        const v=k==='PATH'?c.env[k].split(';').map(p=>slash(p).replace(/^([a-zA-Z]):/,(_,d)=>'/'+d.toLowerCase())).join(':'):c.env[k];
+        console.log('export '+k+'='+quote(v));
+      }
+    } else console.error('ALIPAY_AIPAY_INTERNAL:WINDOWS_ENV_RESULT='+JSON.stringify({schemaVersion:1,status:'READY',validationCoverage:'NOT_VERIFIED'}));
+  }catch(e){report(e);process.exitCode=78;}
+}

package/skill-pre/references/normal/scripts/windows/prepare.mjs

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import {refreshWindowsCli} from './cli-install.mjs';
+import {findGitBash} from './git-discovery.mjs';
+import {policy,run,stateRoot,readState,saveState,withLock,ensureReady,locateJq,fail,report} from './preflight.mjs';
+
+export function claimPreparation(state,{repair=false,authorized=false}={}) {
+  if(!authorized) fail('PREPARATION_AUTHORIZATION_REQUIRED');
+  if(repair) {
+    if(state.repairAttempts>=policy.explicitRepairRetries) fail('RETRY_BUDGET_EXHAUSTED');
+    state.repairAttempts++;
+  } else if(state.prepareAttempts>=1 || state.repairAttempts>=1) fail('RETRY_BUDGET_EXHAUSTED');
+  state.prepareAttempts++;state.blocked=true;state.reason='PREPARATION_INCOMPLETE';
+  return state;
+}
+function installAsset(name,asset) {
+  const bin=path.join(os.homedir(),'.local/bin');fs.mkdirSync(bin,{recursive:true});
+  const target=path.join(bin,name+'.exe');
+  const hash=b=>crypto.createHash('sha256').update(b).digest('hex');
+  if(fs.existsSync(target)&&hash(fs.readFileSync(target))===asset.sha256)return;
+  const temporary=path.join(bin,name+'-'+crypto.randomUUID()+'.download');
+  const curl=path.join(process.env.SystemRoot||'C:/Windows','System32/curl.exe');
+  try {
+    const r=run(curl,['--compressed','--fail','--silent','--show-error','--location','--proto','=https','--proto-redir','=https','--connect-timeout','10','--max-time','60','--output',temporary,asset.url],{timeout:65000});
+    if(r.status!==0)fail('DOWNLOAD_FAILED',name);
+    if(hash(fs.readFileSync(temporary))!==asset.sha256)fail('INTEGRITY_FAILED',name);
+    fs.renameSync(temporary,target);
+    if(run(target,name==='jq'?['--version']:['version']).status!==0)fail('EXECUTION_FAILED',name);
+  }finally{if(fs.existsSync(temporary))fs.unlinkSync(temporary);}
+}
+export function prepare({authorized=false,repair=false}={}) {
+  const root=stateRoot();
+  withLock(root,()=>{
+    const state=claimPreparation(readState(root),{authorized,repair});saveState(root,state);
+    try {
+      if(!findGitBash()) {
+        const winget=path.join(process.env.LOCALAPPDATA||'','Microsoft/WindowsApps/winget.exe');
+        if(!fs.existsSync(winget))fail('MANUAL_GIT_INSTALL_REQUIRED','Git Bash');
+        const r=run(winget,['install','--id','Git.Git','--exact','--source','winget','--scope','user','--silent','--disable-interactivity','--accept-package-agreements','--accept-source-agreements'],{timeout:120000});
+        if(r.status!==0||!findGitBash())fail('GIT_INSTALL_FAILED','Git Bash');
+      }
+      if(!locateJq()) installAsset('jq',policy.jq);
+      const cli=path.join(os.homedir(),'.local/bin/alipay-cli.exe');
+      if(!fs.existsSync(cli)||run(cli,['version']).status!==0) {
+        if(refreshWindowsCli()!=='READY') fail('CLI_INSTALL_FAILED','alipay-cli');
+      }
+      state.blocked=false;state.reason='';saveState(root,state);
+    }catch(e){state.blocked=true;state.reason=e.reason||'INSTALL_FAILED';saveState(root,state);throw e;}
+  });
+  return ensureReady();
+}
+export function parseEnvironmentRequest(args, route=process.env.ALIPAY_AIPAY_WINDOWS_ROUTE) {
+  const [mode,...rest]=args;
+  const options={};
+  for(let i=0;i<rest.length;i+=2) {
+    if(!['--product-type','--authorized','--repair-confirmed','--root-intent'].includes(rest[i])||rest[i+1]===undefined||Object.hasOwn(options,rest[i]))fail('ENVIRONMENT_ARGUMENT_INVALID');
+    options[rest[i]]=rest[i+1];
+  }
+  if(options['--product-type']&&!['aipay','webpay','apppay'].includes(options['--product-type']))fail('ENVIRONMENT_ARGUMENT_INVALID');
+  for (const key of ['--authorized','--repair-confirmed']) {
+    if (options[key] !== undefined && !['true','false'].includes(options[key])) fail('ENVIRONMENT_ARGUMENT_INVALID');
+  }
+  if (mode === 'retry' && options['--repair-confirmed'] !== 'true') fail('PREPARATION_AUTHORIZATION_REQUIRED');
+  const recovering = mode === 'retry' || (mode === 'prepare' && options['--repair-confirmed'] === 'true');
+  if (recovering && (!['integration_only','onboarding_only','full_process'].includes(options['--root-intent']) ||
+      route !== 'LEGACY')) fail('ENVIRONMENT_ARGUMENT_INVALID');
+  if (!recovering && options['--root-intent'] !== undefined) fail('ENVIRONMENT_ARGUMENT_INVALID');
+  return {mode,options,recovering};
+}
+export function runEnvironment(args) {
+  const {mode,options,recovering}=parseEnvironmentRequest(args);
+  try {
+    if(['prepare','prepare-jq'].includes(mode))prepare({authorized:options['--authorized']==='true',repair:options['--repair-confirmed']==='true'});
+    else if(['check','integration-check','retry'].includes(mode))ensureReady({retry:mode==='retry'&&options['--repair-confirmed']==='true'});
+    else fail('ENVIRONMENT_ARGUMENT_INVALID');
+    console.log('CLI_ENV:READY');
+    if (recovering) process.stderr.write('ALIPAY_AIPAY_INTERNAL:WINDOWS_ROUTE=' +
+      JSON.stringify({schemaVersion:1,rootIntent:options['--root-intent'],route:'READY'}) + '\n');
+    return 0;
+  }catch(e){report(e);return 78;}
+}

package/skill-pre/references/normal/scripts/windows/probe.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -eu
+case "$(uname -s)" in MINGW*|MSYS*) ;; *) exit 78;; esac
+for tool in cygpath mktemp chmod stat find sed grep awk tr base64 head tail dirname basename cat mv rm mkdir env curl git; do
+  command -v "$tool" >/dev/null || exit 78
+done
+[[ "$(cygpath -m "$(command -v alipay-cli)")" == "$ALIPAY_WINDOWS_CLI_ENTRY" ]] || exit 78
+value='猫抓板 "quoted" $HOME /scope/a https://example.com/a?x=1&y=2'
+out=$(printf '%s' "$value" | "$ALIPAY_WINDOWS_JQ" -Rs . | "$ALIPAY_WINDOWS_JQ" -r .)
+[[ "$out" == "$value" ]] || exit 78
+"$ALIPAY_WINDOWS_NODE" -e 'if(process.argv[1]!==process.env.WINDOWS_PROBE_VALUE) process.exit(78)' "$value" >/dev/null 2>&1 && exit 78
+WINDOWS_PROBE_VALUE="$value" "$ALIPAY_WINDOWS_NODE" -e 'if(process.argv[1]!==process.env.WINDOWS_PROBE_VALUE) process.exit(78)' "$value"
+"$ALIPAY_WINDOWS_CLI" version >/dev/null
+printf 'WINDOWS_PROBE:READY\n'

package/skill-pre/references/normal/scripts/windows/python-execution.mjs

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {protect} from './acl.mjs';
+
+// Pin tempfile itself: environment variables alone allow Python to fall back to
+// another directory if the protected directory becomes unavailable.
+const bootstrap = [
+  'import os, runpy, sys, tempfile',
+  'tempfile.tempdir = sys.argv[1]',
+  'sys.argv = sys.argv[2:]',
+  'sys.path[0] = os.path.dirname(sys.argv[0])',
+  'runpy.run_path(sys.argv[0], run_name="__main__")'
+].join('\n');
+
+// The caller has already validated the single registered A2M script path.
+export function runWindowsPython(python, script, args, {
+  env = process.env, tempRoot = os.tmpdir(), protectDirectory = protect, spawn = spawnSync,
+  cleanup = directory => fs.rmSync(directory, {recursive: true, force: true})
+} = {}) {
+  const temporary = fs.mkdtempSync(path.join(path.resolve(tempRoot), 'alipay-aipay-a2m-'));
+  try {
+    // Empty until NTFS DACL setup and readback have both succeeded. Children
+    // inherit the restricted ACL, including files written directly by curl.
+    protectDirectory(temporary);
+    const childEnv = Object.fromEntries(Object.entries(env)
+      .filter(([key]) => !['TEMP', 'TMP', 'TMPDIR'].includes(key.toUpperCase())));
+    Object.assign(childEnv, {TEMP: temporary, TMP: temporary, TMPDIR: temporary});
+    return spawn(python.command, [...python.prefix, '-c', bootstrap, temporary, script, ...args], {
+      env: childEnv, stdio: 'inherit', shell: false, windowsHide: true
+    });
+  } finally {
+    // Clean only this invocation's scratch directory; never replay the payment.
+    try { cleanup(temporary); }
+    catch { process.stderr.write('ALIPAY_AIPAY_INTERNAL:WINDOWS_A2M_SCRATCH_CLEANUP=FAILED\n'); }
+  }
+}

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

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {run, fail, protect} from './acl.mjs';
+
+const script = fileURLToPath(new URL('../../../integration/modules/scripts/local_402_sandbox_pay.py', import.meta.url));
+const probe = 'import json, os, runpy, sys; assert sys.version_info.major == 3 and sys.platform == "win32"; sys.path.insert(0, os.path.dirname(sys.argv[1])); runpy.run_path(sys.argv[1], run_name="__alipay_probe__"); print(json.dumps({"executable":sys.executable,"version":list(sys.version_info[:3])}))';
+
+export function findWindowsPython({env = process.env, execute = run, exists = fs.existsSync, list = fs.readdirSync} = {}) {
+  const probeEnv = Object.fromEntries(Object.entries(env).filter(([key]) =>
+    !['PYTHON_MANAGER_AUTOMATIC_INSTALL', 'PYLAUNCHER_ALLOW_INSTALL', 'PYLAUNCHER_ALWAYS_INSTALL'].includes(key.toUpperCase())));
+  probeEnv.PYTHON_MANAGER_AUTOMATIC_INSTALL = '0';
+  const candidates = [{command: 'py', prefix: ['-3']}, {command: 'python', prefix: []}, {command: 'python3', prefix: []}];
+  const roots = [env.LOCALAPPDATA && path.win32.join(env.LOCALAPPDATA, 'Programs/Python'), env.ProgramFiles && path.win32.join(env.ProgramFiles, 'Python')].filter(Boolean);
+  for (const root of roots) {
+    let names = [];
+    try { names = list(root).filter(name => /^Python3\d+$/i.test(name)).sort().reverse(); } catch {}
+    for (const name of names) candidates.push({command: path.win32.join(root, name, 'python.exe'), prefix: []});
+  }
+  for (const candidate of candidates) {
+    const result = execute(candidate.command, [...candidate.prefix, '-c', probe, script], {env: probeEnv, timeout: 10000});
+    if (result.status !== 0) continue;
+    try {
+      const value = JSON.parse(result.stdout);
+      if (value.version?.[0] === 3 && path.win32.isAbsolute(value.executable) && exists(value.executable)) {
+        return {command: value.executable, prefix: []};
+      }
+    } catch {}
+  }
+  return null;
+}
+
+// A separate budget: preparing Python for A2M never consumes or resets the
+// Git/jq/CLI environment repair state, or any business/telemetry state.
+export function prepareWindowsPython({authorized = false, repair = false, find = findWindowsPython,
+  execute = run, env = process.env, root, protectRoot = protect, lock, exists = fs.existsSync} = {}) {
+  const existing = find({env});
+  if (existing) return existing;
+  if (!authorized) fail('DEPENDENCY_MISSING', 'Python 3');
+  protectRoot(root);
+  return lock(root, () => {
+    const file = path.join(root, 'python-environment.json');
+    let state = {prepareAttempts: 0, repairAttempts: 0};
+    if (fs.existsSync(file)) {
+      try { state = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { fail('ENVIRONMENT_STATE_INVALID'); }
+    }
+    if (!Number.isInteger(state.prepareAttempts) || state.prepareAttempts < 0 ||
+        !Number.isInteger(state.repairAttempts) || state.repairAttempts < 0) fail('ENVIRONMENT_STATE_INVALID');
+    if (repair ? state.repairAttempts >= 1 : state.prepareAttempts >= 1 || state.repairAttempts >= 1) fail('RETRY_BUDGET_EXHAUSTED');
+    state.prepareAttempts++; if (repair) state.repairAttempts++;
+    fs.writeFileSync(file, JSON.stringify(state));
+    const winget = env.LOCALAPPDATA && path.win32.join(env.LOCALAPPDATA, 'Microsoft/WindowsApps/winget.exe');
+    if (!winget || !exists(winget)) fail('MANUAL_PYTHON_INSTALL_REQUIRED', 'Python 3');
+    const result = execute(winget, ['install', '--id', 'Python.Python.3.14', '--exact', '--source', 'winget',
+      '--scope', 'user', '--architecture', 'x64', '--silent', '--disable-interactivity',
+      '--accept-package-agreements', '--accept-source-agreements'], {env, timeout: 180000});
+    if (result.status !== 0) fail('PYTHON_INSTALL_FAILED', 'Python 3');
+    const python = find({env});
+    if (!python) fail('PYTHON_VERIFY_FAILED', 'Python 3');
+    return python;
+  });
+}
+
+export async function runPythonEnvironment(args) {
+  const [mode, ...rest] = args;
+  const options = {};
+  for (let i = 0; i < rest.length; i += 2) {
+    if (!['--authorized', '--repair-confirmed'].includes(rest[i]) ||
+        !['true', 'false'].includes(rest[i + 1]) || options[rest[i]] !== undefined) fail('ENVIRONMENT_ARGUMENT_INVALID');
+    options[rest[i]] = rest[i + 1];
+  }
+  if (!['check-python', 'prepare-python'].includes(mode) || (mode === 'check-python' && rest.length)) fail('ENVIRONMENT_ARGUMENT_INVALID');
+  const {stateRoot, withLock, report} = await import('./preflight.mjs');
+  try {
+    // Delay all filesystem state until installation is actually necessary.
+    const found = findWindowsPython();
+    if (!found) {
+      if (mode === 'check-python' || options['--authorized'] !== 'true') fail('DEPENDENCY_MISSING', 'Python 3');
+      prepareWindowsPython({authorized: true, repair: options['--repair-confirmed'] === 'true',
+        root: stateRoot(), protectRoot: protect, lock: withLock});
+    }
+    process.stderr.write('ALIPAY_AIPAY_INTERNAL:PYTHON_ENV=READY\n');
+    return 0;
+  } catch (error) { report(error); return 78; }
+}

package/skill-pre/references/normal/scripts/windows/routing.mjs

@@ -0,0 +1,83 @@
+import {applyReady, report, resultError, readState, stateRoot} from './preflight.mjs';
+import {prepare} from './prepare.mjs';
+
+const intents = ['integration_only', 'onboarding_only', 'full_process'];
+const prefix = 'ALIPAY_AIPAY_INTERNAL:';
+
+// This is a routing result, never proof of a successful payment or onboarding.
+export function selectRoute({rootIntent = '', authorized = false, repair = false} = {}) {
+  if (rootIntent && !intents.includes(rootIntent)) throw new Error('非法 Windows 根意图');
+  let error;
+  try {
+    applyReady({retry: repair});
+    return emit({rootIntent, route: 'READY'});
+  } catch (e) { error = e; }
+  if (authorized) {
+    // A missing dependency or an unlaunchable local CLI permits preparation;
+    // network, permissions, architecture, integrity and business errors do not.
+    try {
+      const state = readState(stateRoot());
+      const cliUnusable = error.reason === 'EXECUTION_FAILED' && error.dependency === 'alipay-cli';
+      if ((error.reason === 'DEPENDENCY_MISSING' || cliUnusable ||
+          (error.reason === 'REPAIR_REQUIRED' && state.reason === 'DEPENDENCY_MISSING')) &&
+          state.prepareAttempts === 0 && state.repairAttempts === 0) {
+        prepare({authorized: true});
+        return emit({rootIntent, route: 'READY'});
+      }
+    } catch (e) { error = e; }
+  }
+  report(error);
+  return emit({rootIntent, route: 'LEGACY', ...resultError(error)});
+}
+
+function emit(result) {
+  const value = {schemaVersion: 1, ...result};
+  process.stderr.write(prefix + 'WINDOWS_ROUTE=' + JSON.stringify(value) + '\n');
+  return value;
+}
+
+export function runWindowsEntry(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i], value = args[i + 1];
+    if (!['--root-intent', '--prepare-authorized', '--repair-confirmed'].includes(key) ||
+        value === undefined || options[key] !== undefined) throw new Error('Windows 入口参数非法');
+    options[key] = value;
+  }
+  if (!intents.includes(options['--root-intent'])) throw new Error('必须先识别三种根意图之一');
+  for (const key of ['--prepare-authorized', '--repair-confirmed']) {
+    if (options[key] !== undefined && !['true', 'false'].includes(options[key])) throw new Error('Windows 入口布尔参数非法');
+  }
+  return selectRoute({rootIntent: options['--root-intent'],
+    authorized: options['--prepare-authorized'] === 'true', repair: options['--repair-confirmed'] === 'true'});
+}
+
+// A caller's LEGACY fact can only disable operations. READY is never a capability token.
+export function consumeRoute(args) {
+  const remaining = [];
+  let route;
+  let seen = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== '--windows-route') { remaining.push(args[i]); continue; }
+    if (seen || !['READY','LEGACY'].includes(args[i + 1])) throw new Error('Windows 分流参数非法');
+    seen = true;
+    route = args[++i];
+  }
+  return {args: remaining, route};
+}
+
+// Native Node messages, telemetry and project inspection do not depend on Bash.
+// READY is never trusted as proof; the actual business executor checks again.
+export function requireBusinessEnvironment() {
+  if (process.env.ALIPAY_AIPAY_WINDOWS_ROUTE === 'LEGACY') {
+    const error = Object.assign(new Error('WINDOWS_ENVIRONMENT_UNAVAILABLE'), {reason: 'WINDOWS_ENVIRONMENT_UNAVAILABLE'});
+    throw error;
+  }
+  return applyReady();
+}
+
+export function onboardingRoute() {
+  if (process.env.ALIPAY_AIPAY_WINDOWS_ROUTE === 'LEGACY') return 'LEGACY';
+  try { requireBusinessEnvironment(); return 'READY'; }
+  catch (error) { report(error); return 'LEGACY'; }
+}

package/skill-pre/references/normal/scripts/windows/shell_helpers.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Loaded only on real Git for Windows; no Linux/macOS command is replaced.
+_win_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_win_exports=$(command node "$(cygpath -m "$_win_dir/preflight.mjs")" shell-env) || { exit 78; }
+eval "$_win_exports"
+unset _win_exports
+
+windows_protect() {
+  "$ALIPAY_WINDOWS_NODE" "$ALIPAY_WINDOWS_ACL_SCRIPT" "$(cygpath -m "$1")" >/dev/null
+}
+
+git() {
+  local args=() previous='' arg
+  for arg in "$@"; do
+    if [ "$previous" = -C ]; then arg=$(cygpath -m "$arg") || return 78; fi
+    args+=("$arg");previous="$arg"
+  done
+  command git "${args[@]}"
+}
+
+# jq is a Bash function so large --argjson values never enter a Windows argv.
+# Slurp exactly one JSON value and bind it back to the original variable name.
+jq() {
+  local args=() files=() bindings='' filter='' name value file rc arg
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --argjson)
+        [ "$#" -ge 3 ] || return 64
+        name="$2";value="$3";shift 3
+        [[ "$name" =~ ^[a-zA-Z_][a-zA-Z0-9_]*$ ]] || return 64
+        file=$(mktemp "${TMPDIR}/jq-argument.XXXXXX") || return 78
+        printf '%s' "$value" >"$file" || { rm -f "$file"; return 78; }
+        files+=("$file");args+=(--slurpfile "$name" "$(cygpath -m "$file")")
+        bindings+="(if (\$$name|length)==1 then \$$name[0] else error(\"invalid argjson\") end) as \$$name | "
+        ;;
+      --arg)
+        [ "$#" -ge 3 ] || return 64
+        value="$3"
+        if [ "$2" = configPath ]; then value=$(cygpath -m "$value") || return 78; fi
+        args+=("$1" "$2" "$value");shift 3 ;;
+      --argfile|--slurpfile|--rawfile)
+        [ "$#" -ge 3 ] || return 64
+        value=$(cygpath -m "$3") || return 78
+        args+=("$1" "$2" "$value");shift 3 ;;
+      -*) args+=("$1");shift ;;
+      *) filter="$1";shift;break ;;
+    esac
+  done
+  if [ -n "$filter" ]; then args+=("$bindings$filter"); fi
+  for arg in "$@"; do
+    if [[ "$arg" == /* ]] && [ -f "$arg" ]; then args+=("$(cygpath -m "$arg")");else args+=("$arg");fi
+  done
+  if "$ALIPAY_WINDOWS_JQ" "${args[@]}"; then rc=0; else rc=$?; fi
+  [ "${#files[@]}" -eq 0 ] || rm -f "${files[@]}"
+  return "$rc"
+}
+
+node() {
+  local args=() catalog='' arg previous='' first=true
+  while [ "$#" -gt 0 ]; do
+    arg="$1";shift
+    if [ "$arg" = --mcc-catalog-json ]; then
+      [ "$#" -gt 0 ] || return 64
+      catalog="$1";shift;args+=(--mcc-catalog-json @windows-stdin);continue
+    fi
+    if { [ "$first" = true ] && [[ "$arg" == /* ]]; } || [[ "$previous" =~ ^--(project-path|base-path|config-path|search-base-path)$ ]]; then
+      arg=$(cygpath -m "$arg") || return 78
+    fi
+    args+=("$arg");previous="$arg";first=false
+  done
+  if [ -n "$catalog" ]; then printf '%s' "$catalog" | "$ALIPAY_WINDOWS_NODE" "${args[@]}"
+  else "$ALIPAY_WINDOWS_NODE" "${args[@]}";fi
+}
+
+# Preserve command names and business arguments; only file-upload paths cross
+# the POSIX/native boundary here. No fake CLI and no business response rewriting.
+alipay-cli() {
+  local args=("$@")
+  if [ "${1:-}" = file ] && [ "${2:-}" = upload ] && [ "$#" -ge 3 ]; then
+    args[2]=$(cygpath -m "$3") || return 78
+  fi
+  "$ALIPAY_WINDOWS_NODE" "$ALIPAY_WINDOWS_CLI_RUNNER" "${args[@]}"
+}