Project Analyzer Generate Doc - Java 工程智能文档生成器

深度支持 Java/Maven/MyBatis 工程的分层文档生成器 - 让 AI 全面理解你的工程架构

核心特性

深度 Java 技术栈支持:

- MyBatis Mapper 与 XML 映射分析
Maven 依赖关系解析
Spring Boot 配置解析
复杂业务逻辑自然语言描述

智能任务管理:

- ✅ 任务状态实时跟踪
✅ 自动重试机制（最多 3 次）
✅ 断点续传支持
✅ 子代理健康检查
✅ 进度百分比报告

智能文档管理:

- 已有文档智能迁移与合并
按源码路径结构同步 MD 文档位置
重复文档内容去重与整合

细粒度分析能力:

- 方法级别业务逻辑分解
超大文件智能切分分析
完整的 Java 源码解析

核心原则

严格自底向上流程: INLINECODE0

绝不跳过任何步骤: 必须等所有 L3 完成 → 才能生成 L2 → 必须等所有 L2 完成 → 才能生成 L1

上下文压缩: 每处理 2-3 个文件自动压缩已处理内容，只保留路径 +1 行摘要

子代理分片: 大模块拆分为多个子代理并行处理，每片 8-12 个文件

激活条件

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

- "生成项目文档"
"分析工程架构"
"创建代码索引"
"理解这个工程"
"为 AI 分析准备文档"
"Java 工程文档"
"Maven 项目分析"
"MyBatis SQL 分析"
"业务逻辑文档"
"三层级文档"
"L1/L2/L3 文档"

文档层级结构

CODEBLOCK0

默认输出路径: INLINECODE1

可选自定义: 通过 -OutputPath 参数指定其他位置

完整工作流程

📋 Step 0: 项目扫描与规划

CODEBLOCK1

输出: 模块列表 + 文件数统计 + 分片计划 + 依赖关系图

📁 Step 0.5: 文档迁移与合并（如果.ai-doc 已存在，需用户确认）

目的: 整理已存在的文档，使其与源码路径结构匹配

⚠️ 安全约束: 执行任何移动/合并/删除操作前，必须明确询问用户并获得确认

CODEBLOCK2

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

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

CODEBLOCK3

⚠️ 重要安全约束:

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

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

📄 Step 1: 生成所有 L3 文件级文档

核心策略:

- 每片 8-12 个文件，spawn 多个子代理并行（减少单个代理负担）
每处理 2-3 个文件 → 压缩上下文（只保留路径 +1 行摘要）
简单文件 (<50 行纯定义/枚举/接口) → 跳过或简化文档
复杂文件 → 完整 L3 文档（包含业务逻辑自然语言描述）

⚠️ 路径规则（重要！）：

- 输出路径必须是：INLINECODE3
❌ 错误示例：.ai-doc/module/com/company/Class.java.md（缺少 src/main/java）
✅ 正确示例：INLINECODE5

子代理任务模板:

CODEBLOCK5json
{
"module": "<模块名>",
"chunk": "X/Y",
"status": "completed|partial",
"processed": ["File1.java", "File2.java"],
"skipped": ["SimpleClass.java", "EntityClass.java"],
"failed": ["ProtectedFile.java"],
"summaries": [
{"file": "File1.java", "lines": 150, "type": "complex", "summary": "一句话摘要"},
{"file": "Mapper.xml", "lines": 80, "type": "mybatis", "summary": "SQL 映射文件，包含订单相关查询"}
]
}
CODEBLOCK6

上下文压缩策略:
CODEBLOCK7

文件读取失败处理:
CODEBLOCK8

大文件处理策略:

对于超过 1000 行的超大文件：
1. 按类/方法进行切分
2. 生成多个子文档（MethodA.md, MethodB.md 等）
3. 最终合并为一个完整的文件文档

📁 Step 2: 生成所有 L2 模块级文档

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

核心策略:

- 每个模块 spawn 一个子代理
读取该模块所有 L3 文档的摘要（而非完整内容）
汇总生成 module.md
包含模块内 MyBatis 映射关系、Maven 依赖、Spring 配置

子代理任务模板:

CODEBLOCK10

摘要提取规则:

