125 lines
2.9 KiB
Markdown
125 lines
2.9 KiB
Markdown
# 子计划 4：用户文档命令实现
|
||
|
||
## 目标
|
||
|
||
创建 `/aide:user-docs` 命令，实现 docs 目录下面向用户的详细文档生成功能。
|
||
|
||
## 具体步骤
|
||
|
||
### 4.1 添加配置项
|
||
|
||
**位置**：`aide-program/aide/` 配置模块
|
||
|
||
**新增配置项**：
|
||
|
||
```toml
|
||
[user_docs]
|
||
# 用户文档目录路径（相对于项目根目录）
|
||
docs_path = "docs"
|
||
```
|
||
|
||
### 4.2 创建命令文件
|
||
|
||
**位置**：`aide-marketplace/aide-plugin/commands/user-docs.md`
|
||
|
||
**命令流程**：
|
||
|
||
```
|
||
开始
|
||
│
|
||
├─ 检查 make-readme-rules.md 是否存在
|
||
│ │
|
||
│ ├─ 不存在 → 提示先执行 /aide:readme
|
||
│ │
|
||
│ └─ 存在 → 继续
|
||
│
|
||
├─ 检查项目文档是否存在（.aide/project-docs/）
|
||
│ │
|
||
│ ├─ 不存在 → 建议先执行 /aide:docs + /aide:load
|
||
│ │
|
||
│ └─ 存在 → 继续
|
||
│
|
||
├─ 分析项目类型和结构
|
||
│
|
||
├─ 确定文档结构
|
||
│
|
||
├─ 生成/更新 docs 目录下的文档
|
||
│
|
||
└─ 结束
|
||
```
|
||
|
||
### 4.3 文档结构设计
|
||
|
||
根据项目类型，docs 目录应包含不同的文档：
|
||
|
||
**纯文档/材料类项目**：
|
||
```
|
||
docs/
|
||
├── overview.md # 内容概述
|
||
├── navigation.md # 导航指南
|
||
└── topics/ # 主题分类
|
||
├── topic-1.md
|
||
└── topic-2.md
|
||
```
|
||
|
||
**单体程序项目**：
|
||
```
|
||
docs/
|
||
├── getting-started.md # 快速开始
|
||
├── installation.md # 安装指南
|
||
├── usage.md # 使用说明
|
||
├── configuration.md # 配置说明
|
||
├── api/ # API 文档
|
||
│ └── ...
|
||
└── guides/ # 使用指南
|
||
└── ...
|
||
```
|
||
|
||
**多项目仓库**：
|
||
```
|
||
docs/
|
||
├── overview.md # 仓库概述
|
||
├── projects/ # 各项目文档
|
||
│ ├── project-a/
|
||
│ │ ├── README.md
|
||
│ │ └── ...
|
||
│ └── project-b/
|
||
│ ├── README.md
|
||
│ └── ...
|
||
└── shared/ # 共享文档
|
||
└── ...
|
||
```
|
||
|
||
### 4.4 与 README 的关联
|
||
|
||
- 读取 `make-readme-rules.md` 了解用户偏好
|
||
- docs 目录下的文档与 README 中的链接保持一致
|
||
- 支持在 README 中自动插入 docs 文档的链接
|
||
|
||
### 4.5 增量更新机制
|
||
|
||
- 首次执行：生成完整文档结构
|
||
- 再次执行：
|
||
- 检测项目变更
|
||
- 更新受影响的文档
|
||
- 保留用户手动编辑的内容（通过标记区分）
|
||
|
||
## 验证标准
|
||
|
||
- [ ] `aide config get user_docs.docs_path` 正常工作
|
||
- [ ] 根据项目类型生成合适的文档结构
|
||
- [ ] 与 README 正确关联
|
||
- [ ] 增量更新机制正常工作
|
||
- [ ] 保留用户手动编辑的内容
|
||
|
||
## 依赖
|
||
|
||
- 前置：子计划 3（README 命令）
|
||
- 后续：子计划 5（用户流程图命令）
|
||
|
||
## 风险评估
|
||
|
||
- **风险等级**：中
|
||
- **潜在影响**：文档结构的合理性和可维护性
|
||
- **缓解措施**：参考主流开源项目的文档组织方式
|