sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4a0759e36c04e626171aeb8a82d06ab175990ec9
agent-aide/aide-marketplace/aide-plugin/commands/docs.md

12 KiB
Raw Blame History

Aide 项目文档管理

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

核心原则

完全深度探索：不考虑过度设计、开销、效率问题。对项目中的每一个文件、每一个目录（包括空目录）都要完全覆盖，不允许遗漏。

分步执行机制

此命令支持真正有效的分步执行和接续执行，适用于任意规模项目（包括百万行代码级别）。

设计原则

  1. 索引式计划文档：block-plan.md 只做索引，详细信息存在独立步骤文档中
  2. 自包含步骤文档：每个步骤包含执行所需的全部信息，接续执行无需重新分析
  3. 粒度动态控制：根据区块大小动态拆分步骤，确保单次对话可完成
  4. 分析与执行分离：分析阶段产出详细计划，执行阶段直接产出

文档结构

.aide/project-docs/
├── README.md              # 总导览
├── block-plan.md          # 区块计划（索引式）
├── steps/                 # 步骤详情目录
│   ├── step-001.md        # 步骤1详情
│   ├── step-002.md        # 步骤2详情
│   └── ...
└── blocks/                # 区块文档
    ├── block-1.md
    └── ...

前置准备

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

这是一个非常长的任务，因此规划您的工作可能会很有益。**建议花费您的整个输出上下文来处理任务 - 只需确保您不会在有大量未提交的工作时用尽上下文。**继续系统地工作，直到您完成此任务。**您的上下文窗口将在接近其限制时自动压缩，允许您从中断的地方继续无限期地工作。因此，不要因为令牌预算问题而提前停止任务。**当您接近令牌预算限制时，在上下文窗口刷新前将您当前的进度和状态保存到内存中。始终尽可能坚持和自主，并完全完成任务，即使您的预算即将用尽。无论剩余上下文如何，永远不要人为地提前停止任何任务。

开始

检查文档配置

aide config get docs.path
aide config get docs.block_plan_path
aide config get docs.steps_path

如果未配置，使用默认值：

  • 文档目录：.aide/project-docs
  • 区块计划：.aide/project-docs/block-plan.md
  • 步骤目录：.aide/project-docs/steps

检查文档状态

检查区块计划文件是否存在：

  • 不存在 → 进入创建流程
  • 已存在 → 进入接续流程

创建流程

阶段 1：完整目录扫描

此阶段必须完整执行，不允许跳过任何目录或文件。

1.1 读取忽略规则

读取项目根目录的 .gitignore 文件，解析忽略规则。

1.2 递归遍历所有目录

使用 find 或类似命令遍历项目所有目录和文件：

# 获取完整目录树（排除 .git）
find . -not -path './.git/*' -not -name '.git' | sort

必须记录的信息：

  • 每个目录（包括空目录）
  • 每个文件的路径
  • 文件大小
  • 文件类型（源码/配置/文档/二进制/其他）

1.3 生成目录树结构

生成完整目录结构，对于 .gitignore 中的项目标注 [ignored]。

1.4 统计项目信息

- 总目录数：xx（含 xx 个空目录）
- 总文件数：xx
- 源码文件：xx
- 被忽略项：xx
- 代码行数：约 xxx 行

阶段 2：区块划分

根据以下规则划分区块：

  1. 按目录结构：每个主要目录可作为一个区块
  2. 按功能模块：相关功能的文件归为一个区块
  3. 包含空目录：空目录也要归入相应区块
  4. 低耦合：区块间依赖关系尽量简单
  5. 完整覆盖：每个非忽略的子目录都必须归入某个区块

阶段 3：步骤生成（关键阶段）

这是实现有效分步执行的核心阶段。

3.1 评估区块复杂度

对每个区块评估：

复杂度 文件数 代码行数 处理方式
小 <20 <2000 整个区块作为 1 个步骤
中 20-100 2000-10000 按子目录拆分为 2-5 个步骤
大 100-500 10000-50000 按文件组拆分为 5-15 个步骤
超大 >500 >50000 按单文件或小文件组拆分

