stripe

Stripe 运营

使用此技能读取 Stripe 账户状态，并在获得明确确认后，执行受保护的更改：账户余额、付款意图、订阅和取消订阅。此技能是 Stripe 平台的工具技能。在应用中集成 Stripe 付款属于集成开发；此技能负责日常 Agent 工作流：回答“我们的余额是多少？”“哪些付款已成功？”“有哪些有效订阅？”并执行已确认的取消操作。

操作约定

1. 先只读。 余额、付款和订阅查询可自由执行，且绝不会更改任何内容。随附的 stripe-cli 脚本主要用于这些读取操作。
2. 每次更改都要设防。 更改状态的操作——取消订阅——必须通过 stripe-cli 获得明确的人工指令，并使用 --dry-run 预览以及 --yes 确认。取消订阅会产生财务影响和账单后果：操作前请确认订阅、时间安排和影响。
3. 遵守读取范围限制。 Stripe 使用 limit 和 has_more 分页；只读取任务所需的内容，不要翻页过多。stripe-cli --limit 会限制每次列表查询。
4. 控制证据范围。 引用简短 ID、金额和状态；绝不要在聊天中完整展示 API 密钥、客户数据或原始负载。金额会按货币格式化，JSON 则保留原始整数和货币以供审计。
5. 将资金数据视为敏感信息。 余额、付款和订阅详情均为财务记录；只引用问题所需的信息，绝不泄露完整的银行卡或客户数据。

stripe-cli 脚本

scripts/stripe-cli 是一个面向 Agent、仅使用标准库的 Stripe API 命令行工具。它遵循先只读原则：余额、付款和订阅是主要功能；唯一的更改操作受到保护。

stripe/scripts/stripe-cli --help                          # no key or network needed
stripe/scripts/stripe-cli --json balance show
stripe/scripts/stripe-cli --json --limit 20 payments list
stripe/scripts/stripe-cli --json --limit 20 subscriptions list
stripe/scripts/stripe-cli --json subscriptions get --id sub_123
stripe/scripts/stripe-cli subscriptions cancel --id sub_123 --dry-run   # preview
stripe/scripts/stripe-cli subscriptions cancel --id sub_123 --yes       # confirmed

退出代码：0 表示成功，1 表示 API 错误或检查失败，2 表示用法错误。取消操作受到保护：若未使用 --dry-run 或 --yes，脚本会以退出代码 1 拒绝执行，且绝不会调用 API。读取操作受 --limit 限制（默认值为 20，最大值为 100）。

操作流程

1. 明确问题范围：这是读取操作（余额、付款、订阅），还是更改操作（取消）？先通过读取功能找到目标对象。
2. 在范围内读取：使用 balance show 查看可用和待处理资金；使用 payments list 查看近期付款意图；使用 subscriptions list/subscriptions get 查看有效订阅及其项目。
3. 梳理答案：将问题对应到证据（金额、状态、客户、周期结束日期）。
4. 经确认后操作：仅在有人明确要求更改后，使用 --dry-run 预览，并使用 --yes 确认。
5. 验证：重新读取订阅，确认已设置 cancel_at_period_end（在周期结束时取消），并说明客户在该日期前仍可继续使用服务。

读取范围：余额、付款、订阅

• 余额（GET /balance）：按币种列出可用余额和待处理余额。账户资金的只读快照。
• 付款（GET /payment_intents）：最近的付款意向，包含金额、币种、状态（succeeded、requires_action 等）和客户。结果受 --limit 限制；has_more 表示是否有更多记录因达到上限而未显示。
• 订阅（GET /subscriptions、GET /subscriptions/{id}）：活跃订阅，包含状态、客户、周期结束时间和项目（价格、金额、间隔）。这是取消前的读取操作。

Stripe 金额使用最小货币单位：JPY 等普通的零小数位币种以整数显示，其他币种显示两位小数。UGX 和 ISK 为保持向后兼容，API 值仍保留两位小数，因此金额 500 显示为 5.00 UGX 或 5.00 ISK。JSON 会在格式化后的显示值旁保留原始整数（amount_minor，订阅价格则为 unit_amount_minor）和币种。HUF 和 TWD 的收费/价格记录使用两位小数（整单位规则适用于手动付款）。Stripe 不支持用于展示的三位小数币种，因此会拒绝这些币种。来源和详情请参阅 references/01-stripe-read-operations.md。

