webnovel-writer/docs/operations/plugin-release.md

插件发版指南

本项目的发布说明优先面向中文网文作者：先说明这版对写书有什么帮助，再补维护者关心的 CLI、schema、测试和 CI 细节。

发版前审计

发布说明必须覆盖“上一个正式版本 tag 到本次发布提交”的全部变化，而不是只写最后一次提交。

发版前先确认版本边界：

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

把变化分成四类：

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

发布说明来源

每个正式版本都必须有两份文档：

• CHANGELOG.md：长期更新日志。
• releases/vX.Y.Z.md：GitHub Release 正文的唯一来源。

README 只保留一句中文用户收益摘要，例如：

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

不要把 README 当完整 changelog。

版本同步

写好 CHANGELOG.md 和 releases/vX.Y.Z.md 后，再同步版本号和 README 摘要：

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

该命令会更新：

• webnovel-writer/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• README.md 版本徽章
• README.md 当前版本行

本地校验

提交前至少运行：

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 的“验证”小节。

通过 GitHub Actions 发版

1. 确认本地校验通过。
2. 提交并推送版本说明和版本元数据。
3. 打开仓库 Actions 页面，选择 Plugin Release。
4. 输入 version，例如 6.2.0。
5. 工作流会自动：
   • 校验 plugin.json、marketplace.json、README 版本一致。
   • 校验 CHANGELOG.md 和 releases/vX.Y.Z.md 存在且覆盖上个 tag。
   • 校验插件包结构。
   • 创建并推送 vX.Y.Z tag。
   • 使用 releases/vX.Y.Z.md 创建 GitHub Release。

自动版本校验

Plugin Version Check 工作流会在 Push / PR 时自动检查：

• 版本元数据一致。
• README 版本徽章一致。
• 当前版本有 release note。
• 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/**