双色球一注生成（支付宝 A2M 付费技能）

0. 变更记录

1. 能力、触发与边界

业务链路：用户说「来一注双色球」→ 技能取 402 出账 → 用户完成 0.01 元付款 →
技能查询订单状态 → 服务端回传资源体（含 pick_token）→ 技能端用固定算法派生号码并展示。

其中「用户完成付款」是全链路唯一由人完成的动作：技能把收银台交出去之后，用
有界自动等待（§3.1）盯住这一单，用户一付款就立刻出号；等满上限仍未到账则退回人工触发。
注意：等待期间不会重复发起支付，所以「超时」只意味着「本轮结束」，不意味着订单作废。

2. 依赖与环境

3. 调用方法（照官方 402 六步骨架，不另造）

下文 <SKILL_DIR> 指技能加载时返回的 base directory。

第 1 步 · 取 402 出账（原始请求，不重写业务语义）

node "<SKILL_DIR>/scripts/fetch-402.js" \
  --method GET \
  --expect-amount-fen 1

• 默认打生产资源地址。该地址不在本文档里写字面值，硬编码在
  scripts/fetch-402.js 的 DEFAULT_RESOURCE_URL；GET，无 body、无自定义 header。
• 下文命令里的 <RESOURCE_URL> 是一个占位符，取值方式（按优先级）：
  1. 第 1 步输出 JSON 里的 resource_url 字段——首选，直接原样取用；
  2. 或读 scripts/fetch-402.js 的 DEFAULT_RESOURCE_URL。
  不要手抄、不要凭记忆拼写：文档里的字面值会随服务端迁移而漂移，输出字段才是权威。
• 固定走本脚本而不是 curl：生产站只开 TLS 1.3，Windows Schannel 不支持 TLS 1.3，
  curl 会报 schannel: failed to receive handshake；Node 自带 TLS 栈可正常握手。
• 环境变量 SSQ_RESOURCE_URL 可覆盖资源地址，但只在指向本机（127.0.0.1/localhost/::1）
  时生效，其他主机一律忽略并回落生产地址 —— 防误配把请求打到别处。
• Payment-Needed 的值是支付凭证：脚本只落盘、绝不打印，输出里只有 secret_file 路径与
  secret_fingerprint（长度 + 摘要前 16 位）。目录 0700、文件 0600。

第 2 步 · 校验 402

读脚本输出 JSON：

• ok: true 且 channel: "payment-needed" → 继续第 3 步（--file 分支）。
• channel: "amt-payment-link" → 继续第 3 步（--amt-payment-link 分支，按协议不写文件）。
• ok: false 或 errors 非空 → 原样告知用户并 STOP，尤其当 errors 含
  「金额不一致」时：说明服务端出账金额与技能声明的 1 分没拉平，此时不得发起付款。

第 3 步 · 发起支付（官方 CLI，技能端不自己实现）

从运行时元数据解析 sessionId（优先级：sessionId → session_id → threadId/thread_id
→ conversationId/conversation_id → agentContextId → CODEBUDDY_SESSION_ID →
CLAUDE_SESSION_ID → CODEX_THREAD_ID → AIPAY_SESSION_ID）。
可先自查：node "<SKILL_DIR>/scripts/a2m.js" session --session-id '<值>'。
全部为空时 STOP 并说明「运行时未提供当前会话标识」——不生成、不猜测、不向用户索取。

> 注意（2026-09-18 实测）：WorkBuddy 运行时只提供 CODEBUDDY_SESSION_ID（兼容别名
> CLAUDE_SESSION_ID），不提供 CODEX_THREAD_ID / AIPAY_SESSION_ID。解析链里若缺
> CODEBUDDY_SESSION_ID 这一项，自动解析必然返回 ok:false，技能会在第 3 步直接 STOP、
> 永远走不到付款。新增环境名时务必同步 test/selftest.js 的 S5–S7 断言。

# Payment-Needed 分支
alipay-bot 402-buyer-pay \
  --session-id '<sessionId>' \
  --file '<第 1 步的 secret_file>' \
  --resource-url '<RESOURCE_URL>' \
  --method GET \
  --intent-summary '原始请求：为用户生成一注双色球号码'

# amtPaymentLink 分支（仅在 channel 为 amt-payment-link 时）
alipay-bot 402-buyer-pay \
  --session-id '<sessionId>' \
  --amt-payment-link '<第 1 步响应头原值>' \
  --resource-url '<RESOURCE_URL>' \
  --method GET \
  --intent-summary '原始请求：为用户生成一注双色球号码'

