企业官网建设流程全解析

本指南基于 opencodex 仓库devlog/_fin/260723_grok_build_bridge/041_receipt.md（wp4 生命周期生产加固验收回执）撰写，围绕「Grok Build 用户以 opencodex 为本地代理时，代理生命周期内 Grok 配置如何保持确定性存在」这一核心主题展开。读完本文，你将掌握ocx ensure的 live/spawned 双分支 Grok 配置重注入机制、ocx restart往返验证中暴露并修复的 service-manager stop 缺陷、以及response.heartbeat在 chat_completions 桥接中的消费决策与回归测试，并能直接对照仓库源码与测试用例复现验证。

背景：为什么需要「生命周期生产加固」

opencodex 作为通用 Provider 代理（Universal provider proxy），支持 Codex CLI/App/SDK 与 Claude Code 接入任意 LLM。当 Grok Build 用户把 opencodex 当作本地服务器使用时（ocx start启动，ocx-*模型经 fence 块注入~/.grok/config.toml），此前 wp3（030_grok_config_autoinject.md）已完成 start/stop/eject/uninstall 路径上的配置自动注册与解注册。

但ocx ensure（幂等收敛命令）与ocx restart是生命周期中另外两条关键路径：

• ensure live 分支：当代理已在运行时执行ocx ensure，原实现（src/cli/index.ts 中handleEnsure()的 live 分支）只执行syncModelsToCodex+injectSystemEnv，Grok 配置只在 start 路径注入——ensure 之后 fence 可能缺失；
• ensure spawned 分支：当 ensure 需要拉起子进程时，父进程在/healthz响应后立即返回，而子进程的 Grok 注入晚于该时刻，存在readiness race（审计阻塞点 1）；
• restart 往返：restart 等价于handleStop → handleEnsure，一旦 stop 路径在到达 strip 前抛错，配置 fence 与代理都会停留在失效状态。

041_receipt.md是这一加固工作的验收回执（Date 2026-07-23，commits8ddeab8f+7c521a6c），记录了三项核心验证 c1/c2/c3 及其源码与测试证据。对应规划文档为 040_production_hardening.md，更早的联动计划见 000_plan.md。

c1 — ensure 分支的 Grok 配置重注入（live 与 spawned）

新增统一同步入口syncGrokConfig

规划（040 §1）明确：新建 src/grok/sync.ts，镜像 src/codex/sync.ts 的依赖注入模式，提供：

export async function syncGrokConfig( port: number, config: OcxConfig, opts: { hostname?: string; grokHome?: string } = {}, deps: GrokSyncDeps = { fetchAllModels: defaultFetchAllModels, injectGrokConfig }, ): Promise<GrokInjectResult>

其职责链为：fetchAllModels(config)拉取可见模型目录 →projectGrokCatalog()生成 Grok 目录投影 →standaloneCodexRoutingTarget(port, ...)计算代理实际路由目标（含 admission token 需求判断）→injectGrokConfig()将 fence 块幂等写入~/.grok/config.toml。GrokSyncDeps允许测试注入 mock 的fetchAllModels与injectGrokConfig，无需真实代理即可验证。

syncGrokConfig返回GrokInjectResult（定义于 src/grok/inject.ts），字段包括ok、changed、message，以及skippedReason（取值"no-grok-home" | "orphaned-marker" | "non-loopback"）。调用方可在显式ocx ensure中对ok:false以警告形式表面化（审计建议 4）；若模型目录拉取失败，则返回ok:false且不改动配置文件。

hostname 选择的两个分支

• live 分支：ensure 时代理已在运行，必须使用 proxy-liveness 运行时记录的live.hostname作为 hostname 传入——config.hostname可能已漂移，指向进程从未绑定的主机；wildcard 绑定（0.0.0.0）或 IPv6（::1）场景下此差异会真实影响注入内容；
• spawned 分支：ensure 刚刚按当前配置拉起子进程，因此使用config.hostname。

syncGrokConfig内部还会根据requiresAdmissionToken决定传入opts.hostname（回退config.hostname）还是targetUrl.hostname，并透传config.grokExcludedModels排除集与投影信息。这一 hostname 行为在测试 tests/providers/xai/grok-sync.test.ts 中有专门用例「the observed bind hostname reaches injection (ensure live branch)」覆盖：分别以0.0.0.0与::1调用，断言注入时使用观测到的实际绑定主机。

readiness race 的解决：父进程直接注入

spawned 分支的审计阻塞点 1 是：ensure 父进程在/healthz响应后即返回，而子进程自身的 Grok 注入晚于此。修复方式是：ensure 父进程在waitForProxy()成功之后直接调用syncGrokConfig(port, ...)，确定性保证注入完成。由于注入是对同一 fence 块的整块替换（幂等），与子进程自身的注入不存在冲突。

live 验证结果（隔离环境 :10190）

041 回执记录的验证路径：

