本节只看架构设计。先不要陷入源码函数名，先理解它为什么要拆成 Claude 入口、Node companion、Codex app-server、job store 四层。
这座桥解决的核心问题是什么？
codex-plugin-cc 要解决的不是“怎么执行一条 shell 命令”，而是怎么让 Claude Code 把一个任务委派给另一个独立 agent runtime。
这件事天然有 5 个问题：
| 问题 | 如果不设计桥，会怎样 |
|---|---|
| 入口问题 | Claude Code 只认识 slash command，不认识 Codex thread |
| 执行问题 | Codex 能跑任务，但不知道 Claude 的命令上下文 |
| 状态问题 | 后台任务需要 jobId、log、结果和取消能力 |
| 恢复问题 | 继续上次任务需要找到 Codex threadId |
| 权限问题 | Claude 权限和 Codex sandbox 不是同一套东西 |
它为什么不是直接调用 codex exec？
直接调用 codex exec 可以完成一次性任务，但很难自然支持这些能力：
- 后台任务：命令返回后还要继续跑，并能查询状态。
- 恢复任务：下一次调用要接回上一次 Codex thread。
- 结果管理：Claude Code 需要用
/codex:result拉结果。 - 取消任务：需要能定位 job 并终止 worker。
- 统一配置：模型、effort、sandbox、workspace 都要映射成 Codex 可理解的参数。
所以它选择接 Codex app-server，用 thread/turn 这个更高层协议，而不是只跑一个一次性 CLI 命令。
桥的四层设计
```mermaid
flowchart TD
subgraph Claude[Claude Code 插件世界]
C1[commands/rescue.md]
C2[agents/codex-rescue.md]
end
subgraph Node[Node Companion 世界]
N1[codex-companion.mjs]
N2[task/status/result/cancel]
N3[job store]
end
subgraph Codex[Codex Runtime 世界]
X1[Codex app-server]
X2[thread/start 或 thread/resume]
X3[turn/start]
end
C1 --> C2
C2 --> N1
N1 --> N2
N2 --> N3
N2 --> X1
X1 --> X2
X2 --> X3
```
第一层：Claude 插件入口
Claude Code 的插件系统天然支持 slash command 和 subagent。/codex:rescue 借这个入口获得用户命令，但不把业务逻辑塞在 Markdown 命令文件里。
这种设计的好处是：入口很薄，逻辑集中到脚本层。
第二层：Subagent 转发层
codex-rescue subagent 的设计很克制：它不是另一个会自己分析问题的 agent，而是一个受控转发器。
它负责把 Claude Code 的 agent 调用变成一次明确的 Bash/Node 调用。
这是关键点：subagent 不是为了“多一个智能体”，而是为了拿到 Claude Code 插件体系里的一个可编排执行点。
第三层：Node companion 协议层
Node companion 是真正的桥。它承担协议转换：
flowchart LR A[Claude 传来的自然语言任务和 flags] --> B[parse args] B --> C[build task job] C --> D{foreground or background} D -->|foreground| E[直接等待 Codex turn] D -->|background| F[写 job store 并 spawn worker] E --> G[render result] F --> H[status/result/cancel 查询]
它把用户输入拆成 job、prompt、flags、sandbox、model、effort、resumeThreadId 等结构化信息。
第四层：Codex app-server 执行层
Codex app-server 才是真正执行任务的地方。它懂 Codex 的 thread、turn、工具调用、sandbox 和登录态。
Node companion 不自己实现 agent loop，而是把任务交给 Codex 已有 runtime。
这套设计最值得学的地方
它的精妙点是边界非常薄：
- Markdown 命令只做路由。
- subagent 只做转发。
- Node companion 只做协议转换和状态管理。
- Codex runtime 只做 agent 执行。
每层都避免做不属于自己的事，所以整个系统容易扩展：后面新增/codex:review、/codex:status、/codex:cancel时，不需要推翻前面的设计。