| name | third-party-flow |
| description | 接入第三方服务（支付 / IM / OAuth / 短信 / OSS 等）。强制输出 Vendor 适配层，
应用层只用领域接口，不直接调用 SDK；强制密钥/Webhook 安全审计；强制沙箱 + 失败
重放剧本。
Use when integrating with third-party services or SDKs.
Voice triggers: "接第三方", "/third-party-flow", "接入 SDK", "对接".
|
third-party-flow
适用场景
接入支付、IM、OAuth、短信、OSS、地图、AI Provider 等任意第三方服务/SDK。
前置条件
确认 _playbook.md Part B.3 启动参数；额外 vendor_name、vendor_doc_url、use_case（一句话描述用途）。
流程步骤
阶段 0 · 上下文初始化
move_agent_to_root；建知识库目录（极简 META.md）。
阶段 1 · 文档与契约调研
- 读官方文档；列出能力 / 限制 / 计费 / 配额 / 错误码
cursor-ide-browser 打开 vendor 文档示例页面，必要时跑一遍其 demo- 输出
VENDOR_NOTES.md：能力清单、关键限制、错误码、SLA、计费模式
阶段 2 · 安全与合规检查
prompt: "本次接入是否涉及："
options:
- "用户敏感数据（身份证 / 手机号 / 支付 / 健康）"
- "Webhook 回调（vendor 反向推送给我们）"
- "需要存储 vendor 颁发的 token / refresh_token"
- "以上都不是"
allow_multiple: true
任一勾选 → 阶段 7 必做 /cso，且 IMPLEMENTATION_PLAN.md 必须含密钥管理与回调签名校验方案。
阶段 3 · 适配层方案 + 卡点
- 设计领域接口（
PaymentGateway、SmsSender 等抽象）
- vendor SDK 仅在适配层使用，应用层一律调领域接口
- 输出
IMPLEMENTATION_PLAN.md：适配层接口 + DTO 转换 + 错误映射 + 重试/超时策略
- 卡点：
prompt: "适配层方案如下：[一句话摘要]。请确认："
options:
- "方案 OK，进入实现"
- "需要修改方案（说明）"
- "需要先做更多 vendor 调研"
阶段 4 · 沙箱实现
- 用 vendor 的 sandbox / test mode 跑通最小路径
- 派
backend-agent（适配层）+ test-agent（契约 + 错误码 + Webhook 签名）
- commit：
feat(scope): 接入 [vendor] 沙箱
阶段 5 · 失败剧本演练
按 vendor 错误码列表，主动注入失败：网络超时 / 401 / 429 / 5xx / 签名错误 / 重复回调；
确认每种情况都有合理处理（重试 / 降级 / 告警）。输出 FAILURE_PLAYBOOK.md。
阶段 6 · 切到生产 vendor
- 切换密钥/endpoint
- 在预发跑一次最小金额/最小动作的真实调用
- 确认账单/日志/监控就位
阶段 7 · 自查
/cso（必做：密钥不入库、Webhook 签名校验、敏感字段日志脱敏）/qa + /review
阶段 8 · 上线
/ship → /land-and-deploy → /canary（重点监控 vendor 错误率、回调延迟）。
阶段 9 · 复盘
append _lessons.md：vendor 坑点 / 错误码处理模式 / 限流抗压数据。
错误处理
- vendor 文档与实际行为不符 → 在
VENDOR_NOTES.md 标注，必要时联系 vendor 支持
- 沙箱与生产差异大 → 阶段 6 拉长真实调用验证窗口
- 密钥误提交到 git → 立即吊销 + 重发；按 _playbook.md Part B.5"事故应对"处理
产物清单
META.md、VENDOR_NOTES.md、IMPLEMENTATION_PLAN.md、适配层代码、FAILURE_PLAYBOOK.md、/cso 报告、PR 链接。
支持的修饰符
- M3 新项目 → 阶段 4 同时落地适配层模板，写入
ARCHITECTURE.md，便于未来同类 vendor 复用
- M4 数据库迁移（如要存储 vendor 数据/log）→ 必出
MIGRATION_PLAN.md
详细 delta 见 _playbook.md Part D。
与其他 skill 的关系
- 通常被
/dev-flow 路由到（也可被用户直接触发）
- 强依赖
/cso
- 派发：
backend-agent、test-agent
- 自查：
/qa、/review、/cso
- 上线：
/ship、/land-and-deploy、/canary
附录