从每个 L3 文档提取：
- 文件路径
- 行数
- 文件类型（Service/Controller/Entity/Mapper/XML）
- 1 行职责描述
- 核心函数签名（仅复杂文件）
- 业务逻辑摘要

不提取：
- 完整方法实现
- 详细调用关系图
- 变更历史

🏗️ Step 3: 生成 L1 项目级文档

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

核心策略:

- spawn 一个子代理
读取所有 L2 文档的核心摘要（每模块 500 字）
汇总生成 project.md
包含项目整体架构、模块依赖、技术栈、部署架构

子代理任务模板:

CODEBLOCK12

文档模板规范

L3 文件级文档模板

详见 references/l3-template.md

核心字段:
CODEBLOCK13

L2 模块级文档模板

详见 references/l2-template.md

核心章节:
CODEBLOCK14

L1 项目级文档模板

详见 references/l1-template.md

核心章节:

# {项目名} - 系统架构

## 项目基本信息
{技术栈、架构模式、数据库、中间件}

## 核心模块索引表
| 模块名 | 职责 | 文档路径 | 文件数 | 关键词 |
|--------|------|----------|--------|--------|

## 系统架构图
{模块依赖关系，可用 Mermaid 格式}

## Maven 依赖关系
{项目间依赖、外部依赖关系图}

## MyBatis 映射概览
{各模块 SQL 映射情况汇总}

## 核心业务流程
{跨模块的核心业务流程，自然语言描述}

## 技术栈汇总
{框架、中间件、数据库}

## 部署架构
{服务部署关系，容器化情况等}

## 文档覆盖状态
{L3 文档生成统计，覆盖率}

子代理分片策略

上下文监控阈值

阈值	动作
30%	正常处理
40%

分片规则

CODEBLOCK16

上下文压缩操作

CODEBLOCK17

任务监控与重试机制

任务状态跟踪

状态文件: INLINECODE6

CODEBLOCK18

自动重试机制

重试策略:
CODEBLOCK19

重试流程:
CODEBLOCK20

子代理健康检查

检查频率: 每 60 秒

检查项目:
CODEBLOCK21

健康状态:
CODEBLOCK22

进度报告机制

报告频率: 每 5 分钟或每完成 10% 进度

报告内容:

## 📊 文档生成进度报告

**项目**: mgmt-api-cp
**开始时间**: 2026-03-05 15:30:00
**当前时间**: 2026-03-05 15:45:00
**已用时间**: 15 分钟

### 总体进度：45.5%

[████████████░░░░░░░░░░░] 45.5%
CODEBLOCK24

断点续传机制

状态保存点:

- 每完成一个分片保存一次
每 5 分钟自动保存一次
子代理启动/结束时保存

恢复流程:
CODEBLOCK25

日志记录

日志文件: INLINECODE7

日志格式:

# 任务执行日志

## 任务信息
- **项目路径**: E:\projects\mgmt-api-cp
- **开始时间**: 2026-03-05 15:30:00
- **模式**: 完整生成 (L3→L2→L1)

## 执行记录

### [15:30:00] 任务启动
- 扫描项目结构...
- 发现 7 个模块，共 312 个关键文件

### [15:31:00] 分片计划完成
- 制定 28 个分片计划
- 最大并行子代理数：8

### [15:32:00] L3 阶段开始
- Spawn 子代理：L3-ces-domain-chunk1
- Spawn 子代理：L3-ces-domain-chunk2
- ...

### [15:38:00] 子代理完成
- ✅ L3-ces-domain-chunk1 完成（12 文件）
- ✅ L3-ces-domain-chunk2 完成（12 文件）

### [15:40:00] 子代理重试
- ⚠️ L3-admin-api-chunk2 超时，准备重试（1/3）
- 等待 30 秒后重试...

### [15:41:00] 子代理重试成功
- ✅ L3-admin-api-chunk2 重试成功（12 文件）

### [15:45:00] 进度报告
- 总体进度：45.5%
- 已完成：142 文件
- 活跃子代理：5/8

...

错误处理

子代理超时

CODEBLOCK27

上下文爆炸

CODEBLOCK28

文件访问权限问题

CODEBLOCK29

模块扫描失败

CODEBLOCK30

