Project Analyzer Generate Doc

Hierarchical Context 分层文档生成器 - 让 AI 理解百万行代码工程

核心原则

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

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

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

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

激活条件

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

• "生成项目文档"
• "分析工程架构"
• "创建代码索引"
• "理解这个工程"
• "为 vibecoding 准备文档"
• "Hierarchical Context"
• "三层级文档"
• "L1/L2/L3 文档"

文档层级结构

项目根目录/
├── .ai-doc/                          # 📁 默认输出目录
│   ├── project.md                    # L1: 项目级架构索引 (~10KB)
│   ├── module-a.md                   # L2: 模块级索引 (~5-15KB)
│   ├── module-b.md
│   └── project-name/
│       ├── module-a/                 # L3: 文件级文档
│       │   ├── ClassA.java.md
│       │   └── ClassB.java.md
│       └── module-b/
│           └── ...
├── .gitignore                        # 自动添加 .ai-doc/ 排除规则
├── src/
│   └── ...                           # 源代码
└── pom.xml                           # 项目配置

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

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

完整工作流程

📋 Step 0: 项目扫描与规划

# 1. 扫描所有模块
Get-ChildItem <项目路径> -Directory | Where-Object { $_.Name -notmatch 'target|.git' }

# 2. 统计每个模块的 Java 文件数
foreach ($module in $modules) {
  $count = (Get-ChildItem "$module" -Include *.java -Recurse | Measure-Object).Count
}

# 3. 制定分片策略
# - <20 文件：单子代理
# - 20-50 文件：2-3 个子代理分片
# - >50 文件：按目录拆分为多个子代理

输出: 模块列表 + 文件数统计 + 分片计划

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

核心策略:

• 每片 10-15 个文件，spawn 多个子代理并行
• 每处理 2-3 个文件 → 压缩上下文（只保留路径 +1 行摘要）
• 简单文件 (<50 行纯定义/枚举/接口) → 简化文档
• 复杂文件 → 完整 L3 文档

子代理任务模板:

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

## 源码路径
<绝对路径>

## 输出路径
D:\ai\workspace\docs\<项目名>\<模块名>\

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

## 要求
1. 为每个文件生成 L3 文档 (*.java.md)
2. 简单文件 (<50 行) → 简化文档（基本信息 + 职责）
3. 复杂文件 → 完整 L3 文档（函数签名、调用关系、关键逻辑行号）
4. **严格上下文压缩**：每处理完 2-3 个文件，压缩已处理内容的完整描述，只保留路径 +1 行摘要
5. 超时前尽可能完成更多文件
6. 完成后返回 JSON 摘要

## L3 文档模板
参考 [references/l3-template.md](references/l3-template.md)

## 返回格式
```json
{
  "module": "<模块名>",
  "chunk": "X/Y",
  "status": "completed|partial",
  "processed": ["File1.java", "File2.java"],
  "summaries": [
    {"file": "File1.java", "lines": 150, "type": "complex", "summary": "一句话摘要"}
  ]
}

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

每处理 2-3 个文件后：

• 保留：文件路径列表 + 1 行摘要/文件
• 丢弃：已生成文档的完整内容、中间思考过程、详细示例
• 目的：为后续文件腾出上下文空间

---

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

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

**核心策略**:
- 每个模块 spawn 一个子代理
- 读取该模块所有 L3 文档的**摘要**（而非完整内容）
- 汇总生成 module.md

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

```markdown
# 任务：为 <模块名> 模块生成 L2 文档

## 输入
读取 D:\ai\workspace\docs\<项目名>\<模块名>\ 目录下所有 L3 文档

## 输出
D:\ai\workspace\docs\<项目名>\<模块名>.md

## 要求
1. 读取所有 L3 文档的摘要信息（文件名、行数、类型、职责）
2. 生成 L2 模块级文档，包含：
   - 模块职责概述（200 字）
   - 文件索引表（文件路径 | 职责简述 | 复杂度 | 行数）
   - 公共 API（核心类、核心方法）
   - 依赖关系图（ASCII 或 Markdown 表格）
   - 核心流程（1-3 个关键业务流程）
   - 配置项（如有）
3. **上下文压缩**：读取 L3 时只提取关键信息，不保留完整文档内容
4. 文档大小控制在 5-15KB

## L2 文档模板
参考 [references/l2-template.md](references/l2-template.md)