Open Interpreter 提示词工程实战：为编码 Agent 写出可安全执行的高质量 Prompt

本文基于仓库 docs/prompting.md 整理展开。Open Interpreter 是一个面向 Kimi K3、GLM 5.3 等开放模型的编码 Agent，其交互式 TUI 与 interpreter exec 非交互模式都以"自然语言指令"驱动。撰写一段好 Prompt 的关键在于：给出可复现的观察、明确的期望行为、不可逾越的约束与可执行的验证命令。读完本文，你将掌握 Bug 修复类 Prompt 的标准模板、如何用 @ 与 -i 携带文件/图片上下文，以及如何在提词时就预设沙箱与审批边界，从而让 Agent 一次把任务做对、做安全。

为什么"具体"是好 Prompt 的第一要素

Open Interpreter 官方文档对 Prompt 质量给出的判断标准非常朴素：

Good Open Interpreter prompts are concrete. Include the observed problem, the expected behavior, constraints, and verification commands.

即一条合格 Prompt 至少应包含四要素：

1. Observed problem（观察到的现象）：描述你实际看到的结果，而不是你的猜测；
2. Expected behavior（期望行为）：明确"修好之后应该是什么样"；
3. Constraints（约束）：告诉 Agent 哪些不许改、哪些必须保持；
4. Verification commands（验证命令）：给出可以立即执行的验收手段，让 Agent 修复后自行自证。

这与仓库 codex-rs/core 下的系统提示词所强调的纪律一致——Agent 被要求直接执行而非空谈，且 "Direct system/developer/user instructions (as part of a prompt) take precedence over AGENTS.md instructions"（见 gpt_5_2_prompt.md）。也就是说：你写进 Prompt 的指令优先级最高，会覆盖项目级 AGENTS.md 的通用指引，因此把话说清楚直接决定了结果边界。

Bug Fix 标准模板：先复现，再修补，后回归

文档给出了一个可直接套用的 Bug 修复模板，其核心是强制 Agent 遵循"复现 → 打补丁 → 重跑复现与测试"的闭环：

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 提示成功但设置没有持久化"。注意它描述的是现象而非原因，避免把 Agent 的排查思路带偏。
• Repro: 编号列出可复现步骤。可复现的步骤是 Agent 验证修复的"度量尺"——没有它，Agent 无法判断自己是否真的修好了。
• Constraints: 声明不可触碰的边界。示例中的"不要改变 API 形状""补丁尽量小""如可行则补回归测试"都直接限制了搜索空间，避免 Agent 顺手重构、改坏接口。
• 结束语 要求执行顺序："先复现，再打补丁，然后重跑复现步骤和测试"。它把"验证"内建进任务本身。

在 Open Interpreter 中执行此类任务，可以在项目目录启动 TUI 后直接粘贴，也可以用 interpreter exec 一次性交付（见 exec.md）：

# 非交互方式执行同一类 Bug 修复请求
interpreter exec "Run the test in tests/auth.spec.ts, reproduce the failing refresh-token test, fix it, then rerun."

如果你希望最终答案结构可控，还可以配合 exec 的 --output-schema <file> 让结论必须满足某个 JSON Schema、用 --verify 在执行末尾追加一轮完整性校验、用 --timeout <seconds> 注入剩余时间提醒（见 exec.md）。

明确优于含糊：别让 Agent 猜你的意图

文档给出了一组极具代表性的对比：

• 应当说 "run pnpm test -- auth and fix the failing refresh-token test"（跑 pnpm test -- auth，然后修复那个失败的 refresh-token 测试），而不是 "fix auth"；
• 应当直接声明 "do not touch migrations"（不要动迁移文件），而不是默认 Agent 自己"应该知道"这条约束。

"fix auth" 之所以是坏 Prompt，是因为它把三个问题留给了 Agent 猜：测试命令是什么？失败的判定标准是什么？允许改动哪些范围？而把命令与期望写进 Prompt 后，Agent 不再需要假设，也就不会把无关模块卷入改动。

同理，这类"显式约束"在仓库的工具链中被反复强化：根目录 AGENTS.md 本身就是一份写给 Agent 看的约束清单（例如 "Do not add general product or user-facing documentation to the docs/ folder"、"Never add or modify any code related to CODEX_SANDBOX_*"），它证明项目级指令注入是该 Agent 的原生工作方式。在 TUI 中可用 /init 为当前项目生成一份 AGENTS.md（见 slash_commands.md），把团队约定沉淀成可被每个会话读取的常驻约束。

用文件与图片喂上下文：@、/mention 与 -i

再精确的措辞也弥补不了上下文的缺失。文档建议：在 TUI 中用 @ 提及文件，或在命令行挂载相关文件/图片。

TUI 内：@ 模糊搜索文件

在 TUI 底部输入框中输入 @，会弹出文件模糊搜索，选中即把文件作为上下文注入对话；等效的方式是 /mention 命令。相关的输入框操作还包括：Enter 发送、Shift+Enter 换行、Ctrl+G 用 $VISUAL/$EDITOR 编辑当前 Prompt、Ctrl+R 搜索历史（完整对照表见 interactive.md）。