3.2 生成步骤文档

为每个步骤生成独立的步骤文档，存放在 steps/ 目录。

步骤文档格式：

# 步骤 XXX：[区块名] - [子任务描述]

## 元信息

| 属性 | 值 |
|------|-----|
| 状态 | pending / in_progress / completed |
| 所属区块 | [区块名] |
| 预估工作量 | 小 / 中 / 大 |
| 依赖步骤 | [无 / step-XXX] |

## 任务描述

完全深度探索以下文件/目录，生成/更新区块文档中的相应部分。

## 目标文件清单

| 文件路径 | 类型 | 大小 | 状态 |
|----------|------|------|------|
| `path/to/file1.py` | 源码 | 150行 | - |
| `path/to/file2.py` | 源码 | 200行 | - |
| `path/to/subdir/` | 目录 | 5文件 | - |
| ... | ... | ... | ... |

## 已知上下文

（在分析阶段填写，供执行时参考）

### 目录结构

[该步骤涉及的目录结构]


### 关键信息
- [已知的模块职责]
- [已知的依赖关系]
- [需要特别注意的点]

## 输出要求

- 更新文件：`blocks/[区块名].md`
- 更新内容：
  - [ ] 文件清单中的文件概述
  - [ ] 核心组件说明
  - [ ] 目录树对应部分

## 执行记录

（执行时填写）

| 时间 | 操作 | 备注 |
|------|------|------|
| | 开始执行 | |
| | 完成 | |

3.3 生成区块计划（索引）

生成 block-plan.md 作为索引：

# 区块计划

> 最后更新：YYYY-MM-DD HH:MM

## 项目概况

- 项目名称：xxx
- 主要语言：xxx
- 文件总数：xxx（含 xx 被忽略）
- 空目录数：xxx
- 代码行数：xxx

## 目录树（简化版）

[前两层目录结构]


## 区块索引

| # | 区块名 | 路径 | 文件数 | 步骤数 | 状态 | 步骤范围 |
|---|--------|------|--------|--------|------|----------|
| 1 | core | src/core/ | 25 | 3 | pending | 001-003 |
| 2 | utils | src/utils/ | 45 | 5 | pending | 004-008 |
| ... | ... | ... | ... | ... | ... | ... |

## 步骤索引

| 步骤 | 所属区块 | 描述 | 状态 |
|------|----------|------|------|
| [001](steps/step-001.md) | core | 分析 core 主模块 | pending |
| [002](steps/step-002.md) | core | 分析 core/parser | pending |
| [003](steps/step-003.md) | core | 分析 core/executor | pending |
| [004](steps/step-004.md) | utils | 分析 utils/helper | pending |
| ... | ... | ... | ... |

## 整体进度

- 总步骤数：XX
- 已完成：0
- 进行中：0
- 待处理：XX

## 执行日志

| 时间 | 步骤 | 操作 | 备注 |
|------|------|------|------|
| | | | |

阶段 4：用户确认

向用户展示计划摘要：

区块计划已生成。

区块数：X 个 总步骤数：Y 个 预估：约需 Z 次对话完成

步骤文档已生成在 steps/ 目录，每个步骤包含完整的执行信息。

是否开始执行？

选项：

  • 开始执行（推荐）
  • 查看计划详情
  • 稍后执行

接续流程

当区块计划已存在时执行此流程。

1. 读取区块计划

读取 block-plan.md 获取：

  • 步骤索引
  • 整体进度
  • 执行日志

2. 显示进度

项目文档进度

总步骤数：XX 已完成：YY（ZZ%） 当前步骤：step-NNN 上次更新：YYYY-MM-DD HH:MM

3. 确认继续

使用 AskUserQuestion：

是否从当前进度继续执行？

选项：

  • 继续执行（推荐）
  • 查看待处理步骤
  • 重新开始（清空进度）

