企业官网建设流程全解析

Pyrefly 发布说明模板解析：占位符设计、LLM 生成管线与安全升级指南

【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly

本文以 Pyrefly 仓库中的发布说明模板 release_notes_template.md 为核心，完整拆解它的章节骨架、全部占位符语义，以及配套脚本 generate_release_notes.py 如何从 GitHub 拉取提交、Issue 与贡献者数据，驱动 LLM 按模板产出版本发布说明。读完后，你将掌握 Pyrefly 发版流程中"模板 + 系统提示词 + 生成脚本 + 后处理校验"的完整协作方式，以及其中给出的代码库安全升级操作步骤。

一、模板的定位与总体结构

Pyrefly 的每一个版本（包括X.Y.Z-dev.N形式的 dev 快照）都在 release_notes/ 目录下留下一份 Markdown 发布说明，例如 release-notes-v1.3.0.md、release-notes-v1.1.0-dev.2.md。这些成品说明全部基于 release_notes/release_notes_template.md 这一模板生成，模板共划分为以下固定骨架：

1. 头部元信息：发布日期、dev 版本免责声明、提交数与贡献者数摘要行；
2. ## ✨ New & Improved：按领域（Type Checking、Language Server、以及可替换的{{AREA_3}}/{{AREA_4}}）分组的 H3 小节 + 扁平列表；
3. ## 🐛 Bug fixes：以 Issue 编号开头的修复条目，附"还有更多"的编号汇总行；
4. ## 📦 Upgrade：升级命令 + "如何安全升级代码库"的四步操作流程；
5. ## 🖊️ Contributors this release：贡献者列表；
6. 页脚说明：本说明只总结主要更新，不逐条列出每个提交。

模板原文的关键片段如下（占位符用{{...}}形式）：

*Release date: {{RELEASE_DATE}}* {{DEV_DISCLAIMER}} {{PROJECT_NAME}} {{VERSION}} bundles **{{COMMIT_COUNT}} commits** from **{{CONTRIBUTOR_COUNT}} contributors**. --- ## ✨ New & Improved ### Type Checking - enhancement 1 - enhancement 2 - enhancement 3 ### Language Server - enhancement 1 - enhancement 2 - enhancement 3 ### {{AREA_3}} - enhancement 1 - enhancement 2 - enhancement 3 ### {{AREA_4}} ... ## 🐛 Bug fixes We closed **{{NUMBER_OF_ISSUES}}** bug issues this release 👏 - **#{{GITHUB_ISSUE_NUMBER}}:** {{DESCRIBE_BUG_FIX_1}} - **#{{GITHUB_ISSUE_NUMBER}}:** {{DESCRIBE_BUG_FIX_2}} - **#{{GITHUB_ISSUE_NUMBER}}:** {{DESCRIBE_BUG_FIX_3}} - And more! #{{GITHUB_ISSUE_NUMBER}}, #{{GITHUB_ISSUE_NUMBER}}, #{{GITHUB_ISSUE_NUMBER}} ## 📦 Upgrade ```bash pip install --upgrade {{PYPI_PACKAGE_NAME}}=={{VERSION}}

How to safely upgrade your codebase

...

🖊️ Contributors this release

{{CONTRIBUTOR_GITHUB_HANDLES}}

