支付宝委托支付技能包

帮助开发者选择委托支付接入方式、理解接口参数并排查联调问题。新版资料核对日期为 2026-09-07，Java SDK 基线为 4.40.987.ALL，覆盖独立签约、支付后推荐和静默签约三种模式。

入口为 agent-payment/SKILL.md。沿用安装标识 agent-payment，支持 Claude Code、Codex 和 Pi 的项目级、用户级 Skill 目录。

覆盖内容

• 三种签约模式的选择条件、接口顺序及协议到支付的数据承接。
• 12 个接口的 SDK 结构与 194 个参数键，包含 AI 付协议、核身、委托任务、预下单、委托支付和即时支付相关能力。
• 客户端 SDK、通知与环境、错误处理指南，以及可追溯的来源登记。
• 结构化参数、错误和通知目录；未确认的必传规则、环境契约和准入条件明确保留为待确认项。

从业务场景开始时，按入口读取业务信息和决策矩阵；查询单个接口时直接使用接口地图。

本包用于接入决策与答疑，尚未经过商户真实环境联调。正式通知与环境缺口见通知与环境；静默签约后的支付协议映射见跨接口数据一致性。

安装

需要 Node.js 18.18 或更高版本及 npm。Skill 资料完整包含在 npm 包内，不需要另行下载 ZIP 或配置 CDN。

在业务项目目录执行：

npx -y @alipay/delegation-skills@latest install

默认只安装到当前项目。安装器依次检查当前 Agent 会话、项目目录和用户目录；能够确定唯一 Agent 时直接安装，否则在终端询问。首次安装不需要额外确认。让 Agent 或自动化脚本执行时，推荐明确指定目标：

# Codex：当前项目
npx -y @alipay/delegation-skills@latest install --agent codex

# Claude Code：当前项目
npx -y @alipay/delegation-skills@latest install --agent claude

# Pi：所有项目共用
npx -y @alipay/delegation-skills@latest install --agent pi --scope user

# 所有项目共用（也适用于 claude / pi）
npx -y @alipay/delegation-skills@latest install --agent codex --scope user

| 目标 | 项目级（默认） | 用户级（--scope user） | | --- | --- | --- | | Claude Code | <项目>/.claude/skills/agent-payment/ | ~/.claude/skills/agent-payment/ | | Codex | <项目>/.agents/skills/agent-payment/ | ~/.agents/skills/agent-payment/ | | Pi | <项目>/.pi/skills/agent-payment/ | ~/.pi/agent/skills/agent-payment/ |

目录依据：Claude Code Skills、Codex Skills。CODEX_HOME 仅参与环境识别，不改变这里的 .agents/skills 目标。自动识别存在歧义且没有交互终端时，会明确提示 --agent 并退出，不等待输入。

Pi 用户级目录遵循 PI_CODING_AGENT_DIR：设置后安装到 <该目录>/skills/agent-payment/。项目级 Skill 需在 Pi 中信任该项目后加载。安装后可运行 /reload 刷新，再用自然语言委托支付问题触发，或显式输入 /skill:agent-payment <问题>。依据为 Pi 随包 docs/skills.md 与 Pi Skills 文档。

预览、更新和卸载

# 预览安装位置和版本，不写入文件
npx -y @alipay/delegation-skills@latest install --agent codex --dry-run

# 指定业务项目目录，支持带空格路径
npx -y @alipay/delegation-skills@latest install --agent codex --dir "/path/to/my project"

# 获取新版安装器，并用它携带的资料更新
npx -y @alipay/delegation-skills@latest update --agent codex

# 检查文件及记录是否与当前取得的安装包一致
npx -y @alipay/delegation-skills@latest status --agent codex

# 确认卸载，仅处理本包的 agent-payment 和版本记录
npx -y @alipay/delegation-skills@latest uninstall --agent codex --yes

更新、检查和卸载时使用与安装相同的 --agent、--scope、--dir。--dir 指业务项目根目录，不能与 --scope user 同时使用。

同版本且内容一致时跳过，不改写文件。升级会整体替换本包目录，移除旧版已删除的资料；版本记录始终对应实际安装包，旧安装器不能降级新版本。

