module-analyzer-generate-doc

---
name: module-analyzer-generate-doc
description: Java/Maven single-module deep documentation generator. Generates L3(file-level) to L2(module-level) business logic docs for specified module. Supports multi-subagent parallel processing, context compression, checkpoint resume, and auto-retry.
---

# 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 三层文档
- `module-analyzer-generate-doc`：单模块深度扫描，生成 L3→L2 两层文档（更详细、更快速）

---

## 完整工作流程

### Step 0: 模块扫描与规划

```powershell
# 1. 扫描模块目录结构
Get-ChildItem "<模块路径>" -Directory -Recurse | Where-Object { $_.Name -notmatch 'target|\.git|build' }

# 2. 统计 Java 文件
$javaFiles = Get-ChildItem "<模块路径>/src/main/java" -Include *.java -Recurse | Where-Object { $_.FullName -notmatch '\\test\\' }

# 3. 统计 XML 文件（MyBatis Mapper）
$xmlFiles = Get-ChildItem "<模块路径>/src/main/resources" -Include *.xml -Recurse | Where-Object { $_.Name -match 'mapper|Mapper' }

# 4. 检查已存在文档
$existingDocs = Get-ChildItem "<项目根目录>/.ai-doc/<模块名>" -Include *.md -Recurse 2>$null

# 5. 制定分片计划
# - <20 文件：单子代理
# - 20-50 文件：3-4 个子代理分片
# - >50 文件：5-6 个子代理分片，每片 10-16 个文件
```

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

---

### Step 0.5: 已存在文档处理

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

```markdown
检查规则:
1. 文档路径是否符合 `.ai-doc/模块名/src/main/java/包路径/类名.java.md` 规则
2. 文档内容是否包含详细业务逻辑描述（非简单解释）
3. 文档是否包含代码片段（应全部为自然语言）

处理策略:
- 路径不符合 → 迁移到正确位置
- 内容过于简单 → 重新生成
- 内容符合要求 → 保留，不重复生成
- 源码已变更 → 更新文档
```

---

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

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

```powershell
# 1. 识别低质量文档（只有模板框架，无实际业务内容）
$lowQualityDocs = Get-ChildItem "<项目根目录>/.ai-doc/<模块名>" -Include *.md -Recurse | Where-Object {
    $content = Get-Content $_.FullName -Raw
    $lineCount = (Get-Content $_.FullName).Count
    # 行数少于 20 行
    $lineCount -lt 20 -or
    # 只包含模板框架文字
    $content -match 'Business component - participates in system business processing' -or
    $content -match 'Executes business logic based on specific scenario' -or
    $content -match 'Simple data object' -or
    $content -match 'Interface definition - declares contract specification'
}
# 输出报告，供用户决定是否处理
foreach ($doc in $lowQualityDocs) {
    Write-Host "低质量文档：$($doc.FullName)"
}

# 2. 识别空文件夹（供用户参考）
Get-ChildItem "<项目根目录>/.ai-doc/<模块名>" -Directory -Recurse | ForEach-Object {
    if ((Get-ChildItem $_.FullName -Force).Count -eq 0) {
        Write-Host "空目录：$($_.FullName)"
    }
}
```

**⚠️ 重要安全约束**:
- 此步骤**仅生成报告**，绝不自动删除任何文件
- 如需处理低质量文档，必须**明确询问用户并获得确认**
- 删除操作示例（仅当用户明确同意时执行）:
  ```powershell
  # 询问用户确认
  $confirm = Read-Host "是否删除 $($lowQualityDocs.Count) 个低质量文档？(y/n)"
  if ($confirm -eq "y") {
      # 移动到回收站而非直接删除（如果可能）
      foreach ($doc in $lowQualityDocs) {
          Write-Host "将移动到回收站：$($doc.FullName)"
      }
  }
  ```

---

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

**子代理分片策略**:

| 文件总数 | 子代理数 | 每片文件数 | 超时时间 |
|----------|----------|------------|----------|
| <20 | 1 | 全部 | 300 秒 |
| 20-50 | 3-4 | 10-16 | 600 秒 |
| 50-80 | 5 | 12-18 | 900 秒 |
| >80 | 6-8 | 10-14 | 900 秒 |

**子代理任务模板**:

