176 lines
5.1 KiB
Markdown
176 lines
5.1 KiB
Markdown
<!-- 由 BMAD™ Core 驱动 -->
|
||
|
||
# 索引文档任务
|
||
|
||
## 目的
|
||
|
||
此任务通过扫描所有文档文件并确保它们都已正确索引并附有描述，来维护`docs/index.md`文件的完整性。它处理根级文档和子文件夹中的文档，并按层次结构组织它们。
|
||
|
||
## 任务说明
|
||
|
||
您现在作为文档索引员操作。您的目标是确保所有文档文件都已在中央索引中正确编目，并为子文件夹进行适当的组织。
|
||
|
||
### 所需步骤
|
||
|
||
1. 首先，定位并扫描：
|
||
- `docs/`目录及其所有子目录
|
||
- 现有的`docs/index.md`文件（如果不存在则创建）
|
||
- 文档结构中的所有markdown (`.md`)和文本(`.txt`)文件
|
||
- 注意文件夹结构以进行分层组织
|
||
|
||
2. 对于现有的`docs/index.md`：
|
||
- 解析当前条目
|
||
- 注意现有的文件引用和描述
|
||
- 识别任何损坏的链接或丢失的文件
|
||
- 跟踪已索引的内容
|
||
- 保留现有的文件夹部分
|
||
|
||
3. 对于找到的每个文档文件：
|
||
- 提取标题（从第一个标题或文件名）
|
||
- 通过分析内容生成简要描述
|
||
- 创建到文件的相对markdown链接
|
||
- 检查它是否已在索引中
|
||
- 注意它属于哪个文件夹（如果在子文件夹中）
|
||
- 如果丢失或过时，则准备更新
|
||
|
||
4. 对于在索引中找到但不存在的任何文件：
|
||
- 呈现引用不存在的文件的所有条目的列表
|
||
- 对于每个条目：
|
||
- 显示完整的条目详细信息（标题、路径、描述）
|
||
- 在删除前要求明确确认
|
||
- 如果文件已移动，则提供更新路径的选项
|
||
- 记录决定（删除/更新/保留）以供最终报告
|
||
|
||
5. 更新`docs/index.md`：
|
||
- 保持现有的结构和组织
|
||
- 为每个子文件夹创建2级部分（`##`）
|
||
- 首先列出根级文档
|
||
- 添加带有描述的缺失条目
|
||
- 更新过时的条目
|
||
- 仅删除已确认为删除的条目
|
||
- 确保整个格式一致
|
||
|
||
### 索引结构格式
|
||
|
||
索引应按以下方式组织：
|
||
|
||
```markdown
|
||
# 文档索引
|
||
|
||
## 根文档
|
||
|
||
### [文档标题](./document.md)
|
||
|
||
文档目的和内容的简要描述。
|
||
|
||
### [另一个文档](./another.md)
|
||
|
||
此处的描述。
|
||
|
||
## 文件夹名称
|
||
|
||
`folder-name/`目录中的文档：
|
||
|
||
### [文件夹中的文档](./folder-name/document.md)
|
||
|
||
此文档的描述。
|
||
|
||
### [文件夹中的另一个](./folder-name/another.md)
|
||
|
||
此处的描述。
|
||
|
||
## 另一个文件夹
|
||
|
||
`another-folder/`目录中的文档：
|
||
|
||
### [嵌套文档](./another-folder/document.md)
|
||
|
||
嵌套文档的描述。
|
||
```
|
||
|
||
### 索引条目格式
|
||
|
||
每个条目应遵循此格式：
|
||
|
||
```markdown
|
||
### [文档标题](relative/path/to/file.md)
|
||
|
||
文档目的和内容的简要描述。
|
||
```
|
||
|
||
### 操作规则
|
||
|
||
1. 切勿修改索引文件的内容
|
||
2. 在现有描述足够的情况下，保留index.md中的现有描述
|
||
3. 保持索引中任何现有的分类或分组
|
||
4. 对所有链接使用相对路径（以`./`开头）
|
||
5. 确保描述简洁但信息丰富
|
||
6. 未经明确确认，切勿删除条目
|
||
7. 报告发现的任何损坏链接或不一致之处
|
||
8. 在考虑删除之前，允许为移动的文件更新路径
|
||
9. 使用2级标题（`##`）创建文件夹部分
|
||
10. 按字母顺序对文件夹进行排序，根文档列在最前面
|
||
11. 在每个部分内，按标题字母顺序对文档进行排序
|
||
|
||
### 流程输出
|
||
|
||
该任务将提供：
|
||
|
||
1. 对index.md所做更改的摘要
|
||
2. 新索引文件的列表（按文件夹组织）
|
||
3. 更新条目的列表
|
||
4. 为删除而呈现的条目及其状态列表：
|
||
- 已确认删除
|
||
- 已更新路径
|
||
- 尽管文件丢失但仍保留
|
||
5. 发现的任何新文件夹
|
||
6. 发现的任何其他问题或不一致之处
|
||
|
||
### 处理丢失的文件
|
||
|
||
对于索引中引用但在文件系统中未找到的每个文件：
|
||
|
||
1. 呈现该条目：
|
||
|
||
```markdown
|
||
检测到丢失文件：
|
||
标题：[文档标题]
|
||
路径：relative/path/to/file.md
|
||
描述：现有描述
|
||
部分：[根文档 | 文件夹名称]
|
||
|
||
选项：
|
||
|
||
1. 删除此条目
|
||
2. 更新文件路径
|
||
3. 保留条目（标记为暂时不可用）
|
||
|
||
请选择一个选项（1/2/3）：
|
||
```
|
||
|
||
2. 在采取任何行动之前等待用户确认
|
||
3. 记录决定以供最终报告
|
||
|
||
### 特殊情况
|
||
|
||
1. **分片文档**：如果文件夹包含`index.md`文件，则将其视为分片文档：
|
||
- 使用文件夹的`index.md`标题作为章节标题
|
||
- 将文件夹的文档列为子部分
|
||
- 在描述中注明这是一个多部分文档
|
||
|
||
2. **README文件**：根据内容将`README.md`转换为更具描述性的标题
|
||
|
||
3. **嵌套子文件夹**：对于深度嵌套的文件夹，保持层次结构，但在主索引中限制为2级。更深的结构应有自己的索引文件。
|
||
|
||
## 所需输入
|
||
|
||
请提供：
|
||
|
||
1. `docs/`目录的位置（默认：`./docs`）
|
||
2. 对`docs/index.md`的写访问权限的确认
|
||
3. 任何特定的分类偏好
|
||
4. 任何要从索引中排除的文件或目录（例如，`.git`、`node_modules`）
|
||
5. 是否包括隐藏文件/文件夹（以`.`开头）
|
||
|
||
您想继续进行文档索引吗？请提供上述所需输入。
|