企业官网建设流程全解析

1. 从“补全一行”到“接管一程”：我为什么盯上了开源编码代理

第一次看到“开源 AI 编码代理”这个说法时，我脑子里冒出来的其实是几年前那批代码补全插件——你敲半个函数名，它给你补全剩下半个，顶多再猜一下你下一行想写什么。那种东西用起来像什么？像输入法联想，有用，但也就那样，你始终是那个握着方向盘的人，它只是帮你少敲几个字。

但“代理”这个词不一样。代理意味着它不只是等你开口，而是能自己规划、自己动手、自己检查、自己修正。你给它一个目标，比如“把这个模块的单元测试补齐并跑通”，它会自己去读代码、找测试框架、写用例、执行、看报错、改代码、再跑，直到通过或者卡住为止。这中间你甚至可以离开工位去倒杯水。这个体验上的差别，不是“快一点”和“慢一点”的差别，而是“工具”和“助手”的差别。

我之所以花时间深度折腾 OpenCode 这类开源编码代理，核心原因有三个。第一，闭源方案虽然体验顺滑，但你的代码、你的项目结构、你的私有依赖，全都要经过别人的服务器，这在很多团队里是过不了合规线的。第二，闭源方案的“黑盒”特性让你没法针对自己的技术栈做深度定制，比如你想让它默认遵循你们团队的代码规范、默认用某个内部测试命令，基本没戏。第三，也是最重要的一点，开源代理的架构是透明的，你能看清楚它每一步在干什么，出了问题能定位，能改，能扩展。这种掌控感，是任何闭源产品都给不了的。

这篇文章适合谁看？如果你是会写代码、但对“AI 代理”这个概念还停留在“自动补全”认知阶段的开发者，那这篇就是写给你的。如果你已经在用某些闭源编码助手，但想搞清楚它内部大概是怎么运转的、为什么有时候聪明有时候犯傻，这篇也能帮你建立底层认知。如果你是想自己搭一套私有化编码代理的团队技术负责人，那这篇里的架构拆解和实操细节，应该能帮你少踩不少坑。

我下面会从整体设计思路讲起，然后拆核心模块，再给一套可复现的实操流程，最后把我踩过的坑和排查经验整理出来。全程尽量说人话，复杂的机制用生活化的类比解释，能直接抄的配置和命令我都会给出来。

2. 整体设计思路拆解：一个编码代理到底由哪些部件组成

2.1 代理和普通代码助手的本质区别在哪

要理解 OpenCode 这类开源编码代理的设计，得先搞清楚它和普通代码助手的本质区别。普通代码助手的工作模式是“请求-响应”：你给一段上下文，它返回一段补全或建议，然后它就没事了，等你下一次请求。整个过程是无状态的、单轮的、被动的。

编码代理的工作模式是“目标-规划-执行-观察-修正”的循环。你给的是一个目标，不是一个具体的补全请求。代理需要自己把目标拆解成若干步骤，每一步执行完要观察结果，根据结果决定下一步是继续、回退还是换方案。这个过程是有状态的、多轮的、主动的。

打个比方。普通代码助手像餐厅里的传菜员，你说“给我来份宫保鸡丁”，他把菜端给你，任务结束。编码代理像餐厅里的厨师长，你说“今天中午给二十个人做顿饭，预算两百块，有人不吃辣”，他得自己去想菜单、去买菜、去安排灶台、去尝味道、去调整，最后把一桌菜端出来。这个过程中他可能发现预算不够，可能发现某个食材不新鲜，这些都要他自己处理。

这个本质区别决定了架构上的差异。普通助手只需要一个模型加一个上下文窗口就够了。编码代理需要一整套运行时环境：任务规划器、工具调用层、文件系统访问、命令执行沙箱、结果解析器、状态管理器、错误恢复机制。这些东西缺一个，代理的能力就会大打折扣。

2.2 为什么“开源”对这个品类特别重要

