@xiashe/sdk 0.1.17 → 0.1.19

package/alipayWallet.mjs

@@ -12,6 +12,110 @@ const SENSITIVE_USER_OUTPUT = /payment[-_ ]?proof|payment[-_ ]?needed|seller_sig
 const DEFAULT_STATE_DIR = path.join(os.homedir(), '.xiashe', 'alipay-402');
 const OFFICIAL_MEDIA_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
 const MAX_OFFICIAL_MEDIA_BYTES = 8 * 1024 * 1024;
+const SAFE_OFFICIAL_FAILURE_CODES = new Set([
+  'TRADE_PROGRESS_FAILED',
+  'PAYMENT_NEEDED_REJECTED',
+  'SYSTEM_ERROR',
+  'BUYER_IDENTITY_REJECTED',
+  'WALLET_NOT_READY',
+  // AI收 payment.verify business errors. These can be returned after the
+  // wallet has paid and retries the protected resource with Payment-Proof.
+  'INVALID_PARAMETER',
+  'CLIENT_SESSION_IS_EMPTY',
+  'PAYMENT_PROOF_AGENT_MISMATCH',
+  'PAYMENT_PROOF_BUYER_MISMATCH',
+  'PAYMENT_PROOF_EMPTY',
+  'PAYMENT_PROOF_ID_MISMATCH',
+  'PAYMENT_PROOF_INVALID',
+  'PAYMENT_PROOF_NOT_FOUND',
+  'PAYMENT_PROOF_STATUS_INVALID',
+  'PAYMENT_PROOF_TRADE_NO_MISMATCH',
+  'TRADE_NOT_FOUND',
+  'TRADE_NO_EMPTY',
+  'TRADE_NO_INVALID',
+  'TRADE_STATUS_CLOSED',
+  'TRADE_STATUS_UNPAID',
+  // AI收 fulfillment.confirm business errors. These do not revoke a
+  // delivered entitlement, but do need an operator-visible diagnosis.
+  'SELLER_IDENTITY_MISMATCH',
+  'SELLER_ID_EMPTY',
+  'TRADE_STATUS_INVALID'
+]);
+
+const OFFICIAL_ERROR_DIAGNOSES = {
+  PAYMENT_NEEDED_REJECTED: {
+    stage: 'alipay_bill_validation',
+    nextStep: '核对支付宝平台中该 APPID 的应用公钥、service_id、收款方 2088 seller_id 和线上接入状态；修复后必须创建新订单再测试。'
+  },
+  CLIENT_SESSION_IS_EMPTY: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '买方 CLI 未传回有效 client_session；升级官方支付宝支付组件后，用新订单重新发起付款。'
+  },
+  PAYMENT_PROOF_AGENT_MISMATCH: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付凭证与当前 Agent 商户身份不一致；确认付款与重试使用同一官方钱包运行时后，以新订单重试。'
+  },
+  PAYMENT_PROOF_BUYER_MISMATCH: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付买家与凭证买家不一致；不要复用凭证，请在同一支付宝买家身份下重新发起付款。'
+  },
+  PAYMENT_PROOF_ID_MISMATCH: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: 'Payment-Proof 中的卖家身份与本 Skill 配置不一致；核对 APPID、2088 seller_id 和 service_id。'
+  },
+  PAYMENT_PROOF_EMPTY: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '官方钱包没有返回支付凭证；请停止，不要手工补造凭证，并用受支持运行时重新发起。'
+  },
+  PAYMENT_PROOF_INVALID: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付宝返回的支付凭证格式无效；请使用最新官方买方组件，并创建新订单重试。'
+  },
+  PAYMENT_PROOF_NOT_FOUND: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付凭证不存在或已过期；不要重复提交旧凭证，创建新订单后重新付款。'
+  },
+  PAYMENT_PROOF_STATUS_INVALID: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付凭证已失效或已被使用；请创建新订单重新付款。'
+  },
+  PAYMENT_PROOF_TRADE_NO_MISMATCH: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付凭证与交易号不匹配；不要重放该凭证，创建新订单后重新付款。'
+  },
+  TRADE_NOT_FOUND: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '支付宝找不到该交易；先查询官方钱包本地状态，未创建交易时用新订单重新发起。'
+  },
+  TRADE_NO_EMPTY: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '官方钱包未返回交易号；当前交易不可继续，请创建新订单重新发起。'
+  },
+  TRADE_NO_INVALID: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '官方钱包返回的交易号格式无效；升级官方买方组件后以新订单重试。'
+  },
+  TRADE_STATUS_CLOSED: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '该交易已关闭；不要重试旧订单，请创建新订单重新付款。'
+  },
+  TRADE_STATUS_UNPAID: {
+    stage: 'merchant_payment_proof_verification',
+    nextStep: '交易尚未完成付款；如本地有查询凭证则运行 status，否则创建新订单重新发起。'
+  },
+  SELLER_IDENTITY_MISMATCH: {
+    stage: 'merchant_fulfillment_confirmation',
+    nextStep: '已交付的 Skill 权益不会撤销；运营方应核对卖家 APPID、2088 seller_id 与交易卖方身份。'
+  },
+  SELLER_ID_EMPTY: {
+    stage: 'merchant_fulfillment_confirmation',
+    nextStep: '已交付的 Skill 权益不会撤销；运营方应检查商户应用签名与卖家身份配置。'
+  },
+  TRADE_STATUS_INVALID: {
+    stage: 'merchant_fulfillment_confirmation',
+    nextStep: '已交付的 Skill 权益不会撤销；运营方应查询支付宝交易状态后处理履约回执。'
+  }
+};
 
 export class AlipayWalletError extends Error {
   constructor(code, message, options = {}) {
@@ -230,6 +334,113 @@ function walletFailureCode(stdout, stderr, exitCode) {
   return Number.isInteger(exitCode) && exitCode !== 0 ? 'official_cli_nonzero_exit' : 'official_cli_unclassified';
 }
 
+/**
+ * The official wallet can return useful machine error codes alongside protocol
+ * material. Expose only a small allow-list: arbitrary vendor output can carry
+ * credentials, URLs, trade identifiers, or PayGuard internals.
+ */
+function safeOfficialFailureCode(stdout, stderr) {
+  const output = `${stdout}\n${stderr}`;
+  const candidates = [
+    ...output.matchAll(/(?:"(?:errorCode|code|sub_code|previous_error)"|\b(?:errorCode|code|sub_code|previous_error)\b)\s*[:=]\s*["']?([A-Z][A-Z0-9_]{2,80})/ig)
+  ].map((match) => match[1].toUpperCase());
+  return candidates.find((candidate) => SAFE_OFFICIAL_FAILURE_CODES.has(candidate)) || null;
+}
+
+/** Codes generated by XiaShe from the signed merchant verification response. */
+function safeMerchantDiagnosticCode(stdout, stderr) {
+  const output = `${stdout}\n${stderr}`;
+  const candidates = [...output.matchAll(/\b(ALIPAY_(?:VERIFY|FULFILLMENT)_[A-Z0-9_]{2,180})\b/g)]
+    .map((match) => match[1]);
+  return candidates.find((candidate) =>
+    /^ALIPAY_(?:VERIFY|FULFILLMENT)_(?:PAYMENT_PROOF_INACTIVE|(?:SYSTEM_ERROR|INVALID_PARAMETER|CLIENT_SESSION_IS_EMPTY|PAYMENT_PROOF_AGENT_MISMATCH|PAYMENT_PROOF_BUYER_MISMATCH|PAYMENT_PROOF_EMPTY|PAYMENT_PROOF_ID_MISMATCH|PAYMENT_PROOF_INVALID|PAYMENT_PROOF_NOT_FOUND|PAYMENT_PROOF_STATUS_INVALID|PAYMENT_PROOF_TRADE_NO_MISMATCH|SELLER_IDENTITY_MISMATCH|SELLER_ID_EMPTY|TRADE_NOT_FOUND|TRADE_NO_EMPTY|TRADE_NO_INVALID|TRADE_STATUS_CLOSED|TRADE_STATUS_UNPAID|TRADE_STATUS_INVALID)|GATEWAY_(?:20000|20001|40001|40002|40003|40004|40005|40006)(?:_[A-Z0-9_]{2,100})?)$/.test(candidate)
+  ) || null;
+}
+
+function paymentFailureDiagnosis(failureCode, stdout, stderr) {
+  const officialCode = safeOfficialFailureCode(stdout, stderr);
+  const merchantDiagnostic = safeMerchantDiagnosticCode(stdout, stderr);
+  const base = {
+    code: failureCode,
+    stage: 'official_wallet_trade_creation',
+    nextStep: '不要重复付款；保留诊断代码和本次 attemptId 以便定位。'
+  };
+  if (officialCode && OFFICIAL_ERROR_DIAGNOSES[officialCode]) {
+    return {
+      ...base,
+      ...OFFICIAL_ERROR_DIAGNOSES[officialCode],
+      officialCode
+    };
+  }
+  if (merchantDiagnostic) {
+    const fulfillment = merchantDiagnostic.startsWith('ALIPAY_FULFILLMENT_');
+    return {
+      ...base,
+      stage: fulfillment ? 'merchant_fulfillment_confirmation' : 'merchant_payment_proof_verification',
+      merchantDiagnostic,
+      nextStep: fulfillment
+        ? 'Skill 权益已交付；运营方应按商家验证诊断处理履约回执，买家无需重复付款。'
+        : '商家已返回支付宝验凭证诊断；不要手工补造凭证，按诊断修复后创建新订单重新付款。'
+    };
+  }
+  if (failureCode === 'payment_needed_rejected') {
+    return {
+      ...base,
+      stage: 'alipay_bill_validation',
+      nextStep: '核对支付宝平台中该 APPID 的应用公钥、service_id、收款方 2088 seller_id 和线上接入状态；修复后必须创建新订单再测试。',
+      ...(officialCode ? { officialCode } : {})
+    };
+  }
+  if (failureCode === 'wallet_runtime_not_supported') {
+    return {
+      ...base,
+      stage: 'agent_runtime_identity',
+      nextStep: '当前运行时没有通过支付宝 Agent 身份校验；请换用已被官方钱包识别并已授权的本地 Agent 运行时。',
+      ...(officialCode ? { officialCode } : {})
+    };
+  }
+  if (failureCode === 'buyer_identity_rejected') {
+    return {
+      ...base,
+      stage: 'buyer_identity_validation',
+      nextStep: '支付宝钱包的买家身份未通过校验；完成钱包授权后，用同一受支持运行时创建新订单。',
+      ...(officialCode ? { officialCode } : {})
+    };
+  }
+  if (failureCode === 'wallet_not_ready') {
+    return {
+      ...base,
+      stage: 'wallet_authorization',
+      nextStep: '支付宝钱包未完成授权或未启用；先完成官方钱包授权，再创建新订单。',
+      ...(officialCode ? { officialCode } : {})
+    };
+  }
+  if (failureCode === 'wallet_network_error') {
+    return {
+      ...base,
+      stage: 'wallet_network',
+      nextStep: '钱包或网络请求没有完成；先检查网络，再创建新订单。',
+      ...(officialCode ? { officialCode } : {})
+    };
+  }
+  return {
+    ...base,
+    ...(officialCode ? { officialCode } : {})
+  };
+}
+
+function paymentFailureUserVisible(diagnosis) {
+  const lines = [
+    '支付宝付款未创建可确认交易。',
+    `诊断代码：${diagnosis.code}`,
+    `失败阶段：${diagnosis.stage}`,
+    ...(diagnosis.officialCode ? [`官方返回代码：${diagnosis.officialCode}`] : []),
+    ...(diagnosis.merchantDiagnostic ? [`商家验证诊断：${diagnosis.merchantDiagnostic}`] : []),
+    `下一步：${diagnosis.nextStep}`
+  ];
+  return lines.join('\n');
+}
+
 function paymentMessage(status) {
   if (status === 'completed') return '支付宝钱包显示本次付款已完成；正在由服务端确认权益。';
   if (status === 'pending_confirmation') return '支付宝已发起本次付款确认；请打开支付宝 App 完成确认，然后运行 status。';
@@ -285,6 +496,7 @@ function publicPaymentResult(state, status, diagnostic, options = {}) {
   const commandFailed = options.commandFailed === true;
   const failureCode = options.failureCode || 'official_cli_nonzero_exit';
   const failed = status === 'failed' || status === 'wallet_command_failed';
+  const diagnosis = failed ? options.diagnosis : null;
   return {
     ok: !failed,
     status,
@@ -293,7 +505,8 @@ function publicPaymentResult(state, status, diagnostic, options = {}) {
     walletInvoked: true,
     message: failed ? paymentFailureMessage(failureCode) : paymentMessage(status),
     diagnostic,
-    ...(options.userVisible ? { userVisible: options.userVisible } : {}),
+    ...(failed && diagnosis ? { userVisible: paymentFailureUserVisible(diagnosis), diagnosis } : {}),
+    ...(!failed && options.userVisible ? { userVisible: options.userVisible } : {}),
     ...(options.officialMedia ? { officialMedia: options.officialMedia } : {}),
     ...(status === 'pending_confirmation'
       ? { confirmation: { source: 'official_alipay_wallet', surface: 'app_or_official_media', required: true } }
@@ -383,18 +596,25 @@ export async function payAlipay402Resource(input, options = {}) {
   const result = paymentStatusFromOutput(walletInvocation.stdout, walletInvocation.stderr);
   const commandFailed = walletInvocation.exitCode !== 0 && result.status === 'unknown';
   const status = commandFailed ? 'wallet_command_failed' : result.status;
+  const failed = commandFailed || status === 'failed';
   const officialMedia = ['pending_confirmation', 'completed'].includes(status)
     ? await officialWalletMedia(walletInvocation.stdout, walletInvocation.stderr)
     : null;
   state.status = status;
   state.queryCredential = result.credential;
+  state.lastFailureCode = failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : null;
+  state.lastDiagnosis = failed
+    ? paymentFailureDiagnosis(state.lastFailureCode, walletInvocation.stdout, walletInvocation.stderr)
+    : null;
+  state.lastWalletDiagnostic = result.diagnostic;
   state.updatedAt = new Date().toISOString();
   await writePaymentState(state, options);
   if (status === 'completed') await rm(paths.paymentNeededPath, { force: true });
-  const failed = commandFailed || status === 'failed';
+  const failureCode = failed ? state.lastFailureCode : undefined;
   return publicPaymentResult(state, status, result.diagnostic, {
     commandFailed: failed,
-    failureCode: failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : undefined,
+    failureCode,
+    diagnosis: failed ? paymentFailureDiagnosis(failureCode, walletInvocation.stdout, walletInvocation.stderr) : undefined,
     userVisible: ['pending_confirmation', 'completed'].includes(status)
       ? userVisibleWalletOutput(walletInvocation.stdout, walletInvocation.stderr)
       : null,
@@ -428,24 +648,64 @@ export async function queryAlipay402Resource(input, options = {}) {
   const result = paymentStatusFromOutput(walletInvocation.stdout, walletInvocation.stderr);
   const commandFailed = walletInvocation.exitCode !== 0 && result.status === 'unknown';
   const status = commandFailed ? 'wallet_command_failed' : result.status;
+  const failed = commandFailed || status === 'failed';
   const officialMedia = ['pending_confirmation', 'completed'].includes(status)
     ? await officialWalletMedia(walletInvocation.stdout, walletInvocation.stderr)
     : null;
   state.status = status;
   state.queryCredential = result.credential || state.queryCredential;
+  state.lastFailureCode = failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : null;
+  state.lastDiagnosis = failed
+    ? paymentFailureDiagnosis(state.lastFailureCode, walletInvocation.stdout, walletInvocation.stderr)
+    : null;
+  state.lastWalletDiagnostic = result.diagnostic;
   state.updatedAt = new Date().toISOString();
   await writePaymentState(state, options);
   if (status === 'completed') {
     const { paymentNeededPath } = statePaths(resourceUrl, options);
     await rm(paymentNeededPath, { force: true });
   }
-  const failed = commandFailed || status === 'failed';
+  const failureCode = failed ? state.lastFailureCode : undefined;
   return publicPaymentResult(state, status, result.diagnostic, {
     commandFailed: failed,
-    failureCode: failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : undefined,
+    failureCode,
+    diagnosis: failed ? paymentFailureDiagnosis(failureCode, walletInvocation.stdout, walletInvocation.stderr) : undefined,
     userVisible: ['pending_confirmation', 'completed'].includes(status)
       ? userVisibleWalletOutput(walletInvocation.stdout, walletInvocation.stderr)
       : null,
     officialMedia
   });
 }
+
+/**
+ * Read-only support output. It never invokes the wallet, replays a 402
+ * request, exposes a query credential, or returns the private protocol file.
+ */
+export async function diagnoseAlipay402Resource(input, options = {}) {
+  const resourceUrl = normalizeResourceUrl(input?.resourceUrl);
+  const state = await readPaymentState(resourceUrl, options);
+  if (!state) {
+    return {
+      ok: false,
+      status: 'no_local_attempt',
+      provider: 'alipay-agent-payment',
+      walletInvoked: false,
+      message: '没有找到本地付款尝试；请不要因此重复付款。'
+    };
+  }
+  return {
+    ok: state.status !== 'failed' && state.status !== 'wallet_command_failed',
+    status: state.status || 'unknown',
+    provider: 'alipay-agent-payment',
+    attemptId: `alipay-402:${state.resourceDigest.slice(0, 16)}`,
+    walletInvoked: state.status !== 'started',
+    queryAvailable: Boolean(state.queryCredential?.value),
+    diagnostic: state.lastWalletDiagnostic || 'payment_state_recorded',
+    ...(state.lastFailureCode ? { failureCode: state.lastFailureCode } : {}),
+    ...(state.lastDiagnosis ? {
+      diagnosis: state.lastDiagnosis,
+      userVisible: paymentFailureUserVisible(state.lastDiagnosis)
+    } : {}),
+    updatedAt: state.updatedAt || null
+  };
+}

package/index.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { ConvexHttpClient } from 'convex/browser';
 import { anyApi as api } from 'convex/server';
 
-export const VERSION = '0.1.17';
+export const VERSION = '0.1.19';
 
 export const DEFAULTS = {
   cn: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/sdk",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "type": "module",
   "main": "index.mjs",
   "exports": {