用 AI Agent 逆向 5000 个代码文件：从遗留系统到需求规格说明书的全过程

Lost of 程序猿

633人浏览 · 2026-08-14 14:51:13

Lost of 程序猿 · 2026-08-14 14:51:13 发布

用 AI Agent 逆向 5000 个代码文件：从遗留系统到需求规格说明书的全过程

逆向工程实践 · AI Agent · 2026-08

一套运行多年的企业级软件，文档散落、人员更迭、业务逻辑锁在代码里。能不能让 AI 直接读代码，逆推出一份完整的需求文档？我们用一个真实项目验证了这件事。

5000+ 源文件	250+ Controller	900+ 数据实体	15 业务领域

接手一个没有文档的老系统是很多技术团队的噩梦。业务逻辑全在代码里，新人上手靠口口相传，重构和迁移更是无从下手。这次我们尝试让 AI Agent 直接扫描代码目录，自动完成从代码结构分析到需求文档撰写的全过程。本文记录完整的方法论、踩过的坑和最终效果。

1. 问题：当业务逻辑只存在于代码中

企业软件有一个普遍困境：系统上线运行多年，经历了多轮迭代和人员变动，最初的需求文档早已过时甚至丢失。真正的"需求"散落在三个地方——

代码里：Controller 名称暗示功能点，Service 层藏着业务规则，Entity 字段定义了数据模型；
数据库里：表结构、字段约束、外键关系是数据模型的最终真相；
人脑里：老员工知道为什么这么设计、哪些字段已经废弃、哪些流程有历史包袱。

传统做法是组织人力逐模块阅读代码、访谈关键人员、手工整理文档。一个中等规模的系统，这个过程通常需要数周甚至数月，而且整理出来的文档在完成的那一刻就开始过时。

我们面对的是一套典型的行业管理软件——C# ASP.NET MVC 架构，17 个项目，5000 多个源文件，涵盖十几个业务领域。它有三个客户变体版本，代码中通过命名前缀和独立模块区分。目标很明确：在不依赖原开发团队的情况下，仅从代码出发，逆推出一份按领域分类的完整需求规格说明书。

核心挑战

不是"读不懂代码"，而是代码量太大、模块太多。人工逐个文件阅读效率极低，且容易遗漏跨模块的业务关联。需要一种结构化的方法，让 AI 能够系统性地扫描、归类和提炼，而不是泛泛地"看一眼代码就开始写"。

2. 思路：AI 逆向需求的三层映射模型

在动手之前，我们先建立了一个核心认知：MVC 架构本身就是一座从代码通往需求的桥梁。在典型的 ASP.NET MVC 项目中，代码结构与业务需求之间存在三层可机械提取的映射关系：

代码层	映射到需求	提取方式
`Areas/` 目录	业务领域——每个 Area 对应一个业务模块	列出顶层目录名称
`*Controller.cs`	功能点——每个 Action 方法对应一个用户操作	递归扫描 Controller 文件名
`Entity/*.cs`	数据模型——实体类和字段映射数据库表结构	读取实体类属性和 EF Mapping

这三层不是孤立的。Controller 名称引用 Entity，Entity 之间通过导航属性关联，Areas 把相关 Controller 组织在一起。三者交叉验证，就能还原出"谁在什么模块里对什么数据做了什么操作"——这正是需求规格说明书的核心内容。

逆向分析流水线

基于这个模型，我们设计了一条清晰的处理流水线：

📁 目录扫描 → 📊 结构提取 → 🔍 领域归类 → 🤖 深度阅读 → 📝 文档生成
递归列出源文件  Areas/Controller/Entity  按业务语义分组  关键实体与流程  按领域撰写SRS

3. 实战：五步完成代码到文档

第一步：直接访问本地文件系统

最初的顾虑是文件上传限制——如果一个个文件上传，5000 个文件根本不现实。但 Coze Agent 的桌面端能力可以直接访问本地文件系统，通过授权后就能用命令行递归扫描目录，无需上传任何文件。

