project-analyzer-generate-doc

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

# project-analyzer-generate-doc Skill

> Java Maven 工程智能文档生成器 - 让 AI 全面理解你的工程架构

---

## 📖 简介

本 Skill 通过**自底向上**的完整流程（L3 → L2 → L1），为 Java/Maven/MyBatis 工程生成三层级文档索引：

- **L3 文件级**: 每个 Java/XML 文件生成详细业务逻辑文档
- **L2 模块级**: 汇总模块内所有文件，生成模块架构文档
- **L1 项目级**: 汇总所有模块，生成系统架构全景文档

**核心优势**:
- ✅ 深度支持 Java 技术栈（MyBatis、Maven、Spring Boot）
- ✅ 任务状态实时跟踪与监控
- ✅ 自动重试机制（最多 3 次）
- ✅ 断点续传支持
- ✅ 子代理健康检查
- ✅ 进度百分比报告
- ✅ 智能文档迁移与合并
- ✅ 使用子代理分片策略，规避上下文限制
- ✅ 严格的上下文压缩，确保任务稳定性

---

## 🚀 快速开始

### 环境要求

| 工具 | 版本 | 用途 |
|------|------|------|
| PowerShell | 5.1+ | 执行脚本 |
| Git | 2.x+ | 增量更新检测 |
| OpenClaw | 最新 | 子代理调度 (sessions_spawn) |
| Java | 17+ | 目标项目语言 (可选) |

### 激活方式

**方式 1: 直接对话激活**
```
用户：为 E:\projects\mgmt-api-cp 生成业务逻辑文档

AI: 收到！开始执行完整流程...
```

**方式 2: 指定输出路径**
```
用户：为 E:\projects\mgmt-api-cp 生成文档，输出到 D:\docs\mgmt-api-cp

AI: 收到！文档将生成到 D:\docs\mgmt-api-cp\.ai-doc\
```

### 完整流程

```
1. 扫描项目结构（统计模块和文件数）
2. 检查.ai-doc 目录，执行文档迁移合并（如果存在）
3. 制定分片计划（大模块拆分为多个子代理）
4. 并行生成 L3 文档（每片 8-12 文件，严格上下文压缩）
5. 汇总生成 L2 文档（所有 L3 完成后）
6. 生成 L1 文档（所有 L2 完成后）
7. Git 提交文档（可选）
```

---

## 📁 文件结构

```
project-analyzer-generate-doc/
├── SKILL.md                          # 主技能文档
├── README.md                         # 使用说明
├── templates/                        # 文档模板
│   ├── l1-template.md
│   ├── l2-template.md
│   ├── l3-template.md
│   └── gitignore-template.txt
├── references/                       # 参考指南
│   ├── context-compression.md
│   ├── checkpoint-resume.md
│   ├── incremental-update.md
│   └── subagent-task-template.md
├── examples/...