开源对编码代理这个品类的重要性，比其他很多 AI 应用都要高。原因在于编码代理要接触的东西太敏感了：你的完整代码库、你的环境变量、你的数据库连接串、你的内部 API 密钥、你的部署脚本。这些东西一旦泄露，后果不是“推荐不准”这种级别，而是实打实的安全事故。

闭源方案要解决这个问题，通常只能靠“承诺不记录”“承诺不训练”这类信任机制。但信任机制的问题是，你没法验证。你不知道它到底有没有把你的代码传出去，不知道它的日志保留策略到底是什么，不知道它的模型有没有在你的私有代码上做过微调。

开源方案把这个问题从“信任问题”变成了“技术问题”。你可以自己审计代码，可以自己部署在内网，可以自己控制数据流向。你可以看到它每一次工具调用到底传了什么参数，可以看到它把哪些文件内容放进了上下文，可以看到它有没有在你不注意的时候把敏感信息发到外部。这种透明度，对于任何对代码安全有基本要求的团队来说，都是刚需。

而且开源还带来一个额外好处：可定制。每个团队的技术栈、代码规范、测试流程都不一样。闭源方案你只能用它给你的那套，开源方案你可以改。你可以让它默认用你们内部的 lint 命令，可以让它遵循你们的 commit message 规范，可以把它接入你们自己的代码审查系统。这种灵活性，在真实工程场景里价值极高。

2.3 核心架构的四个层次

OpenCode 这类开源编码代理的架构，我把它拆成四个层次来看，这样理解起来比较清晰。

最底层是模型层。这是代理的“大脑”，负责理解目标、规划步骤、生成代码、分析报错。模型层可以是本地部署的开源模型，也可以是调用外部 API 的闭源模型，架构上通常做成可插拔的，方便你根据场景切换。本地模型的好处是数据不出内网，坏处是能力通常弱一些；外部 API 的好处是能力强，坏处是数据要出去。这个取舍后面会细讲。

往上一层是工具层。这是代理的“手脚”，包括文件读写、命令执行、代码搜索、网络请求等能力。代理本身不会直接操作你的文件系统，它通过工具层来间接操作。工具层的关键设计是“沙箱化”和“可审计”：每个工具调用都要有明确的权限边界，都要留下日志，方便你追溯。

再往上是编排层。这是代理的“神经系统”，负责把模型层的输出翻译成工具层的调用，把工具层的返回结果整理成模型层能理解的格式，管理整个任务的状态和上下文。编排层是代理最核心也最复杂的部分，它决定了代理能不能处理长任务、能不能从错误中恢复、能不能在多个步骤之间保持一致性。

最上面是交互层。这是代理的“脸面”，包括命令行界面、编辑器插件、Web 界面等。交互层决定了你用起来顺不顺手，但相对来说技术含量最低，也最容易替换。

这四个层次的分工要清晰，耦合要低。我见过一些实现把编排逻辑和工具调用混在一起，结果就是改一个工具要动半个代码库，加一个新模型要重写一遍流程。好的架构应该是：换模型不影响工具，加工具不影响编排，换界面不影响核心逻辑。

2.4 任务规划的策略选择：一次性规划还是边做边看

任务规划是编码代理最核心的能力之一，也是不同实现之间差异最大的地方。主流策略有两种：一次性规划和边做边看。

一次性规划的思路是，代理先通读任务和相关代码，然后生成一个完整的步骤列表，之后按部就班执行。这种策略的优点是全局观强，不容易在局部绕圈子；缺点是如果第一步的假设就错了，后面全错，而且它不会在执行过程中根据新信息调整计划。

边做边看的思路是，代理只规划下一步，执行完看结果，再决定下一步。这种策略的优点是灵活，能根据实际情况调整；缺点是容易“短视”，可能在一个小问题上反复折腾，忘了大目标。

