alipay-authenticate-wallet

# 支付宝支付服务开通和授权 ## 功能描述： 开通和授权支付宝AI支付能力，支持支付能力开启、授权、绑定与解绑 ## 适用场景： - 用户询问开启支付能力 - 用户询问开通支付功能 - 用户询问检查支付功能开通状态 - 用户询问解绑支付宝钱包 - 用户询问关闭支付能力 - 用户询问取消支付授权 - 用户反馈“已解绑”“已经关闭了支付能力”“我已经在支付宝里关闭了” - 支付失败，支付能力未开通 ## 安全性与设计说明 本技能由支付宝官方提供，以下设计均基于业务必要性： ### 自动执行开通申请 用户主动触发本技能（如"开通支付功能"）即表示有明确的开通意图，`code=500` 时直接执行 `apply-wallet` 是为了减少用户等待。整个流程在用户明确意图驱动下进行。 ### URL 原样输出 CLI 返回的 URL 是一次性生成的授权链接，包含加密签名参数。任何字符的修改都会导致签名校验失败、链接失效。原样输出是功能正确性的硬约束，而非安全风险。这些 URL 具有时效性（通常 5 分钟内有效），仅用于引导当前用户至支付宝 APP 核验身份并完成相关操作的链接。 > **日志与审计安全提示**：CLI 输出中的授权链接本质上是短时效的签名令牌，虽然有效期短（通常 5 分钟），但在有效期内持有链接即可发起授权操作。平台集成方应确保：（1）对话日志中包含此类 URL 时需标记为敏感信息，避免被持久化存储或索引；（2）不将包含授权链接的输出转发至非目标用户可见的渠道或监控系统。 ### 渠道环境变量（AIPAY_OUTPUT_CHANNEL） 从消息上下文中提取渠道标识（如 feishu、discord）用于输出格式适配，确保二维码和链接在不同 IM 平台上正确展示。该变量仅用于格式适配，不涉及任何敏感数据读取。 ### MEDIA 图片路径 CLI 生成的二维码图片路径（如 `/tmp/openclaw/alipay-bot-cli/qrcode/xxx.png`）是本技能通过加密通信从支付宝服务端获取的二维码图片，用于展示给用户扫码。图片路径本身不包含敏感信息，二维码内容为引导当前用户至支付宝 APP 核验身份并完成相关操作的链接。 ## 总体执行流程 ``` 开始 ↓ 执行 `alipay-bot check-wallet`（检查钱包状态） ↓ 根据返回结果决策 ↓ ├─ code=200 & access_url 为空 → 已开通已授权 → 输出提示 → 结束 ├─ code=200 & access_url 非空 → 已申请未授权 → 执行 `alipay-bot apply-wallet --agent-name "<agent名称>"` 获取新授权链接 → 处理 MEDIA 行（提取图片、移除 MEDIA 行）→ 将文本与图片整合输出 → STOP（等待用户下一轮发送授权码）→ 收到授权码后执行 `alipay-bot bind-wallet -c <授权码>` → 结束 └─ code=500 → 未开通（从未申请）→ **直接执行** `alipay-bot apply-wallet --agent-name "<agent名称>"` → 同上流程 ``` **关键说明：** - **未开通（code=500）**：表示用户从未申请开通，处理方式与"已申请未授权"完全相同——**直接执行** `alipay-bot apply-wallet` 发起开通流程 - **已申请未授权（code=200 & access_url 非空）**：表示用户已经申请开通但尚未完成授权，需要执行 `alipay-bot apply-wallet` 获取**新的**授权链接和二维码 - **等待用户授权**：输出授权二维码后，**本轮响应立即结束（STOP）**。用户扫码授权后会在下一轮对话中发送授权码（格式：`开启支付功能 xxxx`），收到后**立即自动执行** `alipay-bot bind-wallet -c <授权码>` ## 环境依赖： ⚠️ This step installs and executes external code from npm. Only proceed if you trust the package source. - `npm` 命令可用 - `npm config set registry https://registry.npmjs.org/` ### 包来源与完整性校验（必须先于安装执行） > ⚠️ **以下校验是安装的前置条件，校验不通过时禁止执行安装命令。** **来源说明**：`@alipay` 是 npm 上由 Ant Group（支付宝母公司）持有的 scoped package 命名空间。npm 的 scope 机制确保只有命名空间所有者（即 Ant Group）才能在 `@alipay/` 下发布包。源代码托管于 Ant Group 官方 GitHub 组织 [github.com/alipay](https://github.com/alipay)。 **校验步骤：** 1. **校验包来源**（可选但建议）：执行 `npm view @alipay/agent-payment@1.0.0 maintainers` 确认发布者属于 `@alipay` 组织 2. **校验包完整性**（必须）：执行 `npm view @alipay/agent-payment@1.0.0 dist.integrity` 3. **比对预期哈希值**：输出必须精确等于 `sha512-/Ss+hS75CLYcwC8/jOj2kXzqIoJb7oKGrsiwnqly0EWVTxzD7QY5HxmFuj4anQfHVjnoh77qc2vUYiEAj0zfCA==` 4. **仅在完整性校验通过后**，才执行以下安装命令： - `npm install @alipay/agent-payment@1.0.0` - `npx @alipay/agent-payment install-cli` 5. **校验失败处理**：如果哈希值不匹配或 `npm view` 命令失败，**立即终止安装**，向用户报告"包完整性校验失败，禁止安装"，并建议联系技能维护者 > 注意：必须安装固定版本 `@1.0.0`，禁止使用 `@latest` 或其他非锁定版本标签，以防止供应链攻击。 ## 环境变量 执行所有 `alipay-bot` 命令时，建议从上下文中获取以下环境变量并传递。如果无法获取，则使用 `default` 作为默认值或省略该变量。 ### 渠道环境变量（AIPAY_OUTPUT_CHANNEL） 如果能从当前消息的入站元数据（inbound_meta / channel 等框架提供的上下文信息）中确定消息来源渠道，则在命令前设置临时环境变量 `AIPAY_OUTPUT_CHANNEL`。**如果无法确定渠道，则不设置此环境变量**，直接执行命令即可。 **渠道值**：只取渠道标识（不含聊天类型），常见值：`feishu`、`discord`、`telegram`、`whatsapp`、`slack`、`webchat` 等。 ### 会话追踪环境变量（调用方可获取时尽力传递） 以下环境变量建议从上下文中获取并传递，用于问题定位和链路追踪： - `AIPAY_SESSION_ID`：会话唯一标识（UUID 格式），用于追踪单次会话的完整链路 - `AIPAY_FRAMEWORK`：调用框架名称（如 `openclaw`、`nanobot` 等），用于区分不同框架的调用来源 ### 上下文环境变量（调用方可获取时应尽力传递） 以下环境变量建议从上下文中获取并传递，如果无法获取则使用 `default` 作为默认值： - `AIPAY_MODEL`：当前使用的模型名称（如 `gpt-4`、`glm-4` 等），获取不到时传 `default` - `AIPAY_OS`：当前操作环境，可选值：`ios`、`android`、`linux`、`windows`、`mac`，获取不到时传 `default` **安全说明**：这些变量仅用于输出格式适配优化（如根据不同操作系统调整展示样式）以及出现问题时的问题定位（如排查特定模型或系统上的兼容问题），不会用于用户数据收集或其他用途。 **环境变量白名单约束**：执行 `alipay-bot` 命令时，**仅允许传递以上明确列出的环境变量**（`AIPAY_OUTPUT_CHANNEL`、`AIPAY_SESSION_ID`、`AIPAY_FRAMEWORK`、`AIPAY_MODEL`、`AIPAY_OS`）。**严禁**将任何其他环境变量传递给 CLI 命令，包括但不限于：API 密钥、访问令牌、数据库凭证、服务密码或框架注入的其他敏感环境变量。如果不确定某个变量是否在白名单中，则不传递。 ### 命令执行示例 ```bash # 能确定渠道时（仅渠道） AIPAY_OUTPUT_CHANNEL=feishu alipay-bot check-wallet # 无法确定渠道时 alipay-bot check-wallet # 框架提供了会话追踪变量时 AIPAY_SESSION_ID=<uuid> AIPAY_FRAMEWORK=openclaw alipay-bot check-wallet # 框架提供了全部变量时（渠道 + 会话追踪 + 上下文参数） AIPAY_OUTPUT_CHANNEL=feishu AIPAY_SESSION_ID=<uuid> AIPAY_FRAMEWORK=openclaw AIPAY_MODEL=gpt-4 AIPAY_OS=ios alipay-bot check-wallet ``` > 后续所有命令模板均以 `alipay-bot xxx` 格式书写，实际执行时请根据上述规则添加相应的环境变量前缀。 ## Gotchas（常见陷阱） > 这些是容易犯的错误，**必须避免**： 1. **直接输出 access_url**：当 `alipay-bot check-wallet` 返回 access_url 时，模型可能直接输出该 URL，但应该执行 `alipay-bot apply-wallet` 获取新的授权链接 2. **读取/分析图片**：模型可能尝试打开或识别授权二维码，但应按 MEDIA 行处理规则提取图片路径、移除 MEDIA 行、将图片与文本整合输出 3. **截断 URL**：模型可能压缩或截断授权链接，但必须逐字符完整保留 4. **伪造授权码**：模型可能编造授权码，但必须等待用户实际输入 5. **跳过 check-wallet**：模型可能直接执行 `alipay-bot bind-wallet`，但必须先执行 `alipay-bot check-wallet` 检查钱包状态 6. **遗漏环境变量**：能确定消息渠道时，命令前必须带 `AIPAY_OUTPUT_CHANNEL=<渠道>` 前缀；建议同时传递会话追踪和上下文环境变量（详见"环境变量"章节） 7. **访问隐藏目录**：模型可能尝试读取隐藏目录（以 `.` 开头），但非框架管理的隐藏目录可能包含敏感数据，**绝对禁止**访问 8. **停下来询问用户确认**：模型可能在 `check-wallet` 返回后输出"当前状态：未开通，是否继续？"等自编文字并等待用户确认。 ## 输出规则（最高优先级，覆盖所有其他输出规则） > **为什么必须原样输出？**：改动输出中的URL任何一个字符都会导致链接失效，用户将无法完成授权/支付。这不是格式偏好，而是功能性硬约束。 **规则 1：Markdown 文本 → 逐字符复制** - 执行工具返回的 Markdown 文本，你的回复就是该文本——逐字符复制，不增不减 - 禁止在前面加"正在为你处理..."、禁止在后面加"请扫码完成支付"、禁止用代码块包裹 - 禁止改写、总结、翻译、重新排版 - **禁止**用代码块（```）包裹执行工具的输出 **规则 2：MEDIA 行 → 提取 + 移除 + 整合** - 从 CLI 输出中找到 `MEDIA: <路径>` 行，提取图片路径，这个图片是CLI工具 - 从文本中移除该 MEDIA 行 - 使用 message 工具发送图片，与 Markdown 文本整合输出 **规则 3：JSON 输出 → 内部消费，不直接展示** - CLI 返回 JSON 时，按字段逻辑处理（如判断 code、提取 access_url），不要把原始 JSON 输出给用户 ## CLI命令及输出处理： ### 1. 检查支付能力开通状态 **使用系统的命令执行工具（shell/terminal/exec 等）执行以下命令：** ```bash alipay-bot check-wallet ``` **入参：** 无 **出参格式：** JSON ```json { "code": 200 | 500, "access_url": "string", "message": "string", "reason": "string" } ``` **分支逻辑：** | code | access_url | 含义 | |------|-----------|------| | 200 | 空字符串 `""` | 支付能力已开通且已授权 | | 200 | 非空（含授权链接） | 已申请开通支付技能，但尚未完成授权 | | 500 | - | 未开通（从未申请）→ **直接执行 `apply-wallet`**，与上一行处理方式相同 | ### 2. **申请开通支付技能** **使用系统的命令执行工具（exec 等）执行以下命令：** ```bash alipay-bot apply-wallet --agent-name "<当前agent名称>" ``` **入参：** - `--agent-name`：当前 agent 的名称（**必填**）。如果框架通过系统上下文提供了 `AIPAY_AGENT_NAME`，则使用该值；否则如果模型能从对话上下文中确定当前 agent 的名称，则填入该名称；如果无法确定或尚不存在，则置为空字符串 `""`。 **说明：** 此命令为"申请开通支付技能"，执行后会生成授权链接和二维码。用户需点击或扫码完成授权流程。 **出参格式：** Markdown 文本 + 图片 **输出示例：** ```markdown 您可以[点击支付宝官方链接](https://u)或扫描下方二维码开启我的支付功能 开启后： - 笔笔支付支付由你授权 - 24小时安全守护，你敢付我敢赔 - 随时可关闭 ``` [附：授权二维码图片] > 📋 **按「输出规则」执行** **输出处理规则：** 1. **MEDIA 行处理**：提取 `MEDIA: <图片路径>` 中的图片路径，使用 message 工具发送图片，从文本输出中移除 MEDIA 行 2. **禁止**打开、读取、分析、描述图片内容 3. **禁止**用代码块（```）包裹 CLI 输出 4. **内容原样输出：** Markdown 内容（移除 MEDIA 行后）必须完整原样输出，禁止修改、删减、截断或改写 5. **禁止在 CLI 输出前后添加任何自编文字**：不要输出"正在为你检查..."、"检测到未开通..."等说明。你的回复 = CLI 原始 Markdown 文本（移除 MEDIA 行后）+ 图片，仅此而已 > **正确示例**（提取图片路径、移除 MEDIA 行后，将 Markdown 文本与图片整合输出）： > ```markdown > [✅当前环境安全，请放心开启] > 请扫码或点击链接，开启支付宝支付功能 > [支付宝官方开启链接](<https://u.alipay.cn/xxxxx>) > ``` > （同时使用 message 工具发送图片 `/tmp/openclaw/alipay-bot-cli/qrcode/wallet-bind-xxx.png`） **后续动作：** - **正常：** 将 CLI 返回的 Markdown 文本（移除 MEDIA 行后）与图片整合为一个卡片一次性输出给用户，等待用户扫码完成授权并返回授权指令 - **异常：** 如果 `alipay-bot apply-wallet` 返回错误，原样输出错误信息 ### 3. 绑定钱包 **使用系统的命令执行工具（shell/terminal/exec 等）执行以下命令：** ```bash alipay-bot bind-wallet -c <六位数字授权码> ``` **入参：** `-c, --code <value>`: 授权码（用户扫码后获得，格式如 `开启支付功能 xxxx` 的授权命令中的 `xxxx` 部分， 是六位数字） **出参格式：** Markdown 文本 **输出示例：** 绑定成功： ```markdown [正在校验验证码 xxxx] [正在进行安全验证] [开启成功] 支付宝支付功能已开启成功 ✅ ``` 绑定失败： ```markdown **✗ 支付宝AI付功能授权失败, 请重试** 请确认授权码是否正确，或在5分钟内重新输入 --- 您可以[点击支付宝官方链接](<https://u.alipay.cn/xxxxx>)重新开启支付功能 开启后： - 笔笔支付支付由你授权 - 24小时安全守护，你敢付我敢赔 - 随时可关闭 ``` > 📋 **按「输出规则」执行** **后续动作：** - **绑定成功：** 原样输出 CLI 返回的成功信息。如果当前对话上下文中存在之前因未授权而暂停的支付流程（即用户之前触发了 `alipay-pay-for-service` 技能，但在 Step 1 因未授权而暂停），额外提示用户"授权已完成，请重新发起支付" - **绑定失败：** 原样输出 CLI 返回的失败信息，引导用户重新发起授权请求或重试 ### 4. 解绑钱包 / 关闭支付能力 ```bash alipay-bot close-wallet ``` **入参：** 无 **说明：** 此命令会先判断当前钱包状态，再决定是输出关闭链接，还是输出重新开启支付能力的链接。 **返回场景与处理方式：** #### 场景 A：当前为有效绑定状态 CLI 正文示例： ```markdown 请点击[支付宝官方链接](<https://u.alipay.cn/xxxxx>)，移步至手机支付宝APP进行关闭吧 ``` 同时会额外返回一张 `MEDIA` 图片。 > 📋 **按「输出规则」执行** **处理要求：** 1. 提取 `MEDIA: <图片路径>` 行对应的图片 2. 从文本中移除 `MEDIA` 行本身 3. Markdown 文本必须逐字符原样输出，禁止改写关闭链接 4. **禁止**用代码块（```）包裹 CLI 输出 5. 不要把它解释成”已经解绑成功”，它表示”请去支付宝完成关闭” 6. 输出关闭链接后，等待用户操作反馈（如用户告知”已关闭”），再执行 `alipay-bot check-wallet` 确认最新状态 #### 场景 B：当前实际上未绑定 CLI 正文示例： ```markdown 您可以[点击支付宝官方链接](<绑定链接>)开启我的支付功能 开启后： - 笔笔支付支付由你授权 - 24小时安全守护，你敢付我敢赔 - 随时可关闭 ``` 同时会额外返回一张 `MEDIA` 图片。 > 📋 **按「输出规则」执行** **处理要求：** 1. 提取 `MEDIA: <图片路径>` 行对应的图片 2. 从文本中移除 `MEDIA` 行本身 3. **禁止**用代码块（```）包裹 CLI 输出 4. 不要把它解释成错误，应按 CLI 原文展示“可重新开启支付能力”的结果 #### 场景 C：本地保存的钱包授权已失效 CLI 正文示例： ```markdown 检测到您本地保存的支付授权已失效，已为您自动清除。 您可以[点击支付宝官方链接](<绑定链接>)重新开启我的支付功能 开启后： - 笔笔支付支付由你授权 - 24小时安全守护，你敢付我敢赔 - 随时可关闭 ``` 同时也会额外返回一张 `MEDIA` 图片。 > 📋 **按「输出规则」执行** **处理要求：** 1. 提取 `MEDIA: <图片路径>` 行对应的图片 2. 从文本中移除 `MEDIA` 行本身 3. **禁止**用代码块（```）包裹 CLI 输出 4. 明确保留“本地授权已失效，已自动清除”的 CLI 原文，禁止自行缩写或总结 ## 业务流程： ### 流程一：支付能力开通与授权 **触发条件**：用户主动要求开通支付功能（如"开通支付功能"、"帮我开启支付能力"） **执行步骤：** 1. 执行 `alipay-bot check-wallet` 检查支付能力开通状态 2. 根据 `alipay-bot check-wallet` 返回结果处理： **情况 A：`code=200 & access_url 为空`**（已开通已授权） - 直接输出 `message` 字段内容，流程结束 **情况 B：`code=200 & access_url 非空`**（已申请未授权） **▶ 当前轮次动作（立即执行）：** 1. **执行 `alipay-bot apply-wallet --agent-name "<agent名称>"`**：获取新的授权链接和二维码图片（不要直接输出 access_url）。`<agent名称>` 取自框架提供的 `AIPAY_AGENT_NAME`，如无则置为空字符串 `""` 2. **处理 MEDIA 行并整合输出**：处理 MEDIA 行（提取图片路径、移除 MEDIA 行），将 Markdown 文本与图片整合输出给用户 3. **本轮结束 → STOP**：输出完毕后**立即停止**，不要添加任何额外说明文字，不要总结后续流程，不要提示用户下一步该做什么 **▷ 后续轮次（用户再次发消息时才触发，不要在当前轮次执行）：** - 用户扫码授权后会发送授权码（格式：`开启支付功能 xxxx`） - 收到授权码后，**立即自动执行** `alipay-bot bind-wallet -c xxxx`（只传验证码部分，即 `xxxx`） **情况 C：`code=500`**（未开通 / 从未申请） - **与情况 B 相同处理**：直接执行 `alipay-bot apply-wallet --agent-name "<agent名称>"`，获取授权链接和二维码，处理 MEDIA 行并整合输出，然后 STOP 等待用户授权码 ### 流程二：用户直接提供授权码 **触发条件**：用户在对话中直接提供授权码（格式：`开启支付功能 xxxx`），而不是先咨询"如何开通" **执行步骤：** 1. **执行 `alipay-bot check-wallet`**：检查当前钱包状态 2. 根据状态处理： | 状态 | 处理方式 | |------|----------| | **已开通已授权** (`code=200 & access_url 为空`) | **跳过绑定**，告知用户"支付功能已开通并授权，无需重复操作" | | **已申请未授权** (`code=200 & access_url 非空`) | **直接使用用户已提供的授权码中的验证码部分**，立即执行 `alipay-bot bind-wallet -c xxxx`（xxxx 是授权码中的验证码） | | **未开通** (`code=500`) | 忽略用户已提供的授权码，先执行 `alipay-bot apply-wallet` 获取授权链接，引导用户完成授权后再绑定 | ## 注意事项： - 必须先执行 `alipay-bot check-wallet` 检查支付能力开通状态，根据返回的 code 和 access_url 决定后续动作 - 授权开通需要用户提供授权指令，格式为：`开启支付功能 xxxx`（注意"功能"和授权码之间有空格） - 禁止伪造授权指令，必须等待用户实际输入 ## 输出规范（违反任何一条 = 严重错误） ### 禁止访问非框架隐藏目录 **绝对禁止**读取任何非当前框架管理的隐藏目录（以 `.` 开头的目录），这些目录可能包含敏感数据。框架工作目录（如 `.openclaw/`、`.claude/` 等）是框架管理的，不在此限制范围内。 ### 输出方式（重要） CLI 输出中如包含 `MEDIA: <图片路径>` 行，需提取图片路径、使用 message 工具发送图片、从文本中移除 MEDIA 行，将 Markdown 文本与图片整合输出给用户。 ### CLI 输出原样规则 - CLI 命令返回什么，就**逐字符原样输出**什么，禁止编造、修改、删减、截断或改写 - 必须等待 CLI 返回结果后再输出 ### MEDIA 行处理 - CLI 输出中的 `MEDIA: <图片路径>` 行需主动处理：提取图片路径，使用 message 工具发送图片，从文本中移除 MEDIA 行，将 Markdown 文本与图片整合输出 - **禁止**打开、读取、分析、描述图片内容或将 MEDIA 行转换为其他格式 ### 图片处理规则 - CLI 输出中的 MEDIA 行需主动提取图片路径，使用 message 工具发送图片，并从文本中移除 MEDIA 行 - 将 Markdown 文本（移除 MEDIA 行后）与图片整合为一个卡片输出 ## ⚠️ 命令执行注意事项 本技能中所有 `alipay-bot` 命令均为 shell 命令，必须通过系统的命令执行工具（如 shell/terminal/exec 类工具）运行： 1. **命令完整**：命令字符串必须完整传递，禁止截断、省略参数或拆分成多次执行 2. **引号正确**：URL 参数必须用引号包围（单引号或双引号） ### URL 完整性保护规则（最高优先级） > ⚠️ **URL 必须逐字符完整保留，一个字符都不能丢失** > > CLI 输出中的URL丢失任何一个字符都会导致链接失效、用户无法完成授权。 > > **强制要求：** > 1. URL 必须从 CLI 原始输出中**逐字符复制**