PR Agent `/update_changelog` 工具完全指南：自动维护 CHANGELOG.md 的配置、原理与容错机制

• 人工智能
• AI Agent
• 代码评审
• 代码智能体
• 开发工具
• 质量保障
• 工作流自动化

导读

/update_changelog是 PR Agent 提供的一键式工具，它基于当前 PR 的标题、描述、提交信息与完整 diff，自动生成符合项目既有格式的变更记录，并将内容以评论形式发布或直接提交到仓库的CHANGELOG.md。本文以官方工具文档为主体，结合本仓库中该功能的源码实现（pr_agent/tools/pr_update_changelog.py）、提示词模板（pr_agent/settings/pr_update_changelog_prompts.toml）、默认配置（pr_agent/settings/configuration.toml#L261-L265）与单元测试，系统讲解该工具的触发方式、全部配置项、底层执行流水线以及读取/写入失败时的降级策略，帮助你在 GitHub、GitLab、Bitbucket 等平台上稳定落地"PR 自动更新 Changelog"的工作流。

工具概述：一条命令完成 Changelog 更新

update_changelog的核心职责是：根据 PR 的变更内容，自动更新项目根目录下的CHANGELOG.md文件。它读取 PR 的标题、分支、描述、提交信息与 Git Diff，交给模型生成一段精简的变更摘要，然后按照配置决定是"仅发布为 PR 评论"还是"直接写入并提交到 PR 分支"。

在任意 PR 中评论该命令即可触发：

/update_changelog

工具执行后，会在 PR 下产生类似下面的评论输出（实际截图见下文）：

• 生成一段新的 Changelog 条目，包含日期与变更分类（如Added/Changed/Fixed）；
• 若未开启自动推送，评论末尾会追加提示，指导你通过命令完成真正的仓库写入。

从仓库的调度注册表可以确认该命令与实现类的绑定关系：pr_agent/agent/pr_agent.py#L48 将命令名update_changelog映射到PRUpdateChangelog类，因此无论是在 Webhook 服务、GitHub Action 还是 CLI 模式下，命令分发都统一走到同一套实现。

触发方式：评论、CLI 与自动化

除了在 PR 评论区手动输入命令，该工具还有两种典型触发路径：

CLI 直连（适合本地调试或 CI 脚本调用，见 docs/docs/tools/index.md）：

python -m pr_agent.cli --pr_url=<PR_URL> update_changelog

自动化配置：可在pr_commands中加入该命令（例如在配置文件中为push事件或特定标签绑定），即可实现"合并前自动更新 Changelog"；自动化用法细节见 docs/docs/usage-guide/automations_and_usage.md。

需要说明的一个模式差异：/update_changelog属于"内容生成"型工具，在纯 diff 模式（plain_diff_mode）下没有可用的 PR 元数据与文件读取能力，因此在 docs/docs/usage-guide/plain_diff_mode.md 中被明确列为"该模式下无意义"的工具之一。

配置项详解：[pr_update_changelog]分区

所有相关配置集中在配置文件的[pr_update_changelog]分区下（默认值见 pr_agent/settings/configuration.toml#L261-L265）。官方文档定义了四个核心配置项，逐一说明如下。

push_changelog_changes

• 默认值：false
• 作用：控制生成结果的处理方式。
  • false：不写入仓库，仅把生成的 Changelog 内容发布为一条 PR 评论；
  • true：直接将新内容写入 PR 分支的CHANGELOG.md并提交。

从源码实现看，该开关还决定了对已有文件读取的严格程度（pr_agent/tools/pr_update_changelog.py#L327-L351）：

• 当push_changelog_changes=true且开启了publish_output时，工具以strict_read（propagate_errors=True）方式读取CHANGELOG.md：确认文件存在且内容可读是后续写入的前提；
• 确认文件缺失（读取返回空）时，按"空文件"处理，直接用生成内容作为新文件内容；
• 其他读取失败（如网络错误）则会跳过仓库写入，转而发布一条"未能生成"的降级评论，同时把原始读取错误向上抛出（详见下文"容错与降级"一节）。

此外，该开关并不保证"只要开启就一定能推送"：如果当前 Git Provider 不支持文件写入（缺少create_or_update_pr_file方法），或配置了restricted_mode禁用push_code能力，工具会降级为发布评论而不是跳过执行、丢弃输出（pr_agent/tools/pr_update_changelog.py#L53-L61）。降级时评论末尾会附注未推送的原因（如not supported for this git provider或restricted by configuration (restricted_mode)）。

