AI Agent / 系统课时
添加文件与图像上下文
添加文件与图像上下文
当问题只写“这里报错了”或“页面和设计稿不一样”时,Codex 必须先猜代码位置、失败现象和视觉差异。本篇把代码路径、日志片段、错误信息和截图组合成最小充分上下文,让 Codex 知道该读什么、比较什么,以及最终用什么结果验收。
学习目标
- 能按代码、运行证据和视觉证据选择最合适的上下文形式
- 能用明确文件路径和
--image把本地代码、日志与截图关联到同一个任务 - 能控制上下文规模,避免整仓日志、无关截图和敏感信息降低定位质量
先区分上下文的职责
代码文件回答“系统现在是怎么实现的”,日志和错误信息回答“运行时实际发生了什么”,截图或设计图回答“用户实际看到什么”。三者不是越多越好,而是要围绕同一个问题形成证据链。
| 上下文 | 最适合表达 | 提供方式 | 常见误区 |
|---|---|---|---|
| 代码 | 实现、调用关系、配置 | 在提示中写精确仓库路径和符号名 | 只说“看一下相关代码” |
| 日志/错误 | 时间顺序、异常、请求结果 | 提供最相关片段或保存为工作区文本文件 | 整份生产日志直接塞入 |
| 截图 | UI 状态、视觉错位、错误弹窗 | 通过 Codex 图像输入附加 | 只给图,不说明要观察什么 |
| 设计图 | 目标布局、间距、层级 | 作为视觉参考并写清验收点 | 把参考图当成像素级绝对规范 |

引用代码和日志时给出定位锚点
Codex 在本地工作区中可以通过工具读取可访问的仓库文件,所以与其复制几百行源码,更好的做法通常是直接给出路径、关键符号和问题位置。例如说明“检查 src/checkout/submit.ts 的 submitOrder,并结合 context/payment-timeout.txt 中的超时片段定位重试条件”。这样既保留原始文件结构,也减少手工复制时遗漏上下文。
日志应先做最小化处理:保留异常前后的关键行、请求标识和必要时间顺序,删除访问令牌、Cookie、个人信息和无关批量输出。遇到重复报错时,只保留能证明模式的少量样本,再在任务里说明“这是重复现象”,比粘贴数万行相同错误更有效。
下面的命令把现有日志中与超时相关的行连同前后各 3 行提取到独立上下文文件,便于后续让 Codex读取。
mkdir -p context
grep -n -C 3 -E 'TimeoutError|request_id=' logs/app.log > context/payment-timeout.txt
wc -l context/payment-timeout.txt预期输出:
<VALUE> context/payment-timeout.txt<VALUE> 是筛选后的实际行数,会随日志内容不同而变化。重点不是固定行数,而是得到一份比原始日志更小、仍保留异常上下文的证据文件。
把截图与任务目标一起发送
Codex CLI 支持用 -i 或 --image 把一个或多个本地图像附加到初始提示;当前 CLI 参数定义将其作为“附加到初始提示的可选图像”。:contentReference[oaicite:3]{index=3} 图像适合错误截图、布局问题、架构图和设计参考,但路径本身不能替代观察要求。
codex --image ./debug/checkout-error.png "结合 src/checkout/submit.ts 与这张截图,定位提交失败原因;先说明截图中可见的错误状态,再检查代码路径,最后给出最小修改和验证步骤。"预期结果:
Codex 会把 checkout-error.png 作为视觉上下文,并结合指定代码文件回答;具体措辞和修改建议会随仓库内容而不同。同一张图最好只承担一个明确角色,例如“失败现场”或“目标设计”。如果同时有当前页面与设计稿,应在提示里明确哪张是现状、哪张是目标,并列出要比较的维度,如组件缺失、层级、间距、断点行为,而不是只说“做得一样”。
组织一个最小可用上下文包
在真正提交任务前,可以把上下文压成五个槽位:目标、代码位置、运行证据、视觉证据、验收标准。下面是一个可直接改写的提示模板,它不是 Shell 命令,而是给 Codex 的任务说明。
目标:修复结账页提交后停留在 loading 状态的问题。
代码:检查 src/checkout/submit.ts 中的 submitOrder。
运行证据:读取 context/payment-timeout.txt,只关注第一次超时及其前后调用。
视觉证据:已通过 --image 附加 debug/checkout-error.png,它表示失败现场。
约束:不要改变公开 API,也不要引入新的生产依赖。
验收:修复后运行现有 checkout 测试,并说明通过了哪些检查。这种写法把“材料”和“任务”绑定在一起:Codex 知道哪些文件是事实来源、图像代表什么、哪些修改不能做,以及完成后如何证明结果。对调试任务而言,这通常比继续追加背景叙述更有价值。
控制上下文而不是堆上下文
长对话、工具输出和图像都会消耗上下文空间,Codex 的代理循环会随着会话继续把历史消息和工具结果带入后续轮次,并在需要时做上下文压缩。:contentReference[oaicite:4]{index=4} 因此,新的证据如果已经替代旧日志或旧截图,应直接说明“以这份为准”,不要让互相冲突的版本长期并存。
提交前只问三个问题:这份材料是否直接影响判断、Codex 是否知道它的角色、材料里是否含不该暴露的秘密。满足这三点后再发送,通常能得到比“把所有可能相关内容都塞进去”更稳定、更容易验证的结果。