命令行：把首条消息带上附件

在 CLI 直接指定首条消息附带图片（见 cli-reference.md 中 --image, -i <path[,path...]> 与 interactive.md）：

# 单张图片：让它诊断 UI 问题
interpreter -i screenshot.png "explain what is wrong in this UI"

# 多张图片：对比前后状态
interpreter -i before.png,after.png "compare these states"

exec 非交互模式同样支持图片附件（见 exec.md）：

interpreter exec -i screenshot.png "describe the UI problem"

管道输入：把动态上下文交给 Prompt

除了文件，还可以把命令输出直接变成上下文。这特别适合"让 Agent 基于当前改动工作"的场景：

git diff | interpreter exec "explain this diff and flag risky changes"
cat task.md | interpreter exec -

上下文不是越多越好

文档特别强调一个反直觉原则：Keep context focused; too much irrelevant context makes the task harder.（上下文要保持聚焦，无关上下文过多反而会让任务更难。）这一设计与仓库对"模型可见上下文"的硬性约束一致：AGENTS.md 要求所有注入上下文的条目必须有界、设硬上限、单项不超过 10K token（见 AGENTS.md "Model visible context" 一节）。会话过长时，可用 /compact 让 Agent 把旧上下文压缩成摘要再继续（见 interactive.md 的 Session Controls）。

所以正确姿势是：只挂载与当前改动直接相关的文件（如出错的模块、对应测试），而不是把整个仓库丢进去。

在 Prompt 中预设行为边界：沙箱、审批与执行策略

"让 Agent 行动"与"让 Agent 安全行动"之间的桥梁是权限系统。撰写 Prompt 时把权限预期一并声明，能显著减少往返确认与误操作。

Open Interpreter 的默认姿态面向可信仓库的日常开发：工作区内允许访问，工作区之外的活动先征求同意。可用 /permissions 切换当前策略（见 interactive.md）。内置的审批姿态与沙箱模式可参见 permissions.md 与 sandbox.md，CLI 侧对应 --sandbox（read-only / workspace-write / danger-full-access）与 --ask-for-approval（untrusted / on-request / never）两个参数。

举例而言，若修复任务只允许写工作区，可这样启动：

interpreter --sandbox workspace-write \
  "Fix the refresh-token test in tests/auth.spec.ts without touching migrations."

需要说明的是，--yolo（绕过审批与沙箱）被 cli-reference.md 明确标注为 Dangerous，不应出现在常规任务的 Prompt 方案里。除此之外，还有更细粒度的 execpolicy 机制把"安全地执行"与"无需逐次询问"统一起来——safe 模式下的命令可以在不打断流程的前提下自动放行（见 execpolicy.md），非常适合把一段"复现步骤 + 验证命令"交给 Agent 连续执行。

用好任务前的"检查式"指令：/plan 与 /review

有些任务不该直接开改。Open Interpreter 提供了两个与 Prompt 强相关的内置模式（见 interactive.md 与 slash_commands.md）：

• /plan：先让 Agent 检查并给出方案，再动手编辑——适合影响面大、需要先对齐思路的任务；
• /review：对当前改动做一轮代码审查。Review 模式是只读的，会先报告 bug、回归、缺失测试与风险行为，再做总结。

在非交互场景，exec 也提供了类似能力：

interpreter exec review --uncommitted
interpreter exec "summarize the changes in the last commit"

这让"审查"与"修复"可以拆成两段独立的 Prompt 闭环：先用 /plan 收敛方案，再按 Bug Fix 模板执行修复，最后用 /review 兜底验收。

从单条 Prompt 到项目惯例：把好指令沉淀成资产

单条高质量 Prompt 解决当下问题，而把 Prompt 里反复出现的约束沉淀下来，能持续降低后续每个会话的沟通成本：

1. 用 /init 在当前项目生成 AGENTS.md，把"禁止改动迁移文件""测试必须通过"这类约束写进去（见 slash_commands.md）。它会成为后续每个会话的常驻上下文，且低于你单条 Prompt 的即时指令优先级。
2. 用 /model 选择 provider、模型与推理力度（如 interpreter -m gpt-5.1-codex "review this module"），不同模型对超长指令与结构化模板的耐受度不同（相关能力说明见 cli-reference.md）。
3. 把可复现的 Bug 模板与验证命令沉淀为团队文档或脚本，git diff | interpreter exec "explain this diff and flag risky changes" 这类管道写法甚至可以做成 git 别名，让"上下文输入"这件事本身标准化。

小结

Open Interpreter 的提示词哲学可以浓缩为一句话：把你亲眼看到的现象、你期望的结果、你不许越过的边界、以及可以一键验证的命令，全部写进同一条 Prompt。 模板（Bug 现象 + 复现步骤 + 约束 + 验证命令）、文件/图片上下文（@、/mention、-i、管道输入）、行为边界（--sandbox、--ask-for-approval、/permissions）与检查型指令（/plan、/review）四者结合，就能把"模糊的自然语言"改造成 Agent 可理解、可复现、可安全执行的工程指令。