企业官网建设流程全解析

本文以 opencodex 仓库devlog/_fin/260723_open_pr_review/100_merge_records.md记录的一次真实「开放 PR 评审与本地合并」会话为骨架，系统讲解一种只在本地产出合并提交、不触碰远程仓库、由 Sol 子代理逐轮审计的 PR 合并工作流：从 base refresh、逐 PR 的 Sol audit（PASS/FAIL/NOOP/NEEDS_HUMAN）、fixup 补丁、冲突裁决，到与上游 maintainer dev 的对齐集成和最终推送，并穿插源码级证据说明每个审计结论背后的实现依据。读完本文，你将掌握一套可复用的「审计—合并—验证—推送」四段式 PR 处理流水线，以及 opencodex 中 Google wire 编译、SSE 解码、Chat Completions 翻译等关键模块的底层原理。

会话背景：一份本地合并栈记录

100_merge_records.md记录了 2026-07-23 前后 opencodex 维护流程中的一轮「open PR review」执行结果（完整计划见 000_plan.md）。其核心工作方式是：

• 在独立 worktree 上创建本地分支codex/pr-review-260723（trackingorigin/dev），把所有评审通过的 PR以本地 merge commit 形式叠放在栈上；
• NO push、NO GitHub mutations——合并过程完全不触碰远程仓库，GitHub 状态保持原样；
• 每个工作包（Work Package，WP）由Sol 子代理（gpt-5.6-sol，medium effort）执行审计并给出 PASS / FAIL / CLEAN 等结论，人工只在必要时介入（如 NEEDS_HUMAN 裁决）；
• 每次合并后以bun run typecheck与bun run test作为硬性验证门槛，记录测试总数（3614 → 3631 → 3651 → 3650 → 3676，全部 0 fail）。

该计划最初盘点 8 个开放 PR（#316/#309/#307/#306/#304/#303/#279/#249/#317），而合并记录文档聚焦于最终进入本地栈的 4 个工作包（WP2/WP3/WP4/WP5/WP6），并追加了 WP-INT（与 maintainer dev 集成）与 WP-PUSH（推送）两节。

阶段一：Base refresh —— 先对齐上游再叠 PR

在开始逐 PR 合并之前，记录明确了一个关键步骤：先把本地分支刷新到最新origin/dev。

1639af37: no-ff merge of origin/dev 02b67b03

这次 no-ff 合并一次性吸收了上游已合入的#316（anthropic SSE 终帧修复）与#317（WHAM 月度配额窗口）。它的直接收益是：WP3（PR #317）在评审前就已包含在栈基中，因此后续被判定为NOOP——不重复合并。判定证据是 git 的祖先关系检查：

git merge-base --is-ancestor pr-317 HEAD → true

这条命令验证了「目标 PR 的 HEAD 已经是当前分支的祖先」，从而避免重复合入。这是整个工作流的第一条可复用经验：叠 PR 之前先吸收上游，并用 merge-base 祖先关系去重，把「已合入」与「待合入」精确区分开。

阶段二：WP2 合入 —— 审计 PASS 路径（PR #307）

PR #307（custom model display names，详见 030_pr307_display_name.md）是第一个走完完整 PASS 路径的 PR：

1. Sol audit（agent 019f8dbc）：PASS，0 blockers。审计确认合并树干净、与 #313/#316/#317 无语义冲突、注入面受控（JSON.stringify持久化 + CLI/API 层拒绝斜杠）、catalogModelSlug导出存在。
2. Merge commit：2523a6f5，3 文件 +168/−1，零冲突。
3. 验证：bun run typecheck退出码 0；bun run test3631 pass / 0 fail（3614→3631，+17 个测试来自 #307 与 base refresh）。

记录中特别提到一个环境性插曲：首次运行时出现 2 fails + 2 errors，根因是全新 worktree 缺少 gui/ 下的 node_modules（react/jsx-dev-runtime），执行bun install后即恢复，与合并本身无关。这提醒我们：在干净 worktree 中做合并验证，必须先补装依赖再下结论。

阶段三：WP4 裁决 —— 审计 FAIL 与 NEEDS_HUMAN 路径（PR #309）

