跳到主要内容

Stripe Link Cli

通过 Stripe Link 实现 agent 支付——支持卡片、SPT 与审批流程。

Skill 元数据​

Source可选 — 使用 kopi skills install official/payments/stripe-link-cli 安装
Pathoptional-skills/payments/stripe-link-cli
Version0.1.0
AuthorTeknium (teknium1), KOPI AI AGENT
LicenseMIT
Platformslinux, macos
TagsPayments, Stripe, Link, Checkout, MPP
Related skillsmpp-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 会在首次运行时逐步引导用户完成:

无需任何环境变量——认证状态由 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 Elementscard(默认)
在 www-authenticate 中返回包含 method="stripe" 的 HTTP 402shared_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 表示已安装并已登录。