update-docs

更新文档工作流

代码发生变更且项目文档需要同步更新时，使用此工作流。Agent 会使用 git 检测自上次文档提交以来的变更，分析差异，并仅更新受影响的文档。

此工作流与项目无关：它会自动检测项目根目录和文档位置。

---

步骤 1 — 确定方向：检测项目

// turbo 运行以下命令，确定项目根目录和基本结构：

# Project root and current branch
git rev-parse --show-toplevel && git branch --show-current

# Last 5 commits (so we can pick the baseline)
git log --oneline -5

然后查找文档所在位置：

# Look for common doc directory patterns
find "$(git rev-parse --show-toplevel)" -maxdepth 3 -type d \
  \( -name "docs" -o -name "doc" -o -name "wiki" -o -name "pages" \) \
  ! -path "*/.git/*" ! -path "*/node_modules/*" ! -path "*/.venv/*"

# Also check for top-level markdown files
find "$(git rev-parse --show-toplevel)" -maxdepth 1 -name "*.md" -type f

根据结果，确定：

• $ROOT：git 根目录
• $DOCS_DIR：文档文件所在位置（例如 docs/src/、docs/、wiki/）

如果无法自动确定 $DOCS_DIR，请询问用户：“你的文档文件在哪里？（例如 docs/、docs/src/，或者只有 README.md）”

---

步骤 2 — 查找基准提交

// turbo 查找最近一次修改文档目录的提交：

git log --oneline --all -- "$DOCS_DIR" | head -5

记下第一个哈希值，将其称为 <baseline>。这是文档最后一次保持最新的时间点。

如果不存在文档提交，则使用初始提交作为基准：

git log --oneline --all | tail -1

---

步骤 3 — 获取基准之后的代码差异

// turbo 首先，简要汇总源代码（非文档）的变更：

git diff <baseline> HEAD --stat -- . \
  ':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'

如果差异内容便于处理，则获取完整差异：

git diff <baseline> HEAD -- . \
  ':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'

提示：如果差异超过约 400 行，请使用以下命令逐个文件分析：

git diff <baseline> HEAD -- path/to/file.py

重点关注：新增或删除的类或函数、变更的方法签名、新模块、变更的配置键、新数据文件。

---

步骤 4 — 了解现有文档结构

阅读步骤 1 中找到的文档文件。了解：

• 每个文件涵盖的主题
• 每个文件记录的模块／组件／概念
• 写作风格（语言、标题级别、代码块和表格的使用方式）

编辑时，保持与现有文档相同的风格和语言。

---

步骤 5 — 将变更映射到受影响的文档

对于每个发生变更的文件或模块，确定需要更新哪些文档文件。

通用映射启发式规则（根据具体项目结构调整）：

代码变更类型	需要更新的内容
新增类或模块	在介绍该层的架构／概览文档中添加相关内容；更新依赖关系图
删除类或函数	从所有提及它的文档中删除或标记为删除
方法签名／参数变更	更新代码示例和参数表
新增配置键或环境变量	更新配置文档
新增外部依赖	更新设置／安装文档
数据架构变更（DB、JSON、Pydantic 等）	更新数据模型文档
新增 CLI 命令或标志	更新 CLI 参考／使用文档
行为变更（算法、业务逻辑）	更新设计／架构文档
新增测试覆盖（大量新增测试）	通常无需更新文档，除非存在测试指南

---

步骤 6 — 对受影响的文档进行精准修改

仅更新已过时的部分。仍然准确的部分不要重写。

编辑规则：

• 添加差异中出现的新项目（类、方法、参数、配置键）
• 删除或修订已重命名、删除或重构项目的描述
• 更新流程图、分步流程和表格，以反映最新情况
• 保留差异未涉及的所有部分，不要无故重写
• 完全匹配现有文档的写作风格（语言、格式、代码围栏样式）

---

步骤 7 — 总结更改并可选择提交

完成所有编辑后，显示简要总结：

• 修改了哪些文档文件
• 每个文件中添加、删除或更新了哪些内容

然后询问用户：“文档已更新。是否要将这些改动提交到 Git？(Y/n)”

如果是，请按以下格式提供提交信息建议：

docs: update <DOCS_DIR> to reflect changes since <baseline-short-hash>

然后运行（相应替换 <DOCS_DIR> 和 <message>）：

git add <DOCS_DIR> && git commit -m "<message>"

如果否，请提醒用户所有文件均已保存，之后可使用以下命令提交：

git add <DOCS_DIR> && git commit -m "docs: ..."