PR #309（google wire 兼容，消除 Antigravity 请求形状 400，详见 020_pr309_google_wire_compat.md）展示了当 Sol 审计判定 FAIL 时，维护者如何处理——不粗暴合入，也不当场私改，而是升级为 NEEDS_HUMAN。

Blocker 1（High）：toolNameCodec 跨请求的非确定性碰撞

PR 引入的toolNameCodec（google-wire-compiler.ts）会给非法工具名（如 MCP 的server.tool点号，违反^[A-Za-z_][A-Za-z0-9_-]{0,63}$，见 L15）生成prefix_hash8形式的 wire 名。问题在于：盐化名字依赖 encounter 顺序——如果某个合法工具名恰好等于生成的prefix_hash8候选，重排工具集合就会改变碰撞工具在 wire 上的名字。而 Antigravity replay 缓存按 provider 可见名字签名（google-antigravity-replay.ts:39,120），跨 turn 的重排/子集变化会导致缓存签名失配，从而重新触发 400。

评审综合意见（REVIEW-SYNTHESIS-01）承认：常规场景（无碰撞）是确定性的，因为 hash 基于原始名字；只有对抗性/运气不佳的名字碰撞才会触发。属于真实但低概率的正确性缺口，应交给上游修复。

Blocker 2（Medium）：allowlist 过度裁剪 Vertex / AI Studio

PR 将 schema 清洗从 blocklist 换成 Google 文档 allowlist 子集，但minimum/maximum/additionalProperties/pattern被一并丢弃——而 Google 明确文档支持这些字段。因此 PR 声称的「Google-documented allowlist」对非 CCA 路径不成立，且反向推翻了现有测试断言（google-tool-schema.test.ts:27,80）。建议方案是provider-profiled 编译：仅在 Cloud Code Assist 路径启用严格清洗，Vertex / AI Studio 保留文档化字段。

裁决

WP4 关闭为NEEDS_HUMAN——按当前组成不并入本地栈；两项 findings 作为上游反馈记录（本会话不向 GitHub 发帖，交由维护者决定如何转达）。栈状态保持不变（最后一个 green 节点是 2523a6f5）。核心经验：审计 FAIL 不等于 PR 无价值，而是「当前形态不可入栈」；修复属于作者/维护者的工作，不属于合并现场临时补丁。

阶段四：WP5 合入 —— 两轮 fixup 修复后 PASS（PR #279）

PR #279（GitHub Copilot App 通过 OpenAI 兼容 chat completions 接入，详见 070_pr279_copilot_chat_completions.md）是工作流中最完整的一次「审计→修复→再审→合入」循环，共经历3 轮 Sol audit。

Round 1：3 个 blocker

1. High —— /v1/models 鉴权回归：PR 把GET /v1/models从requireApiAuth(data-plane)切到requireResponsesApiAuth，导致远程绑定下不再接受Authorization/x-api-key的裸 bearer 放行，会同时破坏 OpenAI bearer 客户端和 Claude gateway 经anthropic-version的发现流程。修复：改回requireApiAuth——因为/v1/models从不向上游转发 Authorization，「双 bearer 冲突」的顾虑不成立。
2. Medium —— 文档自相矛盾：docs/github-copilot-app.md 的远程配置同时写了 API-key 字段和x-opencodex-api-key头。判定为residual（仅文档、loopback 不受影响），只记录为上游反馈，不本地修复。
3. High —— 手写 SSE 切分器缺陷：outbound 用自写的\n\nsplitter，既漏掉 CRLF 帧边界，又在 EOF 时丢终帧——导致有效响应被误报为 "truncated"。这与栈内共享的 SSE 解码器（#316 引入）构成语义冲突。修复：改用decodeServerSentEvents。

Round 2：新 blocker —— cancel() 悬挂

Round 1 的修复提交（fixup commit 1：/v1/models恢复requireApiAuth(data-plane)并注释说明；responsesSseToChatCompletionsSse重写为共享解码器；补 CRLF/EOF 回归测试）之后，Round 2 仍 FAIL：cancel() 悬挂在空闲的上游读取之后——generator return 会等待 pending await，live probe 显示upstreamCancelled:false。

