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 这一模板生成模板共划分为以下固定骨架头部元信息发布日期、dev 版本免责声明、提交数与贡献者数摘要行## ✨ New Improved按领域Type Checking、Language Server、以及可替换的{{AREA_3}}/{{AREA_4}}分组的 H3 小节 扁平列表## Bug fixes以 Issue 编号开头的修复条目附还有更多的编号汇总行## Upgrade升级命令 如何安全升级代码库的四步操作流程## ️ Contributors this release贡献者列表页脚说明本说明只总结主要更新不逐条列出每个提交。模板原文的关键片段如下占位符用{{...}}形式*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 pyrefly1.3.0。更具实操价值的是How to safely upgrade your codebase四步流程模板原文解释升级 Pyrefly 或你依赖的第三方库可能会暴露出新类型错误一次性全部修完往往不现实因此官方提供了脚本帮助暂时静默这些错误。升级后按以下步骤操作pyrefly check --suppress-errors运行你选择的代码格式化工具pyrefly check --remove-unused-ignores重复上述步骤直到格式化干净且类型检查通过。该流程会在代码中插入# 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参数说明repoowner/repo形式如facebook/pyreflyfrom_tag起始 tag开区间exclusiveto_ref结束 tag 或分支名分支时用该分支最新提交--version说明中显示的版本号默认等于to_refto_ref是分支名时使用--template自定义模板路径默认release_notes/release_notes_template.md--prompt自定义系统提示词路径默认release_notes/prompt.md--output/-o输出文件默认release-notes-version.md写在 release_notes 目录--providerLLM 提供方当前仅支持openai默认环境变量依赖GITHUB_TOKENGitHub PAT也可写入.env由load_env_file()向上逐级查找见 scripts/github_utils.py#L87-L131和OPENAI_API_KEY。run_generate()scripts/generate_release_notes.py#L594-L686的执行链路是解析 reffrom_tag必须是 tagget_tag_date()会区分 annotated tag 与 lightweight tag 两种 ref 结构scripts/github_utils.py#L524-L559to_ref由resolve_ref_date()先按 tag 解析、失败再按 branch 解析scripts/generate_release_notes.py#L88-L114分支场景下用当前时间作为区间终点支持打 tag 前预写说明拉取提交get_commits_between_tags()基于 compare API 翻页每页 100 条。这里有两处防御性设计值得注意GitHub compare 端点单次响应最多 250 条提交但total_commits报告真实规模所以脚本从第一页锁定总数并在收满后停止若最终数量与total_commits不符会直接抛错拒绝生成——因为从部分区间生成的说明会静默漏掉整个功能而不是显得不对scripts/generate_release_notes.py#L117-L159提取贡献者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拉取 Issue按区间日期翻页拉取已关闭 Issue过滤 PR 后筛出 bug 集合拼装 promptuser prompt 依次包含项目/版本/日期/各项计数、完整模板代码围栏内、提交日志短 SHA 作者 缩进消息、bug 列表编号 标题 正文前 500 字、全部已关闭 Issue、贡献者 handle 列表按提交数降序GitHub 用户加前缀、以及归档的历史发布说明调用 LLMcall_openai()使用 Chat Completions 接口model 为gpt-4omax_tokens16384scripts/generate_release_notes.py#L217-L238后处理与落盘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).(9000N)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 pyrefly1.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考