REA逆向梳理：用Agent还原登录、存储与更新流程

上个月接手一个交接了三轮的自研客户端项目代码库能跑文档停在两年前登录模块里最醒目的一行注释是“这里别动动了会炸”。这种项目没法靠读文档上手只能靠人肉顺着调用链往上爬。我当时的做法是把整件事拆成三条链路登录怎么进来、数据存在哪、版本怎么更新。三条链路爬完之后我换了个思路——把“我爬”变成“Agent爬”让模型在受控的证据范围内做流程还原和叙述。这套东西我内部叫 REAReverse Engineering Analysis逆向梳理分析只针对自有或已获授权的代码库。这篇文章就把这套方法和踩过的坑完整讲一遍核心目标只有一个让 Agent 把应用的登录、存储与更新流程讲清楚讲到新人照着看就能上手改代码的程度。先明确适用范围避免误导。REA 分析的对象是自己团队维护的代码、自己公司的应用、或者明确拿到授权的代码库用途是补文档、做交接、排查历史遗留逻辑、做重构前的依赖梳理。这套方法不讲任何绕过鉴权、跳过校验的路子所有动态观察都在测试环境和自建调试工具里完成账号是测试白名单账号。这个边界必须先划清楚因为 Agent 一旦被喂进来源不明的材料输出的内容可信度会直接崩掉后面所有推理都是建在沙子上。1. 为什么“让 Agent 讲流程”比“让人读代码”更靠谱1.1 传统交接方式的三个死结做过项目交接的人大概都体会过那种无力感。第一个死结是文档与代码的时序错位文档描述的是两年前的架构代码早就改了三轮谁也不知道哪句话还成立。第二个死结是局部正确、全局断裂每个人都能说清自己负责的那块但登录拿到的令牌怎么传给存储层、存储层的数据结构变更怎么影响更新时的数据迁移这种跨模块的问题通常没人能一句话讲明白。第三个死结是隐性知识不可传递很多逻辑是“当时为了绕开某个问题临时加的”代码里没注释改的人早走了后来者只能靠猜。这三个死结的共同点是它们都不是“缺少信息”而是“信息散落在几十个地方没人做汇总和交叉验证”。人做这件事的成本极高因为人的工作记忆有限看到第 30 个文件的时候第 3 个文件的细节已经模糊了。而这恰恰是 Agent 擅长的部分——它可以同时持有上百个证据片段按统一的契约输出结构化结果而且不会因为加班到晚上十点就漏看一个分支。1.2 REA 的三层结构证据、推理、表达我把 REA 拆成三层这三层必须严格分开混在一起就一定出问题。证据层是纯客观的原材料代码片段、配置文件、字符串常量、测试环境的请求日志、数据库表结构、历史工单描述。这一层的关键要求是“可寻址”——每一条证据都要有唯一编号比如EV-0231能反查回原始文件和行号。推理层是把证据串成因果链从 A 证据能推出 B 结论这条推理必须有明确的依据和置信度。比如“登录成功后令牌写入了本地键值存储”这个结论依据是某处写入调用的证据置信度高而“令牌在两小时后过期”如果只看到常量定义没看到实际使用置信度就只能标中。表达层是最终给人看的东西流程图、时序表、状态机、注意事项清单。表达层的质量标准是“可验收”——新人拿着这份东西能不能在不问人的情况下完成一次登录链路的修改。三层分开的好处是当 Agent 说错话时你能立刻定位是证据没采到、还是推理跑偏了、还是表达时把置信度抹平了。我见过太多人直接把一堆代码丢给模型说“帮我分析一下”然后拿到一段似是而非的总结问题就出在没分层——你没法判断它哪句话是有据的、哪句话是脑补的。1.3 登录、存储、更新为什么必须一起讲单独讲登录你会得到一个“输入账号密码、调接口、拿到令牌、存起来”的流程图看起来挺完整。但它回答不了三个关键问题令牌存在哪、存的方式安不安全、更新版本之后这个存储位置还在不在。单独讲存储你会得到一个“用了哪几种存储介质、分别存了什么”的清单但它回答不了“谁写的、什么时候写的、什么时候清”这些生命周期问题。单独讲更新你会得到一个“检查版本、下载、安装”的流程但它回答不了“更新过程中用户登录态会不会丢、本地缓存要不要迁移”这些真正会引发线上问题的地方。这三条链路的交汇点其实是同一个东西用户身份的持久化表示。登录产生它存储承载它更新有可能破坏它。我在一次真实排查里就遇到过新版本把本地存储的命名空间改了登录态读不到用户每次冷启动都要重新登录而这个问题的根因藏在更新流程的迁移逻辑里只看登录模块永远找不到。所以 REA 分析必须三条链路并行推进在交汇处做交叉验证。2. 把 Agent 变成“流程解说员”的整体设计2.1 证据池怎么建三路采集与统一编号证据池是整个 REA 的地基。我的做法是三路并行采集最后统一编号入库。静态路对代码库做索引抽取函数定义、调用关系、常量、字符串资源、配置文件、依赖清单。这一步不需要 Agent 参与用脚本跑就行产出是结构化的 JSON。关键是保留文件路径和行号后面所有引用都要能反查。动态路在测试环境跑一遍完整流程采集请求日志、本地存储快照、运行日志。这里要注意的是动态采集只能覆盖实际走到的分支遗漏的分支必须靠静态证据补。文档路把需求文档、接口文档、历史工单、代码评审记录全部拉进来做成分块索引。这一路的证据置信度最低因为它可能过时但它的价值在于提供“意图”——代码为什么这么写往往只有文档能解释。三路采集完之后统一编号格式我建议用EV-来源码-序号来源码用 S/D/K 区分静态、动态、文档。这样在最终输出里看到EV-S-0417就知道这是一条静态代码证据可以要求 Agent 给出原文。证据池的规模要控制。我的经验是单个分析任务的证据池控制在 800 到 1500 条之间比较合适。太少覆盖不全太多会导致检索精度下降。如果项目很大就按链路切分成子池登录一个池、存储一个池、更新一个池交汇处的证据复制一份到两个池里。2.2 三个角色分工侦察、推理、校对我不用单个 Agent 从头干到尾而是拆成三个角色每个角色职责单一。侦察 Agent只干一件事找入口和证据。它的任务是回答“这条链路从哪开始、经过哪些关键节点、每个节点的证据在哪”。它不做推理只输出证据卡片节点名称、所在位置、证据编号、一句话客观描述。推理 Agent接收侦察 Agent 的证据卡片负责串因果链。它的输出是流程卡每一步的触发条件、输入、动作、输出、证据编号、置信度。它是整个流程里最容易出错的一环因为模型天然倾向于把不完整的证据补全成完整的故事所以必须用强约束的提示词压住。校对 Agent的任务是找反例。给定推理 Agent 的输出它去证据池里找“有没有哪条证据和这个结论矛盾”或者“这条流程有没有遗漏的分支”。这个角色非常重要我实测下来它能捞回大约两成的错误尤其是那种“看起来合理但其实代码里有 if 判断没覆盖到”的情况。三个角色的产出要串行流转不能并行。侦察先跑完推理才有输入推理跑完校对才有靶子。整个流程跑一轮大概需要半小时到一小时取决于项目规模和证据池的检索效率。2.3 提示词结构把“讲清楚”拆成可验收的检查项“讲清楚”是个很虚的要求模型没法执行。我把它拆成五个可验收的检查项写进提示词。第一项是节点可枚举流程必须拆成离散的步骤每步有编号不允许出现“系统完成认证”这种笼统描述。第二项是条件可判定每步的触发条件必须是能写成布尔表达式的比如“请求返回码为 200 且响应体包含 token 字段”不允许写“正常情况下”。第三项是证据可追溯每个结论后面必须挂证据编号没挂证据的结论一律视为假设要标注“待验证”。第四项是失败可枚举每一步必须列出至少两种失败路径和对应的处理逻辑。这一条是所有人在写文档时最容易漏的但它恰恰是排查线上问题最需要的。第五项是置信度可标注每条结论标高、中、低三档。高的标准是“直接证据且被交叉验证过”中的标准是“直接证据但仅为单点”低的标准是“间接推理”。提示词里还要写死禁止事项不许猜测未出现在证据池里的常量值不许把文档描述当成代码事实不许省略失败分支。这几条禁令我吃过亏——早期版本跑出来的流程卡特别漂亮但里面有好几个常量值是按“行业惯例”编的实际代码里根本不是那个数。2.4 输出契约三种视图配合使用最终交付我用三种视图缺一不可。流程卡是纵向的按步骤编号排列适合当操作手册看。表格字段固定为步号、节点名、触发条件、输入、动作、输出、失败处理、证据编号、置信度。时序表是横向的按交互双方排列适合看“谁先谁后”。字段是时间序号、发起方、接收方、消息内容、同步/异步、超时时间。状态机是看全局的适合理解“系统一共有几种状态、怎么迁移”。字段是当前状态、触发事件、目标状态、副作用、是否可逆。这三种视图配合起来基本上能把一条链路的“怎么做、什么顺序、什么状态”讲全。我通常还会额外输出一份“改动影响面评估”列出如果改动某个节点哪些地方会受影响——这份东西在做重构的时候特别有价值。3. 登录流程从入口到会话落地的完整还原3.1 登录链路的六个观察点登录看起来简单实际上是最容易藏分支的地方。我总结出六个必须逐一确认的观察点任何一处没确认清楚这条链路就不算讲明白了。第一入口有几个。除了登录页的登录按钮通常还有深链唤起、第三方回调、静默登录、扫码确认这几条。入口不同前置校验和后续跳转都不一样。侦察 Agent 在这一步要做的是把所有可能触发登录的调用点全部列出来这是一个逆向查询不是从入口往下找而是先找到所有“发起登录”的调用再往上找谁调用了它。第二前置校验有哪些。版本号拦截、设备环境校验、网络类型判断、隐私协议勾选这些通常在真正提交凭证之前跑。这部分最容易漏因为它往往不是阻塞式的而是“不满足条件就静默降级”代码里可能就一行 if 判断。第三凭证提交走什么形态。账号密码、短信验证码、第三方授权这几条分支的处理逻辑差异很大尤其是第三方授权涉及本地回跳和数据合并是重灾区。第四响应里到底有什么。不要只看代码里取用了哪几个字段要把响应体的完整结构记下来因为很多字段是“当前没用但未来会用到”的不知道它的存在就会在后面的分析里产生困惑。第五令牌怎么落地。存放位置、是否加密、有效期、刷新策略这四点必须全部明确。我见过的最坑的情况是令牌存在两个地方一个是内存缓存、一个是持久化存储两者刷新时机不一致导致偶发的鉴权失败。第六登出清理范围。清理了哪些键、哪些缓存、哪些内存状态有没有清理第三方 SDK 的状态。这一块漏清理导致的残留问题是最难排查的一类线上问题。3.2 令牌生命周期建模一张表说清令牌这块我建议单独建一张生命周期表把“从产生到销毁”整个过程摊开。字段设计如下阶段触发条件处理动作数据落点失效条件证据编号签发凭证校验通过下发访问令牌与刷新令牌响应体无EV-D-0112落地响应解析成功写入内存缓存与持久化存储内存 本地存储进程结束内存/ 覆盖写持久化EV-S-0233使用业务请求发起附加到请求头不落盘请求完成EV-S-0241续期访问令牌临近过期用刷新令牌换新覆盖旧值刷新令牌失效EV-S-0258失效收到鉴权失败响应清理本地并跳转登录全清重新登录成功EV-S-0270这张表的价值在于它把“时间”这个维度显式化了。很多 bug 是时序问题——比如刷新令牌的请求还没回来业务请求已经带着旧令牌发出去了。有了这张表你就能一眼看出哪些操作是并发的、哪些是有序的。续期窗口这个参数值得单独说一下。常见做法是给访问令牌设一个较短的有效期然后提前一段固定时间刷新。这个提前量怎么定我的经验值是访问令牌有效期的三分之一到二分之一同时要大于单次请求的最坏耗时。举个例子访问令牌有效期 30 分钟最坏请求耗时 10 秒那提前量设在 10 到 15 分钟比较稳妥如果设得太小比如只提前 1 分钟那并发请求同时触发刷新很容易把刷新接口打爆。这个计算过程我在文档里会明确写出来因为后来改代码的人如果不知道这个约束随手调小提前量就会出问题。3.3 存储介质与加密边界登录态存在哪这件事必须画成一张“介质地图”。常见的有几层内存缓存、进程级偏好存储、数据库、文件缓存。每一层都要回答三个问题存了什么、什么时候写、什么时候读。内存缓存的特点是快但易失进程被杀就没了偏好存储适合小体积键值但并发写入要小心数据库适合结构化数据但要注意事务边界文件缓存适合大块内容但要注意清理策略。加密边界是另一个必须讲清楚的点。哪些字段是加密存的、密钥从哪来、密钥会不会随版本变更——这三个问题不搞清楚后面做数据迁移就是灾难。我在一个项目里见过本地存储的加密密钥是硬编码在代码里的后来要做密钥轮换发现历史数据全解不开只能强制用户重新登录。这种问题在文档里如果不写清楚下一个接手的人会重蹈覆辙。让 Agent 生成这张地图的时候我是这么给指令的从所有写入本地存储的调用点出发反向聚合出“键名 → 数据类型 → 写入方 → 读取方 → 生命周期”这五列然后按存储介质分组输出。这个指令的关键是“从写入点出发”因为很多存储介质在代码里是以封装类形式出现的直接搜存储类名会漏掉那些通过封装写作的地方。3.4 三个高频坑多入口、静默登录、并发刷新第一个坑是多入口状态不一致。不同入口进来登录成功后的落地页和数据初始化范围不一样如果统一处理很容易出现“从深链进来的人没有初始化某些数据”的问题。REA 分析时要专门把每个入口的后续路径单独走一遍输出一张“入口 × 落地页 × 初始化项”的矩阵。第二个坑是静默登录的判断条件。很多应用会在启动时尝试用已有令牌做静默登录失败就转正常登录页。这里的判断条件往往写得很绕涉及令牌是否存在、是否过期、上次登录是否成功等多个标志位的组合。Agent 分析这部分时我要求它把判断逻辑翻译成真值表把每个标志位的取值组合列出来这样哪个分支覆盖不到一眼就能看出来。第三个坑是并发刷新。多个请求同时发现令牌过期同时发起刷新这是很常见的竞态。正确的做法是加一个刷新中的标志位后来的请求等待第一次刷新的结果。这个问题在代码里往往体现为一个锁或者一个状态变量容易被忽略。分析时我要求 Agent 专门去找“是否存在并发保护的证据”找不到就标为风险点。4. 存储流程本地数据的读写地图怎么画4.1 存储分层与职责边界本地存储最怕的是“什么都往里塞”。我在做 REA 分析的时候第一件事就是把存储分成四层然后看每层实际承担了什么职责。偏好层小体积键值对存配置、标志位、登录态摘要。特点是读写频繁、并发敏感。这一层最容易失控因为写入太方便久而久之什么数据都往里塞最后没人知道某个键是谁写的。结构层数据库存业务实体。特点是结构清晰、有事务。这一层的关键是表结构变更的管理尤其是更新流程涉及迁移时的兼容处理。缓存层文件和内存缓存存可重新获取的数据。关键是明确“这份数据丢了能不能重建”凡是不能重建的就不该放这一层。临时层会话级的临时数据进程结束即清。关键是明确清理时机避免占着不放。分层之后要回答一个核心问题同一份数据会不会出现在多层。如果会那就有同步问题必须明确“哪一层是权威源”。这个判断在文档里必须写出来否则后来者不知道该读哪一层。4.2 让 Agent 生成读写矩阵读写矩阵是存储分析的核心产出格式是一张表数据项存储介质键名/表名写入方读取方写入时机清理时机是否敏感登录令牌偏好存储auth_token登录模块网络拦截器登录成功登出/鉴权失败是用户配置偏好存储user_prefs设置页全局用户修改登出否消息列表数据库msg_table同步模块列表页收到推送/主动拉取账号切换否图片缓存文件缓存/cache/img图片加载器图片加载器加载成功超过上限/登出否这张表的生成指令我是这么写的以“写入”为起点逐个调用点向上追溯调用方向下追溯读取方对每一行都必须给出写入方和读取方任一侧找不到就标“未发现读取方”作为风险提示。这个指令里的“任一侧找不到就标风险”很关键因为孤儿数据只写不读和幽灵数据只读不写都是典型的代码腐化信号。实测下来一个中等规模的应用大概能扫出 60 到 120 个数据项其中大约 10% 到 15% 会被标为可疑。这些可疑项值得人工复核往往能捞出历史遗留的无效键或者已经废弃的功能残留。4.3 数据迁移与版本兼容存储这块最容易被低估的是迁移。每次版本更新只要存储结构变了就得有迁移逻辑而迁移逻辑的代码往往是“一次性”的写完再也没人看。REA 分析在迁移这块要输出三样东西。第一是迁移链条从版本 A 到版本 B 到版本 C每一跳做了什么转换。这条链必须完整中间断了一环就可能导致老用户升级失败。第二是幂等性判断迁移逻辑重复执行会不会出问题。理想情况下应该是幂等的但实际代码里经常不是需要明确标注。第三是回滚方案迁移失败怎么办是重试、跳过还是降级。这三个问题让 Agent 去分析时我给的指令是先找到所有涉及存储结构变更的版本记录然后对每一对相邻版本找出迁移代码再判断幂等性。幂等性判断这一步比较难自动化我的做法是让 Agent 输出“迁移逻辑是否包含前置状态检查”这个信号有前置检查的大概率幂等没有的就需要人工看。4.4 敏感数据的合规边界这一块必须单独强调。本地存储里凡是涉及用户身份、联系方式、位置、行为轨迹的字段都要在矩阵里标成敏感并且明确三件事是否加密、密钥如何管理、保留多久。我要求 Agent 在生成读写矩阵时对“是否敏感”这一列不能靠模型判断必须依据一张预定义的分类清单去匹配。原因是模型对敏感性的判断很不稳定同一个字段两次跑可能给出不同答案。用固定清单匹配结果就是确定的。另外清理时机这一列对敏感数据尤为重要。登出时该清的必须清干净包括缓存里的副本、临时文件、内存中的引用。我见过登出后缓存里还留着上一个账号的头像和昵称的情况这就是清理范围没覆盖到。5. 更新流程版本收敛、灰度与生效时机5.1 更新链路的三段式拆解更新流程我习惯拆成三段检查、获取、生效。每一段的失败模式完全不同必须分开讲。检查段的核心是版本比较逻辑。这里有个常被忽略的细节版本号的比较不能简单按字符串比必须按段解析成数字再比。举个典型的坑1.10.0和1.9.0按字符串比1.10排在1.9前面但按语义版本它应该是更新的。让 Agent 分析这部分时我要求它把版本比较函数完整还原出来包括每一段的处理逻辑和异常输入的兜底。获取段的核心是完整性和可恢复性。下载中断了能不能续、下载完了怎么校验、校验失败了怎么重试这三点必须明确。校验一般用摘要比对摘要值的来源必须在文档里写清楚否则后来者不知道去哪更新这个值。生效段的核心是时机。冷启动生效、立即生效、下次启动生效三种策略的用户体验和风险完全不同。冷启动生效最安全但用户感知差立即生效体验好但可能打断正在进行的操作。文档里必须写清楚选了哪种、为什么选这种。5.2 灰度与回滚的判定条件灰度这块REA 分析要回答的是“谁能拿到新版本”。判定维度通常有版本区间、渠道、地域、用户分组、设备特征。这些条件的组合逻辑必须还原清楚因为这是最容易出问题的地方——组合条件写错了可能导致某个用户群体永远收不到更新。我让 Agent 输出一张判定表把每个维度的取值和对应的结果列出来然后用真值表的方式检查有没有遗漏的组合。这个检查很重要因为条件判断的代码里经常有else兜底分支被漏掉。回滚的判定条件同样要还原。什么情况下触发回滚、回滚到哪个版本、回滚时本地数据怎么处理这三个问题必须明确。尤其是第三个回滚到旧版本旧版本不认识新版本写的存储结构这时候要么做向下兼容要么清空数据两种方案的影响完全不同。5.3 更新与登录态、存储的耦合点这是三条链路的交汇处也是最容易出线上问题的地方。我总结出三个必须检查的耦合点。耦合点一更新后登录态是否保留。取决于登录态存在哪、存储命名空间有没有变、加密密钥有没有变。这三个变量任何一个变了登录态就可能失效。分析方法是对比更新前后的存储配置逐项检查命名空间、密钥来源、序列化格式。耦合点二更新过程中的数据迁移是否影响登录。迁移逻辑如果在登录之前跑且迁移失败会阻塞启动那用户就卡在启动页了。分析时要确认迁移的失败处理策略是跳过、重试还是阻断。耦合点三热更新与冷更新的边界。热更新通常只能改一部分逻辑涉及存储结构变更的部分一般不能热更。这条边界必须明确写出来否则容易出现“热更之后数据写坏了”的问题。5.4 版本比较与灰度的参数计算实例举个具体的计算例子帮助理解版本比较这块的细节。假设当前版本是2.7.3服务端下发的最低支持版本是2.6.0最新版本是2.9.1。三段式比较的逻辑是主版本号相同则比次版本号次版本号相同则比修订号。逐段解析成整数比较2 27 6所以当前版本高于最低支持版本允许继续使用7 9所以当前版本低于最新版本提示更新。如果版本号里带预发布标记比如2.9.1-beta.2比较规则要额外定义预发布版本永远小于同号的正式版本预发布之间按标识符逐段比。这块逻辑如果不写清楚灰度发布的时候就容易出现“灰度用户收不到正式版”的问题。灰度比例这块常见的做法是按用户标识做哈希取模。假设灰度 10%哈希值范围 0 到 99取模后小于 10 的进灰度。这个方案的关键是哈希函数必须稳定同一个用户每次算出来结果一样否则用户会在灰度和非灰度之间反复横跳体验很差。这个稳定性要求在文档里必须写明我见过有项目用随机数做灰度判断结果用户每次启动看到的版本都不一样。6. 一次完整 REA 分析的实操记录6.1 准备阶段划定范围与清洗证据项目是一个中等规模的自研客户端代码量大概十几万行涉及登录、本地存储、版本更新三块。准备工作花了大半天主要是三件事。第一件是划定分析范围。我没有把整个代码库丢进去而是先按模块圈定范围认证相关模块、存储封装层、更新模块、以及它们的直接依赖。圈完之后大概是全部代码的三成这个比例比较合理既能覆盖完整链路又不至于让证据池爆炸。第二件是建立证据编号体系。静态证据用EV-S-动态证据用EV-D-文档证据用EV-K-。编号由脚本自动生成生成规则是文件路径哈希加行号保证唯一性和可反查性。第三件是准备提示词模板。三个角色各一套模板每套模板里固定包含角色定义、任务描述、证据范围说明、输出契约、禁止事项、置信度标注规则。模板不追求精简反而要写得很啰嗦把所有边界条件都堵死。这里有个细节值得说我在提示词里明确写了“如果证据不足以支撑某个结论输出INSUFFICIENT不要用常识补全”。这句话的效果非常明显加上之前模型输出的完整度大概有九成但错误率很高加上之后完整度降到七成左右错误率降了一大截。剩下那三成缺口由人工补比事后纠错省事得多。6.2 采集与建池静态索引加动态快照静态索引用脚本跑输出三类文件符号表函数、类、常量的定义位置、调用图谁调用谁、字符串资源表所有硬编码的字符串和它的位置。这三类文件加起来大概几万条记录按模块切片后入池。动态快照这块要格外小心。我在测试环境用测试账号跑了一遍完整流程冷启动、登录、浏览、切后台、杀进程、重启、检查更新、登出。每一步都记录了请求日志和本地存储快照。这里的关键是快照要带时间戳和步骤标记否则后面分析的时候分不清哪个快照对应哪个阶段。跑完之后我发现一个有意思的现象登录成功后本地存储里多出来三个键但代码里只看到两处写入调用。第三处是通过一个通用封装类写的搜具体的键名搜不到。这就是为什么我强调“从写入点出发”而不是“从键名出发”——键名往往是运行时拼出来的静态搜不到。文档这块我把能找到的需求文档和工单都拉了进来但只作为辅助证据置信度标为最低。实际分析中确实用上了有一处逻辑代码里看着莫名其妙翻到两年前的一个工单才明白是为了兼容某个旧版本的数据格式。6.3 推理与生成三轮迭代到可用第一轮跑侦察 Agent输出了一份节点清单登录链路 14 个节点存储 9 个节点更新 11 个节点。这份清单本身价值不大但它是后面推理的骨架。第二轮跑推理 Agent把节点清单和对应的证据卡片一起喂进去输出流程卡。第一版流程卡问题很多失败分支基本没覆盖置信度全部标成高有几个常量值是编的。我做了两件事修正一是把禁止事项再强化一遍明确写出“每个节点至少列出两种失败路径”二是加了一步预检查让模型先输出“这个节点有哪些证据”再输出“基于这些证据能得出什么结论”两步分开编造的概率明显降低。第三轮跑校对 Agent专门找反例。它捞出了几个问题一个是有个判断分支在流程卡里被合并了实际代码里是两个独立分支另一个是登出清理范围的描述漏了两个键。校对 Agent 的价值在这轮体现得最明显如果没有它这两个问题会一直留在文档里。三轮下来总共花了大概四十分钟产出的流程卡加上人工补充的注释基本上达到了“新人能照着改代码”的程度。6.4 交叉验证与文档落地最后一步是交叉验证我用了三个方法。方法一反向走查。拿着流程卡从终点往起点倒推看每一步的输入是不是上一步的输出。这个方法能抓出“断链”——流程卡里看起来连贯实际中间少了一步。方法二代码抽样核对。随机抽 20% 的流程卡条目去代码里逐行核对。这个比例是我试出来的低于 15% 漏检率明显上升高于 30% 边际收益很小。方法三场景验证。设计几个典型场景——首次登录、令牌过期后自动续期、更新后首次启动、登出再登录——按流程卡走一遍看能不能对上实际行为。这个方法最费时间但最能发现问题我这次跑下来发现了两个流程卡没覆盖的边界情况。文档落地我用的是一份主文档加三张附表的结构。主文档是三条链路的流程卡和时序表附表分别是读写矩阵、版本迁移链条、风险点清单。风险点清单是这次分析额外的收获把所有置信度低或者证据缺失的地方汇总起来作为后续补文档的待办。7. 常见问题与排查技巧实录7.1 Agent 输出失真的四种典型形态跑这套流程时间长了能总结出模型出错的几种固定模式识别出来就能针对性地防。形态一故事化补全。证据只有 A 和 C模型自动脑补出 B让整个流程看起来连贯。识别方法是检查每个结论的证据编号凡是没挂编号或者编号对不上的一律标为可疑。防的办法是强化“证据不足输出 INSUFFICIENT”的指令并且在输出契约里强制要求每个节点必须挂至少一个证据编号。形态二置信度均质化。所有结论都标成高置信度失去了区分的意义。识别方法是看置信度分布如果高于九成都是高那基本可以判定模型没认真判断。防的办法是在提示词里给出明确的判定标准并且要求模型对每条结论说明“为什么是这个置信度”。形态三失败分支缺失。只讲成功路径不讲失败路径。这是最常见的因为训练数据里的文档大多只写成功路径。防的办法是把“每个节点至少两种失败路径”写成硬性要求并且在验收时逐个检查。形态四常量值幻觉。编造常量值比如把超时时间写成“常见值 30 秒”而实际代码里是 15 秒。识别方法是所有常量都必须挂证据编号没挂的一律不信。防的办法是在提示词里明确禁止“用行业惯例补全常量”。7.2 证据不足时的降级策略不是所有地方都能采到足够证据这时候要有降级策略不能硬编。降级一标为待验证。证据只有间接线索时输出结论但明确标注“待验证”并在风险清单里登记。这类条目后续由人工补。降级二输出开放问题。完全没证据的地方不要输出结论而是输出一个具体的问题比如“登录成功后是否有第三处写入调用未找到证据需人工确认”。这个形态比空白有用因为它给人工排查指明了方向。降级三范围收缩。如果某个子链路证据严重不足就把这个子链路从本次分析范围里摘出去明确写在文档里“本次未覆盖”而不是给一个半成品。半成品的危害比空白大因为后来者会误以为已经分析过了。7.3 常见问题速查表现象可能原因排查方向处理建议流程卡出现无证据结论模型故事化补全检查证据编号是否齐全强化禁止指令逐条核对编号置信度全部为高判定标准不明确查看置信度分布提示词中给出三档判定标准失败分支缺失训练数据偏向成功路径逐个节点检查失败路径数量硬性要求每个节点至少两条常量值与代码不符用常识补全抽查常量是否挂证据禁止无证据常量强制标注存储键名搜不到键名运行时拼接从写入调用点反向找改为从写入点出发检索登录态更新后丢失存储命名空间或密钥变更对比更新前后存储配置检查迁移逻辑是否覆盖该键并发刷新打爆接口缺少刷新中的互斥保护查是否有状态标志位增加刷新锁后到请求等待灰度用户版本回退灰度哈希不稳定检查哈希函数是否含随机因子改为基于用户标识的稳定哈希迁移逻辑重复执行出错缺少幂等前置检查查迁移前是否有状态判断补前置状态检查保证幂等孤儿数据堆积只写不读的历史遗留读写矩阵中找单边项确认无用后清理并记录7.4 几条不上文档的经验第一条证据池宁可小一点不要大而全。我早期试过把整个代码库塞进去结果检索精度极差模型经常引用不相关的证据。后来的做法是按链路切分每条链路一个池池内证据控制在千条以内效果明显好很多。第二条校对 Agent 不能省。很多人觉得三个角色太麻烦想用一个大模型从头干到尾。实测下来省掉校对这一步错误率大概翻倍。校对不需要多强的模型它的任务很简单就是找矛盾用同一个模型换个提示词就能干。第三条人工复核的比例不要低于两成。完全信任 Agent 的输出是会出事的尤其是存储和更新这两块涉及数据安全的判断必须人工过一遍。我现在的习惯是登录链路抽 15%、存储链路抽 30%、更新链路抽 25%按风险高低分配。第四条分析结果要跟着代码一起版本管理。文档放在文档系统里代码改了文档不会改半年后又变成过时文档。我的做法是把流程卡和读写矩阵以结构化格式放在代码库里代码评审时如果改动了相关模块要求同步更新对应的流程卡条目。这个约定执行起来有点麻烦但比事后重新分析一遍省事得多。第五条先跑通一条链路再铺开。三条链路一起上看起来很高效实际上调试成本很高出了问题分不清是哪个环节的错。我建议先拿存储链路练手它的边界清晰、失败模式少跑通之后再上登录和更新。这套方法我前后用了大概半年覆盖了四个项目最大的收获不是省了多少时间而是把“靠人记忆维持的隐性知识”变成了“可检查的结构化文档”。Agent 在这件事里的角色说白了就是一个不知疲倦、但需要严格约束的整理员——它不会替你做判断但它能把你需要判断的材料全部摆到桌面上而且摆得整整齐齐。真正决定文档质量的还是你给它的约束有多严、验收有多细。