• --intent-summary 保留原始业务目的（生成一注双色球），不写 URL 或「支付」二字。
• --resource-url 永远是资源地址，不是支付链接。
• 发起前不重新请求资源；不要复用历史 402 文件（服务端会轮换 challenge）。
• 联调/演示开关：当运行环境设置了 SSQ_DRY_RUN=1 时，不要执行第 3 步，改为把将要执行的
  完整命令原样打印一次并 STOP（这一步的自动化实现就是
  node "<SKILL_DIR>/test/verify-402-stop-before-pay.js" --session-id '<id>'，它跑完 402 处理
  的全部动作后停在付款确认前）。未设置该变量时才真正调用 CLI。

第 4 步 · 输出收款信息，然后进入有界自动等待

CLI 命令待确认时，把对客结果原样输出一次（订单号、支付方式链接逐字符保留）。
二维码/收银台必须先展示给用户（present_files 传二维码图片，或输出 CLI 给的链接），
再启动下面的自动等待——顺序反了用户根本看不到码，等于白等一轮。

记录对客标签备用：

3.1 有界自动等待（紧接第 4 步，默认开启）

# 必须显式给 tool 传 timeout ≥ max-wait + 30s，否则会被工具默认超时（120s）打断
node "<SKILL_DIR>/scripts/wait-pay.js" \
  --out-shake-no '<订单号>' \
  --interval 30 \
  --max-wait 300

行为约定：

• 每 --interval 秒查询同一订单（默认 30，最小 1——不许高频打生产查单接口）。
• 查到 status=success 就立刻派生号码并交付；text 与手动路径逐字同口径（§5），
  默认就是那一行「双色球：…，祝你中大奖！！」，原样发给用户即可。
• 等满 --max-wait 秒（默认 300，硬上限 540）仍未到账 → 输出超时说明并结束本轮，
  文案里必须带「不要重新发起支付」。
• 只调用 402-query-payment-status：子命令与参数由 wait-pay.js 固定拼装，
  不接受外部注入、不重取 402、不复用历史凭证。
• 命令固定带 --output json（CLI 的全局开关），走结构化通道取资源体；
  若某些版本不吃这个开关，解析层会自动回退到「Markdown + 末尾 JSON 块」的文本通道。
• 「未付款」只能靠信封的 status 字段判定，不能靠文本正则（2026-09-19 生产实测）：
  真实未付款信封是 { active:false, resourceDelivered:false, status:"payment_unconfirmed", success:true, tradeNo } —— 里面没有任何中文「未支付」标记，而且 success 仍是 true。
  判定顺序为：资源体 → 信封 status → 文本标记；已登记的 pending 取值还带正则兜底。
  因此「success:true 就当作已付款」是错误读法，会直接把未付款误判成成功。
• 退出码不能当成败判据：真实 CLI 在「已履约、不重复提供」时返回 success:false
  且进程退出码为 1，但资源体依然完整可用（2026-09-19 生产实测）。因此判定一律以
  输出内容为准，且只有 spawn 级失败才计入连续失败（§6）。

退出码与处理：

参数与运行约束：

用户随时可以插话：付款后直接说「已付款 / 继续 / 查询」即走第 5 步，不必等自动等待结束。
SSQ_DRY_RUN=1 时同样不执行自动等待（它属于付款后的动作）。

第 5 步 · 用户表示已支付 → 查询同一订单

用户说「已支付 / 付好了 / 完成 / 搞定 / 继续 / 查询」时：

alipay-bot 402-query-payment-status \
  --out-shake-no '<订单号>' \
  --resource-url '<RESOURCE_URL>' \
  --method GET
# 只有交易号时：--trade-no '<交易号>'（并带上 --resource-url / --method）

状态不明时先查单，不要重新发起支付、不要重取 402。
若本轮自动等待（§3.1）已经交付过号码，用户再说「已付款」时不必重查——直接复述同一份
text 即可（凭证台账保证同一订单号码不变，重查也只是重复同一条结果）。
自动等待超时后用户才说「已付款」的，就用上面这条命令走正常路径，无需再次付款。

第 6 步 · 校验资源体并渲染号码

把查询输出的 JSON 存到会话目录，再交给渲染器：

node "<SKILL_DIR>/scripts/a2m.js" render \
  --resource "$HOME/.ssq-create/session/resource.json" \
  --order-no '<订单号>'

退出码即结论，直接照它分支，不要自己猜：

