bug: 灰度安装包因缺少对应 Git tag 无法准备 Cindy Make 源码

[sakiko-toyokawa]

问题描述 / What happened

灰度/预发安装包无法走完 Cindy Make 源码准备。环境检查可以通过，但「2 · 准备源码」失败，界面显示「当前版本所需的 tag 不存在。」点「重试准备」仍失败。

实际行为

已打包客户端会按 app.getVersion() 去 https://github.com/makecindy/cindy.git 查找对应 Git tag，再克隆个人版源码：

• 正式号（如 0.1.91）：先找 v0.1.91，再找 v0.1.91-beta
• 带 -beta 的版本：先找 vX.Y.Z-beta，再找 vX.Y.Z
• 未打包开发版：跟 main，不找版本 tag

灰度打包只把 --version 写进 package.json，不会创建 Git tag。因此版本号已经是下一版（本机实测 0.1.91），仓库最新正式 tag 仍是 v0.1.90 时，ls-remote 两个候选都没有，源码准备抛 tagNotFound。Cindy Make 后续制作、隔离测试、生成个人版都进不去。

这不是某次漏打 tag 的偶发操作问题，而是两套规则不一致：

• apps/desktop/scripts/package-desktop.mjs：只打安装包，不打 tag；cindy-source.json 只记录构建 commit
• apps/desktop/src/main/cindy-make/sourcePreparation.ts 的 sourceTarget() / resolveRemoteRef()：已打包客户端不看构建 commit，也不跟 main，只认版本 tag

期望行为

灰度安装包应能准备与当前构建对应的源码（例如使用 cindy-source.json 的 sourceCommit，或在 tag 不存在时回退到该 commit / main），或在打包/发版流程中同步创建 Cindy Make 所需的 tag。当前门禁会让所有「版本号已 bump、仓库尚未打 tag」的预发包无法使用 Cindy Make。

不影响：不经过 Cindy Make 源码准备的其他灰度项。

环境 / Environment

• Cindy 版本或 commit / version or commit: Desktop 0.1.91（Cindy.exe FileVersion=0.1.91）；resources/cindy-source.json 的 sourceCommit=f4aeeca8e94d94e6a0af82f74d16eaab7ec47776（GitHub 上该 SHA 也不存在）
• 平台与版本 / platform & OS version: Windows x64
• 安装方式 / install method: 本机已安装的灰度/预发安装包（C:\Users\XD\AppData\Local\Programs\Cindy\Cindy.exe），app.isPackaged=true，版本号不含 -beta，按 release 渠道解析
• 仓库对照：makecindy/cindy 无 v0.1.91 / v0.1.91-beta；最新正式 tag 为 v0.1.90（2026-09-21）

复现步骤 / Steps to reproduce

1. 安装一份版本号已写成下一版、但 GitHub 上还没有对应 tag 的 Desktop 安装包（本机为 0.1.91）。
2. 打开本机 Cindy，在任意本机会话输入框发送：/cindy-make 我想要一个定制化的壁纸（需求文案可换，不影响）。
3. 等待「Cindy Make」前置弹窗完成「1 · 准备环境」。
4. 观察「2 · 准备源码」。

日志与截图 / Logs & screenshots

[dash-s-cindy]

判断

Cindy Make 对已打包客户端按 app.getVersion() 解析 vX.Y.Z / vX.Y.Z-beta 两个 tag 来准备源码，这条「源码与运行版本精确对应」的链路在已发布版本上工作正常；缺口在于灰度/预发包在对应 tag 创建之前就已分发，恰好落在两个候选 tag 都不存在的窗口里，「2 · 准备源码」必然抛 tagNotFound，后续制作、隔离测试、生成个人版全部无法进入。这是发布流程与客户端解析规则之间的结构性不一致，不是单次漏打 tag；每个灰度周期都会复现。当前仓库确实没有 v0.1.91 / v0.1.91-beta（最新 0.1.x tag 为 v0.1.90 / v0.1.90-beta，指向同一 commit），与报告一致。

行动

