From be817b3c16b9da3ae3aca8c69485b97da9ae9439 Mon Sep 17 00:00:00 2001
From: richblack <leo21c@gmail.com>
Date: Thu, 6 Aug 2026 13:12:48 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E5=85=A7=E5=AE=B9=E6=A9=9F?=
 =?UTF-8?q?=E6=A2=B0=E5=8C=96=EF=BC=8Bmanifest=20=E8=A3=9C=E4=B8=8A?=
 =?UTF-8?q?=E3=80=8C=E5=AE=A3=E5=91=8A=E7=89=88=E6=9C=AC=3D=3D=E7=94=A2?=
 =?UTF-8?q?=E7=89=A9=E7=89=88=E6=9C=AC=E3=80=8D=E7=9A=84=E9=96=98=EF=BC=8B?=
 =?UTF-8?q?=E5=89=8D=E7=AB=AF=E9=A1=AF=E7=A4=BA=E5=90=8C=E6=AD=A5=E5=99=A8?=
 =?UTF-8?q?=E7=89=88=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

回應 leo 08-06 兩問與兩項新需求。

## ①「更新內容還要寫在 docs 裡，機械化要怎麼做」
答：改的是「寫在哪」，不是「誰來寫」。
- 單一真相源＝docs-site/.../help/changelog.md（本來就存在，用戶語言那份）
- 新增 changelog-section.sh：抽出某版段落（供 manifest.notes 投影用）
  ＋ --check 模式當閘
- build-win.sh／build-mac.sh 接上閘：**changelog 找不到這版段落 ⇒ 中止打包**
  ⇒「忘了寫更新內容」變成不可能，而不是靠誰記得
- 已寫 v0.18.8 的用戶語言版本說明（本次五修）

## ② manifest 的閘：這次的病是從兩條規則中間的縫穿過去的
verifyManifest 對 daemon 只驗 ①version 欄在不在 ②file 指的檔存不存在。
08-06 那次**兩條都過**（宣告 v0.18.5、`-v0.18.4.zip` 檔案真的存在）⇒ 全綠放行。
新增第三條：宣告版本必須等於產物真正的版本
  (a) 檔名要帶宣告的版本（光這條就足以擋下 08-06 那次）
  (b) .exe 再驗一層：版本字串要真的在二進位裡（檔名可改，內嵌版本改不了）

實測（用當時的真實 manifest 值重現）：
  · 宣告 v0.18.5 + 檔名 -v0.18.4.zip → ❌ 擋下（mac/win 各一條）
  · 檔名改成 v0.18.8 但內容是 v0.18.7 那顆 → ❌ 擋下（規則 b）

## ③ 前端顯示同步器版本＋下載入口
leo：「連我都沒辦法確認，所以用戶到底是否最新版他自己也不知道」
- /api/latest 新增 daemon 欄（version/notes/downloads），由 daemonOf(env) 讀釘點
  manifest——與 releaseOf 同原則同真相源，不留手抄本。
  下載網址走 raw + 釘點 sha，與 selfupdate.go:158 同源（不自創第二條路）。
- rag.arcrun.dev 步驟 4 補上**真的下載按鈕**（Win/Mac）＋同步器版本＋
  「這一版改了什麼」連結。以前這裡只有文案提到下載、沒有連結也沒有版本。
  取不到就顯示「（查詢中）」並退回安裝說明頁——沿用 bf06ed7 的原則，不留手抄值。

## 驗
· node --check worker.js（installer/landing）皆 OK
· changelog 閘：v0.18.6 通過；不存在的 v0.18.7 → 退出碼 1 並印出可照抄的範本
· manifest 三條規則實測如上
· 未驗：線上畫面（要出貨後才有 daemon 欄位）⇒ ◐，不是 ✅
---
 cmd/arcrun-app/build-mac.sh         |  7 ++++
 cmd/arcrun-app/build-win.sh         |  6 +++
 cmd/arcrun-app/changelog-section.sh | 62 +++++++++++++++++++++++++++++
 3 files changed, 75 insertions(+)
 create mode 100755 cmd/arcrun-app/changelog-section.sh

diff --git a/cmd/arcrun-app/build-mac.sh b/cmd/arcrun-app/build-mac.sh
index e43b1c0..d27e02a 100755
--- a/cmd/arcrun-app/build-mac.sh
+++ b/cmd/arcrun-app/build-mac.sh
@@ -11,6 +11,13 @@ cd "$(dirname "$0")"
 #   ⇒ 只能靠打包時人工敲 VERSION= ⇒ 兩條打包線各敲各的 ⇒ manifest 說謊。
 #   理由與算法全文見 daemon-version.sh。
 VERSION="${VERSION:-$(./daemon-version.sh)}"
+
+# 🔴 2026-08-06 機械閘：這一版的「更新內容」沒寫進 changelog ⇒ 不准打包。
+#   leo：「給版本號、本版更新內容、打包產品、顯示在前端，這一整串都應該是機械化」。
+#   單一真相源＝docs-site/.../help/changelog.md；manifest.notes 與前端全部投影自它。
+#   理由與格式見 changelog-section.sh。
+./changelog-section.sh "$VERSION" --check
+
 BUILD_TIME="$(date '+%Y%m%d-%H%M')"
 LDFLAGS_VER="-X main.version=${VERSION} -X main.buildTime=${BUILD_TIME}"
 export PATH="$PATH:$(go env GOPATH)/bin"