OpenCode 这类成熟实现通常采用混合策略：先做一次粗粒度的全局规划，确定大方向和关键里程碑，然后在每个里程碑内部采用边做边看的方式。这样既有全局观，又有灵活性。这个设计选择背后的逻辑是：编码任务的不确定性主要在中观和微观层面，宏观层面的目标通常是清晰的。所以宏观上一次性规划够用，中微观上需要灵活调整。

提示：如果你自己实现或定制代理，任务规划的粒度控制是个关键调参点。粒度太粗，代理容易跑偏；粒度太细，代理容易陷入细节。我的经验是，把规划粒度控制在“一个步骤对应一个可验证的结果”这个级别比较合适。

3. 核心模块深度解析：模型、工具、编排、记忆

3.1 模型层：本地模型和外部 API 怎么选

模型层的选型是搭建编码代理时第一个要做的决策，也是最影响最终体验的决策。我把常见的选项和各自的取舍整理成下面这张表，方便你对照自己的场景做判断。

本地部署开源模型的关键参数是模型规模和量化等级。模型规模决定了能力上限，量化等级决定了显存占用和推理速度。我的经验是，对于编码任务，模型规模低于某个阈值之后，能力下降会非常明显，具体阈值取决于模型架构，但一般来说，参数量太小的模型在复杂任务上基本不可用。量化方面，适度的量化对编码任务的影响相对可控，但过度量化会导致模型在细节上频繁出错，比如变量名拼错、括号不匹配这种低级问题。

外部 API 的选型相对简单，主要看能力和成本。但有一个容易被忽略的点：不同 API 对“工具调用”的支持程度不一样。编码代理高度依赖工具调用能力，如果 API 对工具调用的支持不完善，代理的编排层就要做很多额外工作来适配。选型时一定要确认 API 的工具调用接口是否稳定、是否支持并行调用、是否有调用次数限制。

混合方案是我个人最推荐的。具体做法是：把任务按敏感度分级，涉及核心业务逻辑、密钥、内部接口的任务走本地模型，通用的、公开的、不敏感的编码任务走外部 API。这样既保证了安全底线，又能在大多数场景下享受最强能力。实现上，编排层需要支持根据任务标签动态路由到不同模型，这个后面在实操部分会讲怎么配。

3.2 工具层：文件操作、命令执行、代码搜索的设计要点

工具层是代理和真实世界交互的接口，设计好坏直接决定了代理的能力边界和安全性。我重点讲三个最核心的工具类别。

文件操作工具包括读文件、写文件、列目录、搜索文件内容等。设计要点有三个。第一是路径安全，代理只能访问项目根目录下的文件，不能通过相对路径跳出项目目录，这个必须在工具层强制校验，不能靠模型自觉。第二是写入原子性，代理写文件时应该先写临时文件再原子替换，避免写到一半失败导致文件损坏。第三是变更追踪，每次文件写入都要记录 diff，方便你事后审查代理到底改了什么。

命令执行工具是最强大也最危险的工具。代理通过它来跑测试、跑构建、跑 lint。设计要点同样有三个。第一是命令白名单，不是所有命令都允许执行，比如删除文件、修改系统配置这类命令应该默认禁止或需要人工确认。第二是超时控制，任何命令都要有超时限制，避免代理跑一个死循环命令把机器拖垮。第三是输出截断，命令输出可能非常长，要截断到合理长度再喂给模型，否则上下文会被撑爆。

代码搜索工具是代理理解大型代码库的关键。当项目有几千个文件时，代理不可能把所有文件都读进上下文。它需要能根据关键词、符号名、文件类型等条件快速定位到相关代码。这个工具的实现通常基于倒排索引或向量检索，设计要点是召回率和精确率的平衡。召回率太低，代理找不到需要的代码；精确率太低，代理会被无关代码干扰。

注意：工具层的权限设计一定要遵循“最小必要”原则。代理需要读文件就给读权限，需要写文件才给写权限，需要执行命令才给执行权限。不要图省事一次性把所有权限都打开，这是很多安全事故的根源。

