@alipay/alipay-aipay 1.7.9 → 1.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/package.json +3 -3
  2. package/skill/SKILL.md +34 -3
  3. package/skill/VERSION +1 -1
  4. package/skill/references/integration/flow.md +2 -0
  5. package/skill/references/integration/modules/checklist.md +4 -2
  6. package/skill/references/integration/modules/code-examples/csharp/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.md +3 -1
  7. package/skill/references/integration/modules/code-examples/java/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemoController.md +3 -1
  8. package/skill/references/integration/modules/code-examples/nodejs/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.md +6 -2
  9. package/skill/references/integration/modules/code-examples/php/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.md +3 -1
  10. package/skill/references/integration/modules/code-examples/python/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.md +8 -3
  11. package/skill/references/integration/modules/interface-contract/aipay-interface-contract.md +3 -1
  12. package/skill/references/integration/modules/interface-contract/apppay-interface-contract.md +3 -3
  13. package/skill/references/integration/modules/interface-contract/common-trade-contract.md +8 -8
  14. package/skill/references/integration/modules/interface-contract/notify-url-contract.md +7 -7
  15. package/skill/references/integration/modules/interface-contract/webpay-interface-contract.md +2 -2
  16. package/skill/references/integration/modules/sandbox/a2m-sandbox-test.md +4 -4
  17. package/skill/references/normal/conversation-telemetry.md +103 -0
  18. package/skill/references/normal/json/customer-messages.json +1 -1
  19. package/skill/references/normal/scripts/conversation_consent.mjs +76 -0
  20. package/skill/references/normal/scripts/conversation_telemetry.mjs +200 -0
  21. package/skill/references/normal/scripts/render_customer_message.mjs +2 -0
  22. package/skill/references/normal/scripts/runtime.mjs +1 -0
  23. package/skill/references/normal/scripts/telemetry.mjs +618 -74
  24. package/skill/references/runtime-entry.md +7 -1
  25. package/skill-pre/VERSION +1 -1
  26. package/skill-pre/references/integration/flow.md +7 -3
  27. package/skill-pre/references/integration/modules/checklist.md +4 -2
  28. package/skill-pre/references/integration/modules/code-examples/csharp/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.md +3 -1
  29. package/skill-pre/references/integration/modules/code-examples/java/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemoController.md +3 -1
  30. package/skill-pre/references/integration/modules/code-examples/nodejs/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.md +6 -2
  31. package/skill-pre/references/integration/modules/code-examples/php/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.md +3 -1
  32. package/skill-pre/references/integration/modules/code-examples/python/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.md +8 -3
  33. package/skill-pre/references/integration/modules/interface-contract/aipay-interface-contract.md +3 -1
  34. package/skill-pre/references/integration/modules/interface-contract/apppay-interface-contract.md +3 -3
  35. package/skill-pre/references/integration/modules/interface-contract/common-trade-contract.md +8 -8
  36. package/skill-pre/references/integration/modules/interface-contract/notify-url-contract.md +7 -7
  37. package/skill-pre/references/integration/modules/interface-contract/webpay-interface-contract.md +2 -2
  38. package/skill-pre/references/integration/modules/sandbox/a2m-sandbox-test.md +4 -4
  39. package/skill-pre/references/integration/modules/sandbox/sandbox-setup-guide.md +2 -2
  40. package/skill-pre/references/normal/conversation-telemetry.md +9 -9
  41. package/skill-pre/references/normal/full-process-routing.md +2 -2
  42. package/skill-pre/references/normal/scripts/conversation_telemetry.mjs +113 -18
  43. package/skill-pre/references/normal/scripts/telemetry.mjs +243 -32
  44. package/skill-pre/references/normal/windows-environment.md +4 -4
  45. package/skill-pre/references/runtime-entry.md +2 -2
@@ -52,7 +52,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" telemetry resolve-sessi
52
52
 
53
53
  从首条 bootstrap/start-run 起,本文件及所有 flow 登记的每条 runtime 命令均追加 `--agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"`,将两个占位符分别替换为当前工具名称和根入口已取得的同一会话 ID;不使用环境变量前缀,不依赖前一次工具调用的进程环境。gateway 在业务参数解析前剥离此公共参数,规范化后传给当前进程及子进程。业务 CLI 的 `PLATFORM` 和遥测 Yuyan `d2` 优先使用本次命令的 Agent 宿名,只有该值为 `unknown` 或非法时才检查当前进程的宿主自动识别信号;继承的通用平台变量只能作为末级兼容值。这样即使进程同时残留其他宿主的 session/thread 环境变量,也不得遮蔽本次 runtime 明确提供的当前宿主。所有来源中的 `unknown` 或非法值都继续回退,不得提前终止识别。该兜底不使用宿主名称枚举或映射表:纯 ASCII 名称统一小写并去除空格、下划线和连字符,合法 Unicode 名称保留可读原文;无法安全规范化仍为 `unknown`。该参数不改变业务确认、run_id、PLATFORM_ID 或模型字段。
54
54
 
55
- 根 `SKILL.md` 启动器已经在读取本文件前确定本轮有效版本,并完成本对话所需的首次 `env refresh-alipay-cli` 或命中同路径、同版本的成功刷新事实。运行时禁止再次执行自更新、读取 `normal/self-update.md` 或切换其他副本;成功事实仍有效时不重复刷新 CLI,只按原始请求识别根意图并加载入口:
55
+ 根 `SKILL.md` 启动器已经在读取本文件前确定本轮有效版本,并完成本对话的采集说明及明确选择(同意采集或仅使用服务),以及本对话所需的首次 `env refresh-alipay-cli` 或命中同路径、同版本的成功刷新事实。运行时禁止再次执行自更新、读取 `normal/self-update.md` 或切换其他副本;成功事实仍有效时不重复刷新 CLI,只按原始请求识别根意图并加载入口:
56
56
 
57
57
  | 意图 | 判定 | 入口 | 后续按需加载 |
58
58
  |---|---|---|---|
@@ -70,6 +70,12 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" telemetry resolve-sessi
70
70
 
71
71
  遥测默认开启。`ALIPAY_AIPAY_TELEMETRY=0|false|off|no` 时不计数,不生成 event/c4/进度,不读写 outbox/status,不上传、不启动 worker、不 flush;只允许保留 `PLATFORM_ID <- run_id` 所需的最小私有 run context。失败静默,不改变业务、消息、确认或卡点,内部 marker 不对客。`integration_only` 由 `integration_summary` 终结;`onboarding_only` 由 `onboarding_summary` 终结;`full_process` 由 `all_summary` 终结,`full_process` 的 `integration_summary` 只是中间 event。每个 stage 先在 run state 固定唯一 event,再写 outbox并同步上传,网络硬超时 3 秒;失败保留原 event 后才尝试 detached worker,绝不延迟重算 c4。补传细节见 `normal/telemetry.md`。
72
72
 
73
+ 对话采集在用户明确同意后,以触发 Skill 的那条用户消息为起点,按原始顺序补采授权前的完整对话(含采集说明、澄清往来等助手收口消息),每条只采集一次、不重复采集,使用独立的 `conversation_id`,不携带或关联业务 `run_id`。对话遥测环境开关默认可用,但实际采集还必须取得当前会话的明确同意;`ALIPAY_AIPAY_CONVERSATION_TELEMETRY=0|false|off|no` 时只停用对话采集,不影响阶段遥测。阶段遥测继续使用 code=1005;对话遥测默认使用独立 code=1008,可由 `ALIPAY_AIPAY_CONVERSATION_CODE` 覆盖,非法值或与 1005 相同则停用对话采集。
74
+
75
+ 当前会话已明确同意、全局遥测开启且对话 code 有效时,读取 `normal/conversation-telemetry.md` 的采集规则。每轮采集本轮用户消息,以及阻塞式对客消息和最终收口助手回复;过程输出、工具结果和非阻塞阶段消息跳过。用户消息先执行原有 `count-user-input`,再采集。助手消息必须在发送前采集,采集副本仅替换随后发送正文中的凭证和个人信息,其余文字与格式保持一致;不得为满足逐字一致而上传敏感原文。
76
+
77
+ 运行时命令使用 `$CONVERSATION_ID` 和 `$RUN_ID` 作为 Shell 变量;协议字段统一写为 `conversation_id` 和 `run_id`。对话采集不关联业务 run,不上传工具输出、system 消息、隐藏推理或附件内容。任务完成、明确取消或退出时,先采集最终回复,再执行 `telemetry end-conversation`。采集失败静默,不阻断 Skill。
78
+
73
79
  用户输入计数是入口前置职责,只从 `clarify_intent` 之后开始,到当前 `run_id` 的 `summary` 收口为止。当前 active run 期间,聊天框里**每收到一条用户消息都必须先计一次**,再做任何 Skill 相关或非 Skill 相关处理;计数不按是否与 Skill 流程强相关筛选。只要是用户在 Agent 对话框发送的消息,就按一条计,不计宿主/系统/网页授权、扫码、Skill stage、runner、工具调用或自动轮询。文字、图片/文件、空白/短确认、材料补充、确认回复和中途插话都按一条用户消息计;同一条消息含文字和图片/文件仍只计一条。`USER_INPUT_ID` 是当前 active run 内用户消息的本地幂等键:Agent 给每条新用户消息分配对话内单调序号,同一消息重试复用同一值。`USER_INPUT_ID` 不得包含或派生自用户输入内容、文件名、路径、截图/OCR、业务材料、stage 名或工具调用序号;运行时只保存其本地 hash,不上报。
