Open Interpreter 开发工作流实战指南：Bug 修复、代码审核、安全重构与文档同步

2026-09-06 18:58:49作者：尤峻淳Whitney

导读

本文基于 docs/workflows.md 整理，聚焦 Open Interpreter（本仓库 codex-rs 内核驱动的编码智能体）在日常开发中的四类可重复工作流：修复 Bug、审核 Diff、安全重构与保持文档更新。无论你使用全屏 TUI 交互，还是在脚本与 CI 管道中用 interpreter exec 非交互执行，都能从文中拿到可直接落地的操作步骤、命令与源码级依据，让 AI 成为团队里可靠、可复现的结对开发者。

适用前提：文中命令与行为以当前仓库（README.md）为基准。TUI 命令在交互界面中输入，interpreter exec 属于非交互子命令，适用于脚本与 CI。

一、修复 Bug：先复现，再修改，最后回归

修复 Bug 是 AI 编码智能体最容易“自作聪明”的场景：Agent 往往快速给出补丁，却因没有先复现而对根因判断错误。docs/workflows.md 给出了一条克制而严谨的五步流程：

从仓库根目录开始：让会话的工作目录锚定在仓库根，保证相对导入、测试路径与 Git 命令都基于同一上下文。
提供复现步骤和限制条件：把可稳定复现的最小操作序列交给 Agent，并明确边界（如“不得改动 X 模块”“只允许修改 src/parser.rs”）。
在编辑之前，先让 Agent 复现问题：这是整条流程的核心纪律。Agent 应先运行复现命令并确认观察到失败/异常，再谈修改，避免“盲改”。
审核补丁：不要直接信任 AI 生成的改动，逐行检查其补丁是否符合预期且没有引入新的风险。
让它重新运行复现步骤并进行项目检查：修改完成后要求 Agent 重跑复现以证明“确实修好了”，同时执行项目测试与静态检查防止回归。

实操：如何把“复现”落到实处

复现是否可信，取决于你给 Agent 的环境与证据。Open Interpreter 提供了三种让任务可运行、可验证的通道：

交互式（TUI）：直接在同一仓库目录下用自然语言发起会话，借助 /mention 把相关文件加入对话上下文（参见 docs/slash_commands.md）。

非交互式（一次性任务）：适合把 Bug 描述作为脚本参数执行，输出人类可读的结论到 stdout：

interpreter exec "在 src/parser.rs 中复现并修复一个 bug：先运行复现命令，再修改，最后重跑测试"

管道输入复现证据：把复现产物直接喂给提示词，能显著提升 Agent 对现场的还原度：

# 把一段失败日志作为上下文交给 Agent
cat reproduction.log | interpreter exec "基于这段日志定位并修复崩溃，修复前先复现"

# 把当前工作区改动喂给 Agent，让它在真实 diff 上排查
git diff | interpreter exec "解释这段 diff 并标出高风险改动"

以上非交互用法详见 docs/exec.md。修复类任务应优先限制在只读沙箱或带审批的策略下进行，防止 Agent 在仓库外乱写文件——--sandbox 与 --ask-for-approval 旗标可覆盖默认沙箱与审批姿态。

源码依据：Review 子命令的实现结构

“审核补丁”这一步可以交给内置的 Review 通道（详见下一节）。从源码结构看，CLI 将 Review 建模为一个独立子命令：在 codex-rs/exec/src/cli.rs 中可以看到 Review(ReviewArgs) 变体及其注释“Run a code review against the current repository.”，即一次针对当前仓库的只读代码审查会话。

二、审核 Diff：用内置 Review 通道守住合并门槛

docs/workflows.md 明确指出，代码审查的产出应优先暴露 Bug、回归、缺失的测试与高风险行为，而非停留在风格建议上。Open Interpreter 把这套审查能力做成了开箱即用的命令。

TUI 内一键审查

在交互式界面中输入：

/review