• 资源体的 content 字段是字符串形式的 JSON，渲染器会二次解析；解析失败一律拒绝渲染。
• 取到非空资源后官方 CLI 已自动发送履约回执，成功路径不追加独立回执、不重复查询。
• 仅当同一次输出明确提示「履约回执发送失败」且用户在后续消息要求恢复时，才执行一次
  alipay-bot 402-buyer-fulfillment-ack --trade-no '<同次输出的交易号>'。

可选开关（只在排查/联调时用，日常不加）：

4. 号码由技能端确定性派生（幂等的关键）

A2M 要求「同一订单重试返回同一份资源」，而本产品把号码生成放在技能端（服务端只当收款闸门）。
若让模型"随机想"一组号码，同一订单两次查询就会得到不同结果，幂等性直接崩掉。因此：

1. 服务端在履约时签发 pick_token（32 字节随机 hex），与订单一起持久化，同一订单只签发一次；
   资源体里同时带 pick_algorithm: "ssq-v1"。
2. 技能端用 scripts/derive.js 的固定算法展开 token，禁止模型口算随机数：

每轮用 4 字节而非 1 字节：1 字节取模时 256 % (i+1) ≠ 0（如 256 % 33 = 25）会让部分下标
出现概率高约 12%，实测 5000 次抽样红球最大偏移 9.25%；改 4 字节后偏差降到 1e-8 量级。
服务端若自实现洗牌，必须与此一致。

3. 于是服务端不存号码也能保证幂等，技能端"生成"了号码，双方还能各自复算对账。

node "<SKILL_DIR>/scripts/derive.js" <pick_token>
# {"algorithm":"ssq-v1","red":[11,12,22,26,28,33],"blue":1,"token_fingerprint":"..."}
node "<SKILL_DIR>/scripts/derive.js" --selftest 20000   # 稳定性/合法性/覆盖度/分布自检

4.1 凭证来源裁决顺序（token_source）

渲染器按固定顺序裁决用哪张凭证，不允许模型自行挑选：

服务端优先对新订单始终成立；台账只对已经交付、号码已对客可见的订单生效。

4.2 本地兜底凭证（服务端未签发 pick_token 时）

背景：2026-09-19 实测生产站履约返回的是 demo 占位体，content 里既无 pick_token
也无 pick_algorithm，导致渲染器退出码 2、无法交付。为打通闭环，技能端提供兜底：

凭证 = sha256("ssq-local-v1:" + source + ":" + 订单标识)   // 64 位 hex，32 字节
source ∈ { out_trade_no, trade_no }，订单号优先，缺失才回退交易号

• 仍是纯函数：同一订单在任何机器、任何时刻都复算出同一组号码，无需服务端存号码。
• 不是"随便编一个号"：凭证由订单标识确定性派生，可复算、可对账。
• 加 ssq-local-v1: 前缀，使兜底派生与服务端随机 token 在算法上不可能相撞，两套来源始终可区分。
• 两个标识都没有 → 报错（DERIVE_LOCAL_BASIS_MISSING），绝不凭空生成。
• 兜底来源写在结构化输出（token_source / local_basis）与凭证台账里；对客文本默认只有一行号码（§5），排查时用 --details 取完整行。
• 每次兜底都会在 warnings 里留下 basis 与凭证指纹，便于排查与对账。
• 服务端联调验收想确认「是否真的签发了凭证」时，加 --require-server-token 让兜底失效。

4.3 凭证台账（粘性，防止老订单换号）

台账每完成一次交付就把本次实际使用的凭证按订单落盘：

~/.ssq-create/ledger/<订单标识>.json     # 目录 0700 / 文件 0600，可用 SSQ_LEDGER_DIR 覆盖
{ out_trade_no, trade_no, token, token_source, token_fingerprint, algorithm, local_basis, recorded_at }

为什么必须有它：今天用兜底发的号码，等服务端补上 pick_token 后查同一订单，
凭证一变、号码就变 —— 已交付的客户会看到自己的号码被改掉，这在幂等语义下是明确缺陷。
台账命中即锁定原凭证，优先于服务端本次签发的值，于是：

• 新订单 → 走服务端 pick_token；
• 已交付的老订单 → 沿用首次交付的凭证，号码永不改变。

边界：台账不存号码（只存凭证，号码仍靠 derive 复算）；订单标识做白名单校验防路径穿越
（^[A-Za-z0-9_.:-]{1,64}$ 且不含 ..）；读写失败/内容损坏一律降级为 warning + 按未命中处理，
绝不阻断对客交付，同时把原因写进 warnings 以免"号码莫名换了却无从排查"。

