Open Interpreter 编程智能体实战用例指南：用具体工作区、清晰约束与验证目标驱动高质量交付

本指南基于 Open Interpreter（本仓库面向 Kimi K3、GLM 5.3 等开放模型优化的编程智能体）的官方文档整理而成。它的核心应用场景是：让一个具备终端执行能力的编程智能体在你的真实代码仓库中完成工程修改、代码审查与质量保障、数据分析与文档产出三类高频任务。读完本文，你将掌握一套可复用的任务设计方法——把"目标 + 相关文件 + 约束 + 验证命令"组合成高质量提示，并配合 TUI 的 /review、/plan 与非交互式 interpreter exec 把每条用例落到可执行的会话中。

一个前提：智能体在具体约束下表现最佳

docs/use-cases.md（中文镜像见 docs/zh/use-cases.md）开篇即给出使用要诀：

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

这三点缺一不可，对应的正是智能体在三类任务中能否收敛的关键变量：

• 具体的工作空间（concrete workspace）：在哪个仓库、哪个目录下干活，涉及哪些文件。Open Interpreter 以当前工作目录为默认工作区，~/.openinterpreter/ 保存配置与会话状态，AGENTS.md 从仓库根目录逐层向下生效（见 docs/agents_md.md）。
• 清晰的约束（clear constraints）：能改什么、不能改什么、范围多小。例如"不要改动 API 形状""补丁保持最小""不要动迁移文件"。
• 验证目标（verification target）：一条能证明"工作已完成"的命令，例如 pnpm test -- auth、cargo test -p codex-core。

在此基础上，好的提示应当包含四要素，这与 docs/prompting.md 中的 Bug Fix 模板完全一致：

提示要素	说明	示例
目标	期望达到的行为	"修复点击保存后设置不持久化的问题"
相关文件	通过 @ 或 /mention 指出的文件	src/settings.rs、web/App.vue
约束	不许越过的边界	"不改 API 形状""不加新依赖"
验证命令	证明完成的标准	"改完跑 pnpm test -- settings 复现并确认通过"

docs/prompting.md 的另一条经验是："运行 pnpm test -- auth 并修复失败的 refresh-token 测试"永远好过一句"修一下 auth"；同样，与其假设智能体知道某条隐式规则，不如直接写出"不要动 migrations"。相关文件上下文要精而不滥——无关上下文过多反而会增加任务难度。

工程类用例：修复、解释、重构与测试

文档列出的工程类任务都围绕"修改代码但保持或改善其行为"展开。下面是逐条展开及对应的会话设计。

根据复现步骤修 bug

把复现步骤原样交给智能体，让它"先复现，再定位，再补丁，最后重跑复现与测试"。例如：

Bug: 点击 Save 显示成功但设置并未持久化。
复现：
1. npm run dev
2. 打开 /settings
3. 切换 Enable alerts
4. 点击 Save
5. 刷新页面，开关被重置

约束：
- 不改变 API 形状。
- 补丁保持最小。
- 如可行请补充回归测试。

先从复现开始，再打补丁，最后重跑复现和测试。

解释不熟悉的代码路径

适合把范围与"证明你懂了"的标准写进提示，例如：

interpreter "定位 auth 中间件，说明它的调用链、校验了什么、在哪里可能被绕过，并列出关键文件路径"

在 TUI 里启动会话后可以直接用 interpreter "find the auth middleware and explain how it works" 这种"首条提示随命令行传入"的写法（见 docs/interactive.md）。

重构模块而不改变行为

行为保持是这类任务的最大风险。设计提示时应给出行为等价判据：现有测试集是什么、重构后需要全量通过哪些用例；必要时用"重构后 diff 中除目标模块外不应有任何逻辑变化"作为硬约束。仓库自身也实践了这一纪律——AGENTS.md 中对重构有明确的模块规模引导（"目标 Rust 模块控制在 500 行内、超 800 行应拆分新模块"），codex-rs/core 因体量膨胀而被明确要求"抵制继续往里加代码"。把这类仓库约定写进提示，智能体就能在重构时主动遵守。

为回归问题添加测试

文档在工程类用例中单列"为回归问题添加测试"。仓库对回归测试的实践非常成熟，可直接作为任务模板：

• 核心代理层修改必须附带集成测试，优先使用 test_codex 在 codex-rs/core/tests 下搭建测试实例（见 AGENTS.md）；
• TUI 等涉及用户可见输出的改动必须附带 insta 快照测试，快照位于 codex-rs/tui 下；
• 测试优先整体对象相等断言，不要逐字段比较（见 AGENTS.md）。

给智能体的提示因此可以是：

