# Aide 项目文档管理

你正在执行 Aide 项目文档管理流程。创建和维护面向 LLM 的项目文档。

## 前置准备

**首先触发 `aide` skill 学习 aide 命令的使用方法。**

---

## 开始

### 检查文档配置

```bash
aide config get docs.path
aide config get docs.block_plan_path
```

如果未配置，使用默认值：
- 文档目录：`.aide/project-docs`
- 区块计划：`.aide/project-docs/block-plan.md`

### 检查文档状态

检查文档目录是否存在及其内容：
- 不存在或为空 → 进入**创建流程**
- 已存在 → 进入**更新流程**

---

## 创建流程

### 阶段 1：目录探索

1. 遍历项目目录结构
2. 统计文件数量和大小
3. 识别 `.gitignore` 排除项
4. 记录关键文件（README、配置文件、入口文件等）

### 阶段 2：初步区块划分

根据以下规则划分区块：

1. **按目录结构**：每个主要目录可作为一个区块
2. **按功能模块**：相关功能的文件归为一个区块
3. **大小控制**：单个区块不超过 5000 行代码
4. **低耦合**：区块间依赖关系尽量简单

生成初步区块计划：

```markdown
# 区块计划

## 项目概况
- 项目名称：xxx
- 主要语言：xxx
- 文件总数：xxx
- 代码行数：xxx

## 区块划分

### 区块 1：[名称]
- 路径：xxx/
- 文件数：xx
- 状态：待处理

### 区块 2：[名称]
...

## 进度追踪
- [ ] 区块 1
- [ ] 区块 2
...
```

### 阶段 3：区块验证

对每个区块进行浅层探索：
1. 阅读区块内的关键文件（入口、配置、README）
2. 验证区块划分是否合理
3. 调整区块边界（如需要）

### 阶段 4：逐区块深度了解

对每个区块：

1. **完整阅读**：阅读区块内所有文件
2. **提取信息**：
   - 模块职责
   - 核心组件/类/函数
   - 对外接口
   - 依赖关系
3. **生成文档**：按子区块文档格式生成

### 阶段 5：生成总导览

整合所有区块信息，生成总导览文档。

---

## 更新流程

### 阶段 1：读取区块计划

读取现有的区块计划文档，了解当前文档结构。

### 阶段 2：分区块验证

对每个区块：
1. 对比文档与当前代码
2. 识别差异（新增、删除、修改）

### 阶段 3：增量更新

1. 更新有变化的区块文档
2. 更新总导览（如需要）
3. 更新区块计划的时间戳

---

## 文档格式规范

### 总导览文档格式

```markdown
# [项目名称] 项目导览

> 本文档面向 LLM，用于快速了解项目结构和脉络。
> 最后更新：YYYY-MM-DD

## 项目简介

[1-2 段简要描述项目目的和核心功能]

## 技术栈

- 语言：xxx
- 框架：xxx
- 主要依赖：xxx

## 架构概述

[简要描述项目架构，可包含简单的 ASCII 图]

## 区块索引

| 区块 | 路径 | 说明 |
|------|------|------|
| [区块名](./blocks/xxx.md) | xxx/ | 简要说明 |
| ... | ... | ... |

## 快速导航

- 想了解 xxx → 查看 [区块名](./blocks/xxx.md)
- 想修改 xxx → 查看 [区块名](./blocks/xxx.md)
```

### 子区块文档格式

```markdown
# [区块名称]

> 路径：xxx/
> 最后更新：YYYY-MM-DD

## 概述

[区块的职责和作用]

## 文件清单

| 文件 | 说明 |
|------|------|
| xxx.py | 简要说明 |
| ... | ... |

## 核心组件

### [组件/类/函数名]

- **职责**：xxx
- **位置**：`文件:行号`
- **关键方法**：
  - `method1()` - 说明
  - `method2()` - 说明

## 接口说明

[对外暴露的接口、API、命令等]

## 依赖关系

- 依赖：[其他区块名]
- 被依赖：[其他区块名]

## 注意事项

[开发时需要注意的点]
```

---

## 多对话续接

如果项目过大，可能需要多次对话完成：

1. 每次开始时读取区块计划
2. 找到未完成的区块
3. 继续处理
4. 更新区块计划的进度

---

## 完成

文档创建/更新完成后：

1. 确认所有区块已处理
2. 确认总导览已更新
3. 向用户汇报完成情况

```
项目文档已更新：
- 总导览：.aide/project-docs/README.md
- 区块数：N 个
- 本次更新：[新增/更新的区块列表]
```