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

导读

/describe是 PR-Agent（gh_mirrors/pr/pr-agent）核心工具之一，能够在数秒内基于 PR 的 Git Diff 自动生成 PR 标题、PR 类型（Bug fix / Tests / Enhancement 等）、摘要、逐文件代码走读（Changes walkthrough）以及可选的 Mermaid 序列图与语义化标签。本文以官方文档 describe.md 为主体，结合仓库源码与配置实现，完整讲解该工具的手动/自动触发方式、全部配置参数、Markers 模板机制、自定义标签方案及底层执行流程，帮助你把它深度集成到自己的 PR 工作流中。

1./describe工具概述

describe工具会针对一个 Pull Request 生成以下内容：

• PR 标题（可选，由generate_ai_title控制）；
• PR 类型（type）：如Bug fix、Tests、Enhancement、Documentation、Other；
• PR 摘要（description）：对 PR 变更的总体概括；
• 代码走读（walkthrough）：逐文件的变更说明；
• 序列图（可选，Mermaid flowchart）：展示组件/函数间的交互；
• 标签（可选）：自动为 PR 打上语义化标签。

工具的触发方式有两种：

1. 自动触发：每次新 PR 被 打开 时自动运行；
2. 手动触发：在任意 PR 上评论/describe即可调用。

2. 手动触发与运行效果

在任何 PR 上评论/describe，工具即被唤醒：

大约30 秒后（取决于模型响应与 PR 大小），工具会生成一份完整的 PR 描述：

如果需要临时调整本次调用的配置，可以直接把配置项拼到命令后面：

/describe --pr_description.some_config1=... --pr_description.some_config2=...

例如：

/describe --pr_description.generate_ai_title=true --pr_description.publish_labels=false

--后面的参数采用<section>.<key>=<value>的命名法，任何pr_description配置项都可以这样覆盖。

3. 自动触发：PR 打开时自动运行

要实现在 PR 打开时自动执行describe，需要在本地配置文件（仓库根目录的.pr_agent.toml）中定义：

[github_app] pr_commands = [ "/describe", ... ] [pr_description] publish_labels = true ...

• pr_commands：PR 打开时自动执行的命令列表。注意，GitLab Webhook、Bitbucket App、Azure DevOps Webhook 等部署形态也使用类似机制（见 automations_and_usage.md 中各自平台的pr_commands配置）。
• [pr_description]：describe工具专属配置段，想要调整的默认值都在这里覆盖。

除此之外，describe也可以挂到push 事件上：当新代码被推送到已打开的 PR 时自动执行。例如：

[github_app] handle_push_trigger = true push_commands = [ "/describe", "/review", ]

安装 PR-Agent 后的默认行为是pr_commands = ["/describe", ...]，即每个新 PR 都会以默认配置自动运行一次describe。

提示：配置文件的加载优先级为「本地.pr_agent.toml（仓库默认分支） > 全局配置 > 外部配置 URL」，且建议配置文件保持精简，只覆盖需要修改的项，不要整段复制默认配置（参见 configuration_options.md）。

4. 保留原始用户描述（Preserving the original user description）

默认情况下，PR-Agent 会尽量保留你原始的 PR 描述——通过把它放在自动生成内容上方的方式实现。这要求在创建 PR 时就写好描述。

常见疑问："PR-Agent 把我原来的描述删了，为什么？"

根据项目经验，主要有两种可能：

1. 你在工具运行过程中编辑了描述：这会触发竞态条件，可能导致原始描述丢失。因此建议在发起 PR 之前就写好描述，工具运行期间不要改动。
2. 更新描述时的分区逻辑：/describe在更新PR 描述时，会把"PR Type" 字段以上的内容视为用户内容并予以保留；该标记以下的内容被视为之前自动生成的内容，会被整体替换：

这个行为在源码_prepare_pr_answer()中也有体现：add_original_user_description配置开启时，self.user_description会被重新插入生成的数据字典，并排在title、type之前（见 pr_description.py 的_prepare_data方法）。

5. 序列图（Mermaid Diagram）支持

/describe生成的内容中包含一个Mermaid 序列图/流程图，用于展示 PR 中组件或函数之间的交互关系。该功能默认开启，由pr_description.enable_pr_diagram控制。

方向自适应：图的绘制方向会根据图形形状自动调整——

• 当图中最长节点链超过pr_description.pr_diagram_direction_threshold（默认5）时，图会改为**自上而下（TD）**绘制，而不是自左向右（LR），避免宽图被缩放得难以阅读；
• 也可以显式设置pr_description.pr_diagram_direction = "LR"或"TD"来固定方向。