手动安装、旧安装记录或本地修改会要求确认。确认替换前，原目录和记录会备份到 skills 目录之外的 .alipay-delegation-backups/，并输出完整备份位置。自动化如已确认要替换，可在命令末尾加 --yes。卸载也保留备份，其他 Skill 不受影响。备份不会自动清理；需要恢复时，将现有同名目录移开，再把所选备份中的 agent-payment/ 和版本记录复制回输出的 skills 目录。

npx -y 的 -y 只确认 npm 下载；安装器的 --yes 用于确认覆盖本地内容或卸载，不会替你选择 Agent。可用 --dry-run 先看目标。

从源码构建安装

在本仓库安装依赖并构建：

npm install
npm run build
node bin/alipay-delegation-skills.js install --agent codex --dir "/path/to/your/project"

将 codex 替换为 claude 或 pi，即可选择对应 Agent。同一 CLI 支持上述 update、status、uninstall 和所有参数。推送 Git 分支不会更新 npm 包。

也可以不使用 CLI：把完整的 delegation-skill/agent-payment/ 复制到上表对应目录，无需 Node.js 或构建。保留整个目录中的 references/、assets/ 和 agents/；已有同名目录时先移出 skills 目录备份，再整体复制。手动安装不生成 CLI 版本记录，之后可运行 install 接管。

使用示例

安装器会显示实际路径、版本及备份位置。接下来在业务项目的 Agent 会话中加载 agent-payment，试试说：

使用 agent-payment Skill，帮我规划缺货商品到货后自动代买的委托支付接入。用户先确认授权，商品到货后再购买。请给出接口顺序、客户端与服务端分工、关键参数及待确认条件。

status 验证的是磁盘文件；是否已被 Agent 加载，需要在会话中确认，未出现时可重新打开会话。安装知识包不代表商户准入、签约或支付联调已经完成。

仓库结构

delegation-skill/agent-payment/  # 可安装的 skill：入口、路由、接口、目录和模板
bin/ + src/                    # npm/本地 CLI 安装器
scripts/                       # 资产校验、SDK 核验与表格生成工具
tests/                         # 工具回归测试、12 个模拟问题与验收标准

npm 包分发 bin/、编译后的 dist/、delegation-skill/ 和 LEGAL.md。参数和错误目录以 skill 内 YAML 为唯一编辑源；原始 SDK 压缩包、源码克隆和语雀缓存不随仓库分发。

维护与验证

资产工具使用 Python 3 与 PyYAML；可通过 uv 临时提供依赖：

uv run --with pyyaml python scripts/validate-assets.py
uv run --with pyyaml python -m unittest discover -s tests -p test_validate_assets.py -v
npm test
npm pack --dry-run

npm test 在临时目录验证目标选择、非交互安装、真实升级、旧文件清理、备份与失败回滚；不会写入真实 Agent 的 Skill 目录。npm pack / npm publish 会通过 prepack 从源码重新构建，清理过期编译文件。

需要表格审阅时再生成 generated/reference-tables/；生成物已加入 Git 忽略，不重复提交：

uv run --with pyyaml python scripts/render-catalogs.py
uv run --with pyyaml python scripts/render-catalogs.py --check

修改场景或接口语义后，可用 cases.yaml 进行离线问答回归：逐例将问题与 skill 交给独立 agent，再按 expectations.yaml 核对答复；验收标准不交给被测 agent，也不调用真实业务接口。该模拟评估与工具单元测试分别执行。

来源 URL、版本和校验值见 sources.yaml。历史设计、研究和回放记录可从 Git 提交 13ce426 查阅。

升级 SDK 时，可从官方 SDK 压缩包提取这 12 个接口的源码和字段，用于核对变化：

python3 scripts/extract-sdk-contracts.py /path/to/alipay-sdk-JAVA-version.zip

结果写入忽略目录 .sources/sdk/，结构化字段位于 contracts.json。该工具不修改 skill；核对版本、字段差异和业务规则后再人工更新 YAML。

使用说明

请结合支付宝开放平台协议与实际产品准入使用，参阅 LEGAL.md。本 skill 的来源核验与模拟验收不能替代商户环境中的接口联调。