1. 本周期恢复（零客户端改动）：把 0.1.91 灰度构建对应的 commit 推送到公开仓库，并创建 v0.1.91-beta（或同时创建 v0.1.91）。release 渠道按 v0.1.91 → v0.1.91-beta 顺序探测，tag 出现后，已安装的灰度包点「重试准备」即可恢复，无需重新分发安装包。注意：报告环境中 resources/cindy-source.json 的 sourceCommit（f4aeeca…）在 GitHub 上不存在（404），说明该构建基于一个未推送公开仓库的 commit——需要先推送该 commit，或退而在最接近的可用 commit 上打 tag。
2. 流程固化（发布侧）：灰度/canary 发布时同步「推送构建 commit + 创建 -beta tag」。客户端的双候选设计（正式号也会回退探测 -beta tag）天然支持「灰度先打 -beta、正式发布再补 stable tag」。打包脚本在本仓库明确「只打包，不发布」，tag 创建落在仓库外的发布工具链，需要在那一侧落地。
3. 产品决策（客户端兜底，待确认后再做）：是否允许 tag 缺失时回退，见下文「可选方案与风险」。

复核结论与证据

• 解析规则：apps/desktop/src/main/cindy-make/sourcePreparation.ts 的 sourceTarget()——dev 渠道跟 main；release 渠道候选仅 [vX.Y.Z, vX.Y.Z-beta]（beta 渠道顺序相反）；resolveRemoteRef() 对 https://github.com/makecindy/cindy.git 执行 git ls-remote --heads --tags，两个候选都不存在即抛 tagNotFound。sourcePreparation.test.ts 锁定了该行为。
• 覆盖所有入口：/cindy-make 前置流程（taskRuntime.ts / doctorCommand.ts，经 commands/builtins.ts）与设置页「准备源码」共用同一 prepareCindySource，且每次都先重新解析远端 ref——本地留有旧版本的 ready checkout 也绕不过这道门。
• 打包侧：apps/desktop/scripts/package-desktop.mjs 头注明确「只打包，不发布」，仓库内没有任何创建 Git tag 的脚本；cindy-source.json 由 forge.config.ts 在 prePackage 阶段写入 { sourceCommit, builtAt }，目前只用于个人版构建校验（versionStore.ts 的 retainPersonalVersion）与打包自检，源码准备不读取它。
• 外部状态（公开 GitHub API 核对）：无 v0.1.91 / v0.1.91-beta；v0.1.90 与 v0.1.90-beta 指向同一 commit，符合「发布时成对打 tag」的节奏；报告中的 sourceCommit f4aeeca… 返回 404。

可选方案与风险（需产品确认，不是既定改法）

• 「回退 cindy-source.json 的 sourceCommit」对本例无效：该 SHA 在公开仓库不存在，无法 fetch。它对「从公开 commit 构建的包」有效，但对基于未推送 commit 的灰度包救不了。
• 「回退 main」能覆盖所有情况（dev 渠道即此行为），但准备的源码可能与用户运行的二进制不一致——这会改变「个人版基于与运行版本精确对应的源码」的现有保证，且对灰度测试可能造成「测的不是包里的东西」的误导。若产品确认接受，建议在界面上明示实际使用的 ref/commit，而不是静默回退；实现上可复用已有的构建身份机制（cindy-runtime-source.ts 在构建时烘焙 commit，runtimeVersion.ts 已消费，且已把「仅版本号 bump」视为干净构建）。
• 附带影响面：fix(desktop): preserve versionless exemption for direct builds #580 保留的 versionless 社区打包（版本 0.0.0）走同一 tag 门禁（探测 v0.0.0）同样必然失败。若做客户端回退，这类构建可一并修复；若只走发布侧打 tag，社区包需要单独考虑。

验证方案

• 本周期：tag 推送后，在受影响的 0.1.91 灰度安装上点「重试准备」，确认步骤 2 通过、「查询上游」与后续制作流程可进入。
• 若实施客户端回退：补充「packaged + 版本号无对应 tag」的回归用例（现有测试只覆盖候选存在与非法版本号两种情况），并验证回退路径的 UI 提示。

相关记录

• fix(cindy-make): 完善个人版制作、测试与失败恢复流程 #4778：合入当前 tag 解析与源码准备/个人版完整流程的 PR。本 Issue 描述的行为即其现行设计（有测试锁定），确认这不是回归，而是设计尚未覆盖「tag 创建前分发灰度包」的场景。
• fix(desktop): preserve versionless exemption for direct builds #580：确立 versionless 0.0.0 哨兵的 PR。这类社区构建同样会命中本 Issue 的 tag 门禁，评估修复方案时建议一并纳入。

[sakiko-toyokawa]

已确认 makecindy/cindy 现有 �0.1.91-beta（commit 4aad753，GitHub Pre-release 2026-09-22）。当前仍无正式 tag �0.1.91。按 Cindy Make 源码准备逻辑，已打包正式号客户端会先找 �{version}，找不到再找 �{version}-beta，因此本机 Desktop