该逻辑在源码中有完整实现：apply_diagram_direction()会先解析 Mermaid 头部方向声明，再通过_parse_diagram_edges()提取有向边，用_longest_diagram_chain()基于拓扑排序计算最长链长度，最后按阈值决定方向（见 pr_description.py 的apply_diagram_direction函数）。对应单测位于 test_pr_description.py，其中用SHORT_CHAIN = 'A --> B --> C'、THRESHOLD_CHAIN = 'A --> B --> C --> D --> E'、LONG_CHAIN = 'A --> B --> C --> D --> E --> F'三组用例验证方向选择与默认阈值5的边界行为。

注意：enable_pr_diagram生效依赖 Git Provider 支持GFM Markdown（GitHub、GitLab 支持）。从源码看，enable_pr_diagram = get_settings().pr_description.get("enable_pr_diagram", False) and self.git_provider.is_supported("gfm_markdown")（见 pr_description.py），不支持 GFM 的平台会自动关闭该能力。

6. 配置参数详解（Configuration Options）

以下参数位于配置文件[pr_description]段。表格为官方文档整理，默认值以仓库内 configuration.toml 为准（文中已按该文件补齐）：

6.1 从源码看配置项的实际作用

几个关键配置在 pr_description.py 中有明确的代码落点：

• enable_semantic_files_types与 GFM 依赖：__init__中若平台不支持gfm_markdown，会自动降级关闭该配置（源码注释为 "Disabling semantic files types ... gfm_markdown not supported"）。
• collapsible_file_list_threshold：__init__中通过get_settings().pr_description.get("collapsible_file_list_threshold", 8)读取（配置文件的正式默认值为6），并在process_pr_files_prediction()中参与 adaptive 判断。
• 发布流程：run()方法中，publish_labels为 true 且平台支持标签时会合并原始用户标签后publish_labels(new_labels)；publish_description_as_comment决定走publish_comment/publish_persistent_comment还是publish_description覆盖原始描述。覆盖模式下，若generate_ai_title为 false，title_to_publish会被置为None，从而不触碰用户手动编辑的标题（对应注释#2474）。

6.2 大 PR 处理机制

当enable_large_pr_handling=true且 PR 超出单次 token 预算时，工具会：

1. 通过get_pr_diff_multiple_patchs()将 diff 拆成多个补丁块（chunk）；
2. 对每个块用pr_description_only_files_prompts并行或串行生成文件级描述（由async_ai_calls控制，默认并发）；
3. 合并所有块的 YAML 结果，再用pr_description_only_description_prompts推断 PR 头部（标题/类型/摘要）；
4. 通过extend_uncovered_files()把未被覆盖的文件以 "additional files" 形式补进表格（上限MAX_EXTRA_FILES_TO_OUTPUT = 100）。

若某些块生成失败，工具会保留成功块的结果，并在描述末尾追加覆盖率提示脚注（_get_description_coverage_footer()，最多列出MAX_DESCRIPTION_COVERAGE_FILES = 50个失败文件），确保用户清楚描述是否完整覆盖了全部文件。相关单测见 test_pr_description_lifecycle.py 与 test_pr_description.py。

7. Markers 模板机制

启用pr_description.use_description_markers=true后，/describe采用模板式替换：PR 原始描述中的pr_agent:marker_name占位符会被逐一替换为对应内容。这种机制能精确控制用户内容与自动生成内容的落位，把最大控制权交给用户。

例如 PR 原始描述是：

User content... ## PR Type: pr_agent:type ## PR Description: pr_agent:summary ## PR Walkthrough: pr_agent:walkthrough ## PR Diagram: pr_agent:diagram

替换规则：

• pr_agent:type→ PR 类型；
• pr_agent:summary→ PR 摘要；
• pr_agent:walkthrough→ PR 走读；
• pr_agent:diagram→ 序列图（若开启）。

从源码_prepare_pr_answer_with_markers()看，替换实现还额外支持HTML 注释格式的占位符（如<!-- pr_agent:type -->），且若原始描述中没有 markers，工具会完全不做任何改动——_prepare_prediction()中有明确检查：if get_settings().pr_description.use_description_markers and 'pr_agent:' not in self.user_description: ... Skipping AI prediction。

效果示意（替换前 → 替换后）：

相关配置参数：

• use_description_markers：启用 markers 模板；默认false；
• include_generated_by_header：为自动生成内容添加 "Generated by PR Agent at ..." 头部；默认true；
• diagram：若描述中存在该 marker，则替换为 PR 序列图（需开启 diagram）。

8. 自定义标签（Custom Labels）

describe工具的默认标签比较通用，适合任何仓库：Bug fix、Tests、Enhancement、Documentation、Other。

你可以定义与自身仓库/业务相关的自定义标签，有两种配置途径。

8.1 通过配置文件定义

在配置文件中启用并描述每个标签。标签描述必须是条件语句，明确说明满足什么条件时将该标签加到 PR 上：

[config] enable_custom_labels=true [custom_labels."sql_changes"] description = "Use when a PR contains changes to SQL queries" [custom_labels."test"] description = "use when a PR primarily contains new tests" ...

提示：当自定义标签不再相关时，运行generate_labels或describe工具会自动将其从 PR 中移除。

