doc-sync

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	手动触发，完整执行
周报技能自动调用	周报生成后自动执行（静默模式，无需用户确认）
"同步文档索引" / "更新文档目录"	自然语言触发

核心规则

1. index.yml 是权威元数据：文件名→标题映射的唯一数据源
2. guide.list.directory.md 是渲染视图：从 index.yml 生成，两者必须一致
3. 新增文件自动补标题：读取文件第一行 # 标题，写入 index.yml
4. 不自动删除：文件不存在但 index.yml 有记录时，标记为 注意：文件缺失 提醒用户，不自动删除条目
5. 前缀校验：不符合 7 种合法前缀的 .md 文件，报告为异常但不自动修复

执行流程

Phase 1: 扫描 doc/ 目录

# 获取所有 .md 文件（不含子目录），提取文件名（不含路径和 .md 后缀）
ls doc/*.md | sed 's|doc/||; s|\.md$||' | sort

得到 实际文件列表。

Phase 2: 读取 index.yml

读取 doc/index.yml 的 docs: 段落，提取所有已注册的文件名，得到 索引文件列表。

Phase 3: 双向对比

3.1 新增文件（实际有，索引无）

对每个新增文件：

1. 校验前缀是否为 guide / design / rule / spec / plan / report / debt 之一
2. 读取文件第一行 # 标题，提取标题文本
3. 如果没有标题行，使用文件名作为临时标题，并标记为需人工补充
4. 将 文件名: 标题 追加到 index.yml 对应前缀分区的末尾

3.2 缺失文件（索引有，实际无）

对每个缺失文件：

1. 不自动删除条目
2. 在输出中报告为 注意：文件缺失：{filename}
3. 询问用户：保留（可能是临时删除）还是清理

3.3 标题变更检测

对每个已存在的文件：

1. 读取文件第一行 # 标题
2. 与 index.yml 中的标题对比
3. 如果不一致，以文件内标题为准，更新 index.yml（文件内容是一手数据源）

Phase 4: 更新 index.yml

按以下排序规则重写 docs: 段落：

1. 按前缀分区：guide → design → rule → spec → plan → report
2. 每个分区内按文件名字母序排列
3. 保留分区注释行（# ── 一、指南 ── 等）

Phase 5: 重新生成 guide.list.directory.md

从更新后的 index.yml 生成 guide.list.directory.md：

1. 保留文件头部（标题 + 说明 + 使用方式表格）不动
2. 保留变更历史表格不动
3. 重新生成文档列表部分：

对 index.yml 中每个文件，按以下格式生成条目：

- [{中文标题}]({文件名}) `{文件名}`
  > {描述文字}

描述文字来源（优先级从高到低）：

1. guide.list.directory.md 中已有的描述（保留不变）
2. 文件内第一段非标题文本（新增文件时自动提取）
3. {中文标题} 的重复（兜底，标记为需人工补充）

Phase 6: 追加变更历史

在 guide.list.directory.md 的变更历史表格中追加本次同步的变更记录：

日期	操作	文件名	中文标题

操作类型：

• 新增 — 新文件加入索引
• 移除 — 文件已删除，从索引清理
• 更新 — 标题变更

Phase 7: 输出报告

文档索引同步完成

新增：{N} 个文件
  - {filename}: {title}
移除：{N} 个文件
  - {filename}（已从索引清理）
标题更新：{N} 个文件
  - {filename}: "{旧标题}" → "{新标题}"
异常：{N} 个文件
  - {filename}: {原因，如前缀不合法}
缺失：{N} 个文件（索引有记录但文件不存在）
  - {filename}

无变更时输出：文档索引已是最新，无需更新。

静默模式（被其他技能调用时）

当由周报等技能调用时，进入静默模式：

1. 不询问用户确认
2. 缺失文件自动保留（不清理），仅在输出中提及
3. 如果无变更，只输出一行 文档索引已是最新
4. 如果有变更，输出精简报告（不逐个列举，只给总数）

边界情况

场景	处理
index.yml 不存在	从零创建，扫描所有文件生成
guide.list.directory.md 不存在	从零创建，使用默认头部模板
文件名不符合 {prefix}.{name}.md 格式	报告为异常，不加入索引
文件无 # 标题 行	使用文件名作为标题，标记需人工补充
同名文件大小写不同	按实际文件系统为准

与其他技能的协作

文档变更（日常开发）
  │
  ▼
手动 /doc-sync → 对齐索引
  │
  ▼
/weekly → 周报生成完成后 → 自动调用 doc-sync（静默模式）
  │
  ▼
外部同步工具 git pull → 读取 index.yml → 同步到语雀/Confluence/...