Yeeap Wallet

Preflight: 校验或安装 yeeap-cli

在每次会话发起首次支付或授权相关命令前，先静默校验本地 CLI：

yeeap-cli --version

若命令不存在或版本校验失败，仅执行一次安装：

npm install -g yeeap-cli@wallet-stable

安装成功后，CLI 的 postinstall 会自动将 yeeap-cli 链接到 ~/.local/bin/yeeap-cli。请再次执行 yeeap-cli --version 完成校验。

注意：本技能固定安装 yeeap-cli@wallet-stable。wallet-stable 是 YEEAP 官方维护的 npm dist-tag，指向当前支付稳定版 CLI；不得改用 @latest。后续所有支付、授权和查询命令均直接调用 yeeap-cli，不再使用 npx。

yeeap-cli --version 输出合法版本号视为通过，不要向用户播报版本信息，直接进入下一阶段。安装失败或 CLI 仍不可用时，向用户报告并停止。

执行边界与安全约束 (Instruction Scope & Boundaries)

执行本技能前，须阅读并遵循 IMPORTANT_STATEMENTS.md。

• 人类确认 (Human-in-the-loop)：所有引发实际授权或支付的 URL，必须向用户展示，并等待用户明确回复确认。绝对不要轮询（do not poll）。
• 凭证安全：流程依赖统一的授权 URL 与一次性短效会话令牌运作；永远不要主动向用户索要支付密码或私钥，也不要在日志中留存敏感凭据。
• 本地文件：订单详情位于 ~/.yeeap/orders/<app_id>/<order_no>.json，仅由 CLI 读写；禁止使用 Read 等通用文件工具读取该文件原文对外展示。
• 当前会话绑定：执行 pay-context / auth-init-context / check-auth-context，由 CLI 内部完成支付上下文准备；不得向用户展示或解释上下文内容。
• 禁止自行探测或注入身份上下文：不得执行 env、printenv、set、export、echo $AGENT_SESSION_ID 等命令判断 agentId / loginAccount 是否存在；不得读取 shell profile、.env、npm config、Agent 配置文件或历史日志来推断身份；不得手动设置 AGENT_SESSION_ID、CODEBUDDY_SESSION_ID、YEEAP_CLIENT_TYPE 等变量。WorkBuddy 等客户端的原生变量名不一定是 AGENT_SESSION_ID，必须让 CLI 统一采集。CLI 报身份缺失时，只能展示 CLI 错误并停止，不得自行补救。

[!IMPORTANT] 后续所有与支付、授权查询的操作，均依靠 Preflight 阶段安装完毕的 yeeap-cli 命令行工具处理。

处理支付请求

1. 必需参数

请严格按定义格式提供以下参数：

• order_no（string，必填）：业务技能 Phase 1 输出的商户订单号。也接受 orderNo。
• app_id（string，必填）：业务技能 Phase 1 输出的收款方应用标识。也接受 appId。

[!NOTE] 订单详情已由业务技能 Phase 1 写入 ~/.yeeap/orders/<app_id>/<order_no>.json。本技能只需把 order_no 与 app_id 透传给 CLI；不得自行读取或解析该文件。

2. 执行命令

使用 CLI 的支付上下文模式执行支付；不要解析、展示或解释上下文过程：

yeeap-cli pay-context -o <order_no> -a <app_id>

参数约束：-o 必须是小写字母 o（order），不得写成数字 -0。若 CLI 因缺少 order_no、订单文件不存在或参数错误而失败，视为命令未成功提交支付；不得要求用户重新授权，应修正参数后使用原 order_no 与 app_id 重新执行本命令。

3. 结果处理规则

分析执行命令的标准输出，并严格按以下响应协议按顺序处理。命中第一项后立即停止，不要继续后续步骤。

[!NOTE] 为避免向用户输出过长 URL，向用户展示授权链接或日志原文时，可将其中用于会话的查询参（如 token、sign 等）简写为 ***。

⚡ 全局优先级规则

