agent-aide/aide-marketplace/aide-plugin/commands/user-docs.md

Aide 用户文档生成

你正在执行 Aide 用户文档生成流程。这个命令帮助用户在 docs 目录下创建面向用户的详细文档。

分步执行机制

此命令支持真正有效的分步执行和接续执行，适用于任意规模项目。

设计原则

1. 索引式计划文档：user-docs-plan.md 只做索引，详细信息存在独立步骤文档中
2. 自包含步骤文档：每个步骤包含执行所需的全部信息（已提取的源信息）
3. 粒度动态控制：根据文档复杂度动态拆分步骤
4. 分析与执行分离：分析阶段产出详细计划，执行阶段直接生成文档

文档结构

docs/
├── user-docs-plan.md      # 计划文件（索引式）
├── steps/                 # 步骤详情目录
│   ├── step-001.md        # 步骤1详情
│   ├── step-002.md        # 步骤2详情
│   └── ...
└── [生成的文档]           # 产出的文档
    ├── getting-started.md
    ├── installation.md
    └── ...

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

---

前置准备

首先触发 readme-templates skill 学习模板使用方法。

---

开始

检查计划文件

aide config get user_docs.docs_plan_path
aide config get user_docs.docs_steps_path

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

• 计划文件：docs/user-docs-plan.md
• 步骤目录：docs/steps

根据计划文件状态决定流程：

• 计划文件不存在 → 进入分析和计划阶段
• 计划文件存在 → 进入接续执行阶段

---

分析和计划阶段

当计划文件不存在时执行此流程。

1. 检查前置条件

1.1 检查 README 规范文件

aide config get user_docs.rules_path

如果规范文件不存在：

检测到 README 编写规范（make-readme-rules.md）不存在。

建议先执行 /aide:readme 创建规范文件。规范文件定义了项目的文档风格， 用户文档应与 README 保持一致的风格。

使用 AskUserQuestion 询问：

• 先执行 /aide:readme（推荐）
• 继续生成文档（使用默认风格）

1.2 检查项目文档

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 确定文档清单

根据项目分析确定需要生成的文档：

文档类型	适用场景	典型内容
getting-started.md	所有项目	最小可运行示例
installation.md	需安装的项目	系统要求、安装步骤
usage.md	有 CLI/API 的项目	命令、参数说明
configuration.md	有配置项的项目	配置详解
api/	库项目	API 文档
guides/	复杂项目	使用指南

4. 步骤生成（关键阶段）

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

4.1 评估文档复杂度

对每个文档评估：

复杂度	特征	处理方式
小	单一主题，内容简单	整个文档作为 1 个步骤
中	多个章节，有交叉引用	按章节拆分为 2-3 个步骤
大	大量内容，需要分析多个模块	按功能点拆分为 3-5 个步骤
超大	API 文档等，涉及大量接口	按模块/文件拆分为多个步骤

4.2 生成步骤文档

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

步骤文档格式：

# 步骤 XXX：生成 [文档名称]

## 元信息

| 属性 | 值 |
|------|-----|
| 状态 | pending / in_progress / completed |
| 目标文档 | [文档路径] |
| 预估工作量 | 小 / 中 / 大 |
| 依赖步骤 | [无 / step-XXX] |

## 任务描述

生成/更新 [文档名称]，包含 [具体内容]。

## 源信息（已提取）

以下是生成本文档所需的全部信息，**已从项目文档和代码中提取整理**：

### 项目基础信息

| 属性 | 值 |
|------|-----|
| 项目名称 | xxx |
| 项目类型 | 库/应用/工具 |
| 主要语言 | xxx |
| 入口文件 | xxx |

### 相关模块/功能

| 模块 | 位置 | 说明 |
|------|------|------|
| [模块1] | path/to/module1 | 功能说明 |
| [模块2] | path/to/module2 | 功能说明 |

### 关键代码摘要

（已从代码中提取的关键信息，如函数签名、配置项等）

[已提取的关键代码片段或结构说明]

### 已有文档参考

（从项目文档或 README 中提取的相关内容）

