面向旧系统（Legacy System）的智能解析、文档生成与改修辅助方案

---

1. 背景与问题定义

在大量企业系统中，仍然存在以下典型问题：

• 代码规模大（几十万～上百万行）

• 技术栈老旧（Java 6/7、COBOL、Shell、PL/SQL 等）

• 文档缺失或与实现严重不一致

• 维护人员更替频繁，知识无法传承

传统的做法依赖：

• 人工阅读代码

• grep / IDE 搜索

• 经验型理解

其结果是：

• 理解成本高

• 改修风险大

• 测试覆盖不足

RAG（Retrieval-Augmented Generation）+ Code Analysis 正是为解决上述问题而出现的一条可落地的技术路线。

---

2. 什么是 RAG + Code Analysis

2.1 RAG 的定义

RAG（检索增强生成）是一种架构思想：

在生成回答之前，先从外部知识库中检索“相关上下文”，再基于这些上下文进行生成。

其核心价值在于：

• 模型不需要记住所有知识

• 知识可以随时更新

• 生成结果可追溯来源

2.2 Code Analysis 的定义

Code Analysis 并不是简单的“把代码丢给 AI”，而是：

• 对代码进行结构化解析

• 提取可理解的语义单元

• 显式表达依赖关系与行为

典型分析对象包括：

• 文件 / 模块

• 函数 / 方法

• SQL / 数据表

• 画面 / API / Batch

---

3. 整体标准架构

┌──────────────┐
│ Legacy Code  │
└──────┬───────┘
       │
       ▼
┌────────────────────┐
│ ① Code Parsing     │
│  (结构解析)        │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ ② Semantic Chunking│
│  (语义拆分)        │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ ③ Embedding        │
│  (向量化)          │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ ④ Vector DB        │
│  (pgvector等)      │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ ⑤ RAG Query        │
│  (检索 + 生成)     │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ ⑥ Artifacts Output │
│  (规格/测试/代码) │
└────────────────────┘

---

4. 第一步：代码结构解析（Code Parsing）

4.1 为什么不能直接用全文

直接把代码全文送入向量数据库，会导致：

• 向量语义混乱

• 命中结果不精准

• Token 浪费严重

4.2 正确的解析粒度

语言	推荐粒度
Java	类 / 方法
COBOL	段落（Paragraph）
SQL	单条 SQL
Shell	函数 / 步骤

4.3 解析输出示例

{
  "type": "function",
  "name": "createOrder",
  "file": "OrderService.java",
  "inputs": ["OrderDTO"],
  "outputs": ["OrderResult"],
  "tables": ["T_ORDER", "T_ORDER_DETAIL"],
  "description": "订单创建处理"
}

---

5. 第二步：语义拆分（Semantic Chunking）

5.1 Chunk 的设计原则

• 单一职责

• 可独立理解

• 尽量包含上下文但不过长

5.2 常见 Chunk 类型

类型	示例
Business Logic	订单校验逻辑
Data Access	INSERT / UPDATE
UI Event	按钮点击
Batch Step	批处理步骤

---

6. 第三步：向量化与元数据

6.1 为什么元数据是“生死线”

向量只能表示“像不像”，不能表示“是谁”。

必须附带元数据：

{
  "module": "order",
  "layer": "service",
  "language": "java",
  "path": "/src/order/OrderService.java",
  "depends_on": ["UserService"]
}

6.2 推荐数据库

• PostgreSQL + pgvector（最现实）

• Milvus / Qdrant（规模化）

---

7. 第四步：RAG 查询设计

7.1 查询不是“问问题”

错误示例：

请分析这个系统

正确示例：

基于 Order 模块的 Service 层与 DB 操作，生成订单创建处理的处理概要

7.2 RAG Prompt 模板（示意）

以下是从系统代码中检索到的相关实现片段：
{context}

请基于以上内容：
- 总结处理流程
- 列出使用的数据表
- 明确输入与输出

---

8. 第五步：生成工件（Artifacts）

8.1 可生成的成果物

成果物	自动化程度
处理概要	高
画面项定义	高
DB 定义书	高
测试仕様书	高
改修代码	中

8.2 推荐流水线

解析 → 草稿 → 人工 Review → 定稿 → 测试生成

---

9. 典型落地场景

• 旧系统文档再生成

• 回归测试用例自动化

• 改修影响范围分析

• 新人 Onboarding

---

10. 常见失败原因

原因	结果
不做结构解析	AI 胡编
Chunk 过大	命中不准
无元数据	无法定位
期待全自动	项目失败

---

11. 总结

RAG + Code Analysis 的本质不是“让 AI 理解系统”，而是：

把系统理解这件事，变成“可检索、可复用、可验证”的工程过程。

这是目前旧系统现代化中，风险最低、ROI 最高的一条路线。