3.3 编排层：状态机、上下文管理、错误恢复

编排层是代理的“大脑皮层”，负责协调模型和工具之间的所有交互。这部分最复杂，我拆成三个子问题来讲。

状态机设计决定了代理如何管理任务进度。一个典型的编码代理状态机至少包含这些状态：空闲、规划中、执行中、等待工具返回、分析结果、修正计划、完成、失败。状态之间的转换条件要明确，比如“执行中”收到工具返回后进入“分析结果”，“分析结果”发现报错则进入“修正计划”，“修正计划”生成新步骤后回到“执行中”。状态机设计得清晰，代理的行为就可预测、可调试；设计得混乱，代理就会表现得“神经质”，时而聪明时而犯傻。

上下文管理是编排层最容易被低估的部分。编码任务的上下文消耗非常大：代码文件、命令输出、错误日志、历史对话，加起来很容易超出模型窗口。编排层需要决定哪些信息放进上下文、哪些摘要化、哪些丢弃。常见策略是分层管理：最近的几轮交互保留完整信息，较早的交互做摘要，更早的只保留关键结论。这个策略的调参很讲究，保留太多会撑爆窗口，保留太少代理会“失忆”。

错误恢复是区分玩具和工具的关键。编码过程中出错是常态：测试不通过、命令报错、文件不存在、依赖缺失。好的编排层能从错误中提取有用信息，判断是重试、换方案还是求助人工。比如测试失败，代理应该先看失败原因，如果是断言不匹配，就改代码；如果是依赖缺失，就装依赖；如果是环境问题，就报告人工。这个判断逻辑需要精心设计，不能简单粗暴地“出错就重试”。

3.4 记忆层：短期记忆和长期记忆的配合

记忆层是很多开源实现容易忽略的部分，但它对代理的长期表现影响很大。我把记忆分成短期和长期两类。

短期记忆就是当前任务的上下文，包括任务目标、已执行的步骤、每步的结果、当前的代码状态。这部分通常放在模型的上下文窗口里，容量有限，需要精细管理。

长期记忆是跨任务的知识积累，包括这个项目的代码规范、常用的命令、之前踩过的坑、团队约定的模式。这部分通常存在外部存储里，需要时检索出来注入上下文。长期记忆的价值在于让代理“越用越懂你的项目”。比如第一次它可能不知道你们的测试命令是什么，你告诉它一次，它记下来，以后就自动用了。

长期记忆的实现方式有几种：简单的用文件存键值对，复杂的用向量数据库做语义检索。我的经验是，对于单个项目，文件存储加关键词检索就够了；对于多项目、多团队的场景，向量检索更合适。但要注意，长期记忆也会带来风险：如果记忆内容过时或错误，代理会一直沿用错误信息。所以记忆需要支持人工审查和修正。

4. 实操过程：从零搭一套可用的编码代理

4.1 环境准备与依赖安装

这一节给一套可复现的搭建流程。我假设你用的是常见的开发环境，具体命令我会给出来，你根据自己的系统调整。

第一步是准备运行时环境。编码代理通常需要较新的运行时版本，因为要用到一些新特性。以常见的运行时为例，先确认版本：

node --version

如果版本太旧，建议升级到当前稳定版。升级方式取决于你的系统，用系统包管理器或者版本管理工具都行。

第二步是获取代理的源码。从项目的公开仓库克隆下来：

git clone <项目仓库地址> cd <项目目录>

第三步是安装依赖。大多数项目用标准的包管理器：

npm install

这一步可能会比较慢，取决于网络和依赖数量。如果卡住，可以试试换镜像源或者用其他包管理器。

第四步是配置模型。这是最关键的一步。你需要准备至少一个模型的访问方式。如果用本地模型，需要先部署好推理服务，拿到服务地址；如果用外部 API，需要准备好 API 密钥。配置通常放在一个环境变量文件里：

