Code Agent多智能体协作系统实战：RuntimeRunner硬调度设计

1. 这不是又一个“Agent框架”演示，而是一次真实系统生命周期的复盘

“Code Agent 解剖”这个系列我写了十八篇，每一篇都聚焦一个具体模块、一次关键迭代、一个踩过的坑。但第十九篇，我想聊点不一样的——不是怎么写好一个Agent，而是怎么看着它从一行空文件长成能跑通完整ReAct Loop的系统，再眼睁睁看着它被归档进git历史里，变成一个带星号的实验分支。标题里的“AgentTeams”，不是某个开源库的官方命名，而是我们内部给那个短暂存在了72天的协作式代码生成实验系统起的代号。它不叫AutoGen，也不对标LangChain的Team模式，它就是一串在凌晨三点commit message里写着“临时加个multi-agent coordination layer试试”的草稿。核心关键词很直白：Code Agent是它的身份底色，AgentTeams是它的实验形态，MyCodeAgent是它对外暴露的统一入口名，RuntimeRunner是它真正干活的执行引擎，而ReAct Loop——不是概念，是它每天要跑满23小时、每轮平均耗时8.7秒、失败率稳定在4.3%的真实工作流。

这个系统解决的问题非常具体：当单个Code Agent在处理跨文件、跨模块、带状态依赖的重构任务时，开始频繁卡在“理解上下文边界”和“协调修改顺序”上。比如把一个工具函数从utils.py抽离到core/transformers/下，再同步更新所有import语句和测试用例——单Agent要么改漏，要么改错顺序导致CI直接挂掉。我们没去堆prompt engineering，也没立刻上分布式调度，而是用最笨的办法：让三个角色Agent坐一张桌子——一个专读代码、一个专写修改、一个专做验证，它们之间不靠LLM自己推理协调，而是由一个轻量级RuntimeRunner硬编码调度逻辑。它不优雅，文档里找不到，社区没人提，但它在那72天里，把这类任务的交付成功率从61%拉到了89%。适合谁看？不是想学“如何设计下一代Agent架构”的理论派，而是正在被类似问题卡住、手头有真实代码库要动、需要立刻见效方案的工程师。你不需要懂Llama-3的attention机制，但得知道怎么让两个Agent不同时改同一个文件的同一行。

2. 系统设计思路：为什么选择“硬调度”而非“软协商”

2.1 放弃LLM自主协调的三个现实理由

当时团队争论最激烈的是“该不该让Agent自己协商”。主流方案无非两种：一种是像AutoGen那样，让每个Agent带一个System Prompt，描述自己的角色和协作规则，靠LLM输出JSON格式的“下一步该谁干”；另一种是用Tool Calling机制，让Agent调用一个“assign_task”工具，把子任务分发出去。我们试了两周，结论很明确：在代码生成场景下，LLM的协调能力是不可靠的幻觉放大器。不是模型不行，是问题域太苛刻。举三个实测案例：

• 案例1：重构任务中，Reader Agent识别出需要修改A.py、B.py、C.py三个文件，Writer Agent却只改了A.py和C.py，理由是“B.py的变更已在A.py中体现”——实际上B.py里有个独立的校验逻辑，漏改直接导致运行时panic。LLM把“逻辑等价”当成了“文件等价”。

• 案例2：验证环节，Verifier Agent报告“所有import已更新”，但实际漏掉了tests/unit/test_utils.py里一个深埋的from utils import *。LLM在长上下文里丢失了这个引用，而Reader Agent的摘要里根本没提测试文件。

• 案例3：当Writer Agent修改完A.py后触发pre-commit hook失败，LLM生成的恢复策略是“回滚A.py并重试”，但没意识到失败是因为B.py还没改，hook里有跨文件依赖检查——它把因果关系搞反了。

这三个问题背后是同一个本质：代码的精确性要求与LLM的概率性输出存在根本矛盾。LLM擅长模糊匹配和语义泛化，但代码重构要求字节级精确、依赖图严格、执行顺序确定。指望它在ReAct Loop里动态协调多Agent，就像让一个擅长即兴演讲的人去操作核电站控制台——听起来很酷，但没人敢签责任书。

2.2 RuntimeRunner：用确定性对抗不确定性

