Stripe Link Cli
通过 Stripe Link 实现 agent 支付——支持卡片、SPT 与审批流程。
Skill 元数据
| Source | 可选 — 使用 kopi skills install official/payments/stripe-link-cli 安装 |
| Path | optional-skills/payments/stripe-link-cli |
| Version | 0.1.0 |
| Author | Teknium (teknium1), KOPI AI AGENT |
| License | MIT |
| Platforms | linux, macos |
| Tags | Payments, Stripe, Link, Checkout, MPP |
| Related skills | mpp-agent, stripe-projects |
参考:完整的 SKILL.md
以下是 Kopi Agent 在触发此 skill 时加载的完整 skill 定义。也就是 skill 处于激活状态时 agent 所看到的指令内容。
Stripe Link CLI Skill
封装 @stripe/link-cli,使 Kopi Agent 能够代表用户使用一次性虚拟卡或共享支付令牌(Shared Payment Token,SPT)完成购买。每一笔支出都必须在 Link 移动端/网页应用中经过审批后才能执行——Kopi Agent 无法自行批准。
目前仅限美国地区使用(Link 账户要求)。上游 CLI 不支持 Windows——此 skill 的限制条件为 [linux, macos]。
适用场景
触发短语:
- "buy X"、"pay for X"、"make a purchase"、"complete checkout"
- "get me a card"、"I need a payment method"
- "log in to Link"、"connect my Link wallet"
- 来自商家 API 的 HTTP 402 响应,且
www-authenticate: ... method="stripe"
如果用户想要的是付费 API 调用(HTTP 402、无结账表单),则 card 路径不适用——应通过同一 skill 使用 SPT,或转交给 mpp-agent skill。
前置条件
PATH上可用的 Node.js 20+(node --version)- 位于美国(Link 账户要求)
Link 账户、支付方式和支出审批应用无需在 Kopi Agent 尝试支付前预先设置——CLI 会在首次运行时逐步引导用户完成:
- Link 账户(https://app.link.com)——在首次
link-cli授权时创建/关联 - 至少一种支付方式——在首次运行时于 https://app.link.com/wallet 添加
- Link 移动端/网页应用——在首次支出请求发出时打开以进行审批
无需任何环境变量——认证状态由 CLI 在其自身的配置目录中本地保存。
安装
一次性全局安装:
npm install -g @stripe/link-cli
也可以通过 npx @stripe/link-cli 临时调用。下文的 skill 使用已安装的 link-cli 形式。
运行方式
所有命令均通过 terminal 工具运行。CLI 会自动检测非 TTY 调用方,并默认输出紧凑的 toon 内容——适合模型读取。如果某个步骤需要结构化字段,请传入 --format json。
发现可用命令:link-cli --llms-full。
在调用前先获取命令的 schema:link-cli <command> --schema。
操作流程
1. 检查 / 建立认证
link-cli auth status
如果尚未认证,请使用清晰的客户端名称登录(该标签会显示在用户的 Link 应用中):
link-cli auth login --client-name "Kopi Agent" --interval 5 --timeout 300
--interval/--timeout 形式会在内联轮询,因此 agent 无需自行管理 _next 步骤。将验证 URL + 短语打印给用户,然后等待 CLI 返回。
在 auth status 确认登录成功之前,不要继续进行后续步骤。
2. 在创建支出请求前评估商家
确定凭据类型:
| 商家端 | --credential-type |
|---|---|
| 标准网页结账表单 / Stripe Elements | card(默认) |
在 www-authenticate 中返回包含 method="stripe" 的 HTTP 402 | shared_payment_token |
返回不含 method="stripe" 的 HTTP 402 | 不支持——停止操作 |
对于 402 响应,不要手动解码 challenge。请直接传入原始 header:
link-cli mpp decode --challenge '<full WWW-Authenticate header>'
这会验证 challenge 并提取网络 ID + 解码后的请求体。
3. 列出支付方式与配送信息
link-cli payment-methods list
link-cli shipping-address list
除非用户另有指定,否则使用第一条记录。来自 payment-methods list 的 id 将作为下一步的 --payment-method-id。
4. 创建支出请求
在执行此命令前,先与用户确认最终总金额。金额单位为分(cents)。
link-cli spend-request create \
--payment-method-id <pm_id> \
--merchant-name "<name>" \
--merchant-url "<url>" \
--context "<one sentence: what is being purchased and why>" \
--amount <cents> \
--line-item "name:<item>,unit_amount:<cents>,quantity:1" \
--total "type:total,display_text:Total,amount:<cents>" \
--request-approval
对于 MPP 商家,请添加 --credential-type shared_payment_token。
--request-approval 会向用户的 Link 应用发送通知并轮询,直到用户批准或拒绝。若被拒绝 / 超时,CLI 会以非零状态退出。
5. 获取凭据——务必安全处理
不要将卡片详情打印到 stdout。 请使用 --output-file,以确保 PAN 绝不会进入 agent 的对话记录或日志:
link-cli spend-request retrieve <lsrq_id> \
--include card \
--output-file /tmp/link-card.json \
--format json
该文件以 0600 权限写入;stdout 仅显示经过脱敏的字段(卡组织、后四位、有效期)以及一个 card_output_file 路径。
6. 使用凭据
-
对于网页结账:将文件路径交给用户,或者传递给能直接从磁盘读取并填写表单的浏览器驱动工具。切勿
read_file或cat将卡片文件读入 agent 的推理上下文。 -
对于 MPP 商家:
link-cli mpp pay <merchant-url> \
--spend-request-id <lsrq_id> \
--method POST \
--data '<json body>'
7. 清理
购买完成后立即删除卡片文件:
rm -f /tmp/link-card.json
可选:改为以 MCP 服务器运行
@stripe/link-cli --mcp 会通过 stdio 将相同的命令以 MCP 工具的形式暴露出来。要将其注册到 Kopi Agent 原生 MCP:
kopi mcp add stripe-link --command "npx" --args "@stripe/link-cli --mcp"
随后 kopi mcp list 应显示 stripe-link。相同的审批规则同样适用——MCP 不会绕过 Link 应用的审批步骤。
常见陷阱
- 仅限美国。 在美国境外,
auth login会失败。请告知用户,不要反复重试。 - 卡片 PAN 绝不能进入 agent 上下文。 每次都要使用
--output-file。如果你之前在未使用该参数的情况下获取了数据,仅立即执行link-cli auth logout是不够的——该卡虽是一次性使用的,但轮换卫生习惯依然很重要。 --request-approval会一直阻塞,直到用户操作。 如果用户正在睡觉,CLI 将会超时。请提前说明这一点。- 多步
_next命令。 某些命令会返回_next.command,必须执行它们才能继续。如有疑问,优先使用内联轮询参数(--interval/--timeout)。 - 在非 TTY 模式下,输出格式默认为
toon。 用于文本内容没问题,但如果后续步骤需要解析特定字段,请传入--format json。 - 不要默认使用
card。 第 2 节中的商户评估步骤之所以存在,就是因为选错凭据类型会导致购买静默失败,或者泄露超出必要范围的数据。
验证
link-cli --version && link-cli auth status
退出码 0 表示已安装并已登录。