Skip to content

feat(runtime): 支持 Codex 兼容 CLI 独立运行时 - #719

Open
xiongz-c wants to merge 5 commits into
masterfrom
codex/codex-compatible-runtime
Open

feat(runtime): 支持 Codex 兼容 CLI 独立运行时#719
xiongz-c wants to merge 5 commits into
masterfrom
codex/codex-compatible-runtime

Conversation

@xiongz-c

@xiongz-c xiongz-c commented Aug 3, 2026

Copy link
Copy Markdown
Collaborator

背景

此前 cliId 同时承担协议适配器和具体发行版身份,cliPathOverride 只能替换启动二进制。Codex 魔改发行版虽然大体可运行,但版本检查、更新提示、会话恢复和 UI 展示仍可能沿用官方 Codex 语义。

本 PR 引入一套通用的 Codex-compatible runtime 能力,让未来兼容 Codex 契约的独立 CLI 通过配置接入,不需要逐个新增 adapter。完整设计见 docs/design/2026-08-03-codex-compatible-runtime.md

方案

  • cliId 固定为协议能力,新增 cliRuntime 描述具体发行版:稳定 id、展示名、可执行文件和更新策略。
  • 会话创建时冻结 runtime 快照;启动、resume、adopt、RPC、卡片、命令和 Dashboard 都优先使用会话自己的身份,避免 bot 热切换后历史会话被重标或拉起错发行版。
  • 更新检查按真实安装和发行源隔离:支持 autoselfnpmnone,只有官方 runtime 可以使用官方 Codex 更新源。auto 必须唯一证明 npm bin 所有权;来源冲突、歧义或换包时 fail-closed。
  • Dashboard 和 setup 支持配置、只读 --version 预检、legacy path 迁移以及运行时状态展示。
  • 结构化 runtime 写入时原子双写等值 cliPathOverride 降级影子,使旧版 BotMux 仍启动同一二进制;新 loader 对缺失或不一致的影子直接拒绝。

向前与向后兼容

  • 未配置 cliRuntime 的现有 20+ CLI 路径不变。
  • 官方 Codex 行为不变,继续使用 internal 更新源。
  • 存量 cliPathOverride 继续可启动并使用安全的 auto 更新探测;因无法证明完整兼容契约,RPC 增强保持关闭。
  • 老客户端只修改 model 时保留结构化 runtime;显式切换 Official Codex 才清除。交互式 setup 留空表示保留,- 才表示清除。
  • runtime、CLI 或 wrapper 热切换会关闭仍冻结旧启动身份的活跃会话,防止 lazy resume 到错误发行版。
  • executable 解析同时覆盖 macOS/Linux、POSIX/Windows 绝对路径,并避免 shell 插值和任意 argv 误识别。

影响面评估

  • CLI:结构化 runtime 当前仅允许 cliId=codex;其他 adapter 共用路径有回归覆盖。
  • 后端:普通启动覆盖 PTY/tmux/herdr/zellij;Codex RPC 仍仅在满足原有 tmux 安全门槛时开启。
  • 会话类型:覆盖新建、恢复、adopt、daemon restart、关闭卡片、Dashboard restart/resume 和定时任务。
  • 平台:macOS 本机全量验证;Linux arm64 容器完成构建与关键矩阵验证。
  • 线上状态:未切换全局 botmux 指向,未重启 live daemon。

验证

  • pnpm build:通过。
  • 改动面矩阵:24 files,1162 tests passed。
  • Linux arm64 Docker:构建通过,10 files,484 tests passed,包含原生 node-pty
  • pnpm test:12459 passed,35 skipped;仅剩 2 条 master 既有基线失败,相关测试文件本 PR 未修改:
    • test/v2-run-archive.test.ts:612:对目录调用非 recursive rmSync
    • test/v3-host-execution.test.ts:205:对目录调用非 recursive rmSync
  • git diff --check、公开域名审计、私有 CLI/主机名扫描:通过。

Dashboard 示例

Codex-compatible runtime Dashboard

提交关系

  1. docs(design):先定义 schema、边界、迁移和验收矩阵。
  2. feat(runtime):引入 runtime 模型、严格校验和降级影子。
  3. fix(update):按发行版隔离更新来源、缓存和通知水位。
  4. feat(codex):打通会话快照、RPC、adopt/resume 与展示闭环。
  5. feat(dashboard):补齐 Dashboard、预检、文档和截图。

@xiongz-c
xiongz-c requested a review from deepcoldy as a code owner August 3, 2026 14:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant