agent-stripe 用于调查 Stripe 支付事故、发票问题、订阅计费、webhook/事件问题、争议、退款、余额、关联账户或组织账户上下文。它设计为只读优先，涉及真实模式操作风险较高，不建议在聊天中粘贴 Stripe API 密钥；应让用户在本地运行 agent-stripe auth add <profile> --form 以便密钥直接进入系统对话框，替换已存密钥用 agent-stripe auth update <profile> --form。可用 --context 指定关联账户或组织账户路径，只有用户明确需要被脱敏的 Stripe 响应字段时才用 --expose <path,key>，已存储的配置密钥不会被该标志暴露。
常用入口包括 agent-stripe usage、agent-stripe investigate usage、agent-stripe auth list、agent-stripe auth check、agent-stripe config show、agent-stripe balance get。当用户以事故语言提问而非指定 Stripe 对象时，优先使用 investigate 命令，例如 investigate resolve、customer-context、customer-card-payment、invoice-payment、subscription-renewal、collection-risk、incoming-payment、duplicate-charge、statement-descriptor、action-required、refund-settlement、checkout-session、outgoing-payment、ledger、payout-failure、refund-recovery、account-health、account-events、connect-readiness 等。直接探索可用资源命令，如 customers list、payment-intents get、charges get、invoices get、subscriptions get、accounts self/list/get、accounts-v2 get/list、events-v2 list、api get 等。
本地测试可运行 mockstripe 并把 AGENT_STRIPE_BASE_URL 设为其基础 URL。Stripe 有两套关联账户命名空间且都以 acct_ 前缀：Connect v1 用 accounts 命令，Accounts v2/UA2 用 accounts-v2 命令。命名空间未知时不要猜测，可用 investigate resolve 或 account-health 探测，二者先试 v2 再回退 v1 并说明由哪个命名空间应答。不要把 v2 账户用 v1 词汇描述，v2.core.account 没有 charges_enabled 或 payouts_enabled。账户资格与要求变更只以 v2 thin 事件发出，agent-stripe events list 不会显示，应使用 investigate account-events 或 events-v2 list。资金流动与命名空间无关，transfers、payouts、balance transactions、application fees 都是 /v1 端点，可接受 v2 账户 ID。
输出默认 NDJSON，单资源 get 也是一行，--format json 输出美化对象；错误含 fixable_by 和提示。列表命令默认返回紧凑摘要并脱敏敏感字段，需要原始脱敏对象时加 --full。调查输出使用 evidence 记录，展开的嵌套对象作为独立 entity 记录，父数据中以 ID 替代。长字符串可能被截断，可用 --expand-field 或 --full 重跑，但截断控制不覆盖脱敏。429 响应自动重试并带退避与抖动，--max-retries 0 可关闭，--debug 查看重试记录。非机密配置元数据在 XDG 配置中，API 密钥存在 Keychain，认证命令可显示 credential_type 但不显示密钥。更多细节可参考 references/commands.md、investigations.md、output.md 和 scenarios.md。