企业官网建设流程全解析

用 aider 保持 README 与源码同步：update-docs 自动文档维护实战与原理解析

【免费下载链接】aideraider is AI pair programming in your terminal项目地址: https://gitcode.com/GitHub_Trending/ai/aider

本文基于 aider 官方示例会话 update-docs.md 展开。它展示了一个非常典型、极具复用价值的场景：命令行参数在main()中被更新后，用户把 README 与源码文件同时加入同一次会话，让 AI 依据最新代码自动修订 README 中的参数说明，并完成 git 提交。读完本文，你将掌握如何用一条aider命令驱动「代码改动 → 文档同步 → 自动提交」的闭环流程，理解会话中"编辑块"的语法与自动应用机制，并弄清--input-history-file、--chat-history-file等历史文件参数背后的实现细节。

场景速览：为什么"更新文档"适合交给 aider

原文档（aider/website/examples/update-docs.md）开篇即点明本示例的核心命题：

In this chat transcript, the user asks to automatically update the Usage docs based on the latest version of themain()function in the code.

即：以源码中最新的main()为准，自动同步更新使用文档中对命令行参数的描述。手工维护这类文档的最大痛点是"文档滞后于代码"——参数改名、默认值调整、环境变量变化往往不会及时回写到 README。而 aider 的解法是：在聊天会话中同时放入「需要改的文档」和「作为事实来源的源码」，由模型对照二者产出精确的差异补丁，再由工具自动落盘并提交。同类的官方示例还可在 示例会话索引 中浏览（如代码修改类示例 semantic-search-replace.md）。

会话启动：把文档与源码文件一起加入会话

原会话的第一步是一条很普通、但值得细品的启动命令：

$ aider ./README.md aider/main.py > Added README.md to the chat > Added aider/main.py to the chat

• 在命令行直接传入的文件路径，会被视为**加入聊天会话（added to the chat）**的可编辑文件；
• 后续即使不再输入任何指令，模型在应答前就能"看到"这两个文件的完整内容，这是它能够交叉比对文档与代码的前提。

按照 示例会话索引 中对会话机制的说明：模型只能看到并修改"已加入会话"的文件；除了命令行，还可以在会话中使用/add命令追加文件；若模型主动要求查看其他文件，aider 会先征求用户同意再将其加入。文档同步这类任务，一定要遵循"改哪个文档，就把哪个文档和对应源码都拉进会话"的原则，否则模型只能凭空猜测、无法核对事实。

提示：本仓库中该会话改动的是仓库根目录的README.md与包入口 aider/main.py；你可以仿照该模式，把main.py换成你自己的命令行入口文件、把 README 换成任何需要与代码保持一致的文档。

完整会话回放与逐段解读

加入文件后，用户发出了本次会话唯一的指令：

the cmd line args in main() have been updated. update the readme to accurately describe them.

（main() 中的命令行参数已被更新，请修订 README 使描述与实际一致。）

请求相当"口语化"，没有任何命令式提示模板，模型却准确完成了「找出新增/删除/改名的参数 → 修订文档条目 → 保持既有条目不动」的工作。模型返回的是一个针对README.md的标准编辑块（edit block）：