> [引用的相关内容]

## 输出要求

- 文件：`docs/[filename].md`
- 格式要求：
  - [ ] 包含自动生成标记
  - [ ] 保留用户编辑区域
  - [ ] 符合 README 规范风格

### 内容大纲

1. [章节1]
   - [要点1]
   - [要点2]
2. [章节2]
   - [要点1]
   - [要点2]

## 执行记录

（执行时填写）

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

4.3 生成计划文件（索引）

生成 user-docs-plan.md 作为索引：

# 用户文档生成计划

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

## 项目概述

{{基于项目文档/分析的简要描述}}

## 项目类型

{{纯文档/单体程序/多项目仓库}}

## 文档结构

docs/ ├── getting-started.md ├── installation.md ├── usage.md └── ...

## 步骤索引

| 步骤 | 目标文档 | 描述 | 状态 |
|------|----------|------|------|
| [001](steps/step-001.md) | getting-started.md | 快速开始指南 | pending |
| [002](steps/step-002.md) | installation.md | 安装说明 | pending |
| [003](steps/step-003.md) | usage.md | 使用说明 | pending |
| ... | ... | ... | ... |

## 整体进度

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

## 执行日志

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

5. 用户确认

向用户展示规划的文档结构：

用户文档计划已生成。

文档清单：

{{PLANNED_STRUCTURE}}

总步骤数：{{TOTAL_STEPS}}

步骤文档已生成，每个步骤包含已提取的源信息，执行时可直接生成文档。

是否开始执行？

选项：

• 开始执行（推荐）
• 调整结构（自定义）
• 稍后执行

如用户选择调整，通过对话确认最终结构后更新计划文件。

如选择开始执行，进入步骤执行流程。

---

接续执行阶段

当计划文件存在时执行此流程。

1. 读取计划文件

读取 user-docs-plan.md 获取：

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

2. 显示进度

用户文档生成进度

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

3. 确认继续

使用 AskUserQuestion：

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

选项：

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

如选择重新开始，删除计划文件后进入分析和计划阶段。

---

步骤执行流程

执行单个步骤

1. 读取步骤文档：

   • 打开 steps/step-XXX.md
   • 获取已提取的源信息和内容大纲

2. 生成文档：

   • 基于步骤文档中的源信息直接生成
   • 无需重新分析代码/项目文档，信息已在步骤文档中
   • 遵循内容大纲和格式要求

3. 保存产出：

   • 写入文档文件
   • 使用自动生成标记区分自动内容和用户编辑区域

4. 更新步骤文档：

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

5. 更新计划文件：

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

步骤间询问

每完成一个步骤后询问：

步骤 XXX 已完成：{{STEP_DESCRIPTION}}

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

是否继续下一步？

选项：

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

如选择暂停，当前进度已保存，下次可直接接续。

---

文档内容规范

文档文件结构

每个文档文件应包含：

# 文档标题

<!-- 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. 确认所有步骤状态为 completed
2. 更新 README 中的文档链接（如需要）
3. 向用户汇报完成情况

用户文档已生成：docs/

生成的文档：
- getting-started.md
- installation.md
- usage.md
- ...

建议：
- 检查生成的内容是否准确
- 在 <!-- USER-EDIT --> 标记下方添加自定义内容
- 自定义内容不会被后续更新覆盖

如需重新生成，可删除计划文件后再次运行 /aide:user-docs。

---

配置项

配置项	默认值	说明
user_docs.docs_path	docs	用户文档目录路径
user_docs.docs_plan_path	docs/user-docs-plan.md	计划文件路径
user_docs.docs_steps_path	docs/steps	步骤文档目录
user_docs.rules_path	make-readme-rules.md	README 规范文件路径

---

注意事项

1. 分步执行：每个步骤文档包含已提取的源信息，执行时无需重新分析
2. 进度持久化：进度同时保存在步骤文档和计划文件中
3. 保留用户编辑：使用标记区分自动生成和用户编辑的内容
4. 风格一致：文档风格与 README 保持一致
5. 增量更新：多次运行不会覆盖用户自定义内容