未开启推送时，评论末尾会自动追加提交指引（pr_agent/tools/pr_update_changelog.py#L270-L273）：

>to commit the new content to the CHANGELOG.md file, please type: >'/update_changelog --pr_update_changelog.push_changelog_changes=true'

这也说明运行期覆盖配置是支持的：在 PR 评论中追加--参数即可临时开启推送，无需修改仓库配置。

extra_instructions

• 默认值：""
• 作用：向模型追加额外指令，典型用法是约束输出结构或补充必须遵守的规则，例如（示例见 docs/docs/usage-guide/additional_configurations.md）：

/update_changelog --pr_update_changelog.extra_instructions="Make sure to update also the version ..."

该字符串会被渲染进系统提示词中的Extra instructions from the user段落（pr_agent/settings/pr_update_changelog_prompts.toml#L13-L19），因此可以覆盖输出结构、分类规范、语言风格等要求。

add_pr_link

• 默认值：true
• 作用：是否让模型尝试把 Changelog 的主标题转换为指向该 PR 的可点击链接。开启时，PR 链接会被注入提示词变量pr_link，系统提示词会额外要求"使用 PR URL 将 changelog 主标题转为可点击链接，格式为header *"（pr_agent/settings/pr_update_changelog_prompts.toml#L8-L10）。链接注入点位于 pr_agent/tools/pr_update_changelog.py#L203-L204，仅在该配置为真时才会填充pr_link变量。

skip_ci_on_push

• 默认值：true
• 作用：当push_changelog_changes=true时，控制提交信息是否包含[skip ci]前缀，从而避免 Changelog 提交触发 CI 流水线。实现位于 pr_agent/tools/pr_update_changelog.py#L282-L285：

if get_settings().pr_update_changelog.get("skip_ci_on_push", True): commit_message = "[skip ci] Update CHANGELOG.md" else: commit_message = "Update CHANGELOG.md"

安全边界：哪些配置可以放在仓库内

值得注意的安全设计：在"按目录覆盖"（per-directory override）机制下，pr_update_changelog分区只开放extra_instructions和add_pr_link两个键（pr_agent/config_security.py#L158）。push_changelog_changes等可能触发 bot 侧写入（提交、推送）的键禁止由仓库内嵌套配置注入，只能来自根配置或宿主环境——这是防止"仓库内文件诱导 bot 自动提交代码"的安全防护，详见 pr_agent/config_security.py#L118-L125。

底层执行流水线：从读取到写入的源码级拆解

PRUpdateChangelog类的完整执行链路可拆解为六个阶段（入口为run()，见 pr_agent/tools/pr_update_changelog.py#L103-L170）。

阶段一：读取现有 CHANGELOG.md（含默认模板兜底）

初始化时，工具从 PR 分支读取CHANGELOG.md：

• 只截取前 50 行（常量CHANGELOG_LINES = 50，pr_agent/tools/pr_update_changelog.py#L25）作为模型参考的"既有格式与内容"，控制 token 开销；
• 若 Provider 返回字节流，会先做 UTF-8 解码（pr_agent/tools/pr_update_changelog.py#L339-L340）；
• 若文件为空，则注入一个示例模板作为格式提示（含Added/Changed/Fixed分类骨架，pr_agent/tools/pr_update_changelog.py#L312-L325）。

阶段二：组装提示词与预算控制

工具将 PR 标题、分支、描述、主语言、提交信息、diff、当前日期、既有 changelog、extra_instructions、pr_link等变量填充进系统/用户提示词（pr_agent/tools/pr_update_changelog.py#L77-L92）。系统提示词要求模型：

• 遵循文件既有的日期、章节标题等格式与风格；
• 只追加新条目，不重复已有条目；
• 内容保持概括，不超过 3-4 行简短描述，避免具体文件与细节；
• 直接输出"将成为新文件一部分的内容"，不要附带任何介绍或总结（pr_agent/settings/pr_update_changelog_prompts.toml#L2-L7）。

在调用模型前，工具通过AttemptTokenBudget计算输入容量，并要求完整 diff 必须能放入 token 预算（preserve_minimum=True），否则视为失败并可触发 fallback 模型重试（pr_agent/tools/pr_update_changelog.py#L201-L244）。

阶段三：模型调用与响应清洗

生成阶段使用弱模型路由（ModelType.WEAK，该工具与/describe、/ask一样使用config.model_weak，见 docs/docs/usage-guide/changing_a_model.md），并通过retry_with_fallback_models支持模型级容错。

