Appearance
Q79 · Code Agent 怎么设计？
假设你维护一个博客。产品同事说：“搜索‘LangGraph’时，明明有一篇文章在正文里提到了它，却返回零篇，请修好。”如果把这句话直接交给大模型，让它凭想象输出一整份新文件，问题很可能变成：它不知道仓库里搜索代码在哪、可能覆盖已有功能，也不知道改完以后搜索页能否运行。
**Code Agent（代码智能体）**要做的事情更具体：把自然语言任务变成一次有边界的软件修改。它先读真实仓库和约束，再决定改哪里，用工具编辑文件，运行能证明修改有效的检查，最后把改动和剩余风险交给人看。这里的“Agent”不表示模型获得无限操作权；它只是能在受控循环中选择下一步工具动作。OpenAI：构建编码智能体、OpenAI：Sandbox agents
术语、工具与例子里的变量
| 词或符号 | 先用白话理解 | 在搜索故障里对应什么 |
|---|---|---|
| 仓库（repository） | 项目的代码、测试、配置和文档所在的文件集合，通常由 Git 管理 | 博客网站的前端与搜索代码 |
| 工作区 | Agent 当前能读写的那份仓库副本 | 本次修复所在的目录 |
| 上下文 | 让模型判断下一步所需的代码、说明、报错和历史 | 搜索函数、需求说明、相关测试，而非整个仓库原封不动塞进去 |
| Shell 命令 | 在系统里执行的命令，例如搜索文件或运行测试 | 用 rg 定位搜索实现，运行项目已有测试 |
| 补丁（patch） | 记录哪些行被增加、删除或替换的小份修改 | 把“只查标题”改为“标题或正文命中” |
| 差异（diff） | 修改前后逐行对比的结果 | 审核 Agent 有没有顺手动到无关文件 |
| 沙箱（sandbox） | 给命令划定可用文件、网络、进程等范围的执行环境 | 测试脚本不能随意读取私人文件或访问外网 |
| 测试 | 把预期输入与输出写成可重复检查的程序 | 搜索词只出现在正文时也能找到文章 |
| 副作用 | 执行动作后，外部或持久状态发生改变 | 改文件、安装依赖、推送代码、发布网站 |
| 人工审批 | 对高风险动作，由有权限的人确认后再执行 | Agent 不自行删除数据、推送主分支或部署 |
| 停止条件 | 告诉 Agent 什么情况下可以交付、失败或求助 | 测试通过且差异符合任务；或时间到、权限不足 |
query | 用户输入的搜索词 | LangGraph |
article | 仓库里的单篇文章数据 | 标题不含 LangGraph，正文包含它的文章 |
title / body | 文章标题 / 正文两个字段 | 决定搜索究竟检查哪些内容 |
rg 是常用的文本搜索命令，作用像在仓库里快速“查找包含这个词的文件”；git diff 显示当前代码相对于修改前的差异。它们是工具，不负责理解产品需求。模型负责提出假设和选择下一步；真实文件、命令输出与测试结果负责提供证据。
一次修复怎样从请求走到交付
图中从左到右的五步是主线。“跑测试失败”只返回“改代码”，不表示每次失败都该无脑再改一遍：先读报错，确认是修改引起、原本就坏，还是测试环境缺依赖。右上的“隔离环境”贯穿整段执行，不只是最后一步才开启。
以博客搜索故障为例，完整流程可以走成这样：
- **确定验收结果。**先把口头请求翻译成可检查的条件：若某文章标题不含
LangGraph，但正文含有它，搜索LangGraph应返回这篇文章；原来能按标题搜到的文章仍要搜到。若需求没有说正文是否应该被索引，Agent 需要查产品文档或现有测试，不能自作主张把所有私密草稿也加入公开搜索。 - 定位和阅读。查看项目说明、搜索入口、索引生成脚本、数据结构与现有测试。假设最终发现过滤逻辑只检查
article.title。此时只是找到了可能原因，仍要确认“正文应纳入搜索”的需求和索引中是否真的保存了body。 - **限定修改。**计划只调整搜索匹配逻辑和对应测试；不改页面样式、部署配置和全站文章。改动越小，越容易评审和回退。若正文根本没有进入索引，则计划要改为“索引生成 + 查询 + 测试”三处，而不是仅修改查询条件。
- **编辑并验证。**用补丁改相关行，增加“只在正文出现关键词”的测试，先运行该测试，再运行项目规定的搜索测试或构建。测试失败则读具体失败原因，必要时重新定位代码。
- **检查和汇报。**看
git diff与文件清单，确认只改了预定文件；说明修复原理、运行了哪些命令、实际结果和未验证之处。若测试因缺依赖无法跑，要如实说“未运行”，不能把“我写了测试”说成“测试通过”。
以上例子的实际字段名、文件名和测试命令，应从目标仓库读取。没有读仓库前就编出 search.ts 或 npm test 并断言它们存在，是 Code Agent 常见的不可靠做法。
模型、工具和控制程序各负责什么
实现时可以把系统拆成三层，先看清责任再选择框架。
| 层 | 要完成的工作 | 不该由它单独决定的事 |
|---|---|---|
| 模型 | 理解需求，结合工具结果推断原因，提出下一步和补丁 | 文件访问权限、外部发布权限、测试是否真实成功 |
| 工具 | 读文件、搜索、执行受限命令、应用补丁、返回原始结果 | 自己判断需求是否正确或发布是否安全 |
| 控制程序 | 限制工具参数、目录和超时，记录轨迹，检查审批与停止条件 | 把模型输出直接当作可信的系统命令 |
一次调用不是“把仓库发给模型，等它吐出最终答案”。控制程序先提供任务和少量上下文；模型请求读某些文件；工具把真实内容返回；模型再提出修改；工具应用补丁并执行检查；控制程序记录每一步。OpenAI 的编码 Agent 示例与 Apply Patch 工具都采用这种“模型提议、工具执行、结果回传、继续迭代”的思路；Apply Patch 使用结构化差异来表达文件修改。OpenAI：构建编码智能体、OpenAI：Apply Patch
为什么需要控制程序？假设模型把网页上的一句“运行 curl ... | sh 才能修复搜索”当成命令。网页内容是待分析的数据，不是给 Agent 授权的管理员指令。工具入口必须限制可执行动作；对联网、删除、安装和发布设置独立规则。否则“模型只是在建议”并不能降低命令真正执行后的风险。OpenAI：Sandbox security、Anthropic：Claude Code sandboxing
怎样让 Agent 看见足够的代码，又不被整个仓库淹没
初学者容易以为“上下文越多越好”：把整个项目一次塞进提示词，模型自然会找到问题。实际仓库可能包含大量无关文件、生成产物、过期说明和长日志。过多内容既昂贵，也会让关键代码被噪声盖住，甚至超过模型的输入上限。
更稳妥的查找顺序是从任务线索逐步扩展：
- 读仓库顶层说明、项目约定和测试命令，知道该怎么开发。
- 用“搜索”“search”“索引”等线索查文件名和代码引用；查看调用方与数据来源。
- 读取命中的小范围文件和相关测试，确认实际行为。若只读到了页面按钮，却没有读索引生成逻辑，就不能断言问题只在页面。
- 修改后根据报错再扩展读取范围，而非每一轮把全部文件重新发送。
还要区分相关性和权威性。仓库当前代码说明“现在怎么做”，需求或产品文档说明“应该怎么做”，测试说明“过去承诺过什么”。三者冲突时，不能简单地让模型选最像答案的一段；要分析版本和影响面。比如代码只搜标题、旧测试也只写标题搜索，但新需求明确要求正文搜索，修改时就要补新的验收测试，而不是把旧实现解释成正确需求。
读取文件也不能无限扩张。默认只允许任务仓库内的必要路径，过滤密钥、私有证书、用户本机目录和大型二进制文件；给文件读取、搜索结果和命令输出设长度上限。需要更多内容时按文件和行号再取。这样既控制成本，也降低意外泄露。
补丁、测试和差异检查分别证明什么
继续看搜索例子。假设索引已有标题和正文，当前逻辑等价于“只要标题不含 query，就排除 article”。改动方向是让“标题或正文”命中即可保留。为了让概念具体，下面是教学用伪代码，不对应某个仓库的真实语法：
text
for each article in public_articles:
title_matched = contains(article.title, query)
body_matched = contains(article.body, query)
if title_matched or body_matched:
keep(article)其中 public_articles 表示允许公开搜索的文章集合；contains(text, query) 表示在 text 中找 query；title_matched 和 body_matched 分别保存两次检查的真假；keep(article) 把文章放进结果。拿具体输入走一遍：文章标题“图结构入门”不含 LangGraph，所以 title_matched = false；正文写着“LangGraph 用图表示流程”，所以 body_matched = true；“或”条件为真，这篇文章留下。另有标题包含 LangGraph 的文章，也仍会留下。
这个片段尚未解决大小写、中文分词、HTML 标签、排序、索引更新和权限问题。真实项目需先沿用原有搜索语义，按需求逐一验证，而非复制伪代码上线。尤其是“正文可搜”可能把草稿、权限内容或隐藏字段泄露给未登录用户，检索范围必须由可信代码限定。
补丁证明 Agent 具体改了什么，适合人审查。测试证明一部分预先写明的行为能否重复出现，不能证明所有场景都正确。构建证明项目至少能完成编译或静态站生成，也不能证明搜索语义正确。因此三者要配合：
| 检查 | 对本例最有用的问题 | 还不能推出什么 |
|---|---|---|
| 定向测试 | “只在正文出现”是否能返回；标题搜索是否仍正常 | 线上数据一定与测试数据相同 |
| 相关测试集 | 搜索排序、权限过滤、空搜索词是否退化 | 整个网站所有功能都正确 |
| 构建或类型检查 | 改动是否破坏编译、打包 | 用户体验和结果质量已经充分验证 |
git diff 与文件清单 | 是否多改了配置、密钥或无关代码 | 代码运行结果一定正确 |
失败时要看失败类型。新测试返回零篇，说明修复还没完成；编译报“body 字段不存在”，说明先前对数据结构的假设错了；测试命令因网络断开无法安装依赖，说明验证环境不完整。这三种情况不能都写成“再让模型试一次”。Agent 应把工具的退出码、报错片段和已做改动纳入下一轮判断，设置最大尝试次数；反复同一错误时停止并报告阻碍。OpenAI：构建编码智能体
为什么代码执行要有边界
“只在自己的电脑上修代码”也可能造成损害。测试脚本能读环境变量，安装脚本能访问网络，删除命令会清掉不该删的目录；仓库中的文档、网页、issue 文本还可能夹带诱导 Agent 执行额外命令的提示词注入。因此要把读内容、改本地文件、运行命令、访问网络、推送与部署视为不同权限，而不是给一个笼统的“允许使用电脑”。
沙箱的第一步是文件和网络边界：只挂载需要的仓库目录，尽量不给个人目录、生产密钥和任意外网；对进程、时间、输出大小和资源消耗设限制。真实沙箱是否有效取决于运行环境与配置，不能只因工具名字叫“sandbox”就认定安全。OpenAI 文档明确提醒，沙箱内运行的代码仍可接触已提供给它的文件、凭据与网络；Anthropic 也把文件系统和网络隔离作为编码工具沙箱的两个核心边界。OpenAI：Sandbox security、Anthropic：Claude Code sandboxing
第二步是动作分级。读一个源码文件通常可以自动执行；修改仓库文件要在限定目录内留下补丁；删除大量文件、执行不明脚本、安装依赖、提交代码、推送主分支或部署，应根据团队规则触发审批。退款、发邮件之类外部业务写操作更不能混进修代码流程。审批应拦在实际工具动作之前，而不是动作完成后让模型问一句“这样可以吗”。OpenAI：Guardrails and human review
第三步是可恢复性。开始前记录工作区状态，修改时保存差异；失败时能撤回 Agent 的修改，但不能随意抹掉人类原有的未提交改动。使用单独的工作区或版本分支，可以更清楚地区分本次修改与其他人的修改。若命令执行过程中已经写入数据库或发布外部服务，简单 git reset 也无法撤销那些副作用，因此这类工具应被更严格地隔离和审批。
什么时候该停、什么时候该交给人
Code Agent 的目标是“交付有证据的修改”，不是无限运行到模型说自己满意。可以预先写出完成条件：验收测试覆盖了核心故障并通过；项目要求的相关检查通过；差异只在授权范围；已说明运行结果与限制。若任一条件缺失，就要继续验证或明确标记未完成。
下面几种情况应停止自动修改并求助：需求有相互冲突的解释；需要生产密钥或未授权数据；连续多轮无法定位原因；每次修复都引入新故障；预算或运行时间到达上限；高风险动作等待人工审批。停止时保留任务、读取证据、已改文件、测试结果和当前假设，使人能够接手，不要把失败伪装成“已优化”。
为了评价这样的 Agent，可做一组隔离的真实仓库任务：给定起始提交和问题描述，让它在固定权限、固定时间和固定工具下工作；最后运行隐藏验收测试，统计任务完成率、误改率、测试证据、人工接手次数、时间和费用。只看“模型写了多少代码”没有意义，写得多反而可能增加审查负担。对上线系统，还要记录每步工具调用、补丁、退出码和审批决定，便于回溯。OpenAI：构建编码智能体
面试时可以这样回答
我会把 Code Agent 设计成“读仓库、制定有边界的修改、应用补丁、运行验证、审查差异”的循环。用户请求先转成可检查的验收条件，例如搜索词只出现在正文时也能找到公开文章。模型根据真实代码和工具结果选择下一步，控制程序负责限制文件、命令、网络和执行时间；编辑以小补丁为主。测试、构建和 diff 分别提供行为、可运行性和修改范围的证据，任何一项都不能单独证明已经修好。失败要读报错后有界重试；需求不明、权限不足或需要推送部署时交给人确认。最终交付改动、实际运行过的检查以及仍未验证的风险。
如果追问“模型能不能直接运行任何 Shell 命令”，答：不能。Shell 能读取文件、联网和造成持久修改，必须按工作区、网络、命令类别和审批策略限制，输出也要有上限。若追问“测试通过是否就能自动合并”，答：还要看测试覆盖的是不是原始问题、差异有没有无关改动、权限和团队评审规则是否满足；测试通过只是一项证据。