# 模型配置示例 MODEL_PROVIDER=local LOCAL_MODEL_ENDPOINT=http://localhost:8000/v1 LOCAL_MODEL_NAME=coder-model # 或者用外部 API # MODEL_PROVIDER=remote # REMOTE_API_KEY=your_key_here # REMOTE_MODEL_NAME=some-model

提示：环境变量文件一定要加入版本控制的忽略列表，避免密钥被提交到仓库。这个坑我见过太多次了。

第五步是初始化项目配置。大多数代理需要在你的项目根目录放一个配置文件，告诉它项目的基本信息：

{ "projectName": "my-project", "language": "typescript", "testCommand": "npm test", "lintCommand": "npm run lint", "buildCommand": "npm run build", "ignorePatterns": ["node_modules", "dist", ".git"] }

这个配置文件的作用是让代理知道你的项目用什么命令跑测试、跑构建，以及哪些目录不用管。配置得越准确，代理的表现越好。

4.2 模型接入与参数调优

模型接入之后，参数调优是决定体验的关键。我重点讲几个最影响编码代理表现的参数。

温度参数控制输出的随机性。编码任务和创意写作不一样，需要的是准确和稳定，所以温度通常设得比较低。但也不能太低，太低会导致代理在遇到问题时不会尝试不同方案，一条路走到黑。我的经验值是设在一个较低的区间，具体数值需要根据模型特性微调。

最大输出长度决定了代理一次能生成多少内容。编码任务经常需要生成较长的代码或较详细的规划，这个值设得太小会导致输出被截断，代理的行为会变得不完整。但设得太大也有问题，会增加延迟和成本。建议根据任务复杂度动态调整，简单任务用小值，复杂任务用大值。

工具调用相关参数包括是否启用并行工具调用、单次最多调用几个工具、工具调用失败后是否重试等。并行工具调用能显著提升效率，比如代理可以同时读多个文件，但也会增加编排层的复杂度。建议初期先关闭并行，等基本流程跑通再开启。

上下文窗口管理参数包括历史保留轮数、摘要触发阈值、关键信息提取策略等。这些参数没有通用最优值，需要根据你的任务类型和模型窗口大小来调。我的建议是先用保守配置跑一段时间，观察代理在什么情况下会“失忆”，然后针对性调整。

调参这件事，我的整体建议是：不要一次调太多参数，每次只动一个，观察效果，记录变化。参数之间会相互影响，一次动多个你根本分不清是哪个起了作用。

4.3 工具权限配置与安全边界

工具权限配置是安全底线，必须认真对待。我按工具类别给出配置建议。

文件操作权限建议这样配：

{ "fileTools": { "read": { "allowed": true, "scope": "projectRoot", "maxFileSize": 1048576 }, "write": { "allowed": true, "scope": "projectRoot", "requireConfirmation": false, "backupBeforeWrite": true }, "delete": { "allowed": false } } }

读权限开放到项目根目录，但限制单文件大小，避免读一个巨大的日志文件把上下文撑爆。写权限也开放，但开启写入前备份，这样万一代理改错了你还能恢复。删除权限默认关闭，需要时手动开。

命令执行权限建议这样配：

{ "commandTools": { "allowed": true, "whitelist": [ "npm test", "npm run lint", "npm run build", "git status", "git diff" ], "blacklist": [ "rm -rf", "curl", "wget", "ssh" ], "timeoutSeconds": 300, "maxOutputLength": 10000 } }

白名单机制比黑名单更安全，因为黑名单永远列不全。只允许代理执行你明确认可的命令，其他一律拒绝。超时和输出长度限制也要设，防止代理跑飞。

注意：命令白名单要定期审查。随着项目演进，有些命令可能不再需要，有些新命令可能需要加入。我建议把白名单配置纳入代码审查流程，任何变更都要有人复核。

4.4 跑通第一个任务：让代理修一个真实的 bug

配置好之后，用一个真实的小任务来验证整套流程。我建议选一个边界清晰、影响范围小的 bug，比如某个函数的边界条件处理错误。

