Open Interpreter 实战工作流指南：用可重复的开发方法完成修 Bug、Diff 审查与安全重构

Open Interpreter（当前仓库为 open 模型编写的编程代理实现）不仅是"能执行命令的聊天工具"，更应当以可重复、可审查、可回退的工作流方式嵌入真实开发任务。本文以 docs/zh/workflows.md 的四个工作流为主线，逐一拆解"修复 Bug、审查 Diff、安全重构、保持文档更新"的标准动作，并结合仓库源码剖析 interpreter exec review 的参数体系与 /plan、/review 等交互命令的底层实现。读完本文，你将得到一套可以直接落地到日常提交前的"复现 → 修改 → 审查 → 回归"闭环方法论。

工作流设计思想：为什么"可重复"如此重要

Open Interpreter 这类代理每一次生成都会因为模型采样而略有不同，因此项目文档给出的核心方法论是：把任务分解成可验证的小步骤，在每一步之间保留检查点（复现、计划、审查、回归）。这与 codex-rs/core 中 Op::Plan、Op::Review 等会话原语的划分是一脉相承的——代理在运行时会话内经历"规划 → 执行 → 审查"的阶段轮转，而人工工作流要做的就是主动控制这些阶段的触发时机。

四个工作流有一个共同的输入前提：从仓库根目录开始。无论是让代理定位模块、生成相对路径还是计算 git diff 基准，稳定的工作目录能显著降低代理出错的概率。

工作流一：修复 Bug（复现优先于编辑）

最经典的开发任务——修 Bug——被提炼为 5 个严格排序的步骤：

1. 从仓库根目录开始：保证代理能正确读取项目结构、找到配置文件与测试入口。
2. 提供复现步骤和限制条件：例如"cargo test parser 失败，报错 X；不要改动公共 API"。清晰的约束能让代理收敛搜索空间。
3. 在编辑之前，让 Open Interpreter 先复现问题：让代理先运行一遍最小复现（写一个失败测试或执行复现脚本），确认它看到了与人类相同的失败输出，再允许它进入编辑阶段。
4. 审核补丁：通过人工查看代理产生的 diff，或用 /review 让代理自审（见下一节），确保补丁只解决目标问题。
5. 让它重新运行复现步骤并进行项目检查：重跑复现脚本确认红灯变绿，再运行该模块的测试套件、linter 与类型检查，防止回归。

这套流程的精髓是"先红后绿"的测试驱动节奏，而且把"复现"作为独立的代理动作，而不是编辑动作的附属品——这也是判断补丁是否真正有效的最强证据。

工作流二：审核 Diff（Review a Diff）

在提交合并之前，用代码审查模式检查当前工作区改动，是成本最低的防回归手段。

命令行：非交互式审查

interpreter exec review --uncommitted

--uncommitted 表示审查目标是"暂存、未暂存与未跟踪的改动"（staged、unstaged 与 untracked changes）。在仓库源码中，这条命令最终会落入 codex-rs/exec/src/cli.rs 的 ReviewArgs 定义，并映射为 build_review_request 中的 ReviewTarget::UncommittedChanges。

从同一份 ReviewArgs 源码可以看出，审查目标远不止"未提交改动"一种：

参数	含义	与其它参数的互斥关系（源码 conflicts_with_all）
--uncommitted	审查工作区中已暂存、未暂存及未跟踪的全部改动	与 --base、--commit、自由 prompt 互斥
--base <BRANCH>	以指定基准分支为参照，审查相对该分支的改动	与 --uncommitted、--commit、自由 prompt 互斥
--commit <SHA>	审查某个历史提交引入的改动	与 --uncommitted、--base、自由 prompt 互斥
--title <TITLE>	为该提交审查提供展示用标题（requires = "commit"，依赖 --commit）	必须配合 --commit 使用
[PROMPT]	自定义审查指令；传入 - 时从标准输入读取	与上述目标参数互斥

这五个参数在 build_review_request 中按优先级依次判断：先看 --uncommitted，再看 --base、--commit，最后是自定义 prompt；若四者皆空，则直接报错 Specify --uncommitted, --base, --commit, or provide custom review instructions。这意味着自定义 prompt 模式下代理按你给出的指令自由审查，例如让指定领域专家视角检查某个子目录的安全隐患。

交互模式：TUI 内的审查命令

在 Open Interpreter 的交互式 TUI 中，直接输入：

/review

它等价于对"当前更改"发起一次审查。根据 docs/zh/slash_commands.md，/review 的定位是"审查当前更改以发现 bug 和回归"。TUI 中还有几个与审查强相关的前置命令值得串用：/mention 把特定文件加入会话上下文，/diff 直接展示当前工作区 diff，/review 对其发起审查。

