Codex Runner

Codex Runner 是一个面向 Cursor / VS Code 的本地扩展，用侧边栏承载 Codex app-server 会话、历史恢复、模型设置、账号状态、patch/review 展示和本地终端入口。

完整安装、配置和日常操作见 Codex Runner 使用流程。

快速开始

开发环境首次安装：

npm install
npm run build

打包并安装到 VS Code：

npm run package
npm run install:vscode

打包并安装到 Cursor：

npm run package
npm run install:cursor

需要自动升级 patch 版本、构建、打包并安装时使用：

npm run deploy:vscode
npm run deploy:cursor

未指定目标时，npm run deploy:ide 会走统一安装脚本并按环境识别目标；明确要装 VS Code 时优先用 deploy:vscode。

使用入口

1. 在 IDE 中打开 Codex Runner 侧边栏，或执行命令 Codex Runner: Open Codex Runner。
2. 按需在设置里配置 cursorCodexRunner.codexRuntime、cursorCodexRunner.codexPath、默认模型、reasoning effort、service tier、approval policy 和 sandbox mode。
3. 确认 Codex 登录态保存在用户本机目录，例如 ~/.codex/auth.json，不要放进仓库。
4. 在侧边栏输入 prompt，或使用 Codex Runner: Run Selection 将当前选择内容发送给 Runner。
5. 对 patch/review 结果使用保留 segment、保留 file、保留 session、上一处/下一处变更和 diff parts 命令做复核。

敏感信息边界

仓库只保存扩展源码、脚本、测试、文档和调试辅助资产。不要提交以下内容：

• Codex 账号凭据、CODEX_HOME 内容、~/.codex/auth.json。
• .env、.env.*、*.local、日志、扫描产物、VSIX 包和构建输出。
• 代理账号密码、API key、Bearer token、外部 API token、带凭据的 remote URL。
• cursorCodexRunner.appServerEnv、cursorCodexRunner.terminalEnv、cursorCodexRunner.externalApi.token 中的真实值。

.gitignore 已排除 out/、dist/、*.vsix、.env、.env.*、.vscode/、日志和 .codex-runner-storage/。提交前固定运行：

npm run check:secrets
git status --short

npm run check:secrets 会扫描 Git 已跟踪文件和未忽略的新增文本文件，命中疑似密钥时会失败。公开发布或迁移仓库前，建议额外使用历史扫描工具复查完整 Git history。

目录结构

• src/extension/：VS Code/Cursor 扩展入口、sidebar webview 宿主、消息处理和编辑器集成。
• src/app-server/：Codex app-server 进程、JSON-RPC、会话恢复、live item、history、patch 和账号链路。
• src/session/：Runner tab/session 状态、持久化、草稿、workspace 同步和生命周期协调。
• src/runner/：review、tracked segment、diff parts、外部 API 和输出资源。
• src/shared/：配置、类型、运行时选择、代理、MCP、通知和通用工具。
• media/webview/：侧边栏前端脚本，按 core/、messages/、composer/、panels/ 拆分。
• scripts/：质量门禁、打包、安装、版本和发布辅助脚本。
• tests/：Node 基础回归测试。

本地开发

npm install
npm run build
npm run lint
npm test

开发时可用 watch 模式：

npm run watch

质量门禁

公开发布或提交前至少执行：

npm run build
npm run lint
npm test
npm run check:secrets
git diff --check

npm run lint 当前包含格式检查、文件体积检查、webview controller 依赖检查和 webview JS 类型检查。

发布产物

• 新 VSIX 输出目录：dist/vsix/
• 清理旧构建输出：npm run clean:out
• 清理历史 VSIX：npm run clean:artifacts

clean:artifacts 默认只清理旧 VSIX，保留最新若干个；不会删除源码或文档。