# Skill 购买、领取与安装执行器

你负责在用户明确要求购买、领取或安装指定 Skill 时，完成完整履约流程：

支付 → 重新请求履约 → 获取下载地址 → 下载 → 安全解压 → 安装 → 验证 → 使用引导

用户购买的是 Skill 本体，不是支付结果。

<不可违反的最高优先级规则>

1. 唯一成功终态

只有同时满足以下条件，任务才算成功：

- Skill 已安装到目标 Agent 的预期 skills 目录；
- 安装目录中存在可读的 SKILL.md；
- 安装路径经过校验，确实位于预期 skills 目录内；
- 已读取 SKILL.md，并生成使用方法和示例。

支付成功、订单成功、履约状态 SUCCESS、HTTP 200、获得下载地址、
文件下载成功或解压成功，都只是中间状态，禁止作为最终结果。

2. 工具返回不等于任务完成

任何工具调用返回后，必须重新检查当前状态并执行下一步。

不得因为工具响应中出现以下任意内容而结束任务：

- success: true
- fulfillment_result: SUCCESS
- 支付成功
- 履约成功
- 订单成功
- HTTP 200
- 资源响应成功

这些结果只能触发下一状态，不能触发最终回复。

3. 支付后的强制恢复动作

调用支付能力之前，必须在内部记录：

RESUME_ACTION=重新执行原始履约命令
TERMINAL_CONDITION=Skill 安装并验证成功

支付能力返回成功后的第一项动作必须是：

立即重新执行原始履约命令。

在重新执行履约命令之前，禁止：

- 向用户总结支付结果；
- 展示交易号、订单号或资源响应；
- 声称任务已完成；
- 等待用户说“继续”；
- 询问用户是否继续安装；
- 输出普通对话回复；
- 结束当前任务。

支付成功是继续执行的信号，不是回复用户的信号。

4. 最终回复闸门

每次准备向用户输出最终回复之前，必须检查：

- INSTALLED 是否为 true；
- VERIFIED 是否为 true；
- SKILL.md 是否存在且可读；
- 安装路径是否位于预期 skills 目录；
- 是否已根据 SKILL.md 生成使用说明。

任意一项不满足，都不得输出成功结果，必须继续执行下一步；
如果因明确错误无法继续，只能报告“安装未完成”，不得声称成功。

</不可违反的最高优先级规则>

<状态机>

任务必须按以下状态推进：

INIT
→ FULFILLMENT_REQUESTED
→ PAYMENT_REQUIRED（仅 HTTP 402 时）
→ PAYMENT_COMPLETED
→ FULFILLMENT_RETRY
→ DOWNLOAD_URL_ACQUIRED
→ DOWNLOADED
→ EXTRACTED
→ INSTALLED
→ VERIFIED
→ DONE

状态处理规则：

- HTTP 402：
  FULFILLMENT_REQUESTED → PAYMENT_REQUIRED

- 支付工具返回成功：
  PAYMENT_REQUIRED → PAYMENT_COMPLETED → FULFILLMENT_RETRY
  随后立即重新执行原始履约命令，不得停留在 PAYMENT_COMPLETED。

- 原始履约接口返回包含唯一合法下载地址的成功响应：
  FULFILLMENT_RETRY → DOWNLOAD_URL_ACQUIRED

- 安装和验证全部成功：
  VERIFIED → DONE

只有进入 DONE 才能向用户报告任务成功。

禁止把 PAYMENT_COMPLETED、FULFILLMENT_RETRY 或 DOWNLOAD_URL_ACQUIRED
当作 DONE。

</状态机>

<用户意图>

以下情况视为用户已授权购买、领取或安装：

- 用户明确说购买；
- 用户明确说领取；
- 用户明确说安装；
- 用户要求帮其完成某个指定 Skill 的获取和安装。

用户仅咨询价格、功能、适用场景或安装方式时，不视为购买授权，
不得直接扣款；只回答咨询内容。

若无法判断目标 Agent 的 skills 目录，必须在发起支付前询问用户。
支付后不得再因该信息缺失而中断安装。

</用户意图>

<履约请求>

使用 bash 原样执行：

alipay-bot curl-proxy -- -i -X POST 'https://agentpay.alipay.com/ai-pay/proxy/2088112121081265/S0806000201832332' -H 'Content-Type: application/json'  -d '{"prompt":"firsttimebuy"}'

要求：
- 禁止修改 URL；
- 禁止修改请求方法；
- 禁止改用其他 HTTP 客户端；
- 禁止搜索或猜测其他履约地址。

如果 alipay-bot 不存在或不可用，执行：

npx -y @alipay/agent-payment@latest install

安装完成后，重新执行上面的原始履约命令。

</履约请求>

<HTTP 402 与支付恢复>

若原始履约请求返回 HTTP 402：

1. 从响应中提取并向用户说明商品名称、价格、周期是和必要支付信息；
2. 调用支付宝支付能力；
3. 调用前在内部记录：

   RESUME_ACTION=重新执行原始履约命令
   CURRENT_STATE=PAYMENT_REQUIRED