如果输出包含 已获取到支付凭证，无论同一份输出里是否还出现「需要授权 / 授权链接」等信息，都必须先只执行步骤 2（提取订单号），然后主动带着订单号回调调用方业务技能获取支付状态，再根据返回的状态继续分流。

禁止事项（命中 已获取到支付凭证 时，在回调调用方获取状态之前）：

• 不要自行解析 CLI 输出中的支付状态。
• 不要提取或解码授权链接。
• 不要向终端用户发起授权指引。
• 不要跳过回调调用方，自行执行后续业务逻辑（如直接展示授权页面、直接进入业务 Phase 3 等）。

交互流程：

1. 若出现 已获取到支付凭证 → 先走步骤 2 提取订单号，然后主动带着订单号回调调用方业务技能，由调用方返回支付状态。
2. 拿到调用方返回的支付状态后：
   • 成功 → 走步骤 4 Case A。结束。
   • 处理中 → 走步骤 4 Case B。结束。
   • 失败（FAIL） → 走步骤 2.1，结合之前 CLI 输出中的授权链接判断是否可恢复，必要时回退至步骤 3。
3. 若输出包含 支付状态: 处理中 → 直接走步骤 2.2。结束。
4. 若输出包含 支付状态: 成功 但不包含 已获取到支付凭证 → 直接走步骤 2.3。结束。
5. 若输出包含 订单不存在 → 直接走步骤 4.1的「订单不存在」分支；若授权已成功或本地 token 已写入，允许自动重提一次支付。结束。
6. 若未出现 已获取到支付凭证 → 按顺序评估步骤 1，再评估步骤 3。

步骤 1 — 网络 / 系统失败（优先检查）

• 触发条件：输出包含 网络或系统异常:。
• 排除条件：若同一份输出包含 订单不存在，不要按本步骤处理，必须转到步骤 4.1的「订单不存在」分支。
• 处理动作：报告 CLI 返回的具体错误。若输出包含 返回消息: <MESSAGE>，将 <MESSAGE> 作为补充上下文展示给用户，并给出下一步建议。到此停止；不要进入步骤 2。

步骤 2 — 获取支付凭证

• 触发条件：输出包含 已获取到支付凭证 且包含 订单号: <ORDER_NO>。

• 含义：支付请求已被服务端受理，订单可进入下一阶段。

• 处理动作：

  1. 向用户返回订单号：

     订单号： <ORDER_NO>

  2. 输出约束：命中本步骤时，对外回复只允许包含订单号（可附极简等待提示），不得附加支付状态判断、授权链接、解码结果或后续业务动作。

• 返回订单号后：主动带着订单号回调调用方业务技能，由调用方解析并返回支付状态。拿到状态后继续执行步骤 4；若状态为失败（FAIL），继续执行步骤 2.1。

步骤 2.1 — 凭证回退（Fallback）

该步骤仅在后续支付结果为**失败（FAIL）**时触发。

• 触发条件：步骤 2 之后的支付状态为 FAIL（或同等失败状态）。

• 处理动作：检查原始 CLI 输出是否包含授权指示：

  Case A：输出包含 授权链接 指示

  • 含义：用户尚未完成授权，导致支付无法完成。
  • 处理动作：回退到步骤 3 —— CLI 已提供用户授权指引。

  Case B：不存在授权指示

  • 含义：支付失败且不存在进一步的恢复路径。
  • 处理动作：向用户报告失败。若存在 返回消息: <MESSAGE>，将其作为补充上下文；若无具体细节，建议用户稍后重试或联系支持。

步骤 2.2 — 支付处理中

• 触发条件：输出包含 支付状态: 处理中，且不包含 授权链接:。
• 含义：支付请求已经被服务端受理，但最终支付结果尚未确定。
• 处理动作：
  1. 告知用户支付正在处理中。
  2. 不得重新执行 pay-context，不得发起或展示新的授权链接。
  3. 如需继续确认结果，使用原 order_no 与 app_id 执行一次「查询支付订单状态」命令，并按步骤 4.1处理查询结果。

