Open Interpreter 实战用例指南：从 Bug 修复、代码审查到数据文档工程的高效任务交付

本文围绕仓库文档 docs/zh/use-cases.md 展开：它会告诉你在什么条件下把任务交给 Open Interpreter（当前仓库提供的 interpreter CLI）效果最好，并逐类给出工程、审查与质量、数据与文档三大场景下可直接套用的任务清单。读完你不仅能把"修 Bug、审 PR、分析日志"这些高频需求准确地表述成 prompt，还能理解为什么"具体的工作空间、清晰的约束、验证目标"三者缺一不可——以及它们在本仓库配置与源码中分别对应着什么。

一、何时该把任务交给 Agent：三条前提是效果的分水岭

原文档开篇即给出全篇最重要的判断标准：

Open Interpreter 在您为其提供具体的工作空间、清晰的约束以及验证目标时表现最佳。

这三条不是空话，在当前的实现中都对应着实实在在的机制：

前提	通俗解释	对应实现入口
具体的工作空间	让 Agent 知道该在哪动手、能碰哪些目录	启动目录（--cd）、沙箱范围（--sandbox / sandbox_mode）、可写目录（--add-dir）
清晰的约束	明确不许做的事，如"不要改 API 形状"	审批策略（approval_policy）、AGENTS.md / 项目规则、hooks 拦截
验证目标	一句能判定"任务是否真的完成"的命令	交互中的复现/测试重跑，interpreter exec 的 --verify 追加校验回合

例如工作目录与沙箱范围，在 docs/cli-reference.md 的全局参数表中对应 --cd, -C <path>（从其它工作目录启动）、--sandbox, -s <mode>（read-only / workspace-write / danger-full-access 三档）、--add-dir <path>（追加可写工作区根目录）。这些枚举值也可以在生成的 JSON Schema codex-rs/core/config.schema.json 中通过 sandbox_mode（见其中第 842-844 行引用的 SandboxMode 定义）与 approval_policy（第 408-410 行引用的 AskForApproval 定义）交叉验证。

一句话归纳：docs/prompting.md 的表述更为精炼——"好的 Open Interpreter 提示词应当是具体的：包含观察到的现象（observed problem）、预期行为（expected behavior）、约束（constraints）以及验证命令（verification commands）。"

二、工程类任务：让 Agent 做你最不想做的那部分编码工作

原文档列举的六项工程用例是使用频次最高的场景，每一项都值得配上一个合格的 prompt 骨架。

1. 根据复现步骤修复 Bug（Fix a bug from reproduction steps）

这是最容易翻车也最值得标准化的任务。失败的关键在于给了模糊目标（"帮我修个 bug"），而成功的要诀是把复现步骤喂给 Agent，并让它先复现、后修改、再复验。

docs/prompting.md 给出了完整的 Bug Fix Template，可直接套用：

Bug: Clicking Save shows success but does not persist the setting.
Repro:
1. npm run dev
2. Open /settings
3. Toggle Enable alerts
4. Click Save
5. Refresh; the toggle resets

Constraints:
- Do not change the API shape.
- Keep the patch minimal.
- Add a regression test if practical.

Start by reproducing, then patch, then rerun the repro and tests.

与之一致，docs/workflows.md 的 "Fix a Bug" 工作流把过程拆成五步，顺序即纪律：

1. 在仓库根目录开始（确保工作空间正确）；
2. 提供复现步骤与约束；
3. 要求 Agent 在动手编辑前先复现；
4. 人工审查补丁；
5. 要求它重跑复现步骤与项目检查。

注意约束要显式给出，不要假设 Agent 知道。docs/prompting.md 给了一个非常生动的对比：与其说"fix auth"，不如说 "run pnpm test -- auth and fix the failing refresh-token test"；与其假设 Agent 知道不能动迁移脚本，不如直接说 "do not touch migrations"。

2. 解释不熟悉的代码路径（Explain an unfamiliar code path）

接手他人代码或接手新仓库时，这是性价比最高的任务之一。它天然是低风险场景——Agent 只读不写，尤其适合在 read-only 沙箱下执行：

interpreter exec "explain the request flow from cli entrypoint to app-server thread execution"

