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: 模块扫描与规划

# 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: 已存在文档处理

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

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

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

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

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

# 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)"
    }
}

⚠️ 重要安全约束:

此步骤仅生成报告，绝不自动删除任何文件
如需处理低质量文档，必须明确询问用户并获得确认

删除操作示例（仅当用户明确同意时执行）:

# 询问用户确认
$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 秒

子代理任务模板:

# 任务：为 <模块名> 模块生成 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 |

**代码特征检查**（满足任一条件即跳过）：

文件行数 < 30 行
不包含以下关键字：if, for, while, switch, try, catch, return（getter/setter 除外）
只包含字段定义和 @ 注解
方法体都是空的（只有分号或 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 文档模板

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

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

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

## 核心业务逻辑

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

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

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

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

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

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

返回格式

{
  "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

内容:

{
  "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
}

重试策略

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 分钟或每完成一个分片

内容:

## 📊 文档生成进度报告

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

错误处理

子代理超时

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

解决:
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 中添加：

### 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

版本

版本	日期	变更
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 模块实战经验

Module Analyzer Generate Doc

Description

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 单模块深度文档生成器

核心特性

激活条件

完整工作流程

Step 0: 模块扫描与规划

Step 0.5: 已存在文档处理

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

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

5. 上下文管理

5. 上下文管理

6. 文件读取失败处理

L3 文档模板

返回格式

任务监控与重试机制

状态文件

重试策略

进度汇报

二次扫描查漏

错误处理

子代理超时

上下文爆炸

文件访问权限问题

配置项

使用示例

基础用法

带已有文档的增量更新

断点续传

性能参考

生成时间估算

Token 消耗估算

相关文件

版本

Reviews (0)

Comments (0)

Compatible Platforms

Links

Pricing

Related Configs

self-improving-agent

Self Improving Agent

Find Skills

Summarize