先说结论：Agent-Reach 是我从零写的自研 AI Agent 运行时，用 Rust 实现，核心就做三件事——让 Agent 稳定调用外部工具、把短期和长期记忆管起来、让多个 Agent 分角色协作完成复杂目标。项目名里的 Reach 是我的执念，它有两层含义：一是"工具可达"，就是 Agent 到底能"够到"多少个外部能力；二是"目标可达"，一个任务交出去能不能真的跑到终点而不是半路烂尾。这个项目前后写了四个月，已经在真实客服工单场景里替换掉了之前基于 LangChain 搭的 Demo，稳定性和资源占用都有明显改善。
如果你只是为了快速验证一个想法，直接用现成框架最省事；但如果你和我一样，要把 Agent 放进生产环境，面对的是几十个内部工具、每天上千次调用和各种反人类的输入数据，那自己写一个可控运行时的收益会远超想象。下面按我实际的开发顺序，把这个项目完整复盘一遍。
1. 从一个跑不动的 LangChain Demo 说起：为什么我决心自研 Agent-Reach
1.1 现成框架的痛：编排靠人肉，问题藏在链路深处
最开始我用 LangChain 搭工单自动处理 Agent 的时候，Demo 阶段一切正常：用户提问，模型调用几个工具，返回答案，看起来很顺。但一旦上了真实数据，问题全冒出来了。
首先是编排问题。所谓的"智能"其实有很大一部分是人肉写死的，LLM 只负责在链路的节点里生成文本和参数，而"下一步调哪个工具、失败以后走哪条分支"这些真正的编排逻辑，都是我手写在代码里的。工单场景里一个请求可能跨好几个系统，查订单、查退款状态、补发通知、更新标签，每个环节都可能出幺蛾子——接口超时、返回格式变来变去、参数里有特殊字符，链路越深越难排查。框架的抽象层把细节全吞了，等到生产环境出问题，我根本不知道是哪一层出了问题。
其次是资源占用。LangChain 全家桶加一堆依赖，一个 Agent 进程跑起来内存随随便便上 GB，启动还慢。我们需要在客服工作台里常驻多个 Agent 实例，每个坐席一个会话，内存直接扛不住。
还有一个很致命的问题：错误恢复。现成框架里工具调用一旦失败，通常就是把错误文本塞回给模型让它再试一次，没有重试上限、没有降级策略、没有"这个工具暂时不可用"的状态管理。结果就是模型在一个永远失败的调用上反复横跳，把 token 烧光，用户等半天等来一句"抱歉我遇到了问题"。
我意识到问题不在 LLM 本身，而是运行时太薄了。我需要的东西不是"更聪明的提示词"，而是一个能把工具调用、记忆、任务编排、错误恢复都管起来的 Agent 运行时。
1.2 "Reach" 的两层含义：工具可达与目标可达
给项目起名的时候我一直在想，一个 Agent 的价值到底怎么衡量。最后定了 Reach 这个词，因为它同时覆盖了我想解决的两件事。
第一层是工具的"可达性"：Agent 能不能够到它需要的能力。大模型的参数里装不下我司内部的订单系统和库存系统的数据，它必须通过工具去拿。工具可达性不只是"工具列表里有多少个工具"，还包括：工具的输入输出规不规范、沙箱隔离安不安全、调用超时怎么处理、失败之后能不能自动降级。工具链路越宽，Agent 能干的事越多。
第二层是目标的"可达性"：一个任务交给你，你能不能真的干完。很多 Demo 看着厉害，是因为只挑简单的用例展示。真实业务里，问题本身可能就有歧义、有缺失信息、需要多轮确认。目标可达是我最看重的指标，后面专门做了评测集来量化它。
1.3 项目定位：不是框架，是带仪表盘的运行时
想清楚之后定位就很明确了：Agent-Reach 不是一个"帮你编排流程的框架"，而是一个"帮你把 Agent 跑稳的运行时"。
我参考了 langchain、dify、crewai 这些框架的设计思路，但刻意没有去封装那些高级抽象。运行时里核心就四个模块：任务调度器、工具注册器、记忆管理器、监督器。每个模块都是独立组件，用消息驱动。这样做的最大好处是，出问题的时候我能直接看每个环节的状态，而不是在一堆抽象类的调用栈里猜来猜去。
目标用户也很清楚：后端工程师，要把 Agent 嵌进现有系统里的那种。不面向普通用户，不提供拖拽画布，界面只有一个观测用的控制台。这个定位帮我省了很多力气——我不需要做万能的低代码平台，只需要把运行时的稳定性做到极致。
2. Agent-Reach 的运行时骨架：Planner、Executor、Supervisor 三个角色怎么分工
2.1 三角色的职责边界与消息流转
整个运行时我实现了三个角色：Planner（拆解者）、Executor（执行者）、Supervisor（监督者）。用户请求进来以后，消息流大概是这样的：
- 用户请求进入会话队列，Planner 收到任务后把它拆成一个有序任务列表，每个任务带上明确的目标、依赖关系和成功标准；
- Executor 从队列里取任务，进入 ReAct 循环，调用工具拿信息、做推理，产出中间结论；
- 每个任务完成后，结果写回共享内存区，Supervisor 检查结果，判定"这个子任务合格了""需要补信息""还是整个任务应该终止"；
- 全部子任务通过后，Supervisor 汇总结果，生成最终回复。
这里有个设计细节：Planner 和 Executor 并不直接通信，中间隔着一个监督层。一开始我把拆解和执行做成直连，结果发现 Executor 执行过程中经常会发现任务拆得不合理，比如有个必要的依赖被漏掉了，这时候想改任务都不知道该通知谁。引入 Supervisor 做中转之后，Executor 发现问题可以上报，Supervisor 决定是否回退给 Planner 重新拆解。
// 三个角色之间的消息类型，用枚举来定义 pub enum AgentMessage { TaskAssigned { task_id: String, spec: TaskSpec }, TaskResult { task_id: String, content: TaskOutput, meta: ResultMeta }, TaskFailed { task_id: String, reason: FailureReason }, RequestResplit { task_id: String, message: String }, FinalAnswer { content: String }, }这套设计朴素，但我实测下来非常稳。角色少，职责清楚，消息类型有限，日志打出来一条条链路都对应得上。比起把编排隐式塞进"图"里，这种显式的消息流转更适合我这种需要对着日志排查问题的人。
2.2 会话级任务队列与优先级调度
任务队列我按会话来隔离，每个会话一条独立队列，避免多个用户的任务串台。队列里每条任务带优先级字段，交互类请求（用户正在等回复）优先级高，后台类请求（比如批量工单归档）优先级低。
优先级调度这块有个小坑：不能简单用优先级抢占，否则高优先级任务多的会话会一直插队，低优先级任务饿死在队尾。我加了一个简单的加权轮转逻辑，每条队列按优先级占比分配执行额度，保证低优先级任务至少能推进。
之前用 Python 原型的时候，队列是靠 Redis List 实现的，功能没问题但调试起来很痛苦——消息进出太快，不知道谁先消费了谁。换成 Rust 之后，我把队列搬进了内存，用 tokio 的 mpsc channel 实现，每个会话一个 channel，状态存在内存里，再异步刷到磁盘。这样既保证了实时性，崩溃了还能从快照恢复。
2.3 为什么是 Rust：单二进制、内存安全、沙箱亲和
选型的时候我对比过 Go 和 Rust，最后选了 Rust。核心原因有三个。
第一个是资源占用。Rust 编译出的单二进制文件静态链接，部署的时候一个文件搞定，不再需要一堆动态链接库。跑起来的内存占用比 Python 版本低了将近一个数量级——现在一个 Executor 实例大概 180MB，包括模型调用的缓冲区，这个数值在 Python 时代是不可想象的。
第二个是并发安全。Agent 运行时要同时跑很多异步任务：工具调用、LLM 请求、记忆写入、监督器检查。Rust 的所有权系统和 tokio 的异步模型让我在编译期就躲掉了一大批数据竞争问题。头发掉得少了，加班也少了。
第三个是沙箱亲和度。我计划用 WASM 沙箱来隔离不可信的工具代码，而 Rust 对 WebAssembly 的支持是原生级别的，wasmtime 库用起来非常顺。用 Python 或者 Go 想达到同等的隔离能力，得套容器或者虚拟机，重得多。
开发效率上确实比 Python 慢，这个我不洗地。但运行时的代码一旦写好，后面基本不怎么改，慢在前期的投资换来的是长期的稳定。这笔账我算过，划算。
3. 工具可达性：带 Schema 校验的工具注册器与 WebAssembly 沙箱
3.1 工具注册器的设计：JSON Schema 双端校验
工具可达性的地基是注册器。每个工具注册进来的时候，必须带上格式化的描述信息：
pub struct ToolDef { pub name: String, pub description: String, pub input_schema: serde_json::Value, // JSON Schema pub output_schema: serde_json::Value, // JSON Schema pub handler: Arc<dyn ToolHandler>, pub timeout: Duration, pub sandbox: SandboxMode, }工具的描述字段是给 LLM 看的，所以必须写得准确。我发现一个规律：description 里如果写了"调用这个工具前请确认参数 xxx"，模型就真的会主动去确认；如果只写"用于查询订单"，模型就会在信息不全的时候乱填参数。所以我在注册器里加了一个 lint 检查，描述不符合规范（缺少参数说明、没用中性语气）的工具直接拒绝注册。
输入校验是双重保险。第一重，模型生成的参数在进入执行器之前，先用 JSON Schema 校验一遍，不合规的直接不发给真工具，省掉一次真实调用；第二重，工具返回值也按 schema 校验，防止工具改了返回格式导致下游解析崩溃。
{ "type": "object", "properties": { "order_id": { "type": "string", "pattern": "^[A-Z]{2}\\d{8}$" }, "include_refunds": { "type": "boolean", "default": false } }, "required": ["order_id"], "additionalProperties": false }// 校验失败时的重试逻辑，控制重试次数，避免烧 token async fn call_tool_with_retry(tool: &ToolDef, args: Value, max_attempts: usize) -> ToolOutcome { for attempt in 0..max_attempts { let repaired = match validate_tool_args(tool, &args) { Ok(()) => args.clone(), Err(e) => repair_args_by_feedback(&e.feedback, &mut args).await, }; match tool.handler.call(repaired).await { Ok(output) => return ToolOutcome::Success(output), Err(err) if attempt < max_attempts - 1 => { // 把错误信息整理成结构化反馈，交给模型修正 args = build_correction_prompt(&err); } Err(err) => return ToolOutcome::Failure(err), } } }参数修复这步很值得说：模型第一次给的参数不对，你不应该把原始错误文本整段塞回去，那样既浪费 token 又容易把模型带偏。我这边会先把错误信息结构化，比如"字段 order_id 格式应为两位字母加八位数字，收到值 XYZ-123"，再把它作为反馈装进修正提示里发给模型。实测下来修正成功率高了很多。
3.2 沙箱执行：wasmtime 隔离、超时与取消
沙箱是我投入精力最多的模块之一。为什么需要沙箱？因为工具是 Agent 的双手，但这双手不一定可信。有时候是工具代码本身有 bug，有时候是模型生成参数过于离谱，比如拿订单号去调库存接口，还可能把不该删除的字段标成可删。如果所有工具都在主进程里裸跑，一次故障就能把整个 Agent 打崩。
我采用的方案是分级：
- 内部可信工具（自研系统的 SDK），直接用子进程隔离，进程崩溃不影响主进程；
- 第三方或不可信工具，编译成 WASM 模块，放进 wasmtime 沙箱里运行，通过网络白名单和文件系统能力限制，让它们只能访问被授权的东西；
- 纯计算型工具（正则、格式化、统计），才允许在主进程内勾线调用。
let mut store = Store::new(engine, wasi_ctx); let instance = Instance::new(&mut store, module, &imports)?; // 强制的超时控制，wasm 执行超过时限立刻终止 let timeout = tokio::time::timeout(tool.timeout, async { instance.get_typed_func::<(), i32>(&mut store, "run")?.call(&mut store, ()) }).await; match timeout { Ok(Ok(code)) => { /* 正常结束，按 code 判断返回码 */ } Ok(Err(_)) => { /* 陷入死循环了，回收 */ } Err(_elapsed) => { // 时间到了，中断执行并返回超时错误 } }沙箱的核心价值不是防黑客，而是防"意外"。它把工具出错的影响面锁死在沙箱内部，错误以受控的方式传回给 Agent，Agent 再决定重试还是换路，而不是让整个运行时跟着陪葬。
3.3 工具调用失败后的自适应降级
工具失败是常态，不是异常。我现在对工具调用的处理逻辑分三层：
第一层，重试修正。参数问题导致的失败，先修正参数重试一两次。
第二层，降级替代。比如向量数据库挂了对，我这边会自动切成关键词检索；订单接口 5xx，就切到只读缓存快照。每个工具注册时都会注一个fallback字段，指向备选工具，备选工具再失败就往上报。
第三层，标记不可用。同一个工具在短时间内连续失败几次，监督器会把它标记为"当前会话临时不可用"，并明确告诉模型："工具 X 暂时不可用，请基于已有信息作答或询问用户"。这一步避免了模型反复用同一个坏工具，大幅节省了 token，也提升了用户体验。
实测数据：加入降级机制后，工单 Agent 的故障会话比例从 12% 降到了 2.1%。这 2.1% 里有一大半是上游系统整体停机，Agent 再怎么努力也挽不回。
4. 记忆不是日志：短期事实、长期档案与双通道召回的设计
4.1 短期事实存储：SQLite 而不是 JSON 文件
开始写记忆模块前我问了自己一个问题：记忆和日志有什么区别？日志是给程序看的事件流水，记忆是给模型用的、经过筛选和结构化的事实。想清楚这一点，记忆模块的设计方向就完全不同了。
短期记忆我选的是 SQLite，WAL 模式，存的是当前会话里已经发生的事实：用户提供了什么信息、查询到了什么结果、决定了什么事。一开始图省事用 JSON 文件存，很快就被教育了——多线程并发写会丢数据，没有事务回滚，查个历史状态要全量读文件。SQLite 单文件、支持事务、并发读写稳妥，而且 Rust 侧有成熟的 sqlite 库，几行代码就能接上。
CREATE TABLE short_term_facts ( session_id TEXT NOT NULL, fact_key TEXT NOT NULL, fact_value TEXT NOT NULL, source TEXT NOT NULL, -- 'user' | 'tool' | 'planner' | 'executor' created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL ); CREATE INDEX idx_short_term_session ON short_term_facts (session_id, created_at);每条短期事实都带过期时间。客服场景里，用户说"我想退了这个订单"，这个事实的有效期可能就一天；但"这个用户是黑金会员"这种画像，该进长期档案而不是短期事实。过期机制保证会话上下文不会越滚越臃肿，这是 Agent 保持"清醒"很重要的一环。
4.2 长期记忆的写入策略：谁来决定"值得记住"
长期记忆的坑在于"写太多"。如果你把每个会话的完整记录都塞进长期记忆，那长期记忆很快就变成一锅粥，检索出来的全是噪音。
我的方案是加了一个"记忆策展人"角色。每个会话结束后，策展人（可以是一个轻量任务，不一定非得 LLM）负责做三件事：去重、泛化、归档。比如用户连续三次询问了"退货政策"，短期记忆里可能有三条重复记录，策展人把它合并成一条长期记忆："该用户近期关注退货政策，可能正在考虑退货"，并附上原始会话的引用 ID。
去重和归档用规则就能做掉一部分，但"泛化"这步还是得靠 LLM。好在策展人是异步的，不阻塞用户会话，即使慢一点也没关系。我用一个独立的低优先级队列跑策展任务，用户完全没有感知。
长期记忆的写入还有一个原则：宁缺毋滥。拿不准要不要写，就不写。因为写错记忆比没写记忆更糟——模型会一本正经地拿一条错误的长期记忆当事实，还很难纠回来。
4.3 双通道召回：向量检索加关键词检索
召回阶段我做的是双通道：向量相似度和关键词命中，然后把两路结果合并重排。为什么不做纯向量？因为 Agent 的记忆常常涉及精确值，比如订单号、日期、金额。向量检索对这类精确信息的召回很差，而关键词检索刚好补上这块短板。
向量通道用的是 sqlite-vec 插件，直接嵌在 SQLite 里，保持单二进制部署的简洁性。向量化的 embedding 请求我做了三级缓存：内存缓存、SQLite 本地缓存、远程模型服务。实测下来，embedding 调用量下降了 80%，整体检索延迟从 450ms 降到 120ms 左右。
合并策略很简单：向量结果前三名和关键词结果前三名取并集，都命中的排最前面。这个策略傻但有效，没有引入复杂的重排模型，维护成本极低。后续如果要优化，我会考虑给不同来源的记忆打一个新鲜度分数，让最近写入的记忆有更高的权重，但这轮我没做——先保证正确，再追求花哨。
5. 多 Agent 协作中的粒度实验：拆任务、跑循环、定阈值
5.1 任务拆分的粒度：拆太碎、拆太粗都会翻车
多 Agent 协作最核心的参数不是模型，是任务的"粒度"。我做过残酷的对比实验。
第一次，我让 Planner 把任务拆得很细，目标是"每个子任务都小到一眼能看懂"。结果一个"帮用户查询退款进度并通知"的请求被拆成了 8 个子任务，实际执行了 12 次 LLM 调用（因为有的子任务失败重试了）。每多一次调用就多几十秒延迟，用户等得很崩溃。
第二次，我反过来让 Planner 拆得粗，一个请求就一个任务。确实省调用，但 Executor 要在一个任务里走很长的链路，中间一旦出问题，整个任务只能整体重来，没有任何部分完成的收获。
最后打磨出来的拆法是一个原则：按依赖关系拆，不按动作数量拆。一条必须串行的链路（查订单 → 查退款 → 发通知 → 更新标签），就按四个逻辑阶段拆成四个任务，阶段内可能有多个动作，但动作之间不强行拆开。可以并行的分支（查订单和验证会员信息没有依赖关系），才单独拆出来并行执行。这个原则让平均任务数控制在 3 到 4 个，成功率和延迟都到了可接受的范围。
5.2 Executor 的 ReAct 循环实现细节
Executor 的核心是 ReAct 循环，但我在实现上做了一些参数和状态上的加码，让它更适合生产环境。
pub async fn run_react_loop( ctx: &ExecutionContext, tools: &ToolRegistry, max_steps: usize, ) -> LoopOutcome { let mut steps = Vec::new(); for step in 0..max_steps { // 组装当前状态给模型：系统提示 + 短期事实 + 工具描述子集 + 历史步骤 let prompt = build_react_prompt(ctx, &steps)?; let resp = llm_chat(&ctx.model_cfg, prompt).await?; if let Some(final_answer) = extract_final_answer(&resp) { return LoopOutcome::Finished(final_answer, steps); } if let Some(action) = extract_action(&resp) { let outcome = call_tool_with_retry(&action, tools).await?; steps.push(Step::Observation { action, outcome }); continue; } // 模型没有输出有效动作也没有输出最终答案 —— 视为一步失败 steps.push(Step::MalformedResp { resp }); } LoopOutcome::ExceededMaxSteps(steps) }有三个细节很关键。
第一，工具描述不能全量塞给模型。工具多了之后，完整列表会占掉海量 token。我实现了一个简单的相关性过滤，先让模型或规则筛选出和当前任务可能相关的工具子集，再把这个子集发给模型。实测工具调用准确率不但没降，反而因为"选择少、注意力集中"而升了一点。
第二，max_steps 必须有。没有上限的运行循环是预算黑洞，我设的默认值是 8 步，工单场景里大多数任务 3 到 4 步就结束了，8 步是给极端情况的保险。
第三，MalformedResp 也算一步。模型偶尔会输出既没动作也没最终答案的废话，如果不计步，它可能一直废话十几次。计步之后，废话达到几次就直接判失败，进入恢复流程，效率显著提升。
5.3 监督器：什么时候该收手、什么时候该返回去
Supervisor 是这套架构里最重要的角色，它负责回答三个问题。
第一个问题：这个子任务的产出合格吗？我的检测逻辑是多维度的：事实是否齐全（有没有拿到必要的字段）、工具调用是否有异常残留、最终答案是否有支撑来源。子任务的 spec 里会写清楚验收标准，比如"必须包含订单号、退款金额、预计到账时间"，监督器按标准逐项检查。
第二个问题：要不要回退重拆？当 Executor 上报"缺少前置信息，且认为应该返工"时，监督器会判断是信息真的缺失，还是 Executor 理解错了。判断依据很简单：如果短期记忆里的确有相关信息，那就是 Executor 的问题，让它重读记忆再跑一次；如果真没有，那就要么规划补齐信息的新任务（比如向用户追问），要么直接回报用户"还差哪些信息"。
第三个问题：要不要终止？我加了一个信心分数机制。每个子任务完成时，Executor 给它一个 [0, 1] 的置信度，监督器在关键任务上低于阈值就要求返工。整个任务的终止条件有两个：所有子任务通过，或者累计失败次数超过上限（默认 3 次）。上限到了就果断放弃，而不是无限循环烧钱。很多 Agent 项目在"什么时候放弃"这个决策上做得很烂，要么永不放弃，要么一失败就放弃，都不对。
6. 用"可达率"说话：评测集构造与三指标压测
6.1 自建评测集：真实业务 Query 加多级评分
不做评测，你就永远不知道 Agent 改进了没有。我吃过一次大亏：凭着感觉优化了一个版本，推出后发现用户投诉率上升了，但我自己跑 Demo 感觉还挺好。问题出在我用的是自己编的样例，跟真实用户问法完全不是一个分布。
后来我建了一个评测集，思路很简单但很费功夫：从线上日志里抽了 200 条真实工单请求，去掉涉及隐私的字段，保留原始表述——包括带错别字的、中英混杂的、问一半没问完的。每条请求都让三个业务专家标注，标注内容分四档：
- A 档：目标完全完成，信息准确，无幻觉；
- B 档：目标完成，但有一到两处信息不完整（比如查到了金额但没给到账时间）；
- C 档：部分完成，关键信息有缺失或错误；
- D 档：任务失败，回复无实际价值。
专家标完不一致的地方再人工仲裁，保证每条数据有稳定基准。这个评测集现在还在持续扩充，每加一批线上数据，就把旧的边缘 case 一起回归一遍，防止改一处坏一处。
6.2 三个核心指标：可达率、工具调用成功率、恢复率
评测指标我精简到三个，多了记不住也管不过来。
可达率就是 A 档和 B 档占总量的比例。这是最硬的指标，代表"用户交给 Agent 的事，到底办成没有"。我这个版本的可达率是 87.5%，比第一版提升了 22 个百分点，其中大部分提升来自降级机制和任务拆分原则的优化。
工具调用成功率是"成功返回预期格式结果的调用次数 / 工具调用总次数"。这个指标反映工具层的基本盘，成功率高不代表任务成功（模型可能乱用工具），但成功率低了任务一定好不了。当前是 94.2%，剩下 5.8% 里面，过半是上游系统本身的偶发故障。
恢复率是指工具调用失败后，Agent 能在不需要人工介入的情况下，通过重试、修正、降级等方式把流程走下去的比例。当前是 78%，这个指标直接决定了整体稳定性的上限。恢复率提升的空间还很可观，我下一步打算针对"连续降级链路"做专项优化。
这三个指标组合起来，能帮我在任何一个版本迭代后第一时间发现问题出在哪一段：如果成功率掉，先查工具注册层；如果恢复率掉，先查反馈修正逻辑；如果两个都不掉但可达率掉，那就是模型决策层的毛病，该调提示词或者换模型。
6.3 压测暴露的瓶颈与针对性调优
评测集给了量化依据之后，我做了一轮压测，重点看吞吐和延迟。
第一个发现是：性能瓶颈根本不在 LLM 主体调用上，而是 embedding。每轮检索要调 embedding 接口，单次约 50ms，但架不住次数多。加了三级缓存和批量编码之后，检索阶段的平均耗时降了一半以上。
第二个发现是：并行度太低。初始版本里子任务是一个个跑的，压测时发现一个 4 任务调用链跑下来要 90 秒，其中串行部分占了太多。改成无依赖任务并行之后，同样场景降到 55 秒左右。并行度的代价是内存和并发数的上升，所以我又给调度器加了一个并发上限控制，默认 4，避免高峰期把主进程资源耗尽。
第三个发现比较反直觉：温度设为 0 反而容易出问题。温度 0 下模型过于保守，遇到不太确定的参数会直接拒绝生成，导致大量"MalformedResp"。调到 0.2 之后，生成合理的参数反而更顺畅。这个小发现为我省下了不少失败重试的开销。
7. 踩坑实录：Rust 写 Agent 运行时最容易翻车的三个地方
7.1 异步循环里的取消与超时：一个隐藏的"僵尸线程"问题
Rust 的 async 默认是协作式取消，这个特性坑了我整整一周。具体场景是：当顶层任务超时被 abort 掉之后，它 spawn 出来的子任务并不会跟着取消，它们还在后台继续跑，等于是"僵尸线程"。表现为进程 CPU 居高不下，但日志里看不到任何活动任务。
当时的排查过程很折磨：先以为是死锁，加了一堆锁排查无果；又以为是内存泄漏，看内存监控也没有异常放大；最后在进程的线程快照里看到一堆卡在 socket read 上的线程，才意识到是 abort 没透传。
解决方法是统一用 CancellationToken 串起来。每个顶层任务持有一个 token，所有子任务共享同一个 token 派生出来的子 token，调用外部接口时监听取消事件，一旦触发就立刻中断等待。同时用 tokio 的 JoinSet 管理所有子任务，等待顶层结束时也 Join 一遍，确保子任务真正清理干净再返回。
这个坑提醒我：异步环境下"取消"是一个必须从设计层面就考虑进去的横切关注点，不能指望靠框架自动帮你处理。
7.2 参数序列化地狱：LLM 输出和真实类型的鸿沟
工具参数校验通过的代码，到了真实环境还是会崩，因为 LLM 输出的字段类型会花式作妖。我收集到的问题包括：数字字段输出成字符串、日期输出成中文"今天"、可选字段没有给 null 而是干脆缺了、布尔值输出成 "是/否"。
我一开始很天真，让 serde_json 直接反序列化到结构体，一遇到类型不匹配就报错。后来加了一个参数强制修复层，规则是：
- 字符串类型的数字字段，尝试安全转成数字，转换失败才报错；
- 布尔字段接受 "true"/"false"/"是"/"否"/"1"/"0"，映射成标准布尔；
- 缺失的可选字段填默认值，缺失的必填字段走修正反馈流程。
加完这层之后，工具调用成功率肉眼可见地涨了 5 个百分点。做 Agent 的人一定要有这种觉悟：LLM 的 JSON 输出从来不是真的等于 JSON Schema 定义的干净对象，它更像是"带自由发挥的 JSON"，你必须先把这层脏数据洗干净，工具侧才敢接。
7.3 "记忆污染"：上下文越长，Agent 越蠢
做了记忆模块之后，我犯了一个很多新手都会犯的错误——觉得记忆越多越聪明。结果恰恰相反：短期记忆里堆了几十条事实之后，模型反而开始犯低级错误。它会在二十条事实里找不到关键的那条，还会把过期的信息当最新状态用。我把这种现象叫作"记忆污染"。
后来我做了两个改动。第一，写入短期记忆前先过"当前状态摘要"这一关：每次工具调用或用户关键信息出现后，生成一条"当前状态"记录，并清理掉被覆盖的旧记录。比如用户先说"我要退款"，后来又改成"我要换货"，那么第一条事实会被标记为过期，而不是同时存在于上下文中让模型困惑。第二，送入 LLM 的短期记忆是分段裁剪的，最多保留最近的上限条事实，更早的进长期档案当背景，不直接进 prompt。
改完之后，模型在长会话里的准确率明显回升。这件事给我的启发是：记忆系统的目标不是"存更多"，而是"在正确的时刻给模型看正确的那一条"。把记忆当成数据库来设计，而不是当成垃圾箱。
最后，说点个人体会
写 Agent-Reach 这四个月，我最大的感受是：做 Agent 项目，难的不是"让模型聪明"，而是"让整个系统在真实环境下不崩"。模型的天花板决定 Agent 的上限，但运行时的稳健程度决定 Agent 的下限。我见过很多团队把关注点全放在调提示词、试不同模型上，结果系统上生产环境三天两头出问题，用户体验远不如一个用普通模型但运行得稳稳当当的系统。
如果你想复制这条路，我的建议很直接：先把"工具调用失败怎么处理"想明白，再谈记忆和多 Agent。工具层不稳，上层的一切智能都是空中楼阁。评测集从第一天就开始建，别等版本上线了才回头补，那时候你已经不知道哪个改动有用哪个改动有害了。至于技术栈，如果你没有必须用某语言的理由，而且团队熟悉 Rust，那这个选择会给你长期的扎实回报；如果你只是想要个能跑的 Agent，那现成框架确实更快，也省心。关键是把运行时的稳定边界想清楚，知道自己在哪一层投资。
