用途
update-docs 是一个用于在代码变更后刷新项目文档的工作流。根据其描述，它适用于实现功能、改变行为或准备里程碑提交之后。
主要能力
- 使用 git 检测自上一次文档提交以来的变化。
- 分析 diff，并只更新受影响的文档。
- 不依赖特定项目：自动检测项目根目录与文档位置。
- 支持发现常见文档目录（docs、doc、wiki、pages）以及顶层 Markdown 文件。
- 若无法自动确定文档目录，会向用户询问。
- 可输出被修改的文档文件及增删改摘要。
- 可选地将改动提交到 Git。
使用方式（工作流步骤）
第 1 步 — 定位项目
运行以下命令确立项目根目录与基本结构：
# Project root and current branch
git rev-parse --show-toplevel && git branch --show-current
查看最近 5 次提交（用于选择基线）：
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，询问用户：“Where are your documentation files? (e.g. docs/, docs/src/, or README.md only)”。
第 2 步 — 查找基线提交
查找最近一次触及文档目录的提交：
git log --oneline --all -- "$DOCS_DIR" | head -5
记录第一个哈希，称为 <baseline>。这是文档最后一次保持最新的时间点。若不存在文档提交，则使用初始提交作为基线：
git log --oneline --all | tail -1
第 3 步 — 获取基线以来的代码 diff
先获取源代码（非文档）变化的紧凑摘要：
git diff <baseline> HEAD --stat -- . \
':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'
若 diff 规模可控，获取完整 diff：
git diff <baseline> HEAD -- . \
':!'"$DOCS_DIR" ':!*.md' ':!*.rst' ':!*.txt' ':!*.json'
提示：若 diff 超过约 400 行，逐文件分析：
git diff <baseline> HEAD -- path/to/file.py
重点关注：新增/删除的类或函数、变更的方法签名、新模块、变更的配置键、新增数据文件。
第 4 步 — 了解现有文档结构
读取第 1 步发现的文档文件，理解：每个文件覆盖的主题、每个文件记录的模块/组件/概念、写作风格（语言、标题层级、代码块与表格的使用）。编辑时保持与现有文档相同的风格与语言。
第 5 步 — 将变更映射到受影响的文档
对每个变更的文件或模块，确定需要更新哪些文档文件。通用映射规则：
| 代码变更类型 | 需要更新什么 |
|---|---|
| 新增类或模块 | 将其加入覆盖该层的架构/概览文档；更新依赖图 |
| 删除类或函数 | 从所有提及它的文档中移除或标记删除 |
| 方法签名/参数变化 | 更新代码示例、参数表 |
| 新增配置键或环境变量 | 更新配置文档 |
| 新增外部依赖 | 更新安装/设置文档 |
| 数据模式变化（DB、JSON、Pydantic 等） | 更新数据模型文档 |
| 新增 CLI 命令或标志 | 更新 CLI 参考/用法文档 |
| 行为变化（算法、业务逻辑） | 更新设计/架构文档 |
| 新增测试覆盖（重大新测试） | 通常无需更新文档，除非存在测试指南 |
第 6 步 — 对受影响的文档做精准编辑
只更新过时的章节，不要重写仍然准确的部分。编辑规则：
- 添加 diff 中出现的新的项（类、方法、参数、配置键）。
- 移除或修订被重命名、删除或重构内容的描述。
- 更新流程图、分步流水线和表格以反映新情况。
- 保留 diff 未触及的所有章节——不做无谓的重写。
- 完全匹配现有文档的写作风格（语言、格式、代码围栏风格）。
第 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: ..."
适用场景
代码发生变化、需要让项目文档保持最新时。具体触发时机包括：实现功能之后、改变行为之后、准备里程碑提交时。
限制
资料中未提供额外的平台限制、收费情况或效果说明。