webnovel-writer 插件发版指南：从发版审计到 GitHub Release 的全流程自动化实践-酒店常州论坛

webnovel-writer 插件发版指南：从发版审计到 GitHub Release 的全流程自动化实践

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

本指南面向 webnovel-writer 插件的维护者与贡献者，完整讲解从「发版前审计」到「自动打 tag 生成 GitHub Release」的标准发布流程：包括版本边界确认、双文档发布说明体系（CHANGELOG.md+releases/vX.Y.Z.md）、版本元数据同步脚本、三道本地校验关卡，以及两条 CI 工作流的自动兜底。读完你不仅能按规范发版，还能理解校验脚本与工作流的底层实现，独立排查发版失败。

一、发版前审计：先锁定版本边界

webnovel-writer 的发版原则非常明确：发布说明必须覆盖「上一个正式版本 tag 到本次发布提交」的全部变化，而不是只写最后一次提交。发版前先用三个 git 命令确认版本边界：

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

三个命令各司其职：

命令	作用
`git tag --list "v*" --sort=-v:refname`	按语义化版本倒序列出全部正式 tag，确认上一个正式版本号
`git log --oneline v上一版本..HEAD`	列出上一 tag 之后的所有提交，作为变化清单来源
`git diff --stat v上一版本..HEAD`	从文件维度统计变化规模，帮助判断改动影响面

拿到变化清单后，把全部变化分成四类，分别写入对应章节：

给作者看的变化：写章、审查、规划、查询、恢复、文档等用户能感受到的变化——这是发布说明的主角，要用中文网文作者能理解的场景语言描述。
兼容性：是否需要迁移旧书项目，是否改变现有/webnovel-*命令习惯。
已知影响：跳过项、限制、需要注意的风险。
给维护者：新增 CLI、schema、helper、测试、CI、内部重构。

这四类与 docs/operations/plugin-release.md 中描述的发版审计口径完全一致，后续所有文档章节都围绕这四类展开。

二、发布说明来源：双文档体系与 README 摘要

每个正式版本都必须有两份文档，二者角色不同、缺一不可：

CHANGELOG.md：长期更新日志，持续累积所有正式版本的用户可感知变化。
releases/vX.Y.Z.md：GitHub Release 正文的唯一来源，工作流创建 Release 时直接读取该文件内容。

而README 只保留一句中文用户收益摘要，不要把 README 当完整 changelog。当前版本行示例（来自原发版指南）：

| **v6.2.0 (当前)** | 写章结果更清楚，失败后更好恢复 |

这套分工在 releases/README.md 中有完整的维护规则与固定模板。写作顺序为：

先确定发版范围，例如v6.1.0..v6.2.0。
先写「给作者看的变化」，使用中文网文作者能理解的场景语言。
再写「是否需要改旧项目」和「已知影响」。
最后写「给维护者」，记录 CLI、schema、测试、CI、内部结构变化。
运行validate_release_notes.py检查格式和范围。
推送到master后由Plugin Release工作流自动创建 tag 和 GitHub Release；已存在的 tag 或 Release 不会重复创建。

固定模板如下（实际validate_release_notes.py会强制其中 5 个小节必须存在，见下文）：

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

实际仓库中的 releases/v6.2.1.md 与 releases/v6.2.0.md 就是按这套模板落地的范例。

三、版本同步：一键更新四处版本元数据

写好两份文档后，运行版本同步脚本，一次性更新版本号和 README 摘要：

python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --version X.Y.Z --release-notes "一句中文用户收益"

该命令会更新四处位置（对应源码 webnovel-writer/scripts/sync_plugin_version.py 中的sync_versions()）：

更新对象	文件路径	说明
插件版本号	`webnovel-writer/.claude-plugin/plugin.json`	插件自身 manifest，当前仓库为`6.2.1`
Marketplace 条目	`.claude-plugin/marketplace.json`	`plugins[]`中`name=webnovel-writer`条目的`version`字段
版本徽章	`README.md`	匹配`badge/version-X.Y.Z-brightgreen.svg`形式的徽章链接
当前版本行	`README.md`	版本表中形如`\| vX.Y.Z (当前) \| 说明 \|`的行

从源码看，同步逻辑有几个值得注意的实现细节：

幂等：只有当plugin.json或marketplace.json中版本与目标不一致、或 README 内容需要更新时才会写盘，changed=False时输出No changes needed. Current version: X.Y.Z，不会产生无意义的 diff。
行内更新而非整表重写：update_readme_release()先定位 README 版本表的表头与分隔行，再逐行用正则^\| \*\*v...匹配版本行，更新目标版本行的(当前)标记与摘要；若目标版本在表中不存在，则自动在分隔行后插入新行。
版本号严格校验：VERSION_PATTERN = ^\d+\.\d+\.\d+$，--version与--expected-version都必须符合X.Y.Z格式，否则parser.error直接拒绝执行。
读与写均强制 UTF-8：load_json/save_json/load_text/save_text统一使用encoding="utf-8"，命令行的-X utf8进一步保证 Windows 下脚本行为一致。

