<!-- 由 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.  是否包括隐藏文件/文件夹（以`.`开头）

您想继续进行文档索引吗？请提供上述所需输入。