所以AgentTeams的设计起点很务实：把不确定的部分锁死，把确定的部分放开。我们把整个协作流程拆成四个硬性阶段，每个阶段由RuntimeRunner强制推进，不接受Agent的“建议”：

1. Context Harvest（上下文收割）：Reader Agent只做一件事——扫描指定目录，生成一份结构化代码地图（AST节点+文件路径+依赖关系），输出必须是JSON Schema定义的固定格式，字段缺失直接报错退出，不给LLM自由发挥空间。

2. Plan & Split（计划与切分）：RuntimeRunner拿到代码地图后，用预置规则引擎（不是LLM）做三件事：① 识别所有待修改文件；② 按文件粒度切分原子任务（如“修改A.py第12行import语句”、“在B.py第45行插入新函数”）；③ 根据依赖图排序任务队列。这里用的是一个简化的拓扑排序算法，复杂度O(n²)，但胜在100%可预测。

3. Execute & Validate（执行与验证）：Writer Agent按队列顺序逐个执行原子任务，每次只改一个文件的一处；Verifier Agent在每次Writer提交后，立即运行pylint + mypy + 单元测试子集，结果必须是布尔值（pass/fail），不接受“基本通过”或“警告忽略”这类模糊反馈。

4. Rollback or Commit（回滚或提交）：如果任何一步失败，RuntimeRunner触发全链路回滚——还原所有已修改文件到初始状态，并记录失败点。只有全部原子任务成功且验证通过，才允许git commit。

这个设计牺牲了“智能感”，换来了可调试性。你可以随时在任意阶段打断流程，查看RuntimeRunner生成的中间产物（比如Plan阶段输出的任务队列JSON），或者对比Writer执行前后的文件diff。而纯LLM协调的方案，debug时你只能看到一长串token概率分布，根本不知道它“以为”自己在做什么。

2.3 MyCodeAgent：统一入口背后的降维打击

MyCodeAgent这个名字听起来像一个产品，其实它只是AgentTeams对外的API网关。它的核心价值不是功能，而是收敛复杂度。用户调用时只传一个自然语言指令：“把utils.date_format()函数移到core/datetime.py，并更新所有调用处”。MyCodeAgent不做任何决策，它只做三件事：

• 解析指令，提取目标函数名、源文件、目标文件、影响范围（默认全项目）；
• 调用RuntimeRunner启动AgentTeams流程；
• 封装最终结果（成功/失败 + 修改文件列表 + diff摘要）。

为什么不用更“智能”的入口？因为我们发现，用户真正需要的不是“理解力”，而是“确定性响应”。当工程师说“我要重构”，他要的不是Agent跟你辩论“这个重构是否合理”，而是“OK，3分钟内给你一个可review的PR”。MyCodeAgent把所有决策权交给RuntimeRunner的硬规则，自己只做协议转换——HTTP请求转成内部消息，内部消息转成HTTP响应。它甚至没有自己的prompt模板，所有LLM交互都由Reader/Writer/Verifier各自封装。这种“无脑转发”看似简单，却让整个系统的可观测性提升了数个量级：所有日志都按RuntimeRunner的阶段打标，监控大盘能清晰看到“Plan阶段平均耗时1.2s”、“Verify阶段失败率最高（占总失败73%）”，而不是一堆混在一起的“Agent thinking time”。

3. 核心细节解析：RuntimeRunner的五个关键实现点

3.1 代码地图生成器：Reader Agent的“手术刀式”解析

Reader Agent不是简单地把文件内容喂给LLM。它的工作流是：先用tree-sitter解析目标代码库，生成AST；再遍历AST节点，提取三类信息并结构化存储：

• 声明节点：函数名、类名、变量名、所在文件、行号、参数签名（对函数）、继承关系（对类）；
• 引用节点：import语句（绝对/相对路径）、from...import...、函数调用、属性访问；
• 依赖边：基于引用节点构建有向图，边权重=引用频次（用于后续优先级排序）。

输出JSON示例：

{ "functions": [ { "name": "date_format", "file": "utils.py", "line": 12, "signature": "(dt: datetime, fmt: str) -> str", "references": [ { "file": "models/user.py", "line": 45, "type": "call" }, { "file": "tests/test_utils.py", "line": 12, "type": "call" } ] } ], "imports": [ { "file": "utils.py", "target": "core.datetime", "line": 3 } ], "dependency_graph": { "utils.py": ["core/datetime.py"], "models/user.py": ["utils.py"] } }