启动代理，给它任务描述：

<代理启动命令> --task "修复 utils/date.ts 中 formatDate 函数在传入无效日期时的崩溃问题，修复后确保相关测试通过"

代理的执行流程大致是这样的：先读 utils/date.ts 找到 formatDate 函数，再找相关测试文件，跑一遍测试确认当前失败状态，分析失败原因，修改代码，再跑测试，确认通过。

你要观察几个关键点。第一，代理有没有正确找到相关文件。如果它找错了文件，说明代码搜索工具有问题。第二，代理有没有先跑测试确认失败。如果它直接改代码，说明它的流程意识不够。第三，代理改完代码后有没有跑测试验证。如果它改完就宣布完成，说明它的验证环节缺失。第四，如果第一次改错了，它有没有根据测试报错自我修正。

这个过程中，你可以随时中断代理，查看它的中间状态，也可以给它补充信息。比如它找不到某个文件，你可以告诉它文件在哪。这种人工介入在初期很正常，随着你对代理行为的熟悉，介入会越来越少。

任务完成后，一定要审查代理的所有改动。用 git diff 看它改了什么，确认没有引入意外变更。这一步不能省，代理再聪明也可能犯错，人工审查是最后一道防线。

5. 常见问题与排查技巧实录

5.1 代理“卡住”不动了怎么办

代理卡住是最常见的问题，表现是它长时间没有输出，或者反复执行同一个操作。原因通常有几类。

第一类是模型响应超时。模型服务可能负载过高或者网络有问题，导致请求迟迟不返回。排查方法是看代理的日志，确认最后一次模型请求是什么时候发的、有没有收到响应。如果是超时，检查模型服务的健康状态和网络连通性。

第二类是工具调用死循环。代理可能陷入“调用工具-分析结果-再调用同一个工具”的循环。这通常是因为工具返回的结果没有给代理足够的信息来推进，或者代理的规划逻辑有缺陷。排查方法是看工具调用日志，如果发现同一个工具被反复调用且参数相似，基本可以确认是死循环。解决办法是在编排层加调用次数上限，超过就强制中断并报告。

第三类是上下文溢出。当上下文超出模型窗口时，有些实现会静默失败，表现为代理“失忆”或者行为异常。排查方法是看上下文长度监控，如果接近或超过窗口上限，就需要调整上下文管理策略。

我整理了一个速查表：

5.2 代理改错代码、越改越乱怎么破

代理改错代码是另一个高频问题。表现是它改了一处，测试挂了，再改一处，又挂了另一处，最后代码面目全非。

这个问题的根源通常是代理缺乏全局观。它只盯着当前报错，没有理解代码的整体结构，所以改一处坏一处。解决办法有几个。

第一是加强规划环节。让代理在动手之前先通读相关模块，理解模块之间的依赖关系，再制定修改方案。这个可以通过在提示词里明确要求来实现。

第二是限制单次修改范围。让代理一次只改一个逻辑单元，改完验证通过再改下一个。这样即使改错，影响范围也可控。

第三是开启写入前备份。这样万一代理把代码改乱了，你可以一键回滚到修改前的状态，不用手动恢复。

第四是引入人工确认环节。对于影响范围较大的修改，让代理先给出修改方案，人工确认后再执行。这个在初期特别有用，等你对代理的行为有足够信心了再逐步放开。

提示：我个人的做法是，在代理的配置里设置一个“修改行数阈值”，单次修改超过这个阈值就强制人工确认。这个阈值根据项目复杂度设，我一般设在几十行的量级。

5.3 上下文被撑爆的几种典型场景

上下文溢出是编码代理的“慢性病”，不致命但很烦人。我总结了几种典型场景和对策。

场景一是读取大文件。代理为了理解代码，可能会读一个几千行的文件，一下子占掉大量上下文。对策是在文件读取工具里加大小限制，超过限制的文件只读关键部分，或者先做摘要再读。