模型返回后，工具会剥离包裹整个回答的代码围栏（code fence）：因为提示词以悬空的```markdown结尾，模型通常只补一个闭合围栏。若用str.strip("")直接处理会误删条目内部行内代码的尾反引号，因此实现使用正则只匹配"整体包裹"的围栏（[pr_agent/tools/pr_update_changelog.py#L26-L40](https://pre-link.gitcode.com/i/1bfb66d743d7101c8f1407c354a99b73#L26-L40)），确保形如- HandleNoneinparse()` 的条目能原样提交。

阶段四：合并新条目到既有文件

_prepare_changelog_update（pr_agent/tools/pr_update_changelog.py#L258-L274）把生成内容拼接到既有文件顶部：

• 有既有内容：new_file_content = answer + "\n\n" + changelog_file；
• 无既有内容：直接使用生成内容作为新文件全文。

阶段五：输出与推送（或评论）

依据commit_changelog标志二选一：

• 评论模式：发布**Changelog updates:** 🔄开头的评论（未推送原因存在时附加说明）；
• 推送模式：调用create_or_update_pr_file将新内容写入 PR 分支的CHANGELOG.md，提交信息为[skip ci] Update CHANGELOG.md（或去掉前缀）；写入后sleep(5)等待文件更新，再尝试以 PR Review 形式挂一条CHANGELOG.md update的内联评论（从第 1 行到生成内容行数），若 Review 创建失败则退化为普通评论（pr_agent/tools/pr_update_changelog.py#L276-L310）。

阶段六：清理临时评论

执行期间会先发布Preparing changelog updates...临时评论（受config.publish_output控制），无论成败，finally块都会尝试移除该临时评论（pr_agent/tools/pr_update_changelog.py#L116-L170）。

容错与降级策略：读取失败与写入失败的行为

官方文档特别强调了该工具的可靠性设计，源码将其落实为两套明确的降级路径：

读取失败（_publish_changelog_read_error_fallback，pr_agent/tools/pr_update_changelog.py#L172-L186）：仅当推送模式（严格读取）下读取CHANGELOG.md失败时触发。此时不写仓库，改为发布一条带⚠️ These changes were not pushed because the existing CHANGELOG.md could not be read safely.提示的评论（若内容已生成则保留内容，否则提示could not be generated），并向上抛出原始读取错误，避免"基于不可信内容做提交"。

写入失败（_publish_changelog_write_error_fallback，pr_agent/tools/pr_update_changelog.py#L188-L199）：create_or_update_pr_file抛异常时，工具会做一次尽力而为的评论发布，把已生成内容保留在 PR 中以便人工恢复，同时提示⚠️ The repository update could not be confirmed.，并继续抛出原始写入错误。之所以措辞为"无法确认更新"而非"肯定未推送"，是因为传输层失败可能发生在远端写入完成之后，工具无法可靠区分，因此只承诺"内容已保留供恢复"，不夸大保证。

单元测试 tests/unittest/test_pr_update_changelog.py 覆盖了读取异常、字节流解码、空文件默认模板、非提交模式追加指引等场景；tests/unittest/test_changelog_code_fence_stripping.py 则以"端到端提交"方式断言：以行内代码结尾的条目会被原样写入文件、反引号数量保持偶数、围栏不会泄漏进CHANGELOG.md，且提交信息确为[skip ci] Update CHANGELOG.md。

最佳实践建议

结合上述机制，落地时建议遵循以下实践：

1. 默认先评论、审核后推送：保持push_changelog_changes=false，让模型生成的条目先以评论形式呈现，人工确认无误后再执行--pr_update_changelog.push_changelog_changes=true提交，避免低质量条目直接进入历史记录；
2. 保持既有格式一致：仓库内维护一份格式清晰的CHANGELOG.md（含日期与Added/Changed/Fixed分类），工具会自动参考其前 50 行的风格；
3. 善用extra_instructions：需要补充版本号、Jira 单号或自定义章节结构时，通过命令行参数覆盖即可，无需修改全局配置；
4. 保留skip_ci_on_push=true：Changelog 提交不应触发全量 CI，避免无效构建开销；
5. 留意安全边界：仓库内嵌套配置只能覆盖extra_instructions与add_pr_link，涉及自动提交的开关必须由仓库所有者从根配置或部署环境控制。

通过上述配置组合与对执行流水线的理解，你可以把/update_changelog安全地接入团队的 PR 工作流，让 Changelog 维护从手工整理升级为"AI 生成 + 人工确认"的半自动流程。

• 人工智能
• AI Agent
• 代码评审
• 代码智能体
• 开发工具
• 质量保障
• 工作流自动化