企业官网建设流程全解析

webnovel-writer 发布说明维护规则：从 vX.Y.Z.md 模板到自动化校验的完整发版流程

【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统，解决 AI 写作中的「遗忘」和「幻觉」问题，支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer

导读

本文讲解 webnovel-writer 仓库的版本发布说明（Release Notes）维护体系：每次正式发版如何在releases/vX.Y.Z.md中沉淀一份「从上一个 tag 到本次发布之间完整用户可感知变化」的中文发布说明，如何按固定模板组织作者视角与维护者视角的内容，以及如何用validate_release_notes.py与sync_plugin_version.py两个脚本把发布说明、CHANGELOG、插件版本元数据串成一条可自动校验、可被 CI 复用的发布流水线。读完本文，你将掌握该仓库发版的完整写作顺序、模板字段语义、校验规则的源码级细节，以及一套可直接复制的验证命令。

一、发布说明在仓库中的角色定位

releases/README.md 开篇就定下了两条硬规则：

1. 每次正式发版必须在releases/目录下新增一份vX.Y.Z.md，这份文件是 GitHub Release 正文的唯一来源；
2. 发布说明不是最后一次提交的摘要，而是从上一个正式 tag 到本次发布提交之间的完整用户可感知变化。

这个定位决定了发布说明的写作范围：只记录用户（作者）与维护者真正能感知的变化，而不是罗列提交历史。README 本身只保留一句短摘要，完整变化分别落在两份文件里：

• releases/vX.Y.Z.md：发版时的完整发布说明，对应 GitHub Release 正文；
• CHANGELOG.md：按版本累积的更新日志，其开头明确写着「发布说明优先面向中文网文作者：先说写作体验有什么变化，再补维护者关心的技术细节」。

仓库当前最新版本为 6.2.1（见 webnovel-writer/.claude-plugin/plugin.json），releases/目录下已有两份真实示例：releases/v6.2.0.md 与 releases/v6.2.1.md，可作为写作范本。

二、写发布说明前的 git 准备命令

文档要求在动笔前先运行三条命令，确定「本次发版到底覆盖了哪些变化」：

git tag --list "v*" --sort=-v:refname git log --oneline v上一版本..HEAD git diff --stat v上一版本..HEAD

• 第一条列出所有正式 tag 并按版本号倒序排列，用于确认上一个正式版本，例如v6.2.0；
• 第二条列出从上个 tag 到当前 HEAD 的全部提交，用于盘点用户可感知的行为变化；
• 第三条给出文件级别的改动统计，帮助定位代码结构变化，供「给维护者」一节取材。

值得注意的是，上一版本的推断在发布说明校验器中也有自动化实现：validate_release_notes.py的_infer_previous_tag函数会执行git tag --list "v*"，解析出所有形如X.Y.Z的 tag，筛选出版本号小于当前版本者，再取其中最大的一个作为上一版本。也就是说，即使你忘了手写v6.1.0，校验器也会尝试从 git tag 中自动推断范围并核对发布说明是否提到了它。

三、写作顺序：先作者、后维护者

releases/README.md 给出了明确的六步写作顺序，核心思想是发布说明的读者首先是中文网文作者，其次才是维护者：

1. 先确定发版范围，例如v6.1.0..v6.2.0——范围用上一 tag 到本次发布提交表示，覆盖该区间全部变化，而不是只写最后一个版本号提交；
2. 先写「给作者看的变化」，使用中文网文作者能理解的场景语言，如「写章失败后更好恢复」「结果更好读」，避免出现内部 JSON 字段或类名；
3. 再写「是否需要改旧项目」和「已知影响」，明确告知作者升级成本与行为边界；
4. 最后写「给维护者」，记录 CLI、schema、测试、CI、内部结构变化；
5. 运行validate_release_notes.py检查格式和范围；
6. 推送到master后由Plugin Release工作流自动创建 tag 和 GitHub Release；已存在的 tag 或 Release 不会重复创建。