Round 3：PASS

fixup commit 2 的解法是给decodeServerSentEvents增加可选{ signal }参数：abort 直接 cancel 底层 reader，从而让消费者的iterator.return()不再悬挂在空闲上游之后。这在 sse-decoder.ts 中有清晰实现——注释明确说明「a plain generator return waits for the pending await first」，而onAbort会reader.cancel(signal?.reason)立即解开 in-flight read。outbound 侧则「先 abort 再关迭代器」，并为 idle-upstream 取消补了回归测试；no-signal 消费者（#316 anthropic 路径）行为不变。

最终：PASS（"cancellation resolves promptly, cancels upstream exactly once, listener cleanup safe, no-signal consumers unchanged, 27 focused tests pass"）。合并提交eebd4977+ 2 fixups；typecheck 0；bun run test3651 pass / 0 fail，覆盖 297 个文件（85.97s）。

源码佐证：outbound 的翻译层

PR 落地后的核心代码现存于仓库：src/chat/outbound.ts 实现了 Responses SSE → Chat Completions 形状的转换：流式输出data: {choices:[{delta:...}]}以data: [DONE]收尾；非流式输出{ id, object:"chat.completion", choices:[{message}], usage }。其中chatCompletionsUsage把 Responses 的input_tokens/output_tokens（含 cached / reasoning 明细）映射为 OpenAI 兼容的prompt_tokens/completion_tokens/total_tokens——并总是输出 detail 对象（零值兜底），使要求严格的 OpenAI 兼容客户端在路由到不报告缓存/推理数的 provider 时也不会失败。入站侧 src/chat/inbound.ts 的assertChatCompletionsRoutingBody只校验 Chat 路由前必需字段（model非空字符串、messages非空数组），产出体必须通过responsesRequestSchema，从而完整继承现有 routing/OAuth/pool/sidecar 逻辑。

阶段五：WP6 合入 —— 安全评审 + 冲突裁决（PR #304）

PR #304（kiro 修复：恢复加固并完成文本回合，详见 050_pr304_kiro_followup.md）涉及 Kiro OAuth/凭据导入，按 MAINTAINERS.md 属security-review 范围。

Sol 安全子裁决：CLEAN

• 只读的KIROCLI_DB_PATHselector（实现见 src/adapters/kiro/adapter.ts 与 src/adapters/kiro/wire.ts）；
• %:token常量绑定参数——无 SQL 注入面；
• 模糊/缺失 token 选择时 fail-fast，不泄露 values/keys/paths；
• clientIdHash受限；诊断信息分类化；redaction 完整（upstream-http-error.ts:6）；
• 安全文件 HEAD vs pr-304byte-identical（凭据加固已随 #302 restore 落地）；privacy:scan通过。

合并裁决 Round 1：FAIL —— 5 处真实冲突

kiro.ts、structure/04、kiro-stream+ 2 个 e2e 测试文件冲突。记录坦诚指出：手工 merge-tree preflight 漏看了+前缀标记，而 Sol 正确使用了merge-tree --write-tree——教训被记录在案。

冲突解决策略：PR 侧优先（superset 原则）

pr-304 已经在上游 dev 9ca7ea32 合并过，因此PR 侧是包含栈侧的超集。5 个区域全部取 PR 侧后验证：4 个代码/测试文件与 pr-304 逐字节一致；structure 文档保留栈内 Cursor 章节；kiro-stream 测试数 53==53。

合并提交bb94ecbe，Sol C 轮验证 PASS（"conflict resolution faithfully preserves the stack while applying #304's intended completion behavior"；测试 delta -1 是有意为之：4 个旧 fallback 用例 → 2 个 completion-semantics 用例 + test-runner 测试；#279/#316 blobs 未变）。验证：typecheck 0；bun run test3650 pass / 0 fail，298 个文件；privacy scan 通过。

栈终态：合并记录汇总

分支codex/pr-review-260723仅存本地，未推送，GitHub 未被触碰。应反馈上游的事项：#309 两个 blocker、#279 文档矛盾（residual）。

阶段六：WP-INT —— 与 maintainer dev 的理性对齐