脚本也提供纯校验模式（不发版、只检查一致性）：

python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --check python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --check --expected-version X.Y.Z

check_versions()会比对四个版本来源：plugin.json、marketplace.json、README 当前版本行、README 徽章，任何一个不一致都会打印 mismatch 列表并返回退出码 1；--expected-version用于额外强制要求当前元数据等于指定版本，只能与--check搭配使用。

四、本地校验：提交前的四道关卡

提交前至少运行以下命令，确保文档、元数据与插件包全部合格：

python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --check --expected-version X.Y.Z python -X utf8 webnovel-writer/scripts/validate_release_notes.py --version X.Y.Z python -X utf8 webnovel-writer/scripts/validate_plugin_package.py git diff --check

涉及代码或提示词变化时，还要运行对应 pytest、行为评估或 smoke test，并把结果写进releases/vX.Y.Z.md的「验证」小节（见 docs/operations/operations.md 的测试一节，可使用run_tests.ps1 -Mode smoke/full与run_behavior_evals.py）。

4.1 发布说明校验：validate_release_notes.py

webnovel-writer/scripts/validate_release_notes.py 是发布说明的「格式警察」，从源码看它逐项检查：

标题：文件必须以# vX.Y.Z -开头，强制「一句中文用户收益」的写法。
必需小节：## 发版范围、## 给作者看的变化、## 是否需要改旧项目、## 给维护者、## 验证五个小节缺一不可（REQUIRED_RELEASE_HEADINGS常量）。
发版范围：正文必须提及上一个正式 tag（如v6.2.0），防止只写最后一次提交。
作者向语言：正文必须至少出现作者、写章、网文、故事、正文中的一个词（AUTHOR_WORDS），防止发布说明写成纯内部技术日志。
CHANGELOG 联动：CHANGELOG.md必须存在、必须包含当前版本小节、且该小节必须提及上一个 tag。
版本推断：--version未指定时从plugin.json读取；--previous-tag未指定时自动执行git tag --list "v*"并排序选出小于当前版本的最近 tag。
输出格式：--format text（默认）或--format json，任何 issue 都会给出code / message / path / repair四元组与修复建议，退出码 0/1 便于 CI 直接使用。

脚本对外暴露的 schema 版本为webnovel-release-notes-validator/v1，输出含version、previous_tag、release_note、changelog路径与issues列表，机器可读性很强。对应测试见 webnovel-writer/scripts/tests/test_validate_release_notes.py。

4.2 插件包校验：validate_plugin_package.py

webnovel-writer/scripts/validate_plugin_package.py 按 Claude Code plugin-dev 思路检查插件包整体健康度，从源码看检查面覆盖六大块：