这个结构的关键在于剥离语义理解，专注结构提取。Reader Agent的LLM prompt只有一句话：“请严格按上述JSON Schema输出，不要添加任何额外字段或解释。” 它不负责判断“date_format是否应该移动”，只负责告诉你“它现在在哪、谁在用它、它依赖谁”。实测下来，这个步骤的准确率稳定在99.2%，错误基本来自语法错误的代码（比如未闭合的括号），而这类代码本身就不该进入重构流程。

提示：我们刻意避开了用LLM做AST解析。曾试过让GPT-4直接输出JSON，结果发现它会“脑补”不存在的引用，或者把注释里的字符串当成import路径。tree-sitter是唯一可靠的方案——它不理解代码，但绝不会错。

3.2 任务切分引擎：RuntimeRunner的“机械臂”逻辑

Plan阶段是RuntimeRunner最重的逻辑。它接收Reader输出的JSON，执行以下确定性步骤：

1. 目标定位：根据指令中的函数名（date_format），在functions数组中找到对应项，确认其当前文件（utils.py）和目标文件（core/datetime.py）。

2. 影响范围计算：遍历该函数的所有references，对每个引用文件，生成一个原子任务：

   • 任务类型：UPDATE_IMPORT（修改import语句）
   • 目标文件：models/user.py
   • 操作：将from utils import date_format改为from core.datetime import date_format
   • 行号：45
   • 前置条件：core/datetime.py必须已存在且包含date_format函数定义

3. 依赖排序：构建任务DAG。UPDATE_IMPORT任务依赖于CREATE_FUNCTION任务（在core/datetime.py中创建函数）。RuntimeRunner用Kahn算法做拓扑排序，确保CREATE_FUNCTION永远排在所有UPDATE_IMPORT之前。

4. 冲突检测：检查是否有两个任务修改同一文件的同一行。例如，如果另一个指令也要求修改models/user.py第45行，这里会直接报错“行冲突”，拒绝启动流程。这是人工Review无法实时发现的硬伤。

这个引擎没有机器学习，全是if-else和图算法。好处是：每一步都能单元测试，每个任务都能生成可追溯的ID（如TASK-20240515-001），失败时日志里直接显示“TASK-20240515-003 failed: line 45 conflict with TASK-20240515-002”。

3.3 Writer Agent的“手术执行”协议

Writer Agent不接受自由发挥。它只认一种输入格式：

{ "task_id": "TASK-20240515-001", "file_path": "core/datetime.py", "operation": "INSERT_FUNCTION", "content": "def date_format(dt: datetime, fmt: str) -> str:\n return dt.strftime(fmt)", "line_number": 15 }

它的输出也严格限定：

{ "task_id": "TASK-20240515-001", "status": "SUCCESS", "file_hash_before": "a1b2c3...", "file_hash_after": "d4e5f6...", "diff": "@@ -12,0 +13,5 @@\n+def date_format..." }

关键约束：

• 原子性：每次只改一个文件的一处，不允许批量修改；
• 幂等性：对同一task_id重复执行，结果必须一致（靠file_hash_before校验）；
• 可逆性：每次修改都生成reverse_diff，用于回滚。

我们放弃让Writer“理解”代码意图，只让它做文本编辑。实测证明，这反而提升了稳定性——GPT-4 Turbo在纯文本插入任务上的准确率是99.8%，而在“理解业务逻辑后重构”任务上只有82%。把复杂度锁死在协议层，是降低故障率最有效的手段。

3.4 Verifier Agent：不是“检查”，而是“执行”

Verifier Agent的名字容易误导。它不“检查”代码，它“执行”验证。流程是：

1. RuntimeRunner将Writer刚修改的文件复制到临时沙箱环境；
2. 在沙箱中运行三条命令：
   • pylint --errors-only <modified_file>（只报error，忽略warning）
   • mypy <modified_file>（类型检查）
   • pytest tests/ -k "test_date_format" --tb=short（只跑相关测试）
3. 收集三个命令的exit code和stdout，合成一个布尔结果。