```markdown
# 任务：为 <模块名> 模块生成 L3 文档（分片 X/Y）

## 项目路径
<绝对路径>

## 源码根目录
<模块路径>/src/main/java

## 输出目录
<项目根目录>/.ai-doc/<模块名>/

## 本分片文件列表
<文件列表，10-16 个>

## 核心要求

### 1. 文档内容要求
- **详细业务逻辑描述**：将代码逻辑转换为自然语言，非程序员也能理解
- **不包含代码片段**：MD 文件中不要出现任何原代码
- **方法级别分析**：每个有业务逻辑的方法都要描述其执行流程、业务语义
- **领域知识**：解释涉及的业务概念、领域术语
- **流程上下文**：方法间的调用关系、数据流转
- **设计意图**：为什么这样设计，解决什么问题

### 2. 文档路径规则（⚠️ 重要！）
- 源文件：`<模块路径>/src/main/java/包路径/类名.java`
- 文档：`<项目根目录>/.ai-doc/<模块名>/src/main/java/包路径/类名.java.md`
- **⚠️ 必须包含 `src/main/java/` 完整路径！**
- **❌ 错误示例**：`.ai-doc/app-api/com/infypower/...`（缺少 src/main/java）
- **✅ 正确示例**：`.ai-doc/app-api/src/main/java/com/infypower/...`
- 生成文档前必须检查路径是否正确，错误路径的文档会被视为无效

### 3. 跳过规则（⚠️ 严格执行！）

**必须跳过的文件类型**（满足任一条件即跳过）：

| 类型 | 判断标准 | 示例 |
|------|----------|------|
| **DTO/VO/Param** | 类名以 DTO/VO/Param/BO 结尾，且行数<50，且不包含方法（除 getter/setter） | UserDTO.java, LoginVO.java |
| **枚举** | 包含 `enum` 关键字，且不包含复杂方法 | PaymentStatus.java |
| **常量类** | 类名包含 Constant，且只包含 `public static final` 字段 | AppApiConstant.java |
| **接口** | 包含 `public interface`，且无方法实现 | UserService.java |
| **MapStruct Converter** | 包含 `@Mapper` 注解，或接口名包含 Converter | UserConverter.java |
| **抽象基类** | 包含 `public abstract class`，且方法都是抽象的 | AbstractHandler.java |
| **测试类** | 类名包含 Test，或包含 `@Test` 注解 | UserServiceTest.java |

**代码特征检查**（满足任一条件即跳过）：
```
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"

**自检示例**：
```markdown
# ❌ 低质量文档（需要重新生成）
## Business Responsibility
Business component - participates in system business processing

## Core Business Logic
Executes business logic based on specific scenario

# ✅ 合格文档（正确示例）
## 业务职责
AuthService 是认证服务核心类，处理用户账户的创建、更新、查询，
以及支付宝授权码验证和加密手机号解密。当用户通过小程序授权登录时，
该类负责从微信/支付宝获取用户信息，创建或更新本地用户账户...

## 核心业务逻辑
### 支付宝授权码验证
触发条件：用户在小程序点击授权登录，前端传入 auth_code
处理流程：
1. 调用支付宝 API 换取用户 open_id
2. 验证返回的 open_id 是否有效
3. 根据 open_id 查询本地用户...
```

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

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

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

## L3 文档模板

```markdown
# {类名} - 业务逻辑详解

## 基本信息
- **文件路径**: {relativePath}
- **行数**: {lines}
- **文件类型**: {Config/Controller/Service/ServiceImpl/Interceptor/Handler/Util}
- **所属模块**: {moduleName}

## 业务职责
{用自然语言描述这个类的业务职责，200-300 字}

## 核心业务逻辑

### {方法/功能点 1}
{详细描述该功能的业务逻辑流程，包括：
- 触发条件
- 输入数据处理
- 业务规则判断
- 数据流转过程
- 输出结果
- 异常情况处理
}

### {方法/功能点 2}
{同上}

## 业务流程
{描述方法间的调用关系和业务流转过程}

## 数据交互
{描述与数据库、外部服务、Redis、MQ 等的交互}

## 依赖关系
{该类依赖的其他组件和服务}

## 设计意图
{解释为什么这样设计，解决了什么业务问题}
```

