huanyan/desktop 增量质检报告（v0.1.2）

• 项目：huanyan/desktop　分支：v0.1.2
• 对比区间：a96e98a2（base） → 53ec3d8a（head）
• 变更文件数：7（新增 1 / 修改 6）
• 质检问题变化（工具口径）：修复 0 条 / 新增 1 条
• 人工复核补充问题：3 条（工具未捕获，见「四、人工复核发现」）

---

一、变更概览

本次提交主题是发布链路补齐 + 出厂种子自愈：一条命令本机出 macOS dmg 并上传 Gitea Release，同时让「早期占位页残留」被新种子自动接管。

---

二、修复的问题（base 有 / head 无）

修复 0 条。 本次区间无历史质检问题被消除。

---

三、新增的问题（head 有 / base 无）

新增 1 条（工具质检口径）：

成因：bootstrap 原本只有 2 处日志（Warn 播种回退 + Info 播种完成），本次新增了「自愈升级」的 Info 后达到 3 处，触发阈值。

影响：仅日志冗余，无功能影响；但该函数在启动路径，Info 级别会出现在默认输出中（合并见「四-2」的语义问题）。

---

四、人工复核发现（工具未捕获）

1. 【Medium｜脚本 Bug】scripts/release-mac.sh 的 AUTH 数组被空格拆散 —— RELEASE_TOKEN 路径必然失败

位置：scripts/release-mac.sh 第 33–41 行（auth() + AUTH=($(auth))），及第 86/88/91 行对 "${AUTH[@]}" 的使用。

auth() {
  if [ -n "${RELEASE_TOKEN:-}" ]; then echo "-H"; echo "Authorization: token $RELEASE_TOKEN"; else
    ...
  fi
}
AUTH=($(auth))          # ← 未加引号的命令替换，按 IFS 空白做分词

问题：echo "Authorization: token $RELEASE_TOKEN" 的输出含空格，AUTH=($(auth)) 会按空白拆成 4 个元素：

AUTH = ( -H  "Authorization:"  "token"  "<token>" )

于是 curl "${AUTH[@]}" ... 展开为 curl -H "Authorization:" token <token> <真实URL>： -H 只吃到空值头 Authorization:，而 token、<token> 被当作额外 URL去请求 → 请求失败；配合 set -e / --fail-with-body，脚本在设置了 RELEASE_TOKEN 时直接中断。

关键点：这是 README 明确宣传的首选凭据路径（“环境变量 RELEASE_TOKEN（40 位 token）”）。对照 scripts/release.sh 的同段落（AU=(-H "Authorization: token $RELEASE_TOKEN")，数组元素成对书写）是正确的——两个脚本写法不一致，release-mac.sh 这一处是笔误。

修复建议（与 release.sh 对齐）：

if [ -n "${RELEASE_TOKEN:-}" ]; then
  AUTH=(-H "Authorization: token $RELEASE_TOKEN")
else
  CRED="$(printf 'protocol=https\nhost=git.1v5.com\n\n' | git credential fill 2>/dev/null)"
  U="$(awk -F= '/^username=/{print $2}' <<<"$CRED")"
  P="$(awk -F= '/^password=/{print $2}' <<<"$CRED")"
  AUTH=(-u "$U:$P")
fi

2. 【Low｜语义 Bug】自愈分支会打印误导性日志（err 为 nil 却报“解析本地载荷失败”）

位置：main.go bootstrap（约 154–168 行）。

active, err := store.Active()
if err == nil {
    if !payload.ShouldAdoptSeed(active, seedWebVersion) {
        return active, nil
    }
    logger.Info("出厂种子高于本地载荷，自愈升级", "local", active, "seed", seedWebVersion)
}
if !errors.Is(err, payload.ErrNoPayload) {          // ← 自愈分支下 err==nil
    logger.Warn("解析本地载荷失败，尝试出厂种子", "err", err)
}

问题：走「自愈升级」分支时 err == nil，但仍会落入下一段判断：errors.Is(nil, ErrNoPayload) 为 false → !false = true → 打印 Warn "解析本地载荷失败，尝试出厂种子" err=<nil>。该日志既语义错误（本地载荷并未解析失败，而是主动让位给更高的种子），又级别过高（Warn 会在正常自愈场景输出噪声），也正是上面「过度日志」新增告警的直观来源。

修复建议：用显式标记区分「回退播种」与「自愈播种」，仅在前者打印 Warn；或把自愈分支改为 return 后单独走一段播种并只打 Info。