步骤 2.3 — 订单成功但未获取凭证

• 触发条件：输出包含 支付状态: 成功，且不包含 已获取到支付凭证。
• 含义：pay-query 只确认服务端订单已成功，不返回也不写入 payCredential。
• 处理动作：
  1. 不得进入调用方业务技能 Phase 3。
  2. 使用原 order_no 与 app_id，按上文「处理支付请求 → 2. 执行命令」自动重新执行一次 pay-context，走后端 SUCCESS 幂等路径获取并写入支付凭证；不得更换 CLI 版本，不得添加额外参数。
  3. 重提后必须重新按本节结果处理规则分流；若仍未出现 已获取到支付凭证，向用户报告“订单已成功但支付凭证尚未写入”，不要继续业务执行。

步骤 3 — 需要授权 (Authorization Required)

⚠️ 此步骤用于两种场景：

1. 原始 CLI 输出不包含 已获取到支付凭证。
2. 后续失败结果表明用户仍需完成授权。

• 触发（直接）：输出同时满足以下全部条件：

  1. 订单状态: 待授权 ← 必需（精确匹配）
  2. 存在 授权链接: 指示 ← 必需
  3. 不包含 已获取到支付凭证 ← 必需

• 含义：在用户完成授权前，支付无法继续。

• 处理动作：

  1. CLI 输出包含面向用户的授权链接。将该链接作为官方授权链接展示给用户；若存在 返回消息: <MESSAGE>，请一并作为补充上下文。
  2. 从 stdout 的 授权ID: <AUTH_ID> 提取 auth_id；若旧版 CLI 未输出 授权ID:，再从授权 URL 路径末段提取，例如 https://ap.yeepay.com/yeeap/auth-qr/auth_xxxxx 中的 auth_xxxxx。如未来 URL 使用查询参数 authId，也可从查询参数读取。该值仅用于后续 check-auth-context，不得展示给用户。
  3. 提示用户完成授权：「扫码完成授权后，请告诉我「我已授权」或「我已完成授权」，以便继续支付流程。」

  用户确认已授权后的处理流程

  当用户回复「我已授权」或「我已完成授权」时，不要直接重新支付，必须按以下顺序执行：

  1. 先查询授权状态：使用前面提取的 auth_id，执行下文「查询支付授权状态」命令，确认授权是否成功。
  2. 根据查询结果分流：
     • 成功（successful） → 使用原始的 order_no 与 app_id 重新执行支付命令（回到「处理支付请求 → 2. 执行命令」），并按步骤 4 处理支付结果；若返回 支付状态: 处理中，按步骤 2.2处理，禁止重新授权。
     • 处理中（processing） → 告知用户授权仍在处理中，请稍后再试。
     • 失败或异常 → 告知用户授权未成功，请重新扫码授权。

若步骤 3 命中，到此停止；不要继续步骤 4。

步骤 4 — 按最终支付状态路由

获得调用方返回的支付状态后，按以下分支处理：

Case A：成功

• 触发条件：调用方返回支付状态为成功。
• 处理动作：
  1. 向用户确认支付已成功处理。
  2. 提示业务技能进入下一阶段（Phase 3）继续业务流程。

Case B：处理中

• 触发条件：调用方返回支付状态为处理中。
• 处理动作：告知用户支付仍在处理中，请稍候再查询支付状态；禁止重复发起支付。若需要主动确认结果，执行「查询支付订单状态」命令并按步骤 4.1处理。

Case C：失败

• 触发条件：调用方返回支付状态为失败（或 FAIL）。
• 处理动作：转到步骤 2.1（凭证回退），判断是否存在可恢复路径（授权）。不要在此直接报告失败 —— 必须先经步骤 2.1 评估。

步骤 4.1 — 查询支付订单状态后的处理

• 执行命令：

yeeap-cli pay-query -o <order_no> -a <app_id>

