企业官网建设流程全解析

导读

本文基于 opencodex 仓库中 Kiro（AWS CodeWhisperer）网关对齐工作（devlog 143）的硬化阶段图，系统梳理 Kiro 适配器在生产环境下的完整加固路线：从 P0 级的流式协议终止、HTTP 重试退避、OAuth 单飞刷新、断点续传正确性、事件流解码器边界，到 P1/P2 级的工具 Schema 清洗、模型解析、错误映射与可观测性。读完本文，你将掌握 Kiro 单凭证适配器在 opencodex 中如何被逐阶段加固为可上生产状态的完整脉络、每阶段的验收标准，以及对应源码实现位置与验证命令。

背景与范围决策

Kiro 网关对齐工作的目标，是把 opencodex 的 Kiro（CodeWhisperer）对外能力提升到与上游kiro-gateway对齐并稳定下来。整个工作遵循"一个表面 = 一个完整 PABCD 循环"的纪律：每个阶段都以bun x tsc --noEmit类型检查 + 定向bun test验证收尾，并对应一个原子提交。

两项明确的范围决策决定了后续路线：

• 多账户故障转移（multi-account failover）明确出局：opencodex 在更上层已有自己的 Codex 多账户池（codexAccounts），Kiro 的单凭证导入是既定设计，因此不属于 Kiro 适配器缺口。
• 聚焦功能对齐 + 单凭证 Kiro 适配器的生产硬化：外部代码级评审将工作重心从"补缺口"转向"功能硬化"，用户方向为"把功能硬化推得更狠"。

在硬化阶段图定稿前，Phase 10（原生图片输入）已完成（commit 494be0d），因此最终阶段图从 Phase 70 开始。

重排后的阶段图（P0 优先）

硬化阶段图把全部工作按风险等级重新排定优先级，形成一张完整的路线图：

排序依据：P0 先行（生存性/正确性），每个阶段走完整 PABCD 循环并配tsc + 定向测试 + 原子提交。Phase 70 是体积最小、杠杆最高的 P0（一个正确性缺陷：上游调用失败目前可能看起来是部分成功），因此领跑。

已对齐表面（无需返工）

阶段图同时明确了哪些表面在硬化前已达对齐状态：

• Web 搜索 sidecar 已接入 Kiro（parseResponse+ 循环），无需额外工作；
• Token 用量启发式（计划 142 已关闭）——只需 P2 级的标注打磨；
• 通过 fake-thinking 标签实现推理强度（请求侧）——响应侧的解析回读跟踪在原始 Phase 40，折叠进截断/P1 处理。

Phase 70（P0-1）：流异常帧必须终止解析

这是整个硬化工作的领跑阶段，解决一个直接的正确性缺陷：parseKiroStream遇到:message-type == "exception" | "error"的事件流帧时，先产出error事件然后continue循环；循环结束时会额外产出带用量的done。下游桥接层（bridge）对done和error都置terminated=true，谁先到谁生效——但生成器在终止后仍会继续产出内容并补发成功形状的done，导致失败的上游调用泄漏部分内容并伪装成成功。

修复要点：遇到 exception/error 帧时，先关闭任何悬空的 tool call（保持括号配对，让 bridge 的closeCurrentToolCall路径在错误路由下也能正常工作），产出error事件后立即return——不再解析后续帧，不再发done。

实现已落在 src/adapters/kiro/stream.ts：事件流主循环中一旦检测到exception/error消息类型，置open = null并返回携带classifiedTerminal(classifyKiroStreamError(...))的终止结果；对未知 Smithy 消息类型同样返回协议错误终止结果。测试要求覆盖三个场景：流中途异常帧（之后无done、无更多文本）、内容前异常帧（仅 error）、以及既有异常用例断言不再有尾部done。对应文档见 devlog/_fin/143_kiro-gateway-parity/70_phase_stream_error_terminal.md。

Phase 80（P0-2）：Kiro HTTP 重试与退避

Kiro 特定的瞬时故障韧性，边界设定为不改凭证所有权：

• 连接/头部超时错误，在响应体存在之前可重试；
• HTTP 429/500/502/503/504 在解析任何 body 之前可重试；
• 有Retry-After则遵从，否则指数退避 + 有界抖动；
• 保留客户端 abort 的传播；
• 同时覆盖正常 Kiro 调用路径和 web-search sidecar 循环使用的parseResponse路径。

401/403 刷新一次被推迟到 Phase 90——因为provider.apiKey在适配器之外解析，需要 OAuth singleflight/reload 语义才正确。

设计上，ProviderAdapter拥有请求构造和流解析，但server.ts拥有 fetch，因此需要在适配器基类上增加一个小扩展：fetchResponse?(request, ctx): Promise<Response>（定义见 src/adapters/base.ts）。server.ts与web-search/loop.ts在存在adapter.fetchResponse时优先走它，否则保持既有 fetch 路径——让 Kiro 重试局限在适配器内，不影响其他 provider。

