402 lines
9.0 KiB
Markdown
402 lines
9.0 KiB
Markdown
# Aide 用户文档生成
|
||
|
||
你正在执行 Aide 用户文档生成流程。这个命令帮助用户在 docs 目录下创建面向用户的详细文档。
|
||
|
||
此命令支持**分步执行**和**接续执行**，适用于大型项目。
|
||
|
||
这可能是一个非常长的任务，因此规划您的工作可能会很有益。**建议花费您的整个输出上下文来处理任务 - 只需确保您不会在有大量未提交的工作时用尽上下文。**继续系统地工作，直到您完成此任务。**您的上下文窗口将在接近其限制时自动压缩，允许您从中断的地方继续无限期地工作。因此，不要因为令牌预算问题而提前停止任务。**当您接近令牌预算限制时，在上下文窗口刷新前将您当前的进度和状态保存到内存中。始终尽可能坚持和自主，并完全完成任务，即使您的预算即将用尽。无论剩余上下文如何，永远不要人为地提前停止任何任务。
|
||
|
||
---
|
||
|
||
## 前置准备
|
||
|
||
**首先触发 `readme-templates` skill 学习模板使用方法。**
|
||
|
||
---
|
||
|
||
## 开始
|
||
|
||
### 检查计划文件
|
||
|
||
```bash
|
||
aide config get user_docs.docs_plan_path
|
||
```
|
||
|
||
读取配置的计划文件路径，检查文件是否存在。
|
||
|
||
**根据计划文件状态决定流程**：
|
||
|
||
- **计划文件不存在** → 进入**分析和计划阶段**
|
||
- **计划文件存在** → 进入**接续执行阶段**
|
||
|
||
---
|
||
|
||
## 分析和计划阶段
|
||
|
||
当计划文件不存在时执行此流程。
|
||
|
||
### 1. 检查前置条件
|
||
|
||
#### 1.1 检查 README 规范文件
|
||
|
||
```bash
|
||
aide config get user_docs.rules_path
|
||
```
|
||
|
||
如果规范文件不存在：
|
||
|
||
> 检测到 README 编写规范（`make-readme-rules.md`）不存在。
|
||
>
|
||
> 建议先执行 `/aide:readme` 创建规范文件。规范文件定义了项目的文档风格，
|
||
> 用户文档应与 README 保持一致的风格。
|
||
|
||
使用 AskUserQuestion 询问：
|
||
- **先执行 /aide:readme**（推荐）
|
||
- **继续生成文档**（使用默认风格）
|
||
|
||
#### 1.2 检查项目文档
|
||
|
||
```bash
|
||
aide config get docs.path
|
||
```
|
||
|
||
如果项目文档目录（`.aide/project-docs/`）不存在：
|
||
|
||
> 检测到面向 LLM 的项目文档（`.aide/project-docs/`）不存在。
|
||
>
|
||
> 建议先执行 `/aide:docs` 和 `/aide:load` 创建项目文档。
|
||
> 项目文档可以帮助生成更准确、更完整的用户文档。
|
||
|
||
使用 AskUserQuestion 询问：
|
||
- **先执行 /aide:docs**（推荐）
|
||
- **继续生成文档**（基于代码分析）
|
||
|
||
### 2. 分析项目
|
||
|
||
#### 2.1 读取项目信息
|
||
|
||
**优先级**：
|
||
|
||
1. **项目文档**（如果存在）：
|
||
- 读取 `.aide/project-docs/README.md` 获取项目概述
|
||
- 阅读相关区块文档了解详细信息
|
||
|
||
2. **README**（如果存在）：
|
||
- 读取 README.md 了解项目定位
|
||
|
||
3. **代码分析**：
|
||
- 分析配置文件（package.json、Cargo.toml、pyproject.toml 等）
|
||
- 分析目录结构
|
||
- 识别主要功能模块
|
||
|
||
#### 2.2 确定项目类型
|
||
|
||
| 类型 | 特征 |
|
||
|------|------|
|
||
| 纯文档/材料 | 主要是 markdown 文件，无代码 |
|
||
| 单体程序 | 单一主项目，可能有子模块 |
|
||
| 多项目仓库 | 包含多个独立子项目 |
|
||
|
||
### 3. 规划文档结构
|
||
|
||
根据项目类型选择文档结构模板：
|
||
|
||
#### 3.1 纯文档/材料类项目
|
||
|
||
```
|
||
docs/
|
||
├── overview.md # 内容概述
|
||
├── navigation.md # 导航指南
|
||
└── topics/ # 主题分类
|
||
├── topic-1.md
|
||
└── topic-2.md
|
||
```
|
||
|
||
#### 3.2 单体程序项目
|
||
|
||
```
|
||
docs/
|
||
├── getting-started.md # 快速开始
|
||
├── installation.md # 安装指南
|
||
├── usage.md # 使用说明
|
||
├── configuration.md # 配置说明（如有配置）
|
||
├── api/ # API 文档（如有）
|
||
│ ├── index.md
|
||
│ └── ...
|
||
└── guides/ # 使用指南
|
||
└── ...
|
||
```
|
||
|
||
#### 3.3 多项目仓库
|
||
|
||
```
|
||
docs/
|
||
├── overview.md # 仓库概述
|
||
├── projects/ # 各项目文档
|
||
│ ├── project-a/
|
||
│ │ ├── README.md
|
||
│ │ └── ...
|
||
│ └── project-b/
|
||
│ ├── README.md
|
||
│ └── ...
|
||
└── shared/ # 共享文档
|
||
└── ...
|
||
```
|
||
|
||
### 4. 生成计划文档
|
||
|
||
在配置的路径创建计划文件：
|
||
|
||
```bash
|
||
aide config get user_docs.docs_plan_path
|
||
```
|
||
|
||
计划文档格式：
|
||
|
||
```markdown
|
||
# 用户文档生成计划
|
||
|
||
## 项目概述
|
||
|
||
{{基于项目文档/分析的简要描述}}
|
||
|
||
## 项目类型
|
||
|
||
{{纯文档/单体程序/多项目仓库}}
|
||
|
||
## 文档结构
|
||
|
||
```
|
||
{{PLANNED_STRUCTURE}}
|
||
```
|
||
|
||
## 执行步骤
|
||
|
||
| # | 步骤描述 | 状态 |
|
||
|---|----------|------|
|
||
| 1 | 创建目录结构 | - |
|
||
| 2 | 生成 {{doc-1}}.md | - |
|
||
| 3 | 生成 {{doc-2}}.md | - |
|
||
| ... | ... | - |
|
||
| N | 更新 README 链接 | - |
|
||
|
||
## 当前进度
|
||
|
||
- 当前步骤：0（未开始）
|
||
- 已完成：0 / {{TOTAL_STEPS}}
|
||
- 最后更新：{{TIMESTAMP}}
|
||
|
||
## 备注
|
||
|
||
（执行过程中的记录）
|
||
```
|
||
|
||
### 5. 用户确认
|
||
|
||
向用户展示规划的文档结构：
|
||
|
||
> 根据项目分析，建议创建以下文档结构：
|
||
>
|
||
> ```
|
||
> {{PLANNED_STRUCTURE}}
|
||
> ```
|
||
>
|
||
> **预估步骤**：共 {{TOTAL_STEPS}} 步
|
||
>
|
||
> 是否按此结构生成文档？
|
||
|
||
**选项**：
|
||
- **开始执行**（推荐）
|
||
- **调整结构**（自定义）
|
||
- **稍后执行**
|
||
|
||
如用户选择调整，通过对话确认最终结构后更新计划文档。
|
||
|
||
如选择开始执行，进入步骤执行流程。
|
||
|
||
---
|
||
|
||
## 接续执行阶段
|
||
|
||
当计划文件存在时执行此流程。
|
||
|
||
### 1. 读取计划文档
|
||
|
||
解析计划文件获取：
|
||
- 项目概述和类型
|
||
- 文档结构
|
||
- 执行步骤列表和状态
|
||
- 当前进度
|
||
- 历史备注
|
||
|
||
### 2. 显示进度
|
||
|
||
> **用户文档生成进度**
|
||
>
|
||
> 项目类型：{{PROJECT_TYPE}}
|
||
> 当前步骤：{{CURRENT_STEP}}
|
||
> 已完成步骤：{{COMPLETED_STEPS}}/{{TOTAL_STEPS}}
|
||
> 上次更新：{{LAST_UPDATE}}
|
||
|
||
### 3. 确认继续
|
||
|
||
使用 AskUserQuestion：
|
||
|
||
> 是否从当前进度继续执行？
|
||
|
||
**选项**：
|
||
- **继续执行**（推荐）
|
||
- **查看计划详情**
|
||
- **重新开始**（清空进度）
|
||
|
||
如选择重新开始，删除计划文件后进入分析和计划阶段。
|
||
|
||
---
|
||
|
||
## 步骤执行流程
|
||
|
||
### 执行单个步骤
|
||
|
||
对于每个步骤：
|
||
|
||
1. **显示当前任务**：
|
||
> 正在执行：{{STEP_DESCRIPTION}}
|
||
|
||
2. **执行步骤**：
|
||
|
||
**步骤类型 A：创建目录结构**
|
||
- 检查 docs 目录是否存在
|
||
- 创建必要的子目录
|
||
|
||
**步骤类型 B：生成文档文件**
|
||
- 分析相关代码/文档
|
||
- 根据模板生成内容
|
||
- 写入文件
|
||
|
||
**步骤类型 C：更新 README 链接**
|
||
- 检查 README 中的文档链接部分
|
||
- 更新链接指向新生成的文档
|
||
|
||
3. **更新计划文档**：
|
||
- 标记步骤完成（`✓`）
|
||
- 更新当前进度
|
||
- 记录时间戳
|
||
|
||
4. **保存产出**：
|
||
- 写入生成的文档文件
|
||
|
||
### 步骤间询问
|
||
|
||
每完成一个步骤后询问：
|
||
|
||
> 步骤 {{STEP_ID}} 已完成：{{STEP_DESCRIPTION}}
|
||
>
|
||
> 是否继续下一步？
|
||
|
||
**选项**：
|
||
- **继续**（推荐）
|
||
- **查看产出**
|
||
- **暂停（保存进度）**
|
||
|
||
如选择暂停，保存进度后结束本次执行。
|
||
|
||
---
|
||
|
||
## 文档内容规范
|
||
|
||
### 文档文件结构
|
||
|
||
每个文档文件应包含：
|
||
|
||
```markdown
|
||
# 文档标题
|
||
|
||
<!-- AUTO-GENERATED: This section is automatically maintained -->
|
||
|
||
{{自动生成内容}}
|
||
|
||
<!-- USER-EDIT: DO NOT MODIFY ABOVE -->
|
||
<!-- You can add custom content below -->
|
||
|
||
{{用户自定义内容区域}}
|
||
```
|
||
|
||
### 各类文档内容要求
|
||
|
||
#### getting-started.md（快速开始）
|
||
|
||
- 最小可运行示例
|
||
- 简洁的步骤说明
|
||
- 链接到详细文档
|
||
|
||
#### installation.md（安装指南）
|
||
|
||
- 系统要求
|
||
- 多种安装方式
|
||
- 安装验证步骤
|
||
- 常见问题
|
||
|
||
#### usage.md（使用说明）
|
||
|
||
- 基本用法
|
||
- 常用命令/操作
|
||
- 参数说明
|
||
|
||
#### configuration.md（配置说明）
|
||
|
||
- 配置文件位置
|
||
- 配置项详解
|
||
- 配置示例
|
||
|
||
#### api/（API 文档）
|
||
|
||
- 按模块组织
|
||
- 函数签名
|
||
- 参数说明
|
||
- 使用示例
|
||
|
||
---
|
||
|
||
## 完成流程
|
||
|
||
当所有步骤完成时：
|
||
|
||
1. **更新计划文档**：
|
||
- 标记所有步骤完成
|
||
- 记录完成时间
|
||
|
||
2. **显示完成提示**：
|
||
|
||
> 用户文档已生成：`{{DOCS_PATH}}/`
|
||
>
|
||
> 生成的文档：
|
||
> {{GENERATED_FILES_LIST}}
|
||
>
|
||
> 建议：
|
||
> - 检查生成的内容是否准确
|
||
> - 在 `<!-- USER-EDIT -->` 标记下方添加自定义内容
|
||
> - 自定义内容不会被后续更新覆盖
|
||
>
|
||
> 如需重新生成，可删除计划文件后再次运行 `/aide:user-docs`。
|
||
|
||
---
|
||
|
||
## 配置项
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| `user_docs.docs_path` | `docs` | 用户文档目录路径 |
|
||
| `user_docs.docs_plan_path` | `docs/user-docs-plan.md` | 计划文件路径 |
|
||
| `user_docs.rules_path` | `make-readme-rules.md` | README 规范文件路径 |
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **分步执行**：大型项目建议分多次对话完成
|
||
2. **进度持久化**：进度保存在计划文件，可随时接续
|
||
3. **保留用户编辑**：使用标记区分自动生成和用户编辑的内容
|
||
4. **风格一致**：文档风格与 README 保持一致
|
||
5. **增量更新**：多次运行不会覆盖用户自定义内容
|
||
6. **链接同步**：README 中的文档链接自动更新
|