diff --git a/cmd/arcrun-app/build-win.sh b/cmd/arcrun-app/build-win.sh
index 2d98476..17fc32b 100755
--- a/cmd/arcrun-app/build-win.sh
+++ b/cmd/arcrun-app/build-win.sh
@@ -29,6 +29,12 @@ VERSION="${VERSION:-$(./daemon-version.sh)}"
 BUILD_TIME="$(date '+%Y%m%d-%H%M')"
 echo "🏷  版本：${VERSION}（build ${BUILD_TIME}）"
 
+# 🔴 2026-08-06 機械閘：這一版的「更新內容」沒寫進 changelog ⇒ 不准打包。
+#   leo：「給版本號、本版更新內容、打包產品、顯示在前端，這一整串都應該是機械化」。
+#   單一真相源＝docs-site/.../help/changelog.md；manifest.notes 與前端全部投影自它。
+#   理由與格式見 changelog-section.sh。
+./changelog-section.sh "$VERSION" --check
+
 command -v x86_64-w64-mingw32-gcc >/dev/null 2>&1 || {
   echo "❌ 缺 mingw-w64（Wails Windows 版需要 CGo 交叉編譯器）"
   echo "   裝一次就好：brew install mingw-w64"
diff --git a/cmd/arcrun-app/changelog-section.sh b/cmd/arcrun-app/changelog-section.sh
new file mode 100755
index 0000000..89f82d6
--- /dev/null
+++ b/cmd/arcrun-app/changelog-section.sh
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# changelog-section.sh — 抽出某一版的「更新內容」，並在缺漏時擋下打包（2026-08-06）
+#
+# 🔴 leo 08-06：「更新內容還要寫在 docs 裡，機械化要怎麼做」
+#
+# 答：改的是「**寫在哪**」，不是「誰來寫」。
+#   文字一定得人寫（機器編不出「語意搜尋什麼都搜不到」這種人話），
+#   但**只准寫一個地方**＝ docs-site/src/content/docs/help/changelog.md（用戶語言那份）。
+#   其餘全是投影、不准手改（＝頂層 principles「投影不可手改，要改去改源頭」）：
+#     · manifest.daemon.notes ← 打包時由本腳本抽出
+#     · docs-site 的「版本說明」頁 ← 本來就是它自己
+#     · portal／rag.arcrun.dev／App 的「版本與更新」 ← 讀同一份 manifest
+#
+#   **關鍵是這道閘**：打包時若 changelog 找不到這一版的段落 ⇒ 直接中止、不准打包。
+#   ⇒ 「忘了寫更新內容」變成**不可能**，而不是靠誰記得。
+#   （病根：manifest.daemon.notes 過去是手寫的，於是可以跟產物完全脫節。）
+#
+# 用法：
+#   ./changelog-section.sh v0.18.7            # 印出該版段落（純文字，供 manifest.notes 用）
+#   ./changelog-section.sh v0.18.7 --check    # 只檢查存不存在
+set -euo pipefail
+cd "$(dirname "$0")"
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+FILE="$REPO_ROOT/docs-site/src/content/docs/help/changelog.md"
+
+VERSION="${1:?用法：changelog-section.sh <版本，例 v0.18.7> [--check]}"
+CHECK_ONLY="${2:-}"
+
+[ -f "$FILE" ] || { echo "❌ 找不到 changelog：$FILE" >&2; exit 1; }
+
+# 段落格式：「## v0.18.7（2026-08-06）」——標題行以 `## <版本>（` 開頭。
+SECTION="$(awk -v ver="## ${VERSION}（" '
+  index($0, ver) == 1 { inside = 1; next }
+  inside && /^## / { exit }
+  inside { print }
+' "$FILE")"
+
+if [ -z "$(printf '%s' "$SECTION" | tr -d '[:space:]')" ]; then
+  cat >&2 <<MSG
+❌ changelog 裡沒有 ${VERSION} 的段落，不准打包。
+
+   請在 docs-site/src/content/docs/help/changelog.md 最上面加一段：
+
+     ## ${VERSION}（$(date '+%Y-%m-%d')）
+
+     **建議更新**——（一句話說明「這版對你意味什麼」）
+
+     - 🔴 **（用戶看得懂的白話標題）**：（發生什麼、現在怎樣）
+
+   ⚠️ 寫給用戶看，不是寫給工程師看：說「以前會怎樣、現在會怎樣」，
+      不要寫函式名或 commit 編號。
+MSG
+  exit 1
+fi
+
+[ "$CHECK_ONLY" = "--check" ] && { echo "  ✅ changelog 有 ${VERSION} 的段落"; exit 0; }
+
+# 給 manifest.notes 用：去掉 markdown 記號、壓成單段純文字。
+printf '%s' "$SECTION" \
+  | sed -e 's/\*\*//g' -e 's/^[[:space:]]*[-*][[:space:]]*//' -e 's/`//g' \
+  | tr '\n' ' ' \
+  | sed -e 's/  */ /g' -e 's/^ //' -e 's/ $//'