8.2 通过仓库的 Labels 页面定义

也可以直接在仓库的标签页管理自定义标签：

• GitHub：进入https://github.com/{owner}/{repo}/labels（或在 Issues/PRs 页面点击 "Labels" 标签页）；
• GitLab：进入https://gitlab.com/{owner}/{repo}/-/labels（或左侧菜单 "Manage" → "Labels"）。

新增/编辑标签时按下述格式：

• 标签名：自定义标签的名称；
• 描述：描述以pr_agent:前缀开头，例如pr_agent: Description of when AI should suggest this label。

示例：

• Main topic:performance——pr_agent:The main topic of this PR is performance
• New endpoint——pr_agent:A new endpoint was added in this PR
• SQL query——pr_agent:A new SQL query was added in this PR
• Dockerfile changes——pr_agent:The PR contains changes in the Dockerfile

描述要详尽且条件明确，告诉模型何时建议该标签：

从源码看，自定义标签会注入到提示词模板中：set_custom_labels()根据config.enable_custom_labels和custom_labels_class变量将标签枚举注入pr_description_prompts.toml的 Pydantic 定义（PRType枚举后追加{{ custom_labels_class }}），模型输出的labels字段再经_prepare_labels()归一化后发布。发布时还会通过get_user_labels()合并 PR 上已有的用户标签，避免覆盖人工设置（见 pr_description.py 的run()与 pr_description_prompts.toml）。

9. 使用提示（Usage Tips）

• 自动化默认行为：安装 PR-Agent 后，describe的默认模式为pr_commands = ["/describe", ...]，即每个新 PR 都会以默认配置自动运行一次。

• Markers 与命令参数组合：Markers 是控制生成描述落位的另一条路径。若设置：

  pr_commands = ["/describe --pr_description.use_description_markers=true", ...]

  工具会把 PR 描述中所有pr_agent:marker_name形式的占位符替换为对应内容，其中marker_name可以是：

  • type：PR 类型；
  • summary：PR 摘要；
  • walkthrough：PR 走读。

• Markers 模式下的安全行为：启用 markers 后，如果原始 PR 描述中不包含任何 marker，工具将完全不改动描述（源码中会跳过 AI 预测），这为那些不想被自动改写描述的场景提供了保底机制。

10. 从源码看完整执行链路

describe的运行时主入口是PRDescription.run()（见 pr_description.py），整体流程可以归纳为：

1. 初始化：解析 PR URL、主语言、git provider 上下文，构建vars变量集（标题、分支、描述、diff、commit messages、repo context、skills context 等）；
2. 发布进度占位评论："Preparing PR description..."（临时评论，完成后删除）；
3. 关联工单提取（可选）：extract_and_cache_pr_tickets()解析 PR 中的 ticket 引用并放入上下文（若 token 预算不足会裁剪，见fit_related_tickets_to_prompt_budget）；
4. 生成预测：retry_with_fallback_models(self._prepare_prediction, ModelType.WEAK)调用弱模型类别完成预测，失败时自动回退到备用模型；_prepare_prediction()内部判断是否走大 PR 分片路径；
5. 解析与后处理：_prepare_data()将 YAML 预测结果重排键序，_prepare_file_labels()生成按语义标签分组的文件字典，_prepare_labels()归一化标签；
6. 组装输出：按use_description_markers走_prepare_pr_answer_with_markers()或_prepare_pr_answer()，后者渲染出标题、正文与 walkthrough 表格，并追加覆盖率脚注、帮助文本、show_relevant_configurations/show_run_details等可选区块；
7. 发布：先向可选外部 sink 推送输出（push_outputs），再按配置发布标签与描述；若发布失败且config.propagate_tool_errors=true，异常会继续向上传播；
8. 清理：编辑/移除进度评论，记录运行状态。

其中walkthrough 表格由process_pr_files_prediction()渲染：按语义标签分组，为每个文件生成带+/-行数统计、行号链接（get_line_link）、折叠列表（adaptive 折叠）的 HTML 表格，并调用insert_br_after_x_chars()对长文本做换行处理以适配评论宽度。

11. 小结

/describe是 PR-Agent 中"输入最少、产出最全"的工具：一条/describe命令即可获得标题、类型、摘要、逐文件走读、序列图与标签六类信息。通过[pr_description]配置段，你可以精确控制每一部分的生成与发布行为；通过 Markers 模板可以把自动内容"镶嵌"进自己撰写的描述中；通过自定义标签则能让标签体系贴合仓库语义。无论是作为 GitHub App / GitLab Webhook 的自动流程，还是手工在评论中触发，它都能显著降低 PR 描述撰写的成本，并让代码变更对评审者与下游工具更可读、可检索。

延伸阅读：自动化触发配置详见 automations_and_usage.md；全部配置项权威默认值见 configuration.toml；渲染后的配置参考见 configuration_reference.md。

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