REA工作模式：让Agent读懂代码仓库并讲清登录存储更新流程

1. 先想清楚REA 要解决的是答得对不是答得像REA 这个名字是我自己起的三个字母对应Reason、Explore、Act——推理、探索、行动一个循环里反复走这三步。它本质上是把 ReAct 那套边想边查的范式做了一次工程收敛推理负责拆问题探索负责找证据行动负责把证据读进来。这套方法落到应用代码理解这个场景上就变成了一件事让 Agent 面对一个陌生的代码仓库能把登录怎么走、数据存到哪、版本怎么更新这三条链路讲清楚而且每一句都能落到具体的文件和行号上。为什么挑这三条流程因为它们是绝大多数应用里跨层最多、隐式约定最多、文档最容易过期的部分。登录牵涉路由入口、凭证获取、令牌存放、刷新与失效、权限校验横跨前后端存储牵涉内存缓存、本地持久化、服务端持久层三层写在哪、读在哪、什么时候失效经常只有代码自己知道更新流程更麻烦Web 端、移动端、服务端三套逻辑完全不同光更新两个字就能让 Agent 答偏。我试过直接拿一段裸问题丢给通用模型问这个应用的登录流程是怎样的它给出的回答通顺、结构漂亮、每一段都有小标题但一半以上是行业通用套路不是这个仓库里的真实实现。这种东西拿去做新人上手文档比没有更危险。所以这篇文章适合谁适合手上有一堆历史项目、要接手别人代码的同学适合在团队里做知识沉淀、想让 AI 帮忙写架构说明的同学也适合已经在搭 Agent、但发现检索一堆文件塞进上下文效果很差、想搞明白问题出在哪的同学。文中的实操部分我会给出可以直接抄的代码骨架和提示词结构基础薄弱的读者照着改参数也能跑有经验的读者可以直接跳到第 4 节的编排细节。需要先声明一点REA 不是什么现成框架也不是某家平台的私有方案它是一套可以自己在几十行到几百行代码里搭出来的工作模式。文中涉及的模型调用、向量检索、语法解析这些环节我都用通用接口描述你换成自己团队在用的那套服务即可思路完全一致。1.1 三个问题背后的真实业务场景把这三条流程放在一起看会发现它们共享一个特征答案藏在代码的连接处而不在代码的主体里。登录流程的关键不在登录页那个表单组件而在路由守卫、请求拦截器、令牌刷新这几处横切逻辑存储流程的关键不在数据模型定义而在谁调用了写入方法、谁在什么时机清了缓存更新流程的关键不在版本号常量而在构建脚本、发布清单、迁移脚本的执行顺序。我在一个中型项目上做过统计问登录流程接入点最密集的文件分布在前端的请求封装层和后端的鉴权中间件加起来不到八个文件但这八个文件分散在三个不同目录文件名里没有一个是login。这就是普通检索的失效点——关键词搜索 login 只能捞到表单和接口定义捞不到拦截器。Agent 必须具备顺着调用关系往外走的能力这正是 Explore 这一步存在的理由。另一层是词义消歧。举一个我踩过的坑某次问更新流程Agent 一头扎进客户端的版本检查逻辑给了一份完整的应用商店更新说明但实际项目里更关键的是服务端的数据库迁移脚本执行顺序因为那才是真正的风险点。它没错但答的不是我问的。后来我在提示词里强制加了第一步先判断问题涉及哪一层列出可能的解释选一个并说明理由答偏的概率直接降了一大截。1.2 裸模型为什么必然翻车翻车有三个典型模式值得挨个拆。第一个是路径幻觉。让模型凭记忆说登录逻辑在src/auth/login.ts它会给你一个语法完全合理、命名符合直觉、但根本不存在的路径。这不是模型不聪明是它在做概率补全而真实仓库的文件名往往反直觉——真实项目里可能是src/views/entry/index.tsx里套了一个useSession。解决办法很土但有效所有路径必须来自工具返回禁止模型自己拼。这条规则写进系统提示效果立竿见影。第二个是上下文稀释。一个文件八百行全塞进去模型对中间那几十行的注意力会被摊薄。我做过对比同一个鉴权中间件整文件输入和只给关键一百二十行后者在令牌过期后走哪条分支这个问题上的正确率明显更高。所以读文件必须带行区间一次不超过两百行这是个硬约束。第三个是证据链断裂。模型说令牌存在本地存储里但它看的是写入的那一行没有看读取的那一行也没有看失效清理的那一行。真实情况可能是写入用了一个封装过的方法读取走了另一条路径清理在拦截器里。三处不一致才是这个仓库真正的知识。所以我要求 Agent 对每个结论至少给出两处证据一处写入、一处读取或消费。1.3 我最后的取舍探索优先推理兜底搭这类 Agent 有两种思路。一种是把整个仓库向量化问题进来直接检索片段一次调用出答案快但浅另一种是给模型工具让它自己决定查什么慢但深。我选的是后者但不是纯后者。纯工具调用的问题是不稳定同一个问题问两次走的路径可能完全不同有时候绕了十轮还没摸到主链路。我的做法是给它一张粗糙的地图索引阶段先跑一遍轻量静态分析产出一份目录摘要、符号表、配置清单、最近的提交摘要把这些压缩成两三千字的仓库速览放进系统提示。模型拿到速览之后再决定往哪钻路径选择就稳多了。这个取舍的核心逻辑是检索决定下限推理决定上限。检索把模型拉进真实代码推理负责把散落的证据串成流程。两个都不能省但优先保证检索的可靠性因为推理再强也救不回一份错的证据。2. REA 的整体架构与工具选型整套东西我拆成三层索引层、工具层、编排层。分层不是为了好看是为了让每一层都能单独测。索引层出错表现是所有问题都答偏工具层出错表现是模型反复重试编排层出错表现是烧了一堆 token 却什么都没查。分开测定位问题能省掉大量时间。2.1 索引层不追求全追求找得到入口索引层我做了六件事按重要性排序文件清单与语言识别遍历仓库排除依赖目录、构建产物、二进制资源。这一步能砍掉 60% 以上的噪音文件。文本倒排索引关键词到文件:行号的映射支持正则。这是最朴素也最管用的东西比向量检索在代码场景下更可控。符号表用语法解析提取函数、类、方法的定义位置。注意只要定义位置不做类型推导够用就行。调用关系近似基于符号名的文本匹配建立谁调用了谁允许误报不允许漏报。配置清单标记把构建配置、依赖清单、环境变量示例、数据库迁移目录单独标出来这些文件在流程问题里出现频率极高。提交摘要取最近两三百条提交的标题和前几个改动文件压缩成短列表。更新流程这类问题光看代码经常串不起来得靠提交信息补上下文。这里有个关键取舍不做全量向量化。原因很实际代码片段的向量相似度经常被注释和命名风格带偏两个功能毫不相干的函数只要注释写得像向量距离就很近。而且向量检索给不出行号边界返回的是模糊片段对证据必须精确到行这个要求是硬伤。我的做法是文本检索为主向量检索只在找语义相近的实现这种模糊场景下作为补充并且明确告诉模型这是模糊结果。符号表这块也有坑。有些语言的语法解析器对动态特性支持一般遇到装饰器包装、元类、宏展开符号位置会偏。我的处理是解析失败就回退到正则宁可粗糙也别丢。实测下来正则兜底能把符号召回率补回来不少。2.2 工具层五个工具少而狠工具给多了模型会挑花眼这是我在别的项目上验证过的教训。给到十几个工具之后模型经常在该用哪个上纠结或者连续调用三个功能重叠的工具做重复劳动。最后我压到五个工具名作用关键参数设计要点list_tree看目录结构路径、深度限制深度避免一次吐出上千条search_text全文正则搜索表达式、文件范围、上限必须返回行号和命中行内容read_slice按行区间读文件路径、起止行强制带行号返回单次上限两百行trace_symbol查定义与调用方符号名、方向双向既能找定义也能找调用者git_pick查提交记录关键词或路径、条数返回标题、哈希前七位、改动文件五个工具里search_text是使用频率最高的占我统计里六成以上的调用。所以它的返回质量决定一切。我的做法是每次最多返回三十条命中每条带文件路径、行号、该行原文外加前后各一行的上下文。三十条这个数字是调出来的太少会漏太多模型看不过来还会占掉本该留给read_slice的预算。trace_symbol是这套方案跟普通检索的分水岭。它让 Agent 能从一个具体函数往上追调用方往下追实现。登录流程能串起来靠的就是这个——从接口定义往上追到路由注册往下追到鉴权中间件再横向追到令牌工具类。注意trace_symbol的结果一定要标注置信度。基于文本匹配的调用关系遇到同名方法、反射调用、依赖注入会给出假阳性。我在工具返回值里加了一个hint字段写明基于名称匹配可能存在同名干扰模型看到这个提示后会主动去read_slice验证误判率明显下降。2.3 上下文预算留白比塞满更重要这一块是很多人忽略的地方。我的分配是系统提示与仓库速览占三成证据工具返回内容占五成推理历史占一成半剩下半成留白。为什么留白因为模型的输出也需要空间而且在多轮循环里如果历史对话把窗口占满最后一轮的推理质量会明显下滑——它没地方想了。我吃过这个亏早期版本经常在第七八轮突然给出一个含糊的结论后来加了预算控制情况好转很多。压缩策略是摘要式淘汰。工具返回的原始内容在保留一轮之后折叠成一行摘要格式是读过path:120-180关键信息令牌在此处写入本地存储键名由常量拼接。原始内容丢进可回溯缓存需要时可以重新读。这样既省窗口又保留线索。3. 三条流程怎么被讲清楚这一节是全文最实的部分。我按要查什么、怎么查、容易漏什么来拆每一条都可以直接对应到工具调用序列。3.1 登录流程从入口一路追到令牌失效登录这条链路Agent 最容易做的事是找到登录页面就宣布结束。真正的流程节点远比这多。我给它的检索清单是七项按顺序走第一找到入口。搜索路由注册、页面清单、接口定义确认登录是从哪个入口触发的。这里要区分是页面跳转、弹窗还是回调不同入口对应的后续路径差别很大。第二找到凭证提交。搜索表单提交、请求方法定义确认凭证字段名和提交地址。这一步的关键是拿到字段名的真实拼写因为后面追后端校验全靠它。第三找到后端接收。用字段名去搜后端通常能命中控制器或处理器。命中之后再往上追一层鉴权中间件这里往往是整条链路的核心。第四找到令牌签发。搜索令牌生成、签名、过期时间设置。这一步要记录三件事令牌有效期、刷新机制是否存在、签名密钥来源。第五找到令牌存放。这是最容易漏的一步。搜索写入操作同时搜索读取操作两边对不上就要警惕——我见过写入用封装方法、读取直接取存储的案例这种不一致本身就是重要信息。第六找到失效处理。搜索状态码处理、拦截器、路由守卫。重点是过期之后跳哪里、有没有静默刷新。第七找到权限校验。搜索角色判断、权限装饰器、菜单过滤。七步走完一份登录流程才算立起来。这里我要强调一个原则每个节点至少两处证据。签发一处、校验一处写入一处、读取一处。单点证据的结论我要求在输出里标注待确认。提示追登录链路时search_text的搜索词不要用 login用字段名和错误码。字段名是跨层传递最稳定的锚点错误码往往能一次性定位到所有分支处理逻辑。3.2 存储流程三层结构先分清再下钻存储问题最容易答偏因为存哪这三个字至少有三层含义。我让 Agent 先做一个判断问题是问客户端本地存储、内存缓存还是服务端持久层。判断不清楚就问不要猜。分清之后每层的追法不一样。客户端本地存储追的是写入点、读取点、清理点、键名生成规则。键名生成规则特别值得追因为很多项目会用用户标识拼前缀这意味着换账号时数据是否隔离答案就在这几行拼接代码里。内存缓存追的是缓存实例的创建位置、过期策略、失效触发条件。这里最常见的坑是缓存与数据源不同步——写入数据库之后忘了清缓存或者清了缓存但没清关联键。Agent 只要把写和清两处代码摆在一起问题一眼就看出来。服务端持久层追的是模型定义、读写封装、事务边界、迁移脚本。迁移脚本这块要单独看目录很多项目的表结构演进全在那里光看模型定义看不出历史包袱。三层追完之后我会要求 Agent 输出一张数据流向表列是层 / 写入位置 / 读取位置 / 失效位置 / 备注。这张表是整篇回答里信息密度最高的部分新人拿着它基本能自己摸下去。3.3 更新流程先问是哪一种更新前面提过这个词的歧义。我的处理是在提示词里写死四种解释让 Agent 先选客户端版本更新版本检查、下载、校验、安装、强制更新判断。服务端发布构建、打包、滚动发布、健康检查、回滚。数据迁移迁移脚本的命名规则、执行顺序、幂等性、回滚脚本。配置热更新配置来源、拉取时机、生效范围、降级策略。选错解释的代价很大所以这一步不允许跳过。选完之后追法就明确了。以客户端版本更新为例关键节点是版本号来源配置文件还是构建时注入、检查时机启动、切前台、定时、比较逻辑语义化版本比较还是数值比较这里经常有边界 bug、下载与校验有没有完整性校验、强制更新判断最低支持版本从哪来、灰度开关有没有按渠道或用户分组。数据迁移这块重点看三件事命名规则决定执行顺序、有没有幂等保护、有没有对应的回滚脚本。我见过最危险的情况是迁移脚本没有幂等保护重跑一次就重复插入而发布流程里恰好有个重试机制。这种问题Agent 把两处代码并排摆出来人一眼就能发现。4. 实操把 REA 跑起来前面讲的是思路这一节讲落地。代码我用 Python 写模型调用抽象成一个chat方法你换成自己那套服务即可参数名对应调整就行。4.1 索引构建半小时能跑完的第一版第一版不要追求完美能跑就行。我的建议是先做文件清单、文本索引、符号表三样调用关系和提交摘要放到第二轮补。import os, re, json SKIP_DIRS {.git, node_modules, dist, build, vendor, __pycache__, .venv} CODE_EXT {.py, .js, .ts, .tsx, .jsx, .go, .java, .kt, .rb, .php} def walk_repo(root): files [] for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if d not in SKIP_DIRS] for name in filenames: ext os.path.splitext(name)[1] if ext in CODE_EXT: files.append(os.path.join(dirpath, name)) return files这段看着平淡但跳过目录这个集合是踩过坑才定下来的。早期我没排除构建产物结果搜索令牌命中的全是压缩后的 bundle 文件行号长得离谱读进来毫无意义。另外vendor和.venv也要排第三方库的实现会严重干扰判断——你问的是这个项目怎么做不是那个库怎么做。符号表我用了两种方式优先走语法解析失败回退正则。DEF_PATTERN re.compile( r^\s*(?:async\s)?(?:def|function|class|func)\s([A-Za-z_][A-Za-z0-9_]*), re.MULTILINE, ) def build_symbols(files): symbols {} for path in files: try: text open(path, encodingutf-8, errorsignore).read() except OSError: continue for m in DEF_PATTERN.finditer(text): name m.group(1) line text[:m.start()].count(\n) 1 symbols.setdefault(name, []).append({file: path, line: line}) return symbols正则版召回率高但精确度一般会把注释里的示例代码也扫进来。所以在使用的时候我让trace_symbol的返回值带上置信度标记模型看到低置信度结果会自己去read_slice确认。这比在索引阶段死磕精确度划算得多索引阶段的目标是快精确度交给后续验证。仓库速览的生成我压到两三千字顶层目录树两层、文件数统计、符号数量前二十的文件名、配置清单、最近一百条提交的标题。这份东西放进系统提示模型第一轮就能判断这是个前后端一体的项目还是纯前端路径选择准很多。4.2 工具实现返回值格式比逻辑更重要这五个工具的实现都不难难的是返回什么格式。我调了很多次最后定下来的格式是结果 行号 上下文 提示。def search_text(pattern, root., globNone, limit30): hits [] regex re.compile(pattern) for path in walk_repo(root): if glob and not path.endswith(glob): continue try: lines open(path, encodingutf-8, errorsignore).read().splitlines() except OSError: continue for i, line in enumerate(lines, start1): if regex.search(line): hits.append({ file: path, line: i, text: line.strip()[:200], context: lines[max(0, i-2):i1], }) if len(hits) limit: return {hits: hits, truncated: True, hint: 结果已截断建议收紧正则或限定目录} return {hits: hits, truncated: False}三个细节值得说。第一text截断到两百字符太长的行会挤爆预算而且模型也不需要完整长行。第二truncated字段很重要模型看到它就知道该收紧搜索而不是硬着头皮往下猜。第三hint是我加的引导字段用自然语言告诉模型下一步该干什么比在系统提示里写一堆规则管用。read_slice有个硬约束必须写死def read_slice(path, start, end): if end - start 200: end start 200 lines open(path, encodingutf-8, errorsignore).read().splitlines() body \n.join(f{i:5}| {lines[i-1]} for i in range(start, min(end, len(lines)) 1)) return {file: path, range: [start, end], content: body}两百行这个上限我试过放到五百结果模型经常在长篇内容里迷路抓不住重点。压到两百之后倒逼它先search_text定位再读反而更准。行号前缀用竖线分隔是我试过几种格式里模型引用最不容易出错的一种。4.3 编排循环三轮定框架两轮补细节循环结构本身很简单难的是什么时候停。def rea_loop(question, tools, chat, max_turns10): messages [ {role: system, content: SYSTEM_PROMPT REPO_OVERVIEW}, {role: user, content: question}, ] evidence [] for turn in range(max_turns): resp chat(messages, toolstools) if resp.tool_calls: for call in resp.tool_calls: result dispatch(call) evidence.append({call: call.name, args: call.args, result: result}) messages.append({role: tool, content: json.dumps(result, ensure_asciiFalse)}) continue # 无工具调用进入反思 messages.append({role: assistant, content: resp.content}) if turn 3 and enough_evidence(evidence): break return resp.content, evidence真正起作用的是enough_evidence这个判断。我的规则是三条流程问题至少要覆盖三个不同目录、五个以上不同文件、十个以上精确行号引用且每个关键节点有两处证据。不满足就再来一轮但不超过十轮。超过十轮基本说明问题本身有歧义该回去问人了。提示词这块系统提示里我固定写四条铁律一、所有文件路径必须来自工具返回不得自行拼写。 二、每条结论至少两处证据格式为路径:起始行-结束行写不出就标待确认。 三、先判断问题涉及哪一层客户端/服务端/构建流程判断不清先列出候选并说明理由。 四、不要复述行业通用做法只描述本仓库的实际实现找不到证据就说找不到。第三条和第四条是效果最明显的。第三条解决答偏第四条解决那种通顺但空洞的回答。加进去之后回答里通常会一般来说这类词的频率断崖式下降。反思轮的提示词我单独写了一段让模型列出为了确认结论还缺哪三处证据然后针对这三处再调工具。这一轮经常能补上前面漏掉的失效处理或者配置来源性价比很高。4.4 输出结构表格是给新人看的证据是给自己看的最终输出我定了一个四段结构一句话结论、流程节点表、关键代码证据、风险提示。流程节点表长这样阶段触发位置处理位置证据凭证提交登录表单组件请求封装层统一加签路径A:45-62服务端校验路由注册处鉴权中间件路径B:88-121令牌签发中间件内调用令牌工具类路径C:12-40令牌存放拦截器写入本地存储封装路径D:30-58失效处理状态码拦截跳转逻辑路径E:70-95这张表的价值在于它是可验证的。新人拿到表逐个点开行号看对不上就说明 Agent 错了。这比一段流畅的散文强太多。风险提示那一段我要求写具体的比如令牌刷新逻辑只在前端拦截器里服务端未见刷新接口可能存在过期后强制重登录的情况而不是建议加强安全性这种空话。5. 常见问题与排查实录这部分全是踩坑换来的按出现频率排。5.1 动态注册导致调用链断掉这是最头疼的问题。装饰器注册路由、依赖注入容器、配置驱动加载、字符串反射——这几种写法都会让静态文本搜索断链。你搜函数名只能搜到定义搜不到它在哪被挂上去。我的应对是三招并用。第一招搜注册表找register、bind、route这类词很多时候注册表是集中写的找到表就等于找到全部。第二招搜字符串字面量反射调用一定会有字符串形式的类名或方法名用search_text精确搜这个名字往往能定位到配置文件。第三招搜入口文件主入口里通常有初始化逻辑从那儿往下读两三层注册过程就露出来了。这三招里第二招命中率最高但前提是你得先知道那个字符串长什么样。所以顺序上我会让 Agent 先做第一招和第三招建立整体认知再用第二招补精确位置。5.2 上下文超限与信息蒸发表现很典型前几轮明明读到了关键代码最后一轮结论里却没提。原因是历史被压缩时把关键信息压掉了。我的修法是关键证据提前固化。每轮结束时让模型用一句话把本轮确认的事实写进一个独立的facts列表格式是事实 证据位置。这个列表不进压缩池全程保留。后面所有推理都从facts里取不从历史对话里翻。改完之后关键信息丢失的情况基本没有了。另一个小技巧facts列表超过十五条就做一次归并把同一文件的多条合成一条只留位置和一句摘要。这样既控制长度又不丢线索。5.3 幻觉路径与证据校验即便写了路径必须来自工具返回还是会有漏网。我在输出前加了一个机械校验环节把最终回答里所有路径:行号形式的引用抽出来逐个检查文件是否存在、行号是否在文件范围内、该行附近是否真有关键词命中。不通过的引用直接标红让模型重写那一段。这一步是纯代码实现的不需要模型参与成本极低但效果很好。实测能拦掉大部分凭空生成的路径。行号偏移也归它管——有时候文件在索引之后改过行号整体位移校验会发现对不上然后触发重新读取。5.4 问题速查表现象可能原因排查动作反复调同一个工具结果不满足预期模型在重试检查返回是否被截断放宽 limit只读不写结论缺够了的判定信号补足够的证据门槛或加轮次提醒答成通用行业方案系统提示约束不够硬加只描述本仓库实现的强约束流程缺一环漏了横切逻辑用字段名而不是功能名搜引用路径不存在自拼路径开输出校验环节行号对不上索引后文件被改重新校验必要时重建索引同名函数混淆文本匹配假阳性返回值带置信度强制二次验证一个额外的经验把问题拆成两问效果更好。先问登录流程涉及哪些文件再问这几个文件里的登录流程是怎样的。一步到位反而容易浅。这可能跟模型在长链路推理上的特性有关先建立地图再走路线稳得多。6. 评测怎么判断它真的讲清楚了没有评测这套东西就是玄学。我的做法不算复杂但够用。6.1 评测集怎么造我挑了五个不同规模的项目每个项目手工标注二十个问题覆盖三条流程每个问题标一个黄金文件集合三到八个文件。评测指标就两个文件召回率Agent 实际读到的文件里覆盖了多少黄金文件和引用正确率输出里的路径行号有多少经校验是真的。召回率低于七成说明检索策略有问题引用正确率低于九成五说明约束不够硬。这两个数字比人工读回答靠谱而且能自动化跑。还有一个人工环节随机抽五条回答让不熟悉这个项目的同学照着回答去改一个相关的 bug改得动就算讲清楚了。这个测试很残酷但很真实——能指导操作的说明才是好说明。6.2 我自己的一条经验不要用回答看起来对不对来调参。我早期就是这么干的结果陷进局部最优——调整了七八轮回答读起来越来越顺但召回率没动。后来改成只看数字改一处测一次进度快得多。另外评测集一定要包含答不出来的问题。我在里面故意放了几个这个项目根本没有的功能看 Agent 会不会硬编一个答案出来。这个测试特别能暴露问题早期版本有一半是硬编的加了几轮约束之后才老实说未找到相关实现。最后分享一个我觉得最值钱的观察这套东西真正提升的不是写文档的速度而是代码审查时的提问质量。用熟了之后我自己看陌生仓库会下意识地找写入点和读取点是否一致、横切逻辑挂在哪这些问题比让 Agent 直接给答案更有价值。工具改变的是提问方式这个收获比自动化本身大。