Open Interpreter 提示工程指南：编写具体、可验证的高质量代理提示

提示（Prompt）的质量直接决定了 Open Interpreter 这一自然语言编程代理的行为边界与执行效果。本文基于仓库官方中文文档《提示》展开，结合 codex-rs/cli 与 codex-rs/tui 的源码实现，系统讲解一套可复用的缺陷修复提示模板、如何把模糊请求改写为精确指令，以及如何在 TUI 与命令行中通过 @ 与 -i 把文件和图片纳入上下文。读完本文，你将掌握"问题描述 + 复现步骤 + 约束条件 + 验证命令"的结构化提问方法，从而让代理在更少的来回中安全、准确地完成任务。

好的提示从"具体"开始

官方文档开宗明义地指出：好的 Open Interpreter 提示是具体的（concrete）。一个合格的提示应当包含四类信息：

1. 观察到的问题（the observed problem）：当前实际发生了什么，而非你的猜测或抱怨；
2. 期望的行为（the expected behavior）：修复或改动后应当表现为什么样；
3. 约束条件（constraints）：明确告诉代理哪些边界不能跨越；
4. 验证命令（verification commands）：用于确认任务是否真正完成的检查手段。

这种结构的价值在于把代理从"猜你想要什么"中解放出来。仓库中的提示文档（见英文原文 docs/prompting.md 与中文版 docs/zh/prompting.md）本身就是项目作者对交互经验的沉淀——Open Interpreter 会被同时用于修复 bug、重构代码、解释存量系统等任务，提示越是精确，代理越是能在更少的执行轮次里给出可靠结果。

缺陷修复模板：一份可直接复制的起点

官方文档提供了一份完整的缺陷修复提示模板，是实战中最值得直接套用的骨架：

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.

逐段拆解这份模板，就能明白它为什么有效：

• Bug: 行用一句话陈述故障现象——"点击 Save 提示成功，但设置没有被持久化"。注意这里只描述客观事实，不预判根因，避免诱导代理朝着错误方向排查。
• Repro: 步骤给出从零复现的最小操作序列。它把"前端保存逻辑、设置项状态、后端持久化"三层可能出错的链路收窄到确定路径，同时为最后一步的验证提供现成的对照脚本。
• Constraints: 部分显式声明红线："不要改动 API 形状""补丁保持最小""如可行则补充回归测试"。这些都是无法从代码里自动推断出来的工程约束，必须由人在提示中写清楚。
• 末尾的执行顺序指令（先复现，再打补丁，最后重跑复现步骤和测试）规定了代理的工作流，避免它跳过复现直接改代码、改完不验证就收工。

优于模糊请求：把意图说破，而非留给代理去猜

官方文档给出了两组正反对照，是最容易被忽略却最能提升成功率的技巧：

与其只写"修复身份验证"，不如写"运行 pnpm test -- auth 并修复失败的 refresh-token 测试"。与其假设代理知道约束，不如明确写"不要修改数据库迁移"。

对照原文（英文版见 docs/prompting.md），可以提炼出两条原则：

1. 给出入口命令而非目标口号。"修复 auth"是目标，但代理不知道你的测试入口、不知道失败的具体用例、不知道你希望从哪一层入手；而"运行 pnpm test -- auth 并修复失败的 refresh-token 测试"同时交付了入口（命令）、定位（测试套件名）与任务（针对该失败用例修复），代理可以直接执行。
2. 显式声明隐含约束。诸如"不要修改数据库迁移"这类约束通常写在团队的潜意识里，而不是代码里。代理既没有你的背景知识，也没有读心术，凡是越界成本高的约束都应该写进提示。同理，在 Open Interpreter 中为这类结构性保护还可以配合沙箱与权限策略，把"能做什么"从系统层面兜底——参见 docs/zh/sandbox.md 与 docs/zh/permissions.md。