申请目录权限后，Agent 获得了"始终允许"的授权，后续所有读取操作都无需重复确认。

⚠️ 环境适配：Windows vs Linux 命令

用户本地电脑是 Windows 环境，第一次尝试用 find、ls -R、head 等 Linux 命令全部失败——要么被安全策略拦截，要么 PowerShell 不识别。最终统一改用 PowerShell 原生命令 Get-ChildItem，问题解决。

关键扫描命令（已过滤掉 bin/obj/packages 等编译产物目录）：

# 递归列出所有 C# 源文件
Get-ChildItem -Path 'D:\Project\CodeRoot' -Recurse -File `
  -Include *.cs,*.cshtml,*.csproj,*.sln |
  Where-Object { $_.FullName -notmatch '\\(bin|obj|packages)\\' } |
  ForEach-Object { $_.FullName } | Sort-Object

第二步：提取三层结构

三条命令分别提取目录结构、Controller 清单和 Entity 清单：

列出所有项目和 Areas 目录——先看解决方案文件（.sln）了解项目组成，再列出各项目顶层目录，识别出 17 个项目和 50 多个业务区域。
递归扫描所有 Controller——一条命令拿到 250+ 个 Controller 的完整路径，按 Areas 分组后，业务领域的轮廓立刻清晰了。
扫描全部 Entity 文件——900+ 个实体类文件，包括 EF Mapping 配置。Entity 的命名直接揭示了数据模型：设备、工单、物料申请、采购订单、修理工单、预算……

这一步的产出是三份结构化清单，不需要 AI "理解"代码，只需要机械提取文件名和目录结构。但这三份清单构成了后续所有分析的骨架。

第三步：按业务语义归类领域

拿到 Controller 和 Entity 清单后，通过命名模式识别业务领域。例如：

DeviceInfo → 设备管理       Parts*    → 备件管理
Mrp*       → 物料/物资管理   Rep*      → 船舶修理
Budg*      → 预算管理       Safe*     → 安全管理
Supplier*  → 供应商管理     PmsDictionay → 系统字典
Book*      → 台账/手册管理   wf*       → 工作流引擎

同时发现了重要线索：很多 Controller 带有 HKMW_ 前缀，而代码库中存在三个解决方案文件（面向不同客户），说明这是一个多租户/多客户变体的系统。这些变体差异必须在需求文档中明确标注。

第四步：深度阅读关键代码

清单和归类解决了"有什么"的问题，但需求文档还需要回答"怎么运作"。我们选择了每个领域最核心的 Entity 文件进行精读：

设备工作项目（device_job）——揭示了基于计数器的保养计划触发机制；
工单（work_card）——揭示了工单从创建、审批到完工的完整状态机；
物料申请（mrp_apply）——揭示了申请→询价→订单→入库的采购链路；
备件库存（parts_material_info/stock/in_out）——揭示了备件台账和出入库流水。

读取实体类的属性定义和 EF Mapping 配置，可以精确到字段级别——字段名、类型、是否必填、最大长度、关联关系。这些是需求文档中数据模型章节的直接素材。

✅ 为什么不读所有代码？

5000 个文件全量精读既不现实也不必要。Controller 名称已经覆盖了功能点的"面"，核心 Entity 精读补充了业务规则的"点"，点面结合足以还原需求全貌。Service 层的业务逻辑可以在需要时按需深入，但对需求文档而言，Controller + Entity 的信息密度已经足够高。

第五步：派发子 Agent 并行撰写

结构化分析完成后，进入文档撰写阶段。这一步的工作量大但目标清晰，适合交给子 Agent 后台执行：

sessions_spawn({
  agent: "lead",
  name: "PMS需求逆推文档",
  task: `基于以下代码分析结果，撰写完整的需求规格说明书...
    - 15个业务领域的Controller清单
    - 核心Entity字段定义
    - 业务流程描述
    - 多客户变体差异标注
    输出：/项目目录/船舶PMS系统逆向需求分析.md`
})

主会话把前三步提取的全部结构化数据（Controller 完整清单、Entity 字段、领域分类）打包传给子 Agent，子 Agent 专注于文档撰写，主会话保持可响应。约 10 分钟后，一份 1600+ 行的需求规格说明书自动生成。

4. 关键技术决策与踩坑记录

决策一：直接读文件 vs 上传文件

❌ 逐文件上传	✅ 桌面端直接访问
受单次上传数量限制	一次授权，递归扫描
5000 文件需要数百次操作	保持完整目录结构
无法保持目录结构上下文	可过滤编译产物
二进制和配置文件干扰	按需精读，不占上下文

决策二：先提取结构再阅读内容

最容易犯的错误是一上来就让 AI “读代码然后告诉我系统是做什么的”。这种方式在小项目上可行，但面对 5000 个文件时，AI 会被海量信息淹没，产出泛泛而谈的概述。

我们的做法是先建立骨架（目录+文件清单），再填充血肉（精读关键文件）。骨架阶段只提取元数据（文件名、路径、目录结构），不读取文件内容，因此速度极快且不消耗大量上下文。拿到骨架后，AI 对系统全貌有了结构化认知，再精读关键文件时就能精准定位、有的放矢。

决策三：用子 Agent 处理重撰写任务

文档撰写是典型的"输入明确、耗时较长、可独立检查"的任务。主会话已经完成了所有分析工作，把结构化结果交给子 Agent 撰写，既避免了主会话上下文耗尽，又能让用户在等待期间继续对话。

踩坑：Windows 路径中的特殊字符

代码目录路径中包含括号 (BS)，在 PowerShell 中如果不用单引号包裹会被解析为表达式。所有涉及路径的命令都必须用单引号包裹：

# 正确：单引号包裹含特殊字符的路径
Get-ChildItem -Path 'D:\Project\(BS)CodeRoot' -Recurse

# 错误：括号会被 PowerShell 解析
Get-ChildItem -Path D:\Project\(BS)CodeRoot -Recurse

踩坑：高危命令确认机制

递归扫描命令（如 Get-ChildItem -Recurse）会被系统安全策略标记为高危操作，需要用户在卡片上点击确认。虽然已授权目录访问，但递归扫描仍会触发二次确认。在实际操作中提前告知用户"接下来会有确认弹窗"，可以避免流程中断。

5. 产出物与效果评估

最终交付了一份约 84KB、1646 行的需求规格说明书，包含以下章节：

章节	内容	追溯依据
文档概述	系统简介、术语表（17 项）、优先级定义	.sln 文件、代码注释
系统总体描述	10 类用户角色、3 个客户变体差异、技术架构、17 个项目结构	项目引用关系、Area 命名前缀
功能需求	15 个业务领域逐一展开，200+ 功能点	250+ Controller 名称与分组
非功能需求	船岸协同、多租户、多语言、安全权限等 8 个维度	代码中的 IfLand 字段、RBAC 模型、语言包
数据模型	实体关系图、14 个实体分组、6 项设计特征	900+ Entity 类及 EF Mapping
系统接口	SSO、工作流、邮件、附件等 6 类接口	接口项目、WF5 引擎、邮件服务代码
附录	Controller 完整功能追溯矩阵	全量 Controller 路径清单

这份文档好在哪里

可追溯：每个功能点都标注了对应的 Controller 名称，可以直接回到代码验证；
有优先级：P0/P1/P2 三级标注帮助读者快速识别核心功能；
标注变体差异：清晰区分了三个客户版本的特有功能；
基于实证：所有需求均来自代码中真实存在的类、方法和字段，没有编造。

它的局限

⚠️ 需要人工补充的部分

代码能告诉你"系统做了什么"，但无法完全回答"为什么这么做"。某些业务规则背后的历史原因、废弃功能与在用功能的区分、以及未体现在代码中的业务约束（如行业合规要求的具体条款），仍然需要熟悉业务的人员进行校验和补充。AI 逆向出的需求文档是一个高质量的起点，而不是终点。