受保护的变更：取消订阅

• subscriptions cancel --id sub_... --dry-run 可预览取消操作；--yes 用于确认并提交 cancel_at_period_end=true——这是安全默认选项，会安排在周期结束时取消（客户在此之前仍可使用服务），而非立即取消。
• 脚本会验证 Stripe 是否已确认变更（响应中的 cancel_at_period_end: true），然后才报告成功；如果不匹配，则会引发错误，且不会假定状态已变更。
• 在周期结束前将 cancel_at_period_end=false，即可撤销已安排的周期结束取消。本工具的变更范围刻意不包含立即取消和退款——这需要由人工在 Stripe 控制面板中操作，或通过专用集成处理。

访问模型和凭据

• Stripe 使用密钥（sk_...）或受限密钥（rk_...）进行身份验证。读取范围请使用限定为只读权限的受限密钥（balance:read、payment_intents:read、subscriptions:read）；只有在确实需要取消订阅时才添加 subscriptions:write。
• 密钥分为正式环境密钥和测试环境密钥（sk_live_/sk_test_）。切勿将正式环境密钥用于测试数据，或反之；运行任何可能影响真实收费的操作前，请先确认密钥类型。
• 将密钥存储在 STRIPE_API_KEY 中，切勿将其放入代码、聊天内容或提交记录中。若密钥泄露，请立即在 Stripe 控制面板中轮换。

参考资料索引

加载时机	参考资料
来源、刷新流程	references/00-source-index.md
端点、分页、取消语义、错误	references/01-stripe-read-operations.md

包含的文件

• scripts/stripe-cli：受限、仅依赖标准库的 CLI（余额、付款列表、订阅列表/获取、受保护的取消操作；--json；--limit；通过 --dry-run/--yes 控制变更）。
• tests/test_stripe_cli.py：针对 Stripe API 存根的 14 项确定性测试，包括 USD/JPY 格式化、特殊币种规则、原始单位保留和变更门控。
• references/：带日期的来源索引和 Stripe 读取操作参考资料。
• evals/evals.json：用于评估 Agent 运行输出质量的 7 个用例。

验证边界

声明	最低证据要求
余额为最新状态	stripe-cli balance show --json 按货币返回可用余额和待处理余额
付款已成功	stripe-cli payments list --json 显示状态为 succeeded 的支付意图
订阅处于有效状态	stripe-cli subscriptions get --json 返回状态 active 和周期结束时间
取消操作已被接受	stripe-cli subscriptions cancel --yes 以状态码 0 退出，且响应包含 cancel_at_period_end: true
某项变更可以安全执行	stripe-cli subscriptions cancel --dry-run 打印确切的订阅 ID

硬性边界

• 未收到人工指示、未通过 --dry-run 预览且未使用 --yes 确认时，绝不取消订阅——取消会影响计费。
• 可执行的变更仅限于将取消安排在周期结束时生效。退款、立即取消和扣款操作均不在范围内。
• 读取数据时绝不翻页超过 --limit；绝不在聊天中输出完整 API 密钥、客户数据或原始负载。
• 此技能用于操作 Stripe API。它不会将支付功能集成到应用中，也不涵盖其他支付处理商。

何时不使用

• 将 Stripe 支付功能集成到应用中（Checkout、代码中的 Payment Intents、应用的 Webhook、计费逻辑）——这是集成开发；请参阅 backend-engineering。
• 管理 Stripe 控制面板（账户设置、银行账户、争议、税务登记）——请使用 Stripe Dashboard。
• 退款、立即取消或扣款操作——这些操作有意被排除在此技能的受保护变更范围之外；应由人工在控制面板中决定，或通过专用集成处理。
• 其他支付处理商（Braintree、Adyen、PayPal）——每种服务都有自己的 API 和工具；此技能仅涵盖 Stripe。