## 返回格式

```json
{
  "chunk": "X/Y",
  "status": "completed|partial",
  "processed": ["File1.java", ...],
  "skipped": ["SimpleClass.java", ...],
  "failed": [],
  "summaries": [
    {"file": "File1.java", "lines": 150, "type": "Controller", "summary": "一句话业务摘要"}
  ]
}
```
```

**上下文压缩策略**:

```
每处理 2-3 个文件后：
保留：
- 文件路径列表
- 每文件 1 行摘要
- 当前任务描述
- 输出路径
- 进度统计

丢弃：
- 已生成文档的完整内容
- 中间思考过程
- 详细示例
- 完整函数体
```

---

### Step 2: 生成 L2 模块级文档

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

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

**L2 文档模板**:

详见 [references/l2-module-template.md](references/l2-module-template.md)

**核心章节**:

```markdown
# {模块名} - 模块详解

## 模块职责
{200-300 字概述模块的业务定位和核心价值}

## 文件索引表
| 文件路径 | 职责简述 | 类型 | 行数 |
|----------|----------|------|------|
{列出所有已生成 L3 文档的文件}

## 核心业务流程

### 1. {核心流程 1}
{详细描述跨类的业务流程，如用户认证授权流程}

### 2. {核心流程 2}
{如数据权限隔离流程}

### 3. {核心流程 3}
{如系统管理功能流程}

## MyBatis 映射关系
{SQL 与 Java 方法的映射关系，核心表说明}

## 模块依赖
- **内部依赖**: 依赖的其他模块
- **外部服务**: Redis/MySQL/Apollo/RabbitMQ/XXL-Job 等
- **框架依赖**: Spring Boot/MyBatis-Plus/Spring Security 等

## 配置项汇总
{application 配置文件的主要设置，按功能分类}

## 技术栈
{使用的框架和技术组件清单}
```

---

## 任务监控与重试机制

### 状态文件

**路径**: `<项目根目录>/.ai-doc/.generate-state.json`

**内容**:
```json
{
  "version": "1.0.0",
  "projectPath": "<项目根目录>",
  "targetModule": "<模块名>",
  "startTime": "2026-03-07T10:17:00+08:00",
  "currentPhase": "L3",
  "overallProgress": 76.5,
  "phases": {
    "L3": {
      "status": "completed|in_progress|pending",
      "totalFiles": 81,
      "processedFiles": 62,
      "skippedFiles": 19,
      "failedFiles": 0,
      "chunks": {
        "total": 5,
        "completed": 5,
        "inProgress": 0,
        "pending": 0,
        "failed": 0
      }
    },
    "L2": {
      "status": "completed|in_progress|pending",
      "totalModules": 1,
      "completedModules": 0
    }
  },
  "subagents": [
    {
      "label": "L3-chunk1",
      "status": "completed|running|failed|timeout",
      "files": 16,
      "startTime": "...",
      "endTime": "..."
    }
  ],
  "lastCheckpoint": "2026-03-07T10:40:00+08:00",
  "canResume": true
}
```

### 重试策略

```yaml
retry_policy:
  max_retries: 3                    # 最大重试次数
  initial_delay: 30                 # 初始延迟（秒）
  backoff_multiplier: 2             # 延迟倍增因子
  max_delay: 300                    # 最大延迟（秒）
  retryable_errors:
    - "timeout"
    - "context_overflow"
    - "file_access_error"
    - "subagent_crash"
```

### 进度汇报

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

**内容**:
```markdown
## 📊 文档生成进度报告

**模块**: 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
```

---

## 二次扫描查漏

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

**流程**:
```powershell
# 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
}
```

---

## 错误处理

### 子代理超时

```
问题：子代理处理大模块时超时

解决:
1. 检查已生成的文件
2. 将剩余文件拆分为更小的分片（每片 5-7 个文件）
3. 增加超时时间到 15 分钟
4. 重新 spawn 子代理，传递已完成进度
```

### 上下文爆炸

```
问题：子代理上下文使用率超过 60%

解决:
1. 立即触发强制压缩
2. 如果仍超过 60%，停止当前子代理
3. 将剩余文件拆分为更小的分片
4. 为新分片 spawn 新的子代理
5. 增加压缩频率（每 1 个文件就压缩）
```

### 文件访问权限问题

```
问题：文件因权限限制无法读取