模板中出现的占位符及其含义： | 占位符 | 含义 | | --- | --- | | `{{RELEASE_DATE}}` | 发布日期（斜体行） | | `{{DEV_DISCLAIMER}}` | dev 版本的免责声明块；稳定版本为空 | | `{{PROJECT_NAME}}` / `{{VERSION}}` | 项目名（Pyrefly）与版本号 | | `{{COMMIT_COUNT}}` / `{{CONTRIBUTOR_COUNT}}` | 两个 ref 之间的提交总数 / 贡献者总数 | | `{{AREA_3}}` / `{{AREA_4}}` | 除 Type Checking、Language Server 外的动态领域标题 | | `{{NUMBER_OF_ISSUES}}` | 本版本关闭的 bug 类 Issue 总数 | | `{{GITHUB_ISSUE_NUMBER}}` / `{{DESCRIBE_BUG_FIX_N}}` | 单个 bug 修复的编号与描述 | | `{{PYPI_PACKAGE_NAME}}` | PyPI 包名（升级命令用） | | `{{CONTRIBUTOR_GITHUB_HANDLES}}` | 贡献者 handle 的逗号分隔列表 | ## 二、`{{DEV_DISCLAIMER}}`：唯一由脚本预填充的占位符 模板里唯一不经过 LLM 直接落地的占位符是 `{{DEV_DISCLAIMER}}`。在 [generate_release_notes.py](https://link.gitcode.com/i/e05e14b530968136af0afadf340694f5#L64-L85) 中，脚本定义了一段固定的 dev 版本说明文本 `_DEV_DISCLAIMER`，内容大意是：dev 版本（形如 `X.Y.Z-dev.N`）是从主干定期切出的非稳定快照，供早期用户尝鲜新功能并提前暴露问题，但不具备稳定版同等的稳定性与兼容性保证，生产项目不要固定在 dev 版本上。 填充逻辑在 `_dev_disclaimer_for()`（[scripts/generate_release_notes.py#L74-L85](https://link.gitcode.com/i/e05e14b530968136af0afadf340694f5#L74-L85)）：先把版本号去掉 `v` 前缀（因为 `is_prerelease` 解析的是不带 `v` 的标准 semver），再调用 [version_helpers.py](https://link.gitcode.com/i/fb52af2262f0d94e7337e7544d12245f) 中的 `is_prerelease()` 判断版本是否含 `-dev.N` 段（[scripts/version_helpers.py#L110-L113](https://link.gitcode.com/i/fb52af2262f0d94e7337e7544d12245f#L110-L113)）。是预发布版本就插入免责声明，否则替换为空字符串，让模板中该行干净消失。在 `run_generate()` 里，这一步发生在拼装 user prompt 之前（[scripts/generate_release_notes.py#L659](https://link.gitcode.com/i/e05e14b530968136af0afadf340694f5#L659)），注释明确说明：预填充后 LLM 会把这段文本当作"不可改写的固定样板"原样保留。这一点也被写进了系统提示词——[prompt.md](https://link.gitcode.com/i/5fd49073aff833f0e9f436c9c5b7d24d) 要求对 `{{DEV_DISCLAIMER}}` "treat its value as opaque fixed text"，逐字替换、不得改写或重排。 对比实际产物可以验证这一行为：dev 版本 [release-notes-v1.1.0-dev.2.md](https://link.gitcode.com/i/cac709476e2c539f5ebe98b0ce573d44) 第 3-4 行包含完整的引用块免责声明，而稳定版 [release-notes-v1.3.0.md](https://link.gitcode.com/i/397094e5eab9ae800d5bdb545392ca11) 该位置直接省略。 ## 三、Bug fixes 章节：编号规范与"最多 10 条"的硬约束 模板对 bug 修复条目规定了统一格式：`- **#编号:** 描述`，最后一行用 `And more! #a, #b, #c` 汇总未展开的编号。围绕这一格式，仓库里有三层保障： **数据层**。脚本从 GitHub issues 接口翻页拉取区间内已关闭的 Issue（[scripts/generate_release_notes.py#L162-L194](https://link.gitcode.com/i/e05e14b530968136af0afadf340694f5#L162-L194)），再用 `filter_bug_issues()` 按"issue type 为 Bug 或带 bug 标签"筛出 bug 集合（[scripts/generate_release_notes.py#L197-L209](https://link.gitcode.com/i/e05e14b530968136af0afadf340694f5#L197-L209)）。注意接口返回里 PR 也混在 issues 端点中，拉取时会显式跳过含 `pull_request` 键的条目。 **提示词层**。[prompt.md](https://link.gitcode.com/i/5fd49073aff833f0e9f436c9c5b7d24d) 规定：最多写 10 条详细修复，编号必须作为加粗前缀 `**#1234:**` 出现；不允许照抄 Issue 标题原文，要用人话描述"用户遇到了什么问题、现在如何修复了"，1-2 句即可；超过 10 条时把剩余编号合并进 `And more!` 行；贡献者列表按给定的逗号分隔形式原样收录，不得增删。 **后处理层**。即使 LLM 不听话，脚本也会兜底。`validate_and_fix_release_notes()` 调用 `_fix_bug_fix_count()`（[scripts/generate_release_notes.py#L366-L451](https://link.gitcode.com/i/e05e14b530968136af0afadf340694f5#L366-L451)），它会按 🐛 定位 Bug fixes 小节的起止行，用正则 `^- #\d+` 识别详细条目，若超过 10 条则把溢出条目折叠进 `And more!` 行并输出修复警告。`build_user_prompt()`（[scripts/generate_release_notes.py#L246-L358](https://link.gitcode.com/i/e05e14b530968136af0afadf340694f5#L246-L358)）里还额外注入了一条 IMPORTANT 指令，要求"从列表里挑 10 个最重要的 bug 详写，其余编号全部放进 And more!"。 [release-notes-v1.1.0-dev.2.md](https://link.gitcode.com/i/cac709476e2c539f5ebe98b0ce573d44) 是这套规范的一个完整范例：10 条 `**#编号:**` 详述 + 一条 `And more! #3235, #3673, ...` 汇总。 ## 四、New & Improved 章节：分组规则与写作约束 模板固定了 `### Type Checking` 与 `### Language Server` 两个小节，并预留 `{{AREA_3}}`、`{{AREA_4}}` 两个动态领域槽位（实际产物中会填成 `Performance`、`Configuration & CLI`、`Coverage Reporting`、`Experimental Extensions` 等）。[prompt.md](https://link.gitcode.com/i/5fd49073aff833f0e9f436c9c5b7d24d) 对这部分的内容质量有明确约束： - 只写**用户可感知**的变化：描述"用户现在能做什么"，而不是内部实现细节。文档给了一个对照示例——不要写 "Refactor session store rotation"，而要写 "Active sessions now persist across server restarts."； - 每个领域至少 2 条 bullet；相关变更归入同一 H3 小节，列表保持扁平，**禁止使用 Markdown 表格**； - 纯内部重构、构建系统微调、代码清理、无用户可见影响的依赖升级一律不写；没有具体数字的用户可感知性能提升不得单开 "Performance" 小节（内部 solver/binder 重构不算性能改进）； - 不写 "Website" 或 "Documentation" 小节，因为网站与文档站独立于库发布。 提示词还说明 LLM 会拿到 [release_notes_archived.md](https://link.gitcode.com/i/61823faf5d70440ecf93940eb7f8b652) 中过往发布说明作为**风格与语气参考**：对齐最近的措辞习惯、bug 修复描述方式、领域命名习惯，但禁止复制旧内容。在 `run_generate()` 中，该归档文件若存在就会被读入并附在 prompt 末尾（[scripts/generate_release_notes.py#L650-L654](https://link.gitcode.com/i/e05e14b530968136af0afadf340694f5#L650-L654)）。 ## 五、Upgrade 章节：升级命令与代码库安全升级四步法 模板的 Upgrade 小节给出升级命令： ```bash pip install --upgrade {{PYPI_PACKAGE_NAME}}=={{VERSION}}