1. live 分支：手动 strip fence →ocx ensure→ 日志出现+ Grok Build config updated，fence 1 块恢复，且live.hostname正确传递（proxy-liveness 运行时记录）；
2. spawned 分支：ocx restart（stop→ensure）后，父进程在waitForProxy成功后直接注入，readiness race 消除；
3. 既有门控确认：当codexAutoStart=false时 ensure 提前返回（该行为与 Grok 无关，属既有逻辑）。

c2 — restart 往返验证：发现并修复 service-manager stop 缺陷

首轮 restart 暴露的既有缺陷

隔离环境中第一轮 restart 复现了一个既有缺陷（非 Grok 新代码引入）：service-manager stop 因 home-mismatch 抛出异常，该异常被升级为stopFailed→process.exit(1)，导致 ensure 根本未被执行，代理在死亡状态下退出。此缺陷意味着在 service-installed 环境下，restart 会丢失 service persistence（自动重启/登录启动保证），且未托管的 child 死亡后 Grok fence 会无限期指向 dead proxy，直到下一次 start/ensure 被调用。

修复 commit7c521a6c：stopFailed 降级为警告

修复策略是：保留警告，但不再将 stop 失败升级为stopFailed——本地 teardown 与 ensure 与 service manager 相互独立，不应因 service-stop 的 home-mismatch 阻断后续收敛。规划文档（040 §2）确认该缺陷属于既有ocx restart本身的缺陷，而非本次新增代码，restart 的完整重设计（「service-installedocx restart应通过 service manager 重启并在重启后重新保证 fence」）作为后续验收标准（acceptance criterion）另立议题。

修复后的两轮往返结果

修复后执行连续 2 次 restart 往返，均成功：旧 pid stop + fence strip → 新 pid 启动 + fence 1 块重注入（pid 56377→57004，uptime 重置确认）。注意 wp4 的 live 验证前提是non-service 路径：service-installed 环境的 live 复现不可行（真实 launchd service 占用生产端口 :10100），因此 service-installed 的 persistence 损失与 stale-fence 风险作为release-known-limitation记录于 wp5 文档，并在 receipt 中明确非 service 路径前提（041 回执首段「전제（오딧 합의）」）。

c3 — heartbeat 决策：bridge 保留 keep-alive，chat 路径不透传 raw 帧

问题本质

Grok 的 strict Responses 解码器遇到未知 variant（如response.heartbeat）会直接崩溃（见 011_receipt.md 的 R2 记录）；而chat_completions 入站是安全的：src/chat/outbound.ts 的responsesSseToChatCompletionsSse会消费response.heartbeat，但绝不透传 raw heartbeat 帧——只通过ensureRole()放出「最大有效」的 Chat Completions role chunk（见 src/chat/outbound.ts 的ensureRole实现与 src/chat/outbound.ts 的case "response.heartbeat"分支）。

由于自动注入路径对全部模型强制api_backend="chat_completions"（见 030_grok_config_autoinject.md 的 fence 块示例），strict-解码器崩溃路径不可达。

决策与备选方案评估

决定（对应审计确认 6）：bridge 保留response.heartbeat，理由是它对 codex-rs 的 keep-alive 契约最优——任一事件都会重新武装 idle 计时器、未知事件被忽略。被否决的备选方案：

• SSE comment 形式：eventsource 解析器不会将其作为事件上送，codex idle 计时器无法续期，存在断流风险；
• response.in_progress：在 strict 模式下需要携带完整 response 快照 payload，代价过高。

同时，chat 入站「不透传 raw heartbeat」通过ensureRole()只放出有效 role chunk（stream 与非 stream fold 均如此，审计确认 src/chat/outbound.ts 的相关行）。相应动作：① 新增 chat 路径 heartbeat 消费回归测试；② 对直接使用 responses 后端（未走 chat_completions 注入路径）的用户，在 wp5 文档中记录 known-limitation。

回归测试证据

回归测试位于 tests/responses/chat-completions-endpoint.test.ts，用例名即为「responsesSseToChatCompletionsSse consumes response.heartbeat without forwarding a raw frame」（该文件 chat 端点测试 22 项通过），断言所有 data 帧均为chat.completion.chunk，绝无 raw heartbeat 帧流出。

验证矩阵与质量关卡

041 回执的 Verifiers 汇总：

与相邻工作包的关系

• wp3（031_receipt.md）：完成 start/stop/eject/uninstall 的 fence 注入/剥离，验收遗留「ensure live-proxy 分支无 Grok 重注入」——正是 wp4 c1 的输入；
• wp5 文档：承接 service-installed restart 的 release-known-limitation、responses 直连用户的 known-limitation 记录；
• wp6 冒烟：后续工作包的 live 冒烟范围。

wp4 明确 out-of-scope 项包括：bridge.ts 修改（按 c3 决策无需变更）、docs（归 wp5）、smoke（归 wp6）。

关键文件索引

以上实现证据均可直接在仓库对应路径复查，实测复现时建议沿用回执中的隔离手法（独立GROK_HOME、非 10100 的隔离端口、dummy loopback key），避免触碰生产 service 实例。