该命令“审查当前改动中的 Bug 与回归”（见 docs/slash_commands.md 的 Files and Code 分组）。审查依据的是当前工作区未提交的改动。

非交互式：`interpreter exec review`

在不需要打开 TUI 的场景（本地脚本、CI、提交前钩子）直接运行：

interpreter exec review --uncommitted

更细粒度的目标选择由三个互斥的参数提供，见 codex-rs/exec/src/cli.rs 中 ReviewArgs 的定义：

参数	作用	冲突/约束
`--uncommitted`	审查已暂存（staged）、未暂存（unstaged）与未跟踪（untracked）的全部工作区改动	默认 `false`，与 `--base`、`--commit`、位置 prompt 互斥
`--base <BRANCH>`	相对给定基础分支（base branch）审查改动	与 `--uncommitted`、`--commit`、位置 prompt 互斥
`--commit <SHA>`	审查某个具体提交引入的改动	与 `--uncommitted`、`--base`、位置 prompt 互斥
`--title <TITLE>`	在审查摘要中展示的可选提交标题	仅与 `--commit` 配合使用（`requires = "commit"`）

典型用法：

# 审查相对 main 分支的全部改动
interpreter exec review --base main

# 审查某一次提交
interpreter exec review --commit abc123

从源码结构可以推断，--uncommitted、--base、--commit 与位置 prompt 之间的 conflicts_with_all 约束（见 codex-rs/exec/src/cli.rs）保证了每个会话只针对一个明确的“改动范围”，避免审查目标歧义——这也印证了工作流中“先给清晰上下文”的原则。

自定义审查指令

默认审查关注点之外，你可以注入团队专属的审查规范，例如强制要求“检查是否补充了回归测试”“只关注安全边界”。传入文本即可：

interpreter exec review --base main "重点检查认证模块的越权风险，并指出缺少的测试"

传入 - 则从 stdin 读取完整审查规范，适合把长篇幅的审查 check-list 放入文件后复用：

cat review-checklist.md | interpreter exec review --base main -

让审查结果可被机器消费

审查输出会随会话以事件流形式产出。使用 --json 可让每一行都成为一个 JSON 事件（进度、工具调用、文件改动、推理摘要、最终消息），配合 --output-last-message/-o 可以把最终审查结论落盘：

interpreter exec review --uncommitted --json -o review-result.txt

若希望最终答复严格满足固定结构，可搭配 --output-schema <file> 要求输出符合 JSON Schema（详见 docs/exec.md）。

三、安全重构：先计划，再小步执行

重构是最容易破坏行为的任务。docs/workflows.md 给出的原则是：让 AI 先产出计划，确认方向正确后再动手，并且分小阶段执行、每阶段跑测试。

在 TUI 中使用 `/plan`

当你想让 Agent 先勘察、再提议、最后才改动时，使用计划模式：

/plan
Split the oversized parser module without changing public behavior.

从源码结构看，“plan”是一种协作模式（collaboration mode）：在协议侧，客户端请求与服务器通知的枚举中均包含 "plan"（见 codex-rs/app-server-protocol/schema/json/ClientRequest.json）；在分析侧，会话减少器将 ModeKind::Plan 归一为 "plan" 标记（见 codex-rs/analytics/src/reducer.rs）。TUI 的聊天组件也专门维护了 plan 模式的测试场景（见 codex-rs/tui/src/chatwidget/tests/plan_mode.rs），说明计划模式是经过专门测试验证的一等公民功能。

计划模式下 Agent 倾向于只读勘察：它会读取模块结构、梳理公共 API、评估拆分风险，在改动任何文件之前把“怎么拆、分几步、每步验证什么”交给你确认。

拆解为可验证的小阶段

在计划被确认后，分阶段执行并在阶段之间运行测试是防回归的关键：

