feat: 解耦原生 Codex CLI 选择 / decouple native Codex CLI selection

[VirgilMing]

摘要

当用户为 Codex Desktop 选择独立更新的原生 Codex CLI 时，codexhost 受管启动此前仍会使用安装探测决定的包内 CLI 或 Desktop 缓存。本 PR 将原生 CLI 选择与 Desktop 安装识别分开。

• launch 和 inspect 增加 --codex-cli，优先于非空的继承 CODEX_CLI_PATH；未指定时保留各平台默认选择。
• 在 Desktop 将 CODEX_CLI_PATH 替换为 Shim 前解析和校验显式目标。显式选择不要求包内 CLI 或 Windows Desktop 缓存存在；无效路径直接报错。
• 拒绝当前 Shim 自引用、符号链接别名和 Unix 硬链接；受管环境再次调用时，恢复并校验已有的原生转发目标。
• 通过 CODEXHOST_STOCK_CODEX_PATH 传递选中的原生 CLI；inspect 文本和 JSON 区分包内路径、执行路径和选择来源，控制台兼容缺少新增字段的旧 schema v1。
• 增加原生 CLI 回归测试、功能文档及 Linux 中英文说明。

Desktop 安装身份与资源仍按现有规则校验。此配置适用于本地原生 Codex CLI；外部 Harness 继续使用各自的 Adapter 和原生接口。

验证

本地环境：Gentoo Linux x86-64，Node.js 26.11.1，Rust 1.99.0。GitHub CI 使用仓库指定的 Node.js 22.22.0 和 Rust 1.97.1。

• cargo test --locked -p codexhost-platform -p codexhost-launcher：120 项通过（65 项 Launcher、4 项 CLI 集成、51 项 Platform）。
• npm run test:typescript -- packages/console-server/test/installation.test.ts packages/console-server/test/diagnostic-report.test.ts packages/host-runtime/test/runtime-maintenance.test.ts packages/update-manager/test/update-manager.test.ts packages/update-manager/test/updater-ready.test.ts：33 项通过；1 项仅 Windows 的测试在本地跳过。
• npm run typecheck、npm run lint（含包边界检查）、npm run format:check、Platform/Launcher 全目标 clippy 和 git diff --check。
• 以最新上游 1aa9f65d 为唯一父提交；PR 保持一个功能提交，差异仅涉及原生 CLI 选择的 13 个文件。

跨平台 CI：本次提交的 CI 已全部通过：Linux x64、Linux ARM64、macOS 和 Windows，含各平台配置的 Rust 检查及 Linux npm 包 smoke 验证。

Summary

Managed codexhost launches previously kept using the packaged native Codex CLI or Desktop cache selected by installation discovery, even when a user wanted an independently updated CLI. This PR separates native CLI selection from Desktop installation discovery.

• Add --codex-cli to launch and inspect, ahead of nonempty inherited CODEX_CLI_PATH; preserve platform defaults without an override.
• Resolve and validate overrides before Desktop's CLI path becomes the Shim. Explicit targets do not require packaged CLIs or the Windows Desktop cache; invalid paths fail directly.
• Reject current-Shim recursion, symlink aliases, and Unix hard links; recover and validate the native forwarding target on managed reentry.
• Forward the selected CLI through CODEXHOST_STOCK_CODEX_PATH. Report packaged paths, executable paths, and selection provenance in text and JSON inspect output, accepting older schema v1 launchers without the additive fields.
• Add focused native CLI regression tests, feature documentation, and Chinese/English Linux documentation.

Desktop identity and resource validation retain their existing rules. This setting applies to the local native Codex CLI; external Harnesses continue using their own Adapters and native interfaces.

Validation

Local environment: Gentoo Linux x86-64, Node.js 26.11.1, Rust 1.99.0. GitHub CI uses the repository's Node.js 22.22.0 and Rust 1.97.1.

• Platform and Launcher Rust tests: 120 passed (65 Launcher, 4 CLI integration, 51 Platform).
• Focused updater, handoff, runtime maintenance, and console diagnostics tests: 33 passed; one Windows-only test skipped locally.
• Typecheck, lint including package boundaries, repository formatting, Platform/Launcher all-target clippy, and diff checks.
• Upstream 1aa9f65d is the sole parent; the PR contains one feature commit limited to the 13 native CLI selection files.

Cross-platform CI: the run for this commit passed on Linux x64, Linux ARM64, macOS, and Windows, including each lane's Rust checks and Linux npm package smoke validation.

关联问题 / Related issues

无 / N/A.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: BytePioneer-AI/codex-host/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: d39c9942-d6c2-4f69-8af3-79c481d605e9

📥 Commits

Reviewing files that changed from the base of the PR and between 6eec7ce and 1a91d0b.

📒 Files selected for processing: 2

• crates/platform/src/desktop_launch.rs
• docs/index.md

🚧 Files skipped from review as they are similar to previous changes: 1

• docs/index.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📜 Recent review details