74
80
 
75
81
  `start-run` 的 `clarify_intent` 开始生成后计数器为 0,直到当前 run 最终 summary 到达。Agent 每收到一条聊天框用户消息,都必须先分配不含消息内容的 `USER_INPUT_ID`,执行 `node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" telemetry count-user-input --run-id "$RUN_ID" --input-id "$USER_INPUT_ID" --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"`,再解释、分类、路由、调用 runner/tool 或回复;不论消息是否与 Skill 相关,文字、图片/文件、空白、确认、中途插话和打断后输入都执行。同一消息重试复用同一 ID,runtime 只保存 `run_id + USER_INPUT_ID` hash。无 active run、缺少/错误 run ID 或 run 已关闭时成功 no-op。runner、recovery、renderer、交互回复、tool call/result 和 stage 禁止隐式计数;它们保留的业务 `--input-id` 也不是计数兜底。宿主总入口不在仓库内,因此这是 Agent 收到消息后必须遵循的唯一显式计数动作,不增加用户操作。
package/skill-pre/VERSION CHANGED
@@ -1 +1 @@
1
- 1.7.8-pre
1
+ 1.8.0-pre
@@ -1,7 +1,7 @@
1
1
  <!-- ALIPAY_AIPAY_FLOW:INTEGRATION_CORE:START -->
2
2
  # 支付产品-代码开发流程
3
3
 
4
- 本 flow 的 Windows READY/LEGACY/CODE_ONLY 指根入口的唯一兼容环境分流事实,或 Windows 环境文档明确修复后唯一、根意图匹配的新 READY 事实;BLOCKED 停在环境恢复点,不进入本 flow。后续命令附加当前有效的 `--windows-route`。Windows READY 通过 Git Bash 执行登记的快速沙箱脚本;Windows LEGACY/CODE_ONLY 保留原 Node 独立开发和手工沙箱分支。三者都由当前 Agent 串行执行,不启用 Integration Worker。Windows 沙箱项目配置不要求精确 NTFS ACL 白名单;仍校验字段、项目实际加载路径及防误提交。登录凭据与生产配置沿各自动作的保护规则处理。CODE_ONLY 允许 `integration_only/full_process` 在可选工具故障时继续代码开发,沙箱保持 `VERIFY_PENDING`;完整接入完成代码部分后停在开通前,不把 CODE_ONLY 用于 Onboarding。根意图变化必须重跑 Windows 入口。
4
+ 本 flow 的 Windows READY/LEGACY/CODE_ONLY 指根入口的唯一兼容环境分流事实,或 Windows 环境文档明确修复后唯一、根意图匹配的新 READY 事实;BLOCKED 停在环境恢复点,不进入本 flow。后续命令附加当前有效的 `--windows-route`。Windows READY 通过 Git Bash 执行登记的快速沙箱脚本;Windows LEGACY/CODE_ONLY 保留原 Node 独立开发和手工沙箱分支。三者都由当前 Agent 串行执行,不启用 Integration Worker。Windows 沙箱项目配置不要求精确 NTFS ACL 白名单;仍校验字段、项目实际加载路径及防误提交。登录凭据与生产配置沿各自动作的保护规则处理。CODE_ONLY 允许 `integration_only/full_process` 在可选工具故障时继续代码开发,沙箱默认 `VERIFY_PENDING`,用户主动提供完整有效手工资料并完成项目配置校验后可记 `READY`;配置就绪不改变环境分流,各测试仍须满足自身实际依赖。完整接入完成代码部分后停在开通前,不把 CODE_ONLY 用于 Onboarding。根意图变化必须重跑 Windows 入口。
5
5
 
6
6
  > ⚠️ **前置声明**:本 flow 仅支持 **AI 网页应用收款、AI 移动应用收款、AI 按量付费**三种产品的集成。原有“网站支付”“APP 支付”“按量付费”仍作为输入别名和资源目录名。**其他产品(当面付、订单码支付、JSAPI支付、预授权支付、商家扣款等)暂不支持**,如需集成请前往[支付宝开放平台](https://open.alipay.com/)查阅相关文档。
7
7
 
@@ -144,7 +144,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message loc
144
144
  - [INT.ENV.PROJECT_LANGUAGE_READY] 已确认唯一目标项目路径和服务端语言,且目标项目包含已确认语言的构建标识
145
145
  - [INT.SANDBOX.OS_DETECTED] 已检测用户操作系统类型
146
146
  - [INT.SANDBOX.PREPARATION_RECORDED] Unix/macOS/Linux 或 Windows READY 已从固定脚本取得唯一 `READY|CREATE_PENDING|VERIFY_PENDING` 终态。`READY` 时配置已安全落盘或复核;待配置不是成功,不满足任何沙箱配置、测试或生产就绪条件,但本步骤允许继续产品确认和代码开发
147
- - [INT.SANDBOX.WINDOWS_STATE_RECORDED] Windows LEGACY/CODE_ONLY:本轮既有标准消息后提供的完整有效沙箱资料已写入并校验为 `READY`;未进入该资料收集分支时已记录 `VERIFY_PENDING` 并继续代码实现;只有用户明确要求立即配置时才使用既有标准消息收集资料
147
+ - [INT.SANDBOX.WINDOWS_STATE_RECORDED] Windows LEGACY/CODE_ONLY:本轮用户主动提供或既有标准消息后提供的完整有效沙箱资料已写入并校验为 `READY`;没有完整有效资料时记录 `VERIFY_PENDING` 并继续代码实现;只有用户明确要求立即配置时才使用既有标准消息收集资料
148
148
 
149
149
  **执行规则**:
150
150
 
@@ -156,7 +156,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message loc
156
156
  node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" sandbox ensure "<规范化项目路径>" "<已确认服务端语言>" [--telemetry-run-id "$RUN_ID" --telemetry-history-count "$HISTORY_COUNT"] --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
157
157
  ```
158
158
 
159
- 4. Windows LEGACY/CODE_ONLY 不调用快速沙箱脚本。普通代码开发或完整接入请求没有明确要求当前配置沙箱时,不展示申领消息、不补问,直接记录 `sandboxConfigState=VERIFY_PENDING` 并继续步骤 2。只有用户明确要求现在配置/恢复沙箱时才执行下列既有标准消息 `sandbox.windows.manual_setup`;该消息使用自由资料回复,不要求用户输入 `1` 或自行执行脚本。随后只处理用户针对本轮该消息提供的资料:完整有效时写入目标项目实际使用的本机配置并记录 `READY`,部分或错误时使用既有受控失败分支补问实际缺失/错误字段:
159
+ 4. Windows LEGACY/CODE_ONLY 不调用快速沙箱脚本。普通代码开发或完整接入请求没有明确要求当前配置沙箱且未主动提供资料时,不展示申领消息、不补问,直接记录 `sandboxConfigState=VERIFY_PENDING` 并继续步骤 2。用户主动提供本轮目标项目的完整有效手工沙箱资料时,直接校验并写入目标项目实际使用的本机配置,记录 `READY`,无需再次展示申领消息;该状态只证明配置就绪,不将 `CODE_ONLY` 改为环境 `READY`。只有用户明确要求现在配置/恢复沙箱时才执行下列既有标准消息 `sandbox.windows.manual_setup`;该消息使用自由资料回复,不要求用户输入 `1` 或自行执行脚本。主动资料不完整或无效时不使用字段、不记 `READY`,沿用既有受控失败分支只补问实际缺失/错误字段;资料校验通过后继续:
160
160
 
161
161
  ```bash
162
162
  node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message windows-sandbox-setup --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
@@ -423,6 +423,8 @@ Windows LEGACY/CODE_ONLY 的 `CONFIG_PATH` 必须是步骤 1/3 已校验的实
423
423
 
424
424
  **任务**:验证按量付费 402 协议端到端服务端联调流程
425
425
 
426
+ Windows `CODE_ONLY` 下手工沙箱配置为 `READY` 时,按本动作实际依赖判断可执行性;不因缺少 Git Bash 单独跳过原生 Python 402 联调,仍须 Python、curl、服务可访问及本步骤全部前置就绪。缺失工具所依赖的动作列为未完成,不据此调用快速沙箱或进入 Onboarding。
427
+
426
428
  > ⚠️ **必须完整阅读** `modules/sandbox/a2m-sandbox-test.md` 后方可执行本步骤
427
429
  >
428
430
  > 沙箱联调经验集中维护在 `modules/sandbox/a2m-sandbox-test.md`。遇到收银接口临时失败、`ORDER_NOT_FOUND`、资源防串失败或履约确认失败时,先按该文档排查,不要反复请求用户服务生成新订单。
@@ -559,6 +561,8 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message saf
559
561
 
560
562
  > 详细校验清单已附在当前阶段 bundle 的“当前产品适用校验清单”。
561
563
 
564
+ **验收阶段边界**:本轮代码开发按沙箱集成验收;checklist 第七节中尚未开通产品或尚未取得、切换生产实值的检查,记为当前阶段不适用并保留上线前待办,不计入失败项或人工待验证项,不单独阻止 Onboarding。仍须检查生产配置加载边界、环境隔离和所有适用代码/安全控制;已发现的实现缺陷、泄露或环境混用仍是阻断缺口。不得为完成本轮检查索取生产私钥、提前改用生产配置或宣称生产就绪。
565
+
562
566
  **校验完整性要求**:内部必须覆盖当前 bundle 中适用于目标产品的密钥与安全、异步通知、接口覆盖、支付结果处理、按量付费专项、退款、上线前和结果输出章节,不得只检查上方三个摘要项。通过时默认对客只输出通过结论和下一步;部分通过或未通过时只输出实际未完成项、人工待验证项和下一步。步骤 5/6 已展示的沙箱配置、联调或付款体验结论不在 checklist 结果中重复。通过项与不适用项无需逐行展开,用户要求明细时再输出完整逐项结果。精简输出不得导致任何适用校验被跳过。
563
567
 
564
568
  先汇总 checklist 证据;本轮可修复时先修复、重检,不渲染中间结果。项目快照变化会使旧 `CHECKLIST_SCOPE_RECEIPT` 失效,必须重新加载本阶段并重跑受影响检查。
@@ -80,11 +80,11 @@
80
80
  | Payment-Proof 验证 | 收到 `Payment-Proof` 后必须调用 `alipay.aipay.agent.payment.verify` | 验证成功只代表支付宝凭证有效,不代表本地订单已完成校验 |
81
81
  | 本地订单匹配 | 验付成功后必须查询本地订单并校验状态 | 防止凭证有效但商户订单不存在、过期或状态异常 |
82
82
  | 资源防串 | 必须校验本地订单的 `resource_id` 与验付结果/请求资源一致 | 防止用户通过篡改资源标识获取其他资源 |
83
- | 金额一致性 | 必须校验本地订单金额与 `Payment-Needed` 账单金额和服务定价一致;若验付接口返回金额字段,再校验实际支付金额 | 防止金额篡改或错误定价 |
83
+ | 金额一致性 | 商家服务端必须校验本地持久化订单金额与 `Payment-Needed` 账单金额和服务定价一致;验付返回非空金额时必须与本地订单匹配。仅精确沙箱模式(沙箱 SDK 网关且 `serviceId=api_mock_service_id`)缺金额时允许使用本地订单金额继续判断;生产缺金额必须拒绝交付 | 按本地接口契约核对商家代码;自动联调脚本不直接比较验付金额与本地订单金额,通过结果不能替代此项审查 |
84
84
  | 幂等履约 | 同一订单重复携带 `Payment-Proof` 时不得重复发放资源 | 应返回历史履约结果或可重试确认结果 |
85
85
  | 履约确认 | 资源生成后必须调用 `alipay.aipay.agent.fulfillment.confirm` | 确认成功后再标记订单 `FULFILLED` 并返回成功交付 |
86
86
  | 自动联调成功证据 | 必须同时具备 HTTP 200、非空 `resource_id` / `resourceId`、非空 `content`、无明确业务失败,以及当前五语言示例有效的 `Payment-Validation` | 204、空体、空对象、`VERIFY_FAILED`、履约失败或异常响应头均不得判为通过 |
87
- | 敏感过程产物 | 单次联调仅使用本次临时目录,Unix/macOS/Linux 的目录/文件权限不得宽于 `0700/0600`;Windows 检查实际可写和非符号链接,不以 ACL 白名单为完成条件;命令结束时立即清理 | 禁止打印 Payment-Proof 或 Payment-Validation 原始值;失败后重新执行完整联调 |
87
+ | 敏感过程产物 | 单次联调仅使用本次临时目录,Unix/macOS/Linux 的目录/文件权限不得宽于 `0700/0600`;Windows 检查实际可写和非符号链接,不以 ACL 白名单为完成条件;命令结束时立即清理 | 禁止打印 Payment-Proof 或 Payment-Validation 原始值;失败或中断后按 flow 的执行 guard 判定,不得无变化重跑或自动重放结果未知的请求 |
88
88
  | 沙箱 serviceId | 沙箱联调的 `serviceId` 固定为 `api_mock_service_id` | 不向用户索要正式 `serviceId`,不使用其他占位符 |
89
89
  | 沙箱空字段边界 | 沙箱联调中字段为空可用于排查定位,生产环境关键字段为空必须按异常处理 | 不得把沙箱容错逻辑直接迁移成生产跳过校验 |
90
90
  | 生产实现完整性 | 订单持久化、本地订单匹配、金额一致性、资源防串、幂等履约、待确认状态和确认失败重试均已实际实现 | 任一关键控制仍为 TODO、注释、内存演示或伪代码时只能判定沙箱演示可测试,不得判定生产就绪 |
@@ -107,6 +107,8 @@
107
107
  <!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay,webpay,apppay -->
108
108
  ## 七、上线前校验
109
109
 
110
+ 本节区分当前代码开发验收与生产上线验收。沙箱代码开发阶段检查生产配置加载边界、沙箱/生产隔离及适用安全控制;尚未开通产品、尚未取得生产 APPID/密钥/真实 serviceId 或尚未切换生产网关,记录为上线前待办,相应生产实值检查记为“当前阶段不适用”,不计入 `failedItems`、`manualItems` 或 `blockingDefectState`,不单独阻止继续 Onboarding。沿用既有上线提醒交付这些要求,不索取生产私钥、不提前切换配置。代码缺陷、密钥泄露、环境混用等安全问题仍须修复;已有生产配置也须检查其适用保护。实际生产上线验收必须满足本节全部适用项,否则不得宣称生产就绪。
111
+
110
112
  | 校验项 | 校验要求 | 说明 |
111
113
  |----------|----------|----------|
112
114
  | 网关地址切换 | 五语言 A2M 示例默认沙箱网关为 `https://openapi-sandbox.dl.alipaydev.com/gateway.do`;上线时显式切换为 `https://openapi.alipay.com/gateway.do` | 禁止把生产网关复制进沙箱运行配置 |
@@ -2,13 +2,15 @@
2
2
 
3
3
  以下代码展示严格验付和幂等履约的完整控制流。生成项目代码时,请按当前项目结构拆分并绑定真实持久化实现。
4
4
 
5
+ 金额校验由商家服务端执行:验付返回非空金额时必须与本地持久化订单匹配;仅 SDK 网关严格为 `https://openapi-sandbox.dl.alipaydev.com/gateway.do` 且 `serviceId=api_mock_service_id` 的精确沙箱模式下,验付缺少金额才允许使用本地订单金额继续判断。生产缺少金额必须拒绝交付。自动沙箱联调脚本不直接比较这两个金额,脚本通过不能代替商家代码校验。
6
+
5
7
  ```csharp
6
8
  /*
7
9
  * A2M 智能收产品接入示例 - C# 版本
8
10
  *
9
11
  * 本示例展示 A2M 核心协议、严格验付和幂等履约流程。
10
12
  * 必须通过 ConfigureOrderRepository 绑定项目真实持久化实现;端口未绑定时明确失败,
11
- * 不使用内存订单、固定资源或验付字段缺失兜底。
13
+ * 不使用内存订单或固定资源;生产环境不使用验付字段缺失兜底。
12
14
  *
13
15
  * 本文件演示 A2M 核心协议调用流程:
14
16
  * 1. 返回 402 Payment-Needed Header
@@ -2,6 +2,8 @@
2
2
 
3
3
  以下代码展示严格验付和幂等履约的完整控制流。生成项目代码时,请按当前项目结构拆分并绑定真实持久化实现。
4
4
 
5
+ 金额校验由商家服务端执行:验付返回非空金额时必须与本地持久化订单匹配;仅 SDK 网关严格为 `https://openapi-sandbox.dl.alipaydev.com/gateway.do` 且 `serviceId=api_mock_service_id` 的精确沙箱模式下,验付缺少金额才允许使用本地订单金额继续判断。生产缺少金额必须拒绝交付。自动沙箱联调脚本不直接比较这两个金额,脚本通过不能代替商家代码校验。
6
+
5
7
  ```java
6
8
  /*
7
9
  * Copyright (C) 2015-2026 Ant Group
@@ -21,7 +23,7 @@
21
23
  /*
22
24
  * 本示例展示 A2M 核心协议、严格验付和幂等履约流程。
23
25
  * 必须通过 OrderRepository 绑定项目真实持久化实现;端口未绑定时明确失败,
24
- * 不使用内存订单、固定资源或验付字段缺失兜底。
26
+ * 不使用内存订单或固定资源;生产环境不使用验付字段缺失兜底。
25
27
  */
26
28
  package com.alipay.aipayweb.demo;
27
29
 
@@ -2,13 +2,15 @@
2
2
 
3
3
  以下代码展示严格验付和幂等履约的完整控制流。生成项目代码时,请按当前项目结构拆分并绑定真实持久化实现。
4
4
 
5
+ 金额校验由商家服务端执行:验付返回非空金额时必须与本地持久化订单匹配;仅 SDK 网关严格为 `https://openapi-sandbox.dl.alipaydev.com/gateway.do` 且 `serviceId=api_mock_service_id` 的精确沙箱模式下,验付缺少金额才允许使用本地订单金额继续判断。生产缺少金额必须拒绝交付。自动沙箱联调脚本不直接比较这两个金额,脚本通过不能代替商家代码校验。
6
+
5
7
  ```javascript
6
8
  /**
7
9
  * A2M 智能收产品接入示例 - Node.js 版本
8
10
  *
9
11
  * 本示例展示 A2M 核心协议、严格验付和幂等履约流程。
10
12
  * 必须通过 configureOrderRepository 绑定项目真实持久化实现;
11
- * 端口未绑定时明确失败,不使用内存订单、固定资源或验付字段缺失兜底。
13
+ * 端口未绑定时明确失败,不使用内存订单或固定资源;生产环境不使用验付字段缺失兜底。
12
14
  *
13
15
  * 本文件演示 A2M 核心协议调用流程:
14
16
  * 1. 返回 402 Payment-Needed Header
@@ -161,6 +163,7 @@ function base64UrlDecode(str) {
161
163
  }
162
164
 
163
165
  function normalizeAmount(value) {
166
+ if (typeof value !== 'string' && typeof value !== 'number') return null;
164
167
  const match = /^(\d+)(?:\.(\d{1,2}))?$/.exec(String(value ?? '').trim());
165
168
  if (!match) return null;
166
169
  return `${BigInt(match[1]).toString()}.${(match[2] || '').padEnd(2, '0')}`;
@@ -345,7 +348,8 @@ async function verifyPaymentAndDeliverResource(req, res, paymentProof) {
345
348
  const order = verifyOutTradeNo ? await repository.findByOutTradeNo(verifyOutTradeNo) : null;
346
349
  const sandboxMode = isExactSandboxMode();
347
350
  const verifyTradeNo = returnedTradeNo || (sandboxMode ? tradeNo : '');
348
- const verifyAmount = returnedAmount || (sandboxMode && order ? order.amount : '');
351
+ const amountMissing = returnedAmount === undefined || returnedAmount === null || returnedAmount === '';
352
+ const verifyAmount = amountMissing && sandboxMode && order ? order.amount : returnedAmount;
349
353
  const resourceIdVerified = returnedResourceId || (sandboxMode && order ? order.resourceId : '');
350
354
 
351
355
  if (process.env.A2M_DEBUG === 'true') {
@@ -2,6 +2,8 @@
2
2
 
3
3
  以下代码展示严格验付和幂等履约的完整控制流。生成项目代码时,请按当前项目结构拆分并绑定真实持久化实现。
4
4
 
5
+ 金额校验由商家服务端执行:验付返回非空金额时必须与本地持久化订单匹配;仅 SDK 网关严格为 `https://openapi-sandbox.dl.alipaydev.com/gateway.do` 且 `serviceId=api_mock_service_id` 的精确沙箱模式下,验付缺少金额才允许使用本地订单金额继续判断。生产缺少金额必须拒绝交付。自动沙箱联调脚本不直接比较这两个金额,脚本通过不能代替商家代码校验。
6
+
5
7
  ```php
6
8
  <?php
7
9
  /**
@@ -9,7 +11,7 @@
9
11
  *
10
12
  * 本示例展示 A2M 核心协议、严格验付和幂等履约流程。
11
13
  * 必须通过 configureOrderRepository 绑定项目真实持久化实现;
12
- * 端口未绑定时明确失败,不使用内存订单、固定资源或验付字段缺失兜底。
14
+ * 端口未绑定时明确失败,不使用内存订单或固定资源;生产环境不使用验付字段缺失兜底。
13
15
  * 订单快照将支付状态映射为 PENDING_PAYMENT/PAID,
14
16
  * 将履约状态映射为 UNFULFILLED/PENDING_CONFIRM/FULFILLED。
15
17
  *
@@ -2,6 +2,8 @@
2
2
 
3
3
  以下代码展示严格验付和幂等履约的完整控制流。生成项目代码时,请按当前项目结构拆分并绑定真实持久化实现。
4
4
 
5
+ 金额校验由商家服务端执行:验付返回非空金额时必须与本地持久化订单匹配;仅 SDK 网关严格为 `https://openapi-sandbox.dl.alipaydev.com/gateway.do` 且 `serviceId=api_mock_service_id` 的精确沙箱模式下,验付缺少金额才允许使用本地订单金额继续判断。生产缺少金额必须拒绝交付。自动沙箱联调脚本不直接比较这两个金额,脚本通过不能代替商家代码校验。
6
+
5
7
  ```python
6
8
  #!/usr/bin/env python3
7
9
  # -*- coding: utf-8 -*-
@@ -10,7 +12,7 @@ A2M 智能收产品接入示例 - Python 版本
10
12
 
11
13
  本示例展示 A2M 核心协议、严格验付和幂等履约流程。
12
14
  必须通过 configure_order_repository 绑定项目真实持久化实现;
13
- 端口未绑定时明确失败,不使用内存订单、固定资源或验付字段缺失兜底。
15
+ 端口未绑定时明确失败,不使用内存订单或固定资源;生产环境不使用验付字段缺失兜底。
14
16
 
15
17
  本文件演示 A2M 核心协议调用流程:
16
18
  1. 返回 402 Payment-Needed Header
@@ -167,7 +169,9 @@ def base64url_decode(data):
167
169
 
168
170
 
169
171
  def normalize_amount(value):
170
- text = str(value or '').strip()
172
+ if isinstance(value, bool) or not isinstance(value, (str, int, float, Decimal)):
173
+ return None
174
+ text = str(value).strip()
171
175
  if not re.fullmatch(r'\d+(?:\.\d{1,2})?', text):
172
176
  return None
173
177
  return f'{Decimal(text):.2f}'
@@ -381,7 +385,8 @@ def verify_payment_and_deliver_resource(payment_proof):
381
385
  order = repository.find_by_out_trade_no(verify_out_trade_no) if verify_out_trade_no else None
382
386
  sandbox_mode = is_exact_sandbox_mode()
383
387
  verify_trade_no = returned_trade_no or (trade_no if sandbox_mode else '')
384
- verify_amount = returned_amount or (order.get('amount') if sandbox_mode and order else '')
388
+ amount_missing = returned_amount is None or returned_amount == ''
389
+ verify_amount = order.get('amount') if amount_missing and sandbox_mode and order else returned_amount
385
390
  resource_id_verified = returned_resource_id or (order.get('resource_id') if sandbox_mode and order else '')
386
391
 
387
392
  print(f"支付凭证验证成功:tradeNo={verify_trade_no}, outTradeNo={verify_out_trade_no}")
@@ -39,7 +39,7 @@ AI 按量付费只实现 HTTP 402、`Payment-Needed`、`Payment-Proof`、`alipay
39
39
  验付成功不能只看 SDK 调用成功,还必须同时校验:
40
40
 
41
41
  - `active=true`。
42
- - 返回 `amount` 等于本地订单金额。
42
+ - 返回非空 `amount` 时,必须与本地持久化订单金额一致;金额不匹配或格式非法时拒绝交付。仅在精确沙箱模式(SDK 网关严格为 `https://openapi-sandbox.dl.alipaydev.com/gateway.do` 且 `serviceId=api_mock_service_id`)下,验付响应缺少金额时允许使用本地持久化订单金额继续判断;生产环境缺少金额必须拒绝交付,不能使用该回退。
43
43
  - 返回 `out_trade_no` 等于本地订单号。
44
44
  - 返回 `resource_id` 等于当前请求资源。
45
45
  - `trade_no` 未被重复履约。
@@ -47,6 +47,8 @@ AI 按量付费只实现 HTTP 402、`Payment-Needed`、`Payment-Proof`、`alipay
47
47
 
48
48
  任一校验失败时返回 402,让智能体重新支付;不得返回资源。
49
49
 
50
+ 上述金额判断由商家服务端实现。自动沙箱联调脚本从商家返回的 `Payment-Needed` 读取并传递金额,不直接比较验付响应金额与本地订单金额;脚本通过不能替代商家金额校验的代码审查。
51
+
50
52
  ## 履约确认
51
53
 
52
54
  资源生成后调用 `alipay.aipay.agent.fulfillment.confirm`,业务入参只有 `trade_no`。必须在履约确认成功后再把订单标记为最终完成。确认失败时允许同一 `Payment-Proof` 重试确认,避免资源已生成但平台未记录履约。
@@ -4,9 +4,9 @@
4
4
 
5
5
  sourceUrl:
6
6
 
7
- - <https://aipay.alipay.com/docs/mobile-app-pay/app-pay-integration-guide-new.md>
8
- - <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-app-pay.md>
9
- - <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/sync-result.md>
7
+ - <https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/app-pay-integration-guide-new.md>
8
+ - <https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-app-pay.md>
9
+ - <https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/sync-result.md>
10
10
 
11
11
  ## 默认范围
12
12
 
@@ -4,14 +4,14 @@
4
4
 
5
5
  sourceUrl:
6
6
 
7
- - <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-query.md>
8
- - <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-refund.md>
9
- - <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-fastpay-refund-query.md>
10
- - <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-close.md>
11
- - <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-query.md>
12
- - <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-refund.md>
13
- - <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-fastpay-refund-query.md>
14
- - <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-close.md>
7
+ - <https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-query.md>
8
+ - <https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-refund.md>
9
+ - <https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-fastpay-refund-query.md>
10
+ - <https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-close.md>
11
+ - <https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-query.md>
12
+ - <https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-refund.md>
13
+ - <https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-fastpay-refund-query.md>
14
+ - <https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-close.md>
15
15
 
16
16
  网页应用付款和移动应用收款的查询、退款、退款查询、关闭文档当前内容一致,本 Skill 本地维护一份通用契约。
17
17
 
@@ -4,8 +4,8 @@
4
4
 
5
5
  sourceUrl:
6
6
 
7
- - <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/async-notify-verify.md>
8
- - <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/async-notify-verify.md>
7
+ - <https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/async-notify-verify.md>
8
+ - <https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/async-notify-verify.md>
9
9
 
10
10
  当前两份官方文档内容一致。运行时默认读取本文和当前语言 `1-通用接口/异步通知处理代码示例.md`;在线文档只在 fallback 条件下读取。
11
11
 
@@ -59,10 +59,10 @@ sourceUrl:
59
59
 
60
60
  | 语言 | 示例 |
61
61
  | --- | --- |
62
- | Java | `code-examples/java/1-通用接口/异步通知处理代码示例.md` |
63
- | Python | `code-examples/python/1-通用接口/异步通知处理代码示例.md` |
64
- | Node.js | `code-examples/nodejs/1-通用接口/异步通知处理代码示例.md` |
65
- | PHP | `code-examples/php/1-通用接口/异步通知处理代码示例.md` |
66
- | C# | `code-examples/csharp/1-通用接口/异步通知处理代码示例.md` |
62
+ | Java | `../code-examples/java/1-通用接口/异步通知处理代码示例.md` |
63
+ | Python | `../code-examples/python/1-通用接口/异步通知处理代码示例.md` |
64
+ | Node.js | `../code-examples/nodejs/1-通用接口/异步通知处理代码示例.md` |
65
+ | PHP | `../code-examples/php/1-通用接口/异步通知处理代码示例.md` |
66
+ | C# | `../code-examples/csharp/1-通用接口/异步通知处理代码示例.md` |
67
67
 
68
68
  Java 官方示例明确使用 `AlipaySignature.rsaCheckV1`。Node.js 示例给出 `checkNotifySignV2(params)` 的落地形态,但 Agent 落地前必须先读取目标项目 `alipay-sdk` 的 package.json 和类型定义,确认当前版本确实暴露该 API。Python、PHP、C# 示例使用项目内支付宝 SDK 验签适配器表示验签边界;适配器必须封装当前项目实际 SDK API,禁止临时手写不确定的 RSA 验签实现。
@@ -4,8 +4,8 @@
4
4
 
5
5
  sourceUrl:
6
6
 
7
- - <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/ai-web-app-payment-integration-guide.md>
8
- - <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-page-pay.md>
7
+ - <https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/ai-web-app-payment-integration-guide.md>
8
+ - <https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-page-pay.md>
9
9
 
10
10
  ## 默认范围
11
11
 
@@ -123,7 +123,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE
123
123
  8. 生成浏览器付款链接
124
124
  9. 使用同一过程产物构建 Payment-Proof 并重试原始服务
125
125
  10. 仅在 HTTP 200、非空且可归属的资源、无明确业务失败,并且当前示例要求的 `Payment-Validation` 校验通过时输出服务端联调成功
126
- 11. 命令结束前清理敏感过程产物;失败后重新执行完整联调,不保存跨轮恢复状态
126
+ 11. 命令结束前清理敏感过程产物,不保存跨轮恢复状态;失败或中断后必须重新按执行 guard 判定,不得直接重跑
127
127
 
128
128
  **脚本输出**:
129
129
  - Payment-Needed 获取结果(终端不输出原始值)
@@ -134,7 +134,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE
134
134
  - Payment-Proof 重试后的服务响应与测试结论;`Payment-Validation` 原始值不在终端输出
135
135
 
136
136
  **错误处理**:
137
- - 沙箱化 Agent 环境执行本脚本时,首次执行即申请可联网权限;如果已因网络受限失败,复用同一条命令申请可联网权限重试
137
+ - 沙箱化 Agent 环境执行本脚本时,首次执行即申请可联网权限;权限恢复只允许原样重试可确认尚未发出的命令。命令可能已发出时仍按执行 guard 处理,不以网络恢复为由重放结果未知的请求
138
138
  - 如果未找到 `Payment-Needed` 响应头,确认服务端是否实现了 402 协议
139
139
  - 如果收银接口返回 `PARAM_INVALID: protocol.sellerSignature不能为空`,回到预检步骤检查 `protocol.seller_signature` 是否为空、缺失或仍是占位符
140
140
  - 如果 `pay_before` 相关参数报错,检查是否使用 ISO 8601 带时区格式
@@ -142,7 +142,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE
142
142
 
143
143
  ### 第三步:连续验证 Payment-Proof 重试
144
144
 
145
- 标准流程只使用第二步命令中的 `--auto-complete`。脚本生成付款链接后,在同一次进程内继续构建 Payment-Proof、重试原始服务并输出结果;进程中断后重新执行完整联调。
145
+ 标准流程只使用第二步命令中的 `--auto-complete`。脚本生成付款链接后,在同一次进程内继续构建 Payment-Proof、重试原始服务并输出结果;进程中断后按执行 guard 处理,结果未知时不得自动重新执行完整联调。
146
146
 
147
147
  **脚本执行步骤**:
148
148
  1. 读取过程产物目录中的 `state.json`
@@ -154,7 +154,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" a2m run --url "$SERVICE
154
154
  **Payment-Proof 处理约束**:
155
155
  - `trade_no` 必须使用前面沙箱收银接口返回并写入 `state.json` 的交易号;不得改用商户侧 `out_trade_no` 或重新生成。
156
156
  - `payment_proof`、`client_session` 和最终请求头由脚本按沙箱联调约定自动处理;Agent 不得手工拼接、改写或向用户展开其原始值和内部处理规则。
157
- - 进程中断后只能在确认上次命令未取得可用过程产物时重新执行完整 `run --auto-complete` 联调,不复用旧过程产物;明确业务失败、服务实现失败或脚本已输出失败结论时,禁止立即重复执行同一联调命令刷远程动作,必须先处理失败原因。
157
+ - 进程中断后,不得以过程产物缺失或已清理推定请求未发出;`UNKNOWN_PREVIOUS_EXECUTION` 固定记录结果未知,禁止自动重跑。明确业务失败、服务实现失败或脚本已输出失败结论时,禁止立即重复执行同一联调命令;输入未变化时按 `BLOCK_UNCHANGED` 停止;只有代码、配置、URL、方法或 POST body 实际变化且 guard 返回新 `RUN` 时,才允许重新发起完整联调,禁止复用旧过程产物。
158
158
 
159
159
  Payment-Proof 参考结构:
160
160
 
@@ -14,7 +14,7 @@
14
14
  ### 1.2 Windows LEGACY/CODE_ONLY 用户注意事项
15
15
  Windows READY 通过兼容层执行 flow 登记的快速沙箱;下述手工分支适用于 Windows LEGACY/CODE_ONLY;CODE_ONLY 只放行代码开发,不代表站点开通选择。Windows 沙箱项目配置不要求精确 NTFS ACL 白名单,配置是否可用仍由字段校验、实际项目加载路径和防误提交检查决定。
16
16
 
17
- Windows LEGACY/CODE_ONLY 普通代码开发或完整接入请求未明确要求当前配置沙箱时,记录 `sandboxConfigState=VERIFY_PENDING` 并继续代码实现,不展示资料收集消息。只有用户明确要求现在配置或恢复 Windows LEGACY/CODE_ONLY 沙箱时,才使用 `../../../normal/json/customer-messages.json` 的既有 `sandbox.windows.manual_setup`,引导用户前往支付宝 AI 付站点的“选择产品 → 一站式接入 → 技术集成”页面获取当前沙箱的 APPID、公私钥和账号信息;随后只处理用户针对本轮该消息提供的资料,完整时校验并写入目标项目实际使用的本地沙箱配置,部分或错误时只补问对应字段。不得要求用户自行配置、理解 `sandbox_config.sh`、执行 Bash 或手工拼接 Skill 的规范化 JSON。该资料输入例外只适用于沙箱,生产环境应用私钥和密码禁止提供给 Agent;Agent 不得在回复、摘要或普通日志中复述收到的值。
17
+ Windows LEGACY/CODE_ONLY 普通代码开发或完整接入请求未明确要求当前配置沙箱且未主动提供资料时,记录 `sandboxConfigState=VERIFY_PENDING` 并继续代码实现,不展示资料收集消息。用户主动提供本轮目标项目的完整有效手工沙箱资料时,直接校验并写入项目实际使用的本地沙箱配置,记录沙箱 `READY`,无需再次展示资料收集消息。只有用户明确要求现在配置或恢复 Windows LEGACY/CODE_ONLY 沙箱时,才使用 `../../../normal/json/customer-messages.json` 的既有 `sandbox.windows.manual_setup`,引导用户前往支付宝 AI 付站点的“选择产品 → 一站式接入 → 技术集成”页面获取当前沙箱的 APPID、公私钥和账号信息。主动提供或本轮消息后提供的资料均须校验;部分或错误时不使用无效字段、不记 `READY`,只补问实际缺失或错误字段。沙箱 `READY` 只证明配置就绪,不改变 `CODE_ONLY` 环境分流;测试按自身实际依赖执行,不调用快速沙箱,Skill 内产品开通仍须环境 `READY`。不得要求用户自行配置、理解 `sandbox_config.sh`、执行 Bash 或手工拼接 Skill 的规范化 JSON。该资料输入例外只适用于沙箱,生产环境应用私钥和密码禁止提供给 Agent;Agent 不得在回复、摘要或普通日志中复述收到的值。
18
18
 
19
19
  ```bash
20
20
  node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message windows-sandbox-setup --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"
@@ -65,7 +65,7 @@ Windows LEGACY/CODE_ONLY 手工沙箱:
65
65
 
66
66
  1. 没有资料且没有明确配置请求时记录 `VERIFY_PENDING` 并继续代码实现,不渲染消息、不探测猜测配置。
67
67
  2. 用户明确要求配置且尚未提供资料时,才使用标准消息一次收集当前沙箱应用的 APPID、支付宝公钥、应用公钥、与已确认语言匹配的应用私钥和沙箱账号信息;缺失或校验失败时只补问对应字段。
68
- 3. 按第 4 节校验资料,随后由 Agent 写入目标项目实际使用的本地沙箱配置;不要求采用快速沙箱 `data` 的嵌套结构,不把值复制到源码或普通日志。
68
+ 3. 用户主动提供或本轮标准消息后提供的资料均按第 4 节校验;完整有效时由 Agent 写入目标项目实际使用的本地沙箱配置并记录沙箱 `READY`,已有完整有效资料时不重复索取。部分或错误时不使用无效字段、不记 `READY`,只补问实际缺失或错误字段。不要求采用快速沙箱 `data` 的嵌套结构,不把值复制到源码或普通日志。
69
69
  4. 检查沙箱配置未被 Git 跟踪,并已有适用于实际路径的版本控制忽略保护;不因项目目录继承额外 Windows ACL 权限而阻断沙箱配置。
70
70
  5. 只有 `READY` 时才输出第 5 节规定的摘要和 Windows LEGACY/CODE_ONLY 提醒并从实际本机配置映射到 SDK;Agent 不得在回复或摘要中复述用户提供的沙箱密钥和密码,生产环境应用私钥和密码禁止提供给 Agent。
71
71
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## 开关与范围
4
4
 
5
- 对话遥测环境开关默认可用,实际采集必须先取得当前宿主会话的明确同意,可用独立开关 `ALIPAY_AIPAY_CONVERSATION_TELEMETRY=0|false|off|no` 关闭;未设置或为其他值时保持开启。该开关只关闭对话采集,不影响阶段遥测。默认 code 见下方上报字段表。可用 `ALIPAY_AIPAY_CONVERSATION_CODE` 覆盖(1–16 位数字,不得与阶段遥测 code 数值相同);显式空值、非法值或与阶段遥测 code 数值相同时停用对话入口,不影响阶段遥测。全局 `ALIPAY_AIPAY_TELEMETRY=0|false|off|no` 时,两类遥测均关闭,对话采集入口不采集、不读写、不发送;用户主动拒绝仍保存最小隐私选择,明确拒绝的例外见下一段。每条保留 d1~d5,c1 为 conversation_id,c2 仅含 sequence、role、content。正文仅脱敏凭证和个人信息,不设置采集文本或消息 JSON 的人为长度上限,不截断正文;本地缓存沿用阶段遥测的现有规则。阶段遥测原有 run 创建/关闭、计数和进度不变。
5
+ 对话遥测环境开关默认可用,实际采集必须先取得当前宿主会话的明确同意,可用独立开关 `ALIPAY_AIPAY_CONVERSATION_TELEMETRY=0|false|off|no` 关闭;未设置或为其他值时保持开启。该开关只关闭对话采集,不影响阶段遥测。默认 code 见下方上报字段表。可用 `ALIPAY_AIPAY_CONVERSATION_CODE` 覆盖(1–16 位数字,不得与阶段遥测 code 数值相同);显式空值、非法值或与阶段遥测 code 数值相同时停用对话入口,不影响阶段遥测。全局 `ALIPAY_AIPAY_TELEMETRY=0|false|off|no` 时,两类遥测均关闭,对话采集入口不采集、不读写、不发送;用户主动拒绝仍保存最小隐私选择,明确拒绝的例外见下一段。每条保留 d1~d5,c1 为 conversation_id,c2 仅含 sequence、role、content。正文过滤凭证、个人信息及原流程禁止记录的公钥和临时 URL,不设置采集文本或消息 JSON 的人为长度上限,不截断正文;本地缓存沿用阶段遥测的现有规则。阶段遥测原有 run 创建/关闭、计数和进度不变。
6
6
 
7
7
  明确的用户拒绝属于隐私选择:即使遥测环境开关当前关闭,preview consent 的“仅使用服务”和 telemetry opt-out 仍保存最小拒绝状态并关闭已有采集,防止开关恢复后旧授权复活;这不采集正文、不生成事件或发起上传。环境开关关闭时的同意不写授权,恢复开关后仍需有效的明确同意。
8
8
 
@@ -14,7 +14,7 @@
14
14
 
15
15
  `SESSION_ID` 复用启动器处理声明选择时一次取得的稳定身份,后续采集和业务 runtime 命令均显式携带同一个值。宿主无身份时,启动器的 resolve-session 生成一次随机身份并沿用,不能为对话与业务分别生成。无法恢复身份时重新展示声明并取得选择,不能继承旧会话同意。上传的 `conversation_id` 仍由运行时生成独立随机 UUID,不等于 SESSION_ID 或业务 RUN_ID。
16
16
 
17
- 首次采集以触发 Skill 的那条用户消息为起点。用户同意采集时,按原始顺序补采授权前的完整对话:触发消息为第一条(sequence=1),随后依次是内测声明、澄清往来(如有)和同意回复,每条只采集一次,不重复采集。授权前的助手收口消息(声明、澄清)与正常轮次一样带 `--final true` 采集;其 `MESSAGE_ID` 由对应用户消息的幂等键确定性派生(如 `<触发幂等键>#notice`、`<澄清回复幂等键>#clarify`),同一对话内不得与其他消息重复。授权前内容无法可靠取得(如上下文压缩)时,从可可靠取得的最早消息开始,禁止伪造。`MESSAGE_ID` 使用消息的稳定非内容型身份,同一消息重试复用。`SANITIZED_MESSAGE_JSON` 是 `{"role":"user","content":"脱敏后的消息","has_attachments":false}`;只替换凭证与个人信息,保留其余文字及格式。原文不得拼入命令或普通临时文件,使用结构化参数安全传递脱敏 JSON。无文字附件用空文本和 true;不读取附件、OCR 或文件名。运行时兼容 `{"text":"..."}`,其余非法结构静默拒绝。
17
+ 首次采集以触发 Skill 的那条用户消息为起点。用户同意采集时,按原始顺序补采授权前的完整对话:触发消息为第一条(sequence=1),随后依次是内测声明、澄清往来(如有)和同意回复,每条只采集一次,不重复采集。授权前的助手收口消息(声明、澄清)与正常轮次一样带 `--final true` 采集;其 `MESSAGE_ID` 由对应用户消息的幂等键确定性派生(如 `<触发幂等键>#notice`、`<澄清回复幂等键>#clarify`),同一对话内不得与其他消息重复。授权前内容无法可靠取得(如上下文压缩)时,从可可靠取得的最早消息开始,禁止伪造。`MESSAGE_ID` 使用消息的稳定非内容型身份,同一消息重试复用。`SANITIZED_MESSAGE_JSON` 是 `{"role":"user","content":"脱敏后的消息","has_attachments":false}`;过滤凭证、个人信息及原流程禁止记录的公钥和临时 URL,保留其余文字及格式。原文不得拼入命令或普通临时文件,使用结构化参数安全传递脱敏 JSON。无文字附件用空文本和 true;不读取附件、OCR 或文件名。运行时兼容 `{"text":"..."}`,其余非法结构静默拒绝。
18
18
 
19
19
  ```text
20
20
  node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" telemetry start-conversation --session-id "<SESSION_ID>" --message-id "$MESSAGE_ID" --message-json "$SANITIZED_MESSAGE_JSON"
@@ -36,7 +36,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" telemetry opt-out --ses
36
36
 
37
37
  当前授权仍有效且采集 ACTIVE 时,以对话轮次为单位只采集每轮的头和尾:头是本轮用户消息,逐条采集当前宿主会话内的所有用户消息;尾是本轮的阻塞对客消息与最终收口助手回复;不按是否与支付或 Skill 业务相关筛选。包括澄清、补材料和临时切换话题的用户消息;同一轮内的过程说明、进行中回复、阶段性助手回复、工具结果和轮内送达的非阻塞登记对客消息(如方案、摘要、checklist 结果)一律跳过;切换话题本身不等于取消或退出。
38
38
 
39
- 助手侧采集对象按 Skill 既有阻塞/非阻塞概念判定,不另设分类:凡阻塞对客消息(送达后本轮即停止、等待用户回复:上下文补问、MCC/应用/服务候选选择、材料收集、阻塞确认、授权或公钥页 pending 等)一律采集;每轮最终收口回复一律采集。阻塞消息通常同时就是本轮收口回复,按一条采集,不重复。两类都适用下方"先采集、后发送"规则:带 `--final true` 的 `conversation-message` 是送达前必须执行的采集动作(任务结束时仅允许再执行下文的 end-conversation),业务交付屏障"送达前禁止调用工具"不排除本条采集,采集内容是最终正文仅替换凭证和个人信息后的版本,不改写其他内容。正文不含 system、隐藏推理或工具输出;不能把工具 stdout 当已送达的回复。已有业务计数窗口内,先执行原有 count-user-input,再采集;窗口外采集对话不补计 counter,所有交付屏障和原计数顺序优先。后续消息执行:
39
+ 助手侧采集对象按 Skill 既有阻塞/非阻塞概念判定,不另设分类:凡阻塞对客消息(送达后本轮即停止、等待用户回复:上下文补问、MCC/应用/服务候选选择、材料收集、阻塞确认、授权或公钥页 pending 等)一律采集;每轮最终收口回复一律采集。阻塞消息通常同时就是本轮收口回复,按一条采集,不重复。两类都适用下方"先采集、后发送"规则:带 `--final true` 的 `conversation-message` 是送达前必须执行的采集动作(任务结束时仅允许再执行下文的 end-conversation),业务交付屏障"送达前禁止调用工具"不排除本条采集,采集内容是最终正文仅替换凭证、个人信息及原流程禁止记录的公钥和临时 URL后的版本,不改写其他内容。正文不含 system、隐藏推理或工具输出;不能把工具 stdout 当已送达的回复。已有业务计数窗口内,先执行原有 count-user-input,再采集;窗口外采集对话不补计 counter,所有交付屏障和原计数顺序优先。后续消息执行:
40
40
 
41
41
  ```text
42
42
  node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" telemetry conversation-message --session-id "<SESSION_ID>" --conversation-id "$CONVERSATION_ID" --message-id "$MESSAGE_ID" --message-json "$SANITIZED_MESSAGE_JSON"
@@ -44,7 +44,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" telemetry conversation-
44
44
 
45
45
  用户暂时离开、等待补材料或审核、澄清、遇到报错或中间阶段完成都不结束采集;之后在同一宿主对话继续时沿用原 conversation_id。自更新后保留当前标识,后续命令使用新版同一路径。产品已明确时,初始化和后续消息命令可追加 `--product-type aipay|webpay|apppay`;未知则省略,d5=UNKNOWN。不读取或关联业务 run;首次授权前的补采只在上述明确同意后按原始顺序执行,后续持续采集不回填遗漏消息。
46
46
 
47
- 助手最终收口回复固定采用先采集、后发送:Agent 组织好本轮最终收口回复后,先执行上述 `conversation-message` 并追加 `--final true`,`--message-json` 的 content 必须是随后发送正文的脱敏版本,仅允许替换凭证和个人信息;执行采集后发送原定回复。禁止先发送后采集、发送后补采或在脱敏之外改写采集内容。assistant 角色缺少 `--final true` 时运行时静默丢弃该条记录,过程回复不得调用 conversation-message。采集成功时 stderr 产生唯一 `ALIPAY_AIPAY_INTERNAL:CONVERSATION_MESSAGE_RECORDED=<sequence>` 内部事实行;未出现该 marker 视为采集失败,遥测失败静默、不阻断 Skill,仍正常发送回复。
47
+ 助手最终收口回复固定采用先采集、后发送:Agent 组织好本轮最终收口回复后,先执行上述 `conversation-message` 并追加 `--final true`,`--message-json` 的 content 必须是随后发送正文的脱敏版本,仅允许替换凭证、个人信息及原流程禁止记录的公钥和临时 URL;执行采集后发送原定回复。禁止先发送后采集、发送后补采或在脱敏之外改写采集内容。assistant 角色缺少 `--final true` 时运行时静默丢弃该条记录,过程回复不得调用 conversation-message。采集成功时 stderr 产生唯一 `ALIPAY_AIPAY_INTERNAL:CONVERSATION_MESSAGE_RECORDED=<sequence>` 内部事实行;未出现该 marker 视为采集失败,遥测失败静默、不阻断 Skill,仍正常发送回复。
48
48
 
49
49
  MESSAGE_ID 可复用用户消息的 USER_INPUT_ID;本地按 conversation_id+role+message_id 的 hash 幂等分配 sequence,消息身份本身不上报。调用方按消息在当前会话中出现的顺序依次采集:收到用户消息后,在适用的原计数动作之后采集;最终收口回复按上述先采集后发送规则采集。不得先采集后出现的消息,再补采前面的消息。sequence 在采集时分配,从 1 开始,在同一 conversation 内加锁递增,产品变化不重置;同一消息重试和已入队消息补传均保留原序号,不重新编号。消费端按 conversation_id+sequence 去重并按 sequence 排序,不依赖网络到达先后。该序号仍表示采集顺序,不能自动纠正漏采后补采的原始位置;不上传原始消息时间。
50
50
 
@@ -88,16 +88,16 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" telemetry end-conversat
88
88
 
89
89
  ## 脱敏、本地缓存与共用发送
90
90
 
91
- 调用方仅对凭证和个人信息做语义脱敏,保留字段名、周围说明、代码结构及非敏感参数。凭证包括私钥、密码、访问 Token、API Secret/Key、授权码、验证码、认证 Cookie 或支付认证凭证;个人信息包括姓名、手机号、邮箱、身份证号、银行卡号及个人地址。自由叙述中的姓名、住址等由调用方按语义判断,脚本不能保证覆盖任意表达。
91
+ 调用方对凭证、个人信息及原流程禁止记录的公钥和临时 URL 做语义脱敏,保留字段名、周围说明、代码结构及非敏感参数。凭证包括私钥、密码、访问 Token、API Secret/Key、授权码、验证码、认证 Cookie 或支付认证凭证;个人信息包括姓名、手机号、邮箱、身份证号、银行卡号及个人地址。自由叙述中的姓名、住址等由调用方按语义判断,脚本不能保证覆盖任意表达。
92
92
 
93
- 脚本在落盘和构造请求前再次过滤私钥 PEM、可解析为 PKCS#8/PKCS#1/SEC1 的无头单行 Base64 私钥、Bearer/Basic 认证值、完整 Cookie 值、带前缀的凭证字段、明确标注的个人信息字段,以及可识别的邮箱、手机号和身份证格式。普通链接、路径、代码块、应用 ID、服务 ID、MCC 编码、价格、业务状态和公钥不再整段或按长字符串过滤;其中若嵌入凭证或个人信息,仅替换敏感值。例如带 token 的 URL 保留地址和其他参数,仅遮盖 token 值。格式匹配仍可能误判或漏判,不能声称完全匿名。
93
+ 脚本在落盘和构造请求前再次过滤私钥和公钥 PEM、可解析的无头单行或换行 Base64 密钥、公钥字段、deviceCode/keyConfirmToken 字段、Bearer/Basic 认证值、完整 Cookie 值、带前缀的凭证字段、明确标注的个人信息字段,以及可识别的邮箱、手机号和身份证格式。原流程限制为当次调用使用的应用公钥不得进入采集队列;授权、公钥确认等临时 URL 整条移除,URL 规则复用当前渠道 policy-rules.json 的 temporaryUrlAllowlist,含 deviceCode/keyConfirmToken(含编码后的参数名)的其他 URL 也整条移除。URL 规则不可读时保守移除全部 URL,不阻断启动或自更新。普通帮助链接、路径、代码结构、应用 ID、服务 ID、MCC 编码、价格和业务状态继续保留;其中嵌入的凭证或个人信息仍遮盖敏感值。格式匹配仍可能误判或漏判,不能声称完全匿名。
94
94
 
95
95
  采集脱敏后的完整正文,不主动截断或摘要。
96
96
 
97
- 独立 conversation state 只保存随机 ID、会话 hash、去重 hash、消息序号、创建时授权 ID 和 ACTIVE/CLOSED 状态;正文仅进入当前用户的 outbox。Unix/macOS/Linux 使用 `0600` 文件模式,Windows 仅检查目录实际可写,不声称已经配置 ACL。对话事件使用 .conversation 后缀保存 JSON,让只识别 .json 的旧版 worker 跳过。对话正文和解析错误不进入 stdout/stderr。code 入队时固定,后续改配置不重标旧事件。升级前未取得明确同意的旧 conversation 队列不补传;worker 只发送具有创建时授权 ID 的会话消息,后续同意不得追认旧消息。
97
+ 独立 conversation state 只保存随机 ID、会话 hash、去重 hash、消息序号、待确认消息的序号/去重 hash/时间戳、创建时授权 ID 和 ACTIVE/CLOSED 状态;正文仅进入当前用户的 outbox。Unix/macOS/Linux 使用 `0600` 文件模式,Windows 仅检查目录实际可写,不声称已经配置 ACL。对话事件使用 .conversation 后缀保存 JSON,让只识别 .json 的旧版 worker 跳过。对话正文和解析错误不进入 stdout/stderr。code 入队时固定,后续改配置不重标旧事件。升级前未取得明确同意的旧 conversation 队列不补传;worker 只发送具有创建时授权 ID 的会话消息,后续同意不得追认旧消息。
98
98
 
99
- 对话上报请求不设置脚本级网络超时(timeout=0)。采集命令完成本地状态记录和入队后,尝试启动 detached 后台 worker 并立即返回,不在前台等待网络结果。后台发送也负责失败补传;若网络一直不返回结果,仅后台请求等待,不拖住 Skill 的后续命令。前台 flush-outbox 跳过对话记录,把它们留给后台 worker,避免补传重新引入前台等待。后台 worker 启动失败时保留队列,Skill 继续;后续触发时再尝试启动,不保证最终送达。操作系统、宿主和服务端仍可能中止连接;明确失败时继续按原机制保留记录补传。本地状态写入和入队仍需要少量执行时间,不能把“不等待网络”描述为完全零耗时。
99
+ 对话上报请求最多等待 10 秒(包括 DNS、连接和响应正文等待),每个后台 worker 最多运行 60 秒。同一渠道、同一 outbox 只允许一个后台 worker 执行上传;上传者记录包含开始及失效时间,有效期最多 70 秒(60 秒运行上限及 10 秒退出余量),旧版记录按文件修改时间计算同样的上限。仅在记录有效且进程仍存活时阻止重复启动,过期记录不会因进程号被其他程序复用而永久阻塞;并发启动时由队列锁决定唯一上传者。失效记录对应的 PID 若仍存活,其占用中的记录保留原有 claim TTL 恢复规则,不提前抢占其他活跃发送。每批成功后重新检查队列,继续处理上传期间新增的消息;前台启动上传只尝试取得队列锁,不等待;后台释放退出锁后再检查队列,接手退出窗口内新增的消息。到期前已有成功上传且仍有积压时,释放当前记录后交给新的限时 worker;失败或首条请求持续无响应时不循环拉起新进程。授权保存、采集和结束命令不等待会话锁,锁忙时静默失败并继续业务;过期锁按原规则恢复后只重试一次。成功采集完成本地状态记录和入队即返回,后台启动锁忙时保留队列,不在前台等待锁或网络结果。超时或失败保留未发送记录,worker 到期退出时释放自己占用的记录;异常退出后,后续 worker 检查原进程已结束便恢复其占用记录并重试。前台 flush-outbox 跳过对话记录,避免补传引入前台等待。后台启动失败时保留队列,后续触发时再尝试,不保证最终送达。本地状态写入和入队仍需要少量执行时间。
100
100
 
101
- 除上述对话上报的超时与后台发送规则外,上传、claim 恢复、补传和队列保留/清理规则沿用 [telemetry.md 的“进度与上传”](telemetry.md#进度与上传)。state 成功但 outbox 写入失败时允许丢失且不重建,Skill 继续运行。
101
+ 除上述对话上报的超时与后台发送规则外,上传、claim 恢复、补传和队列保留/清理规则沿用 [telemetry.md 的“进度与上传”](telemetry.md#进度与上传)。对话消息先在会话状态中私有保存待确认序号、去重 hash 与事件时间戳,成功入队后再提交正式序号和去重记录;待确认标记不含正文,不代表采集成功。入队失败不推进正式序号、不输出成功回执,目录恢复后可重试同一消息。状态提交失败时尝试清理本次队列记录。异常退出后,下一次采集或后台上传在同一会话锁内核对待确认标记与队列:已入队则恢复原序号及去重,未入队则清除标记;核对或保存失败时停止本次采集/发送,不占用或重复分配序号。后台仍跳过尚未提交且无法恢复的记录。采集成功仅表示本地入队和状态提交成功,不表示已上传。失败时停止继续传入正文,Skill 业务继续运行。
102
102
 
103
103
  预发版默认遥测根目录为系统临时目录下 `alipay-aipay-telemetry/pre`,与正式版的 run、outbox、上传状态及采集授权隔离;手动设置目录/文件覆盖变量时须自行按渠道分开,不能指向同一状态位置。阶段与对话队列各自保留最多 1000 条及 7 天;对话数量不挤占阶段配额。后台先处理阶段队列,再发送对话;对话写入/启动/上传失败均不改写阶段上传状态,前台联网补传判定只统计阶段队列。对话入队外壳采用 schema_ver=2,固定采集时的 platform,跨宿主补传不改变 d2;旧 schema_ver=1 外壳仍兼容。
@@ -1,6 +1,6 @@
1
1
  # 完整接入编排
2
2
 
3
- 本文件是 `full_process` 唯一入口。Windows 复用根入口的 READY/LEGACY/CODE_ONLY 分流,或明确修复后唯一、根意图匹配的新 READY 事实;BLOCKED 先恢复环境,不进入本流程。CODE_ONLY 只完成独立代码开发,沙箱保持 `VERIFY_PENDING`,最终如实列出未完成项并停在 Onboarding 前;不得登录、开通或宣称完整接入完成。从仅开发切换为完整接入时必须先用 `full_process` 重新执行 Windows 入口。命令携带当前有效的 `--windows-route`。READY 执行 Integration 快速沙箱及 Onboarding 本地流程,LEGACY 仅在不支持的平台映射或用户明确选站点时先完成可独立开发内容,再在原衔接点输出站点引导。三者都不重新安装、不创建 Integration Worker。启动方案送达前只复用 Integration 步骤 1 的项目、语言、当前系统分支环境和沙箱准备;不得开发代码、进入 Onboarding 或读取开通信息。
3
+ 本文件是 `full_process` 唯一入口。Windows 复用根入口的 READY/LEGACY/CODE_ONLY 分流,或明确修复后唯一、根意图匹配的新 READY 事实;BLOCKED 先恢复环境,不进入本流程。CODE_ONLY 继续独立代码开发,沙箱默认 `VERIFY_PENDING`;用户主动提供完整有效手工资料并完成项目配置校验后可记沙箱 `READY`,各测试按实际依赖执行,但环境分流仍为 CODE_ONLY,最终如实列出未完成项并停在 Onboarding 前;不得登录、开通或宣称完整接入完成。从仅开发切换为完整接入时必须先用 `full_process` 重新执行 Windows 入口。命令携带当前有效的 `--windows-route`。READY 执行 Integration 快速沙箱及 Onboarding 本地流程,LEGACY 仅在不支持的平台映射或用户明确选站点时先完成可独立开发内容,再在原衔接点输出站点引导。三者都不重新安装、不创建 Integration Worker。启动方案送达前只复用 Integration 步骤 1 的项目、语言、当前系统分支环境和沙箱准备;不得开发代码、进入 Onboarding 或读取开通信息。
4
4
 
5
5
  目标项目和技术栈确定后执行 `node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" flow integration entry --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"`,只加载当前入口阶段并按步骤 1/2 准备及展示方案;代码开发满足衔接条件后执行 `node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" flow onboarding entry --agent-platform "<AGENT_PLATFORM>" --session-id "<SESSION_ID>"`。禁止整读两个 flow。所有 Skill 自有运行时动作只用当前 Skill 绝对路径下的统一入口单命令执行,不前置 `cd`、不拼接管道;用户项目命令仍以已确认项目根为 workdir。
6
6
 
@@ -86,7 +86,7 @@ node "<SKILL_DIR>/references/normal/scripts/runtime.mjs" integration-message sta
86
86
 
87
87
  - 启动方案送达后先完成上述 Worker 分流,再由确定的执行者进入 Integration 步骤 3;用户中断后若项目、产品、语言或框架变化,重新澄清和扫描并输出当前方案。
88
88
  - Integration 先完整执行和校验。只有沙箱待配置,或 READY 且仅剩非阻塞人工待验证项时,保持“部分通过”进入 Onboarding;其他代码、安全或依据缺口停在 Integration,不提前登录或收集开通材料。
89
- - Windows CODE_ONLY 时,即使沙箱待配置是代码部分的唯一缺口,也在 Integration 最终检查后停止;恢复可选工具并按 `full_process` 复检得到 READY,才按实际项目状态恢复沙箱和 Onboarding。
89
+ - Windows CODE_ONLY 时,不论沙箱配置为 `READY` 还是待配置,均在 Integration 最终检查后停止,不进入 Onboarding;有效手工配置可用于满足自身实际依赖的沙箱测试,不因缺少 Git Bash 单独跳过原生 Python 402 联调。恢复可选工具并按 `full_process` 复检得到环境 READY 后,按实际项目状态继续,复用已有有效配置和联调证据,不重放已完成动作。
90
90
  - 阶段间只复用有效的产品、Integration 结果、沙箱状态、人工待验证项和剩余待办,不再询问是否进入 Onboarding;Onboarding 只保留非阻塞方案展示。
91
91
  - 授权后分别查询签约、应用和适用服务;分支独立,单分支失败不回滚其他成功,认证/授权不匹配或主体变化全局阻断。一次只收集一个类别,提前材料直接校验且不重复索取。
92
92
  - 签约材料通过后直接提交;服务创建摘要后直创、修改仍确认;空应用候选材料完整或非空候选明确新建,重查未变即创建,以用户公钥生成官方确认页,校验成功后直接提审。均不增加额外确认点;按量付费沙箱测试仍属 Integration 默认动作。