• 已获取到支付凭证：按步骤 2处理订单号，并回调调用方业务技能确认最终业务状态。
• 支付状态: 成功：按步骤 2.3处理；该状态不代表已写入凭证。
• 处理中：告知用户支付仍在处理中；不得重复执行 pay-context。
• 订单不存在 / NOT_FOUND / 查询不到订单：
  • 触发条件：pay-query 输出包含 订单不存在、网络或系统异常: 订单不存在、NOT_FOUND 或 查询不到订单。
  1. 若当前流程已经确认授权成功（Status: successful）或本地 token 已写入，说明支付尚未真正提交或未落库；使用原 order_no 与 app_id，按上文「处理支付请求 → 2. 执行命令」自动重新执行一次 pay-context；不得更换 CLI 版本，不得添加额外参数。
  2. 仅允许对同一订单自动重提一次；不得新建订单，不得要求用户重新授权，不得无限重试。
  3. 重提后按「处理支付请求 → 3. 结果处理规则」重新分流。若仍然订单不存在或命令未提交成功，向用户报告支付提交失败，并展示 CLI 返回的关键错误信息。
• 其他失败：按步骤 2.1评估是否存在授权恢复路径；没有授权指示时报告失败。

发起支付授权（auth-init）

当 pay-context 的步骤 3 直接提示需授权、或用户明确要求「单独发起支付授权」时执行：

1. 必需参数

• app_id（string，必填）：必须由调用方业务技能或当前支付流程明确提供。

缺少 app_id 时必须停止；不得执行 auth-init-context，不得猜测，不得读取订单文件、环境变量、历史日志或本地配置补全。应要求调用方业务技能提供 app_id。

2. 执行命令

yeeap-cli auth-init-context -a <app_id>

3. 结果处理

解析 stdout 中的 授权ID: 与 授权链接:；若旧版 CLI 未输出 授权ID:，按步骤 3 的兼容规则从授权 URL 提取 auth_id 供后续查询使用；按 步骤 3 引导用户完成授权后回复「我已授权」。

查询支付授权状态（check-auth）

当用户回复「我已授权」或「我已完成授权」时执行：

1. 必需参数

• auth_id（string，必填）：来自 pay-context 或 auth-init-context 输出的授权 ID。
• app_id（string，支付流程内必填）：必须使用同一支付流程原始 app_id。
• order_no（string，支付流程内必填）：必须使用同一支付流程原始 order_no。

若 app_id 或 order_no 缺失，必须停止；不得执行 check-auth-context，不得猜测，不得探测环境变量，不得读取本地订单文件，不得从历史日志补全。应要求调用方业务技能重新提供原始 order_no 与 app_id。

2. 执行命令

yeeap-cli check-auth-context -i <auth_id> -a <app_id> -o <order_no>

-o <order_no> 用于让 CLI 在授权成功后清理该订单的待授权上下文；不得省略。

3. 结果处理规则

分析执行命令的标准输出，并严格遵循以下响应协议：

Case A：处理中

• 触发条件：输出匹配 Status: processing。
• 处理动作：告知用户授权仍在处理中，请稍后再试。

Case B：成功

• 触发条件：输出匹配 Status: successful。
• 处理动作：向用户确认授权成功；可继续走「处理支付请求 → 2. 执行命令」重新发起支付。

Case C：执行失败

• 触发条件：出现任意错误信息、超时，或不匹配上述模式。
• 处理动作：报告 CLI 返回的具体错误，建议用户重新扫码授权。

查看 yeeap 钱包

当用户通过如下短语请求查看其 yeeap 钱包：「查看我的 yeeap 钱包」「查看钱包」「打开 yeeap 钱包」「yeeap 钱包管理」或「view my yeeap wallet」，请按以下内容回复：

您可以通过以下链接打开 yeeap 钱包，完成登录、实名与查看账户详情：

👉 打开 yeeap 钱包

支付授权链接由 pay-context / auth-init-context 命令的输出提供，请勿与本钱包页面混淆。