让 AI Agent 读懂企业源码

沿业务问题读懂实现，将源码转化为可复核的技术依据。

当我们问 AI Agent：“这个功能究竟如何实现？”“修改这段代码会影响哪些业务？”“现有实现是否隐藏着尚未暴露的问题？”期待的并不是几段看似合理的代码解释，而是能够支撑研发和测试工作的分析依据。

连接代码平台、搜索文件、把仓库克隆到本地，只解决了访问问题。要回答业务问题，还要弄清分析对象属于哪个版本，功能分布在哪些仓库，模块怎样连接，哪些条件会改变行为，以及结论能否回到源码中复核。

真正的挑战，不是让 AI Agent 看到代码，而是让它理解代码，并且用源码回答实际业务问题。

这套企业源码分析能力体系围绕这一目标组织能力：基础访问与版本能力取得分析材料，源码地图帮助定位，Agent 再结合指定版本的实现，形成解释、变更影响分析或缺陷候选。它提供源码层面的支撑，不替代产品运行验证，也不接管业务责任方的最终判断。

下面从源码获取、源码理解、变更影响分析和主动缺陷候选发现四个方面展开。它们是便于讲述的能力递进，不是必须依次执行的四阶段流水线：前两部分提供共同基础，后两部分面向不同请求独立开展分析。

贯穿全文的规则优先级案例是教学构造：假设优先级数值越小，排序越靠前；数值 0 合法；未填写时采用默认值 100。这些约定、数值、代码及异常均不代表真实产品已经存在相应缺陷。

一、源码获取：先取得适合任务的分析输入

源码获取首先要回答的，不是下载多少代码，而是当前任务需要哪些源码，拿到的又是哪一个版本。

分析一个指定字段，与准备企业多仓库源码库存，是两类不同规模的工作。混淆两者，可能导致为了一个问题下载大量无关代码，也可能为了读取方便，用默认分支代替任务真正需要的版本。

三项基础能力，分别解决不同问题

代码平台读取能力负责已验证的代码平台访问凭据的管理与只读 HTTPS API，支撑项目、MR 等平台信息读取。它不重新承担浏览器登录，也不提供代码托管平台写操作。

源码与版本读取能力负责只读 Git over SSH、单仓获取、精确源码对象和差异读取。SSH 通道与 Cookie 通道分开；平台元数据与代码事实也不相互冒充。

多仓库源码准备能力负责群组仓库发现、清单对账、串行浅克隆和显式库存维护。它复用 Git 获取能力，不另建产品到仓库的业务映射。

这三个能力共同提供可靠的源码输入，但不意味着每个任务都要重新调用三者。已有正确版本可以直接复用；只有需要准备或补充材料时，才按任务范围获取。

这里必须区分两个对象：发现仓库，是确认能够访问哪些代码项目；理解业务能力，是弄清产品、组件与仓库之间的关系。仓库已经下载成功，并不意味着产品能力已经梳理完成。

版本准确，比默认追新更重要

源码库存可以在选定分支上维护，但历史问题调查、MR 分析或指定版本解释，应绑定任务自己的提交。不能因为本地只有默认分支，就用它代替目标发布版本。

本地仓库可读、远端引用已核验、源码与目标环境的部署版本匹配，是三个不同事实。健康检查不能证明远端没有新提交；取得一个 Commit，也不能证明目标环境已经运行相应构建。

普通克隆优先采用浅克隆。差异分析需要历史时，可以有界补充；历史不足则保留缺口，而不是悄悄更换比较语义。多仓库准备能够跳过健康仓库，保留已成功的结果，并在重跑时继续未完成项。检查超时只说明检查未完成，不能把它当作仓库损坏并删除已有源码。

源码复用还需要考虑任务期限：暂停和续查不等于源码已经用完，能够缓存也不等于无限保留。支撑结论的必要证据应与临时源码空间分开管理。远端只读也不等于本地不产生文件；克隆、索引和报告仍有各自的本地生命周期。

分析哪一版，就取得并核对哪一版；需要多少材料，就按问题准备多少材料。

代码取得之后，新的问题随之出现：这些仓库各自承担什么职责？一个功能由哪些组件协同完成？应该从哪里开始读？因此，下一步不是盲目深入某个文件，而是先梳理产品源码的技术脉络。

二、源码理解：先建立地图，再读懂业务实现

源码获取解决材料问题，源码理解回答这些代码承载什么业务、如何协同工作。源码地图与实现理解能力将源码地图、指定版本读取与按需理解结合起来，支撑正常流程解释、行为推演、测试设计和异常调查。

源码能力地图：把分散仓库联系起来

地图由两类信息共同构成。一类是受维护的产品、组件、系列、角色与仓库对应关系，帮助决定去哪些仓库找；另一类是源码中的模块、路由、导入关系和候选位置，帮助决定进入仓库后从哪里开始读。

可以把阅读路径概括为：从产品与组件定位仓库，从模块与接口定位入口，再进入具体实现。这不是搬动原有仓库，而是在既有代码组织之上建立逻辑关联。

