@xiashe/cli 0.1.22 → 0.1.24

package/README.md

@@ -48,11 +48,11 @@ Production defaults:
 
 `xiashe payment` is the shell-capable Agent path for Alipay AI Pay. It delegates only to the official local `alipay-bot` supplied by `@alipay/agent-payment`; it does not implement or expose `Payment-Needed` / `Payment-Proof` itself.
 
-- `xiashe payment bridge-info` checks that the official buyer CLI is available without querying the wallet. `payment doctor` remains a manual diagnostic only.
+- `xiashe payment bridge-info` checks only that the official buyer CLI can run. It does not check wallet authorization, merchant activation, or whether a transaction can be created. `payment doctor` remains a manual wallet-status diagnostic only.
 - `xiashe payment pay` requests the resource once, saves its exact 402 request in a private local file, and passes that file plus one stable session id to the official buyer CLI. It requires an HTTPS AI-Collect resource URL, a visible purchase-purpose summary, and `--confirm`.
 - `xiashe payment status` resumes the same local attempt with its official query credential and returns a normalized status only. No wallet protocol payload or proof is printed. A QR or confirmation image is exposed only as `officialMedia` when the official wallet emitted that image in the same invocation; the bridge never generates one itself.
-- `xiashe payment diagnose` is read-only. It reports the last stored safe diagnosis for that local attempt, without contacting Alipay, replaying the resource, or exposing its local query credential.
+- `xiashe payment preflight` requests the seller resource once and validates the public field shape of its 402 bill without opening a wallet or creating a trade. It does not prove that Alipay accepts the seller signature, service binding, or merchant activation. `xiashe payment diagnose` is read-only. It reports the last stored safe diagnosis for that local attempt, including allow-listed official error/sub-codes, message, and request/trace identifiers when present, without contacting Alipay, replaying the resource, or exposing its local query credential.
 
 An Agent must never add `--confirm` before the user has explicitly agreed to the displayed purpose. If the wallet is unavailable, obtain permission before running the official `@alipay/agent-payment` setup, then run `payment doctor` again.
 
-For a clean Codex Task, the XiaShe MCP response provides a version-pinned ephemeral command such as `npx -y @xiashe/cli@0.1.22 payment bridge-info`. No global `xiashe` installation is required for that path. The Agent must run the subsequent payment and status commands exactly as supplied, in the foreground: it must inspect the bridge JSON instead of suppressing output or guessing status from shell text. Failed attempts include a redacted `diagnosis` object and `userVisible` next step; do not replace them with a generic payment-failed message.
+For a clean Codex Task, the XiaShe MCP response provides a version-pinned ephemeral command such as `npx -y @xiashe/cli@0.1.24 payment bridge-info`. No global `xiashe` installation is required for that path. Run the supplied preflight command before requesting payment confirmation, then run the payment and status commands exactly as supplied in the foreground. The Agent must inspect bridge JSON instead of suppressing output or guessing status from shell text. Failed attempts include a redacted `diagnosis` object and `userVisible` next step; do not replace them with a generic payment-failed message.

package/bin/xiashe.mjs

@@ -37,6 +37,7 @@ const {
   nowIso,
   checkAlipayWallet,
   getAlipayWalletBridgeInfo,
+  preflightAlipay402Resource,
   payAlipay402Resource,
   queryAlipay402Resource,
   diagnoseAlipay402Resource
@@ -98,6 +99,7 @@ Usage:
   ${c} files list
 
   ${c} payment bridge-info|doctor
+  ${c} payment preflight --resource-url <https-url>
   ${c} payment pay --resource-url <https-url> --intent-summary <text> --confirm [--wallet-timeout-ms <ms>]
   ${c} payment status --resource-url <https-url>
   ${c} payment diagnose --resource-url <https-url>
@@ -1165,6 +1167,12 @@ async function cmdPayment(sub, args, global) {
     print(result, global);
     return;
   }
+  if (sub === 'preflight') {
+    const resourceUrl = requireArg(flags['resource-url'] || flags.resourceUrl || flags.r, '--resource-url');
+    const result = await preflightAlipay402Resource({ resourceUrl }, { timeoutMs: global.timeoutMs });
+    print(result, global);
+    return;
+  }
   if (sub === 'pay') {
     const resourceUrl = requireArg(flags['resource-url'] || flags.resourceUrl || flags.r, '--resource-url');
     const intentSummary = requireArg(flags['intent-summary'] || flags.intentSummary || flags.i, '--intent-summary');
@@ -1188,7 +1196,7 @@ async function cmdPayment(sub, args, global) {
     print(result, global);
     return;
   }
-  fail(`Usage: ${COMMAND_NAME} payment bridge-info|doctor|pay|status|diagnose`, EXIT_USAGE);
+  fail(`Usage: ${COMMAND_NAME} payment bridge-info|doctor|preflight|pay|status|diagnose`, EXIT_USAGE);
 }
 
 async function cmdOps(sub, args, global) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "bin": {
     "xiashe": "bin/xiashe.mjs"
@@ -10,7 +10,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@xiashe/sdk": "0.1.22"
+    "@xiashe/sdk": "0.1.24"
   },
   "engines": {
     "node": ">=20"