子代理崩溃

CODEBLOCK31

配置项

在 TOOLS.md 中添加：

CODEBLOCK32

使用示例

基础用法

CODEBLOCK33

增量更新

CODEBLOCK34

断点续传

CODEBLOCK35

单模块生成

CODEBLOCK36

性能参考

生成时间估算

工程规模	L3 生成	L2 生成	L1 生成	总计
1 万行 (50 文件)	~8 分钟	~3 分钟	~2 分钟	~13 分钟
10 万行 (200 文件)

~35 分钟 | ~12 分钟 | ~3 分钟 | ~50 分钟 | | 50 万行 (500 文件) | ~3 小时 | ~45 分钟 | ~8 分钟 | ~4 小时 |

Token 消耗估算

阶段	每文件/模块	总计 (200 文件)
L3 生成	200k tokens/文件	40M tokens
L2 生成

版本

版本	日期	变更
2.1.4	2026-03-10	安全修复 (完整)：移除所有 bash/external tool 引用、移除 elevated 权限引用、修复 task-execution-guide.md 中的不安全指令
2.1.3

2026-03-10 | 安全修复：移除提权/bash 引用、明确要求用户确认删除/迁移操作 | | 2.1.2 | 2026-03-09 | 文档描述优化、移除模糊指令 | | 2.1.1 | 2026-03-08 | SKILL.md 编码修复、文档格式优化 | | 2.1.0 | 2026-03-05 | 增强任务监控、重试机制、健康检查、断点续传 | | 2.0.0 | 2026-03-05 | 重大更新，增加 Java 特定支持、MyBatis 分析、文档迁移合并 | | 1.1.0 | 2026-03-03 | 添加断点续传、增量更新、L1 样例 | | 1.0.0 | 2026-03-03 | 初始版本，基于 Infypower Energy AI 项目实战经验 |

Project Analyzer Generate Doc - Java 工程智能文档生成器

深度支持 Java/Maven/MyBatis 工程的分层文档生成器 - 让 AI 全面理解你的工程架构

核心特性

深度 Java 技术栈支持:

- MyBatis Mapper 与 XML 映射分析
Maven 依赖关系解析
Spring Boot 配置解析
复杂业务逻辑自然语言描述

智能任务管理:

- ✅ 任务状态实时跟踪
✅ 自动重试机制（最多 3 次）
✅ 断点续传支持
✅ 子代理健康检查
✅ 进度百分比报告

智能文档管理:

- 已有文档智能迁移与合并
按源码路径结构同步 MD 文档位置
重复文档内容去重与整合

细粒度分析能力:

- 方法级别业务逻辑分解
超大文件智能切分分析
完整的 Java 源码解析

核心原则

严格自底向上流程: L3 (所有文件) → L2 (所有模块) → L1 (项目全局)

绝不跳过任何步骤: 必须等所有 L3 完成 → 才能生成 L2 → 必须等所有 L2 完成 → 才能生成 L1

上下文压缩: 每处理 2-3 个文件自动压缩已处理内容，只保留路径 +1 行摘要

子代理分片: 大模块拆分为多个子代理并行处理，每片 8-12 个文件

激活条件

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

- 生成项目文档
分析工程架构
创建代码索引
理解这个工程
为 AI 分析准备文档
Java 工程文档
Maven 项目分析
MyBatis SQL 分析
业务逻辑文档
三层级文档
L1/L2/L3 文档

文档层级结构

项目根目录/
├── .ai-doc/ # 📁 默认输出目录
│ ├── .generate-state.json # 📊 任务状态文件（断点续传）
│ ├── .task-log.md # 📝 执行日志
│ ├── project.md # L1: 项目级架构索引 (~10KB)
│ ├── module-a.md # L2: 模块级索引 (~5-15KB)
│ ├── module-b.md
│ └── <模块名>/ # L3: 文件级文档
│ ├── src/main/java/com/company/ModuleClass.java.md
│ ├── src/main/resources/mapper/ModuleMapper.xml.md
│ └── ...
├── src/
│ └── ... # 源代码
└── pom.xml # 项目配置

默认输出路径: <项目根目录>/.ai-doc/

可选自定义: 通过 -OutputPath 参数指定其他位置