也可以借助 TUI 的 @ 文件引用把问题锚定到具体文件（docs/prompting.md 明确建议 "Mention files with @ in the TUI or attach relevant files/images from the command line"）。当前仓库自身就非常适合这类练习，例如从 codex-rs/cli/src 的 CLI 入口追踪到 codex-rs/core/src 的 agent 主循环，属于典型的跨 crate 代码路径解释任务。

3. 重构模块而不改变行为（Refactor a module without changing behavior）

重构的最大风险不是改不动，而是静默改变行为。因此正确姿势是先要方案、分小步执行、步间跑测试。

docs/workflows.md 的 "Refactor Safely" 流程即为此设计：先用 /plan 要求 Agent 给出计划，再以小阶段推进：

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

然后按阶段执行，并在每个阶段之间运行测试——仓库的贡献规范 AGENTS.md 也同样强调按 crate 粒度运行测试（just test -p <project>），这种"小步 + 每步验证"的工程纪律天然适用于 Agent 重构任务。约束侧可以显式写明 "Keep the patch minimal" / "Do not change the API shape"（复用模板措辞）。

4. 为回归问题添加测试（Add tests for a regression）

先让 Agent 写一个能复现该回归的测试并看着它失败，再让它修复——这是 TDD 风格的反向应用。写作 prompt 时，把"证明回归被锁住"作为验证目标：

Add a regression test that fails on the current main for issue #NNN,
then make it pass with the minimal fix. Run the targeted test suite to show both states.

在该仓库内部，回归测试的惯例可见 AGENTS.md：行为变更必须补集成测试，UI 可见变更必须带 insta 快照覆盖（just test -p codex-tui 后以 cargo insta 审阅 .snap.new 文件）。把这类约定写进约束，Agent 产出的补丁就能贴合项目规范。

5. 升级依赖或 API 集成（Upgrade a dependency or API integration）

依赖升级是"文档很容易骗人"的场景，重点应放在运行时可验证的证据上：

Upgrade <crate/dependency> to <version>. Update the affected call sites.
Constraints: keep the public API surface stable unless the upgrade forces a break.
Run the full workspace tests and show any remaining compile errors.

注意仓库对依赖变更有一套可观测的约束：改动 Cargo.toml/Cargo.lock 后需同步刷新 MODULE.bazel.lock（见 AGENTS.md，可通过 just bazel-lock-update 完成），否则 CI 会因锁文件漂移失败。把这类仓库级副作用一并写进约束，能让"升级依赖"这类跨构建系统的任务少走弯路。

6. 保持文档与代码同步（Keep docs in sync with code changes）

代码变更后文档过期是普遍痛点，Agent 很适合充当"文档同步员"。docs/workflows.md 的建议是：把变更涉及的文件指给它，要求它更新面向用户的文档，同时明确不要把私有工作区细节写进产品文档。

Update the docs that describe the changed files in this diff.
Do not leak local paths or environment-specific values into user-facing docs.

三、审查与质量类任务：把 Agent 当作第二双眼睛

原文档这一节的四类任务都有一个共同点：它们是判读性任务，输出多为分析报告而非代码修改，天然适配 read-only 沙箱与高推理档位。

1. 审核 Pull Request 差异（Review a pull request diff）

docs/workflows.md 给出了两条路径，一条命令行、一条交互式：

interpreter exec review --uncommitted

在 TUI 中则直接用斜杠命令：

/review

其语义在 docs/slash_commands.md 中被定义为"Review current changes for bugs and regressions"（对应 /diff 显示当前工作树差异）。docs/workflows.md 进一步给出审查输出的优先级：bug、回归、缺失的测试、危险行为应排在前面。

结合本仓库的代码评审规则（AGENTS.md 的 Code Review Rules），可让审查更有针对性：crate API 表面是否最小化、模型可见上下文是否有超界/超长风险、对外集成面（app-server API、CLI 参数、配置加载）是否有破坏性变更、是否遵守了单次变更 800 行的规模红线。这些规则本身就是可注入审查 prompt 的 checklist。

2. 审计安全敏感代码（Audit security-sensitive code）

安全审计的边界意识比什么都重要。两种推进方式：

