opencodex 接入 Amazon Bedrock Runtime：原生 Converse/ConverseStream 适配器与可选 SigV4 签名设计解析

【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载opencodex 作为面向 OpenAI Codex 与 Claude Code 的通用 Provider 代理其非 OpenAI Provider 追赶计划devlog/_fin/260717_non_openai_provider_chase/中的 WP14 阶段专门设计了原生 Amazon Bedrock Runtime 适配器 可选 SigV4 签名这一技术路线。本文以该工作阶段文档为骨架结合仓库中已落地的事件流解码基础设施与适配器解析链路完整解读其目标、文件改动地图、架构约束、激活场景、验证方式与终局判定标准帮助读者理解在代理层新增 AWS 原生推理通道时的设计决策与工程边界。背景Bedrock 的双路径接入策略在进入 WP14 之前opencodex 的 Bedrock 接入遵循先低成本、后原生的依赖顺序。整个追赶计划的依赖地图见 000_plan.md明确将 Bedrock 拆成两个独立工作阶段阶段文档目标依赖WP12120_bedrock_mantle.mdOpenAI 兼容的 Bedrock Mantle 通道Responses 协议 Bearer 密钥keyed Responses provider contractWP14140_bedrock_runtime_sigv4.md原生 ConverseStream/SigV4 通道C4 认证边界与事件适配器WP12 建立的 Mantle 通道复用https://bedrock-mantle.region.api.aws/v1这一 OpenAI 兼容端点使用 Bearer API Key 即可接入是成本最低的可行路径而 WP14 则完全不同——它面向 Bedrock Runtime 的原生 Converse/ConverseStream 协议走application/vnd.amazon.eventstream二进制事件流认证上不仅支持 Bearer 密钥还可选升级为 AWS SigV4 签名。二者的边界在 120_bedrock_mantle.md 中被严格划清No SigV4 or native Converse event parsing in WP12WP12 不包含 SigV4 或原生 Converse 事件解析同时 140_bedrock_runtime_sigv4.md 也写明其目标是仅为 Mantle 无法满足的具体模型或功能添加原生适配器。目标与依赖何时才需要原生 Converse 适配器WP14 的目标定义非常克制其核心依赖前置条件如下Add a native Converse/ConverseStream adapter only for concrete models or features not satisfied by Bedrock Mantle. Start with Bedrock Bearer keys; add SigV4 only when an IAM/production requirement is recorded.翻译过来即两条关键决策原生适配器不是默认选择只有当某个具体模型或功能在 Mantle 通道上不可用时才需要 Converse/ConverseStream 原生通道。仓库中src/generated/model-metadata.ts维护着amazon-bedrock的模型元数据含anthropic.claude-3-5-haiku-20241022-v1:0、anthropic.claude-3-5-sonnet-20240620-v1:0等 Claude 系列及上下文窗口、价格信息并在COST_VENDOR_PRIORITY中登记了amazon-bedrock供应商——哪些模型走 Mantle、哪些必须走 Runtime由实际可用性决定。SigV4 是条件性子任务第一版原生通道使用 Bedrock Bearer 密钥即可打通SigV4 签名只有在记录到真实的 IAM/生产环境需求后才启用绝不让签名成为阻塞 Converse 支持的理由。这种先 Bearer 后 SigV4、先可用后加固的顺序与 000_plan 中记录的dead hypothesis已证伪假设直接呼应——最初曾假设接入 Bedrock 必须从定制 SigV4 适配器开始而 Mantle 的 Responses 通道与 Bearer 密钥证明存在更低成本的接入路径因此原生 Runtime 被降级为条件性工作项。C4 循环边界无凭据、无边界就不跑真实调用由于涉及 AWS 凭据与真实线上请求WP14 被提升到 C4 安全等级并在进入实施B 阶段之前设置了一道硬性前置门槛Before B, P must state credential source, allowed AWS regions/accounts, network scope, write scope, maximum live requests/cost, and wall-clock bound. No unattended live call runs without those bounds.即在 P计划阶段就必须明确声明以下六项边界缺一不可凭据来源Bearer 密钥还是 IAM 凭据链允许的 AWS 区域/账户限定可访问的区域白名单与账户范围网络范围允许的出站网络目标写入范围允许的写操作边界最大并发请求/成本上限防止真实调用失控的预算墙上时钟界限每次真实调用的时间上限。这与 000_plan.md 中Cross-cutting invariants横切不变量里的规则一致C4 阶段不得在无明确凭据/写入/时间边界的情况下无人值守启动C4 phases cannot begin unattended without explicit credential/write/time bounds。Diff map 全解析文件级改动地图WP14 的 Diff map 以Action | Path | Before | After四列形式列出了完整的改动清单这是整个计划的可执行核心。整理如下Action路径Before现状After目标NEWsrc/adapters/bedrock.ts无原生适配器构建 Converse/ConverseStream 请求把 system/messages/images/tools/tool results/reasoning/usage/stop reasons 映射为 OCX 事件NEWsrc/adapters/bedrock-eventstream.ts无 AWS event-stream 解码器有界帧解码器带 CRC/长度校验、contentBlockIndex状态、异常帧、中止与终止处理NEWsrc/aws/credentials.ts无直接 AWS 凭据归属仅在 SigV4 获批后按明确优先级解析 env/shared config/container/metadata 凭据默认不 shelling outNEWsrc/aws/sigv4.ts无签名器仅在获批后canonical request、signed headers、session token、region/service scope、clock-skew-safe 测试MODIFYsrc/server/adapter-resolve.ts无bedrockadapter case为 registry id 构造原生适配器MODIFYsrc/providers/registry.tsWP12 之后仅有 Mantle新增bedrock-runtime要求 region 与 model/inference-profile ids认证模式区分 Bearer 密钥与 SigV4 凭据MODIFYsrc/types.ts无 AWS region/credential 配置增加窄化的 Bedrock 字段绝不做通用密钥袋secret bagMODIFYsrc/cli/provider.ts、src/server/management-api.ts、gui/src/components/AddProviderModal.tsx、gui/src/provider-payload.ts、gui/src/i18n/en.ts、gui/src/i18n/ko.ts、gui/src/i18n/zh.ts、gui/src/i18n/de.ts无原生 AWS 输入项region、model/profile id、Bearer-vs-SigV4 模式、脱敏后的就绪状态NEWtests/bedrock-adapter.test.ts无请求映射 fixturemessages、image、tools、tool results、inference config、stop/usage/errorsNEWtests/bedrock-eventstream.test.ts无解码器 fixture分片帧、多索引、CRC/长度失败、异常、取消、终端前 EOFNEWtests/aws-sigv4.test.ts无签名 fixture仅在 SigV4 构建时AWS 官方 canonical 向量、session token、path/query 编码、时钟边界NEWtests/bedrock-runtime-e2e.test.ts无原生中继证明本地 event-stream 服务器证明完整 Responses 桥接无需 AWS 凭据真实冒烟测试单独设门禁与现有代码结构的衔接点Diff map 中列出的两个 MODIFY 文件在仓库中已有明确实现可以据此理解改动落点src/server/adapter-resolve.ts其中的resolveWireProtocolOverride负责按硬 pin → 每模型覆盖 → registry 默认 → provider 自身适配器的优先级解析某模型应使用的 wireresolveAdapter则通过createRegisteredAdapter(providerConfig, ...)为解析后的配置构建适配器。WP14 要做的为 registry id 构造原生适配器就是在这一适配器解析链路上新增bedrock分支。src/providers/registry.ts作为计划中Registry 是 preset 唯一事实来源的枢纽registry → derive → CLI/管理 GUIbedrock-runtimepreset 的 region、model/inference-profile id 校验与 Bearer/SigV4 认证模式区分都会在此收敛。架构约束四条不可逾越的工程红线WP14 明确列出了六条架构约束其中四条直接决定原生适配器的实现形态协议归属隔离不要把 Kiro 适配器代码当作 Bedrock Runtime 代码使用只在所有权审查之后复用小型协议辅助函数。这一条在仓库中有极强的现实对应——src/adapters/kiro/目录下是一整套 CodeWhispererGenerateAssistantResponse适配器其流解析同样基于 AWS event-stream但协议语义完全不同绝不能混用。事件按contentBlockIndex关联事件 payload 通过contentBlockIndex关联到对应的内容块禁止使用单一全局当前块one global current block is forbidden。这是 Converse 流式响应中文本、工具调用、推理内容交错出现的正确处理前提。有界分配 严格 CRC帧与聚合大小在分配内存之前就必须有界CRC/长度不匹配属于协议错误绝不允许忽略。这直接对应激活场景中损坏 CRC、超大长度、异常帧、EOF-before-stop 各自产生有界错误并释放 reader的要求。模型特定参数受控模型专属参数只能通过经过审计的 provider/model policy 进入additionalModelRequestFields。Bearer 优先Bearer API 密钥可覆盖第一条可用的原生路径SigV4 保持为条件性子任务。无新 SDK 依赖不引入新的 AWS SDK 依赖除非通过 P 阶段的依赖/安全审查并取得 C4 新依赖规则的批准。基础设施佐证事件流解码器已在仓库落地WP14 规划的src/adapters/bedrock-eventstream.ts依赖的有界帧解码器能力仓库中已有可复用的底层实现——src/lib/eventstream-decoder.ts。该文件是application/vnd.amazon.eventstream解码器注释明确声明它同时服务两类 AWS event-stream 提供商kiroCodeWhisperer GenerateAssistantResponse与 amazon-bedrockConverse且是两者的基础依赖foundational dependency。其实现要点与 WP14 的架构约束完全同构线格式解析帧由[total length u32][headers length u32][prelude CRC32][headers][payload][message CRC32]组成全部整数大端序头部分为[name_len u8][name utf8][value_type u8][value …]序列。有界校验MAX_MESSAGE_LEN 16 * 1024 * 1024、MAX_HEADERS_LEN 128 * 1024decodeMessage对 total length、prelude CRC、message CRC、headers 越界逐项校验任何不匹配直接抛错。CRC32 实现IEEE/zlib 多项式0xEDB88320与aws-crypto/crc32兼容。异步流解码decodeEventStream消费ReadableStreamUint8Array处理任意 chunk 边界分片帧并在finally中先reader.cancel()再releaseLock()避免早期终止turn abort、HTTP/2 中段重置留下悬空的 pending read 导致 Bun 环境出现无法捕获的unhandledRejection。对应的 tests/responses/eventstream-decoder.test.ts 已覆盖message CRC mismatch、prelude CRC mismatch、headers 越界、超大帧、截断 header、多帧跨 chunk 边界、逐字节分片、CRC 已知向量zlib.crc32(hello) 0x3610a686、消费者提前终止时取消底层 reader、干净完成时正常关闭等场景——这些正是 WP14 中tests/bedrock-eventstream.test.ts计划覆盖的 fixture 类型的先导验证。Kiro 适配器侧的 src/adapters/kiro/stream.ts 则展示了该解码器在真实流解析中的用法import { decodeEventStream } from ../../lib/eventstream-decoder可视为 Bedrock 原生适配器流解析的参照系——但需牢记架构约束第一条只复用小型协议辅助不照搬整套 Kiro 逻辑。激活场景四条可验证的行为契约WP14 定义了四条激活场景作为适配器实现是否达标的行为契约交错块正确归位交错的 tool/text/reasoning event-stream 块映射到正确的 OCX item ids并只产生一个 terminal 事件。协议错误有界化损坏 CRC、超大长度、异常帧、EOF-before-stop 各自产生有界错误并释放 reader不得挂死或泄漏。认证模式纯净Bearer 模式只发送Authorization: BearerSigV4 模式启用时发送 canonicalAuthorization、date、payload hash、session token且任何情况下都不记录 secrets——这与 000_plan.md 中不记录任何凭据、token 响应体、签名材料或工作区 URL 查询参数的横切不变量一致。证明 lane 必要性某个在 Mantle 上不可用、但在 Runtime 上可用的模型是这条原生通道存在价值的直接证据。验证方式本地有界测试 门禁式真实冒烟WP14 给出的验证命令如下bun test tests/bedrock-adapter.test.ts tests/bedrock-eventstream.test.ts tests/bedrock-runtime-e2e.test.ts bun test tests/aws-sigv4.test.ts # 仅当 SigV4 存在时 bun run typecheck bun run privacy:scan bun run build:gui其设计要点是本地验证不依赖 AWS 凭据tests/bedrock-runtime-e2e.test.ts通过本地 event-stream 服务器证明完整的 Responses 桥接链路真实线上冒烟live smoke则单独设门禁——这与 150_integration_closeout.md 中缺失真实凭据记为NEEDS_HUMAN而不是静默通过的关闭原则保持一致。privacy:scan则用于确保新增的凭据解析、签名与请求构建路径不会把 secret 泄漏进日志。终局判定五个明确的退出状态与整个追赶计划的统一约定一致WP14 以五个终局状态收口DONE指定的 Mantle 缺口成立、原生适配器/事件流负向测试套件、认证模式、本地 E2E 与有界真实冒烟全部通过。NOOPMantle 已满足全部指定需求不新增原生适配器即该工作阶段完整执行了 P→A→B→C→D 循环后证明无需改动。NEEDS_HUMAN缺少经批准的 AWS 账户/模型/区域或 SigV4 需求决策未定。UNSAFE凭据解析/签名无法满足 secret、SSRF 或依赖策略。BLOCKED所需模型权限或区域不可用。这套判定体系的价值在于允许诚实地不做。NOOP不是跳过循环的借口而是经过验证后的记录在案的结果——正如 000_plan 所强调的一个阶段以NOOP结束当且仅当探针证明现有实现已满足契约。在追赶计划中的收尾关系WP14 完成后其证据链将汇入 WP15150_integration_closeout.md的关闭矩阵每个 provider 记录需要包含 registry id、adapter、认证模式、base/region 规则、静态与动态模型、图片/工具/流支持、超时/重试策略、聚焦测试、真实冒烟日期与终局状态。也就是说WP14 的 Diff map 不是孤立的一份清单它最终要通过 registry、catalog、管理界面、文档与运行时证据的五方同步成为整个非 OpenAI Provider 追赶计划闭环中的一环——让任何使用者在ocx provider list、/api/provider-presets与 GUI 中看到完全一致的 provider 列表与认证模式。对于希望深入代码的读者建议按以下路径继续探索事件流解码基础设施src/lib/eventstream-decoder.ts 及其测试 tests/responses/eventstream-decoder.test.ts适配器解析链路WP14 的 MODIFY 落点src/server/adapter-resolve.tsBedrock 模型元数据与供应商优先级src/generated/model-metadata.ts前置的 Mantle 通道设计120_bedrock_mantle.md整个追赶计划的依赖地图与横切不变量000_plan.md。赞分享【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载相关推荐opencodex 集成 Amazon Bedrock ConverseStream零 AWS SDK 依赖的 SigV4 与 EventStream 移植实战opencodex 集成 Amazon Bedrock ConverseStream零 AWS SDK 依赖的 SigV4 与 EventStream 移植实AIRI 接入 Amazon BedrockAPI Key 配置、Region 校验与 Converse 适配原理AIRI 接入 Amazon BedrockAPI Key 配置、Region 校验与 Converse 适配原理 Amazon Bedrock 是 AWSAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染npx skills 交互式安装快速指南3 个决策装好技能npx skills 交互式安装快速指南3 个决策装好技能 写给第一次上手、记不住任何命令参数的你。全文演示 npx skills 的交互式安装流程一条命令AI 技能CLI开发工具人工智能上一篇Dante Cloud数据持久化MongoDB与关系型数据库的协同作战下一篇Cherry定时器管理Actor定时任务调度实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考