5. 展示格式

付费提示（第 1 步取到 402 后，用服务端返回的值展示，不要用本地常量覆盖）：

双色球 · 生成一注
本次需支付：0.01 CNY
商品：AI 生成内容服务
订单号：ORDER_...

成功交付（kind: ticket 的 text）——固定为一行纯文本：

双色球：11 12 22 26 28 33 + 01，祝你中大奖！！

• 照抄这一行即可，不要加标题、解释、结语或前后缀；+ 前是 6 个红球（升序、两位补零），
  + 后是蓝球（两位补零）。
• 必须是纯文本：不得改成图片、二维码、卡片或 Markdown 表格——用户要能直接选中整行复制。
• 服务端凭证与本地兜底共用这一个格式（不再区分对客呈现）；来源信息改记在结构化输出
  （token_source / local_basis）与凭证台账里。
• 排查、对账或联调需要订单号与来源标注时，在命令上加 --details（等价 SSQ_TICKET_DETAILS=1）：

双色球：13 14 15 23 25 33 + 10，祝你中大奖！！
订单号：ORDER_...
凭证来源：本地兜底（服务端未签发 pick_token）
号码由订单凭证按固定算法确定性派生，同一订单重复查询结果一致。

details 模式首行仍是同一号码行（便于整行复制），运维行只是追加；对客交付默认不加。
两个入口都支持：a2m.js render --details、wait-pay.js --details。

6. 异常处理

原样透传的边界：CLI 的任何对客结果在整轮只输出一次，不加标题、解释、结论或后续引导；
只执行本文件与官方 402 文档列出的子命令。

7. 安全边界（硬性）

• Payment-Needed、Payment-Proof、Authorization、Set-Cookie 一律不进日志、不进对话；
  对外只允许出现长度 + 摘要指纹。
• 凭证文件仅当前用户可读（目录 0700 / 文件 0600），用后不跨订单复用。
• 密钥、.env、商户私钥、支付宝公钥不由本技能持有，全部在服务端；本技能包内不得出现。
• 不构造官方 CLI 未公开的命令（如退款），不把不可信值当命令或路径片段。
• 自动等待（wait-pay.js）只允许 402-query-payment-status：子命令与参数位由常量拼装，
  订单标识只走 --out-shake-no / --trade-no 的值位，任何来自资源体或用户输入的字符串
  都不得进入子命令位置；脚本不接收外部注入的命令。