• 人工在环：将审计限制在 read-only 沙箱，让 Agent 输出"风险点 + 证据行号 + 修复建议"，不直接改代码；
• 机制兜底：用 docs/hooks.md 在工具调用前/后加确定性校验（hooks 的用途文档明确包括 policy checks、prompt scanning、post-run validation），或为疑似危险命令返回 permissionDecision: "deny"。

docs/hooks.md 同时强调了一个重要立场："Hooks are guardrails, not a substitute for sandboxing and approvals."（hooks 是护栏，不能替代沙箱与审批。）对安全敏感代码，最低限度也要让审批策略处于 on-request，而不是用 --yolo 之类绕过手段。

3. 对 CI 失败日志进行分流（Triage failing CI logs）

把 CI 日志直接喂给 Agent 是最省事的输入方式之一——非交互模式支持从 stdin 读取上下文（docs/exec.md）：

curl -sL <ci-log-url> | interpreter exec "triage these CI failures: group by root cause and give the first fix step for each"

对无法出网的沙箱环境，可以把日志保存到一次性工作空间再分析（见下文"数据与文档"）。分流的产出建议格式化为：失败分组 → 根因推断 → 每条对应的修复动作 → 标出需要人工判断的不确定项。

4. 将不稳定测试报告转化为修复计划（Turn a flaky-test report into a fix plan）

flaky 测试的难点在于"不是每次都挂"，因此产出的核心是计划而非盲改。要求 Agent 先给出假设清单与取证步骤，再给出分级修复方案：

Turn this flaky-test report into a fix plan: list candidate root causes with
evidence to collect, then order fixes from cheapest to most invasive.
Do not modify code yet.

把这类任务的输出限制为 plan，也正是 docs/workflows.md 中 /plan 的用途；当需要他人代审时，还可结合 docs/auto-review.md 由 reviewer agent 评估符合条件的审批请求（配置 approvals_reviewer = "auto_review"），但该文档同时提醒：auto-review 不改变沙箱，只有评审策略与沙箱足够窄时才能使用。

四、数据与文档类任务：在隔离环境中做一次性分析

1. 在一次性工作空间中分析 CSV 或日志导出（Analyze CSV or log exports in a disposable workspace）

"一次性工作空间"意味着用完即弃、不污染日常环境。落地方式有两种：

• 交互式：/new 开启新对话，配合 /sandbox-add-read-dir <path> 仅授予对数据目录的读权限（docs/slash_commands.md）；
• 非交互式：用 interpreter exec 加 --ephemeral（不落盘会话记录）一次性跑完（docs/exec.md）。

interpreter exec --ephemeral \
  "analyze data/export.csv: find the columns with the most missing values and sketch a cleaning plan" 

数据任务尤其适合加 --json 或以 --output-schema <file> 要求最终答案符合指定 JSON Schema——既方便下游脚本消费，也把"输出结构"变成了硬性验证目标（docs/exec.md）。

2. 根据源文件起草内部文档（Draft internal documentation from source files）

与"保持文档同步"不同，这里是从无到有：把源文件锚定为上下文，让 Agent 起草说明性文档。

Draft internal docs for src/parser.rs covering: module responsibilities,
entry points, error handling, and invariants a contributor must preserve.
Cite line ranges for each claim.

仓库内可直接观察到类似的"读源码写说明"产物，例如 codex-rs/README.md、codex-rs/thread-store/README.md 等 crate 级说明，以及生成的配置 Schema codex-rs/core/config.schema.json（文档明确说明它可用于编辑器补全与 CI 校验，见 docs/config.md）。

3. 将 issue 讨论串转换为实现任务（Convert issue threads into implementation tasks）

长 issue 讨论串信息密度低、噪音大，交给 Agent 提炼成可执行任务列表很划算：

cat issue-thread.md | interpreter exec - \
  "convert this issue thread into an implementation task list: goal, constraints, affected files, acceptance criteria, and open questions needing maintainers"

这里"能证明工作完成的命令"（acceptance criteria）会成为后续编码任务 prompt 的验证目标来源——正好闭环回原文档最后的建议：好提示词包含目标、相关文件、约束、以及能证明工作完成的命令。