README.md <<<<<<< ORIGINAL - `--history-file HISTORY_FILE`: Specify the chat input history file (default: .aider.history). Override the default with the environment variable `AIDER_HISTORY_FILE`. - `--model MODEL`: Specify the model to use for the main chat (default: gpt-4). Override the default with the environment variable `AIDER_MODEL`. - `-3`: Use gpt-3.5-turbo model for the main chat (basically won't work). No environment variable override. - `--no-pretty`: Disable pretty, colorized output. Override the default with the environment variable `AIDER_PRETTY` (default: 1 for enabled, 0 for disabled). - `--show-diffs`: Show diffs when committing changes (default: False). Override the default with the environment variable `AIDER_SHOW_DIFFS` (default: 0 for False, 1 for True). - `--no-auto-commits`: Disable auto commit of changes. Override the default with the environment variable `AIDER_AUTO_COMMITS` (default: 1 for enabled, 0 for disabled). ======= - `--input-history-file INPUT_HISTORY_FILE`: Specify the chat input history file (default: .aider.input.history). Override the default with the environment variable `AIDER_INPUT_HISTORY_FILE`. - `--chat-history-file CHAT_HISTORY_FILE`: Specify the chat history file (default: .aider.chat.history.md). Override the default with the environment variable `AIDER_CHAT_HISTORY_FILE`. - `--model MODEL`: Specify the model to use for the main chat (default: gpt-4). Override the default with the environment variable `AIDER_MODEL`. - `-3`: Use gpt-3.5-turbo model for the main chat (basically won't work). No environment variable override. - `--no-pretty`: Disable pretty, colorized output. Override the default with the environment variable `AIDER_PRETTY` (default: 1 for enabled, 0 for disabled). - `--apply FILE`: Apply the changes from the given file instead of running the chat (debug). - `--no-auto-commits`: Disable auto commit of changes. Override the default with the environment variable `AIDER_AUTO_COMMITS` (default: 1 for enabled, 0 for disabled). - `--show-diffs`: Show diffs when committing changes (default: False). Override the default with the environment variable `AIDER_SHOW_DIFFS` (default: 0 for False, 1 for True). - `--yes`: Always say yes to every confirmation (default: False). >>>>>>> UPDATED

会话随后被两条工具通知收尾，代表整个流程闭环完成：

> Applied edit to README.md > Commit 024f45e aider: Updated command line arguments in main() and updated README.md to accurately describe them.

这个编辑块本身就是文档更新最重要的"产物"：左侧ORIGINAL是被替换的旧文本，右侧UPDATED是模型给出的新文本，=======分隔新旧内容。仔细对比可发现，这次更新实际做了三类修改：

1. 拆分参数：旧的单一--history-file被拆成语义更清晰的--input-history-file（聊天输入历史）与--chat-history-file（聊天记录正文）；
2. 新增参数：补上了文档缺失的--apply FILE（直接套用某文件中的改动、跳过交互式聊天，常用于调试）与--yes（对所有确认一律回答 yes）；
3. 保留与微调：--model、-3、--no-pretty、--no-auto-commits、--show-diffs等条目基本保留，仅位置做了重排——这说明模型能区分"确实变化的部分"与"无需改动的部分"，而不是把整个段落推倒重写。

需要说明的是，这份会话记录是某个历史时间点的"快照"（如其中--model的默认值gpt-4、--yes等均为当时的状态）。从当前仓库源码看，参数仍在持续演进：例如 aider/args.py 中对应的选项已演进为--yes-always，aider/main.py 甚至会扫描旧配置文件并提示把yes:键替换为yes-always:。因此，实际使用时请以aider --help与 完整命令行选项文档 为准——而"让 aider 依据最新 main() 自动修正这类文档"这件事本身，永远不会过时。

自动应用与自动提交：编辑块背后的两条机制

编辑块（Edit Format）：模型表达文件修改的契约

会话中模型并没有直接"写文件"，而是返回一段结构化文本：第一行是目标文件路径README.md，随后是<<<<<<< ORIGINAL/=======/>>>>>>> UPDATED包裹的替换块。aider 的 编辑格式说明 对此类机制有系统描述：aider 会针对不同模型选择最优编辑格式（whole、diff、diff-fenced、udiff等），也可用--edit-format强制指定。其中diff系列即"搜索/替换"式增量编辑，模型只需返回有变化的部分，比整文件回传（whole）更省 token；而无论哪种格式，模型输出的补丁都会被 aider 解析并自动应用到源文件，无需人工复制粘贴。这正是> Applied edit to README.md这行通知背后的实现逻辑。

git 自动提交：每个改动都有可回溯的记录

> Commit 024f45e aider: ...揭示了另一条机制——每次自动应用编辑后，aider 都会用描述性信息自动提交，提交信息还会带上 AI 协作的标识。这与 Git 集成文档 的描述一致：aider 每次编辑文件都会自动 commit，从而可用/undo瞬间撤销不满意的 AI 改动、用 git 历史复盘 aider 的全部变更；面对已有未提交改动的"脏文件"，aider 会先把既有改动单独提交，再应用自己的修改，避免相互污染、防止误改丢失工作。aider 的提交信息通常由--weak-model依据 diff 与聊天记录生成，并可通过--no-auto-commits关闭自动提交、用--show-diffs在提交前展示 diff——后者恰好也出现在上文编辑块中被修订的文档条目里，形成了"文档与实现互相印证"的闭环。

深挖本次更新的对象：历史文件参数与默认值逻辑

本次会话最实质的代码变化，是把一个笼统的--history-file拆分成了两个职责不同的参数。理解这一点，需要看它在源码中的真实落点——aider/args.py 中专门有一个 "History Files" 参数分组：

• --input-history-file：记录你在聊天里输入过的命令，供方向键上下翻阅，默认值.aider.input.history；
• --chat-history-file：保存与模型的完整聊天记录正文（Markdown 格式），默认值.aider.chat.history.md；
• 二者默认路径都由git_root与文件名拼接得到——如果启动目录位于 git 仓库内，历史文件会被放在仓库根目录，方便随项目走；
• 同组还提供--restore-chat-history（启动时恢复上次的聊天消息以续聊）与--llm-history-file（把发送给 LLM 的原始消息记录到日志文件，便于排查）。

会话中修订出的文档条目还精确给出了环境变量覆盖约定：每个参数默认都有对应的AIDER_<PARAM>形式环境变量，且布尔参数习惯用1/0表示开关（如AIDER_PRETTY默认 1 启用、0 禁用；AIDER_SHOW_DIFFS默认 0/False、1/True）。这就是 aider 一贯的"命令行参数 + 配置文件 + 环境变量"三通道配置体系，详见 参数配置总览 与 dotenv 说明。

值得注意的是，该 edit block 恰好同时展示了**旧版（ORIGINAL）与新版（UPDATED）**两套命名与默认值：从旧的.aider.history/AIDER_HISTORY_FILE到新的.aider.input.history、.aider.chat.history.md与AIDER_INPUT_HISTORY_FILE/AIDER_CHAT_HISTORY_FILE。命名与默认值变化对用户是有感知的破坏性改动，若文档滞后，用户按旧文档配置就会出现"参数不认识 / 历史文件不生效"的困惑——这正是本例要解决的文档漂移问题。

实操模板：把你的"代码与文档同步"也交给 aider

把本示例提炼成可复制到任意项目的操作模板：

1. 在 git 仓库中启动（aider 与 git 深度集成，见 Git 集成文档，非 git 目录会提示先建仓库）：

   $ aider ./README.md ./main.py

   把「待更新文档」与「作为事实来源的入口函数所在源码」同时加入会话；

2. 用自然语言描述变更来源与目标，参照本例的原话模板：

   the cmd line args in main() have been updated. update the readme to accurately describe them.

   即明确告诉模型：以main()的最新实现为准，去修订 README 中对应的说明段落；

3. 审查模型返回的编辑块：检查ORIGINAL/UPDATED两侧是否只包含必要变化——如果模型试图顺带重构其他无关段落，可要求它缩小范围；
4. 自动应用与提交：确认后 aider 会执行Applied edit to ...并生成描述性 commit（可用/diff查看改动、用/undo反悔，见 Usage 命令说明）；
5. 如果需要人工把关，可加--no-auto-commits关闭自动提交、或加--show-diffs在提交前审查 diff；大型改动建议配合--yes（当前版本为--yes-always）批量确认时谨慎使用。

小结

update-docs.md 用一段不到二十行的真实会话，示范了 aider 在软件文档工程上的核心用法：让 AI 在"有源码可对照"的前提下自动同步用户文档。其背后是三条可独立复用的工程机制——把源文件加入会话以获得事实依据、用结构化编辑块表达精确的文件修改、用 git 自动提交让每次 AI 改动都可审计、可回滚。理解这三点后，你不仅能复制"README 自动更新"这一场景，还能将其推广到 CHANGELOG、配置示例、教程片段等一切"跟随代码变化"的文档维护工作中。更多端到端会话（从 Flask 新项目到多文件重构、从语义化搜索替换到 pygame 游戏）均可从 示例会话索引 进入。

【免费下载链接】aideraider is AI pair programming in your terminal项目地址: https://gitcode.com/GitHub_Trending/ai/aider