llm-api-gateway-cli 1.0.0

package/scripts/install.ps1

@@ -0,0 +1,537 @@
+<#
+.SYNOPSIS
+    llm-api-gateway-cli 一键安装脚本（Windows PowerShell 5.1 / PowerShell 7 通用）。
+
+.NOTES
+    本文件必须保持 **UTF-8 带 BOM**：Windows PowerShell 5.1 读无 BOM 的 UTF-8 会按 ANSI（中文
+    系统上是 GBK）解，结果不只是中文乱码 —— 某些字节序列会被解成引号/反引号，直接把脚本变成
+    语法错误。不少编辑器与写文件工具保存时会丢掉 BOM，**改完请复查首三字节是不是 EF BB BF**：
+
+        [System.IO.File]::ReadAllBytes('scripts\install.ps1')[0..2] -join ','   # 应为 239,187,191
+
+    行尾统一 LF（仓库根有 .gitattributes 兜底，Windows 上手工改仍可能变 CRLF）。
+
+.DESCRIPTION
+    从 GitHub Release 下载 `npm pack` 产物（llm-api-gateway-cli-<版本>.tgz），
+    用 `npm install -g --prefix <目录>` 装到用户私有目录，并把 bin 目录接进用户 PATH。
+    不做逐平台编译产物：本项目除 openai / @anthropic-ai/sdk 外零运行时依赖，
+    一份 tarball 同时供 curl 安装与 `npm i -g` 两条路线使用，避免两套东西漂移。
+
+    为什么默认装到 $HOME\.llm-api-gateway：Windows 的全局 npm 目录（%APPDATA%\npm）
+    与 Program Files 都可能需要管理员权限或被杀软盯着，装到用户家目录既不需要提权，
+    卸载也只是删一个目录。这对「装到无写权限的全局目录」这条风险是直接对策。
+
+.PARAMETER Version
+    安装指定版本，例如 v1.0.0 或 1.0.0；不传则查最新 Release。
+
+.PARAMETER Prefix
+    安装目录，默认 $HOME\.llm-api-gateway。
+
+.PARAMETER Base
+    所有下载地址的前缀，用于换国内镜像（默认 GitHub 仓库地址）。
+
+.PARAMETER NoModifyPath
+    不改用户 PATH，只打印需要手工加的一项。
+
+.PARAMETER DryRun
+    演练：只打印将要执行的步骤，不下载、不安装、不改 PATH。
+
+.PARAMETER Force
+    已是目标版本时也重装一遍（默认直接跳过）。
+
+.PARAMETER Help
+    显示帮助。
+
+.EXAMPLE
+    irm https://raw.githubusercontent.com/boonya-hrgk/llm-api-gateway-cli/v1.0.0/scripts/install.ps1 | iex
+
+.EXAMPLE
+    powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1 -Version v1.0.0 -DryRun
+
+.EXAMPLE
+    # 管道进来时没法直接传参，用 scriptblock 形式传
+    & ([scriptblock]::Create((irm https://raw.githubusercontent.com/boonya-hrgk/llm-api-gateway-cli/v1.0.0/scripts/install.ps1))) -Help
+
+.NOTES
+    环境变量（同名参数优先于环境变量）：
+      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  等价 -DryRun
+      GITHUB_ACTIONS=true            在 CI 里把 bin 目录写进 $env:GITHUB_PATH，而不是改用户 PATH
+#>
+param(
+  [string]$Version = '',
+  [string]$Prefix = '',
+  [string]$Base = '',
+  [switch]$NoModifyPath,
+  [switch]$DryRun,
+  [switch]$Force,
+  [switch]$Help
+)
+
+# ── 常量 ─────────────────────────────────────────────────────────────────────
+# TGZ 名必须与 package.json 的 name/version 对齐：`npm pack` 产出 <name>-<version>.tgz，
+# 而安装器是按 tag 拼文件名的，两边一旦不一致就是 404（CI 里也钉了这条一致性）。
+$AppName         = 'llm-api-gateway-cli'
+$MainCmd         = 'gateway-agent'
+$DefaultRepoSlug = 'boonya-hrgk/llm-api-gateway-cli'
+$DefaultBase     = "https://github.com/$DefaultRepoSlug"
+$DefaultApi      = 'https://api.github.com'
+$MinNodeMajor    = 18
+# 装 5.1 也认这个 UA：GitHub API 对没有 UA 的请求直接 403，而 PS5.1 的默认 UA
+# 在某些代理/网关下会被改写，显式带上最省事。
+$UserAgent       = "$AppName-installer"
+
+# ── 输出 ─────────────────────────────────────────────────────────────────────
+# 提示符统一用 ASCII（==> / [ok] / [!] / [错误]）：Windows 控制台在 GBK 代码页下
+# 显示 ✓ ✗ 这类符号会变成问号，日志重定向后更难认。中文本身靠文件 BOM 保证不乱码。
+function Write-Info { param([string]$Message) Write-Host "==> $Message" -ForegroundColor Cyan }
+function Write-Ok   { param([string]$Message) Write-Host "  [ok] $Message" -ForegroundColor Green }
+function Write-Warn { param([string]$Message) Write-Host "  [!] $Message" -ForegroundColor Yellow }
+function Fail       { param([string]$Message) throw $Message }
+
+function Show-Usage {
+  @"
+llm-api-gateway-cli 一键安装脚本（Windows / PowerShell 5.1 与 7）
+
+用法：
+  powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1 [选项]
+  irm <base>/scripts/install.ps1 | iex
+  & ([scriptblock]::Create((irm <base>/scripts/install.ps1))) [选项]   # 管道形式想传参就用这个
+
+选项：
+  -Version <版本>    安装指定版本，例如 v1.0.0 或 1.0.0（默认查最新 Release）
+  -Prefix <目录>     安装目录（默认 $HOME\.llm-api-gateway，不需要管理员权限）
+  -Base <URL>        所有下载地址的前缀，用于换镜像
+  -NoModifyPath      不改用户 PATH，只打印需要手工加的一项
+  -DryRun            演练：只打印将要执行的步骤，不下载、不安装、不改 PATH
+  -Force             已是目标版本时也重装一遍（默认直接跳过）
+  -Help              显示本帮助
+
+环境变量：
+  LLM_GATEWAY_INSTALL_BASE       下载前缀（默认 $DefaultBase）
+  LLM_GATEWAY_INSTALL_VERSION    等价 -Version
+  LLM_GATEWAY_INSTALL_DIR        等价 -Prefix（兼容 PREFIX）
+  LLM_GATEWAY_INSTALL_API        latest 查询前缀（默认 $DefaultApi）
+  LLM_GATEWAY_INSTALL_DRY_RUN=1  等价 -DryRun
+  GITHUB_ACTIONS=true            把 bin 目录写进 `$env:GITHUB_PATH
+
+装完怎么用：
+  gateway-task                   # 起服务（没有密钥也能起），在页面「设置」里填密钥
+  $MainCmd config set key sk-xxx # 或者命令行填：写 credentials.json，不进 config.json
+  `$env:GATEWAY_KEY = 'sk-xxx'   # 或者环境变量 / SK / .env（优先级更高）
+  $MainCmd --help
+  $MainCmd -p "用一句话介绍你自己"
+"@ | Write-Host
+}
+
+# ── 全局状态 ─────────────────────────────────────────────────────────────────
+$script:TempDir   = ''
+# windows 上 npm 把 bin 垫片直接放在 prefix 根目录，包体在 <prefix>\node_modules；
+# unix 上才是 <prefix>/bin 与 <prefix>/lib/node_modules —— 判定错了就会出现
+# 「装完了但 PATH 指到一个空目录」。
+$script:BinDir    = ''
+$script:PkgJson   = ''
+
+function Get-PlatformFlags {
+  $onWindows = $true
+  if ($PSVersionTable.PSVersion.Major -ge 6) { $onWindows = [bool]$IsWindows }
+  return $onWindows
+}
+
+function Invoke-Setup {
+  if ($Help) { Show-Usage; return }
+
+  if ($PSVersionTable.PSVersion.Major -lt 5) {
+    Fail "需要 PowerShell 5.1 或更高版本（当前 $($PSVersionTable.PSVersion)）"
+  }
+
+  # 5.1 默认可能还在 TLS 1.0：老系统上不补这一句，连 GitHub 会以「基础连接已关闭」失败，
+  # 用户只会以为是网络问题。PS7 里这句是空操作，留着无害。
+  try {
+    $sp = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+    [Net.ServicePointManager]::SecurityProtocol = $sp
+  } catch { }
+
+  # 5.1 的进度条在下载大文件时会拖慢一个数量级；用完还原，别改用户会话的状态
+  $oldProgress = $ProgressPreference
+  $ProgressPreference = 'SilentlyContinue'
+  try {
+    # ── 参数与环境变量合并 ───────────────────────────────────────────────────
+    if (-not $Base) {
+      if ($env:LLM_GATEWAY_INSTALL_BASE) { $Base = $env:LLM_GATEWAY_INSTALL_BASE } else { $Base = $DefaultBase }
+    }
+    if (-not $Version -and $env:LLM_GATEWAY_INSTALL_VERSION) { $Version = $env:LLM_GATEWAY_INSTALL_VERSION }
+    if (-not $Prefix) {
+      if ($env:LLM_GATEWAY_INSTALL_DIR) { $Prefix = $env:LLM_GATEWAY_INSTALL_DIR }
+      elseif ($env:PREFIX) { $Prefix = $env:PREFIX }
+      else { $Prefix = Join-Path $HOME '.llm-api-gateway' }
+    }
+    $api = $DefaultApi
+    if ($env:LLM_GATEWAY_INSTALL_API) { $api = $env:LLM_GATEWAY_INSTALL_API }
+    if ($env:LLM_GATEWAY_INSTALL_DRY_RUN -eq '1') { $DryRun = $true }
+
+    # 结尾斜杠会让拼出来的 URL 变 //，某些镜像/签名校验会因此 403
+    $Base = $Base.TrimEnd('/')
+    $api  = $api.TrimEnd('/')
+
+    # 展开 ~ 与相对路径：后面要做 PATH 幂等比较，带 ~ 的字符串永远比不出相等
+    $Prefix = $Prefix.TrimEnd('\', '/')
+    if ($Prefix -eq '~') { $Prefix = $HOME }
+    elseif ($Prefix.StartsWith('~/') -or $Prefix.StartsWith('~\')) { $Prefix = Join-Path $HOME $Prefix.Substring(2) }
+    if (-not [System.IO.Path]::IsPathRooted($Prefix)) { $Prefix = Join-Path (Get-Location).ProviderPath $Prefix }
+    $Prefix = [System.IO.Path]::GetFullPath($Prefix)
+
+    $onWindows = Get-PlatformFlags
+    if ($onWindows) {
+      $script:BinDir  = $Prefix
+      $script:PkgJson = Join-Path (Join-Path $Prefix 'node_modules') (Join-Path $AppName 'package.json')
+    } else {
+      $script:BinDir  = Join-Path $Prefix 'bin'
+      $script:PkgJson = Join-Path (Join-Path (Join-Path $Prefix 'lib') 'node_modules') (Join-Path $AppName 'package.json')
+    }
+
+    # 从下载前缀里反推仓库 slug：fork / 自建镜像的人不用再手改脚本里的常量
+    $repoSlug = $DefaultRepoSlug
+    if ($Base -match '^https://github\.com/([^/]+/[^/]+)') { $repoSlug = $Matches[1] }
+
+    if ($DryRun) { Write-Info '演练模式（-DryRun）：只打印将要做的事，不下载、不安装、不改 PATH' }
+    Write-Info "安装目录：$Prefix"
+    Write-Info "下载前缀：$Base"
+    Write-Info "bin 垫片目录：$($script:BinDir)"
+
+    # ── 前置检查：Node >= 18 ─────────────────────────────────────────────────
+    $node = Get-Command node -ErrorAction SilentlyContinue
+    if (-not $node) {
+      Fail @"
+找不到 node。本工具需要 Node.js $MinNodeMajor 或更高版本；请先自行安装后重跑：
+  · 官方安装包  https://nodejs.org/zh-cn/download
+  · 版本管理    nvm-windows (https://github.com/coreybutler/nvm-windows) / fnm / scoop / winget
+安装器不代装 Node —— 替你改系统级运行时是越界行为，装错版本更难排查。
+"@
+    }
+    $nodeRaw = (& node -v 2>$null | Select-Object -First 1)
+    if ($LASTEXITCODE -ne 0 -or -not $nodeRaw) {
+      Fail "node 存在但执行失败（node -v 退出码 $LASTEXITCODE），请检查 Node 安装是否完整"
+    }
+    if ($nodeRaw -notmatch '^v?(\d+)\.') {
+      Fail "无法识别 node 版本（node -v 输出：'$nodeRaw'）"
+    }
+    $nodeMajor = [int]$Matches[1]
+    if ($nodeMajor -lt $MinNodeMajor) {
+      Fail @"
+Node.js 版本过低：当前 $nodeRaw，需要 v$MinNodeMajor 及以上。
+升级办法：nvm install $MinNodeMajor（然后 nvm use $MinNodeMajor），或用 winget upgrade OpenJS.NodeJS
+"@
+    }
+    Write-Ok "Node.js $nodeRaw"
+
+    $npmCmd = Get-Command npm.cmd -ErrorAction SilentlyContinue
+    if (-not $npmCmd) { $npmCmd = Get-Command npm -ErrorAction SilentlyContinue }
+    if (-not $npmCmd) {
+      Fail ' 找不到 npm。它随 Node.js 一起分发，请检查安装是否完整（node -v 正常但 npm 缺失，常见于手工拼装的环境变量）'
+    }
+
+    # ── 版本解析 ─────────────────────────────────────────────────────────────
+    if (-not $Version) {
+      if ($DryRun) {
+        # 演练模式不发网络请求：没网时也能确认参数解析与路径规划是否正确
+        $Version = '<latest>'
+        Write-Info '[-DryRun] 会查询最新 Release 解析版本（此处不联网，用占位符继续）'
+      } else {
+        $Version = Resolve-LatestVersion -Api $api -RepoSlug $repoSlug -Base $Base
+      }
+    }
+    $version = $Version.TrimStart('v', 'V').Trim()
+
+    if ($version -eq '<latest>') {
+      $tag = 'v<latest>'
+      $tgz = "$AppName-<version>.tgz"
+    } else {
+      $tag = "v$version"
+      $tgz = "$AppName-$version.tgz"
+      Write-Info "使用版本：$tag"
+    }
+    $downloadUrl = "$Base/releases/download/$tag/$tgz"
+
+    # ── 幂等：已是目标版本就直接退出，连 PATH 都不碰 ─────────────────────────
+    $have = Get-InstalledVersion
+    if ($version -ne '<latest>') {
+      if ($have -eq $version -and -not $Force) {
+        Write-Ok "$AppName $version 已经装在 $Prefix，无需重装"
+        Write-Info '想强制重装：加 -Force；想升级到别的版本：-Version vX.Y.Z'
+        return
+      }
+      if ($have) { Write-Info "已装版本 $have，将覆盖安装为 $version" }
+    }
+
+    if ($DryRun) {
+      Write-Info "[-DryRun] 将下载：$downloadUrl"
+      Write-Info "[-DryRun] 将执行：npm install -g --prefix `"$Prefix`" <临时目录>\$tgz"
+      Register-Path -OnWindows $onWindows
+      Write-Info '[-DryRun] 到此为止，没有写任何文件'
+      return
+    }
+
+    # ── 版本存在性预检 ───────────────────────────────────────────────────────
+    # 拿不到 200 却在后面报「下载失败」，用户会以为是网络问题，实际是版本号写错了 ——
+    # 这两种情况的处理办法完全不同，所以先分开探测。
+    if ($version -ne '<latest>') {
+      $code = Get-HttpStatus -Url $downloadUrl
+      if ($code -eq 404) {
+        Fail @"
+Release $tag 里没有 $tgz（HTTP 404）。
+可能是版本号写错，或该 tag 还没走完发布流水线；-Version 指定的版本必须已经打过 tag。
+核对可用版本：$Base/releases
+"@
+      } elseif ($code -ne 200 -and $code -ne 302) {
+        Write-Warn "无法预先校验 $downloadUrl（HTTP $code），继续尝试下载"
+      }
+    }
+
+    # ── 下载 ─────────────────────────────────────────────────────────────────
+    # 临时目录集中放系统 temp，装完/失败一律删掉：不留半成品是硬要求
+    $script:TempDir = Join-Path ([System.IO.Path]::GetTempPath()) ("$AppName-install-" + [Guid]::NewGuid().ToString('N'))
+    New-Item -ItemType Directory -Path $script:TempDir -Force | Out-Null
+    $tgzPath = Join-Path $script:TempDir $tgz
+
+    Write-Info "下载 $downloadUrl"
+    try {
+      Invoke-WebRequest -Uri $downloadUrl -OutFile $tgzPath -UseBasicParsing -UserAgent $UserAgent -TimeoutSec 300
+    } catch {
+      Fail @"
+下载失败：$downloadUrl
+$($_.Exception.Message)
+排查顺序：
+  1) 确认版本存在：$Base/releases
+  2) 国内网络换镜像：`$env:LLM_GATEWAY_INSTALL_BASE = 'https://your-mirror.example.com'
+  3) 代理环境确认 `$env:HTTPS_PROXY 已设置
+"@
+    }
+    if (-not (Test-Path $tgzPath)) { Fail "下载后没有找到文件：$tgzPath" }
+    Write-Ok "已下载到 $tgzPath"
+
+    # ── 安装 ─────────────────────────────────────────────────────────────────
+    Write-Info "安装到 $Prefix"
+    # --prefix 指到用户家目录下的私有目录：全局 npm 目录在多数系统上需要管理员权限，
+    # 安装器不该悄悄要求提权，也不该往系统目录里写东西。
+    & $npmCmd.Source install -g --prefix $Prefix $tgzPath
+    if ($LASTEXITCODE -ne 0) {
+      Fail @"
+npm 安装失败（临时文件已清理）。
+手工复核：npm install -g --prefix "$Prefix" $tgz
+常见原因：安装目录不可写、npm 镜像源不通（npm config get registry）、磁盘空间不足
+"@
+    }
+    Write-Ok "已安装 $AppName $version → $Prefix"
+
+    # 垫片缺失说明安装没真正落地（例如 npm 把 bin 放到别处），早说比让用户敲命令没反应好
+    $shim = Join-Path $script:BinDir $(if ($onWindows) { "$MainCmd.cmd" } else { $MainCmd })
+    if (-not (Test-Path $shim)) { Write-Warn "没有找到 $shim，$MainCmd 可能不在预期位置" }
+
+    Register-Path -OnWindows $onWindows
+
+    Write-Host ''
+    Write-Ok '安装完成'
+    Write-Host @"
+
+接下来：
+  1) 配密钥（不用手写 .env；三种给法任选）：
+       起服务后在页面「设置」里填 —— 存 `$HOME\.llm-api-gateway-cli\credentials.json（仅本用户可读，不进 config.json）
+       或命令行：$MainCmd config set key sk-xxx
+       或环境变量：`$env:GATEWAY_KEY = 'sk-xxx'   # 也认 SK / OPENAI_API_KEY / ANTHROPIC_API_KEY；也可以放 .env
+     没配之前 Web 服务照样能起（横幅会写「密钥 未配置」），只是发消息会被提示去配。
+  2) 自检（新开的终端里）：
+       $MainCmd --help
+       $MainCmd -p "用一句话介绍你自己"     # 命令行 agent 没有界面，缺密钥会当场报错并列出三种给法
+  3) 起本地 Web UI / 任务页（同一个服务、同一个端口）：
+       gateway-web 或 gateway-task，然后打开 http://127.0.0.1:3100/task
+  4) 想改模型 / 模式 / 历史预算：
+       $MainCmd config list          # 带「来源」列，一眼看出被哪个环境变量盖住了
+
+卸载：Remove-Item -Recurse -Force "$Prefix"，并删掉用户 PATH 里的那一项。
+"@
+  } finally {
+    $ProgressPreference = $oldProgress
+  }
+}
+
+# 解析最新 tag；先用 GitHub API（文档 5.2 第 3 步），失败再退回镜像重定向
+function Resolve-LatestVersion {
+  param([string]$Api, [string]$RepoSlug, [string]$Base)
+
+  $apiUrl = "$Api/repos/$RepoSlug/releases/latest"
+  Write-Info "未指定 -Version，查询最新 Release（$apiUrl）"
+  try {
+    $resp = Invoke-RestMethod -Uri $apiUrl -UseBasicParsing -UserAgent $UserAgent -TimeoutSec 20
+    if ($resp -and $resp.tag_name) { return [string]$resp.tag_name }
+  } catch {
+    Write-Warn "GitHub API 查询失败：$($_.Exception.Message)"
+  }
+
+  # 国内直连 api.github.com 常被墙：GitHub 的 /releases/latest 是 302 到 /releases/tag/<tag>，
+  # 镜像只要保留这个重定向就还能解析出最新版本。
+  try {
+    $r = Invoke-WebRequest -Uri "$Base/releases/latest" -UseBasicParsing -UserAgent $UserAgent -TimeoutSec 20
+    $finalUri = $null
+    # 5.1 用 ResponseUri，7 里换成 RequestMessage.RequestUri：两个属性都探一下，
+    # 探不到就当作没有（没有 Set-StrictMode，取不存在的属性只会得到 $null）
+    try { $finalUri = $r.BaseResponse.ResponseUri } catch { }
+    if (-not $finalUri) { try { $finalUri = $r.BaseResponse.RequestMessage.RequestUri } catch { } }
+    if ("$finalUri" -match '/tag/(v?[0-9][^/?#]*)$') { return $Matches[1] }
+  } catch {
+    Write-Warn "镜像重定向解析失败：$($_.Exception.Message)"
+  }
+
+  Fail @"
+无法解析最新版本（GitHub API 与镜像重定向都没成功）。
+请显式指定版本重试：-Version v1.0.0
+国内网络可换镜像：`$env:LLM_GATEWAY_INSTALL_BASE = '<你的镜像>/llm-api-gateway-cli'
+"@
+}
+
+# 直接读全局包里的 package.json，而不是跑 `gateway-agent --version`：
+# 后者在 PATH 里可能有另一个同名命令，那个版本不代表本次要装的前缀。
+function Get-InstalledVersion {
+  if (-not (Test-Path $script:PkgJson)) { return '' }
+  try {
+    $json = Get-Content -Raw -Path $script:PkgJson -Encoding UTF8 | ConvertFrom-Json
+    if ($json.version) { return [string]$json.version }
+  } catch { }
+  return ''
+}
+
+function Get-HttpStatus {
+  param([string]$Url)
+  try {
+    $null = Invoke-WebRequest -Uri $Url -Method Head -UseBasicParsing -UserAgent $UserAgent -TimeoutSec 20
+    return 200
+  } catch {
+    # 有的镜像/服务器不认 HEAD（405）或直接断开（0）：交给调用方决定是否继续尝试下载
+    if ($_.Exception.Response) {
+      try { return [int]$_.Exception.Response.StatusCode } catch { return 0 }
+    }
+    return 0
+  }
+}
+
+# ── PATH 注入 ────────────────────────────────────────────────────────────────
+function Register-Path {
+  param([bool]$OnWindows)
+
+  $binDir = $script:BinDir
+  $manual = "  把 $binDir 加进 PATH"
+
+  if ($env:GITHUB_ACTIONS -eq 'true') {
+    # CI 里改用户 PATH 是白费力气：runner 的每个 step 都是新进程，
+    # 只有 $env:GITHUB_PATH 会被 GitHub 注入到后续 step 的 PATH 里。
+    if ($env:GITHUB_PATH) {
+      # 同一个 job 里重跑安装（升级 / -Force）不该把 PATH 越加越长
+      $already = $false
+      if (Test-Path $env:GITHUB_PATH) {
+        $already = @(Get-Content -Path $env:GITHUB_PATH -ErrorAction SilentlyContinue) -contains $binDir
+      }
+      if ($already) {
+        Write-Ok "`$env:GITHUB_PATH 里已有 $binDir，跳过 PATH 注入"
+      } elseif ($DryRun) {
+        Write-Info "[-DryRun] 会把 $binDir 追加到 `$env:GITHUB_PATH（$env:GITHUB_PATH）"
+      } else {
+        # 用 .NET 追加：PS5.1 的 Add-Content -Encoding UTF8 会写 BOM，
+        # 文件首行的 BOM 会让 GitHub 认不出第一个路径
+        [System.IO.File]::AppendAllText($env:GITHUB_PATH, $binDir + [Environment]::NewLine)
+        Write-Ok "已把 $binDir 追加到 `$env:GITHUB_PATH"
+      }
+    } else {
+      Write-Warn '检测到 GITHUB_ACTIONS=true 但没有 $env:GITHUB_PATH，跳过 PATH 注入'
+    }
+    return
+  }
+
+  if ($NoModifyPath) {
+    Write-Info '-NoModifyPath：未改 PATH。需要时手工处理：'
+    Write-Host $manual
+    return
+  }
+
+  if (-not $OnWindows) {
+    Write-Warn "当前不是 Windows，本脚本不改 *nix 的 shell 启动文件。请手工加一行："
+    Write-Host "  export PATH=`"$binDir`":`$PATH"
+    return
+  }
+
+  # 直接读写注册表原文而不是 [Environment]::GetEnvironmentVariable('Path','User')：
+  # 后者会把 %VAR% 展开，回写时若变成字面量就等于悄悄改坏了用户的 PATH。
+  # 同理只在原文后面追加一项、不重建整个值，其它项与原有 kind 都不动。
+  $rawUserPath = ''
+  $userPathItem = Get-ItemProperty -Path 'HKCU:\Environment' -Name 'Path' -ErrorAction SilentlyContinue
+  if ($userPathItem -and $userPathItem.PSObject.Properties['Path']) { $rawUserPath = [string]$userPathItem.Path }
+
+  $entries = @()
+  if ($rawUserPath) { $entries = $rawUserPath -split ';' | Where-Object { $_ -ne '' } }
+  $normalized = $entries | ForEach-Object { $_.Trim().TrimEnd('\', '/') }
+  if ($normalized -contains $binDir.TrimEnd('\', '/')) {
+    Write-Ok "用户 PATH 里已有 $binDir，跳过 PATH 注入"
+    return
+  }
+  # 机器级 PATH 里已有就不重复加（只读检查，不动机器级配置）
+  $machinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
+  if ($machinePath) {
+    $machineNorm = $machinePath -split ';' | Where-Object { $_ -ne '' } | ForEach-Object { $_.Trim().TrimEnd('\', '/') }
+    if ($machineNorm -contains $binDir.TrimEnd('\', '/')) {
+      Write-Ok "系统 PATH 里已有 $binDir，跳过 PATH 注入"
+      return
+    }
+  }
+
+  if ($DryRun) {
+    Write-Info "[-DryRun] 会向用户 PATH（HKCU:\Environment 的 Path）追加：$binDir"
+    return
+  }
+
+  if (-not (Test-Path 'HKCU:\Environment')) { New-Item -Path 'HKCU:\Environment' -Force | Out-Null }
+  if ($rawUserPath) {
+    $newUserPath = $rawUserPath.TrimEnd(';') + ';' + $binDir
+  } else {
+    $newUserPath = $binDir
+  }
+  # 两个分支都**显式**要 ExpandString，不依赖 Set-ItemProperty 回写时的 kind 默认行为：
+  # 用户的 User PATH 绝大多数是 REG_EXPAND_SZ，一旦被降级成 REG_SZ，里面的
+  # %USERPROFILE%\... 之类就不再展开 —— 等于安装器悄悄改坏了别人的 PATH，
+  # 事后极难归因。原本是 REG_SZ 的 PATH 变成 REG_EXPAND_SZ 无害且更好：
+  # %VAR% 会正常展开，未定义的变量 Windows 原样保留。
+  New-ItemProperty -Path 'HKCU:\Environment' -Name 'Path' -Value $newUserPath -PropertyType ExpandString -Force | Out-Null
+  # 当前会话也生效，省得用户为了跑一句 --help 还得先重开终端
+  $env:Path = "$binDir;$env:Path"
+  Write-Ok "已把 $binDir 追加到用户 PATH"
+  Write-Info '新开的终端才会自动带上；当前这个会话已经临时生效'
+}
+
+# ── 入口 ─────────────────────────────────────────────────────────────────────
+# 先执行、再在 catch 里落错误，最后统一收尾：这样 finally 一定跑（临时文件一定删），
+# 退出码也不会被 finally 吞掉。
+#
+# 只有以文件方式运行（-File / powershell .\install.ps1）时才 exit：
+# 文档推荐的 `irm ... | iex` 是把这段脚本跑在用户**当前会话**里，
+# 在那里 exit 会直接把用户自己的 PowerShell 窗口关掉 —— 装不上是小事，
+# 关掉用户窗口（可能还挂着别的活）是大事。
+# 管道模式下没有退出码可传，所以至少把失败明确打出来。
+$exitCode = 0
+try {
+  Invoke-Setup
+} catch {
+  Write-Host "  [错误] $($_.Exception.Message)" -ForegroundColor Red
+  $exitCode = 1
+} finally {
+  if ($script:TempDir -and (Test-Path $script:TempDir)) {
+    Remove-Item -Recurse -Force $script:TempDir -ErrorAction SilentlyContinue
+  }
+}
+
+$runFromFile = [bool]$MyInvocation.MyCommand.Path
+if ($runFromFile) {
+  exit $exitCode
+} elseif ($exitCode -ne 0) {
+  Write-Host '  [错误] 安装未完成（已保留你当前的会话，不执行 exit）' -ForegroundColor Red
+}