步骤执行流程

执行单个步骤

  1. 读取步骤文档：

    • 打开 steps/step-XXX.md
    • 获取目标文件清单和已知上下文

  2. 完全深度探索：

    • 按清单逐个阅读文件（从头到尾，不遗漏任何一行）
    • 应用文件处理规则（见下文）

  3. 生成/更新区块文档：

    • 更新 blocks/[区块名].md 的相应部分
    • 更新文件清单中的文件状态

  4. 更新步骤文档：

    • 标记步骤为 completed
    • 填写执行记录

  5. 更新区块计划：

    • 更新步骤状态
    • 更新整体进度
    • 添加执行日志

文件处理规则

文件类型 处理方式
源码文件 完整阅读，分析逻辑和结构，提取核心信息
配置文件 完整阅读，记录关键配置项
文档文件 完整阅读，提取主要内容
二进制文件 根据文件名、大小、关联文件信息进行上下文推断
被忽略文件 只记录文件名/目录名，标注 [ignored]
空目录 记录目录名，标注 [空目录]，根据名称推断用途

步骤间询问

每完成一个步骤后：

步骤 XXX 已完成：[描述]

已完成：YY/ZZ（进度 WW%）

是否继续下一步？

选项：

  • 继续（推荐）
  • 查看产出
  • 暂停（保存进度）

如选择暂停，当前进度已保存在步骤文档和区块计划中，下次可直接接续。

区块文档格式

每个区块生成独立文档 blocks/[区块名].md：

# [区块名称]

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

## 概述

[区块的职责和作用]

## 目录结构

xxx/ ├── module1/ │ ├── init.py │ └── core.py ├── empty_dir/ [空目录] └── README.md


## 文件清单

| 文件 | 类型 | 行数 | 说明 |
|------|------|------|------|
| module1/__init__.py | 源码 | 10 | 模块初始化 |
| module1/core.py | 源码 | 150 | 核心逻辑实现 |
| empty_dir/ | 目录 | - | [空目录] 用途推断 |
| ... | ... | ... | ... |

## 核心组件

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

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

## 依赖关系

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

总导览文档格式

所有区块完成后，生成/更新总导览 README.md：

# [项目名称] 项目文档

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

## 项目概述

[1-2 段简要描述]

## 技术栈

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

## 目录结构（简化版）

project/ ├── src/ 源码目录 ├── tests/ 测试目录 ├── docs/ [空目录] 文档目录 ├── cache/ [ignored] └── README.md


> 详细结构见各区块文档

## 区块索引

| 区块 | 路径 | 文档 | 说明 |
|------|------|------|------|
| core | src/core/ | [查看](blocks/core.md) | 核心逻辑 |
| utils | src/utils/ | [查看](blocks/utils.md) | 工具函数 |
| ... | ... | ... | ... |

## 快速导航

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

## 统计信息

- 总目录数：xx（含 xx 个空目录）
- 总文件数：xx
- 被忽略项：xx
- 代码行数：约 xxx 行

完成流程

当所有步骤完成时：

  1. 确认所有步骤状态为 completed
  2. 生成/更新总导览文档
  3. 运行完整性检查
  4. 向用户汇报完成情况
项目文档已完成：
- 总导览：.aide/project-docs/README.md
- 区块数：N 个
- 总步骤数：M 个
- 总目录数：xx（含 xx 个空目录）
- 总文件数：xx

配置项

配置项 默认值 说明
docs.path .aide/project-docs 文档目录
docs.block_plan_path .aide/project-docs/block-plan.md 区块计划文件
docs.steps_path .aide/project-docs/steps 步骤文档目录

注意事项

  1. 分步执行：每个步骤文档包含完整执行信息，接续执行无需重新分析
  2. 进度持久化：进度同时保存在步骤文档和区块计划中
  3. 粒度可控：大型区块自动拆分为多个步骤
  4. 完整性保证：每个文件的处理状态都有记录