为 shell 命令超时处理新增一个回归测试。测试风格遵循本仓库约定：
优先用 integration test，把本 bug 的复现路径走一遍。
完成后运行对应的 just test 命令确认通过。

升级依赖或 API 集成

此类任务典型的约束与验证对是：升级目标版本、受影响调用点清单、兼容性回归命令。仓库中可参考的真实样例是 docs/zh/migrate.md 与 docs/zh/config.md（配置层迁移文档）；Rust 侧依赖升级会牵动 Cargo.lock 与 MODULE.bazel.lock 的同步刷新（AGENTS.md 明确要求改依赖后运行 just bazel-lock-update）。把"升级 xx 依赖，刷新 lockfile，跑受影响 crate 的测试"写成一条提示即可。

保持文档与代码同步

"文档与代码改动同步"高度依赖仓库结构信息，最适合用 @ 把相关文档指给智能体。本仓库的做法可作范例：codex-rs/ 下每个 crate 几乎都带 README；AGENTS.md 要求修改 ConfigToml 后运行 just write-config-schema 同步 codex-rs/core/config.schema.json，应用服务协议改动后运行 just write-app-server-schema 重新生成 schema 夹具。这类"改代码必须同步产物"的规则非常适合沉淀进仓库 AGENTS.md（TUI 内用 /init 生成草案，见 docs/agents_md.md）。

审查与质量类用例：内置 review 管线的正确用法

文档将"审查与质量"单独归为一类，说明这不是边角功能，而是 Open Interpreter 的一等公民。其四条用例全部有现成的落地命令。

审核 Pull Request 差异

交互式会话中直接输入 /review，即可对当前工作区改动做一次只读代码审查；/plan 则先让智能体勘察并提出方案、再动手编辑（docs/interactive.md）。/review 与 /plan 都来自 TUI 斜杠命令体系（docs/slash_commands.md）。

非交互场景使用 interpreter exec review，其参数定义见 codex-rs/exec/src/cli.rs：

interpreter exec review --uncommitted        # 审查已暂存、未暂存与未跟踪改动
interpreter exec review --base main          # 相对 main 基线的合并差异
interpreter exec review --commit abc123      # 审查某次提交引入的改动
interpreter exec review "自定义审查要求"       # 传入自定义指令；用 - 从 stdin 读取

参数之间互斥（--uncommitted 与 --base、--commit、prompt 冲突），选择逻辑在 codex-rs/exec/src/lib.rs 的 build_review_request 中实现。指定 commit 时还可用 --title "提交标题" 让摘要更可读。

从源码结构看，/review 是一条独立的会话任务：codex-rs/core/src/session/handlers.rs 的 review 处理器把 ReviewRequest 解析后派生一个子线程执行；codex-rs/core/src/tasks/review.rs 显示该子会话会刻意收缩权限：禁用 Web 搜索与协作工具、将审批策略强制为 never、并注入独立的 review 系统提示。审查默认使用独立模型（配置项 review_model，见 codex-rs/core/src/config/mod.rs），审查结果会被格式化为结构化的 ReviewOutputEvent 并写回会话历史（codex-rs/core/src/tasks/review.rs）。审查的评判准则沉淀在 codex-rs/prompts/templates/review/rubric.md：只标记离散、可行动、由本次改动引入的问题，P0–P3 优先级分级，并输出 overall_correctness 结论，结论需以严格 JSON 结构返回——这套提示本身就是一个极佳的"审查类提示"范本。

审计安全敏感代码

"审计安全敏感代码"的落地姿势是限制执行边界。审查会话应使用 read-only 沙箱：

interpreter --sandbox read-only "audit the auth flow"          # 一次性覆盖（见 docs/sandbox.md）
interpreter exec review --uncommitted                           # review 本身只读

沙箱与审批是两套独立的安全控制：sandbox_mode 决定技术边界（read-only / workspace-write / danger-full-access），approval_policy 决定何时打断询问（untrusted / on-request / never），详见 docs/sandbox.md。注意即便在可写根目录内，.git/ 等敏感控制目录仍是受保护路径。TUI 中可用 /permissions 随时切换姿态。

对 CI 失败日志进行分流

在非交互模式下把日志管道喂给智能体，是最适合脚本化的场景之一（docs/exec.md）：

# 从 stdin 读任务
cat task.md | interpreter exec -
# 把上下文管道进提示
git diff | interpreter exec "explain this diff and flag risky changes"
# 输出 JSON 事件流，便于后续机器处理
interpreter exec --json "list the files this task would touch"

配合结构化输出，可以让 CI 日志分流的结果满足固定 schema。定义一个 schema.json，要求智能体返回 risk 与 recommended_fix：

interpreter exec --output-schema schema.json \
  "inspect the current diff and return the highest risk"