以 releases/v6.2.1.md 为例，「给作者看的变化」第一句是「修复 Windows 上写章提交时偶发的WinError 5（拒绝访问）」，紧接着给出 VSCode 用户的操作建议（把**/.webnovel/**加入files.watcherExclude）；而「给维护者」一节则直接落到security_utils.atomic_write_json的指数退避重试参数（20ms→500ms 共 10 次，约 2.6 秒窗口）与新增测试文件上。同一件事，两套表述，这就是「作者视角」与「维护者视角」分层的最佳示范。

四、固定模板逐段解读

releases/README.md 提供了一份固定模板，所有版本文件必须照此结构撰写：

# vX.Y.Z - 一句中文用户收益 ## 发版范围 本次发布覆盖从 `vA.B.C` 到本发布提交的全部变化。 ## 给作者看的变化 - ... ## 是否需要改旧项目 - ... ## 适合谁升级 - ... ## 已知影响 - ... ## 给维护者 - ... ## 验证 - ...

各段落的语义与填写要点如下：

值得注意：## 适合谁升级与## 已知影响是可选段落，而## 发版范围、## 给作者看的变化、## 是否需要改旧项目、## 给维护者、## 验证五个段落是校验器强制要求的（见下节REQUIRED_RELEASE_HEADINGS）。v6.2.0 的发布说明使用了全部八个部分，是模板的完整示例；v6.2.1 属于补丁版本，则精简为范围、作者变化、旧项目、维护者、验证五段。

五、发布说明校验器：validate_release_notes.py 源码级解析

校验入口为 webnovel-writer/scripts/validate_release_notes.py，核心函数validate_release_notes()依次做以下检查，并把所有问题汇总成带code、message、path、repair四个字段的 issue 列表：

1. 版本号合法性（version.invalid）目标版本必须匹配VERSION_PATTERN = re.compile(r"^\d+\.\d+\.\d+$")，即严格的X.Y.Z语义化版本格式；版本来源优先取--version参数，缺省时读取 webnovel-writer/.claude-plugin/plugin.json 中的version字段。

2. 发布说明文件存在性（release_note.missing）检查releases/vX.Y.Z.md是否存在，缺失时的修复建议是「新增 releases/vX.Y.Z.md，并覆盖上个 tag 到本次发布的全部变化」。

3. 标题格式（release_note.title）文件必须以# vX.Y.Z -开头（startswith精确匹配），保证 GitHub Release 与模板规范一致。

4. 必需段落（release_note.heading）用REQUIRED_RELEASE_HEADINGS常量逐一检查，缺失任何一个即报错：

REQUIRED_RELEASE_HEADINGS = ( "## 发版范围", "## 给作者看的变化", "## 是否需要改旧项目", "## 给维护者", "## 验证", )

5. 发版范围核对（release_note.range）如果推断出了上一 tag，则发布说明文本中必须出现该 tag 字样，防止漏写范围。

6. 作者视角校验（release_note.audience）用AUTHOR_WORDS = ("作者", "写章", "网文", "故事", "正文")检查正文是否包含作者可理解的场景词汇，防止发布说明写成纯技术日志——这从机制上保证了「先写作者能看懂的变化」这条规则不被绕过。

7. CHANGELOG 联动（changelog.missing/changelog.version/changelog.range）校验 CHANGELOG.md 存在、包含当前版本小节、且当前小节中也提到了上一 tag。_changelog_section用^##\s+v{version}正则截取当前版本对应的章节文本。

命令行的退出码约定为：校验通过返回 0 并输出OK release notes，存在任何 issue 返回 1 并逐条打印ERROR {code}: {message}、path与repair。支持--format json输出结构化报告（schema 标识为webnovel-release-notes-validator/v1），便于 CI 或脚本消费。

对应的单元测试位于 webnovel-writer/scripts/tests/test_validate_release_notes.py，覆盖了完整作者视角发布说明通过校验、缺文件报release_note.missing、发布说明未提上一 tag 报release_note.range、CHANGELOG 当前小节未提上一 tag 报changelog.range等典型失败路径，可作为理解每类错误码的活样例。

六、版本元数据同步：sync_plugin_version.py

发版不只写文档，还要让插件元数据与文档保持一致。负责这件事的是 webnovel-writer/scripts/sync_plugin_version.py，它把四处版本信息绑在一起：

• webnovel-writer/.claude-plugin/plugin.json的version；
• .claude-plugin/marketplace.json中同名插件的version；
• README.md 版本表格中标记(当前)的那一行（update_readme_release会把目标版本行标为当前、并更新版本徽章badge/version-X.Y.Z-brightgreen.svg）。

常用命令：

# 同步元数据到新版本并刷新 README 当前版本行 python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --version 6.2.1 --release-notes "一句中文摘要" # 只检查四处版本是否一致（可配合 --expected-version 锁定期望值） python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --check --expected-version 6.2.1

--check模式会比较 plugin.json、marketplace.json、README 当前行、README 徽章四处版本，任何不一致都以非零退出码报出Version mismatch detected明细；--expected-version只能与--check搭配使用，用于 CI 中锁定预期版本。两个脚本的关系是：validate_release_notes.py直接import sync_plugin_version，复用其VERSION_PATTERN与load_json，所以发布说明校验天然与版本元数据读取共享同一套逻辑。

七、验证命令与自动化发布闭环

releases/v6.2.1.md 的「验证」一节给出了完整的发版验证命令清单，可以作为每次发版的标准动作：

python -m pytest # 全量测试（v6.2.1 时为 774 passed） python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --check --expected-version 6.2.1 python -X utf8 webnovel-writer/scripts/validate_release_notes.py --version 6.2.1 python -X utf8 webnovel-writer/scripts/validate_plugin_package.py git diff --check

其中-X utf8确保在 Windows 等环境下以 UTF-8 处理中文内容；validate_plugin_package.py负责校验插件包整体结构（对应测试 webnovel-writer/scripts/tests/test_validate_plugin_package.py）。

发布流程的最后一环是自动化：推送到master后由Plugin Release工作流自动创建 tag 和 GitHub Release，且已存在的 tag 或 Release 不会重复创建（幂等）；v6.2.0 的发布说明中还特别提到该工作流「保留手动兜底入口」，即自动化失败时可手动触发。

八、写作检查清单

综合 releases/README.md 的规则与两个脚本的校验逻辑，写一份合格的发布说明需要依次自检：

1. ✅ 已运行三条 git 命令确认发版范围；
2. ✅releases/vX.Y.Z.md已新增，标题以# vX.Y.Z -开头；
3. ✅ 五个必需段落齐全，且「给作者看的变化」用中文网文作者能理解的场景语言；
4. ✅ 发布说明与 CHANGELOG 当前小节都提到了上一 tag；
5. ✅ 正文包含「作者 / 写章 / 网文 / 故事 / 正文」等作者视角词汇；
6. ✅validate_release_notes.py --version X.Y.Z输出OK；
7. ✅sync_plugin_version.py --check --expected-version X.Y.Z四处版本一致；
8. ✅ 推送到master后确认Plugin Release工作流自动生成 tag 与 Release。

这套规则的价值在于把「发布说明质量」从依赖个人自觉的软要求，变成了有模板、有校验器、有测试、有 CI 的硬约束——作者视角的内容完整性由release_note.audience强制兜底，发版范围与 CHANGELOG 的同步由range类检查码强制兜底，版本元数据的一致性由sync_plugin_version.py --check强制兜底，最终形成一条从写作到发布的完整闭环。

【免费下载链接】webnovel-writer基于 Claude Code 的长篇网文辅助创作系统，解决 AI 写作中的「遗忘」和「幻觉」问题，支持 200 万字量级 连载创作。项目地址: https://gitcode.com/GitHub_Trending/we/webnovel-writer