五、好提示词的四个要素：目标、文件、约束、验证命令

原文档以一句话收束全文，值得逐字拆解：

好的提示应包括目标、相关文件、约束以及能够证明工作完成的命令。

结合 docs/prompting.md 与 docs/workflows.md，四个要素可以扩成一张自检表：

要素	回答什么问题	写法要点	仓库中的支撑工具/配置
目标	要达成什么结果	一句话动词开头；避免 "fix auth" 这类模糊说法，改为 "run pnpm test -- auth and fix the failing refresh-token test"	/plan、exec 直接传 prompt
相关文件	让 Agent 在哪找证据	用 @ 引用具体文件（TUI），或命令行附带文件/截图；上下文宁精勿滥（"too much irrelevant context makes the task harder"）	/mention、-i <image>、stdin 管道
约束	哪些事情绝对不许做	显式写出："do not touch migrations"、"keep the patch minimal"、"do not change the API shape"	sandbox_mode、approval_policy、hooks、AGENTS.md
验证命令	怎么证明真的完成了	给出可重跑的命令："rerun the repro and tests"	exec --verify、--output-schema、项目测试命令

把"验证命令"落到配置与执行层面

"验证目标"在 Open Interpreter 中不只是 prompt 措辞，它有对应的运行机制：

• 非交互模式的显式校验：interpreter exec 提供 --verify，含义是"在退出前额外运行一个完成度检查回合"（docs/exec.md），--output-schema 可要求最终回答匹配指定 JSON Schema，-o <file> 可把最终消息落盘供 CI 断言。
• 交互模式的复核工作流：Bug 修复流程要求"先复现 → 修改 → 重跑复现与测试"（docs/workflows.md），三步构成闭环。
• Lifecycle 校验：若需要在工具调用前后执行确定的检查（如禁止某类命令、记录审计日志、运行后校验），hooks 的 PreToolUse / PostToolUse 事件可承载；其中 PreToolUse 甚至能直接拒绝（permissionDecision: "deny"）某个工具调用（docs/hooks.md）。

六、让用例真正跑起来：CLI 与配置速查

把上面的任务清单落地到命令行时，最常用的是这套骨架（命令细节见 docs/cli-reference.md 与 docs/exec.md）：

# 交互式（默认），适合探索、解释、重构等需要来回对话的任务
interpreter

# 非交互式，适合 CI、脚本、单次分析任务；可选 --json / --verify
interpreter exec "fix the failing test"
interpreter exec --json "summarize this repo"
interpreter exec review --uncommitted
cat task.md | interpreter exec -

任务相关的环境控制：

# 在工作目录与沙箱层面给出"具体的工作空间"
interpreter --cd /path/to/repo --sandbox workspace-write
interpreter --add-dir /extra/writable/root

# 通过 profile 固化某类用例的运行参数（见 docs/config.md 的 Profiles）
interpreter --profile review

典型的 review profile 会把沙箱收紧到只读、推理强度拉高（docs/config.md）：

[profiles.review]
model_reasoning_effort = "high"
sandbox_mode = "read-only"

会话管理类用例（改到一半换分支、想回到旧思路）则依赖 docs/sessions.md 与 docs/slash_commands.md 中的命令：/new 开新会话、/resume / interpreter resume --last 续接、/fork 从历史分叉出新线程、/compact 压缩长会话，长任务可搭配 /ps、/stop 管理后台任务。

结语：用例的价值在于"可验证的具体"

把 docs/zh/use-cases.md 通读一遍会发现，它给出的不是一个功能清单，而是一套任务交付方法论：给具体的工作空间（--cd/--sandbox/--add-dir），讲清晰的约束（审批策略、hooks、禁止事项），定验证目标（复现命令、--verify、测试重跑），然后从工程、审查与质量、数据与文档三大类任务中挑出你手头的那一件，写成一个四要素齐备的 prompt。它之所以"在此前提下表现最佳"（原文：Open Interpreter is strongest when you give it a concrete workspace, clear constraints, and a verification target），是因为这三个前提恰好对应了当前实现中沙箱、审批与校验三套机制的边界——把 Agent 放进明确边界里，它才能真正替你干活。