源码能力地图也不等于一份已经验证完整的业务功能清单。它首先提供技术脉络与定位线索；没有检索到名称，不能直接证明功能不存在。

地图同时找到前端提交函数和后端接口，也不能证明两者必然相连。还需要核对真实请求地址、方法、字段和处理入口。两个同名函数、相邻关键词或单侧导入关系，都不足以证明完整调用链。

当地图所依据的库存版本与任务版本不同，候选位置仍可帮助缩小范围，但影响结论的关键连接必须在任务版本中重新核实。

先把脉络理清，不是为了省掉读代码，而是为了让后续阅读更有方向。

沿着问题，从入口读到关键结果

以优先级为例，可以检查表单如何接收输入，提交前如何转换，接口怎样解析校验，数据如何保存，执行逻辑怎样读取排序，以及页面如何展示返回结果。

尤其要区分未填写、空字符串、数值 0 与字符串 "0"。业务上看起来相近的输入，可能经过不同的默认值、类型转换和校验分支。

阅读深度由问题决定。只问未填写时的默认值，可能不需要追到执行器；若解释最终排序异常，就不能停留在表单，而应继续核对持久化与排序条件。重要连接要说明两端是什么、通过什么机制相连，不需要为一个简单问题遍历整个产品。

这种能力不限于故障调查。算法匹配顺序、异步任务的完成条件、配置覆盖优先级、正常的数据流和恢复入口，都可以在没有异常的情况下按需理解。

交付不应只有文件列表，而应解释该版本的处理规则，输入怎样走到结果，哪些分支会改变行为，并保留版本和源码位置。直接读到的事实、代入输入后的推演，以及依赖未确认配置或外部服务的假设，要分开表达。

需求说明应该怎样，源码解释该版本如何实现，运行证据确认目标环境实际怎样。

实现理解本身就可以完成一项任务，不必继续寻找问题。只有当业务带来明确的代码变化，我们才进一步追问：变化沿哪些关系传播，又可能破坏哪些原有约定？

三、变更影响分析：从修改点追踪关联风险

变更影响分析回答：这一处修改，是否可能让其他原本正常的行为发生退化？变更影响分析能力围绕明确、冻结的变更集合开展有界分析。这里仍是基于源码的静态分析，不是运行产品后的动态测试。

外部请求确定分析对象

一个典型来源是缺陷回归。业务侧从 DevOps 问题单取得关联 MR，核实版本和变更范围，再请求源码分析提供影响分析。回归只是触发方，本节不展开其内部执行流程。

平台元数据由代码平台读取能力支撑，源码和差异由源码与版本读取能力支撑；影响分析消费已经核实的比较范围。不能把职责简化成一个分析能力拿着链接完成全部系统读取，更不能写成缺陷查询自动启动影响分析。

开始前需明确仓库、变更前后完整提交、比较语义和文件清单来源。多份 MR 分别绑定，移动分支的当前差异不能直接归给历史 MR。分析范围的缺失不能被解释为空变更。

把文本差异解释成行为变化

假设教学场景中的修复，试图解决未填写优先级时提交空字符串被拒绝的问题。修改前的表达式是 priority == null ? 100 : priority，修改后变为 priority || 100。

对于这个教学表达式，新写法让空字符串采用 100，也让数值 0 变成 100。这是一个可以说明的源码行为差异，但还不能直接宣布整个产品存在排序问题。

接下来需要查明：谁会传入数值 0，哪些路径调用此逻辑，转换后的值是否进入保存和使用。代码多了几行或少了几行，并不是影响分析的终点；输入约定、返回值、状态和配置行为的变化才是关注对象。

沿真实关系扩展，不按组件名称漫扫

假设新增规则与编辑规则都调用共享转换函数，而批量导入使用另一条实现。新增时输入 0，可能在提交前被改写；编辑已有 0 时，即使用户没有调整优先级，也可能在保存时被改写。批量导入则不能仅因功能相近就被归入同一影响路径。

最终排序还要继续核对保存结果、使用方式和触发条件。未修改的文件可能因调用或数据约定变化而受影响；同属一个组件的文件也不一定都受影响。

分析时可以沿公共调用、接口字段、状态流转、数据、配置、权限、异常处理和资源生命周期追踪，但只扩展有真实关系依据的路径。地图帮助找候选，不代替因果关系证明。

“有关联”“行为变化”“存在业务风险”是三个不同判断。关联只说明可能参与；行为变化说明处理结果有差异；风险还要说明这一差异怎样违反适用约定，并导致可观察后果。

主动寻找反证，并核对前后归因

发现可疑路径后，应检查调用前是否已经转换类型，其他层是否覆盖默认值，分支是否可达，以及配置或版本是否排除了触发条件。

例如，数值 0 若在调用前已经变成字符串 "0"，就不会在上述表达式中发生同样的默认值替换；编辑请求若根本不提交该字段，相关候选也可能不成立。