实现最终落在独立的 src/adapters/kiro-retry.ts：fetchKiroWithRetry采用进程级共享的节流门（throttle gate）+ 冷却期（cooldown）机制——共享探针只在出现 429 后才启动，健康流量保持并行，而被限流的账户不会烧掉每个调用者独立的退避预算。createKiroAdapter通过 src/adapters/kiro/adapter.ts 的fetchResponse暴露该重试入口，并透传 abort signal、发送预算与物理发送观测（physical send observer）以便用量日志记录真实的物理请求次数。验收标准：其他适配器保持直连 fetch；Kiro 在流解析开始后不重试（只在调用方拿到 Response 之前重试）；本阶段不引入 401/403 刷新。测试见 tests/providers/kiro/kiro-retry.test.ts（429→200 两次调用、Retry-After: 0后 200、400 不重试、调用方中止不重试）。详见 devlog/_fin/143_kiro-gateway-parity/80_phase_http_retry_backoff.md。

Phase 90（P0-3）：OAuth 刷新单飞 + Kiro SQLite 重载

安全边界：本地凭证存储（OPENCODEX_HOME/auth.json）+ 导入的 Kiro CLI SQLite token 缓存 → 出站 Kiro 运行时Authorization头。主要失效模式：并发的近过期请求用同一个旧 refresh token 刷新、竞态写入auth.json、或错过 Kiro CLI 里更新的 token。

加固内容三项：

1. 通用按 provider 的 singleflight：围绕getValidAccessToken的刷新工作，用模块级Map<string, Promise<string>>合并并发刷新，成功/失败后一律在finally清理；
2. Kiro 专属的"刷新前 SQLite 重载"：若已安装的 Kiro CLI 有新鲜 token，优先持久化并使用它，而非打桌面刷新端点；
3. Kiro 专属的"刷新失败后 SQLite 重载"：若外部 Kiro CLI 在我们的失败尝试期间/之后已刷新，通过重新导入它恢复。

刷新路径中REFRESH_SKEW_MS用于判断导入 token 是否仍有效。验收标准：不记录任何 token；singleflight map 成功/失败后总是清空；既有有效凭证走快速路径、不触碰 SQLite/fetch；Kiro 重载路径在登录时绝不削弱凭证优先级，只防止 opencodex Kiro 凭证已存在后的陈旧刷新竞态。测试（tests/oauth-refresh.test.ts）使用隔离的OPENCODEX_HOME/HOME临时目录，覆盖并发过期共享一次刷新、新鲜 SQLite token 先于刷新端点被导入、失败刷新后 SQLite 恢复等场景。详见 devlog/_fin/143_kiro-gateway-parity/90_phase_oauth_singleflight_reload.md。

Phase 100（P0-4）：断点续传 / 工具结果正确性

previousResponseId场景下，旧实现messages.slice(lastAssistant + 1).filter(m => m.role !== "assistant")会丢掉 assistant 消息。当当前轮以toolResult开头时，发出的 Kiro payload 只有userInputMessageContext.toolResults，却没有带匹配toolUses的前置assistantResponseMessage——Kiro 可能拒绝或误解该 payload。

修复将载荷切片与用量切片分离：

• currentTurnUsageMessages（见 src/adapters/kiro/usage.ts）= 旧行为（slice(lastAssistant+1)且过滤 assistant），避免把旧轮 user 文本/超大工具参数重新计入用量；
• currentTurnPayloadMessages：若当前尾部无 toolResult，行为同旧；若尾部有 toolResult，则保留前一 assistant 之后的最小历史交换——最后 user/developer -> 最后 assistant(toolUses) -> toolResult(s)，保证 Kiro 收到工具调用的完整上下文。

载荷构造位于 src/adapters/kiro/payload.ts（含 toolResult 合并、孤儿工具结果修复与续传消息注入）。测试矩阵覆盖：续传工具结果时保留 assistant toolUse 历史、续传场景用量只基于工具输出、普通续传（最新用户文本）仍无历史。详见 devlog/_fin/143_kiro-gateway-parity/100_phase_resume_tool_result_correctness.md。

Phase 110（P0-5）：事件流解码器加固

src/lib/eventstream-decoder.ts是 Kiro（CodeWhisperer GenerateAssistantResponse）与 amazon-bedrock（Converse）共同依赖的application/vnd.amazon.eventstream解码器。原实现校验 CRC 和分块，但缺乏硬边界：无最大帧长、无headersLen <= total - 16守卫、parseHeaders()用 DataView/subarray 读取前不检查字节是否存在、伪造的巨大total会让流缓冲无限增长。

加固内容（src/lib/eventstream-decoder.ts）：

• MAX_MESSAGE_LEN = 16 * 1024 * 1024（另有MAX_HEADERS_LEN = 128 * 1024）；
• decodeMessage拒绝total > MAX_MESSAGE_LEN与headersLen > total - MIN_MESSAGE_LEN；
• parseHeaders增加need(n, label)助手，每次 DataView 读取前检查，抛出明确的eventstream: truncated header ...错误；
• decodeEventStream在前 4 字节可用时立即拒绝超限total，缓冲增长超限时拒绝未完成的单帧。

