用途:该技能用于让智能体连接并查询 Stripe API,获取客户的账单、支付状态、退款和订阅等分析数据。
连接与认证:基础地址为 https://api.stripe.com,使用 Bearer token 认证,凭证为按用户或组织配置的 STRIPE_SECRET_KEY,需在 Settings → Data sources 中配置。服务端库位于 server/lib/stripe.ts,路由位于 server/routes/stripe.ts,工具页面位于 app/pages/adhoc/stripe/(为工具页而非指标仪表盘)。
智能体操作:面向智能体的 Stripe 工作应使用 stripe 操作,不要从智能体直接调用 /api/stripe/*。可用模式包括:billing(参数 email、customerId、query、months,返回时间段内客户发票)、payment-status(email、customerId、query,返回近期 charges 与 payment intents)、refunds(email、customerId、query,返回客户相关退款)、subscriptions(email、customerId、query,返回活跃订阅)、billing-by-product(email、customerId、query、months,按产品聚合账单)。
API 路由:/api/stripe/billing(GET,参数 email、months 默认 6)、/api/stripe/payment-status(GET,email)、/api/stripe/refunds(GET,email)、/api/stripe/subscriptions(GET,email,返回全部订阅含活跃与非活跃)。所有路由内部会将 email 解析为 Stripe 客户 ID。
导出函数(server/lib/stripe.ts):getCustomersByEmail(email)、getInvoices(customerId, months?)、getCharges(customerId, limit?)、getPaymentIntents(customerId, limit?)、getSubscriptions(customerId)、getRefunds(customerId)。
客户端钩子(app/lib/api-hooks.ts):useStripeBilling、useStripePaymentStatus、useStripeRefunds、useStripeSubscriptions,均带 enabled 标志,仅在点击按钮时拉取数据。
注意事项:Stripe /v1/refunds 不支持 customer 过滤,库先获取客户 charges 再获取已退款 charges 的退款;一个 email 可能对应多个 Stripe 客户对象,路由会跨所有匹配客户聚合;金额以最小货币单位(分)表示,展示时需除以 100;缓存 TTL 为 5 分钟;expand 参数用于发票(line items)和订阅(price details)。
UI 模式:Stripe 页面为工具页,包含 email 输入框、四个操作按钮(Billing History、Payment Status、Refund Status、Subscriptions)以及显示最近一次操作结果的结果面板。