审查输出的优先级

无论走命令还是 TUI，审查报告都应按如下优先级组织：

1. Bug（明确的缺陷与错误逻辑）；
2. 回归（会破坏现有行为的改动）；
3. 缺失的测试（行为变更没有配套用例覆盖）；
4. 风险行为（副作用大、边界不清、可能引发生产问题的操作，例如删除文件、改写数据库、绕过沙箱等危险操作）。

这也是 docs/zh/auto-review.md 所描述的统一审查策略：/review 与 interpreter exec review 共用同一套审查范式，从源码看审查任务最终进入会话层 Op::Review { review_request }（见 codex-rs/core/src/session/handlers.rs 的 Op::Review 分支）与执行层的 InitialOperation::Review（见 codex-rs/exec/src/lib.rs 的对应分支），属于代理内置的一等会话操作。

工作流三：安全重构（Refactor Safely）

重构最容易失控的点是"改着改着就改偏了"。文档给出的策略是计划先行、小步执行、阶段间跑测试：

1. 先请求计划，在 TUI 输入 /plan 并给出目标约束。文档给出的典型示例：

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

（将过大的解析器模块拆分，但不得改变公共行为。）

2. 按阶段执行：每个阶段只做计划中一小块改动。
3. 阶段之间运行测试：每完成一个阶段就跑一遍相关测试，一旦变红立刻停下排查，而不是攒到最后一次性面对海量失败。

为什么先把 /plan 推给代理？按 docs/zh/interactive.md 的说明，/plan 会让代理"在编辑前先检查并提出建议"——即先让代理读代码、产出方案、列出影响面，人类批准后再动手。把"变更公共行为"这类硬约束写进计划，等于给代理上了一道行为护栏。

工作流四：保持文档更新（Keep Docs Current）

代码与文档脱节是仓库腐化的主要来源。工作流建议：把 Open Interpreter 指向已修改的文件，让它更新面向用户的文档。

实操要点：

• 指向变更文件：用 /mention（TUI）或在提示语中直接给出相对路径，例如 docs/zh/cli-reference.md 中新增命令的用法段、docs/zh/config-reference.md 中新增配置项说明。
• 限制范围：要求它只更新受影响的用户文档章节，避免顺手大改无关段落，也便于人工 diff 审查。
• 隐私边界：保持私有工作区的细节（内部主机名、密钥、个人路径、未公开的设计决策）绝不进入产品文档——文档面向的读者是最终用户与贡献者，不是内部备忘录。

如果仓库遵循了 AGENTS.md 之类的项目约定文件，也可以先让代理阅读根目录的 AGENTS.md 了解文档规范再动手，这能显著提高生成的文档与现有风格的一致性。

把四个工作流串成一条日常循环

以上四个工作流并不是孤立的清单，而是可以组合成提交前的标准循环：

1. 拿到 Issue → 按"修复 Bug"流程：先复现、后编辑；
2. 编辑完成 → /diff 查看改动、/review 或 interpreter exec review --uncommitted 自审；
3. 涉及结构性调整 → 先 /plan 获得方案批准，再分阶段执行、逐阶段跑测试；
4. 改动改变了公开行为或配置 → 让代理同步更新 docs 下的用户文档，并人工检查是否夹带私有细节。

对需要更细粒度审查的场景，可对照上文参数表使用 interpreter exec review --base main（对比主分支）或 interpreter exec review --commit abc123（审查指定提交），同样会遵循"Bug、回归、缺失测试、风险行为"的优先级输出。整个循环的核心思想始终不变：让代理的每一步输出都有可验证的锚点（复现结果、测试、diff、计划），人类只负责在每个锚点上把关。

快速参考：命令与相关文档

用途	命令 / TUI	相关源码与文档
审查未提交改动	interpreter exec review --uncommitted	codex-rs/exec/src/cli.rs、codex-rs/exec/src/lib.rs
审查相对分支改动	interpreter exec review --base <BRANCH>	同上
审查某个提交	interpreter exec review --commit <SHA>	同上
自定义审查指令	interpreter exec review "<指令>"	同上
交互式审查	/review	docs/zh/slash_commands.md
查看工作区 diff	/diff	docs/zh/slash_commands.md
编辑前先规划	/plan	docs/zh/interactive.md
把文件加入会话	/mention	docs/zh/slash_commands.md

若想深入每个命令的完整语义，可继续阅读仓库中的 docs/zh/exec.md（exec 子命令全览）、docs/zh/cli-reference.md（CLI 参考）与 docs/zh/auto-review.md（自动审查机制）；交互命令的完整清单见 docs/slash_commands.md。