llm-api-gateway-cli 1.0.0

package/scripts/install.sh

@@ -0,0 +1,510 @@
+#!/usr/bin/env bash
+# =============================================================================
+# llm-api-gateway-cli 一键安装脚本（macOS / Linux / WSL，bash）
+#
+# 用法：
+#   curl -fsSL https://raw.githubusercontent.com/boonya-hrgk/llm-api-gateway-cli/v1.0.0/scripts/install.sh | bash
+#   bash scripts/install.sh --version v1.0.0 --prefix "$HOME/.llm-api-gateway"
+#   bash scripts/install.sh --dry-run          # 只打印将要做什么，不下载、不落盘
+#
+# 环境变量（同名参数优先于环境变量）：
+#   LLM_GATEWAY_INSTALL_BASE       所有下载地址的前缀，用于换国内镜像（默认 GitHub 仓库地址）
+#   LLM_GATEWAY_INSTALL_VERSION    等价 --version
+#   LLM_GATEWAY_INSTALL_DIR        等价 --prefix（另外兼容文档里写的 PREFIX）
+#   LLM_GATEWAY_INSTALL_API        查询 latest 用的 API 前缀（默认 https://api.github.com）
+#   LLM_GATEWAY_INSTALL_DRY_RUN=1  等价 --dry-run
+#   GITHUB_ACTIONS=true            在 CI 里把 bin 目录写进 $GITHUB_PATH，而不是改 rc 文件
+#   NO_COLOR=1                     关掉彩色输出
+#
+# 为什么装 npm tarball 而不是逐平台编译产物：本项目除 openai / @anthropic-ai/sdk 两个
+# npm 依赖外零运行时依赖，逐平台编二进制是纯负担；一份 `npm pack` 产物同时喂给 curl 与
+# `npm i -g` 两条路线（见 .github/workflows/release.yml），两套东西才不会漂。
+# =============================================================================
+set -euo pipefail
+
+# ── 常量 ─────────────────────────────────────────────────────────────────────
+# TGZ 名必须与 package.json 的 name/version 对齐：`npm pack` 产出 <name>-<version>.tgz，
+# 而安装器是按 tag 拼文件名的，两边一旦不一致就是 404（CI 里也钉了这条一致性）。
+APP_NAME='llm-api-gateway-cli'
+MAIN_CMD='gateway-agent'
+DEFAULT_REPO_SLUG='boonya-hrgk/llm-api-gateway-cli'
+DEFAULT_BASE="https://github.com/${DEFAULT_REPO_SLUG}"
+DEFAULT_API='https://api.github.com'
+MIN_NODE_MAJOR=18
+
+# ── 输出 ─────────────────────────────────────────────────────────────────────
+# 只在真终端上色：管道里（curl | bash 之外，比如 CI 日志）留纯文本，免得日志里全是转义码
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+  C_RESET=$'\033[0m'; C_INFO=$'\033[36m'; C_OK=$'\033[32m'; C_WARN=$'\033[33m'; C_ERR=$'\033[31m'
+else
+  C_RESET=''; C_INFO=''; C_OK=''; C_WARN=''; C_ERR=''
+fi
+
+info() { printf '%s==>%s %s\n' "$C_INFO" "$C_RESET" "$*"; }
+ok()   { printf '%s  ✓%s %s\n' "$C_OK" "$C_RESET" "$*"; }
+warn() { printf '%s  !%s %s\n' "$C_WARN" "$C_RESET" "$*" >&2; }
+# 所有致命错误都从这里走：统一带「已清理临时文件」的口径，用户不会以为留下了半成品
+die()  { printf '%s  ✗ %s%s\n' "$C_ERR" "$*" "$C_RESET" >&2; exit 1; }
+
+usage() {
+  cat <<EOF
+llm-api-gateway-cli 一键安装脚本
+
+用法：
+  bash install.sh [选项]
+  curl -fsSL <base>/scripts/install.sh | bash -s -- [选项]
+
+选项：
+  -v, --version <版本>   安装指定版本，例如 v1.0.0 或 1.0.0（默认查最新 Release）
+      --prefix <目录>    安装目录（默认 \$HOME/.llm-api-gateway，避开需要 root 的系统目录）
+      --base <URL>       所有下载地址的前缀，用于换镜像
+      --no-modify-path   不改 shell 的 rc 文件，只打印需要手工加的一行 PATH
+  -n, --dry-run          演练：只打印将要执行的步骤，不下载、不安装、不改 PATH
+  -f, --force            已是目标版本时也重装一遍（默认直接跳过）
+  -h, --help             显示本帮助
+
+环境变量：
+  LLM_GATEWAY_INSTALL_BASE       下载前缀（默认 ${DEFAULT_BASE}）
+  LLM_GATEWAY_INSTALL_VERSION    等价 --version
+  LLM_GATEWAY_INSTALL_DIR        等价 --prefix（兼容 PREFIX）
+  LLM_GATEWAY_INSTALL_API        latest 查询前缀（默认 ${DEFAULT_API}）
+  LLM_GATEWAY_INSTALL_DRY_RUN=1  等价 --dry-run
+  GITHUB_ACTIONS=true            把 bin 目录写进 \$GITHUB_PATH
+
+装完怎么用：
+  gateway-task                 # 起服务（没有密钥也能起），在页面「设置」里填密钥
+  ${MAIN_CMD} config set key sk-xxx   # 或者命令行填：写 credentials.json，不进 config.json
+  export GATEWAY_KEY=sk-xxx    # 或者环境变量 / SK / 当前目录的 .env（优先级更高）
+  ${MAIN_CMD} --help
+  ${MAIN_CMD} -p "用一句话介绍你自己"
+EOF
+}
+
+# ── 全局状态（由 parse_args / main 填充）────────────────────────────────────
+VERSION_OPT=''          # 用户指定的版本（可能带 v 也可能不带）
+PREFIX_OPT=''           # 安装目录
+BASE=''                 # 下载前缀
+API_BASE=''             # latest 查询前缀
+MODIFY_PATH=1
+DRY_RUN=0
+FORCE=0
+HAVE_CURL=0
+TMP_DIR=''
+
+# ── 基础工具 ─────────────────────────────────────────────────────────────────
+# 参数解析手写而不用 getopt：macOS 自带的是 BSD getopt，不支持长选项，
+# 而 curl | bash 的用户恰恰多是 macOS，写了 getopt 反而要分支判断。
+parse_args() {
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -v|--version)
+        [ $# -ge 2 ] || die "$1 需要一个版本号，例如 --version v1.0.0"
+        VERSION_OPT="$2"; shift 2 ;;
+      --version=*)  VERSION_OPT="${1#*=}"; shift ;;
+      --prefix)
+        [ $# -ge 2 ] || die "$1 需要一个目录"
+        PREFIX_OPT="$2"; shift 2 ;;
+      --prefix=*)   PREFIX_OPT="${1#*=}"; shift ;;
+      --base)
+        [ $# -ge 2 ] || die "$1 需要一个 URL"
+        BASE="$2"; shift 2 ;;
+      --base=*)     BASE="${1#*=}"; shift ;;
+      --no-modify-path) MODIFY_PATH=0; shift ;;
+      -n|--dry-run) DRY_RUN=1; shift ;;
+      -f|--force)   FORCE=1; shift ;;
+      -h|--help)    usage; exit 0 ;;
+      # 空参数（curl | bash -s -- 后面没跟东西）直接放过，别报「未知参数 →」
+      '')           shift ;;
+      *)            die "未知参数：$1（用 --help 看用法）" ;;
+    esac
+  done
+
+  # 环境变量兜底：文档 5.2 只钉了 LLM_GATEWAY_INSTALL_BASE，
+  # 其余同名前缀变量与 PREFIX 是为了「不想改命令行、只想设个变量」的场景。
+  [ -n "$BASE" ]       || BASE="${LLM_GATEWAY_INSTALL_BASE:-$DEFAULT_BASE}"
+  [ -n "$API_BASE" ]   || API_BASE="${LLM_GATEWAY_INSTALL_API:-$DEFAULT_API}"
+  [ -n "$VERSION_OPT" ] || VERSION_OPT="${LLM_GATEWAY_INSTALL_VERSION:-}"
+  if [ -z "$PREFIX_OPT" ]; then
+    PREFIX_OPT="${LLM_GATEWAY_INSTALL_DIR:-${PREFIX:-}}"
+  fi
+  if [ "${LLM_GATEWAY_INSTALL_DRY_RUN:-}" = '1' ]; then DRY_RUN=1; fi
+
+  # 结尾斜杠会让拼出来的 URL 变 //，某些镜像/签名校验会因此 403
+  BASE="${BASE%/}"
+  API_BASE="${API_BASE%/}"
+
+  [ -n "$PREFIX_OPT" ] || PREFIX_OPT="$HOME/.llm-api-gateway"
+  # 展开 ~、解析相对路径：后面要用它做 PATH 幂等判断，带 ~ 的字符串比不出相等
+  # shellcheck disable=SC2088  # 这里匹配的是字面量 ~，正是要自己展开，不是让 shell 展开
+  case "$PREFIX_OPT" in
+    '~')   PREFIX_OPT="$HOME" ;;
+    '~/'*) PREFIX_OPT="$HOME/${PREFIX_OPT#\~/}" ;;
+  esac
+  case "$PREFIX_OPT" in
+    /*) : ;;
+    *)  PREFIX_OPT="$(pwd)/$PREFIX_OPT" ;;
+  esac
+  # 去掉结尾斜杠 + 折叠重复斜杠（手工传 --prefix foo//bar 也能比出正确路径）
+  while [ "${PREFIX_OPT%/}" != "$PREFIX_OPT" ]; do PREFIX_OPT="${PREFIX_OPT%/}"; done
+
+  # 从下载前缀里反推仓库 slug：fork / 自建镜像的人不用再手改脚本里的常量
+  REPO_SLUG="$DEFAULT_REPO_SLUG"
+  case "$BASE" in
+    https://github.com/*) REPO_SLUG="${BASE#https://github.com/}" ;;
+  esac
+  # 万一后面还挂了 /releases/... 之类，只取 owner/repo 两段
+  REPO_SLUG="$(printf '%s' "$REPO_SLUG" | awk -F/ 'NF>=2{print $1"/"$2; exit}')"
+  [ -n "$REPO_SLUG" ] || REPO_SLUG="$DEFAULT_REPO_SLUG"
+}
+
+need_cmd() { command -v "$1" >/dev/null 2>&1; }
+
+# curl 优先、wget 兜底：两者都没有就没法下载，但要给出「装一个」的可执行指引
+pick_downloader() {
+  if need_cmd curl; then
+    HAVE_CURL=1
+  elif need_cmd wget; then
+    HAVE_CURL=0
+  else
+    die "找不到 curl 或 wget，无法下载安装包。请先装一个（Debian/Ubuntu: apt-get install -y curl；Alpine: apk add curl；macOS 自带 curl）"
+  fi
+}
+
+fetch_text() {  # 读 URL 到 stdout
+  if [ "$HAVE_CURL" = 1 ]; then
+    curl -fsSL --connect-timeout 15 --retry 2 "$1"
+  else
+    wget -q -O - --timeout=15 "$1"
+  fi
+}
+
+fetch_file() {  # $1=URL $2=本地文件
+  if [ "$HAVE_CURL" = 1 ]; then
+    curl -fSL --connect-timeout 15 --retry 3 -o "$2" "$1"
+  else
+    wget -q -O "$2" --timeout=15 --tries=3 "$1"
+  fi
+}
+
+http_status() {  # 打印 HTTP 状态码；拿不到就打印 000
+  if [ "$HAVE_CURL" = 1 ]; then
+    curl -sS -o /dev/null -w '%{http_code}' -IL --connect-timeout 15 "$1" 2>/dev/null || printf '000'
+  else
+    if wget -q --spider --timeout=15 "$1" 2>/dev/null; then printf '200'; else printf '000'; fi
+  fi
+}
+
+effective_url() {  # 跟随重定向后的最终 URL，用于镜像没提供 API 时解析 latest tag
+  if [ "$HAVE_CURL" = 1 ]; then
+    curl -sS -o /dev/null -w '%{url_effective}' -L --connect-timeout 15 "$1" 2>/dev/null || true
+  else
+    wget --spider -S --timeout=15 "$1" 2>&1 | sed -n 's/^[[:space:]]*[Ll]ocation:[[:space:]]*//p' | head -n 1 | tr -d '\r'
+  fi
+}
+
+cleanup() {
+  local code=$?
+  if [ -n "$TMP_DIR" ] && [ -d "$TMP_DIR" ]; then
+    rm -rf "$TMP_DIR" 2>/dev/null || true
+  fi
+  exit "$code"
+}
+
+# ── 前置检查 ─────────────────────────────────────────────────────────────────
+check_node() {
+  if ! need_cmd node; then
+    die "找不到 node。本工具需要 Node.js ${MIN_NODE_MAJOR} 或更高版本；请先自行安装后重跑：
+      · 官方安装包  https://nodejs.org/zh-cn/download
+      · 版本管理    nvm (https://github.com/nvm-sh/nvm) / fnm / mise
+    安装器不代装 Node —— 替你改系统级运行时是越界行为，装错版本更难排查。"
+  fi
+
+  local raw major
+  raw="$(node -v 2>/dev/null || true)"
+  # 容错：node -v 是 v18.19.0 / v20.11.0 这种形状，取第一段数字
+  major="$(printf '%s' "$raw" | sed -n 's/^v\{0,1\}\([0-9][0-9]*\).*/\1/p')"
+  if [ -z "$major" ]; then
+    die "无法识别 node 版本（node -v 输出：'${raw}'），请确认 node 装好且能正常执行"
+  fi
+  if [ "$major" -lt "$MIN_NODE_MAJOR" ]; then
+    die "Node.js 版本过低：当前 ${raw}，需要 v${MIN_NODE_MAJOR} 及以上。
+    升级办法：nvm install ${MIN_NODE_MAJOR} && nvm use ${MIN_NODE_MAJOR}，或到 https://nodejs.org/zh-cn/download 换新版"
+  fi
+  ok "Node.js ${raw}"
+
+  if ! need_cmd npm; then
+    die "找不到 npm。它随 Node.js 一起分发，请检查安装是否完整（node -v 正常但 npm 缺失，常见于手工拼装的环境变量）"
+  fi
+}
+
+# ── 版本解析 ─────────────────────────────────────────────────────────────────
+normalize_version() {  # 统一成「不带 v 的纯版本号」+ 输出 tag 时再补 v
+  printf '%s' "$1" | sed -e 's/^[vV]//' -e 's/[[:space:]]*$//'
+}
+
+resolve_version() {
+  if [ -n "$VERSION_OPT" ]; then
+    VERSION="$(normalize_version "$VERSION_OPT")"
+    info "使用指定版本：v${VERSION}"
+    return 0
+  fi
+
+  info "未指定 --version，查询最新 Release（${API_BASE}/repos/${REPO_SLUG}/releases/latest）"
+  local body tag
+  body="$(fetch_text "${API_BASE}/repos/${REPO_SLUG}/releases/latest" 2>/dev/null || true)"
+  if [ -n "$body" ]; then
+    # 用 node 解 JSON 而不是 sed：release notes 正文里也可能出现 "tag_name" 字样，
+    # 而 node 本来就是本脚本的前置依赖，解析成本为零。
+    tag="$(printf '%s' "$body" | node -e 'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{try{const j=JSON.parse(s);if(j&&j.tag_name)process.stdout.write(String(j.tag_name))}catch(e){}})')"
+    if [ -n "$tag" ]; then
+      VERSION="$(normalize_version "$tag")"
+      info "最新 Release：v${VERSION}"
+      return 0
+    fi
+  fi
+
+  # API 不通时的兜底（国内直连 api.github.com 常被墙）：GitHub 的 /releases/latest
+  # 是 302 到 /releases/tag/<tag>，镜像只要保留这个重定向就还能解析出最新版本。
+  tag="$(effective_url "${BASE}/releases/latest" || true)"
+  case "$tag" in
+    */tag/*)
+      VERSION="$(normalize_version "${tag##*/}")"
+      info "通过镜像重定向解析到最新版本：v${VERSION}"
+      return 0 ;;
+  esac
+
+  die "无法解析最新版本（GitHub API 与镜像重定向都没成功）。
+    请显式指定版本重试：--version v1.0.0
+    国内网络可换镜像：LLM_GATEWAY_INSTALL_BASE=<你的镜像>/llm-api-gateway-cli"
+}
+
+# ── 已装版本判定（幂等的关键）───────────────────────────────────────────────
+# 直接读全局包里的 package.json，而不是跑 `gateway-agent --version`：
+# 后者在 PATH 里可能有另一个同名命令，那个版本不代表本次要装的前缀。
+installed_version() {
+  local pkg_json="$PREFIX_OPT/lib/node_modules/${APP_NAME}/package.json"
+  [ -f "$pkg_json" ] || return 0
+  node -e 'const fs=require("fs");try{const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(j.version)process.stdout.write(String(j.version))}catch(e){}' "$pkg_json" 2>/dev/null || true
+}
+
+# ── PATH 注入 ────────────────────────────────────────────────────────────────
+# opencode 那套分支值得照抄：不同 shell 该写哪个文件、写哪一行都不一样，
+# 猜错等于「装好了但敲命令没反应」——这是安装器最招骂的失败方式。
+path_line_for() {  # $1=shell 名 → 打印要写进 rc 文件的整行
+  case "$1" in
+    fish) printf 'fish_add_path "%s"\n' "$BIN_DIR" ;;
+    # 第二个 %s 传的是字面量 $PATH（转义写法）：这一行要原样写进用户的 rc 文件，
+    # 在这里被展开就写错了
+    *)    printf 'export PATH="%s:%s"\n' "$BIN_DIR" "\$PATH" ;;
+  esac
+}
+
+rc_file_for() {  # $1=shell 名 → 打印该 shell 的启动文件
+  case "$1" in
+    # macOS 的登录 shell 读 .bash_profile，Linux 的交互式 shell 读 .bashrc；
+    # 写错了就出现「重开终端才有 PATH」之外的第二种怪现象：永远没有
+    bash) if [ "$(uname -s 2>/dev/null || echo unknown)" = 'Darwin' ]; then printf '%s\n' "$HOME/.bash_profile"; else printf '%s\n' "$HOME/.bashrc"; fi ;;
+    zsh)  printf '%s\n' "$HOME/.zshrc" ;;
+    fish) printf '%s\n' "$HOME/.config/fish/config.fish" ;;
+    *)    printf '\n' ;;
+  esac
+}
+
+register_path() {
+  local manual="  export PATH=\"${BIN_DIR}:\$PATH\""
+
+  if [ "${GITHUB_ACTIONS:-}" = 'true' ]; then
+    # CI 里改 ~/.bashrc 是白费力气：runner 的每个 step 都是新 shell，
+    # 只有 $GITHUB_PATH 会被 GitHub 注入到后续 step 的 PATH 里。
+    if [ -n "${GITHUB_PATH:-}" ]; then
+      # 同一个 job 里重跑安装（升级 / -Force）不该把 PATH 越加越长
+      if [ -f "$GITHUB_PATH" ] && grep -qxF "$BIN_DIR" "$GITHUB_PATH" 2>/dev/null; then
+        ok "\$GITHUB_PATH 里已有 ${BIN_DIR}，跳过 PATH 注入"
+      elif [ "$DRY_RUN" = 1 ]; then
+        info "[dry-run] 会把 ${BIN_DIR} 追加到 \$GITHUB_PATH（${GITHUB_PATH}）"
+      else
+        printf '%s\n' "$BIN_DIR" >> "$GITHUB_PATH"
+        ok "已把 ${BIN_DIR} 追加到 \$GITHUB_PATH"
+      fi
+    else
+      warn "检测到 GITHUB_ACTIONS=true 但没有 \$GITHUB_PATH，跳过 PATH 注入"
+    fi
+    return 0
+  fi
+
+  if [ "$MODIFY_PATH" = 0 ]; then
+    info "已指定 --no-modify-path，未改任何 rc 文件。需要时手工加入："
+    printf '%s\n' "$manual"
+    return 0
+  fi
+
+  local shell_name rc line
+  shell_name="$(basename "${SHELL:-sh}")"
+  case "$shell_name" in
+    bash|zsh|fish) : ;;
+    *) shell_name='' ;;
+  esac
+  if [ -z "$shell_name" ]; then
+    warn "识别不出你的 shell（\$SHELL=${SHELL:-未设置}），请手工把下面这行加进启动文件："
+    printf '%s\n' "$manual"
+    return 0
+  fi
+
+  rc="$(rc_file_for "$shell_name")"
+  line="$(path_line_for "$shell_name")"
+
+  # 幂等：rc 文件里已经有这个目录就什么都不做（重跑安装不该把 PATH 越加越长）
+  if [ -f "$rc" ] && grep -qF "$BIN_DIR" "$rc" 2>/dev/null; then
+    ok "$rc 里已有 ${BIN_DIR}，跳过 PATH 注入"
+    return 0
+  fi
+
+  if [ "$DRY_RUN" = 1 ]; then
+    info "[dry-run] 会向 ${rc} 追加一行：${line%$'\n'}"
+    return 0
+  fi
+
+  mkdir -p "$(dirname "$rc")"
+  # 先补一个换行，避免原文件末尾没有换行时把两行粘成一行。
+  # 这里先判断再写（同一个文件既读又写），别把判断和追加塞进同一个重定向块。
+  if [ -s "$rc" ]; then
+    printf '\n' >> "$rc"
+  fi
+  printf '# added by %s installer\n%s' "$APP_NAME" "$line" >> "$rc"
+  ok "已把 ${BIN_DIR} 写进 ${rc}"
+  info "当前终端生效：source ${rc}（或重开一个终端）"
+}
+
+# ── 主流程 ───────────────────────────────────────────────────────────────────
+main() {
+  parse_args "$@"
+
+  if [ "$DRY_RUN" = 1 ]; then
+    info "演练模式（--dry-run）：只打印将要做的事，不下载、不安装、不改 PATH"
+  fi
+
+  info "安装目录：${PREFIX_OPT}"
+  info "下载前缀：${BASE}"
+  BIN_DIR="${PREFIX_OPT}/bin"
+
+  # 先查 Node 再查下载器：Node 是「装不装得成」的硬前提，curl 只是「怎么装」的手段。
+  # 顺序反过来的话，一台既没 Node 又没 curl 的机器会先被告知去装 curl，说完还得再来一轮。
+  check_node
+  pick_downloader
+
+  if [ -n "$VERSION_OPT" ]; then
+    resolve_version
+  elif [ "$DRY_RUN" = 1 ]; then
+    # 演练模式不去发网络请求：用户在没网的环境里也能确认参数解析与路径规划是否正确
+    VERSION='<latest>'
+    info "[dry-run] 会查询最新 Release 解析版本（此处不联网，用占位符继续）"
+  else
+    resolve_version
+  fi
+
+  if [ "$VERSION" != '<latest>' ]; then
+    TAG="v${VERSION}"
+    TGZ="${APP_NAME}-${VERSION}.tgz"
+    DOWNLOAD_URL="${BASE}/releases/download/${TAG}/${TGZ}"
+
+    # 幂等：已是目标版本且没 --force 就直接退出，连 PATH 都不碰（R3-V4 要的就是这个）
+    local have
+    have="$(installed_version)"
+    if [ -n "$have" ] && [ "$have" = "$VERSION" ] && [ "$FORCE" = 0 ]; then
+      ok "${APP_NAME} ${VERSION} 已经装在 ${PREFIX_OPT}，无需重装"
+      info "想强制重装：加 --force；想升级到别的版本：--version vX.Y.Z"
+      exit 0
+    fi
+    if [ -n "$have" ]; then
+      info "已装版本 ${have}，将覆盖安装为 ${VERSION}"
+    fi
+  else
+    TAG='v<latest>'
+    TGZ="${APP_NAME}-<version>.tgz"
+    DOWNLOAD_URL="${BASE}/releases/download/${TAG}/${TGZ}"
+  fi
+
+  if [ "$DRY_RUN" = 1 ]; then
+    info "[dry-run] 将下载：${DOWNLOAD_URL}"
+    info "[dry-run] 将执行：npm install -g --prefix \"${PREFIX_OPT}\" <临时目录>/${TGZ}"
+    register_path
+    info "[dry-run] 到此为止，没有写任何文件"
+    exit 0
+  fi
+
+  # 先探测 tag 是否存在：拿不到 200 却在后面报「下载失败」，用户会以为是网络问题，
+  # 实际是版本号写错了 —— 这两种情况的处理办法完全不同。
+  if [ "$VERSION" != '<latest>' ]; then
+    local code
+    code="$(http_status "$DOWNLOAD_URL")"
+    case "$code" in
+      200|302) : ;;
+      404)
+        die "Release ${TAG} 里没有 ${TGZ}（HTTP 404）。
+    可能是版本号写错，或该 tag 还没走完发布流水线；用 --version 指定的版本必须已经打过 tag。
+    核对可用版本：${BASE}/releases" ;;
+      *)
+        warn "无法预先校验 ${DOWNLOAD_URL}（HTTP ${code}），继续尝试下载" ;;
+    esac
+  fi
+
+  # 临时目录集中在 /tmp（或 $TMPDIR），装完/失败一律删掉：不留半成品是硬要求
+  TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/${APP_NAME}.XXXXXX" 2>/dev/null || true)"
+  if [ -z "$TMP_DIR" ] || [ ! -d "$TMP_DIR" ]; then
+    TMP_DIR="${TMPDIR:-/tmp}/${APP_NAME}.$$"
+    mkdir -p "$TMP_DIR" || die "无法创建临时目录 ${TMP_DIR}"
+  fi
+  trap cleanup EXIT INT TERM
+
+  info "下载 ${DOWNLOAD_URL}"
+  if ! fetch_file "$DOWNLOAD_URL" "${TMP_DIR}/${TGZ}"; then
+    die "下载失败：${DOWNLOAD_URL}
+    排查顺序：
+      1) 确认版本存在：${BASE}/releases
+      2) 国内网络换镜像：LLM_GATEWAY_INSTALL_BASE=https://your-mirror.example.com
+      3) 代理环境确认 https_proxy / http_proxy 已设置"
+  fi
+  ok "已下载到 ${TMP_DIR}/${TGZ}"
+
+  info "安装到 ${PREFIX_OPT}"
+  # --prefix 指到用户家目录下的私有目录：全局 npm 目录在多数系统上需要 sudo，
+  # 安装器不该悄悄要求 root，也不该往系统目录里写东西。
+  if ! npm install -g --prefix "$PREFIX_OPT" "${TMP_DIR}/${TGZ}"; then
+    die "npm 安装失败（临时文件已清理）。
+    手工复核：npm install -g --prefix \"${PREFIX_OPT}\" ${TGZ}
+    常见原因：安装目录不可写、npm 镜像源不通（npm config get registry）、磁盘空间不足"
+  fi
+  ok "已安装 ${APP_NAME} ${VERSION} → ${PREFIX_OPT}"
+
+  # 垫片缺失说明安装没真正落地（例如 npm 的 bin 目录与预期不符），
+  # 早说比让用户敲命令没反应、再来报「装完用不了」好
+  if [ ! -x "${BIN_DIR}/${MAIN_CMD}" ]; then
+    warn "没有找到 ${BIN_DIR}/${MAIN_CMD}，${MAIN_CMD} 可能不在预期位置（检查 npm 的 prefix 与 bin 设置）"
+  fi
+
+  register_path
+
+  printf '\n'
+  ok "安装完成 🎉"
+  cat <<EOF
+
+接下来：
+  1) 配密钥（不用手写 .env；三种给法任选）：
+       起服务后在页面「设置」里填 —— 存 ~/.llm-api-gateway-cli/credentials.json（仅本用户可读，不进 config.json）
+       或命令行：${MAIN_CMD} config set key sk-xxx
+       或环境变量：export GATEWAY_KEY=sk-xxx   # 也认 SK / OPENAI_API_KEY / ANTHROPIC_API_KEY；也可以在项目目录放 .env
+     没配之前 Web 服务照样能起（横幅会写「密钥 未配置」），只是发消息会被提示去配。
+  2) 自检：
+       ${MAIN_CMD} --help
+       ${MAIN_CMD} -p "用一句话介绍你自己"     # 命令行 agent 没有界面，缺密钥会当场报错并列出三种给法
+  3) 起本地 Web UI / 任务页（同一个服务、同一个端口）：
+       gateway-web 或 gateway-task        # 等价于 node server.js / node task-server.js
+       然后打开 http://127.0.0.1:3100/task
+  4) 想改模型 / 模式 / 历史预算：
+       ${MAIN_CMD} config list          # 带「来源」列，一眼看出被哪个环境变量盖住了
+
+卸载：rm -rf ${PREFIX_OPT}，并把上面写进 shell 启动文件的那行 PATH 删掉。
+EOF
+}
+
+main "$@"

package/server.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * 本地 Web UI 入口（模式四 聊天 + 模式五 任务，同一个端口）
+ *
+ *   node server.js                # http://127.0.0.1:3100/      聊天
+ *                                 # http://127.0.0.1:3100/task 任务
+ *
+ * 实现全在 lib/hub.js；task-server.js 是同一个服务的别名入口，两者完全等价。
+ * 之所以保留两个命令，只是为了不打断已有的习惯和脚本。
+ */
+
+import { runHub } from './lib/hub.js';
+
+runHub(process.argv.slice(2), { entry: 'web' });

package/task-server.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * 任务模式入口 —— 与 server.js 是**同一个服务**的别名。
+ *
+ * 聊天和任务已经合并到一个端口，跑起来之后两个页面都在：
+ *   http://127.0.0.1:3100/      聊天（模式四）
+ *   http://127.0.0.1:3100/task  任务（模式五）
+ *
+ * 原来任务页独占 3101，现在 3101 不再使用；用这个命令起服务会直接落到任务页。
+ * 实现全在 lib/hub.js。
+ */
+
+import { runHub } from './lib/hub.js';
+
+runHub(process.argv.slice(2), { entry: 'task' });