在本地栈构建期间，维护者将 origin/dev 推进到a0b9688d：上游合入了 #307、#309（按原样，不带本地 fixup）、#279、#303 docs、#318 cursor continuation、#319 fast-uri 3.1.4，并从 main 收敛出 v2.7.34。此时本地栈面临两棵树的分叉，记录给出了对齐原则：

• 上游是维护者决策的事实基准：#309 尽管本地审计为 NEEDS_HUMAN，仍被上游合入——尊重而非回滚；两个 blocker 作为 KNOWN-ISSUE 反馈保留（WP4 已记录）。
• 本地侧携带上游缺失的已验证改进：两个 #279 fixup（/v1/models恢复requireApiAuth——上游合入了回归版本；可 abort 的共享 SSE 解码器替代手写 splitter，修复 CRLF/EOF 与 idle-cancel 缺陷）和 #304 合并（kiro clean-text-EOF + 测试隔离，安全评审 CLEAN；PR 在上游仍开放）。

合并机制是：

git merge --no-ff origin/dev → ab72fc10（零冲突）

结果树d31cce0d被验证为与 Sol 审计过的合成树逐字节相等。Sol 集成审计（agent 019f8ded）覆盖 5 个区域，PASS 且无 blocker、无需要手工混编的文件；package.json的混合是预期并集（上游 fast-uri override + 本地 scripts/test.ts runner），版本保持在 2.7.34。验证：typecheck 0；bun run test3676 pass / 0 fail，299 个文件；privacy scan 通过。

阶段七：WP-PUSH —— 用户批准的最终推送

本地栈与上游对齐后，进入推送环节（本次会话经用户批准）：

• Sol 推前门禁：GO——祖先关系成立；32 个变更文件与已审栈一致；无 junk/local-state 路径；推送树内无 codexclaw/goalplan 文件。
• 推送：a0b9688d..3a87829f HEAD -> dev（fast-forward，无 force）。pre-push hook 运行；范围无 gui/ 变更，gui doctor 跳过。
• 远程校验：git ls-remote origin dev==3a87829f== 本地 HEAD。
• 副作用：GitHub 自动关闭 PR #304（其 head 9ca7ea32 已成为 dev 的祖先）。推送后仍开放的 PR：#306（等待 CI + GUI 审批）、#325（新、未分类）。

最终 dev 树携带：上游a0b9688d（含作为维护者决策合入的 #309）+ 本地 #304 合并 + 两个 #279 fixup + review/merge/integration 各 devlog 单元。

可复用的方法总结

1. 本地先行：所有合并先在本地分支完成并审计，GitHub 保持原样——审计结论与合并结果解耦，评审可以放心大胆地说 FAIL / NEEDS_HUMAN。
2. Base refresh 先行 + merge-base 去重：吸收上游后用git merge-base --is-ancestor识别 NOOP，避免重复劳动。
3. 三轮审计循环：PASS 即合；FAIL 则产出最小 fixup 补丁并进入下一轮，直到 Sol 给出「cancellation resolves promptly / upstream exactly once / no-signal consumers unchanged」级别的精确结论。
4. 安全评审单列赛道：涉及凭据/OAuth 的 PR 必须先跑安全子裁决（只读 selector、常量绑定参数、fail-fast 不泄露、redaction、privacy scan），再谈合并。
5. 冲突裁决用 superset 原则：当 PR 已在上游合入时，PR 侧是超集，逐区域取 PR 侧并用字节级对比 + 测试数做收敛验证。
6. 集成阶段以「上游为准 + 本地改进不丢」：维护者决策优先，本地已验证改进（如可 abort 的共享 SSE 解码器）通过 fixup 携带进主干，最终用 push 门禁（祖先关系、文件白名单、无 force）收口。

这套工作流对应的审计证据、逐 PR 详细分析与源码实现均可在此仓库内追溯：计划与决策见 000_plan.md 及 020 / 030 / 050 / 070 / 090；实现层可分别对照 google-wire-compiler.ts（工具名 codec 与 400 修复路径）、sse-decoder.ts（可 abort 的共享 SSE 解码）、src/chat/inbound.ts 与 src/chat/outbound.ts（Copilot chat completions 翻译层）。