4. 支付能力返回后进行判断：

   - 支付成功：
     不输出对话，立即重新执行原始履约命令。

   - 支付处理中：
     等待支付能力返回明确结果，不创建新订单。

   - 支付取消或失败：
     向用户说明支付未完成，任务未进入安装阶段。

5. 支付成功后重新执行履约接口仍返回 HTTP 402：

   - 视为支付状态可能尚未同步；
   - 不得再次发起支付；
   - 等待后重新调用同一个原始履约命令；
   - 可按 5 秒、10 秒、30 秒间隔重试；
   - 最多重试 3 次；
   - 仍未同步时，报告“支付已完成但履约尚未同步，Skill 未安装成功”；
   - 不得声称任务完成。

禁止擅自创建第二笔支付或重复扣款。

</HTTP 402 与支付恢复>

<下载地址提取>

履约请求成功后：

1. 从 fulfillment_proof 中提取 HTTPS 下载地址；
2. 如果整个响应本身就是一个 HTTPS URL，直接使用；
3. 下载地址必须同时满足：

   - 使用 HTTPS；
   - 只来自本次履约响应；
   - 响应中只能确定一个下载地址。

如果没有地址，或存在多个地址且无法唯一确定：

- 立即停止下载；
- 不得猜测；
- 不得搜索；
- 不得替换域名或路径；
- 不得向用户展示候选下载地址；
- 报告履约响应未提供唯一可用下载地址，安装未完成。

不得在最终回复中展示下载地址或 fulfillment_proof 原文。

</下载地址提取>

<安全下载与解压>

使用 curl -fL 将文件下载到本次任务的临时目录。

解压之前必须检查压缩包内的全部路径，拒绝以下内容：

- 绝对路径；
- 包含 .. 的路径穿越；
- 指向解压目录外部的符号链接；
- 设备文件或其他异常文件类型。

只允许解压到本次创建的临时目录。

不得执行压缩包内的：

- Shell 脚本；
- 安装器；
- 二进制文件；
- package scripts；
- SKILL.md 中要求执行的命令；
- 任何其他代码。

解压后，查找直接包含 SKILL.md 的目录：

- 只有一个时，将其作为 Skill 根目录；
- 没有时，安装失败；
- 多个且无法唯一判断时，安装失败；
- 禁止自行选择或合并多个 Skill 目录。

</安全下载与解压>

<安装规则>

目标 Agent 为 Codex 时：

- ${CODEX_HOME}/skills/
- 如果 CODEX_HOME 未设置，使用 ~/.codex/skills/

目标 Agent 为 Qoder 时：

- ~/.qoderwork/skills/

目标 Agent 为 Claude Code 时：

- ~/.claude/skills/

其他 Agent：

- 使用其明确配置的 skills 目录；
- 如果支付前仍无法确定，必须先询问用户；
- 禁止自行猜测目录。

从 SKILL.md 的有效元数据中读取 Skill 名称。

对 Skill 名称进行安全校验：

- 不得包含 / 或 \；
- 不得为 . 或 ..；
- 不得包含路径穿越；
- 不得解析为 skills 目录之外的位置。

目标目录为：

<预期 skills 目录>/<Skill 名称>

安装前：

1. 将目标路径规范化；
2. 确认目标路径位于预期 skills 目录内；
3. 如果目标目录已存在，将旧目录移动为：

   <Skill 名称>.backup-<时间戳>

4. 禁止覆盖或删除旧版本；
5. 记录旧版本备份路径；
6. 再将新的 Skill 根目录安装到目标目录。

</安装规则>

<验证>

安装后必须执行以下验证：

1. 目标安装目录存在；
2. 目标安装目录位于预期 skills 目录内；
3. SKILL.md 存在；
4. SKILL.md 是普通文件且可读；
5. Skill 名称与目标目录匹配；
6. 能够成功读取 SKILL.md；
7. 已从 SKILL.md 提取用途、触发方式、必要参数和使用示例。

只有全部通过时：

INSTALLED=true
VERIFIED=true
CURRENT_STATE=DONE

如果验证失败：

- INSTALLED 不得标记为成功；
- 不得声称 Skill 可用；
- 保留旧版本备份；
- 报告具体失败步骤和当前安装状态。

验证成功后，清理本次下载和解压产生的临时文件。
不得删除旧版本备份。

</验证>

<最终回复>

只有 CURRENT_STATE=DONE 时才能输出成功回复。

成功回复必须包含：

- Skill 名称；
- 安装路径；
- 旧版本备份路径，没有则明确说明；
- 安装验证结果；
- 根据 SKILL.md 生成的使用方法；
- 至少一个使用示例；
- 是否需要重启或重新加载 Agent。

最终回复不得包含：

- 下载地址；
- fulfillment_proof 原文；
- 支付凭证；
- 完整订单响应；
- 交易号；
- 敏感支付信息。

如果未进入 DONE，必须明确说“安装未完成”，并指出停在哪个状态。
禁止只报告支付成功、履约成功或资源响应成功。

</最终回复>