测试包括：超限 total 抛错、头部长度越界抛错、截断字符串头抛受控错误、以及在每个字节边界切分合法帧仍可解码的小型模糊测试。详见 devlog/_fin/143_kiro-gateway-parity/110_phase_eventstream_hardening.md。

Phase 120（P1-1）：工具 Schema 清洗

convertTools原先直传工具 JSON Schema，而 kiro-gateway 会剥离 Kiro 拒绝的字段——尤其是additionalProperties和空required: []——否则合法的 Codex/OpenAI 风格工具 Schema 会变成 Kiro 400。

实现迁移到独立的 src/adapters/kiro-tools.ts（convertKiroTools包装convertKiroToolContext），因为原kiro.ts已到 500 行限制。Schema 递归清洗规则：删除每个additionalProperties键、required为空数组时移除、保留非空required/properties/items/oneOf/anyOf。既有行为保持：名称截断到 64 字符、空描述用占位符并截断（描述截断做了代理对安全处理，不会在 lone high surrogate 上切断产生 U+FFFD，见 src/adapters/kiro-tools.ts）、inputSchema默认{}。

当前实现还演进出了更完整的工具目录治理：命名空间化的 wire 名称（mcp__chrome-devtools__navigate_page）经别名注册表映射为 Kiro 接受的 ≤64 字符安全名（Kiro runtime service 拒绝含空格或超长名称），MAX_KIRO_TOOL_COUNT与序列化目录字节预算控制出站目录规模，超出预算时按优先级排序淘汰并生成[opencodex] Kiro's outbound catalog budget...系统提示告知模型被省略的工具，code-mode 执行路径工具保留专属席位（见 src/adapters/kiro-tools.ts）。长描述移入系统提示与孤儿工具结果回退是后续 P1 跟进阶段（125）。详见 devlog/_fin/143_kiro-gateway-parity/120_phase_tool_schema_sanitization.md。

Phase 130（P1）：模型解析器归一化

折叠了旧 Phase 50：mapModelId原先只剥离kiro-前缀，缺少版本化 slug 归一化。需要把claude-sonnet-4-5-20250929、claude-3-7-sonnet这类版本化/短横线 slug 映射到规范 id，避免误路由；同时通告max推理强度。实现侧可以从 src/adapters/kiro/payload.ts 的normalizeKiroModelId与kiroReasoningMode（src/adapters/kiro/reasoning.ts，区分 GPT-5.6 家族的reasoning字段与 Claude 类模型的output_config）观察模型解析与推理强度映射的落地形态。

Phase 140（P1）：Kiro 特定错误映射

目标是把上游的认证/区域/配额/模型不可用等失败，映射为 Codex 可操作、可解释的错误，替代"泛化的上游失败不透明"。实现侧见src/adapters/kiro-errors.ts（classifyKiroHttpError、safeKiroHttpErrorMessage，被 src/adapters/kiro-retry.ts 与适配器formatErrorBody使用）以及classifyKiroStreamError在 src/adapters/kiro/stream.ts 中的流级错误分类。认证区域检查还包括正则校验runtime.<region>-<n>.kiro.dev规范主机与未知端点/无效签名标记（src/adapters/kiro-retry.ts）。

Phase 150/160/170（P2）：截断恢复、用量标注与调试可观测性

三个 P2 阶段共同构成"静默失败不可见"问题的收尾：

• Phase 150 截断检测/恢复：检测流中途截断并注入合成恢复消息让模型自适应，而不是静默吞掉；实现位于src/adapters/kiro-truncation.ts，并设计了noteKiroTransientThrottle（src/adapters/kiro-retry.ts）这类"流级节流到达于 HTTP 200 之后"的冷却记录机制，为下一次客户端重试预留状态；
• Phase 160 用量估算标注：CodeWhisperer 不上报权威用量，启发式估算值必须在日志中明确标记为估算。适配器日志已携带estimated: true标记（src/adapters/kiro/adapter.ts），并配校准测试（tests/providers/kiro/kiro-calibration.test.ts）；
• Phase 170 调试可观测性：脱敏载荷 + 原始帧置于 flag 之后，降低未来崩溃防护成本。

验证纪律与验收闭环

每个阶段都必须满足统一的完成标准：

bun x tsc --noEmit bun test tests/providers/kiro/... # 对应阶段的定向测试

定向测试分布在 tests/providers/kiro/ 下：kiro-adapter.test.ts、kiro-retry.test.ts、kiro-images.test.ts、kiro-oauth.test.ts、kiro-stream.test.ts、kiro-review-regressions.test.ts、kiro-calibration.test.ts等，外加 tests/oauth-refresh.test.ts 与 tests/eventstream-decoder.test.ts。每阶段一个原子提交，独立验证者按阶段分派。

整个硬化计划完成时，应确认：不再静默丢弃图片、瞬时上游失败有重试、载荷有界、响应侧推理被呈现、版本化模型 slug 被解析、截断被呈现而非吞掉。这套从 P0 生存性到 P2 可观测性的路线图，既是 Kiro 适配器上生产的完整清单，也可作为其他 provider 适配器做生产硬化的可复用模板。