• 自动等待期间不接触任何支付凭证（Payment-Proof 由官方 CLI 自行管理），
  也因此不需要、也不会读 session/*.needed。
• 凭证台账（~/.ssq-create/ledger/）只存凭证与订单标识，不存号码、不含任何支付凭据；
  目录 0700 / 文件 0600。台账键必须过白名单校验后才拼路径，不得把资源体里的字符串直接当路径。
• 本地兜底凭证由订单标识派生，属于可复算的确定性值而非机密；但仍按内部数据对待，
  对外只出现摘要指纹，不把完整 token 打进对话。

7.1 文档脱敏规则（写文档时必守）

本技能包会整包分发/发布，SKILL.md 与 scripts/、test/ 里的注释与字面值都算公开内容。
写文档时以下内容一律不得出现，必须改写为占位符或按位置描述：

代码里的功能必需值（如 fetch-402.js 的默认资源地址）不属此列——删了技能不可用；
但也只在代码常量里出现一次，文档不得重复抄写，避免文档与代码漂移后互相矛盾。

8. 安装 / 运行 / 本地加载 / 打包

8.1 安装（装入 WorkBuddy 技能目录）

# 用户级技能目录，装完所有项目都能用
cp -r <本目录> ~/.workbuddy/skills/ssq-create
ls ~/.workbuddy/skills/ssq-create/SKILL.md

8.2 运行

cd ~/.workbuddy/skills/ssq-create
node scripts/derive.js --selftest 20000        # 派生算法自检
node test/selftest.js                          # 八场景离线自测（160 项断言）
node test/mock-a2m-server.js --port 0          # 单独拉起本地 mock 服务端
node test/verify-402-stop-before-pay.js --session-id '<id>'   # 停在付款确认前
node scripts/fetch-402.js --method GET --expect-amount-fen 1 # 取真实 402（会打生产）

# 有界自动等待（第 4 步出码后调用；只查询，绝不发起支付）
node scripts/wait-pay.js --out-shake-no '<订单号>' --interval 30 --max-wait 300
node scripts/wait-pay.js --trade-no '<交易号>' --interval 30 --max-wait 300
node scripts/wait-pay.js --help

验证兜底路径（不需服务端配合，用 mock 的 pay-no-token 状态）：

# 起 mock 并把状态切到「支付成功但未签发 pick_token」，然后渲染即可看到兜底输出
node -e "const {createMockServer}=require('./test/mock-a2m-server');\
const m=createMockServer({amountFen:1});m.start(0).then(b=>{\
m.setState('pay-no-token');\
console.log(b+m.RESOURCE_PATH+'?out_trade_no=ORDER_DEMO');})"

# 渲染真实资源体（凭证台账默认落在 ~/.ssq-create/ledger）
node scripts/a2m.js render --resource <资源体.json> --order-no ORDER_DEMO

离线验证自动等待（不用真钱包、不用真服务端）：

# 1) 起 mock 当资源站；2) 用测试替身冒充 alipay-bot；
# 3) 替身在「查询两次之后」才回报已付款 —— 验证命中即出号
SSQ_ALIPAY_BOT=./test/fake-alipay-bot.js \
FAKE_DIR=/tmp/ssq-fake FAKE_MODE=unpaid-then-paid:2 \
SSQ_RESOURCE_URL='http://127.0.0.1:<mock端口>/demo/a2m/resource' \
node scripts/wait-pay.js --out-shake-no ORDER_DEMO --interval 1 --max-wait 10 --immediate
# FAKE_MODE 可选：unpaid / unpaid-then-paid:<n> / processing-then-paid:<n> /
#                 fail / invalid-order / weird / call-error / already-delivered-no-body
# <n> = 前 n 次查询回报未付款，第 n+1 次起回报已付款（n=0 即首次就付款）

也可以 npm run selftest / npm run verify / npm run mock / npm run wait -- --out-shake-no <订单号>
（package.json 里已配好）。

8.3 本地加载

把技能目录放进 ~/.workbuddy/skills/<name>/ 后，当轮会话内即可用 Skill 工具加载并触发
（返回的 base directory 即新装入的目录），无需重启会话。正式对外发布前再确认新会话可见性。

8.4 打包（Windows 上无 zip 命令，故用纯 Node 实现）

cd ~/.workbuddy/skills/ssq-create
node scripts/pack.js                       # 输出到 ../ssq-create-<package.json 的 version>.zip
node scripts/pack.js --out D:/tmp/ssq.zip  # 指定输出
node scripts/pack.js --list <zip 路径>     # 只列清单 + 扫描已有包

scripts/pack.js 用 Node 内置 zlib.deflateRawSync 直接写标准 ZIP（deflate + CRC32），
不依赖任何外部命令（本机 Git Bash 没有 zip；PowerShell 5.1 读无 BOM 的 UTF-8 脚本会
让中文乱码，从 Bash 里调 PowerShell 又被安全策略拦掉）。规则是白名单而非黑名单：
只收 SKILL.md、package.json、.gitignore、scripts/、test/，其余从源头就进不来。
之后还有三道关：

1. 防御性剔除：任何路径含 node_modules/session/state/logs 或文件名形如 .env*、
   *.pem、*.key、*.needed、*.state、*.log 的条目一律拒绝，命中即报错退出；
2. 内容扫描：对包内文本文件匹配私钥头、支付宝公钥字段名、应用私钥字段名、2088 开头的
   13 位商户号、JWT 前缀（扫描脚本自身的特征字面量已拆分拼接，避免自命中；全零占位商户号
   已列入安全白名单）；
3. 回读校验：重新解析归档的中央目录、逐条解压、再扫一遍，证明落盘产物同样干净。

绝不进包：node_modules/、.env 及其变体、任何 *.pem/*.key、支付宝配置文件、
状态文件（session/、ledger/、*.needed、*.state、*.log）。
真正的拦截机制是 pack.js 的白名单（只收 SKILL.md、package.json、.gitignore、
scripts/、test/）+ 三道关（防御性剔除 → 内容扫描 → 回读复扫），
不依赖 .gitignore（本目录当前也没有该文件；若日后补上，它只是额外一层，白名单仍是主护栏）。
运行时的 402 凭证写在 ~/.ssq-create/session/、凭证台账写在 ~/.ssq-create/ledger/，
都在技能目录之外，从位置上就进不了包。
注意区分：scripts/ledger.js 是代码，属于技能包；
它运行时读写的 ~/.ssq-create/ledger/ 数据目录不属于技能包。

9. 上线前必须补齐的真实配置