Module Analyzer Generate Doc - Java 单模块深度文档生成器

专注于单个 Java/Maven 模块的深度业务逻辑分析 - 让 AI 全面理解模块的每个细节

核心特性

单模块深度分析:

• - 专注于单个模块的完整扫描（而非整个项目）
• L3 文件级文档：每个包含业务逻辑的类生成详细业务解释
• L2 模块级文档：模块架构索引、核心业务流程、依赖关系汇总

智能任务执行:

• - 多子代理并行分片处理（默认 5 个并行，每片 10-16 个文件）
• 上下文自动压缩（每处理 2-3 个文件压缩一次）
• 失败自动重试（最多 3 次，指数退避）
• 断点续传支持（状态文件记录进度）
• 进度定时汇报（每 20 分钟）

文档质量保证:

• - 纯自然语言业务描述（无代码片段）
• 方法级别流程分析（触发条件、数据处理、业务规则、异常处理）
• 领域知识解释（业务概念、术语说明）
• 设计意图说明（为什么这样设计，解决什么问题）

智能跳过机制:

• - 纯数据对象（Entity/DTO/VO，仅 getter/setter）→ 跳过
• 枚举定义（无复杂逻辑）→ 跳过
• 简单参数对象 → 跳过
• 测试类 → 跳过
• 接口定义（业务逻辑在 Impl 中）→ 跳过

激活条件

当用户提到以下关键词时激活：

• - "分析这个模块"
• "生成模块文档"
• "扫描 admin-api 模块"
• "为 xxx 模块生成源码解析"
• "理解这个模块的业务逻辑"
• "模块级文档索引"
• "Java 模块分析"
• "单模块深度分析"

与 project-analyzer-generate-doc 的区别:

• - project-analyzer-generate-doc：全项目多模块扫描，生成 L3→L2→L1 三层文档
• INLINECODE1：单模块深度扫描，生成 L3→L2 两层文档（更详细、更快速）

完整工作流程

Step 0: 模块扫描与规划

CODEBLOCK0

输出: 文件列表 + 分片计划 + 已存在文档检查

Step 0.5: 已存在文档处理

目的: 检查已存在的文档是否符合要求，按需迁移或更新

CODEBLOCK1

Step 0.6: 识别低质量文档（仅报告，需用户确认）

目的: 识别不符合要求的文档，仅生成报告，不自动删除

CODEBLOCK2

⚠️ 重要安全约束:

• - 此步骤仅生成报告，绝不自动删除任何文件
• 如需处理低质量文档，必须明确询问用户并获得确认
• 删除操作示例（仅当用户明确同意时执行）:

  # 询问用户确认
  $confirm = Read-Host "是否删除 $($lowQualityDocs.Count) 个低质量文档？(y/n)"
  if ($confirm -eq "y") {
      # 移动到回收站而非直接删除（如果可能）
      foreach ($doc in $lowQualityDocs) {
          Write-Host "将移动到回收站：$($doc.FullName)"
      }
  }
  

Step 1: 生成 L3 文件级文档（核心阶段）

子代理分片策略:

子代理任务模板:

CODEBLOCK4

1. 1. 文件行数 < 30 行
2. 不包含以下关键字：if, for, while, switch, try, catch, return（getter/setter 除外）
3. 只包含字段定义和 @ 注解
4. 方法体都是空的（只有分号或 throw new UnsupportedOperationException）

**⚠️ 必须生成文档的情况**（满足任一条件）：
- Controller 类（包含 API 接口）
- Service/ServiceImpl 类
- Helper/Util 类（包含业务方法）
- Consumer/Listener 类（消息处理）
- Job/Task 类（定时任务）
- Config 配置类（包含 Bean 定义）
- Interceptor/Filter/Aspect 类
- 任何包含实际业务逻辑的类

### 4. 文档质量自检（⚠️ 生成后必须检查！）

**生成每个文档后自检**，确保文档合格：

**✅ 合格文档检查清单**（必须全部满足）：
- [ ] 文档行数 > 30 行
- [ ] 包含"触发条件"或类似描述（什么时候执行）
- [ ] 包含"输入数据"或"处理流程"描述（如何处理）
- [ ] 包含"业务规则"或"判断逻辑"描述（判断条件）
- [ ] 包含"输出结果"或"数据流转"描述（结果去向）
- [ ] 不包含原代码片段（`public class`, `if ()`, `return` 等关键字）

**❌ 低质量文档特征**（出现任一需重新生成，不建议使用）：
- [ ] 文档行数 < 20 行
- [ ] 只包含模板框架（"Business component", "Interface definition", "Simple data object"）
- [ ] 只重复类名和包名，无实际业务解释
- [ ] 核心业务逻辑部分只有"Executes business logic based on specific scenario"

**自检示例**：

❌ 低质量文档（需要重新生成）

