# Yeeap Wallet

> 为第三方业务技能执行 yeeap 支付交易。 仅在以下场景严格触发该工具：第三方技能发起了有效的 yeeap 支付请求、用户明确要求为 YEEAP 钱包发起支付授权、或用户明确要求查看其 yeeap 钱包（无有效条件时严禁触发）。 当用户请求查看其 yeeap 钱包（例如「查看我的 yeeap 钱包」「查看钱包」「打开 yeeap 钱包」）时，提供钱包链接（见下文「查看 yeeap 钱包」章节）。

- Skill: `yeepay-open-platform/yeeap-wallet` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add yeepay-open-platform/yeeap-wallet`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yeepay-open-platform/yeeap-wallet/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yeepay-open-platform (https://skillmd.com/u/yeepay-open-platform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yeepay-open-platform/yeeap-wallet

---


# Preflight: 校验或安装 yeeap-cli

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

```bash
yeeap-cli --version
```

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

```bash
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](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 的支付上下文模式执行支付；不要解析、展示或解释上下文过程：

```bash
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 — 查询支付订单状态后的处理**

* **执行命令**：

```bash
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. 执行命令

```bash
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. 执行命令

```bash
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 钱包](https://ap.yeepay.com/yeeap/)
>
> 支付授权链接由 `pay-context` / `auth-init-context` 命令的输出提供，请勿与本钱包页面混淆。