输出JSON：

{ "task_id": "TASK-20240515-001", "status": "PASS", "pylint_errors": 0, "mypy_errors": 0, "pytest_failures": 0, "sandbox_hash": "xyz789..." }

这里的关键是沙箱隔离。我们不用本地环境验证，因为本地可能有未提交的脏代码。沙箱基于Docker镜像构建，镜像里只装项目依赖和Python，每次验证都是干净的。Verifier的LLM prompt只有一行：“请解析上述命令输出，严格按JSON Schema返回，不要解释原因。” 它不负责诊断错误，只负责传递结果。真正的诊断由RuntimeRunner的日志聚合完成——比如连续三次TASK-20240515-003失败，日志会显示“pylint error: unused variable 'fmt'”，工程师一眼就知道是Writer生成的函数签名漏了参数。

3.5 回滚机制：不是“撤销”，而是“还原”

AgentTeams的回滚不是Git reset，而是文件级精准还原。RuntimeRunner在每个Writer任务执行前，都会：

• 计算目标文件的SHA256哈希；
• 将原始内容base64编码，存入内存缓存（不是数据库，避免IO瓶颈）；
• 记录task_id与哈希的映射。

当流程中断时，RuntimeRunner遍历所有已执行任务的task_id，查缓存获取原始内容，直接覆盖写回文件。整个过程不依赖Git，不产生中间commit，100%可预测。实测回滚平均耗时210ms，比git stash pop快3倍。更重要的是，它规避了Git的“状态污染”风险——比如Writer修改了A.py，Verifier失败后回滚，但此时本地还有其他未add的修改，git reset会误删它们。文件级还原只动它动过的文件，其他一切照旧。

4. 实操过程：从零部署到生产灰度的七步落地

4.1 环境准备：最小可行依赖清单

AgentTeams不是重量级框架，它跑在一个标准Python 3.11环境中。我们刻意避开所有“AI工程化”套件，只用最基础的依赖：

安装命令：

pip install tree-sitter pydantic docker-py requests # 注意：tree-sitter需要编译，务必先装build-essential（Ubuntu）或Xcode command line tools（macOS）

注意：不要装langchain、llama-index、autogen这些。它们会引入大量隐式依赖，干扰RuntimeRunner的确定性调度。AgentTeams的哲学是“LLM只负责填空，不负责决策”。

4.2 Reader Agent配置：如何让LLM只做结构提取

Reader Agent的prompt模板是成败关键。我们反复迭代了17版，最终锁定这个极简版本：

You are a code parser. Your only job is to output JSON matching this schema: { "functions": [{"name": string, "file": string, "line": int, "signature": string, "references": [{"file": string, "line": int, "type": string}]}], "imports": [{"file": string, "target": string, "line": int}], "dependency_graph": {string: [string]} } Do not add any other fields, do not explain, do not format as markdown. Output pure JSON. Input code: {code_snippet}

关键技巧：

• 禁用解释：明确说“Do not explain”，否则LLM会加一堆“根据我的分析…”的废话，破坏JSON格式；
• 强Schema约束：用pydantic在代码层二次校验，任何字段缺失或类型错误都抛异常；
• 分片输入：单个文件超过500行时，自动按类/函数切片，分别调用LLM，再合并结果——避免上下文截断。

实测下来，这个prompt在GPT-4 Turbo上对Python代码的结构提取准确率是99.2%，错误集中在嵌套装饰器和动态import上，但这部分本就不该进入重构流程。

4.3 RuntimeRunner初始化：五参数启动法

RuntimeRunner不是一个类，而是一个函数工厂。启动时必须传入五个参数，缺一不可：

