fixed # 修复部分工作流BUG

docs/README.md

@@ -6,6 +6,7 @@
 
 | 文档 | 用途 |
 |---|---|
+| [nonebot-release.md](nonebot-release.md) | NoneBot 同步、自动版本标签、PyPI发布及失败重跑 |
 | [catalogue-updates.md](catalogue-updates.md) | Service 作物维护、发布、启动更新、缓存与兼容回滚 |
 | [23-seasonal-events-and-rust-service.md](23-seasonal-events-and-rust-service.md) | 节日活动交互备选、Rust 发布中心、同步、资产事务、过期清理与上线规划（草案） |
 | [09-foundation.md](09-foundation.md) | 已实现的第一批核心、API、测试与限制 |

docs/nonebot-release.md

@@ -0,0 +1,34 @@
+# NoneBot 发布与版本更新
+
+主仓库 `version.txt` 是版本来源。NoneBot preview 工作流通过测试并生成插件后，
+在主仓库 `main` 推送或手动勾选 `publish` 时，执行以下操作：
+
+1. 校验生成包及来源工作区状态。
+2. 同步 `Shu-Ying/nonebot_plugin_farm` 的 `main` 分支。
+3. 在本次同步提交上创建 `v<version.txt>` 标签。
+4. 标签触发独立仓库的“🚀 发布到 PyPI”工作流，构建、校验并上传发行包。
+
+PR及未勾选publish的手动运行只构建测试，不同步、不打标签。脚本未传
+`--publish` 时仍是离线预演；`--release-tag` 明确开启自动标签步骤。
+标签创建成功只表示触发条件已满足，不表示下游PyPI发布或商店检测已成功。
+
+## 凭据与发布前提
+
+- 主仓库受保护环境中继续使用 `FARM_RELEASE_TOKEN`，必须是可写目标仓库
+  内容及工作流的PAT或GitHub App token；不能替换为普通 `GITHUB_TOKEN`。
+- NoneBot独立仓库需允许Actions运行，并已配置有效的 `PYPI_TOKEN`。
+- 目标仓库标签规则也必须允许该发布身份创建 `v*` 标签。
+- 发布新内容前递增主仓库 `version.txt`；不要在发布仓库手工改生成的版本文件。
+
+## 重跑和失败处理
+
+已有同版本标签时，比较标签中生成清单的版本、包身份和全部文件摘要；内容
+一致则跳过同步和重复触发。只有来源提交信息变化而插件文件相同也会跳过。
+若内容不同则拒绝，并提示升级 `version.txt`；脚本不删除或移动旧标签。
+
+同步main成功但创建标签失败时，工作流会报错，保留已同步代码；修复权限等
+原因后重跑。若标签已创建而下游PyPI上传失败，应在独立仓库重新运行失败的
+发布任务；上游重跑不会再次创建同名标签。PyPI已占用的版本不能靠移动标签
+覆盖，应使用新版本。
+
+本地测试使用模拟GitHub请求，不会创建远端标签或上传PyPI。