Business Responsibility

Core Business Logic

✅ 合格文档（正确示例）

业务职责

核心业务逻辑

支付宝授权码验证

1. 1. 调用支付宝 API 换取用户 openid
2. 验证返回的 openid 是否有效
3. 根据 open_id 查询本地用户...

### 5. 上下文管理
- Config 配置类（包含业务配置逻辑）
- 工具类（包含业务相关工具方法）
- 拦截器/过滤器（包含业务逻辑）
- 异常处理器
- MyBatis Mapper XML 文件
- 任何包含业务逻辑的类

### 5. 上下文管理
- 每处理完 2-3 个文件，压缩已处理内容
- 只保留：文件路径 + 1 行摘要
- 丢弃：完整文档内容、中间思考过程

### 6. 文件读取失败处理
- 如文件读取失败，记录该文件到失败列表
- 在最终报告中标注无法读取的文件
- 请求用户确认文件访问权限
- ⚠️ 禁止尝试提权或使用替代读取工具

## L3 文档模板

{类名} - 业务逻辑详解

基本信息

• - 文件路径: {relativePath}
• 行数: {lines}
• 文件类型: {Config/Controller/Service/ServiceImpl/Interceptor/Handler/Util}
• 所属模块: {moduleName}

业务职责

核心业务逻辑

{方法/功能点 1}

• - 触发条件
• 输入数据处理
• 业务规则判断
• 数据流转过程
• 输出结果
• 异常情况处理

{方法/功能点 2}

业务流程

数据交互

依赖关系

设计意图

## 返回格式

上下文压缩策略:

CODEBLOCK9

Step 2: 生成 L2 模块级文档

触发条件: 所有 L3 文档生成完成

核心策略:

• - spawn 一个子代理
• 读取该模块所有 L3 文档的摘要信息
• 汇总生成 module.md
• 包含模块架构、核心业务流程、依赖关系

L2 文档模板:

详见 references/l2-module-template.md

核心章节:

CODEBLOCK10

任务监控与重试机制

状态文件

路径: INLINECODE2

内容:
CODEBLOCK11

重试策略

CODEBLOCK12

进度汇报

频率: 每 20 分钟或每完成一个分片

内容:

## 📊 文档生成进度报告

**模块**: admin-api
**开始时间**: 2026-03-07 10:17:00
**当前时间**: 2026-03-07 10:40:00
**已用时间**: 23 分钟

### 总体进度：76.5%

### 当前阶段：L3 文件级文档生成

| 分片 | 状态 | 已处理 | 已跳过 |
|------|------|--------|--------|
| chunk1 | ✅ | 16 | 0 |
| chunk2 | ✅ | 6 | 10 |
| chunk3 | ✅ | 16 | 0 |
| chunk4 | ✅ | 13 | 4 |
| chunk5 | ✅ | 11 | 7 |

### 统计
- 已处理文件：62
- 已跳过文件：19（纯定义类）
- 失败文件：0

二次扫描查漏

目的: 确保所有包含业务逻辑的源码都有文档可依

流程:

# 1. 扫描所有 Java 文件
$javaFiles = Get-ChildItem "<模块路径>/src/main/java" -Include *.java -Recurse

# 2. 扫描所有已生成文档
$docFiles = Get-ChildItem "<项目根目录>/.ai-doc/<模块名>" -Include *.md -Recurse

# 3. 对比找出缺失文档的文件
foreach ($java in $javaFiles) {
    $relative = $java.FullName.Replace("<模块路径>/src/main/java/", "")
    $expectedDoc = "<项目根目录>/.ai-doc/<模块名>/$relative.md"
    if (!(Test-Path $expectedDoc)) {
        # 检查是否应该跳过
        $content = Get-Content $java.FullName -Raw
        if (ShouldSkip $content) {
            Write-Host "跳过 (简单类): $relative"
        } else {
            Write-Host "缺失文档: $relative"
            $missing += $relative
        }
    }
}

# 4. 对缺失文档的文件 spawn 补充任务
if ($missing.Count -gt 0) {
    Spawn subagent to process missing files
}

错误处理

子代理超时

CODEBLOCK15

上下文爆炸

CODEBLOCK16

文件访问权限问题

CODEBLOCK17

配置项

在 TOOLS.md 中添加：

CODEBLOCK18

使用示例

基础用法

CODEBLOCK19

带已有文档的增量更新

CODEBLOCK20

断点续传

CODEBLOCK21

性能参考

生成时间估算

Token 消耗估算

相关文件

• - L2 模块文档模板：references/l2-module-template.md
• L3 文档模板：references/l3-file-template.md
• 上下文压缩指南：references/context-compression.md
• 任务监控指南：references/task-monitoring.md
• 重试机制指南：references/retry-mechanism.md
• 二次扫描流程：references/secondary-scan.md

版本