@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/release-argent.sh

@@ -0,0 +1,574 @@
+#!/usr/bin/env bash
+# ══════════════════════════════════════════════════════════════════════════════
+# release-argent.sh <版本> — Argent 发布版本流程（KB-082，2026-09-01）
+#
+# 用途：把开发 HEAD 的稳定改动作为正式版本发布——校验 → 打 tag → 同步分发文件
+#       到服务器 dl/ → 验证 → 输出发布报告。替代手动同步（曾发生 dl/ 落后漏同步）。
+#
+# 用法：
+#   bash release-argent.sh 0.7.1             # 正式发布（校验 → tag+push → 同步 → 验证）
+#   bash release-argent.sh 0.7.1 --dry-run   # 演练：只校验+打印计划，不 tag 不同步
+#   bash release-argent.sh 0.7.1 --full      # 额外同步仓库 skills/、plugins/ 目录
+#   bash release-argent.sh --check-dl        # 只体检：仓库 vs 服务器 dl/ 是否一致（不改任何东西）
+#   bash release-argent.sh --publish-dl      # 只同步分发文件（不打 tag、不 push）——应急修 dl 漂移
+#
+# 为什么有 --check-dl：2026-09-20 实测发现服务器 dl/install-argent.mjs 停在 9-07，
+#   而仓库已是 9-15（缺 dsh 0.1.5-rc.1 已验版本 + profile-doctor 收尾门禁）——**整整漂了 8 天**。
+#   官网那条 `curl https://whyshu.com/dl/install-argent.mjs | node` 下发的就是它。
+#   dl/ 与仓库没有任何自动连接，只能靠"发布时同步 + 平时可体检"两道：本模式就是体检那道。
+#                                             （默认同步 CORE_FILES 四件安装器
+#                                               install-argent.mjs / install.sh / install-dsh.sh / install.ps1；
+#                                               服务器 dl/skills、dl/plugins 有独立静态资源
+#                                               （whyshu-ppt-template/argent-account），
+#                                               与仓库目录不同源，--full 才覆盖，谨慎使用）
+#
+# 前置条件：
+#   - 本机可 ssh ubuntu@81.69.222.211（~/.ssh/whyshu.pem）
+#   - 发布门槛（docs/release.md）：对应改动已在看板 review→done 验收通过（PM 批准）
+#   - VERSION 文件已更新为目标版本、CHANGELOG.md 已含对应条目（可先跑 --dry-run 检查）
+#
+# 流程：
+#   1. 校验：VERSION 与参数一致 / git working tree clean / CHANGELOG 含 ## v<版本>
+#      （缺 CHANGELOG 条目仅警告）/ tag v<版本> 未存在
+#   2. 打 git tag v<版本> + push origin v<版本>（含 tag）
+#   3. 同步分发文件到 ubuntu@81.69.222.211:/home/whyshu/web/dl/：
+#      install-argent.mjs、install.sh、install-dsh.sh、install.ps1（默认）；skills/、plugins/（--full）
+#   4. 验证：本地/服务器 md5 一致 + curl -sI https://whyshu.com/dl/install-argent.mjs = 200
+#   5. 输出发布报告（版本/tag/文件清单/md5/验证结果）
+#
+# ⛔ 投递纪律（本仓红线，2026-10-06 定、2026-10-06 收口）：**客户机/服务器的任何投递禁用 `scp`**，一律用 `rsync`
+#   （或 `cat | ssh`）。原因：scp 的协议/选项面在新旧 OpenSSH 之间不兼容、不支持增量 ⇒ 大包重传、失败静默半截。
+#   **本脚本三条投递路径已全部走 rsync**：模式 P 的能力包上传 / CORE_FILES / `--full` 的 DIR_FILES。
+#   ⚠️ 且投递后都**显式归一远端模式**（`remote_chmod`）：dl/ 是 nginx 静态面，源文件 600（开发树 umask）
+#   被 `rsync -a` 原样带过去 ⇒ **403**，官网那条 `curl …/dl/install-argent.mjs | node` 当场废
+#   （2026-10-09 实测命中，当场 chmod 644 修复；体检现在把"HTTP 取不到"也判红）。
+#   ⛔ 为什么不用 rsync 的 `--chmod=F644`：macOS 自带的 openrsync（"rsync version 2.6.9 compatible"）
+#   不认 `F`/`D` 前缀（实测报 `--chmod=F600: invalid argument`）⇒ 走远端 `chmod`，与 rsync 版本无关。
+#   `grep -n scp` 只应命中本段注释。⚠️ 清单口径（2026-10-06 修脚枪）：模式 P 第 ④ 步的
+#   `--emit-server-manifest` **默认 merge**（只刷新注册表里认识的能力，现网独有的条目原样保留、键序不动；
+#   删条目须显式 `--prune`）⇒ **工具已保证不误删**；仍建议发布前 `--dry-run` 复核 diff
+#   （脚本已自动先 dry-run 打印、再落盘）。
+# ══════════════════════════════════════════════════════════════════════════════
+set -euo pipefail
+
+# ── 常量 ──────────────────────────────────────────────────────────────────────
+SSH_HOST="ubuntu@81.69.222.211"
+SSH_KEY="$HOME/.ssh/whyshu.pem"
+DL_DIR="/home/whyshu/web/dl"
+DL_URL="https://whyshu.com/dl"
+# whyshu-svr 在服务器上的**扁平**部署目录（pm2 cwd；能力包清单就部署在这里）
+SRV_DEPLOY="${SRV_DEPLOY:-/home/whyshu/server}"
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+# push 目标 remote：默认仓库第一个 remote（本机为 whyshu）；可用 ARGENT_RELEASE_REMOTE 覆盖
+REMOTE="${ARGENT_RELEASE_REMOTE:-$(git -C "$REPO_DIR" remote | head -1)}"
+
+# 核心分发文件（与服务器 dl/ 直接对应）
+# 2026-09-20：补 install.ps1 —— 官网 Windows PowerShell 一行命令 `irm .../dl/install.ps1 | iex`
+# 直接吃这个文件；漏了它就等于 Windows 用户在下载"没人管"的副本。
+# 2026-10-09：补 install.sh —— 官网 macOS/Linux 一行命令 `curl .../dl/install.sh | bash` 的入口
+# （旧的 `curl .../dl/install-argent.mjs | node` 因模块级相对 import 必然 ERR_MODULE_NOT_FOUND，
+#  已被 install.sh 取代）。`install-dsh.sh` 留在这里只为**存量老命令**仍能取到，是**遗留**件。
+CORE_FILES=("install-argent.mjs" "install.sh" "install-dsh.sh" "install.ps1")
+# 目录级分发（--full 时启用；服务器对应目录有独立静态资源，非同名覆盖不删旧）
+DIR_FILES=("skills" "plugins")
+
+# ── 参数 ──────────────────────────────────────────────────────────────────────
+VERSION_ARG=""
+DRY_RUN=0
+FULL=0
+MODE="release"          # release | check-dl | publish-dl
+for a in "$@"; do
+  case "$a" in
+    --dry-run) DRY_RUN=1 ;;
+    --full) FULL=1 ;;
+    --check-dl) MODE="check-dl" ;;
+    --publish-packs) MODE="publish-packs" ;;
+    --publish-dl) MODE="publish-dl" ;;
+    -h|--help) sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) VERSION_ARG="$a" ;;
+  esac
+done
+if [[ "$MODE" == "release" && -z "$VERSION_ARG" ]]; then
+  echo "✗ 缺少版本参数（用法：bash release-argent.sh <版本> [--dry-run] [--full]）"
+  echo "  或：bash release-argent.sh --check-dl | --publish-dl | --publish-packs"
+  exit 1
+fi
+if [[ "$MODE" != "release" ]]; then
+  VERSION_ARG="${VERSION_ARG:-current}"
+fi
+
+# ── md5 / 拉取校验的小工具（本地 / 服务器 / 真正下发的 HTTP 内容）──────────────
+md5_of()       { md5 -q "$1" 2>/dev/null || md5sum "$1" | awk '{print $1}'; }
+md5_stdin()    { md5 -q 2>/dev/null || md5sum | awk '{print $1}'; }
+remote_md5_of() { ssh -i "$SSH_KEY" -o ConnectTimeout=10 "$SSH_HOST" \
+                    "md5sum ${DL_DIR}/$1 2>/dev/null | awk '{print \$1}'" 2>/dev/null || echo ''; }
+# 真正"用户会拿到什么"：绕过缓存拉一遍内容算 md5（只有 200 + 内容一致才算数）
+# ⚠️ 2026-10-09 实测事故：旧实现是 `curl -fsSL … | md5_stdin` —— curl 失败时下游**照样**算出一个
+#    "空内容的 md5"（d41d8cd9…）⇒ 调用方看到的是"内容不同"而不是"取不到"；且 `set -e` 下 curl 的
+#    退出码（56）会**直接结束脚本**（现象 = 只打印一行"── dl/ 体检 ──"就没了）。
+#    现在：先探 HTTP 状态码，**非 200 ⇒ 返回空串**（调用方按"HTTP 取不到"报红 + 给 chmod 修法）；
+#    状态码 200 才流式取内容（⛔ 不做命令替换：那会剥掉尾换行 ⇒ md5 与实际下发字节不符 ⇒ 恒假红）。
+http_md5_of()  {
+  local code
+  code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 60 -H 'Cache-Control: no-cache' "${DL_URL}/$1" 2>/dev/null || echo 000)"
+  [ "$code" = "200" ] || return 0
+  curl -fsSL --max-time 60 -H 'Cache-Control: no-cache' -H 'Pragma: no-cache' "${DL_URL}/$1" 2>/dev/null | md5_stdin || true
+}
+
+# 投递后**归一远端文件模式**（2026-10-09 实测事故，见脚本头"投递纪律"）：
+# `rsync -a` 会保留开发树的模式 ⇒ 源文件 600 时 dl/ 上也 600 ⇒ nginx 403 ⇒ 官网一行命令当场废。
+# 用法：remote_chmod <模式> <远端路径…>（模式与路径都交给远端 chmod，路径里的 glob 由远端展开）
+remote_chmod() {
+  local mode="$1"; shift
+  ssh -i "$SSH_KEY" -o ConnectTimeout=10 "$SSH_HOST" "chmod ${mode} $*" 2>/dev/null || true
+}
+
+# ── 解释器解析（两个档）─────────────────────────────────────────────────────────
+# 2026-09-22 重启事故：默认值写死 ~/.dsh/argent/venv ⇒ /tmp 被清后静默空转。
+# 候选（2026-09-22）：ARGENT_PY → DSH_HOME/argent/venv → ~/.dsh/argent/venv → 仓库 .venv → PATH
+py_candidates() {
+  printf '%s\n' "${ARGENT_PY:-}" "${DSH_HOME:-$HOME/.dsh}/argent/venv/bin/python3" \
+    "$HOME/.dsh/argent/venv/bin/python3" "${REPO:-}/.venv/bin/python3" \
+    "$(command -v python3 2>/dev/null || true)"
+}
+# 严格档：配置/发票生成硬要求 openpyxl + yaml（--publish-packs 走这一档）
+pick_py() {
+  local c
+  for c in $(py_candidates); do
+    [ -n "$c" ] || continue
+    [ -x "$c" ] || continue
+    "$c" -c 'import openpyxl, yaml' 2>/dev/null || continue
+    "$c" -c 'import PIL, playwright' 2>/dev/null || \
+      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：node install-argent.mjs --venv-only）" >&2
+    printf '%s' "$c"; return 0
+  done
+  return 1
+}
+# 轻档（2026-10-09）：能力包档**只跑 stdlib**（`capability_pack.py --digest-tgz` / `--emit-server-manifest`）
+# ⇒ 不该被 openpyxl 挡在门外（体检机器上没装办公依赖是常态）。
+pick_py_light() {
+  local c
+  for c in $(py_candidates); do
+    [ -n "$c" ] || continue
+    [ -x "$c" ] || continue
+    "$c" -c 'import json,tarfile,hashlib' 2>/dev/null || continue
+    printf '%s' "$c"; return 0
+  done
+  return 1
+}
+
+# ── 能力包档（2026-10-09 新增）─────────────────────────────────────────────────
+# 为什么要有它：`CORE_FILES` 只有三个安装器 ⇒ **能力包从来没人核**。而 hr 今天就发生过
+#   「**同 URL 覆盖发布**」（版本没提、字节变了）—— 文件名与 HTTP 200 都没变，谁都没发现。
+# 判据（任一不满足即判红，复用本脚本既有的「HTTP 取不到即红」风格）：
+#   ① HTTP 取得到（状态码 200）；② 取回来的 tgz **重算内容摘要 == 清单 sha256**。
+# ⛔ 摘要**只用 CLI 算**（`capability_pack.py --digest-tgz`）：importlib 加载那个模块时
+#   `scripts/` 不在 sys.path ⇒ `import flow_registry` 静默降级成未合并的 base 注册表 ⇒
+#   带流程的能力（full/invoice/daily-report）摘要会**算错**（2026-10-08 实测）。
+# 另外做一次**仓库 ↔ 线上清单**对账（同一份 CLI 的 `--emit-server-manifest` 输出）：
+#   · 版本不同 ⇒ ⚠（发布在途/落后，**不判红**，否则开发中恒红）；
+#   · **版本相同但摘要不同** ⇒ ✗ 判红 —— 那正是「同 URL 覆盖发布」的形态：客户拿到的字节
+#     与仓库里那一版对不上，而版本号骗过了所有人。
+# 用法：check_packs <light-py>  ⇒ 设 PACK_DRIFT=0/1（返回值恒 0，判据走变量，免得被 set -e 咬）
+check_packs() {
+  local py="$1"
+  local tmpd; tmpd="$(mktemp -d -t argent-packs-check)"
+  local rc=0
+  PACK_DRIFT=0
+  echo
+  echo "── 能力包档（服务端清单 → 逐个 HTTP 取回 + **重算内容摘要**）──"
+  if [[ -z "$py" ]]; then
+    echo "  ✗ 找不到可用解释器（stdlib 即可）⇒ 无法重算包摘要（⛔ 不用 importlib 兜底：会静默算错）"
+    rm -rf "$tmpd"; PACK_DRIFT=1; return 0
+  fi
+  local remote_manifest
+  # 部署形态是**扁平**的（`/home/whyshu/server/config/…`，服务按 `services/../config` 解析）；
+  # 仓库形态则是 `src/config/…` ⇒ 两个都试，取第一个存在的（别把"我猜错了目录"报成"清单没了"）。
+  remote_manifest="$(ssh -i "$SSH_KEY" -o ConnectTimeout=10 "$SSH_HOST" \
+    "for p in ${SRV_DEPLOY}/config/capability-packs.json ${SRV_DEPLOY}/src/config/capability-packs.json; do \
+       if [ -f \"\$p\" ]; then cat \"\$p\"; break; fi; done" 2>/dev/null || echo '')"
+  if [[ -z "$remote_manifest" ]]; then
+    echo "  ✗ 取不到服务器上部署的能力清单（试过 ${SRV_DEPLOY}/config/ 与 ${SRV_DEPLOY}/src/config/）"
+    rm -rf "$tmpd"; PACK_DRIFT=1; return 0
+  fi
+  printf '%s' "$remote_manifest" > "$tmpd/manifest.json"
+  # 发布侧真源（本机 whyshu-svr 仓库那一份）：与**已部署**的那份不一致 = 改了没部署。
+  # ⚠️ 比对前两边都去掉**尾随换行**：`$( )` 会剥掉命令替换结果的所有尾换行，而文件末尾有一个
+  #   ⇒ 直接 `diff <(printf '%s' "$remote") <file>` 会**恒报不等**（2026-10-09 实测的假告警）。
+  local local_manifest="${WHYSHU_SVR_DIR:-$HOME/Code/whyshu-svr}/src/config/capability-packs.json"
+  if [[ -f "$local_manifest" ]]; then
+    if [[ "$remote_manifest" == "$(cat "$local_manifest")" ]]; then
+      echo "  ✓ 已部署清单 == 本机 whyshu-svr 工作树那一份（未部署改动 = 0）"
+    else
+      echo "  ⚠ 已部署清单 ≠ 本机 whyshu-svr 工作树那一份 —— 有改动没部署（⚠ 不判红；本脚本只核 dl/）"
+    fi
+  else
+    echo "  · 本机没有 ${local_manifest}（跳过「发布侧真源」对账）"
+  fi
+  local rows
+  rows="$("$py" -c 'import json,sys
+d=json.load(open(sys.argv[1],encoding="utf-8"))
+for cid,e in (d.get("capabilities") or {}).items():
+    print("\t".join([cid,str(e.get("version","")),str(e.get("sha256","")),str(e.get("url",""))]))' \
+    "$tmpd/manifest.json" 2>/dev/null || true)"
+  if [[ -z "$rows" ]]; then
+    echo "  ✗ 服务端清单里**一个能力都没有**（清单空/结构非法）—— 客户机拿到的会是空清单"
+    rm -rf "$tmpd"; PACK_DRIFT=1; return 0
+  fi
+  local cid ver sha url code got f
+  while IFS=$'\t' read -r cid ver sha url; do
+    [[ -n "$cid" ]] || continue
+    if [[ -z "$url" ]]; then
+      echo "  ✗ ${cid} v${ver}：清单没有 url（客户端无从取包）"; PACK_DRIFT=1; continue
+    fi
+    code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 60 -H 'Cache-Control: no-cache' "$url" 2>/dev/null || echo 000)"
+    if [[ "$code" != "200" ]]; then
+      echo "  ✗ ${cid} v${ver}：**HTTP ${code}**（${url}）—— 包取不到；修：bash scripts/release-argent.sh --publish-packs"
+      PACK_DRIFT=1; continue
+    fi
+    f="$tmpd/${cid}.tgz"
+    if ! curl -fsSL --max-time 300 -H 'Cache-Control: no-cache' -H 'Pragma: no-cache' "$url" -o "$f" 2>/dev/null; then
+      echo "  ✗ ${cid} v${ver}：状态码 200 但**内容取不回来**（多半是权限 ⇒ nginx 403 / 传输中断）"
+      PACK_DRIFT=1; continue
+    fi
+    got="$("$py" scripts/capability_pack.py --digest-tgz "$f" 2>/dev/null | head -1 | tr -d '[:space:]' || true)"
+    if [[ -z "$got" ]]; then
+      echo "  ✗ ${cid} v${ver}：摘要重算失败（--digest-tgz 非零退出）"; PACK_DRIFT=1; continue
+    fi
+    if [[ "$got" == "$sha" ]]; then
+      echo "  ✓ ${cid} v${ver} 内容摘要一致（${got:0:8}，$(wc -c < "$f" | tr -d ' ') 字节）"
+    else
+      echo "  ✗ ${cid} v${ver} **内容摘要不符**：清单 ${sha:0:8} vs HTTP 取回重算 ${got:0:8}"
+      echo "     ↳ 这正是「同 URL 覆盖发布」的形态（包换了、版本没提，HTTP 与文件名都还是好的）"
+      PACK_DRIFT=1
+    fi
+  done <<< "$rows"
+
+  # ── 仓库 ↔ 线上清单对账（同一份 CLI 派生，不手抄任何值）──
+  echo "  ── 仓库 ↔ 线上清单对账（capability_pack.py --emit-server-manifest）──"
+  local derived; derived="$("$py" scripts/capability_pack.py --emit-server-manifest 2>/dev/null || true)"
+  if [[ -z "$derived" ]]; then
+    echo "  ⚠ 派生不出仓库侧清单（注册表读不出来？）—— 跳过对账"
+  else
+    printf '%s' "$derived" > "$tmpd/derived.json"
+    local cmp_out; cmp_out="$("$py" -c 'import json,sys
+der=(json.load(open(sys.argv[1],encoding="utf-8")).get("capabilities") or {})
+live=(json.load(open(sys.argv[2],encoding="utf-8")).get("capabilities") or {})
+warn=red=0
+for cid in sorted(set(der)|set(live)):
+    d,l=der.get(cid),live.get(cid)
+    if d is None:
+        print("  ⚠ %s: 线上有、仓库注册表不认识（%s）—— 孤儿条目，无法重建/提版" % (cid,l.get("version"))); warn+=1; continue
+    if l is None:
+        print("  ⚠ %s: 仓库有、线上**没有**（%s）—— 还没发布？" % (cid,d.get("version"))); warn+=1; continue
+    if str(d.get("version"))!=str(l.get("version")):
+        print("  ⚠ %s: 版本不同 仓库 %s vs 线上 %s（发布在途/落后；**不判红**）" % (cid,d.get("version"),l.get("version"))); warn+=1; continue
+    if str(d.get("sha256"))!=str(l.get("sha256")):
+        print("  ✗ %s: **版本相同（%s）但内容摘要不同** —— 仓库 %s vs 线上 %s ⇒ 同版本覆盖发布的形态，客户拿到的字节与仓库这一版对不上" % (cid,d.get("version"),str(d.get("sha256"))[:8],str(l.get("sha256"))[:8])); red+=1
+print("  ⇒ 对账：✗ %d ｜ ⚠ %d%s" % (red,warn,"（✗ 即判红）" if red else "（⚠ 不判红）"))
+print("__RED__" if red else "__OK__")' "$tmpd/derived.json" "$tmpd/manifest.json" 2>/dev/null || true)"
+    printf '%s\n' "$cmp_out" | grep -v '^__' || true
+    if printf '%s' "$cmp_out" | grep -q '__RED__'; then PACK_DRIFT=1; fi
+  fi
+  rm -rf "$tmpd"
+  if [[ "$PACK_DRIFT" -eq 0 ]]; then
+    echo "  ✅ 能力包档：清单里每个包都 HTTP 可达且内容摘要与清单一致"
+  else
+    echo "  ✗ 能力包档**不通过** —— 面向客户的下载面与清单对不上"
+  fi
+  return 0
+}
+
+# ── 模式 P：发布能力包（--publish-packs）── 缺口③：把包托管到 dl/packs/ 并生成服务端清单 ──
+# 为什么需要：客户端的 `--from-packs <url>` 早就支持按 url 装包，但包一直没地方放（清单 url 是占位）。
+# 本模式：① 构建每个能力的**确定性 tgz** → ② rsync 到 `${DL_DIR}/packs/` → ③ 复核 HTTP 可达
+# → ④ 生成 whyshu-svr 的清单（含整包内容摘要 + url）：**默认 merge**（只刷新注册表认识的能力，
+#    现网独有的条目原样保留；删条目须显式 --prune）⇒ 先 `--dry-run` 打印 diff，再落盘。
+#    ⛔ 不再"整表替换"：2026-10-06 前的整表输出会抹掉现网独有条目（实测会把 daily-report-lite 抹掉）。
+if [[ "$MODE" == "publish-packs" ]]; then
+  cd "$REPO_DIR"
+  # 解释器解析（2026-09-22 重启事故：默认值写死 ~/.dsh/argent/venv ⇒ /tmp 被清后静默空转）
+pick_py() {
+  local c
+  # 候选（2026-09-22）：ARGENT_PY → DSH_HOME/argent/venv → ~/.dsh/argent/venv → 仓库 .venv → PATH
+  for c in "${ARGENT_PY:-}" "${DSH_HOME:-$HOME/.dsh}/argent/venv/bin/python3" \
+           "$HOME/.dsh/argent/venv/bin/python3" "${REPO:-}/.venv/bin/python3" \
+           "$(command -v python3 2>/dev/null || true)"; do
+    [ -n "$c" ] || continue
+    [ -x "$c" ] || continue
+    "$c" -c 'import openpyxl, yaml' 2>/dev/null || continue   # 硬要求：配置/发票生成必需
+    "$c" -c 'import PIL, playwright' 2>/dev/null || \
+      echo "[$(date '+%F %T')] ⚠️ 解释器 $c 缺 pillow/playwright ⇒ 浏览器流程会失败（修：node install-argent.mjs --venv-only）" >&2
+    printf '%s' "$c"; return 0
+  done
+  return 1
+}
+if ! PY="$(pick_py)"; then
+  echo "❌ 找不到可用解释器（需含 openpyxl + yaml）：ARGENT_PY / ~/.dsh/argent/venv/bin/python3 / PATH 的 python3" >&2
+  echo "   修复: python3 -m venv ~/.dsh/argent/venv && ~/.dsh/argent/venv/bin/pip install openpyxl pyyaml" >&2
+  exit 2
+fi
+  OUT="${PACKS_OUT:-$(mktemp -d -t argent-packs)}"
+  DL_BASE="${DL_BASE:-https://whyshu.com/dl}"
+  echo "── 构建能力包（确定性 tgz）→ ${OUT} ──"
+  CAPS="$("$PY" scripts/capability_pack.py --list 2>/dev/null | awk '/^  [a-z]/{print $1}')"
+  [[ -n "$CAPS" ]] || CAPS="invoice full daily-report hr"
+  for c in $CAPS; do
+    "$PY" scripts/capability_pack.py --build "$c" --out-dir "${OUT}/${c}" --tar --force >/dev/null 2>&1 \
+      && echo "  ✓ ${c}" || { echo "  ✗ ${c} 构建失败"; exit 1; }
+  done
+  echo
+  echo "── 上传 → ${SSH_HOST}:${DL_DIR}/packs/ ──"
+  ssh -i "$SSH_KEY" -o ConnectTimeout=10 "$SSH_HOST" "mkdir -p ${DL_DIR}/packs"
+  # ⛔ 红线（2026-10-06）：客户机/服务器投递禁用 `scp` ⇒ 改 `rsync`（同一份字节、同一目标目录，
+  #    行为等价；rsync 走 ssh 且支持增量，避免 scp 在新旧 OpenSSH 间的兼容差异与半截失败）。
+  rsync -az --no-owner --no-group -e "ssh -i $SSH_KEY -o ConnectTimeout=10" "${OUT}"/*.tgz "${SSH_HOST}:${DL_DIR}/packs/"
+  # 模式归一（600 ⇒ nginx 403；见 remote_chmod 注释）：包是 HTTP 直接下发物，必须 world-readable。
+  remote_chmod 644 "${DL_DIR}/packs/*.tgz"
+  echo "  ✓ 已上传 $(ls "${OUT}"/*.tgz | wc -l | tr -d ' ') 个包"
+  echo
+  echo "── 复核（HTTP 可达 + 与本地字节一致）──"
+  OK=1
+  for f in "${OUT}"/*.tgz; do
+    n="$(basename "$f")"; l="$(md5_of "$f")"
+    code="$(curl -s -o /dev/null -w '%{http_code}' -I "${DL_BASE}/packs/${n}" || echo 000)"
+    h="$(curl -s "${DL_BASE}/packs/${n}" | md5 -q 2>/dev/null || curl -s "${DL_BASE}/packs/${n}" | md5sum | awk '{print $1}')"
+    if [[ "$code" == "200" && "$h" == "$l" ]]; then echo "  ✓ ${n}（HTTP 200，md5 ${l:0:8}）"; else
+      echo "  ✗ ${n}（HTTP ${code}，md5 本地 ${l:0:8} vs 远端 ${h:0:8}）"; OK=0; fi
+  done
+  [[ "$OK" -eq 1 ]] || { echo "✗ 部分包复核不通过——先别改服务端清单"; exit 1; }
+  echo
+  echo "── 生成服务端能力清单（whyshu-svr；默认 merge，只刷新注册表认识的能力）──"
+  SRV="${WHYSHU_SVR_DIR:-$HOME/Code/whyshu-svr}/src/config/capability-packs.json"
+  # ④a 先 dry-run **看 diff**（不写盘）：工具已保证不误删现网独有条目，这一步是发布前的第二双眼睛。
+  "$PY" scripts/capability_pack.py --emit-server-manifest --dl-base "$DL_BASE" --out "$SRV" --dry-run
+  # ④b 复核无误 ⇒ 落盘（仍是 merge 语义：不认识的条目原样保留、键序不动）
+  "$PY" scripts/capability_pack.py --emit-server-manifest --dl-base "$DL_BASE" --out "$SRV"
+  echo "  ⇒ 下一步：把 ${SRV} 随 whyshu-svr 一起部署（rsync + pm2 startOrReload whyshu-svr）"
+  exit 0
+fi
+
+# ── 模式 A：只体检（--check-dl）/ 只同步（--publish-dl）——不打 tag、不 push ──
+if [[ "$MODE" != "release" ]]; then
+  cd "$REPO_DIR"
+  echo "── dl/ 体检（仓库 ↔ ${SSH_HOST}:${DL_DIR}）──"
+  DRIFT=0
+  for f in "${CORE_FILES[@]}"; do
+    [[ -f "$f" ]] || { echo "  ⚠ 仓库无 ${f}（跳过）"; continue; }
+    l="$(md5_of "$f")"; r="$(remote_md5_of "$f")"; h="$(http_md5_of "$f")"
+    tag="✓"
+    if [[ -z "$r" ]]; then tag="✗"; DRIFT=1; echo "  ✗ ${f}：服务器上没有这个文件"; continue; fi
+    [[ "$l" == "$r" ]] || { tag="✗"; DRIFT=1; }
+    note=""
+    [[ "$l" == "$r" ]] || note="（服务器 ${r:0:8} vs 仓库 ${l:0:8}）"
+    if [[ -n "$h" && "$h" != "$l" ]]; then note="${note}（HTTP 下发 ${h:0:8}）"; DRIFT=1; tag="✗"; fi
+    # 2026-10-09：HTTP 拉不到内容同样判红（实测事故：rsync -a 把开发树的 600 带进生产 ⇒ nginx 403
+    # ⇒ 官网那条 `curl .../dl/install-argent.mjs | node` 一行命令当场废掉，而旧逻辑把空串当"没有证据"放过）。
+    if [[ -z "$h" ]]; then tag="✗"; DRIFT=1; note="${note}（**HTTP 取不到下发内容**：多为文件权限 ⇒ nginx 403；修：chmod 644）"; fi
+    echo "  ${tag} ${f} ${l:0:8}${note}"
+  done
+  # ── 能力包档（2026-10-09 新增）：安装器之外，**能力包也要逐个核**。见 check_packs 注释 ──
+  # 只在"体检"语义下把结果并进 DRIFT；--publish-dl 不改包（要重发用 --publish-packs），
+  # 所以那一档只报告、不据此早退（否则会挡住它本来要干的"修安装器 403"）。
+  check_packs "$(pick_py_light || true)"
+  if [[ "$MODE" == "check-dl" && "$PACK_DRIFT" -ne 0 ]]; then DRIFT=1; fi
+  if [[ "$DRIFT" -eq 0 ]]; then
+    echo "✅ dl/ 与仓库一致（含 HTTP 下发内容一致 + 能力包内容摘要一致）"
+    exit 0
+  fi
+  if [[ "$MODE" == "check-dl" ]]; then
+    echo "✗ dl/ 与仓库**不一致**——修法：bash scripts/release-argent.sh --publish-dl（应急同步安装器，不打 tag）"
+    echo "   能力包不符则用：bash scripts/release-argent.sh --publish-packs（重建+上传+刷新服务端清单）"
+    echo "   或走正式发布：bash scripts/release-argent.sh <版本>"
+    exit 1
+  fi
+  echo
+  echo "── 同步分发文件（--publish-dl：不打 tag、不 push）──"
+  for f in "${CORE_FILES[@]}"; do
+    [[ -f "$f" ]] || continue
+    if [[ "$(md5_of "$f")" == "$(remote_md5_of "$f")" ]]; then
+      echo "  · ${f} 已一致，跳过"
+    else
+      # ⛔ 红线：投递禁用 `scp`（见脚本头"投递纪律"）⇒ 一律 rsync。
+      rsync -az --no-owner --no-group -e "ssh -i $SSH_KEY -o ConnectTimeout=10" "$f" "${SSH_HOST}:${DL_DIR}/${f}"
+      echo "  ✓ ${f} → ${DL_DIR}/${f}"
+    fi
+    # ⭐ 模式归一**无条件**执行（2026-10-09 实测）：内容一致 ⇒ rsync 跳过 ⇒ **权限照旧**，
+    #    600 的文件会一直 403（本次反证就是"已一致，跳过"之后 HTTP 仍取不到 ⇒ 复核判红）。
+    #    "内容对"与"用户拿得到"是两件事，投递必须两件都保证。
+    remote_chmod 644 "${DL_DIR}/${f}"
+  done
+  echo
+  echo "── 复核（服务器 md5 + HTTP 下发内容）──"
+  OK=1
+  for f in "${CORE_FILES[@]}"; do
+    [[ -f "$f" ]] || continue
+    l="$(md5_of "$f")"; r="$(remote_md5_of "$f")"; h="$(http_md5_of "$f")"
+    if [[ "$l" == "$r" && -n "$h" && "$h" == "$l" ]]; then
+      echo "  ✓ ${f} 一致（${l:0:8}；HTTP 下发同字节）"
+    else
+      echo "  ✗ ${f} 仍不一致：仓库 ${l:0:8} / 服务器 ${r:0:8} / HTTP ${h:0:8}"
+      [[ -n "$h" ]] || echo "     ↳ HTTP 取不到内容（403？）—— 面向用户的那条命令会直接失败：服务器上 chmod 644 ${DL_DIR}/${f}"
+      OK=0
+    fi
+  done
+  [[ "$OK" -eq 1 ]] || exit 1
+  if [[ "$PACK_DRIFT" -ne 0 ]]; then
+    echo "✅ 安装器三点已与仓库对齐；但**能力包档有 ✗**（本模式不改包）⇒ 跑：bash scripts/release-argent.sh --publish-packs"
+    exit 0
+  fi
+  echo "✅ dl/ 已与仓库对齐（下次正式发布仍会再同步一遍，不冲突）"
+  exit 0
+fi
+VERSION="${VERSION_ARG#v}" # 容错：0.7.1 或 v0.7.1 均可
+TAG="v${VERSION}"
+
+# ── 1. 校验 ──────────────────────────────────────────────────────────────────
+cd "$REPO_DIR"
+echo "── 发布校验（版本 ${VERSION}）──"
+FAIL=0
+
+# 1a. VERSION 文件与参数一致
+if [[ -f VERSION ]]; then
+  CUR="$(cat VERSION | tr -d '[:space:]')"
+  if [[ "$CUR" != "$VERSION" ]]; then
+    echo "✗ VERSION 文件内容（${CUR}）与参数（${VERSION}）不一致——请先更新 VERSION 并提交"
+    FAIL=1
+  else
+    echo "✓ VERSION = ${VERSION}（一致）"
+  fi
+else
+  echo "✗ 仓库无 VERSION 文件"
+  FAIL=1
+fi
+
+# 1b. git working tree clean
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "✗ git working tree 有未提交改动："
+  git status --porcelain | head -10
+  FAIL=1
+else
+  echo "✓ git working tree clean"
+fi
+
+# 1c. CHANGELOG.md 含对应版本条目（缺则警告，不阻断——发布候选可后补）
+# 判据兼容两种抬头：`## v0.9.9 xxx`（旧写法）与 `## 0.9.9（日期）`（≥0.7.3 现行写法）。
+# 原判据写死 `^## v${VERSION} `（v + 半角空格）⇒ 自 0.7.3 起恒不匹配 ⇒ 门槛 3 实际"永远只警告"。
+V_RE="${VERSION//./\\.}"
+if [[ -f CHANGELOG.md ]] && grep -qE "^## (v)?${V_RE}([ （(]|$)" CHANGELOG.md; then
+  echo "✓ CHANGELOG.md 含 ## ${VERSION} 条目"
+else
+  echo "⚠ CHANGELOG.md 缺 ## ${VERSION} 条目——建议先补充（发布门槛，docs/release.md）"
+fi
+
+# 1d. tag 未存在
+if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+  echo "✗ tag ${TAG} 已存在（$(git log -1 --format='%h %s' "${TAG}")）——如需重新发布请删除旧 tag"
+  FAIL=1
+else
+  echo "✓ tag ${TAG} 可创建"
+fi
+
+# 1e. push 目标 remote 存在
+if [[ -z "$REMOTE" ]]; then
+  echo "✗ 仓库无 git remote（无法 push tag）——可用 ARGENT_RELEASE_REMOTE 指定"
+  FAIL=1
+else
+  echo "✓ push 目标 remote = ${REMOTE}"
+fi
+
+if [[ $FAIL -eq 1 ]]; then
+  echo "✗ 校验未通过，发布中止（可先 --dry-run 排查）"
+  exit 1
+fi
+
+# ── 2. 计划 / dry-run ────────────────────────────────────────────────────────
+echo
+echo "── 发布计划（版本 ${VERSION}，tag ${TAG}）──"
+echo "  1. git tag ${TAG} + git push ${REMOTE} ${TAG}"
+echo "  2. rsync → ${SSH_HOST}:${DL_DIR}/：${CORE_FILES[*]}"
+if [[ $FULL -eq 1 ]]; then
+  echo "  3. rsync 目录 → ${SSH_HOST}:${DL_DIR}/：${DIR_FILES[*]}（--full，覆盖服务器同名内容）"
+else
+  echo "  3. （未指定 --full：skills/ plugins/ 目录不同步——服务器有独立静态资源）"
+fi
+echo "  4. 验证：本地/服务器 md5 + curl -sI ${DL_URL}/install-argent.mjs"
+
+if [[ $DRY_RUN -eq 1 ]]; then
+  echo
+  echo "✅ [dry-run] 校验通过，计划如上（未打 tag、未同步）。确认后执行：bash release-argent.sh ${VERSION}"
+  exit 0
+fi
+
+# ── 3. 执行 ──────────────────────────────────────────────────────────────────
+echo
+echo "── 打 tag + push ──"
+git tag "${TAG}"
+git push "${REMOTE}" "${TAG}"
+echo "✓ tag ${TAG} 已 push"
+
+echo
+echo "── 同步分发文件到服务器 ──"
+SSH_ARGS=(-i "$SSH_KEY" -o ConnectTimeout=10 "$SSH_HOST")
+# ⛔ 红线：投递禁用 `scp`（见脚本头"投递纪律"）⇒ 一律 rsync；目录投递（--full）用的是同一形态。
+RSYNC_SSH="ssh -i $SSH_KEY -o ConnectTimeout=10"
+for f in "${CORE_FILES[@]}"; do
+  if [[ ! -f "$f" ]]; then
+    echo "⚠ 仓库无 ${f}（跳过）"
+    continue
+  fi
+  rsync -az --no-owner --no-group -e "$RSYNC_SSH" "$f" "${SSH_HOST}:${DL_DIR}/${f}"
+  remote_chmod 644 "${DL_DIR}/${f}"   # 模式归一（600 ⇒ nginx 403）
+  echo "  ✓ ${f} → ${DL_DIR}/${f}"
+done
+if [[ $FULL -eq 1 ]]; then
+  for d in "${DIR_FILES[@]}"; do
+    if [[ ! -d "$d" ]]; then
+      echo "⚠ 仓库无 ${d}/（跳过）"
+      continue
+    fi
+    rsync -az --no-owner --no-group -e "$RSYNC_SSH" "$d/" "${SSH_HOST}:${DL_DIR}/${d}/"
+    # 目录面：`a+rX` = 目录可进入/可列举、文件可读（可执行位只给本来就有的）——同样"开发树模式不进生产"
+    remote_chmod -R a+rX "${DL_DIR}/${d}"
+    echo "  ✓ ${d}/ → ${DL_DIR}/${d}/（--full 覆盖）"
+  done
+fi
+
+# ── 4. 验证 ──────────────────────────────────────────────────────────────────
+echo
+echo "── 验证 ──"
+VERIFY_OK=1
+for f in "${CORE_FILES[@]}"; do
+  [[ -f "$f" ]] || continue
+  local_md5="$(md5 -q "$f" 2>/dev/null || md5sum "$f" | awk '{print $1}')"
+  remote_md5="$(ssh "${SSH_ARGS[@]}" "md5sum ${DL_DIR}/${f} 2>/dev/null | awk '{print \$1}'" 2>/dev/null || echo '')"
+  if [[ "$local_md5" == "$remote_md5" && -n "$remote_md5" ]]; then
+    echo "  ✓ ${f} md5 一致（${local_md5}）"
+  else
+    echo "  ✗ ${f} md5 不一致：本地 ${local_md5} vs 服务器 ${remote_md5}"
+    VERIFY_OK=0
+  fi
+done
+http_code="$(curl -sI -o /dev/null -w '%{http_code}' "${DL_URL}/install-argent.mjs")"
+if [[ "$http_code" == "200" ]]; then
+  echo "  ✓ ${DL_URL}/install-argent.mjs HTTP ${http_code}"
+else
+  echo "  ✗ ${DL_URL}/install-argent.mjs HTTP ${http_code}（期望 200）"
+  VERIFY_OK=0
+fi
+
+# ── 5. 发布报告 ─────────────────────────────────────────────────────────────
+echo
+echo "════════ 发布报告 ════════"
+echo "版本: ${VERSION}"
+echo "tag:  ${TAG}（$(git log -1 --format='%h %s' "${TAG}")）"
+echo "提交: $(git log -1 --format='%h %s' HEAD)"
+if [[ $FULL -eq 1 ]]; then
+  echo "同步: ${CORE_FILES[*]} + 目录 ${DIR_FILES[*]}"
+else
+  echo "同步: ${CORE_FILES[*]}（skills/ plugins/ 未同步，--full 可选）"
+fi
+echo "验证: $([[ $VERIFY_OK -eq 1 ]] && echo '全部通过' || echo '存在失败（见上）')"
+echo "════════════════════════"
+[[ $VERIFY_OK -eq 1 ]] || exit 1
+echo "✅ 发布完成：${TAG} 已发布（dl/ 分发文件已同步并验证）"