from runtime_runner import create_runner runner = create_runner( reader_agent=reader_client, # Reader Agent的API客户端 writer_agent=writer_client, # Writer Agent的API客户端 verifier_agent=verifier_client, # Verifier Agent的API客户端 sandbox_image="myproject:latest", # Docker镜像名，必须预构建 max_retries=3 # 单个任务最大重试次数 )

每个参数都有硬性要求：

• Agent客户端：必须实现统一接口execute(task: dict) -> dict，返回必须含task_id和status字段；
• Sandbox镜像：必须包含项目所有依赖，且WORKDIR设为/workspace，否则Verifier找不到文件；
• Max_retries：设为3是经验值。设为1则容错太低，设为5则失败任务拖慢整体流程。

启动后，runner会做三件事：① 验证所有客户端连通性；② 拉取sandbox镜像并检查tag；③ 预热一个沙箱容器（避免首次验证时冷启动延迟）。整个过程耗时<800ms。

4.4 MyCodeAgent API：最简REST接口设计

MyCodeAgent只暴露一个POST端点：/v1/refactor。请求体是纯文本指令，响应体是结构化JSON：

curl -X POST http://localhost:8000/v1/refactor \ -H "Content-Type: text/plain" \ -d "把utils.date_format()函数移到core/datetime.py，并更新所有调用处"

响应示例：

{ "request_id": "REQ-20240515-001", "status": "PROCESSING", "estimated_time_seconds": 180, "steps": [ {"phase": "ContextHarvest", "status": "COMPLETED"}, {"phase": "PlanAndSplit", "status": "COMPLETED"}, {"phase": "Execute", "status": "IN_PROGRESS", "current_task": "TASK-20240515-003"} ] }

关键设计：

• 异步响应：不阻塞等待，立即返回request_id，客户端用/v1/status/{id}轮询；
• 进度透明：steps数组实时反映RuntimeRunner的阶段状态，工程师可随时知道卡在哪；
• 无状态：所有中间状态存内存（用LRU cache），不依赖数据库——简化部署，提升速度。

我们刻意没做JWT鉴权、没做rate limit，因为这是内部工具。安全靠网络隔离，限流靠K8s HPA——让API保持呼吸感。

4.5 灰度发布策略：从个人笔记本到CI流水线

AgentTeams的上线分三步走，每步都设硬性指标：

1. 开发者本地验证（Day 1-3）：

   • 每个工程师在自己笔记本上跑通3个真实重构案例；
   • 指标：成功率≥95%，单任务耗时≤120s；
   • 失败案例必须人工Review，归因到Reader/Writer/Verifier哪个环节。

2. PR机器人集成（Day 4-14）：

   • 在GitHub Action中加入agent-teams-refactorstep，仅对refactor:开头的commit生效；
   • 指标：每周自动处理PR数≥20，人工干预率≤5%；
   • 所有失败PR自动打labelagent-failed，并附详细日志链接。

3. CI前置门禁（Day 15-72）：

   • 在CI pipeline的pre-test阶段插入AgentTeams检查：对所有修改文件，自动执行“影响范围分析”；
   • 指标：拦截高风险修改（如跨模块全局变量变更）准确率≥80%，误报率≤2%；
   • 此阶段不再自动修改，只输出report，由工程师决定是否采纳。

这个节奏保证了每个环节都有数据支撑。最终72天里，AgentTeams共处理1274次重构请求，成功率89.3%，平均节省人工重构时间42分钟/次。但它也暴露了致命短板：当代码库规模超过50万行时，Reader的AST解析耗时飙升至47秒，超出CI容忍阈值。这不是算法问题，是tree-sitter在超大文件上的固有瓶颈。

5. 常见问题与排查技巧实录：72天踩过的12个坑

5.1 Reader Agent的“幽灵引用”问题

现象：Reader输出的references里，出现了一个根本不存在的文件路径，比如/tmp/ghost.py。

根因：tree-sitter解析时，遇到from . import utils这样的相对import，会尝试解析__init__.py，但如果目录下没有__init__.py，它会fallback到临时路径。这不是bug，是tree-sitter的设计选择。

排查技巧：

• 在Reader的输入代码前，加一行# TREE-SITTER-DEBUG: true，它会输出解析日志；
• 检查日志里是否有failed to resolve relative import字样；
• 临时解决方案：在所有包目录下放空__init__.py。

实操心得：我们后来在RuntimeRunner里加了一层过滤，自动剔除所有/tmp/或/var/folders/开头的路径。这不是修复，是绕过——因为改tree-sitter源码成本太高。

5.2 Writer Agent的“行号漂移”故障

现象：Writer按指令修改第45行，结果改到了第46行，导致语法错误。

根因：目标文件在Writer执行前，被其他进程（如IDE自动保存、git merge）修改过，行号已变。Writer拿到的是旧快照。

排查技巧：

• 启用Writer的--dry-run模式，它会输出将要修改的diff，不实际写入；
• 对比file_hash_before和当前文件哈希，不一致就报警；
• 终极方案：Writer执行前，用flock锁定文件。

我们选择了第三种。在Writer的Docker容器里，执行修改前先flock /workspace/target.py -c "python write.py"。虽然增加了100ms延迟，但100%杜绝了行号漂移。

5.3 Verifier沙箱的“依赖幻影”

现象：沙箱里mypy报错ModuleNotFoundError: No module named 'core'，但本地环境正常。

根因：Docker镜像构建时，COPY . /workspace没包含src/目录下的core包，只copy了setup.py。

排查技巧：

• 在Verifier的沙箱里加一条debug命令：ls -R /workspace，确认目录结构；
• 用docker run -it --rm -v $(pwd):/workspace myproject:latest bash手动进镜像验证；
• 构建镜像时，用.dockerignore排除__pycache__和.git，但别excludesrc/。

教训：沙箱环境必须100%复现CI环境。我们后来把镜像构建脚本和CI的build.yml完全同步，用同一个Dockerfile。

5.4 RuntimeRunner的“任务雪崩”

现象：一个简单的函数移动，触发了200+个UPDATE_IMPORT任务，流程卡死。

根因：Reader的references数组里，把from utils import *展开成了所有函数名，包括根本没用到的date_parse、time_now等。

排查技巧：

• 在Plan阶段加日志：logger.info(f"Generated {len(tasks)} tasks for {function_name}")；
• 设置硬上限：if len(tasks) > 50: raise ValueError("Too many tasks, aborting")；
• Reader的prompt里加约束：Only include references that directly call the target function。

我们选了第二种。50是个经验值——超过50个文件调用同一个工具函数，说明设计有问题，该拆分了。

5.5 MyCodeAgent的“超时静默”

现象：API返回504 Gateway Timeout，但RuntimeRunner日志里没有任何错误。

根因：Nginx默认超时60秒，而一个大型重构可能耗时90秒。Nginx先断开连接，但RuntimeRunner还在跑。

排查技巧：

• 在MyCodeAgent的API handler里，加asyncio.wait_for(runner.execute(), timeout=120)；
• Nginx配置加proxy_read_timeout 120;；
• 最重要：所有异步任务必须有try/except包裹，失败时主动写入Redis status key。

我们后来在所有关键路径都加了超时保护，并用Redis做状态中心，这样即使API断开，客户端也能用/status/{id}查到最终结果。

5.6 回滚失败的“哈希失联”

现象：回滚时提示No original content found for TASK-20240515-001。

根因：RuntimeRunner的内存缓存是LRU，当并发任务过多时，旧task的哈希被挤出。

排查技巧：

• 监控缓存命中率：cache_hit_rate = hits / (hits + misses)，低于95%就要扩容；
• 把缓存从内存移到Redis，但会增加200ms延迟；
• 更优解：Writer执行前，把原始文件内容存到本地临时目录，路径用task_id哈希，回滚时直接读。

我们选了第三种。临时目录用/tmp/agent-teams/{task_id}/original.py，100%可靠，且清理简单——任务完成后shutil.rmtree即可。

5.7 ReAct Loop的“无限重试”

现象：一个任务失败后，RuntimeRunner重试3次，每次都失败，最后报错但没给出根本原因。

根因：Verifier的pytest命令没加--tb=short，stdout太长，LLM解析失败，返回空JSON，RuntimeRunner误判为“验证通过”。

排查技巧：

• 所有命令输出必须截断：timeout 30s pytest ... 2>&1 | head -n 100；
• Verifier的LLM prompt里加If output is empty or invalid, set status to "PARSE_ERROR"；
• 在RuntimeRunner里加fallback：当Verifier返回空时，直接标记为VERIFIER_PARSE_FAILED。

这个坑让我们损失了两天debug时间。教训：永远假设下游会返回垃圾数据，上游必须做防御性解析。

5.8 多Agent的“资源争抢”

现象：两个AgentTeams实例同时运行，Writer修改同一个文件，导致内容错乱。

根因：RuntimeRunner没做分布式锁，多个实例共享同一代码库。

排查技巧：

• 用Redis锁：redis.lock(f"repo:{repo_hash}", timeout=300)；
• 或更简单：在代码库根目录放.agent-teams-lock文件，Writer执行前检查并创建；
• 最佳实践：每个AgentTeams实例绑定唯一代码库副本，用git worktree隔离。

我们用了第二种。.agent-teams-lock文件里写入进程PID，冲突时直接kill -9 {pid}。粗暴但有效。

5.9 LLM的“幻觉注入”

现象：Writer生成的函数体里，多了import numpy as np，但原代码根本没用numpy。

根因：Writer的prompt里写了“include necessary imports”，LLM过度发挥。

排查技巧：

• 把“necessary imports”改成“only imports present in original file's top-level scope”；
• Writer输出后，用AST比对：提取生成代码的import列表，与原文件diff，只保留交集；
• 加一道静态检查：grep "import " generated.py | grep -v "from utils"。

我们加了第二道。AST比对100%准确，且不依赖LLM。

5.10 网络分区的“状态撕裂”

现象：Reader成功，Writer失败，但Verifier仍被调用，返回“PASS”，整个流程标记为成功。

根因：RuntimeRunner的阶段间没有状态持久化，网络抖动导致Writer响应丢失，但Verifier的调用请求已发出。

排查技巧：

• 所有阶段调用加retry=2，用指数退避；
• Writer成功后，写一条task_status: EXECUTED到Redis；
• Verifier调用前，先查Redis，确认Writer状态为EXECUTED。

这个设计让整个流程变成“至少一次”语义，虽有重复，但保证不丢。

5.11 日志的“信息黑洞”

现象：流程失败，但日志里只有Task failed，没有具体哪行错。

根因：Logger配置没设exc_info=True，异常堆栈没打印。

排查技巧：

• 统一Logger配置：logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s", exc_info=True)；
• 在每个Agent的execute方法里，try/except捕获所有异常，logger.exception("Agent execution failed")；
• 关键变量打log：logger.debug(f"Task {task_id} input: {task}")。

一句话：不打堆栈的日志，等于没日志。

5.12 归档决策的“最后一击”

现象：系统运行良好，为何72天后被归档？

根因：不是技术失败，是价值衰减。当代码库增长到80万行，Reader耗时突破60秒，CI无法接受；同时，团队发现85%的重构需求其实只需修改3个文件以内，单Agent+强化prompt就能搞定。AgentTeams的边际收益为负。

排查技巧：

• 建立ROI仪表盘：横轴是代码库规模，纵轴是AgentTeams vs 单Agent的耗时比；
• 当比值>1.5且持续一周，触发归档评审；
• 归档前，把RuntimeRunner的硬规则引擎抽出来，作为独立库code-restructure-engine开源。

这就是AgentTeams的终点——它完成了使命，然后安静离开。没有失败，只有适时退场。

6. 项目终结的思考：为什么“生与死”才是Code Agent最该讲的故事

AgentTeams停运那天，我没写任何总结邮件。只是把README里那句“Experimental multi-agent code refactoring system”改成了“Deprecated. See code-restructure-engine for core logic.”。它没死在bug里，没亡于架构腐化，而是死在了一个更残酷的真相面前：在工程世界里，一个系统最大的成功，不是活得多久，而是死得有多及时。

回头看这72天，最值得记录的不是那些漂亮的指标——89.3%的成功率、42分钟的人效节省、1274次自动重构。而是那些深夜三点的debug会议，大家围着屏幕看tree-sitter的解析日志，争论“relative import的fallback路径算不算bug”；是第一次看到Verifier沙箱里mypy报错时，整个办公室爆发出的、带着疲惫的笑声；是当RuntimeRunner的回滚机制在CI里100%还原了被误删的测试文件，那个实习生跳起来拍桌子的样子。

Code Agent不是魔法，它是工具，是杠杆，是无数个确定性规则对抗不确定性世界的笨拙尝试。AgentTeams的“死”，恰恰证明了它的“生”足够真实——它没活在论文里，没飘在PPT上，它真正在生产环境里流过汗、出过错、救过火，然后在该谢幕的时候，鞠躬退场。

如果你正打算启动一个类似的实验，我的建议只有一条：别想“怎么让它永生”，先想“怎么让它死得明白”。