解决:
1. 记录无法访问的文件到日志
2. 请求用户确认文件访问权限
3. 在最终报告中标注无法访问的文件
4. ⚠️ 禁止尝试提权、bash 工具或其他替代读取方式
5. 如果重试 3 次仍失败，跳过该文件
```

---

## 配置项

在 `TOOLS.md` 中添加：

```markdown
### Module Analyzer - Java 单模块深度文档生成器

- 默认分片大小：10-16 文件/子代理
- 最大并行：5-6 子代理
- 上下文阈值：40% 预警，50% 强制压缩
- 压缩频率：每处理 2-3 个文件
- 简单文件阈值：50 行
- 超时时间：300-900 秒（根据分片大小）
- 重试策略：最多 3 次，指数退避
- 进度汇报：每 20 分钟
- 断点续传：自动保存状态
- 文件读取失败处理：记录并重试
- 二次扫描：自动查漏补充
```

---

## 使用示例

### 基础用法

```
用户：分析 E:\projects\mgmt-api-cp 的 admin-api 模块，生成业务逻辑文档

AI: 收到！开始执行单模块深度分析流程：

Step 0: 扫描 admin-api 模块结构...
  📊 发现 81 个 Java 文件，1 个 XML 文件

Step 0.5: 检查已存在文档...
  ✅ 发现 20 个已有文档，检查内容质量

Step 1: 生成 L3 文件级文档（5 个子代理并行）...
  📊 进度：62/81 文件已处理
  🔄 活跃子代理：5/5
  ⏱️ 预计剩余时间：15 分钟

Step 2: 生成 L2 模块级文档...
  ✅ admin-api.md 生成完成（26KB）

二次扫描：查漏补充...
  ✅ 所有业务类都有文档可依

✅ 完成！生成 62 个 L3 文档 + 1 个 L2 模块文档
```

### 带已有文档的增量更新

```
用户：ces-domain 模块有代码变更，更新文档

AI: 收到！执行增量更新流程：

1. 检测变更文件（git diff 或时间戳比较）
2. 检查已存在文档质量
3. 只更新变更文件的 L3 文档
4. 重新汇总生成 ces-domain.md (L2)

注意：保持文档路径与源码路径一致
```

### 断点续传

```
用户：继续之前的文档生成任务

AI: 检测到未完成的生成任务...

## 上次任务状态
- 模块：admin-api
- 中断时间：2026-03-07 10:30:00
- 完成进度：L3 阶段 76.5% (62/81 文件)
- 失败分片：1 个（已重试 2 次）

是否从断点继续？(y/n)

用户：y

AI: 恢复任务...
- 跳过已完成的 62 个文件
- 重新处理 1 个失败分片
- 继续生成剩余 19 个文件的 L3 文档
```

---

## 性能参考

### 生成时间估算

| 模块规模 | L3 生成 | L2 生成 | 总计 |
|----------|---------|---------|------|
| 20 文件 | ~5 分钟 | ~2 分钟 | ~7 分钟 |
| 50 文件 | ~12 分钟 | ~4 分钟 | ~16 分钟 |
| 80 文件 | ~20 分钟 | ~5 分钟 | ~25 分钟 |
| 150 文件 | ~40 分钟 | ~8 分钟 | ~48 分钟 |

### Token 消耗估算

| 阶段 | 每文件/模块 | 总计 (80 文件) |
|------|-------------|---------------|
| L3 生成 | 200k tokens/文件 | 16M tokens |
| L2 生成 | 350k tokens/模块 | 350k tokens |

---

## 相关文件

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

---

## 版本

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.3 | 2026-03-10 | **安全修复 (最终)**：移除 python 代码块引用、移除"必须执行"强制指令、完整清理所有风险关键词 |
| 1.0.2 | 2026-03-10 | **安全修复 (完整)**：移除所有 bash/external tool 引用、移除 elevated 权限引用、明确要求用户确认删除/迁移操作 |
| 1.0.1 | 2026-03-10 | **安全修复**：移除提权/bash 引用、明确要求用户确认删除操作 |
| 1.0.0 | 2026-03-07 | 初始版本，基于 admin-api 模块实战经验 |