场景二是命令输出过长。跑一个测试可能输出几百行日志，全塞进上下文就爆了。对策是在命令执行工具里加输出截断，只保留开头和结尾的关键部分，中间用省略号代替。

场景三是历史对话累积。任务跑得越久，历史对话越多，上下文越满。对策是定期对历史做摘要，把早期对话压缩成关键结论。

场景四是多文件同时读入。代理为了理解一个跨文件的功能，可能同时读十几个文件。对策是分批读，读完一批做摘要，再读下一批。

这几种场景往往同时出现，所以上下文管理需要综合施策。我的经验是，把上下文预算分成几块：系统提示占一块，当前任务描述占一块，最近几轮交互占一块，历史摘要占一块，剩余空间留给工具返回。每块都有上限，超了就压缩或丢弃。

5.4 模型“幻觉”出不存在 API 的应对

模型幻觉在编码场景里特别危险，因为它会生成看起来很像那么回事、但实际上不存在的 API 调用。比如它可能调用一个你项目里根本没有的函数，或者用一个库的旧版接口。

应对幻觉，第一道防线是让代理在生成代码后立即验证。验证方式就是跑测试、跑构建、跑 lint。这些工具能捕获大部分幻觉导致的错误，因为不存在的 API 一跑就报错。

第二道防线是在提示词里明确要求代理“只使用项目中已存在的 API”。这个要求不能保证完全消除幻觉，但能降低概率。更好的做法是在上下文里注入项目的 API 清单或类型定义，让代理有据可依。

第三道防线是人工审查。对于代理生成的关键代码，人工过一遍，确认没有幻觉。这个在初期是必须的，等代理在你的项目上跑熟了，幻觉会明显减少。

第四道防线是建立反馈机制。每次发现幻觉，就把这个案例记录下来，作为长期记忆的一部分，让代理以后避免。这个机制需要人工维护，但长期看收益很大。

6. 影响范围与适用边界：这套东西到底能用在哪些场景

6.1 适合交给代理的任务类型

编码代理不是万能的，搞清楚它擅长什么、不擅长什么，比盲目吹捧或贬低都有用。根据我的实践，以下几类任务特别适合交给代理。

第一类是重复性的代码修改。比如把某个 API 的调用方式从旧版改成新版，涉及几十个文件，每个文件的改法都差不多。这种任务人工做又累又容易漏，代理做又快又全。

第二类是测试补齐。给一个已有模块补单元测试，代理能读代码、理解逻辑、生成用例、跑通验证。这个任务边界清晰，验证标准明确，非常适合代理。

第三类是 bug 修复。特别是那种有明确复现步骤和报错信息的 bug，代理能定位、能修改、能验证。但要注意，涉及复杂业务逻辑或架构问题的 bug，代理可能力不从心。

第四类是代码重构。比如提取重复代码、重命名变量、调整模块结构。这类任务有明确的模式，代理执行起来效率很高。

第五类是文档生成。根据代码生成 API 文档、注释、README。这个任务对准确性要求相对低，代理的产出通常够用。

6.2 暂时别交给代理的任务类型

有几类任务我建议暂时别交给代理，或者至少要人工深度介入。

第一类是涉及核心业务逻辑的修改。这类修改的影响面广、后果严重，代理可能理解不了业务上下文，改出看似合理实则错误的结果。人工主导、代理辅助是更稳妥的方式。

第二类是涉及安全敏感操作的修改。比如认证、授权、加密相关的代码，代理的修改可能引入安全漏洞。这类修改必须人工审查。

第三类是架构级的设计决策。代理能执行具体的修改，但做不了“这个模块应该怎么拆分”这种决策。这类决策需要人的判断。

第四类是跨多个系统的集成任务。代理通常只在一个代码库内工作，跨系统的任务它看不到全貌，容易顾此失彼。