完整工作流程

📋 Step 0: 项目扫描与规划

powershell

1. 扫描所有模块 (排除 target, .git, build 等临时目录)

Get-ChildItem <项目路径> -Directory | Where-Object { $.Name -notmatch target|\.git|build|dist|nodemodules }

2. 统计每个模块的关键文件数

$javaFiles = Get-ChildItem $module -Include *.java -Recurse | Measure-Object $xmlFiles = Get-ChildItem $module -Include *.xml -Recurse | Where-Object { $_.Name -match mapper|Mapper } | Measure-Object $propertiesFiles = Get-ChildItem $module -Include .properties,.yml,*.yaml -Recurse | Measure-Object

3. 解析 Maven 依赖 (读取 pom.xml)

$dependencyTree = @() foreach ($pom in Get-ChildItem $module -Include pom.xml -Recurse) { [xml]$pomXml = Get-Content $pom.FullName $dependencyTree += $pomXml.project.dependencies.dependency }

4. 制定分片策略

- <15 文件：单子代理

- 15-40 文件：2-3 个子代理分片

- >40 文件：按目录拆分为多个子代理

输出: 模块列表 + 文件数统计 + 分片计划 + 依赖关系图

📁 Step 0.5: 文档迁移与合并（如果.ai-doc 已存在，需用户确认）

目的: 整理已存在的文档，使其与源码路径结构匹配

⚠️ 安全约束: 执行任何移动/合并/删除操作前，必须明确询问用户并获得确认

powershell

1. 扫描.ai-doc 目录下的所有.md 文件

$existingDocs = Get-ChildItem <项目路径>/.ai-doc -Include *.md -Recurse

2. 根据文档路径推断对应的源码路径

$migrationPlan = @() foreach ($doc in $existingDocs) { $relativePath = $doc.FullName.Replace(<项目路径>/.ai-doc\, ) $expectedSourcePath = $relativePath.Replace(.md, )

# 3. 查找实际源码路径是否存在
$actualSourcePath = $null
foreach ($extension in @(.java, .xml, .kt, .scala)) {
$potentialPath = <项目路径>\$expectedSourcePath$extension
if (Test-Path $potentialPath) {
$actualSourcePath = $potentialPath
break
}
}

# 4. 如果源码路径不存在，尝试模糊匹配
if (!$actualSourcePath) {
# 在整个项目中查找同名文件
$matches = Get-ChildItem <项目路径> -Include $expectedSourcePath -Recurse
if ($matches.Count -eq 1) {
$actualSourcePath = $matches[0].FullName
}
}

# 5. 如果找到对应的源码路径，验证路径是否正确
if ($actualSourcePath) {
$correctDocPath = $actualSourcePath.Replace(<项目路径>\, <项目路径>/.ai-doc\) + .md

if ($doc.FullName -ne $correctDocPath) {
$migrationPlan += @{
Source = $doc.FullName
Destination = $correctDocPath
Action = if (Test-Path $correctDocPath) { merge } else { move }
}
}
}
}

6. 向用户展示迁移计划，请求确认

if ($migrationPlan.Count -gt 0) { Write-Host 发现 $($migrationPlan.Count) 个文档需要迁移/合并: foreach ($plan in $migrationPlan) { Write-Host $($plan.Action): $($plan.Source) → $($plan.Destination) }

# ⚠️ 必须获得用户明确确认
$confirm = Read-Host 是否执行迁移计划？(y/n)
if ($confirm -eq y) {
foreach ($plan in $migrationPlan) {
$targetDir = Split-Path $plan.Destination -Parent
if (!(Test-Path $targetDir)) {
New-Item -ItemType Directory -Path $targetDir -Force
}

if ($plan.Action -eq merge) {
$existingContent = Get-Content $plan.Destination -Raw
$newContent = Get-Content $plan.Source -Raw
$mergedContent = Merge-Documents $existingContent $newContent
Set-Content -Path $plan.Destination -Value $mergedContent
Remove-Item $plan.Source
} else {
Move-Item -Path $plan.Source -Destination $plan.Destination
}
}
} else {
Write-Host 用户取消迁移，保持文档原位置
}
}

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

project-analyzer-generate-doc项目文档生成器