1. 从“记忆型 AI”到“开工型 Agent”的认知转变1.1 为什么“能记住”不等于“能干活”过去大半年我陆陆续续折腾过不少个人 Agent 项目。最开始那几版我几乎把全部精力都砸在了“记忆”上——向量库、长期记忆、对话摘要、实体抽取能上的全上了。结果呢每次演示的时候它确实能记住我三天前说过喜欢喝美式但真让它帮我处理一件稍微复杂点的事比如“把上周那几份合同里的关键条款整理成一张表顺便标出和标准模板不一致的地方”它就开始胡言乱语要么漏掉一半文件要么把条款张冠李戴。这个体验让我意识到一个很根本的问题记忆只是 Agent 的一个能力维度而不是它的核心价值。一个只会记住你偏好、却无法可靠执行任务的系统本质上还是一个“更聪明的聊天机器人”离“开工”差得远。真正能开工的 Agent需要的是可执行、可验证、可回滚的任务闭环而不是一个越来越大的记忆池。我后来复盘发现“记忆型 AI”有三个致命短板。第一记忆的写入和读取没有明确边界导致上下文污染严重越用越乱。第二任务执行过程没有结构化记录出了问题根本不知道是哪一步崩的。第三缺少对“完成”的定义Agent 自己也不知道什么时候算干完了经常陷入无限循环或者提前收工。这三点不解决记忆越多反而越拖后腿。1.2 我们给“开工”下的三个硬指标在动手重构之前我先给自己定了三条验收标准达不到就不算“能开工”。第一条任务必须能被拆成可独立验证的步骤。也就是说每一步做完之后我都能明确判断它对不对而不是等整个任务跑完再看结果。这要求 Agent 在执行过程中持续输出中间产物而不是黑箱式地一口气跑到底。第二条所有状态变更必须可追溯、可回放。今天它改了哪个文件、调了哪个接口、生成了什么内容我都要能查到。这不是为了审计而是为了调试——Agent 出错是常态关键是出错之后能不能快速定位。第三条失败必须能优雅退出并保留现场。最怕的就是任务跑到一半崩了上下文全丢只能从头再来。一个能开工的 Agent崩了之后应该能告诉我崩在哪、已经完成了什么、从哪可以续上。这三条听起来简单但真做起来涉及到的架构调整比我想象的大得多。接下来我把自己踩过的坑和最终跑通的方案完整拆一遍。2. 核心架构选型为什么是 Event Schema Append-only2.1 用 Event Schema 替代裸 JSON 的思考过程最早我的 Agent 状态是用一个大的 JSON 对象存的每次执行就往里塞字段。用了不到一周就崩了——字段越来越多命名越来越随意不同模块之间互相覆盖调试的时候根本看不出某个字段是谁写的、什么时候写的。后来我换成了Event Schema的思路不再维护一个可变的状态对象而是把 Agent 的每一次动作都记录成一个结构化事件。每个事件有固定的 schema包含事件类型、时间戳、来源模块、载荷、以及一个指向前序事件的引用。这样整个执行历史就是一条事件链状态是这条链的投影而不是一个被反复修改的变量。这个转变带来的好处非常直接。首先调试变得极其简单我只要顺着事件链往下看就能还原出 Agent 每一步的决策依据。其次模块之间解耦了每个模块只负责产生自己类型的事件不再直接改共享状态冲突自然消失。最后回放和重试变得可行因为历史是完整的我可以从任意一个事件节点重新开始执行。我用的 schema 大概长这样字段不多但够用{ event_id: evt_20240612_001, event_type: tool_call, timestamp: 2024-06-12T10:23:41Z, source: planner, payload: { tool: file_reader, args: {path: /docs/contract_a.pdf}, result_ref: evt_20240612_002 }, prev_event: evt_20240612_000, status: success }这里有几个设计细节值得说。event_type我用的是有限枚举不允许自由发挥这样后续做统计和过滤才方便。source标记事件由哪个模块产生排查问题时能快速定位责任方。result_ref指向结果事件把“调用”和“返回”分开记录避免一个事件里塞太多东西。prev_event构成链式结构保证顺序可还原。2.2 Append-only 存储带来的三个实际收益确定了 Event Schema 之后存储方式我选了Append-only也就是只追加、不修改、不删除。这个决定一开始让我有点犹豫因为直觉上“不能改”好像很受限。但实际跑下来收益远超预期。第一个收益是并发安全。多个模块同时写事件只要各自 append就不会有写冲突。以前用可变状态的时候我得加一堆锁还经常死锁。现在完全不用操心写入就是往链尾加一条天然串行。第二个收益是天然的时间旅行能力。因为历史不可变我可以随时把 Agent 的状态回滚到任意一个时间点。这在调试的时候太有用了——比如我想知道“如果当时不调用那个工具会怎样”直接从这个事件之前 fork 一条新链就行原链完全不受影响。第三个收益是审计和复盘成本极低。每次任务跑完我不用额外做日志事件链本身就是最完整的日志。我甚至写了个小脚本把事件链渲染成可读的时间线一眼就能看出 Agent 在哪一步犹豫了、哪一步绕了弯路。当然Append-only 也有代价主要是存储会持续增长。我的处理方式是定期做快照压缩把一段时间内的事件链折叠成一个状态快照快照之后的老事件归档。这样既保留了可追溯性又控制了活跃数据量。压缩策略我一般按任务边界来切一个任务完成就压一次比较自然。2.3 为什么没有选主流的 Agent 框架这里得坦白说我试过好几个现成的 Agent 框架但最后都放弃了。原因不是它们不好而是它们的抽象层级和我的需求不匹配。大部分框架把“记忆”“规划”“工具调用”打包成黑箱我很难在里面插入自己的 Event Schema 和 Append-only 逻辑。改起来要么 fork 源码要么在外面套一层结果就是架构越来越拧巴。自己搭的好处是每个环节都透明出问题我知道去哪找。坏处是前期投入大很多轮子要自己造。我的折中是核心的执行循环和事件系统自己写外围的工具调用、模型接入用现成库。这样既保证了核心可控又不至于什么都从零开始。实测下来这个边界划得还算合理核心代码不到两千行但覆盖了所有关键路径。3. 实操落地从零搭一个能开工的 Agent3.1 环境准备与依赖选择先说环境。我用的是 Python 3.11主要考虑是异步支持比较成熟而且类型提示用起来舒服。核心依赖就三个一个 HTTP 客户端负责调模型一个轻量级存储负责 append 事件一个调度库负责编排步骤。我刻意控制依赖数量因为 Agent 项目最容易失控的地方就是依赖膨胀最后自己都不知道哪个包在干什么。存储这块我一开始想用 SQLite后来换成了基于文件的 JSONL。原因是 JSONL 天然就是 append-only 的每行一个事件写入就是追加一行读取就是逐行解析简单到不能再简单。而且文件可以直接用文本工具查看调试的时候特别方便。性能上单机场景下 JSONL 完全够用我实测每秒写入几千条事件没有压力。模型接入我做了个薄封装把不同提供方的接口统一成一个complete(prompt, tools)的形式。这样上层逻辑不用关心底层用的是哪家模型切换成本很低。封装里我加了重试和超时控制因为模型调用失败是常态不能让一次失败把整个任务链搞崩。3.2 事件链的初始化与任务定义搭好环境之后第一件事是定义任务。我的做法是每个任务在启动时生成一个根事件类型是task_start载荷里包含任务描述、预期产出、以及一个唯一的任务 ID。这个根事件是整个事件链的起点后续所有事件都挂在它下面。任务定义我强制要求写清楚三样东西输入是什么、输出长什么样、怎么判断完成。第三点最容易被忽略但恰恰最重要。比如“整理合同条款”这个任务完成标准不能是“整理完了”而应该是“输出一张包含 N 个字段的表且每个字段都能追溯到源文件的具体位置”。有了明确的完成标准Agent 才知道什么时候该停。任务定义我一般写成 YAML可读性好也方便版本管理task_id: contract_extract_001 description: 从三份合同中提取关键条款并对比标准模板 inputs: - /docs/contract_a.pdf - /docs/contract_b.pdf - /docs/contract_c.pdf outputs: format: markdown_table fields: [clause_type, content, source_file, source_page, deviation] completion_criteria: - 所有输入文件都被处理 - 每个字段都有非空值 - deviation 字段对每个条款都有明确判断3.3 执行循环的编写与关键参数执行循环是整个 Agent 的心脏。我的实现是一个 while 循环每轮做四件事读取当前事件链的最新状态、让规划器决定下一步、执行这一步、把结果写成新事件。循环的退出条件是完成标准满足或者达到最大步数上限。最大步数这个参数很关键。设太小复杂任务跑不完设太大出错时会空转很久。我的经验值是按任务复杂度动态设置简单任务 20 步中等任务 50 步复杂任务 100 步。超过上限就强制退出并把当前状态标记为“未完成”保留现场供人工介入。每轮循环里规划器拿到的上下文不是全部历史而是经过裁剪的事件摘要。具体做法是保留最近 N 个事件的完整内容更早的事件只保留类型和关键载荷。这样既控制了 token 消耗又不丢失关键信息。N 我一般设成 10实测下来对大多数任务够用。执行这一步我做了个工具注册表每个工具声明自己的名称、参数 schema、以及返回格式。规划器只能从注册表里选工具不能凭空捏造。这个约束很重要早期我没做结果 Agent 经常调用不存在的工具然后卡死。加上注册表之后这类问题基本消失了。3.4 中间产物的落盘与校验中间产物必须落盘这是我从“记忆型 AI”时代学到的最重要一课。以前所有中间结果都放在内存里一旦进程崩了全丢。现在每一步的产出都写成事件落到 JSONL 文件里进程重启后可以直接从文件恢复。落盘之后还要校验。我的做法是每个工具执行完立刻做一次轻量级校验检查返回结构是否符合 schema、关键字段是否非空、数值是否在合理范围。校验不通过就标记这个事件为invalid并触发一次重试。重试最多三次三次都失败就暂停任务等人工处理。这个校验机制帮我挡掉了大量低级错误。比如有一次模型返回的 JSON 里少了个括号解析直接失败如果没有校验这个错误会一路传下去最后表现为“结果莫名其妙不对”排查起来非常痛苦。有了校验错误在产生的那一步就被抓住了。4. 常见问题与排查技巧实录4.1 事件链断裂的三种典型场景事件链断裂是我遇到最多的问题表现是prev_event指向了一个不存在的事件 ID。排查下来主要有三种原因。第一种是并发写入顺序错乱。两个模块同时读到了同一个链尾然后各自 append结果后写的那个覆盖了前一个的引用。解决办法是给 append 操作加一个轻量级的文件锁保证同一时刻只有一个写入者。锁的粒度按任务分不同任务之间不互相阻塞。第二种是进程崩溃导致写入中断。事件写了一半文件里留下一条不完整的记录。我的处理是在每条事件末尾加一个校验和读取时先验证校验和不通过就跳过这条记录并在日志里标记。这样即使有损坏记录也不会影响整条链的解析。第三种是任务 fork 之后引用混乱。前面说过我支持从任意节点 fork 新链但 fork 出来的链如果还引用原链的事件就会造成混乱。解决办法是 fork 时给新链分配独立的命名空间所有新事件的 ID 都带上前缀引用也只在新链内部解析。4.2 模型输出不稳定的应对策略模型输出不稳定是另一个高频问题。同一个 prompt今天返回 JSON明天返回 Markdown后天又夹杂一段解释性文字。我的应对分三层。第一层是prompt 里强制约束格式明确说“只返回 JSON不要任何额外文字”。这一层能解决大部分问题但不是全部。第二层是解析时做容错。我写了个解析器能自动剥离代码块标记、提取第一个完整 JSON 对象、修复常见的括号不匹配。实测下来这一层能再挡掉八成剩余问题。第三层是解析失败就重试重试时把上一次的失败输出作为反例塞进 prompt告诉模型“上次你返回了这个格式不对请重新返回”。这一层基本能兜住所有情况。三层加起来格式问题的最终失败率降到了千分之一以下。4.3 任务卡死的定位方法任务卡死表现为循环一直在跑但事件链不再增长或者增长的都是重复事件。定位方法我总结了一个三步法。第一步看最近十个事件的类型分布。如果全是tool_call没有tool_result说明某个工具调用卡住了。如果全是plan没有execute说明规划器陷入了循环。第二步看规划器的输入上下文。把最近的事件摘要打印出来看看是不是有矛盾信息导致规划器反复横跳。我遇到过好几次是因为两个事件的描述互相冲突规划器不知道该信哪个就一直来回选。第三步加一个重复检测。如果连续三个事件的类型和载荷高度相似就强制中断标记为“疑似循环”。这个检测我一开始没做后来加上之后卡死问题基本能在几轮之内被发现不用等到步数上限。4.4 常见问题速查表问题现象可能原因排查方法解决手段事件链断裂并发写入冲突检查 prev_event 引用加文件锁按任务分粒度事件链断裂进程崩溃验证校验和跳过损坏记录标记日志格式解析失败模型输出不稳定查看原始返回三层容错重试带反例任务卡死工具调用无返回看事件类型分布加超时强制中断任务卡死规划器循环看输入上下文加重复检测强制中断结果不对中间产物未校验回溯事件链每步加轻量校验存储膨胀事件无限增长看文件大小按任务边界做快照压缩这张表是我踩坑踩出来的基本覆盖了日常会遇到的问题。建议把它贴在显示器旁边出问题先对照一遍能省不少时间。5. 从能跑到好用几个提升稳定性的细节5.1 给每个工具加超时和熔断工具调用是 Agent 最容易出问题的地方。外部接口可能超时本地脚本可能死循环模型可能返回一个永远跑不完的参数。我的做法是给每个工具强制加超时默认 30 秒特殊工具单独配置。超时之后不直接失败而是标记为timeout让规划器决定是重试还是换方案。熔断是针对反复失败的工具。如果一个工具在短时间内连续失败超过阈值就暂时把它从注册表里摘掉避免规划器一直选它。熔断有冷却时间冷却结束后自动恢复。这个机制帮我挡掉了很多“明知不可为而为之”的无效尝试。5.2 用快照压缩控制存储增长前面提过 Append-only 的代价是存储增长。我的压缩策略是按任务边界做快照一个任务完成后把它的完整事件链折叠成一个状态快照快照里只保留最终产出和关键中间节点其余事件归档到冷存储。快照的格式我设计成和事件链兼容这样恢复的时候逻辑统一。快照本身也是 append-only 的新快照追加在旧快照之后形成快照链。这样即使快照逻辑有 bug也不会破坏原始数据大不了从原始事件链重新生成。实测下来压缩比大概在 20:1 左右一个跑了上千步的任务压缩后只剩几十条关键事件。查询速度也快了很多因为不用再遍历全部历史。5.3 人工介入的接口设计Agent 再强也有搞不定的时候所以人工介入的接口必须设计好。我的做法是在事件链里预留一种human_input事件类型Agent 遇到无法决策的情况时就写一个这种事件然后暂停等外部输入。外部输入通过一个简单的命令行界面提供我输入的内容会被写成human_response事件接在human_input后面然后 Agent 从这一点继续执行。整个过程不破坏事件链的连续性人工介入和自动执行在链上是一视同仁的。这个设计的好处是人工介入的痕迹也被完整记录后续复盘时能看出哪些地方是 Agent 自己搞定的哪些地方是靠人救场的。长期下来这些数据能帮我判断 Agent 的能力边界在哪哪些环节还需要加强。6. 我个人的一些实操体会这套东西跑通之后我最大的感受是Agent 的可靠性不来自模型有多强而来自工程约束有多严。同样的模型放在一个没有事件链、没有校验、没有超时的环境里表现就是时好时坏放在一个有完整约束的环境里表现就稳定得多。模型的不确定性是客观存在的工程的价值就是把这个不确定性框在一个可控范围内。另一个体会是不要追求一步到位。我一开始想设计一个完美的 schema结果卡了两天没动手。后来想通了先跑起来schema 不够用再改。因为事件链是 append-only 的改 schema 不会破坏历史数据新旧事件可以共存解析时按版本号区分就行。这个灵活性让我后续迭代快了很多。最后说个具体的技巧给事件加一个confidence字段。不是所有事件都同等可靠有些是模型直接产出的有些是经过校验的有些是人工确认的。用 confidence 标记可靠性规划器在决策时可以参考这个值优先信任高置信度的事件。这个小改动对稳定性的提升出乎意料地明显尤其是在处理长任务的时候。这套方案我还在持续打磨最近在试的是把事件链做成可查询的图结构方便做更复杂的依赖分析。等有新的进展再单独写一篇。如果你也在折腾个人 Agent欢迎交流尤其是事件 schema 的设计我觉得还有很多可以优化的空间。