feat(gateway): 支持幂等 capture 重试

[Qiyuanqiii]

关联 Issue

Related to #235

背景与定位

#235 已确定：

• feat(adapters): add gateway client adapter kit #316 负责共享 Gateway client / 通用生命周期适配器
• feat(adapter): add Codex MCP gateway bridge #372 负责 stdio MCP Gateway bridge
• feat(adapters): 添加 Vercel AI SDK 记忆中间件 #470 负责 Vercel AI SDK 记忆中间件

本 PR 不再添加新的平台适配器，而是补充这些适配器共同依赖的 Gateway 运行时语义：POST /capture 的幂等重试保护。

现有适配器讨论已经明确将 tdai_capture 标记为“非幂等、有写副作用”。当客户端请求实际执行成功、但响应因超时或网络中断而丢失时，客户端无法安全重试。

问题根因

Gateway 在请求没有携带 messages 时，会根据 user_content 和 assistant_content 临时构造消息。

这些消息没有稳定时间戳，L0 recorder 会在每次请求中重新生成 Date.now()。因此同一轮 capture 被重试时，新时间戳可能越过 checkpoint cursor，被错误识别为新的消息并再次写入。

实现方案

• 为 CaptureRequest 增加可选 idempotency_key
• 幂等键限制为最多 128 个 UTF-8 字节，并拒绝控制字符
• 幂等作用域限定在同一 session_key
• 对请求载荷进行规范化并生成 SHA-256 指纹
• 合并同键、同载荷的并发请求，底层 capture 只执行一次
• 已完成请求在重放窗口内直接复用原始结果
• 重放响应返回 idempotency_replayed: true
• 同一键对应不同载荷时返回 HTTP 409
• 执行失败的请求不会进入缓存，允许客户端继续重试
• 不会为容量回收删除仍在执行的 capture
• 重放表最多保留 1,024 项，已完成结果最多保留 10 分钟

兼容性

未传入 idempotency_key 时，继续走原有 capture 路径，行为完全不变。

本 PR 不包含：

• 新的 Gateway HTTP client
• MCP server 或工具定义
• Dify、Codex、Claude、LangChain 等平台适配器
• 客户端自动重试策略
• 跨 Gateway 重启的持久化幂等记录
• user_id 租户隔离改造
• 对 feat(adapters): 添加 Vercel AI SDK 记忆中间件 #470 的任何修改

因此它是 #316、#372 和 #470 可以共同使用的独立 Gateway 协议增量，而不是另一套竞争性的 Adapter SDK。

文档

README 和 README_CN 增加了 retry-safe capture 的请求示例、冲突语义、容量和有效期边界。

验证

• 定向测试：1 个文件、7 项测试通过
• 完整测试：5 个文件、74 项测试通过
• 插件及三个脚本构建：通过
• git diff --check：通过

npm test -- src/gateway/capture-idempotency.test.ts
npm test
npm run build
git diff --check origin/main...HEAD

定向测试覆盖：

• 并发请求合并
• 已完成请求重放
• 相同键不同载荷冲突
• 失败后使用原键重试
• 会话级键隔离
• 重放窗口过期
• 容量满时保护执行中的 capture
• 规范化载荷指纹
• 幂等键长度与控制字符校验

验证截图

[Maxwell-Code07]

Thank you for submitting this PR and participating in Tencent Rhino-bird Open-source Training Program!
We have successfully received your submission. The program is currently in full swing, and we will complete the Code Review for you as soon as possible. Please keep an eye on the status notifications for this PR so you can follow up promptly once the review feedback is provided.
Thanks again for your contribution and open-source spirit! 🚀

[YOMXXX]

Approved.

I verified this PR locally on the branch:

• pnpm vitest run src/gateway/capture-idempotency.test.ts — passed: 1 file, 7 tests
• pnpm test — passed: 5 files, 74 tests
• pnpm build — passed
• git diff --check HEAD~1..HEAD — passed

The idempotency implementation is scoped by session key, fingerprints the request while excluding only idempotency_key, coalesces in-flight duplicate requests, rejects same-key/different-payload reuse with a conflict, and drops failed entries so retries can proceed. The bounded TTL store and validation rules look appropriate for this gateway-level retry-safety feature.