--output-schema 会强制最终回答匹配 JSON Schema；--output-last-message, -o <file> 可把最终消息落盘，--timeout <seconds> 在长时间运行中发送剩余时间提醒，--verify 在退出前追加一轮完成度校验（均见 docs/exec.md 的命令行 flag 表）。

把不稳定测试报告变成修复计划

文档将其列为独立用例，强调的是"报告 → 计划"的转换，而不是直接改代码。这正好对应 /plan 模式——先勘察再提案；也可以要求 exec 模式"先输出修复计划，待确认后再执行"。仓库中把 flaky test 当一等问题的证据随处可见：AGENTS.md 用专门的篇幅规定快照测试的验收流程（just test -p codex-tui → cargo insta pending-snapshots → 人工复核 → accept），并把 UI 改动缺少快照视为必须补充的测试缺口。

数据与文档类用例：一次性工作区 + 非交互执行

在一次性工作区分析 CSV 或日志导出

"一次性（disposable）"意味着用完即弃、不污染主仓库。建议组合三条 exec 能力（docs/exec.md）：

• --ephemeral：不持久化会话记录；
• --sandbox read-only 或 workspace-write：控制可写范围；
• --json：把进度、工具调用、文件改动等输出为按行分隔的 JSON 事件，供上层程序消费。

cat server.log | interpreter exec --json --ephemeral \
  "classify the 5xx errors by endpoint and suggest the top 3 causes"

分析类会话天然适合 interpreter exec resume 续跑：interpreter exec resume --last "now apply the plan" 续接最近一次非交互会话，interpreter exec resume <SESSION_ID> 指定会话（--all 可跨目录搜索）。

根据源文件起草内部文档

该场景的验证目标往往是"每个被引用的符号真实存在"。把文档目录指给智能体并给出风格约束即可，例如"为 codex-rs/otel crate 起草 README，只描述 src 下真实存在的类型与配置项，完成后核对无虚构路径"。仓库本身就示范了"文档跟随代码"的组织方式：codex-rs/ 各 crate 的 README 与其 src/、tests/ 一一对应，docs/ 与 docs/zh/ 镜像维护中英两版。

把 issue 讨论串转换成实现任务

这是"非代码产出"类任务：智能体阅读 issue/讨论文本，输出拆好的任务清单（含依赖顺序、涉及文件、验收标准）。这类任务建议用 --output-schema 约束产出格式，例如强制返回 [{ "id", "summary", "files", "acceptance" }] 数组，保证下游可以直接对接项目管理工具。

把用例固化为可复用资产：技能与项目指令

以上任何用例，一旦在某个仓库中跑通，都值得沉淀成技能（skill）或项目指令（AGENTS.md），避免每次重新口述约束。

技能就是一个含 SKILL.md 的目录（docs/skills.md）：

cut-release/
├── SKILL.md
├── scripts/
├── references/
└── assets/

SKILL.md 的 description 决定技能何时被选中，应写得足够具体。发布类用例（跑测试 → 更新 changelog → 按 semver 升版本 → 准备提交，先询问再发布）就是技能化的典型对象。技能存放位置：仓库级 .agents/skills/（推荐）、个人级 ~/.agents/skills/ 与内置技能；本地优先级高于个人与内置。

AGENTS.md 则用来存放"跨会话都成立的稳定规则"（docs/agents_md.md）：构建/测试/lint/格式化命令、架构笔记、代码风格与 API 约定、需要小心的文件、发布/迁移/审查期望。TUI 内输入 /init 让智能体勘察仓库并生成草案，然后人工精简到真正长期有效的规则。这些文件既是给未来自己看的文档，也是让后续每次工程/审查用例少写一半约束的杠杆。

结语：把用例套进同一个执行闭环

回顾 docs/use-cases.md 的全部用例（工程 ×6、审查与质量 ×4、数据与文档 ×3），它们其实共享同一个执行闭环：

1. 给出工作区：进入目标仓库（TUI 或 cd 后 exec），用 @//mention 指名相关文件；
2. 写清目标与约束：期望行为 + 不许越界的边界；
3. 圈定沙箱与审批：审查/审计用 read-only，写作用例用 workspace-write，必要时 approval_policy = "on-request" 保持人工闸门；
4. 下达验证命令：明确"跑什么命令、通过什么标准算完成"；
5. 沉淀资产：跑通后用 /init 更新 AGENTS.md、把重复流程做成 skill。

与这些用例配套的完整命令手册见 docs/cli-reference.md，非交互模式细节见 docs/exec.md，交互模式快捷键与斜杠命令见 docs/interactive.md 与 docs/slash_commands.md。按这套方法，Open Interpreter 在修 bug、审 PR、拆 issue 等日常工程任务中都能产出范围可控、结果可验证的工作成果。