反证是筛除错误判断的重要步骤。已有测试文件可以辅助理解意图，但文件存在不等于测试已经执行，也不能直接证明当前实现没有风险。

认定问题由本次修改引入或加重，需要同时引用前后证据。两版都存在相同行为，不能写成本次新引入；缺少一侧源码，应保留未知，不能凭印象归因。

输出能够指导验证的报告

报告应保留变化事实、传播路径、触发条件、业务约束依据、已检查反证、前后归因与覆盖缺口，并给出具体的验证建议。

教学案例中的建议不应笼统写成“回归规则管理”，而应具体到新增规则输入数值 0、编辑已有优先级为 0 的对象但不改动该字段，并说明应观察保存值、显示结果还是排序行为。

分析完成只表示声明的有界范围已经审阅。未发现候选，不能改写成整个 MR 绝无副作用。原问题修复正确性、变更周边影响与目标环境的运行结果，也需要保持分工，不能相互替代。

前面的分析有明确起点：代码发生了变化。但风险并不只来自新变化。现在换一个独立问题：即使没有 MR，现有实现是否也可能违反某项业务约定？

四、主动缺陷候选发现：依据业务约束审视现有实现

源码缺陷候选发现能力面向明确组件与有限源码范围，寻找可能违反可靠业务约束的实现。这里的主动，是不必等待异常暴露，而不是不经请求进行全量扫描。它不是变更影响分析的自动下一步。

先明确应该成立的约定

不能从“让模型随便找几个 Bug”开始，而应先确定有来源、可核实、可反驳的业务约束。例如，合法优先级 0 在接口传递与页面展示中，应保留原有业务含义。

依据可以来自产品规格、接口契约、已有测试、用户验收要求，或经过适用性核对的相邻实现。不能只凭模型置信度判断，也不能因为另一段代码写法不同，就认定当前实现错误。

缺少可靠预期时，只能保留临时假设，不能生成正式候选。

沿有限主题检查跨层一致性

当前主题包括默认值、接口转换、前端枚举和显示条件的一致性，以及功能、权限或许可证约束在入口、设置与后端执行中的一致性。它关注功能约定，不是通用漏洞或依赖扫描。

继续使用优先级背景，但这是没有 MR 的独立任务。假设接口合法返回数值 0，页面却采用“值为真才显示，否则显示未设置”的条件。

Agent 应继续核对实际返回类型、页面使用字段、渲染前转换，以及适用预期是否确实要求显示 0。把这些关系核实后，才有依据形成有效值可能被误显示为空的候选。

这条线索也不能直接扩大为排序失效，因为展示异常不自动意味着执行异常。

从可疑实现，形成可复核线索

候选应说明预期及来源、触发条件、实际源码行为、仓库和提交、具体位置、已检查的相反解释、可观察症状、验证方式和限制。

当前机械检查主要核对有限文本事实与源码身份，不是完整程序语义证明，也不是执行目标产品代码。格式正确、哈希一致或文字命中，不能单独升级为缺陷确认。

当前实现仅覆盖已适配的安全组件，使用符合要求的本地默认分支 tip，并固定本轮提交。该能力处于 Beta；不构建或运行目标产品，不评定最终严重程度，不直接提单。产品运行验证与自动提单的正式联动尚未启用。

它的当前价值，是把值得怀疑的实现转化为有依据、有触发条件、有反证、能够继续验证的问题线索。

结语：让源码理解真正服务业务

按问题组合能力

至此，六项支撑能力均有明确位置：代码平台读取能力、源码与版本读取能力与多仓库源码准备能力提供基础读取和源码准备；源码地图与实现理解能力提供地图与实现理解支撑；变更影响分析能力和源码缺陷候选发现能力分别服务变更影响与主动候选分析。顶层负责路由和必要的轻量编排，不重复实现这些职责。

这套能力不是固定流水线。解释一个配置如何生效，可以在理解完成后结束；分析一份明确 MR，不必启动全量缺陷发现；主动检查现有实现，也不要求先有代码变化。不同任务可以复用已有正确源码和地图，不必每次重新准备全部材料。

工具负责可靠取得事实，能力规约约束方法、输入输出和边界，Agent 围绕业务问题核对关系、推演行为并形成解释，业务责任方结合需求与运行证据完成后续判断。

从源码材料到业务依据

源码原本就是工程资产。我们增强的不是它的存储数量，而是围绕业务问题访问、定位、理解和复核它的能力。评价时应关注是否找对版本、讲清实现、缩小验证范围并减少无依据猜测，而不只统计仓库、报告或候选数量。

源码获取解决可靠材料，源码地图帮助找到关键实现，源码理解解释为什么这样工作，影响分析与候选发现进一步回答哪里值得重点关注。

最终目标不是让 Agent 读到更多代码，而是让它沿着业务问题读懂实现、分析变化，把潜在风险转化为可追溯、可复核、可继续验证的技术依据。