从工程角度可以这样理解：一次对话中代理的上下文窗口是有限的，模糊提示会迫使代理消耗大量往返去澄清需求、试探边界，而结构化提示把这些成本前置到你写提示的那一分钟里，换来的是更少轮次、更小出错面的执行。

使用文件：@ 提及与命令行附加上下文

仅靠文字描述代码，代理仍然需要自己去定位文件。文档给出的第三种做法是把文件本身交给代理：

• 在 TUI（终端 UI）中输入 @ 触发模糊搜索，把目标文件加入上下文；
• 在命令行中直接附加相关文件或图片作为首个提示的一部分。

同时文档强调：保持上下文聚焦——过多无关的上下文反而会让任务变得更难。这提示了上下文窗口既是资源也是噪声源：塞入与任务无关的代码会让代理在相关性判断上失焦，甚至出现幻觉式引用。

在 TUI 中输入框的操作支撑

@ 与 /mention 是 Composer（TUI 底部的提示输入框）的内置能力。根据 docs/zh/interactive.md 中的操作对照表：

操作	键或命令
提及文件	@ 或 /mention
发送消息	Enter
添加换行	Shift+Enter

从源码看，/mention 作为斜杠命令在 Composer 的输入分发中被单独处理，命令分发路径见 codex-rs/tui/src/bottom_pane/chat_composer.rs（其中对 /mention 执行了 dispatch 校验），而命令行选项列表中同时存在"提及文件"对应的命令条目快照（见 codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__command_popup__tests__command_popup_default_items.snap），佐证了 @ 与 /mention 是同一套文件提及入口的两种触发方式。

命令行附加图片：-i / --image

在非交互调用中，图片可以伴随首个提示一并提交。参考 docs/zh/interactive.md 的示例：

interpreter -i screenshot.png "explain what is wrong in this UI"
interpreter -i before.png,after.png "compare these states"

其底层 CLI 参数定义为"可选的、附加到用户提示的图片"，支持逗号分隔一次传入多张图片，对应源码位于 codex-rs/cli/src/main.rs 的 -i/--image 参数声明（value_delimiter = ','，num_args = 1..）。这意味着"界面截图 + 口头描述"这种组合非常适合处理 UI 类缺陷：截图给出客观现状，文字补充期望行为与复现路径，二者互补正与本文的提示四要素相呼应。

使用图片的场景建议：UI 渲染异常、排版错误、图表结果核对等"视觉即证据"的任务。纯代码逻辑问题则优先直接 @ 代码文件，避免引入不必要的视觉 token 开销。

把它们串起来：一份高质量的 Open Interpreter 提示

综合官方文档的模板与本文的扩充，一个完整的高质量提示应当像这样组织：

Bug: 导出 CSV 时中文字段出现乱码。
Repro:
1. interpreter 启动后执行 python export.py --out /tmp/report.csv
2. 打开 /tmp/report.csv
3. 观察 "名称" 列显示为乱码

Constraints:
- 不改动数据源 schema。
- 保持补丁最小。
- 修复后补充对应编码的回归测试。

先复现，再修复，最后重跑复现步骤与测试。相关文件：@export.py

对照检查清单：

• ✅ 描述了观察到的客观问题（乱码现象）；
• ✅ 给出可执行的复现命令与预期差异；
• ✅ 声明了约束（schema 不变、补丁最小、补测试）；
• ✅ 明确验证方式（重跑复现步骤与测试）；
• ✅ 通过 @ 把相关文件交给代理，保持上下文聚焦；
• ✅ 用一句工作流指令约束代理的执行顺序。

小结

Open Interpreter 的能力边界，很大程度上取决于你输入提示的质量。核心方法论只有一句话：把"问题—期望—约束—验证"这四件事讲具体，把需要看的文件和图片真正交到代理手里，把不该碰的东西提前声明成红线。这套方法本身与模型无关，无论你在 CLI 中使用何种后端模型（模型与提供商的选择方式参见 docs/zh/interactive.md 及 docs/zh/models.md），结构化的提示都能带来更稳、更快、更可预测的执行结果。