| name | doc-sync |
| description | 文档索引同步技能。扫描 doc/ 目录，自动对齐 index.yml 和 guide.list.directory.md。手动触发 /doc-sync，或由周报技能自动调用。触发词："同步文档索引"、"更新文档目录"、"doc sync"、"/doc-sync"。 |
文档索引同步
版本：v1.0.0 | 状态：已落地 | 触发：/doc-sync、"同步文档索引"、"更新文档目录"
扫描 doc/ 目录下所有 .md 文件，与 doc/index.yml 和 doc/guide.list.directory.md 进行双向对比，补齐缺失条目、移除已删除条目。
触发方式
| 方式 | 说明 |
|---|
/doc-sync | 手动触发，完整执行 |
| 周报技能自动调用 | 周报生成后自动执行（静默模式，无需用户确认） |
| "同步文档索引" / "更新文档目录" | 自然语言触发 |
核心规则
- index.yml 是权威元数据：文件名→标题映射的唯一数据源
- guide.list.directory.md 是渲染视图：从 index.yml 生成，两者必须一致
- 新增文件自动补标题：读取文件第一行
# 标题，写入 index.yml
- 不自动删除：文件不存在但 index.yml 有记录时，标记为
注意：文件缺失 提醒用户，不自动删除条目
- 前缀校验：不符合 7 种合法前缀的
.md 文件，报告为异常但不自动修复
执行流程
Phase 1: 扫描 doc/ 目录
ls doc/*.md | sed 's|doc/||; s|\.md$||' | sort
得到 实际文件列表。
Phase 2: 读取 index.yml
读取 doc/index.yml 的 docs: 段落，提取所有已注册的文件名，得到 索引文件列表。
Phase 3: 双向对比
3.1 新增文件（实际有，索引无）
对每个新增文件：
- 校验前缀是否为
guide / design / rule / spec / plan / report / debt 之一
- 读取文件第一行
# 标题，提取标题文本
- 如果没有标题行，使用文件名作为临时标题，并标记为需人工补充
- 将
文件名: 标题 追加到 index.yml 对应前缀分区的末尾
3.2 缺失文件（索引有，实际无）
对每个缺失文件：
- 不自动删除条目
- 在输出中报告为
注意：文件缺失：{filename}
- 询问用户：保留（可能是临时删除）还是清理
3.3 标题变更检测
对每个已存在的文件：
- 读取文件第一行
# 标题
- 与 index.yml 中的标题对比
- 如果不一致，以文件内标题为准，更新 index.yml（文件内容是一手数据源）
Phase 4: 更新 index.yml
按以下排序规则重写 docs: 段落：
- 按前缀分区：guide → design → rule → spec → plan → report
- 每个分区内按文件名字母序排列
- 保留分区注释行（
# ── 一、指南 ── 等）
Phase 5: 重新生成 guide.list.directory.md
从更新后的 index.yml 生成 guide.list.directory.md：
- 保留文件头部（标题 + 说明 + 使用方式表格）不动
- 保留变更历史表格不动
- 重新生成文档列表部分：
对 index.yml 中每个文件，按以下格式生成条目：
- [{中文标题}]({文件名}) `{文件名}`
> {描述文字}
描述文字来源（优先级从高到低）：
- guide.list.directory.md 中已有的描述（保留不变）
- 文件内第一段非标题文本（新增文件时自动提取）
{中文标题} 的重复（兜底，标记为需人工补充）
Phase 6: 追加变更历史
在 guide.list.directory.md 的变更历史表格中追加本次同步的变更记录：
操作类型：
新增 — 新文件加入索引移除 — 文件已删除，从索引清理更新 — 标题变更
Phase 7: 输出报告
文档索引同步完成
新增：{N} 个文件
- {filename}: {title}
移除：{N} 个文件
- {filename}（已从索引清理）
标题更新：{N} 个文件
- {filename}: "{旧标题}" → "{新标题}"
异常：{N} 个文件
- {filename}: {原因，如前缀不合法}
缺失：{N} 个文件（索引有记录但文件不存在）
- {filename}
无变更时输出：文档索引已是最新，无需更新。
静默模式（被其他技能调用时）
当由周报等技能调用时，进入静默模式：
- 不询问用户确认
- 缺失文件自动保留（不清理），仅在输出中提及
- 如果无变更，只输出一行
文档索引已是最新
- 如果有变更，输出精简报告（不逐个列举，只给总数）
边界情况
| 场景 | 处理 |
|---|
| index.yml 不存在 | 从零创建，扫描所有文件生成 |
| guide.list.directory.md 不存在 | 从零创建，使用默认头部模板 |
文件名不符合 {prefix}.{name}.md 格式 | 报告为异常，不加入索引 |
文件无 # 标题 行 | 使用文件名作为标题，标记需人工补充 |
| 同名文件大小写不同 | 按实际文件系统为准 |
与其他技能的协作
文档变更（日常开发）
│
▼
手动 /doc-sync → 对齐索引
│
▼
/weekly → 周报生成完成后 → 自动调用 doc-sync（静默模式）
│
▼
外部同步工具 git pull → 读取 index.yml → 同步到语雀/Confluence/...