其中{{PYPI_PACKAGE_NAME}}在真实产物中即pyrefly（见 release-notes-v1.3.0.md 中的pip install --upgrade pyrefly==1.3.0）。

更具实操价值的是"How to safely upgrade your codebase"四步流程，模板原文解释：升级 Pyrefly 或你依赖的第三方库可能会暴露出新类型错误，一次性全部修完往往不现实，因此官方提供了脚本帮助暂时静默这些错误。升级后按以下步骤操作：

1. pyrefly check --suppress-errors
2. 运行你选择的代码格式化工具
3. pyrefly check --remove-unused-ignores
4. 重复上述步骤，直到格式化干净且类型检查通过。

该流程会在代码中插入# pyrefly: ignore注释来静默错误，留待日后回头修复，从而让大规模代码库的升级过程可管理。

这两个 CLI 开关在 Pyrefly 检查命令的实现中均有对应：pyrefly/lib/commands/check.rs 中suppress_errors是检查行为的一个布尔字段，--remove-unused-ignores还接受pyrefly/type/all等取值参数（pyrefly/lib/commands/check.rs#L3161-L3173）。从源码结构看，--suppress-errors的处理发生在错误序列化之后（pyrefly/lib/commands/check.rs#L2012-L2019），与注释中"必须先于 suppress 处理运行"的其他步骤保持明确的执行顺序，保证抑制注释的插入位置与既有忽略语义一致。

六、生成管线全景：从 GitHub 数据到最终 Markdown

把模板串起来的入口是 scripts/generate_release_notes.py。其文档字符串给出的三种典型用法：

# 两个 tag 之间 python generate_release_notes.py facebook/pyrefly v0.1.0 v0.2.0 # 预发布：从 tag 到分支（打 tag 之前先起草说明） python generate_release_notes.py facebook/pyrefly v0.1.0 main --version v0.2.0 # 自定义输出路径 python generate_release_notes.py facebook/pyrefly v0.1.0 v0.2.0 -o notes.md

命令行参数（_parse_args()，scripts/generate_release_notes.py#L473-L541）：

环境变量依赖：GITHUB_TOKEN（GitHub PAT，也可写入.env，由load_env_file()向上逐级查找，见 scripts/github_utils.py#L87-L131）和OPENAI_API_KEY。

run_generate()（scripts/generate_release_notes.py#L594-L686）的执行链路是：

