update-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Docs Workflow

更新文档工作流

Use this workflow whenever code has changed and the project documentation needs to be brought up to date. The agent uses

git

to detect what changed since the last documentation commit, analyses the diff, and updates only the affected docs.

This workflow is project-agnostic: it auto-detects the project root and documentation location.

每当代码发生变更且项目文档需要更新时，即可使用此工作流。Agent会借助

git

检测自上次文档提交以来的变更内容，分析差异并仅更新受影响的文档。

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

Step 1 — Orient: detect the project

步骤1 — 定位：检测项目

// turbo Run the following to establish the project root and basic structure:

bash

undefined

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

bash

undefined

Project root and current branch

项目根目录和当前分支

git rev-parse --show-toplevel && git branch --show-current

Last 5 commits (so we can pick the baseline)

最近5次提交（以便我们选择基线）

git log --oneline -5


Then find where the documentation lives:

```bash

git log --oneline -5


然后查找文档所在位置：

```bash

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

同时检查顶级Markdown文件

find "$(git rev-parse --show-toplevel)" -maxdepth 1 -name "*.md" -type f


From the results, identify:

- **`$ROOT`**: the git root directory
- **`$DOCS_DIR`**: where the documentation files are (e.g. `docs/src/`, `docs/`, `wiki/`)

If `$DOCS_DIR` cannot be determined automatically, ask the user: **"Where are your documentation files? (e.g. `docs/`, `docs/src/`, or `README.md` only)"**

---

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`）"**

---

Step 2 — Find the baseline commit

步骤2 — 查找基线提交

// turbo Find the most recent commit that touched the documentation directory:

bash

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

Note the first hash — call it

<baseline>

. This is the last point in time when docs were current.

If no doc commits exist, use the initial commit as baseline:

bash

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

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

bash

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

记录第一个哈希值——将其称为

<baseline>

。这是文档最后处于最新状态的时间点。

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

bash

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

Step 3 — Get the code diff since the baseline

步骤3 — 获取自基线以来的代码差异

// turbo First, a compact summary of what changed in source code (not docs):

bash

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

If the diff is manageable, get the full diff:

bash

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

Tip: If the diff exceeds ~400 lines, analyse it file by file using:
bash
git diff <baseline> HEAD -- path/to/file.py
Focus on: new/deleted classes or functions, changed method signatures, new modules, changed configuration keys, new data files.

// turbo 首先，生成源代码（非文档）变更的简洁摘要：

bash

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

如果差异内容在可处理范围内，获取完整差异：

bash

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

提示：如果差异超过约400行，请逐文件分析：
bash
git diff <baseline> HEAD -- path/to/file.py
重点关注：新增/删除的类或函数、更改的方法签名、新模块、更改的配置键、新数据文件。

Step 4 — Discover existing documentation structure

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

Read the documentation files discovered in Step 1. Understand:

What topics each file covers
What module/component/concept each file documents
The writing style (language, heading level, use of code blocks, tables)

Maintain the same style and language as the existing docs when making edits.

阅读步骤1中发现的文档文件，明确：

每个文件涵盖的主题
每个文件所记录的模块/组件/概念
写作风格（语言、标题层级、代码块使用、表格）

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

Step 5 — Map changes to affected docs

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

For each changed file or module, determine which documentation file(s) need updating.

General mapping heuristics (adapt to the specific project structure):

Type of code change	What to update
New class or module added	Add it to whichever architecture/overview doc covers that layer; update dependency diagrams
Class or function deleted	Remove or strike from all docs that mention it
Method signature / parameter changed	Update code examples, parameter tables
New config key or environment variable	Update configuration docs
New external dependency added	Update setup/installation docs
Data schema changed (DB, JSON, Pydantic, etc.)	Update data model docs
New CLI command or flag	Update CLI reference / usage docs
Behaviour change (algorithm, business logic)	Update design/architecture docs
New test coverage (major new tests)	No doc update usually needed unless testing guide exists

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

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

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

Step 6 — Make surgical edits to affected docs

步骤6 — 对受影响的文档进行精准编辑

Update only the sections that are out of date. Do not rewrite sections that are still accurate.

Edit rules:

Add new items (classes, methods, parameters, config keys) that appeared in the diff
Remove or revise descriptions of things that were renamed, deleted, or refactored
Update flow diagrams, step-by-step pipelines, and tables to reflect new reality
Preserve all sections not touched by the diff — no gratuitous rewrites
Match the writing style of the existing doc exactly (language, formatting, code fence style)

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

编辑规则：

添加差异中出现的新项（类、方法、参数、配置键）
移除或修改已重命名、删除或重构内容的描述
更新流程图、分步流程和表格以反映新情况
保留所有未受差异影响的部分——不要随意重写
完全匹配现有文档的写作风格（语言、格式、代码块样式）

Step 7 — Summarise changes and optionally commit

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

After all edits, display a brief summary:

Which doc files were modified
What was added / removed / updated in each

Then ask the user: "文档已更新。是否要将这些改动提交到 Git？(Y/n)"

If yes, suggest a commit message in the format:

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

Then run (replace

<DOCS_DIR>

and

<message>

accordingly):

bash

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

If no, remind the user that all files are already saved and can be committed later with:

bash

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

完成所有编辑后，显示简短摘要：

修改了哪些文档文件
每个文件中添加/移除/更新了什么内容

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

如果用户同意，建议使用以下格式的提交信息：

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

然后运行相应命令（替换

<DOCS_DIR>

和

<message>

）：

bash

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

如果用户不同意，提醒用户所有文件已保存，可稍后使用以下命令提交：

bash

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