1. 先搞清楚让Agent讲流程为什么比写代码更费劲前阵子接手一个别人维护了两年的跨平台应用交接文档只有三页登录、存储、更新这三条主链路基本靠口口相传。我的任务是在一周内把这三条链路讲清楚给新加入的同事做一份可复现的说明。人肉读代码当然可以但仓库里前端、后端、本地桥接层加起来几十万行通读一遍不现实。于是我想到用 REA 的思路搭一个 Agent——Reason、Act、Observe 三步循环让它自己去翻代码、追调用链、汇总结论最后输出一份能讲清楚应用登录、存储与更新流程的报告。这个想法的出发点是这三条链路的本质不是某个文件写了什么而是信息在哪些模块之间流动恰好是 Agent 擅长的多跳检索场景。但真正跑起来之后我发现一个反直觉的事实让 Agent 写出一个能跑的登录页面它表现还行让它讲清楚这个应用现有的登录流程它错得离谱。写代码是从零构造模型只需要符合语法和常见范式讲流程是还原既有事实模型必须被证据约束住任何一处凭印象补全都会变成错误结论。这就是我后来花了大量时间在工具设计和输出校验上的原因——REA 的难点从来不在 Reason而在 Act 和 Observe 是否足够诚实。这篇内容适合三类人看一是正在用 Agent 做代码理解、系统梳理的开发者二是需要给遗留系统补文档、做知识沉淀的维护者三是对 ReAct 类循环只有概念、没真正踩过坑的读者。我会把登录、存储、更新三条链路拆开讲每一步说清楚Agent 该看什么为什么看这里它容易在哪里编以及我自己实测下来有效的参数和工具粒度。1.1 三条链路的隐性知识密度完全不同很多人以为流程说明就是画个时序图实际上这三条链路的知识分布差别极大Agent 需要在三种不同的检索模式之间切换。登录链路是窄而深。它在代码里的物理跨度可能只有五六个文件但每一步都带着状态表单校验失败、请求被拦截、凭证过期续期、多端并发登录互踢、设备指纹变化触发二次验证。这些状态大多不在主流程的显式代码里而是散落在拦截器、异常处理器、甚至配置开关里。Agent 如果只顺着主路径追讲出来的流程会干净得不像真实系统。存储链路是宽而浅。读写点可能散布在几十个模块每个点单看都很简单难的是收敛——你要回答的是这个键到底被谁写、被谁读、什么时候失效这是一个全局视图问题靠局部阅读永远拼不出来。更新链路是协议密集。版本协商、灰度分组、差分包生成、签名校验、安装失败回滚每一步都有明确的协议字段和边界条件。这类内容文档化程度通常最高但也最容易过期——代码改了、文档没改Agent 如果优先信任文档就会讲错。我后来的做法是给三条链路配三套不同的提问清单而不是让 Agent 用同一套策略去啃。这个改动的收益比调模型参数大得多。1.2 REA 循环真正在循环的是证据增量关于 ReAct最常见的误解是把它当成多轮对话 工具调用。如果每一轮只是换个说法重复问循环就是空转。我理解的 REA 关键指标只有一个每一轮 Observe 之后Agent 掌握的、可引用的事实是否增加了。举个实测中的对比。我最初给的工具是读取指定路径的文件Agent 第一步读了入口组件第二步读了路由配置第三步开始读一个跟登录完全无关的样式文件——因为它没有下一步该看什么的约束只能按目录顺序往下翻。改成按符号名定位 追踪调用链之后它的路径变成定位登录按钮的点击处理函数 → 追到请求封装层 → 追到拦截器 → 追到凭证写入。四步走完事实密度是完全不一样的。所以我在系统提示里加了一条硬约束效果立竿见影在调用任何工具之前先用一句话写明我当前缺哪个事实、我打算通过哪个工具获取它。如果这句话写不出来说明这一步是无效动作应该直接给出结论或声明无法确定。这条约束逼着模型把我想再看看变成我要验证 X。实测下来平均工具调用次数从 23 次降到 11 次结论准确率反而上升因为无效的翻找少了噪声也少了。2. 工具层的设计底线只读、细粒度、可回溯Agent 讲错流程八成不是模型笨而是工具给得太粗。我见过最典型的错误是直接给一个读取整个代码仓库的能力然后指望模型自己在大海捞针。上下文窗口再大也扛不住这种方式而且一旦超限模型丢的是最早读到的那些入口信息——恰恰是最关键的部分。我的原则是三个词只读、细粒度、可回溯。只读是因为流程梳理阶段绝不能让 Agent 有机会改代码细粒度是为了让每一步的 token 消耗可控、证据可定位可回溯是说每次工具返回都必须带文件路径和行号否则结论无法被人工复核也就失去了价值。2.1 工具粒度切到什么程度算合适我最终留下的是六个工具功能上刻意做了重叠让 Agent 有选择余地工具输入返回适用场景文件名检索关键词/通配路径列表限 50 条定位模块边界符号定位函数名/类名/常量名定义位置 引用位置追调用链起点片段读取路径 起止行带行号的代码片段精读关键逻辑调用链追踪符号名 方向上下游各 N 层调用点跨文件追流程配置查询配置键前缀键值 环境差异确认开关与参数变更历史查询路径 时间范围提交摘要 改动行数判断文档是否过期关键在片段读取这个工具上。我一开始允许它一次读 2000 行结果 Agent 读得很爽但读完就忘因为关键信息被稀释了。后来硬性限制单次上限 120 行并在提示里要求读完立即写一句结论它的表现明显变好。小步读取 即时归纳比大步读取 事后总结可靠得多。还有一个细节调用链追踪工具我做了方向参数默认只追向下被调用方需要显式指定才追向上。原因是向上追的噪声极大一个工具函数可能被几十处引用Agent 很容易陷进去出不来。默认收窄是为了保护它。2.2 返回值裁剪头尾保留加命中上下文工具返回什么直接决定了模型能推理出什么。我踩过的第一个坑是返回完整文件内容第二个坑是只返回匹配的那一行。前者噪声太多后者信息不足——只给一行代码Agent 根本不知道这段代码在什么条件分支里。最后定下来的裁剪策略是命中行上下文各取 15 行文件头保留 10 行通常包含 import 和模块声明超过 300 行的文件额外附一个符号大纲。返回结构统一成 JSON大致长这样{ file: src/auth/session.ts, total_lines: 412, outline: [refreshToken, scheduleRefresh, clearSession], snippets: [ {start: 88, end: 118, reason: match: refreshToken} ], truncated: true }带上outline和truncated是有讲究的。前者让 Agent 知道这个文件里还有别的相关函数避免它以为看到的片段就是全部后者明确告诉它内容被截断了防止它基于不完整信息下结论。这两个字段加上之后Agent 主动补读的概率明显提高说这个文件里没有相关逻辑这种错误结论的情况基本消失了。提示裁剪参数不要一次定死。我最初把上下文设成 5 行结果 Agent 完全无法判断代码处于哪个条件分支里反复要求重读同一段。改成 15 行之后重复读取率下降了大约六成。3. 登录流程从一次点击到一张凭证的完整追踪登录是三条链路里最容易被讲浅的。浅版本是用户输入账号密码请求接口拿到令牌存起来四句话就完了但它无法回答任何一个真实问题令牌过期了怎么办用户在两个设备上同时登录会怎样请求发出去之前有没有做签名这些才是接手的人真正想知道的。我让 Agent 按固定的观察点顺序推进顺序本身就是一种约束防止它乱翻。3.1 观察点的固定顺序与理由顺序是这样的入口视图组件 → 表单校验逻辑 → 请求封装层 → 请求拦截器 → 响应拦截器 → 凭证落盘位置 → 启动时的凭证恢复逻辑。为什么是这个顺序因为登录是一次从界面到存储再回到界面的环形流动从入口切入保证了方向唯一不会中途跑到别的分支去。每一步我给 Agent 一句明确的检索目标比如到请求拦截器这一步目标写成找出所有在请求发出前被注入的头部字段并说明每个字段的来源。这样它不会泛泛地读一遍就交差而是带着具体问题去看。实测中 Agent 在这一步最容易漏掉的是签名计算。因为签名逻辑常常不在拦截器主文件里而是被抽到一个独立的工具模块拦截器里只有一行调用。如果 Agent 没有顺着这一行继续追的指令它就会停在拦截器里把注入了 token 头当成全部。补上这条指令之后它的输出质量提升很明显能讲出签名的输入包含时间戳、请求体摘要和一个本地密钥密钥来自构建期注入的环境配置这种颗粒度的内容。这类信息在交接文档里通常是完全没有的。3.2 凭证落地与续期Agent 编故事的重灾区我统计过 Agent 讲错的高频点续期逻辑稳居第一。原因很简单续期是一个并发 时序问题而代码里体现它的方式非常隐晦——通常是一个正在刷新的标志位加一个等待队列。Agent 看到标志位最常见的错误解读是如果正在刷新就等待刷新完成后重试听起来对但真实实现往往是挂起当前请求把它的回调塞进队列刷新成功后统一重放。这两种描述在代码上只差几行在行为上差别巨大前者在刷新失败时会把错误透传给每个请求后者只会失败一次。我的处理办法是要求 Agent 在描述这类逻辑时必须附上代码片段并且回答三个具体问题刷新期间进来的请求是被丢弃、被排队还是被并行重发刷新失败时已排队的请求收到的是什么错误刷新成功的判定依据是 HTTP 状态码、业务错误码还是响应体里的字段这三个问题逼着它去看真实的判断条件而不是套用经验。凡是它回答不出来或者含糊带过的我就标成待人工确认绝不会直接写进最终报告。凭证的存储位置也有讲究。移动端常见的是加密的本地存储或者系统密钥链Web 端可能是内存加可持久化存储的组合。Agent 容易把写进去了当成结论但真正要讲清楚的是存的是明文还是密文、密钥从哪来、多标签页之间怎么同步。我一般会让它额外查一次配置确认存储层是否启用了加密开关因为这个开关通常由环境配置决定代码里的写入路径是看不出来的。4. 存储流程把散落的读写点收敛成一张流向表存储链路是最能体现 Agent 价值的地方因为这是纯粹的体力活——人工做要翻几十个文件做完了还得反复核对有没有遗漏。但如果方法不对Agent 会给你一份每个文件都提到了存储的流水账毫无用处。我的做法是先让它做键空间梳理再做读写归类最后才是一致性分析。顺序不能反因为一致性分析必须建立在完整的读写清单之上。4.1 键空间的三种收敛方式第一步是找出所有存储键。Agent 通过检索存储接口的调用点把所有键名或键前缀列出来。这一步的产出往往很乱同一个业务的数据可能被拆成七八个键。所以接下来要收敛我教它三种归类方式按业务实体归把user_profile、user_settings、user_avatar收成一个用户实体下的三个字段。这种方式最贴近人的理解适合写进文档。按生命周期归分成会话级关掉就没了、账号级换账号要清、设备级换设备要清。这种方式对排查为什么换了账号还能看到上一个账号的数据特别有用。按写入方归谁写的、谁读的。这种方式能暴露出只写不读的废弃键我在一个项目里靠这个发现了两百多个已经没人读的遗留键。三种方式我都让它跑一遍然后交叉比对。如果某个键在三种归类里都显得孤立那它多半是历史遗留值得标出来让人确认。归类完成之后让它输出一张表列是键/前缀、写入点、读取点、删除点、失效条件。这张表是整个存储流程的核心产出比任何文字描述都有用因为它可以被逐行核对。4.2 缓存与持久化的分歧点故障场景反推法讲存储流程最忌讳的是只讲正常路径。真实系统里存储出问题绝大多数是因为多级存储之间的写入顺序和失败处理不一致。这类问题光看代码很难发现我用的办法是让 Agent 做故障场景反推——给定一个故障反过来推这个系统会表现成什么样。具体操作是给它一个场景清单让它逐个回答如果这里失败用户会看到什么、数据会变成什么状态。下面是我常用的几个场景和实测得到的有价值的结论故障场景需要 Agent 回答的问题常见隐患写入本地成功、写远端失败本地那份会不会被回滚下次同步会不会覆盖远端本地脏数据长期潜伏写远端成功、写本地失败界面是否还显示旧值重启后是否自愈用户看到的数据与实际不符缓存命中但已过期是否存在过期但仍可用的宽限逻辑宽限期多久不同模块宽限策略不一致数据结构版本升级旧版本数据如何迁移迁移失败是否回退升级后老用户数据丢失并发写入同一键谁赢后写的覆盖还是合并关键字段被意外覆盖这套方法的好处是它把读代码变成了验证假设。Agent 有了明确的验证目标检索效率高得多而且结论天然是带条件的——在 A 失败的情况下会 B比系统使用多级缓存这种空话有用一百倍。我特别想强调数据结构版本升级这一项。很多应用的本地数据结构是带版本号的升级时需要迁移。Agent 经常只看到迁移函数存在就下结论支持迁移但真正要确认的是迁移函数在哪个时机被调用、失败时是回退还是清空、迁移过程中用户能不能操作。这三点不问清楚迁移就等于没有。5. 更新流程版本协商、包校验与失败回滚更新链路在三者中协议最明确但也最容易出现文档写的和代码做的不一样。我让 Agent 处理这条链路时刻意加了一条规则凡是文档和代码冲突以代码为准并在报告里标注冲突位置。这条规则在实测中揪出过好几处文档滞后的问题。5.1 触发时机与轮询策略的实际参数先要讲清楚的是什么时候检查更新。常见的有四种触发应用启动、从后台切回前台、定时轮询、用户手动触发。Agent 需要把四种都找出来并给出各自的参数——轮询间隔是多少、有没有退避、失败重试几次、有没有频率上限。这块我让它输出成一张参数表因为参数是最容易被忽略又最影响体验的部分。实测中经常发现的问题有轮询间隔写死在代码里没有走配置导致测试环境和生产环境用同一个值失败重试没有上限网络异常时形成密集请求从后台切回前台的触发没有做去抖短时间多次切换会连发多次检查。去抖这一项我印象很深。代码里只有一个监听看起来很正常但监听回调里直接发起了检查请求没有任何时间窗限制。用户快速切换几次应用就会发出同样数量的请求。这种问题在文档里永远不会写只有真的去看回调实现才能发现。5.2 包校验的完整清单与回滚路径更新包从下载到安装中间有一串校验漏掉任何一环都是安全隐患。我让 Agent 按下面的清单逐项确认每一项都必须给出代码位置找不到就明确标注未发现该校验校验项确认要点缺失后果完整性校验下载完成后是否比对摘要值摘要来源是否可信下载中断的包被当成完整包来源校验是否验证签名公钥如何分发与轮换被替换的包可以安装版本单调性是否拒绝安装低于当前版本的包可被降级到有问题的旧版本兼容性检查是否检查系统版本、架构、可用空间安装中途失败安装结果确认安装后是否校验实际版本号静默失败用户以为已更新降级保护这一项值得单独说。很多实现只检查新版本号是否大于当前版本号但版本号的比较方式本身可能有问题——字符串比较会把1.10判成小于1.9。我让 Agent 专门去确认版本比较函数的实现用几个边界值验证1.9与1.10、1.0.0与1.0、带预发布后缀的版本。这几个用例一问实现是否正确立刻见分晓。至于回滚重点是看安装失败后的状态。理想情况是保留旧版本可执行文件安装失败时能重新启动旧版本差的情况是先删旧再装新中途失败就变成两边都没有。Agent 判断这一点的方法很直接找安装流程里删除旧文件和写入新文件的先后顺序这个顺序基本就决定了回滚能力。6. 让结论可验证报告结构与人工复核清单前面五节讲的都是怎么让 Agent 找到对的信息这一节讲怎么防止它把错的信息说得像对的。我的做法是把输出格式锁死不给它自由发挥的空间。6.1 强制引用格式与置信度标注每一条结论必须包含三样东西结论本身、支撑证据文件路径 行号 一段不超过 10 行的代码、置信度。置信度只允许三档已确认有直接代码证据、推断基于代码但存在未覆盖分支、待确认未找到证据或证据冲突。模板长这样我在提示里写死了格式[结论] 令牌刷新采用排队重放机制刷新期间的新请求不会并发发起。 [证据] src/auth/interceptor.ts:142-158 if (refreshing) { return new Promise(r queue.push(r)); } [置信度] 已确认 [备注] 未覆盖刷新失败分支需确认 queue 中请求的失败处理。这个格式最大的价值不是好看而是逼着模型区分我看到了和我猜的。在没有格式约束的时候它的输出会把这些混在一起读的人根本分不清哪句能信。加了置信度之后我复核的时候只需要看推断和待确认的部分效率差好几倍。我还额外要求它在报告末尾单列一节冲突与疑点把所有文档与代码不一致、多个实现并存、明显废弃但仍在引用的地方列出来。这一节往往是整份报告里最有价值的部分。6.2 幻觉高发场景与交叉验证手段跑多了之后我总结出四类场景 Agent 特别容易编遇到就必须交叉验证同名函数。工具函数叫validate、handle、init的遍地都是。Agent 按名字检索很容易把 A 模块的validate当成 B 模块的。验证方法很简单让它把调用处的导入路径贴出来路径对不上就是找错了。动态派发与反射。有些调用是通过字符串名字动态触发的静态检索根本追不到。Agent 遇到这种情况往往不是承认追不到而是按常见模式脑补一个。所以我要求它在追踪链路中断时必须显式声明中断点而不是自己接上。这一条我写进了系统提示的硬约束里。配置驱动。行为由配置文件决定的代码光看代码会得出错误结论。比如代码里判断如果开启 A 则走 B 路径但 A 的值在环境配置里代码里看不到。解决办法是强制它在遇到配置键时必须调用配置查询工具不允许跳过。跨语言桥接。前端调本地能力、或者跨进程通信的场景链路会断在桥接层。这时候必须两边都追只追一边就会得出这里没有实现的错误结论。至于交叉验证我常用的手段是静态 动态结合。让 Agent 给出结论后我自己跑一次应用抓一次结构化日志对照它说的顺序是不是真的。有一次它说登录成功后才写入凭证实际日志显示凭证在校验通过后、跳转前就写了——顺序上的一步之差在异常场景下的表现完全不同。这种偏差只有跑一次才能发现。7. 实测踩坑记录上下文、终止条件与重复动作前面讲的是方法这一节讲的是我实际跑下来遇到的问题和调过的参数属于文档里一般不会写、但不调就根本跑不顺的部分。7.1 上下文撑爆之后的典型表现第一个坑是上下文。我一开始的设想是让 Agent 一次性把整条链路跑完结果跑到十几步就开始出问题。表现很微妙不是直接报错而是开始重复调用已经调用过的工具读同一个文件前面已经确认的结论后面又给出相反的描述明明已经找到了关键函数却在报告里说未找到相关实现。这三个症状本质是同一个原因早期读到的证据被挤出了有效上下文。我的应对是三条实测有效外部笔记。让 Agent 每完成一个观察点就把结论写进一个结构化的笔记对象后续推理只引用笔记不重新翻原始代码。这个改动让长链路任务的稳定性提升最明显。分段会话。登录、存储、更新三条链路各开一次独立会话每次只带该链路相关的笔记。不要指望一次会话搞定全部那是在跟上下文窗口较劲。提前摘要。每读满 5 个片段就强制做一次一句话摘要。这个看起来是额外开销实际上省下来的上下文远比花掉的多。7.2 终止条件的经验值第二个坑是停不下来。Agent 有时候会陷入再确认一下的循环尤其是遇到调用链追踪返回大量结果的时候。我试过几种终止条件最后用的是组合判断终止条件阈值说明最大步数25 步超过直接强制输出允许标注不完整连续无新增证据2 步连续两步没有产生新的文件或行号引用即停重复动作检测同名工具 同参数出现即中断改为要求它总结当前结论覆盖度达标观察到清单项全覆盖每条链路的观察点全部有结论即停重复动作检测这一项特别有效。模型陷入循环时往往是用完全相同的参数调同一个工具这种模式很容易检测。检测到之后不要直接报错终止而是给它一个总结当前进展的指令让它把已有结论输出通常它一总结就意识到自己已经够了。第三个坑比较隐蔽它在证据不足时倾向于给出合理的默认答案。比如问它凭证是否加密存储如果代码里找不到明确证据它可能会回答通常使用加密存储。这种答案最危险因为读起来完全合理。我的处理是在提示里明确写找不到证据就回答未找到证据并把这个回答视为合格输出不视为失败。明确告诉它不知道是被允许的是降低幻觉率最有效的一招之一。这套东西调下来我最终的用法是把它当成一个读得很快但需要复核的助手而不是能直接交付结论的专家。它负责把几十个文件的读写点、调用链、参数配置在三十分钟内摊开在我面前我负责判断哪些结论站得住。这个分工下效率提升是实打实的——原本要两三天才能理清的链路半天就能出一份带证据的初稿。有几次它给的结论我一开始不信自己翻代码验证结果是对的那种时候确实会觉得这东西值回票价。