Release Gate

CombatSolver 发布、渠道上传与远端同步

适用边界

先按用户口令确定唯一动作范围：

用户声明活动发布批次时，批次规则优先：在用户结束批次前只提交到指定开发版本，不逐项定版。普通“发版”不等于完整发布门禁。

用户已确认：以后正式发版必须通过 tools/release/publish-release.ps1 同步发布创意工坊、GitHub Release 与夸克网盘。准备发版、普通开发提交和单独推送源码不运行统一发布脚本；只有进入 发版/发布 阶段时执行。监控后台的 latestVersion 由用户维护，agent 不读取或写入。

一句请求包含多个口令时，执行覆盖其全部要求的最窄阶段；“给我审核/我拍板后”始终暂停构建、标签和外部动作，直到用户批准。

1. 版本与发布来源

• CombatSolver 的中文版本术语：小版本只将末位加一，0.a.b → 0.a.(b+1)；大版本将中间位加一、末位归零，0.a.b → 0.(a+1).0。不要套用通用语义化版本的 minor/major 定义。用户给出精确版本号时按该版本号执行；已发布版本不追溯改号。
• 同步 CombatSolver.csproj、CombatSolver.json、docs/DEVELOPMENT_NOTES.md、docs/TEST_MATRIX.md 和该版本玩家更新日志。
• 玩家更新日志使用当前游戏官方简中译名，只写玩家可感知的变化。开发日志中的根因、内部职责、runId、构建和测试信息不复制进去。
• 玩家更新日志和创意工坊 changeNote 同时提供简中与英文，使用各语言的游戏译名。PR 或其他外部贡献必须在对应变动条目的开头标明贡献者和 PR，并分别链接贡献者主页与 PR，例如“感谢 [作者](%E4%B8%BB%E9%A1%B5) 提交的 [PR #123](%E9%93%BE%E6%8E%A5)：……”／“[PR #123](%E9%93%BE%E6%8E%A5) by [author](profile): …”，明确表示整项变动来自该贡献；禁止把致谢放在条目末尾，或在日志末尾另写脱离变动的笼统致谢段落。changeNote 直接采用同一版本玩家更新日志的完整中英正文，只允许将 Markdown 标题／列表语法转换为 Steam 富文本，不缩写、不合并或删减任何玩家变动、限制与致谢；转换到 Steam 富文本时也必须保留这两个链接。发布前逐项核对两种语言和两个渠道。若渠道长度限制无法容纳全文，停止该渠道并报告限制，不自行缩短。一次跨多个未上传版本时，先写好覆盖全部玩家变化的完整版本日志，再原样用于 changeNote。发布包含 UI 改动时参考 ../ui-localization/SKILL.md，复用已完成的中英验证，不为了发包重复测试。
• 提交源码、fixture 和文档后，从该提交构建；记录该提交为 release source commit。构建后行为源码、编译配置、依赖或 manifest 变化才使构建失效，纯渠道暂存变化不会。
• “当前最新版”来自仓库中已同步、已提交且完成最小发包的最高版本，不来自游戏 Mods 目录或创意工坊暂存目录。
• 版本创建标签或成功上传创意工坊后即冻结。后续行为改动进入新的“下一版本（开发中）”，不回写已发布版本；用户未指定新版本号时保留待定，不自行猜版本。
• 普通发布不计算哈希。只有来源冲突、发布渠道争议或用户明确要求时才计算。

玩家更新日志定稿规则

1. 以最近已发布版本为基线，描述升级后的最终体验；同一批次的未发布界面不是旧版。
2. 按玩家功能合并开发记录。新功能的试稿、反复调整、测试发现与修复过程保留在开发笔记，发布说明只介绍完成后的功能。
3. 修复条目只描述已发布版本中玩家可能遇到的现象及改善。新增功能在发布前修好的问题并入功能说明，不单列“修复”。
4. 使用游戏场景、操作与结果，避免索引、阈值、像素、容器布局等实现细节；例如写“重复出牌合并显示，标注次数，让长路线更易阅读”，不写“次数从标题行移到右侧，虚线下移两像素”。
5. 一项最终功能写一次；贡献者和 PR 链接保留在所属条目开头，中英文表达相同变化。用户已经删去的表述保持删除。
6. 定稿逐条核对已发布基线、最终默认行为和玩家收益，剔除未启用实验、开发过程、重复条目和没有证据的性能承诺，再将同一正文用于全部渠道。

Steam 更新日志排版合同

此规则适用于 workshop.json 的 changeNote，GitHub 与仓库更新日志继续使用 Markdown；创意工坊长介绍独立维护。

• 版本标题、简体中文与 English 小标题统一使用 [b]文字[/b]，段落使用真实换行，条目使用普通 - 前缀。
• 链接转换为 [url=https://…]文字[/url]，贡献者与 PR 链接全部保留。正文只使用普通文本、换行、[b] 和 [url] 标签。
• 标题不得使用 [h1]、[h2]、[h3]；列表不得使用 [list]、[*] 或 [olist]，也不使用 [quote]、[code]、表格或原始 HTML 等块级排版。
• 原因与证据：2026-09-22 的 0.44.0 更新日志页面将正文放在带背景的 <p> 中，而 [h1] / [h2] 被转换成 <div>，浏览器会提前结束段落，导致正文脱框、上下出现空背景条。旧版的加粗标题与普通换行保持在框内。
• 上传前检查转换后的完整 changeNote：只含上述允许标签、标签成对、换行为真实换行；逐项核对两种语言的正文、条目数量与链接均与 Markdown 来源一致。不能只检查版本字符串或上传器退出码来判断排版正确。
• 上传成功后沿用既有不重复发布、不打开远端页面复核的规则；用户提供排版异常时按实际页面诊断，不重传二进制来修正文字。

固定格式示例（其中换行是实际换行）：

[b]CombatSolver <版本号>[/b]

[b]简体中文[/b]

- 完整中文条目。

[b]English[/b]

- Complete English entry.

2. 一次 Release 构建

Windows（PowerShell 7）：

dotnet clean -c Release
pwsh -NoProfile -File tools\build\build-local-stack.ps1 -Configuration Release -ForPublication -PrivateConfigDirectory <私有配置目录>

Linux（Bash）：

dotnet clean -c Release
./tools/build/build-local-stack.sh --configuration Release --for-publication --private-config-directory <私有配置目录>

私有配置目录必须包含 presence.props 和 showcase.props，可从本机部署定位文件确认；它不进入仓库或发布包。发布构建与统一发布脚本都会检查 DLL 中的在线连接元数据，缺失时停止。不要输出配置值。

从 release source commit 构建，不从游戏 Mods 目录反向复制 DLL，不复用未知来源旧构建。构建成功后不再反射 DLL 版本、重复构建、再次复制部署或重跑已经通过的行为场景。

目标行为已在当前行为源码上通过，之后只改版本号、文档或发布元数据时，Release 构建足以进入打包，不重复行为审计。

3. 一次最小 ZIP

发布包统一输出到仓库根目录的 releases/CombatSolver-<版本号>.zip；当前工作区为 D:\Desktop\sts2mod\CombatSolver\releases。创建 ZIP 前确保目录存在，交付链接使用该路径，发布 ZIP 由现有 Git 忽略规则排除。

当前 has_pck=false。命令显式只写入：

• CombatSolver.json；
• 刚完成的 Release CombatSolver.dll；
• Windows 发布还包括同次构建的 CombatSolver.MemoryCleaner.exe；
• 根目录 LICENSE；
• 根目录 THIRD_PARTY_NOTICES.md；
• manifest 将来明确要求的其他资产。

LICENSE 和 THIRD_PARTY_NOTICES.md 是 MIT 许可及 Random Foreseer 来源署名文件，不得省略。不得加入源码、日志、问题包、存档、fixture、游戏依赖 DLL、bin/obj/.godot/.local 或旧 DLL。

ZIP 创建命令成功就是完成证据。不要重新打开、解压、枚举条目、读取 DLL 版本或计算哈希。

3.1 夸克专用打包版

GitHub Release 继续上传第 3 节的最小 ZIP，创意工坊继续暂存五个发布内容文件。夸克网盘单独使用 releases/CombatSolver-<版本号>-Quark.zip：只保留 CombatSolver 最小包内容，不加入 RitsuLib 或其他依赖。包体不足时增加无压缩的 QUARK_UPLOAD_PADDING.bin，该条目不参与 Mod 加载，解压后可以删除。

统一发布脚本根据最小包的实际大小生成刚好够用的填充内容，并要求最终文件严格大于 15 MiB；未达到时停止发布。夸克打包版由 Git 忽略，不进入源码提交。

4. 版本标签

• 准备发版 不创建标签；用户批准并说 发版/发布 时，在 release source commit 创建 annotated tag v<manifest version>，消息为 Combat Solver <manifest version>。
• 如果用户跳过单独的“发版”口令，直接把已准备版本上传创意工坊，上传成功即表示该版本已经发布；此时在 release source commit 补建本地 annotated tag。
• 标签存在时不移动、不删除、不重建。标签目标与 release source commit 冲突时停止并报告，不猜测哪个版本正确。
• 创建本地标签不等于已同步 GitHub。只有用户要求推送远端时才推送该标签。

5. 创意工坊上传

默认工具与暂存目录：

• D:\Desktop\sts2mod\ModUploader-win-x64\ModUploader.exe；
• D:\Desktop\sts2mod\ModUploader-win-x64\CombatSolverWorkshop。

Linux 不使用上述 Windows 路径。上传前必须设置 COMBATSOLVER_MOD_UPLOADER 和 COMBATSOLVER_WORKSHOP_DIR；任一路径未设置、不可执行或不存在时原样报告阻塞，不猜测其他目录或兼容层。

上传前只做一次本地暂存：

1. 用当前 release source 的 CombatSolver.json、刚完成的 Release DLL、Windows CombatSolver.MemoryCleaner.exe、根目录 LICENSE 和 THIRD_PARTY_NOTICES.md 覆盖 CombatSolverWorkshop/content/；
2. 保留标题、长描述、作者、封面、效果图、标签、依赖和可见性，除非用户明确要求修改或兼容性事实已经变化；
3. 按第 1 节“Steam 更新日志排版合同”将该版本完整简中和英文正文写入 workshop.json 的 changeNote，完成允许标签、正文与链接核对；
4. Windows 执行一次 ModUploader.exe upload -w .\CombatSolverWorkshop；Linux 执行一次 "$COMBATSOLVER_MOD_UPLOADER" upload -w "$COMBATSOLVER_WORKSHOP_DIR"。

创意工坊介绍已有 English / 简体中文两套，标题与正文来源维护于 docs/workshop/。官方 ModUploader 未指定语言时写 English，因此本地 workshop.json 的默认标题和 description 必须保持英文。单独维护任一种语言的标题或介绍时使用 tools/release/WorkshopMetadata（工具说明），以 docs/workshop/metadata.json 和完整介绍为输入：先设置语言，再成对设置非空标题与完整介绍，最后提交并检查结果。简中使用明确的 schinese；不能把中文塞回默认 description，或仅改 tags 代替语言字段。标题与介绍按完整语言记录维护，单字段更新返回 OK 不能证明遗漏字段保持原值。元数据维护使用空 changeNote，只更新该语言的标题与介绍。

英文界面发布时语言 tags 包含 English 与 Simplified Chinese，保留其他标签；tags 用于发现，不能代替上述介绍语言字段。仅发包且介绍未变化时保留既有两种语言，不重复提交介绍。英文介绍和中文介绍各自保留依赖、单人限制、代码来源与许可署名。

普通发版保留线上展示图：上传工作区不放 previews/ 目录，本地图片保存在 previews-preserved/。官方说明明确，目录不存在时线上展示图保持不变；存在时会同步完整列表，空目录会删除线上展示图，因此不能通过清空目录来跳过上传。只有用户明确要求更新展示图时才准备完整 previews/，当前顺序为中文、英文 1、英文 2、英文 3，对应 01-cn1.jpg、02-en1.jpg、03-en2.jpg、04-en3.jpg。主封面 image.png 独立处理，当前官方上传器要求其存在并每次上传，没有跳过参数；不得把跳过四张展示图说成所有图片都未上传。依据：官方目录说明 与 上传实现。

更新说明只写新增功能、实战结果修复、路线质量、UI/操作、兼容性和玩家能感知的性能变化。不要写类名、方法名、Beam/Mirror/GC 实现、runId、提交、构建、测试或打包过程。

上传命令报告成功就是远端完成证据。不要打开创意工坊页面、重新下载订阅内容、再次读取版本或重复上传。失败时只修正命令明确报告的原因，再重试一次；原因不明则原样报告。