3. 【Low｜工程一致性】入库的 frontend/dist/index.html 引用了被 .gitignore 忽略的哈希资源

位置：frontend/dist/index.html（本次改为 Vite 产物，引用 /assets/index-D72ZKR9J.js、/assets/index-DkMjznmH.css、/app-config.js、/favicon.svg） vs .gitignore：

frontend/dist/*
!frontend/dist/index.html

问题：仅 index.html 入库，其引用的 assets/*、app-config.js 均不入库（go:embed all:frontend/dist 只会嵌入 index.html）。因此不经过发布脚本的本地构建（wails3 task build/dev、go build）会 embed 一个引用不存在资源的入口页 → 白屏。发布链路之所以不受影响，是因为 scripts/release-mac.sh（station_seed）与 CI（.gitea/workflows/ci.yaml 的「取出厂种子载荷」步骤）都会在打包前用 OTA 站的真实载荷整体覆盖 frontend/dist。

结论：对发布产物无影响，但仓库把「构建产物」当源文件入库、且与 .gitignore 例外规则相互矛盾，属易踩坑的工程一致性问题。建议二选一：

• 彻底的「产物不入库」：删掉 index.html 例外行，本地/CI 构建前统一由脚本灌入真实载荷；
• 或保留占位页做可独立启动的降级页，不要入库带哈希引用的真实产物 index.html。

补充：README.md 中「本地启动（M0：静态占位页）」小节与 build/Taskfile.yml 的 build:frontend（仅校验 frontend/dist/index.html 存在）仍描述“静态占位页”语义，与本次 index.html 的“真实产物”改动存在文档口径滞后，建议同步。

---

五、变更逻辑正确性核查（正面结论）

1. ShouldAdoptSeed 语义正确：current=='' || seed=='' 返回 false（交由 ErrNoPayload 播种路径处理）；seed > current 才接管，天然满足「只升不降」；Compare 会剥离 v 前缀并按数字段比较，用例覆盖了占位残留（0.0.0）、旧版残留、相等、OTA 先行（0.2.0 不回退）、空目录五种情形，测试充分。
2. 自愈不会形成抖动/回退：自愈后 SetCurrent(seed)，下次 Active() 返回 seed，ShouldAdoptSeed(seed, seed)=false → 稳定返回；本地版本经 OTA 更新到高于种子时不会回退。
3. 发布链路与 CI 口径一致：release-mac.sh 传 SHELL_VERSION/SEED_WEB_VERSION 给 wails3 task package，与 build/darwin/Taskfile.yml 的 -ldflags -X main.shellVersion/seedWebVersion 注入点吻合；tag 触发 Windows CI 出 exe/NSIS 的约定与 README 一致。

---

六、验证建议

1. 脚本冒烟（重点）：分别用 RELEASE_TOKEN=... 与「git credential 账号密码」两种凭据各跑一次 scripts/release-mac.sh（可先加 --skip-tag --no-dmg 干跑），确认真实上传成功——可直接验证「四-1」的问题。
2. 自愈回归：手工把 {appData}/huanyan/current 指到旧版本（如 0.0.0）、并放入占位载荷，用高于它的 SEED_WEB_VERSION 编译，确认首启自动切到种子版本且不打印“解析本地载荷失败”。
3. 种子优先不降级：构造本地 0.2.0 > 种子 0.1.100，确认仍加载本地、未回退。
4. 本地构建可启动性：不使用发布脚本直接 wails3 task build/dev，确认入口页是否白屏（验证「四-3」的影响面）。
5. 门禁保持：gofmt -l . / go vet ./internal/... / go test ./internal/... / GOOS=windows GOARCH=amd64 go vet .。

---

七、结论

• 本次是发布链路补齐 + 出厂种子自愈的功能性提交，核心 Go 逻辑（ShouldAdoptSeed + bootstrap）设计正确、测试充分。
• 工具口径：修复 0 / 新增 1（main.go:154 过度日志，Low）。该告警与「四-2」的误导性日志同源，一并修掉即可消除。
• 需优先处理：scripts/release-mac.sh 的 AUTH 数组空格拆分（「四-1」），它会让 README 宣称的首选凭据 RELEASE_TOKEN 路径完全不可用，属发布链路的阻塞性 Bug。
• 建议跟进：自愈日志语义/级别（四-2）、frontend/dist 入库策略与 .gitignore/文档口径一致性（四-3）。