这篇是补基础概念的速查表。读前面几篇时,如果卡在 slash command、subagent、companion、app-server、thread、turn、job store、sandbox,就先看这里。
slash command 是什么?
Slash command 是 Claude Code 插件暴露给用户的命令入口,例如 /codex:rescue。它的作用像一个路由表:用户输入命令,Claude Code 找到对应的 Markdown 命令定义并执行里面的指令。
subagent 是什么?
Subagent 是 Claude Code 里可以被主对话调用的子代理。它可以有自己的说明、工具权限和行为约束。
在 codex-plugin-cc 里,codex-rescue subagent 的重点不是“更聪明”,而是“更可控”:它只负责把任务转给 Node companion。
companion 脚本是什么?
Companion 脚本 是插件随附的本地脚本,通常负责做模型不适合直接做的确定性工作,例如:
- 解析命令参数。
- 管理本地状态文件。
- 启动后台 worker。
- 调用外部 CLI 或本地服务。
- 格式化返回结果。
在这套设计里,codex-companion.mjs是桥接的核心。
app-server 是什么?
App-server 是 Codex 本地 runtime 暴露出来的服务入口。相比一次性 CLI 命令,它能管理更持续的会话结构,比如 thread 和 turn。
你可以把它理解成:Codex 的“本地后端”。
thread 和 turn 是什么?
| 概念 | 直觉理解 |
|---|---|
| thread | 一条可持续的 Codex 会话线 |
| turn | thread 里的一次用户请求和模型响应 |
| threadId | 用来恢复同一条会话线 |
| turnId | 用来追踪某次执行 |
| 如果没有 threadId,就很难做真正的 resume。 |
job store 是什么?
Job store 是 companion 层维护的任务登记表。它把后台任务变成可管理对象:
flowchart LR A[jobId] --> B[status] A --> C[threadId] A --> D[turnId] A --> E[log] A --> F[result]
没有 job store,后台任务就只是一个散落的进程,无法查询状态、读取结果或取消。
sandbox 是什么?
Sandbox 是 Codex 执行工具时的权限边界。例如只读、workspace 可写、是否能访问网络等。
在 /codex:rescue 里要特别注意:Claude Code 的权限和 Codex 的 sandbox 不是同一个东西。桥接过去以后,真正执行任务的是 Codex runtime。
为什么这套设计值得学?
因为它是一个很典型的低侵入桥接架构:
flowchart TD A[不要重写目标系统] --> B[找到目标系统已有入口] B --> C[写一个薄 companion 做协议转换] C --> D[用 job store 管理长任务] D --> E[把状态查询做成命令]