🔇 Additional comments: 1

crates/platform/src/desktop_launch.rs: 1

152-152: LGTM!

Also applies to: 986-986, 1044-1073, 1288-1288

📝 Summary

Summary by CodeRabbit

• 新功能

  • codexhost inspect 和 codexhost launch 支持通过 --codex-cli 指定原生 Codex CLI，也可通过 CODEX_CLI_PATH 设置。
  • 检查结果新增打包 CLI 路径、实际使用的 CLI 路径及其来源信息。
  • 未指定 CLI 时，按平台现有规则选择；指定路径无效时会报错。

• 文档

  • 补充 CLI 选择规则及 Linux 平台使用说明。

本次变更新增原生 Codex CLI 的选择与校验，并将所选路径和来源接入各平台的桌面安装发现、Launcher 启动及 inspect 输出。文档和 console-server 类型同步说明并验证新增诊断字段。

Changes: 原生 Codex CLI 选择与启动

Layer / File(s)	Summary
CLI 覆盖解析 crates/platform/src/codex_cli.rs, crates/platform/src/lib.rs	新增覆盖解析和来源类型。命令行参数优先于非空环境变量；无有效覆盖时使用平台默认选择。路径校验拒绝无效路径以及当前 Shim 或其硬链接。
平台安装发现 crates/platform/src/installation.rs, crates/platform/src/linux_installation.rs, crates/platform/src/lib.rs, crates/platform/src/desktop_launch.rs	Windows、macOS 和 Linux 的发现流程接受可选 CLI 覆盖，并记录打包 CLI、执行 CLI 和来源。测试覆盖外部 CLI 和缺少包内 CLI 的情形。
Launcher 参数、诊断与文档 crates/launcher/src/main.rs, crates/launcher/src/console.rs, packages/console-server/src/installation.ts, packages/console-server/test/installation.test.ts, docs/architecture/native-codex-cli-selection.md, docs/index.md, docs/platforms/linux/*	launch 和 inspect 接受 --codex-cli。启动流程解析 CLI 覆盖并传给平台发现；测试验证托管启动中的 Shim 与 CLI 转发环境变量。inspect 输出包含 CLI 路径和来源。console-server 接受新增可选字段，并测试新旧 v1 文档解析。新增文档说明选择优先级、校验规则和诊断信息。

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Launcher
  participant Resolver as resolve_codex_cli_override
  participant Discovery as discover_codex_desktop_with_cli
  participant Installation as DesktopInstallation
  Launcher->>Resolver: 显式路径、环境变量和 Shim 信息
  Resolver-->>Launcher: 已验证的覆盖及来源
  Launcher->>Discovery: 传入可选 CLI 覆盖
  Discovery->>Installation: 设置打包路径、执行路径和来源

Loading

Suggested reviewers: bytepioneer-ai

Merge Risk: ⚪ Minimal · up to 1a91d

No actionable merge-blocking issue is identified in the supplied changes.

### Architecture Summary

Architecture risk: 🟡 Medium · up to 6eec7

The change affects 3 systems.

Changed systems: crates, docs, packages/console-server

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — crates (service) was modified; 7 changed files map to changed impact.
• observed — docs (service) was modified; 4 changed files map to changed impact.
• observed — packages/console-server (library) was modified; 2 changed files map to changed impact.

Before / after behavior

• observed — Modified behavior in crates/platform/src/codex_cli.rs: 新增 CLI 覆盖解析逻辑：命令行路径优先；否则仅非空环境变量参与选择。若其 canonicalize 后与 Shim 相同，则在存在转发目标时改选转发路径。所选路径须为绝对路径和现有文件，Unix 上还须可执行；无效路径、Shim 本身及 Shim 的硬链接均返回错误。
• observed — Modified behavior in crates/platform/src/codex_cli.rs: 新增惰性选择函数：有已验证覆盖时返回其路径和来源，不调用默认发现；否则调用默认闭包并返回给定的默认来源。
• observed — Modified behavior in crates/platform/src/codex_cli.rs: 新增测试，覆盖命令行优先及默认发现惰性、环境路径 canonicalize 与空值处理、无效路径拒绝、Shim 别名和硬链接拒绝，以及托管重入时转发原生目标的选择和错误情形。
• observed — Modified behavior in crates/platform/src/desktop_launch.rs: Windows AppX 环境测试中的 DesktopInstallation 初始化新增 codex_cli_source 字段，值为 Packaged。

Reliability and maintainability

• inferred — Risk-relevant change factors for crates: blast_radius_1; direct_dependents_1

Pre-merge checks: 4

Passed checks: 4 passed

Check name	Status	Explanation
Title check		标题准确概括了本次变更的主要目标，即将原生 Codex CLI 选择与 Desktop 安装识别解耦。标题简洁且与变更内容直接相关。
Description check		描述详细说明了 CLI 参数、优先级、路径校验、环境变量转发、兼容性、测试和文档变更，且内容与变更集一致。
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[VirgilMing]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.