第五类是没有明确验证标准的任务。代理需要“跑一下看看对不对”来验证自己的工作，如果任务没有可自动化的验证方式，代理就失去了自我纠错的能力。

6.3 团队协作中的角色定位

在团队里引入编码代理，角色定位要清晰。我的建议是把代理定位成“初级开发者的增强版”，而不是“高级开发者的替代品”。

具体来说，代理可以承担初级开发者能承担的那部分工作：按明确需求写代码、补测试、修简单 bug、做重复性修改。这些工作代理做得可能比初级开发者还快还稳。

但代理不能承担需要判断力的工作：需求分析、方案设计、代码审查、架构决策。这些工作还是得人来。

团队协作上，我建议建立这样的流程：人负责拆解任务、定义验收标准、审查代理产出；代理负责执行具体修改、跑验证、报告结果。人机之间是“指挥”和“执行”的关系，不是“竞争”关系。

还有一个容易被忽略的点：代理的产出需要有人负责。不能因为“是代理改的”就放松审查。代码是谁提交的，谁就要对代码负责，这个原则不能变。

7. 我踩过的坑和几条实在建议

7.1 初期别追求全自动

我刚开始折腾编码代理时，最大的误区是追求“全自动”——给个任务就撒手不管，指望它自己搞定一切。结果就是各种翻车：改错代码、跑偏方向、卡死不动。

后来我调整了策略：初期把代理当成“需要密切监督的实习生”，它每做一步我都看一眼，发现不对立即纠正。这个阶段效率其实不高，但能帮我快速理解代理的行为模式，知道它在什么情况下会犯错、犯什么错。

等我对代理的行为有了足够了解，再逐步放开监督。先放开低风险任务，再放开中风险任务，高风险任务始终保留人工确认。这个渐进过程大概花了我几周时间，但非常值得。直接上全自动，翻车成本太高。

7.2 日志和可观测性比什么都重要

代理出问题时，如果没有详细的日志，你根本不知道它为什么出错。我在这上面吃过大亏：代理改错了代码，但我不知道它是基于什么信息做的决策，只能从头复现，浪费大量时间。

后来我强制要求代理记录完整的执行日志：每次模型请求的输入输出、每次工具调用的参数和返回、每次状态转换的原因。日志要结构化存储，方便检索和分析。

有了日志之后，排查问题的效率提升了一个数量级。代理行为异常时，我直接看日志就能定位到是哪一步出了问题、为什么出问题。这个投入绝对值得。

7.3 长期记忆要定期清理

长期记忆是个双刃剑。用得好，代理越用越懂你的项目；用不好，过时的记忆会误导代理。

我遇到过一个典型问题：项目早期用了一个测试命令，后来命令改了，但代理的长期记忆里还存着旧命令，导致它一直用错误的命令跑测试。这个问题的根源是长期记忆没有清理机制。

后来我加了一个定期审查流程：每隔一段时间，人工过一遍长期记忆的内容，删掉过时的、修正错误的、补充新的。这个流程不复杂，但能避免很多莫名其妙的问题。

7.4 别把代理当黑盒

最后一个建议：别把代理当黑盒用。开源代理最大的价值就是透明，你要充分利用这个透明性。

具体来说，遇到问题时不要只想着“怎么让它跑起来”，而要想“它为什么跑不起来”。去看它的代码，看它的日志，理解它的决策逻辑。这样你不仅能解决当前问题，还能预判它以后可能出的问题。

而且，理解了内部机制之后，你就能做针对性的定制。比如你发现它在某类任务上总是规划得不好，你就可以改它的规划提示词；你发现某个工具返回的信息不够，你就可以改工具实现。这种定制能力，是闭源方案给不了的。

我现在的做法是，每遇到一个代理的“奇怪行为”，就花时间搞清楚背后的原因，然后把理解记录下来。这些记录积累起来，就成了我调优代理的知识库。这个过程一开始比较慢，但越往后越顺，因为大部分问题都是重复出现的，搞清楚一次就够了。