1. 解析 ref：from_tag必须是 tag（get_tag_date()会区分 annotated tag 与 lightweight tag 两种 ref 结构，scripts/github_utils.py#L524-L559）；to_ref由resolve_ref_date()先按 tag 解析、失败再按 branch 解析（scripts/generate_release_notes.py#L88-L114），分支场景下用"当前时间"作为区间终点，支持打 tag 前预写说明；
2. 拉取提交：get_commits_between_tags()基于 compare API 翻页（每页 100 条）。这里有两处防御性设计值得注意：GitHub compare 端点单次响应最多 250 条提交但total_commits报告真实规模，所以脚本从第一页"锁定"总数并在收满后停止；若最终数量与total_commits不符会直接抛错拒绝生成——因为"从部分区间生成的说明会静默漏掉整个功能，而不是显得不对"（scripts/generate_release_notes.py#L117-L159）；
3. 提取贡献者：ContributorAnalyzer._extract_contributors()优先取 commit 的 GitHub author，取不到再回退到 commit 消息里的姓名/邮箱，并按user:/name:前缀区分两类贡献者；bot（[bot]后缀、API 返回的type == "Bot"、以及 dependabot/renovate 等已知模式名单）会被整体排除（scripts/github_utils.py#L356-L410、scripts/github_utils.py#L39-L79）；
4. 拉取 Issue：按区间日期翻页拉取已关闭 Issue，过滤 PR 后筛出 bug 集合；
5. 拼装 prompt：user prompt 依次包含项目/版本/日期/各项计数、完整模板（代码围栏内）、提交日志（短 SHA + 作者 + 缩进消息）、bug 列表（编号 + 标题 + 正文前 500 字）、全部已关闭 Issue、贡献者 handle 列表（按提交数降序，GitHub 用户加@前缀）、以及归档的历史发布说明；
6. 调用 LLM：call_openai()使用 Chat Completions 接口，model 为gpt-4o，max_tokens16384（scripts/generate_release_notes.py#L217-L238）；
7. 后处理与落盘：validate_and_fix_release_notes()做 bug 条目数修正，补结尾换行后写入输出路径，控制台打印"Post-generation fixes applied"警告。

系统提示词 prompt.md 的"General"部分还规定了两条输出纪律：严格遵循模板、只输出最终 Markdown（不得用代码围栏包裹整篇文档）、结尾不得追加 commit 列表或 SHA 清单。

七、版本语义：模板中版本号背后的 semver 规则

模板摘要行里的{{VERSION}}与升级命令里的版本号都受 scripts/version_helpers.py 定义的规范约束：合法版本是标准 semverM.m.p或M.m.0-dev.N，且各段禁止前导零、-dev后必须带数字（解析失败会抛ValueError）。这些规则有完整的参数化测试覆盖，包括对1.2.0-rc.1、v1.2.0、1.2.0.dev4等"看起来对但非法"形式的拒绝（scripts/tests/test_version_helpers.py）。

与发版相关的两个版本映射也在此实现，可解释模板升级命令在不同分发渠道的形态差异：to_pypi()把1.2.0-dev.4映射为 PEP 440 的1.2.0.dev4（稳定版原样通过）；to_marketplace()因为 VS Code Marketplace 不接受 semver 预发布标识，把M.m.0-dev.N映射为M.(m-1).(9000+N)（scripts/version_helpers.py#L116-L184）。因此模板中pip install --upgrade {{PYPI_PACKAGE_NAME}}=={{VERSION}}这一行，其版本值天然符合 PyPI 的 PEP 440 形式。

八、对照成品验证模板落地

以稳定版 release-notes-v1.3.0.md 为例，可以逐段看到模板骨架的落地形态：头部*Release date: September 10, 2026*对应{{RELEASE_DATE}}；摘要行 "Pyrefly v1.3.0 bundles934 commitsfrom71 contributors" 对应{{PROJECT_NAME}}/{{VERSION}}/{{COMMIT_COUNT}}/{{CONTRIBUTOR_COUNT}}；"New & Improved" 下出现 Type Checking、Language Server、Performance、Configuration & CLI、Experimental Extensions 多个 H3 领域（即动态{{AREA_N}}的实例）；Bug fixes 部分以We closed **88** bug issues this release 👏开头，5 条**#编号:**详述；Upgrade 小节保留pip install --upgrade pyrefly==1.3.0与完整四步安全升级流程；结尾保留"本说明只总结主要更新"的页脚注释。dev 版 release-notes-v1.1.0-dev.2.md 则额外验证了{{DEV_DISCLAIMER}}的填充行为与 "And more!" 汇总行的格式。

九、小结

release_notes_template.md 不只是一份填空模板，它与 prompt.md 的写作约束、generate_release_notes.py 的数据采集与后处理校验、version_helpers.py 的版本语义共同构成了 Pyrefly 可复现的发版说明生产线：模板定义结构与占位符契约，脚本负责数据完整性（分页、总数校验、bot 过滤）与格式兜底（bug 条目折叠），LLM 负责把原始提交与 Issue 转写成用户视角的叙述。对维护类似发布流程的团队而言，这套"模板占位符 + 提示词纪律 + 确定性后处理"的分工方式，以及其中pyrefly check --suppress-errors/--remove-unused-ignores的安全升级四步法，都是可以直接借鉴的成熟做法。

【免费下载链接】pyreflyA fast type checker and language server for Python项目地址: https://gitcode.com/GitHub_Trending/py/pyrefly