每个阶段只做一次小范围的机械改动（例如：先移动类型定义、再迁移函数、最后调整导出）。
每完成一个阶段就运行模块测试与 cargo test/just test 等仓库级检查（本项目为 Bazel + Cargo 双轨构建，可参考 justfile 中定义的常用任务）。
任一阶段测试失败立即回滚该阶段，而不是带着失败继续推进。

非交互模式下的“计划—执行”接力

如果你希望在脚本里也贯彻“先计划后执行”，可以利用 interpreter exec resume 把两段会话串起来：第一段让 Agent 产出计划并落盘，第二段基于计划继续执行：

interpreter exec "为拆分超大 parser 模块产出一份分阶段计划，不改任何代码" -o plan.md
interpreter exec resume --last "严格按 plan.md 执行第一阶段，并在每阶段后运行测试"

exec resume 会续接最近一次非交互会话（--last），或按会话 ID 精确续接（见 docs/exec.md）。

用 Review 子命令给重构收尾

重构完成后，把“行为是否改变”交给机器检验：先跑完整测试，再对改动跑一次 Review，让审查输出专门盯“回归”类问题：

interpreter exec review --base main "本次为纯重构，请重点确认没有行为改变、没有缺失测试"

这正好呼应 docs/workflows.md 对审查输出的定位——Bug、回归、缺失测试与高风险行为优先。

四、保持文档更新：让文档与代码同步演进

代码改了文档却忘了更新，是所有团队的痛点。docs/workflows.md 提供了一条低成本同步路径：

把 Agent 指向已修改的文件：会话上下文限定在本次改动涉及的文件，避免 Agent 对无关模块“顺手”改写文档。
让它更新面向用户的文档：明确目标是“面向用户”的文档，例如 CLI 参考、配置参考、使用指南。
保持私有工作区细节不出现在产品文档中：强调信息边界——内部路径、密钥占位、团队隐私信息不得进入公开文档。

实操组合

# 让 Agent 基于最近改动更新 docs 下相关文档
interpreter exec "检查 git diff 中涉及命令/配置的改动，并同步更新 docs/ 下对应的用户文档；不要写入任何私有路径或内部细节"

在 TUI 中则可以 /mention 指定本次改动的文件，然后下达同样的指令。结合交互式文档维护场景，Open Interpreter 还提供 /init 帮助生成 AGENTS.md 项目指南（见 docs/slash_commands.md），它能为后续的文档类任务提供统一的“写作规范”上下文。关于文档约定与风格，可进一步参考仓库中的 docs/contributing.md 与根目录的 AGENTS.md。

对于中文或双语仓库，可显式要求 Agent 同时核对两种语言版本（本仓库维护了 docs/ 与 docs/zh/ 两套镜像文档，可作为对照样例，例如 docs/workflows.md 与 docs/zh/workflows.md）。

五、工作流速查总览

工作流	交互式（TUI）	非交互式（exec）	关键纪律
修复 Bug	自然语言 + `/mention`	`interpreter exec "先复现、再修改、后回归"`	编辑前必须先复现；改完重跑复现与项目检查
审核 Diff	`/review`	`interpreter exec review --uncommitted \| --base <BRANCH> \| --commit <SHA>`	优先暴露 Bug、回归、缺失测试与风险行为；支持自定义审查指令
安全重构	`/plan` + 分阶段执行	先产出计划，`exec resume` 续接执行	先计划、小阶段推进、阶段间跑测试、重构后用 Review 防回归
文档同步	`/mention` 改动文件后指示更新	基于 `git diff` 定向更新 `docs/`	只写面向用户的文档；私有工作区细节不得外泄

四条工作流共享同一条底层原则：AI 能稳定产生正确结果的前提，是清晰的目标范围（Diff/Commit/文件集合）、可验证的证据（复现/测试/检查）以及人与 Agent 之间的阶段闸门。把这套方法沉淀进团队日常后，Open Interpreter 就能从“偶尔惊艳的代码生成器”，变成流程中可预期、可审计的一环。