manifest（plugin.json）：插件名必须 kebab-case、版本必须X.Y.Z、description非空。
marketplace（marketplace.json）：plugins[]中必须存在webnovel-writer条目、source必须为./webnovel-writer、版本与 plugin.json 一致；在插件根目录运行时可忽略该项（降级为 warning）。
README 版本：版本行与徽章必须与 plugin.json 一致。
Skill / Agent frontmatter：遍历skills/*/SKILL.md与agents/*.md，Skill 必须有name、description，Agent 还必须多一个tools字段。
可选资产：插件 LICENSE 必须存在（error）；dashboard/frontend/dist目录缺失记为 warning（提示发布前需先构建前端）；hooks/hooks.json若存在则必须采用 plugin-dev 的 wrapper 格式（外层含description与hooks）。
路径可移植性：扫描 Skill / Agent / manifest / hooks 组件内容，禁止出现C:\Users\...、/Users/...、/home/...等本地绝对路径（warning），组件内应统一使用${CLAUDE_PLUGIN_ROOT}或相对路径。

默认只把 severity 为 error 的 issue 视为失败；加--strict后 warning 也视为失败。对应测试见 webnovel-writer/scripts/tests/test_validate_plugin_package.py。

4.3 git diff --check

git diff --check负责捕获空白错误（行尾空格、空白冲突标记等），保证提交的 diff 干净，这也是 GitHub Actions 常见的第一步卫生检查。

五、自动发版：Plugin Release 工作流

本地校验全部通过后，按以下顺序完成发版：

确认本地校验通过。
提交并推送版本说明和版本元数据到master。
Plugin Release工作流自动接管后续步骤。

工作流定义在 .github/workflows/plugin-release.yml，其自动执行序列为：

校验plugin.json、marketplace.json、README 版本一致：运行sync_plugin_version.py --check --expected-version <解析出的版本>。
校验CHANGELOG.md和releases/vX.Y.Z.md存在且覆盖上个 tag：运行validate_release_notes.py --version <版本>。
校验插件包结构：运行validate_plugin_package.py。
创建并推送vX.Y.Ztag：用git ls-remote检查远端 tag 是否已存在，不存在才git tag+git push origin。
使用releases/vX.Y.Z.md创建 GitHub Release：用gh release view检查 Release 是否已存在，不存在才用softprops/action-gh-release@v2以body_path: releases/vX.Y.Z.md创建。

几个重要的幂等与容错设计（来自工作流源码）：

工作流只在push到master且触及版本相关文件路径时触发（paths限定了 marketplace.json、plugin.json、README.md、CHANGELOG.md、releases/、三个 scripts、工作流自身）。
tag 已存在则跳过打 tag，Release 已存在则跳过建 Release；若之前只创建了 tag 但 Release 缺失，重跑工作流会补建 Release。
workflow_dispatch支持手动兜底触发：手动运行时可以输入version（如6.2.0），也可以留空——留空时工作流会从plugin.json读取当前版本。
环境要求：Python 3.11 +actions/checkout@v4（fetch-depth: 0保证 tag 历史完整，供版本推断使用），权限为contents: write。

六、自动版本校验：Plugin Version Check 工作流

Plugin Version Check工作流（.github/workflows/plugin-version.yml）在Push / PR时自动运行，作为发版前的持续门禁，检查四项：

版本元数据一致（sync_plugin_version.py --check）。
README 版本徽章一致（同上，含在--check内）。
当前版本有 release note（validate_release_notes.py）。
CHANGELOG.md包含当前版本（同上）。

触发该工作流的文件清单（与原文档一致）：

.claude-plugin/marketplace.json
webnovel-writer/.claude-plugin/plugin.json
webnovel-writer/scripts/sync_plugin_version.py
webnovel-writer/scripts/validate_release_notes.py
README.md
CHANGELOG.md
releases/**

也就是说，任何一次版本元数据或发布说明的改动，都会立即触发一致性校验，问题在 PR 阶段就能暴露，而不是等到发版时才发现。

七、实战复盘：v6.2.1 发版示例

仓库中 releases/v6.2.1.md 是一次完整的真实发版记录，可对照前文逐项验证：

发版范围：v6.2.0..v6.2.1，核心是修复 issue #125。
给作者看的变化：Windows 上写章提交偶发WinError 5（拒绝访问）的自动等待重试、VSCodefiles.watcherExclude建议、避免同步盘目录建议——全部是作者能感知、能行动的中文场景语言。
是否需要改旧项目：明确「不需要，无需任何迁移」。
给维护者：security_utils.atomic_write_json的os.replace遇PermissionError改为指数退避重试（20ms→500ms 共 10 次、约 2.6 秒窗口），全部 JSON 投影共用该写入函数；新增 webnovel-writer/scripts/tests/test_security_utils_atomic.py 四个用例（含 Windows 真实句柄占用复现）。
验证：774 passed 全量 pytest、版本同步校验、发布说明校验、插件包校验、git diff --check全部通过。

对应 CHANGELOG.md 的 v6.2.1 小节同步记录了同一信息，README 的当前版本行则只保留一句中文收益摘要。这正是「CHANGELOG 长期累积、releases/vX.Y.Z.md 作为 Release 正文、README 一句话摘要」三级分工的实际落地。

八、发版中的常见问题与维护建议

基于源码实现与文档口径，整理发版时最常遇到的几个问题：

版本元数据不一致怎么办？直接运行sync_plugin_version.py --version X.Y.Z --release-notes "..."重新同步，它会同时修正 plugin.json、marketplace.json 和 README 两处；再跑--check确认四处一致。

发布说明校验失败？按validate_release_notes.py --format json输出的issues数组逐条修复，重点核对：标题是否以# vX.Y.Z -开头、五个必需小节是否齐全、正文是否提到上一个 tag、是否包含作者向词汇、CHANGELOG 是否同步更新。repair字段会直接给出修复指引。

tag 已存在但 Release 缺失？无需手动干预——直接重跑Plugin Release工作流，它会跳过已存在的 tag、补齐缺失的 GitHub Release。

插件包校验的 warning 要不要管？默认只拦截 error；但dashboard/frontend/dist缺失、本地绝对路径等 warning 建议发布前处理，CI 中可用--strict强制零 warning 放行。

本地绝对路径泄漏：从 webnovel-writer/scripts/validate_plugin_package.py 的_check_portability()可见，插件组件内出现C:\Users\...、/Users/...、/home/...会被标记，插件内应统一使用${CLAUDE_PLUGIN_ROOT}或相对路径——这也是插件能否跨机器、跨 Marketplace 安装的关键。

附：发版相关文件索引

发版指南本体：docs/operations/plugin-release.md
发布说明维护规则与模板：releases/README.md
长期更新日志：CHANGELOG.md
版本发布正文：releases/v6.2.1.md、releases/v6.2.0.md
版本同步脚本：webnovel-writer/scripts/sync_plugin_version.py
发布说明校验脚本：webnovel-writer/scripts/validate_release_notes.py
插件包校验脚本：webnovel-writer/scripts/validate_plugin_package.py
自动发版工作流：.github/workflows/plugin-release.yml
版本门禁工作流：.github/workflows/plugin-version.yml
版本元数据：webnovel-writer/.claude-plugin/plugin.json、.claude-plugin/marketplace.json
运维总览：docs/operations/operations.md

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析