dsh-calibguard 0.3.2 → 0.3.4

package/README.en.md

@@ -68,6 +68,24 @@ are missing. **You don't install them by hand.** After you install the plugin an
 > The CG release zip is **no longer downloaded from GitHub by default**; only an explicit
 > `node setup.mjs --from <zip>` or `--url <url>` uses it (offline installs / pinning an engine version).
 
+**Install speed**: the model/engine archive is downloaded with **4 parallel ranged connections** (measured
+0.6 MB/s single → 2.3 MB/s parallel); GitHub direct failures fall back to the gh-proxy / ghfast / ghproxy
+mirrors, and pip tries Tsinghua → Aliyun → USTC → Tencent → PyPI in order. Tune with
+`DSH_CALIBGUARD_DOWNLOAD_CONNECTIONS`.
+
+**GPU auto-tiering**: with an NVIDIA GPU that has **CUDA ≥ 12.8 and compute capability ≥ 7.5** (RTX 20/30/40)
+the installer pulls the **CUDA (cu128) build of torch**; otherwise it installs the CPU build (GTX 10 series is
+SM 6.1 and has no kernels in the cu128 wheels). The panel header shows the inference device and the reason.
+
+Manual override (optional): `node setup.mjs --force-cuda` (force the CUDA build, skipping the CUDA/compute
+checks — use at your own risk) or `node setup.mjs --cpu` (force CPU), or the env vars
+`DSH_CALIBGUARD_FORCE_CUDA=1` / `DSH_CALIBGUARD_CPU_ONLY=1`. Switch later with
+`node setup.mjs --reinstall-torch --force-cuda` (or `--cpu`).
+
+> The CPU and CUDA builds of torch **cannot coexist in one venv** (same package name; installing one replaces
+> the other). The CUDA build is a full torch and falls back to CPU when no GPU is available, so coexistence is
+> unnecessary.
+
 **Where to watch progress**: the panel shows a "First run: preparing engine and dependencies" card with
 the current step and the tail of the installer output; host logs show `[calibguard]` lines. The audit
 button stays disabled until it is ready — press "刷新状态 / Refresh" afterwards. Expect **10–20 minutes**
@@ -92,13 +110,17 @@ once (depends on network and pip mirror).
 
 ### Option 0 — desktop "Add plugin" dialog (easiest, recommended)
 
-DSH desktop → Settings → **Add plugin**, paste any one of the following (restart DSH afterwards):
+**On DSH desktop it is one step: Settings → Add plugin → enter `dsh-calibguard` → restart DSH.**
+That installs the latest npm release; to pin a version write `dsh-calibguard@0.3.3` (`@` + version).
+No terminal and no source download needed.
+
+The dialog also accepts any of the following (restart DSH afterwards):
 
 | Paste | Example | Notes |
 |---|---|---|
 | **GitHub repository URL** (recommended) | `https://github.com/maomitgd2006/dsh-CalibGuard` | Fetches the source and registers the bundle in the current profile |
 | **Local directory path** | `<path to this package>` (e.g. `/opt/dsh-calibguard`) | For a local clone / extracted copy |
-| **Package name** | `dsh-calibguard` | ✅ **Published on npm**; just enter the package name (installs npm `latest`) |
+| **Package name** | `dsh-calibguard` or `dsh-calibguard@0.3.3` | ✅ **Published on npm**; without a version it installs `latest`, with `@version` it pins that version |
 
 > Equivalent CLI (verified: after install DSH automatically appends the package to the profile's
 > `dsh.profile.bundles`):
@@ -201,7 +223,14 @@ After pressing Save:
 - values are written to `$DSH_HOME/calibguard-settings.json` (defaults to `~/.dsh`, never committed);
 - **the AI uses the same values** (precedence: plugin config < shared settings < per-call options);
 - changes take effect immediately, no restart;
-- the API key goes into the DSH credential store (`ctx.credentials`), not into that settings file.
+- the API key goes into the DSH credential store (`ctx.credentials`), not into that settings file;
+- the **credential name** is only the name of the storage slot (not the secret): fill it in the panel
+  (e.g. `DEEPSEEK_API_KEY`) together with the API key; the name is remembered in shared settings
+  (`credentialRef`) and the value is written to the DSH credential store. Leave it empty to use the
+  plugin config `credentialRef`;
+- **audit results**: every audit writes JSON + Markdown into the engine's `reports/` directory
+  (default `<engineRoot>/reports`, `engineRoot` defaults to `~/.dsh/calibguard-engine`). The panel shows
+  that path, has a "clear results" button, and each item links to its Markdown report.
 
 ### 4) Tool parameters (per-call, advanced)
 
@@ -228,7 +257,7 @@ Common keys of the loader row `config` (full table: [docs/configuration.md](docs
 | `enabled` | `true` | When false nothing is registered (no need to remove the row) |
 | `engineRoot` | `''` | CG_GUI directory; empty = the `CG_GUI` next to this package |
 | `device` | `auto` | Checks both CUDA build and compute capability; low-end GPUs fall back to CPU |
-| `credentialRef` | `''` | Recommended credential reference name, e.g. `DEEPSEEK_API_KEY` (resolved via the DSH credential store) |
+| `credentialRef` | `''` | Credential **name** (storage slot, not the secret), e.g. `DEEPSEEK_API_KEY`; empty = use the name saved from the panel; the value lives in the DSH credential store / env |
 | `announceToModel` | `true` | Add "when to use CalibGuard" to the system prompt |
 | `autoSetup` | `true` | On first run, automatically download the engine, a portable Python when needed, and install deps; set `false` to only fail with instructions |
 | `maxFiles` | `20` | Directory recursion cap; explicitly given/uploaded files are not capped |
@@ -240,10 +269,15 @@ Common keys of the loader row `config` (full table: [docs/configuration.md](docs
 | Symptom | Fix |
 |---|---|
 | No sidebar icon / panel says `not found` | Client bundle and routes load at host startup: **restart DSH** |
-| **First run takes 10–20 minutes** | Normal: the model (476 MB) is downloaded from npm mirrors and dependencies (1–3 GB) are installed once; the panel shows progress |
+| **First run takes 10–20 minutes** | Normal: the model (~442 MB, from the repository's model release asset with mirror fallback) and dependencies (1–3 GB) are installed once; the panel shows progress |
 | First audit is slow | Normal: ~475 MB of weights are loaded once (then the process stays resident) |
 | Big file takes tens of seconds | Normal: full-text sliding-window inference; see [docs/performance.md](docs/performance.md) |
-| Gray zone always goes to manual review | No credential configured: set `credentialRef` (recommended) or configure it in DSH Models |
+| Gray zone always goes to manual review | No credential configured: save "credential name + API key" in the panel, or set `credentialRef`, or configure it in DSH Models |
+| **Panel says "credentialRef required" when saving the API key** | Upgrade to ≥ **0.3.3**: the panel has a "credential name" field and remembers it (no plugin config edit needed); older versions require `credentialRef` in the plugin config |
+| **Where are audit results saved / how to clear them** | In the engine's `reports/` directory (default `<engineRoot>/reports`): JSON + Markdown per audit. The panel shows the path and has a "clear results" button; AI tools return `report_md_path` / `report_json_path` |
+| **"First audit will load the model" hint shows every time** | Since 0.3.3 it is only shown while the model is not loaded yet; afterwards the button just says "auditing…" and the header shows "model loaded" |
+| **NVIDIA GPU (e.g. RTX 2060) but the engine keeps using CPU** | The installed torch is the CPU build (old installer behavior). Upgrade to ≥0.3.3 (the panel will tell you) and run `node setup.mjs --reinstall-torch` (~2.5 GB) in the plugin directory, then restart DSH |
+| **Want to force the GPU / CPU torch build** | Add `--force-cuda` / `--cpu` at install time (combine with `--reinstall-torch` to replace an existing build); the runtime device is controlled by the plugin config `device` (auto/cpu/cuda); `cuda` requires the CUDA build |
 | A legitimate third-party library is BLOCKed | Minified libraries are full of eval/base64 patterns and the corpus is Python-heavy — known false-positive tendency, see [docs/troubleshooting.md](docs/troubleshooting.md) |
 | Panel returns 401/403 | Browser session isn't authenticated with the host: refresh / sign in again |
 | The AI ignores changed settings | Press Save in the panel; editing fields without saving applies to that run only |

package/README.md

@@ -62,6 +62,23 @@
 > 默认**不再**从 GitHub 下载 CG 发行包；只有显式 `node setup.mjs --from <zip>` 或 `--url <地址>`
 > 才会走 CG 发行包，用于离线/指定引擎版本。
 
+**安装速度**：模型/引擎包默认 **4 路并发分段下载**（实测单连接 0.6 MB/s → 并发 2.3 MB/s），
+GitHub 直连失败会自动换 gh-proxy / ghfast / ghproxy 镜像；pip 依赖按 清华 → 阿里 → 中科大 → 腾讯 → 官方
+依次回退。可用 `DSH_CALIBGUARD_DOWNLOAD_CONNECTIONS` 调整并发数。
+
+**GPU 自动定档**：检测到 NVIDIA 且 **CUDA ≥ 12.8、算力 ≥ 7.5**（RTX 20/30/40 系）时自动安装
+**CUDA（cu128）版 torch**；否则装 CPU 版（GTX 10 系算力 6.1，cu128 轮子里没有对应 kernel，只能 CPU）。
+面板顶部会显示「推理设备：cpu/cuda」和定档原因。
+
+手动覆盖（可选）：
+`node setup.mjs --force-cuda`（强制装 CUDA 版，跳过 CUDA/算力检查，风险自负）、
+`node setup.mjs --cpu`（强制 CPU 版），或环境变量 `DSH_CALIBGUARD_FORCE_CUDA=1` /
+`DSH_CALIBGUARD_CPU_ONLY=1`。装完想切换：`node setup.mjs --reinstall-torch --force-cuda` 或
+`--reinstall-torch --cpu`。
+
+> CPU 版与 CUDA 版 torch **不能同时存在于同一个 venv**（同名包会互相覆盖）；
+> 但 CUDA 版 torch 本身就是完整 torch，没有 GPU 时会自动用 CPU，所以不需要共存。
+
 **进度在哪看**：面板顶部会出现「首次运行：正在自动准备引擎与依赖」卡片（含当前步骤与输出尾巴）；
 宿主日志里是 `[calibguard]` 开头的行。准备期间审计按钮不可用，完成后点「刷新状态」即可。
 首次约需 **10–20 分钟**（取决于网速和 pip 源），只需一次。
@@ -85,13 +102,17 @@
 
 ### 方式 0：桌面端「添加插件」（最省事，推荐）
 
-DSH 桌面版 → 设置 → **添加插件**，输入框里填以下任意一种即可（装完按提示重启 DSH）：
+**DSH 桌面版只需要一步：设置 → 添加插件 → 输入 `dsh-calibguard` → 重启 DSH。**
+默认装 npm 上的最新版；要固定版本就写 `dsh-calibguard@0.3.3`（`@` 后面是版本号）。
+不需要命令行、不需要下载源码。
+
+输入框里也可以填以下任意一种（装完按提示重启 DSH）：
 
 | 填什么 | 示例 | 说明 |
 |---|---|---|
 | **GitHub 仓库地址**（推荐） | `https://github.com/maomitgd2006/dsh-CalibGuard` | 自动拉取源码并登记到当前 profile 的 bundle |
 | **本地目录路径** | `<你的插件目录>`（例：`D:\code\dsh-calibguard`） | 已 clone / 解压到本地时用 |
-| **包名** | `dsh-calibguard` | ✅ **已发布到 npm**，直接输包名即可（自动装 npm 上的 latest） |
+| **包名** | `dsh-calibguard` 或 `dsh-calibguard@0.3.3` | ✅ **已发布到 npm**；不写版本=装 latest，写 `@版本`=固定版本 |
 
 > 等价命令行（已实测：安装后 DSH 会自动把包加进 profile 的 `dsh.profile.bundles`）：
 >
@@ -191,7 +212,12 @@ AI 能看到完整四档结论与证据；若你说「只审高危文件」，
 - 参数写入 `$DSH_HOME/calibguard-settings.json`（默认 `~/.dsh`，不写进仓库）；
 - **AI 调用同样使用这份设置**（优先级：插件配置 < 共享设置 < 本次调用参数）；
 - 改完立即生效，**不用重启**；
-- API Key 写入 DSH 凭据库（`ctx.credentials`），不落入该设置文件。
+- API Key 写入 DSH 凭据库（`ctx.credentials`），不落入该设置文件；
+- **凭据名**只是"保存位置"的名字（不是密钥本身）：面板里填（如 `DEEPSEEK_API_KEY`）+ API Key，
+  保存后名字记进共享设置的 `credentialRef`，值写进 DSH 凭据库；留空则用插件配置里的 `credentialRef`；
+- **审计结果**：每次审计在引擎的 `reports/` 目录生成 JSON + Markdown（默认 `<engineRoot>/reports`，
+  `engineRoot` 默认 `~/.dsh/calibguard-engine`）。面板结果区会显示该路径并可「清空结果」，
+  条目里的「查看 Markdown 报告」可直接打开。
 
 ### 4) 工具参数（按次覆盖，写给进阶用户）
 
@@ -218,7 +244,7 @@ AI 能看到完整四档结论与证据；若你说「只审高危文件」，
 | `enabled` | `true` | 关掉则什么都不注册（临时停用不必删行） |
 | `engineRoot` | `''` | 引擎目录；留空自动推导：**npm/桌面端安装**时为 `~/.dsh/calibguard-engine`，源码仓库里为本包同级 `CG_GUI` |
 | `device` | `auto` | 自动做「CUDA 版本 + 算力」双检，低算力显卡回落 CPU |
-| `credentialRef` | `''` | 推荐的云端复核凭据引用名，如 `DEEPSEEK_API_KEY`（交给 DSH 凭据库解析） |
+| `credentialRef` | `''` | 云端复核凭据**名**（保存位置，不是密钥），如 `DEEPSEEK_API_KEY`；留空=用面板「凭据名」保存的名字；值存放在 DSH 凭据库/环境变量 |
 | `announceToModel` | `true` | 是否把「何时该用 CalibGuard」写进系统提示词 |
 | `autoSetup` | `true` | 首次运行缺 `.venv` 时**自动**准备引擎（内置代码 + npm 模型分片）、按需下载便携 Python、安装依赖；设 `false` 则只报错提示手动 `node setup.mjs` |
 | `maxFiles` | `20` | 目录展开上限；显式给出/上传的文件不受限 |
@@ -232,8 +258,13 @@ AI 能看到完整四档结论与证据；若你说「只审高危文件」，
 | 侧边栏没有图标 / 面板报 `not found` | 客户端与路由在宿主启动时加载：**重启 DSH** |
 | **首次运行要等十几分钟** | 正常：首次下载模型（约 442 MB，自动镜像回退）并安装依赖（1–3 GB）；面板顶部有进度卡片，只需一次 |
 | 首次审计很慢 | 正常：要加载约 475 MB 权重（之后走常驻进程） |
+| **面板保存 API Key 提示"需要 credentialRef"** | 升级到 ≥ **0.3.3**：面板「凭据名」可直接填写并记住（不用改插件配置）；旧版本请把 `credentialRef` 写进插件配置 |
+| **审计结果保存在哪 / 想清空** | 保存在引擎 `reports/` 目录（默认 `<engineRoot>/reports`），每次审计生成 JSON + Markdown；面板结果区显示路径并带「清空结果」按钮；AI 工具返回 `report_md_path` / `report_json_path` |
+| **审计时总提示"首次会加载模型"** | 0.3.3 起只在模型尚未加载时提示；加载后按钮只显示「审计中…」，顶部状态显示「模型 已加载」 |
+| **有 NVIDIA 显卡（如 RTX 2060）但一直显示 CPU** | 说明装的是 CPU 版 torch（旧版安装器行为）。升级到 ≥0.3.3 后面板会给出提示；在插件目录运行 `node setup.mjs --reinstall-torch`（约 2.5 GB）装上 CUDA 版即可，之后重启 DSH |
+| **想强制用 GPU / CPU 版 torch** | 安装时加 `--force-cuda` / `--cpu`（配合 `--reinstall-torch` 可覆盖已装版本）；运行时设备由插件配置 `device`（auto/cpu/cuda）决定，`cuda` 需要 CUDA 版 torch |
 | 大文件审计几十秒 | 正常：全文滑窗逐窗推理，见 [docs/performance.md](docs/performance.md) |
-| 灰区全部转人工 | 没配凭据：设 `credentialRef`（推荐）或在 DSH Models 页配置 |
+| 灰区全部转人工 | 没配凭据：在面板「凭据名 + API Key」保存，或设 `credentialRef`、或在 DSH Models 页配置 |
 | 正规第三方库被判 BLOCK | 压缩库充满 eval/base64 等特征，模型语料偏 Python 生态 → 属已知误报倾向，见 [docs/troubleshooting.md](docs/troubleshooting.md) |
 | 面板报 401/403 | 浏览器会话未通过宿主鉴权：刷新页面/重新登录 |
 | 改了参数 AI 没变 | 面板里需点「保存」（只改表单不保存 = 仅影响那一次） |

package/bridge/calibguard_bridge.py

@@ -372,7 +372,13 @@ def _op_status(options: dict | None = None) -> dict:
 
     pipeline = _STATE["pipeline"]
     cfg = pipeline.cfg if pipeline is not None else _build_cfg(options)
-    policy = _STATE["device_policy"] or {}
+    policy = dict(_STATE["device_policy"] or {})
+    # 定档说 CUDA、但实际 torch 没启用 CUDA（典型：装的是 CPU 版 torch）→ 如实标注
+    if policy.get("mode") == "cuda" and not cuda_available:
+        policy["mode"] = "cpu"
+        policy["reason"] = (policy.get("reason") or "") + \
+            "；但当前 torch 未启用 CUDA（可能是 CPU 版 torch），实际用 CPU"
+        policy["env"] = "CUDA_VISIBLE_DEVICES 未设置（由 torch 决定）"
     return {
         "engineRoot": root,
         "engineVersion": _engine_version(),

package/cordis.patch.yml

@@ -48,8 +48,9 @@
         # allowThreshold: 0.15
         # blockThreshold: 0.85
         # llmEnabled: false
-        # 【推荐】云端复核凭据：交给 DSH 的 ctx.credentials 解析（继承环境 > 凭据库 > .env）。
-        # 名字写在配置里，插件代码不含硬编码凭据名，也不会隐式继承宿主环境变量。
+        # 【推荐】云端复核凭据名（保存位置，不是密钥）：交给 DSH 的 ctx.credentials 解析（继承环境 > 凭据库 > .env）。
+        # 名字可以写在这里，也可以留空、直接在面板「凭据名」里填（保存后记进共享设置）；
+        # 插件代码不含硬编码凭据名，也不会隐式继承宿主环境变量。
         # credentialRef: DEEPSEEK_API_KEY
         # 备选：直接写字面值（不推荐，凭据会出现在配置文件里）
         # llmApiKey: ''

package/docs/configuration.md

@@ -22,12 +22,18 @@
 | `llmBaseUrl` / `llmModel` | 跟随引擎 | OpenAI 兼容端点与模型名 |
 | `llmContentSource` | 跟随引擎 | 送审内容源：`evidence`（精炼证据）/ `raw`（预处理后全文） |
 | `llmDeliveryMode` | 跟随引擎 | 投递方式：`truncate` / `window` / `all` |
-| `credentialRef` | `''` | **推荐**：DSH 凭据引用名（如 `DEEPSEEK_API_KEY`），交给 `ctx.credentials.resolve()` |
+| `credentialRef` | `''` | **推荐**：凭据**名**（保存位置，不是密钥，如 `DEEPSEEK_API_KEY`），交给 `ctx.credentials.resolve()`。留空时用面板「凭据名」保存进共享设置的名字 |
 | `llmApiKey` | `''` | 字面值 Key（不推荐，会落在配置文件里）；优先于 `credentialRef` |
 | `sensitiveEnvPattern` | `''` | 桥接子进程环境清洗的兜底正则；留空=用 DSH 的实现或内置启发式 |
 | `settingsPath` | `''` | GUI 与 AI 共用的设置文件；留空=`$DSH_HOME/calibguard-settings.json` |
 | `windowStride` | 跟随引擎（256） | 模型侧全文滑窗步长（1~511）。**不在面板/共享设置里**，只走插件配置或工具参数；设 510 时窗口数约减半 |
 
+> **GPU 定档**：安装器检测到 NVIDIA 且 CUDA ≥ 12.8、算力 ≥ 7.5 时自动装 CUDA（cu128）版 torch，
+> 否则装 CPU 版。已经装成 CPU 版时：在插件目录运行 `node setup.mjs --reinstall-torch`。
+> 手动覆盖：`--force-cuda` / `--cpu`（或环境变量）决定**安装哪个 build**；插件配置 `device`
+> （auto/cpu/cuda）决定**运行时用哪个设备**。CPU 版与 CUDA 版 torch 不能共存于同一个 venv
+>（同名包互斥）；CUDA 版在无 GPU 时也能跑 CPU。
+
 ## 二、参数优先级
 
 ```
@@ -40,7 +46,7 @@
 
 ## 三、云端复核的 Key 从哪来（不硬编码、不隐式继承）
 
-1. `credentialRef`（推荐）→ `ctx.credentials.resolve(ref)`，优先级
+1. `credentialRef`（推荐；插件配置或面板「凭据名」两者取其一）→ `ctx.credentials.resolve(ref)`，优先级
    **继承环境 > `~/.dsh/.credentials.yaml` > `<cwd>/.env` > `$DSH_HOME/.env`**；
    解析到的值随请求走 **stdin** 下发，**不进 argv、不进子进程环境变量**，且每次操作重新解析（换 Key 下一次审计即生效）。
 2. `llmApiKey`（字面值，次选）。
@@ -55,17 +61,22 @@
 | 项 | 说明 |
 |---|---|
 | 文件 | `$DSH_HOME/calibguard-settings.json`（默认 `~/.dsh`，**不写进仓库**；可用 `settingsPath` 覆盖） |
-| 内容 | 云端复核开关、Base URL、模型名、送审内容、投递方式、截断/滑窗大小与重叠、灰区上下限、目录上限（**不含凭据、不含模型侧步长**） |
+| 内容 | 云端复核开关、Base URL、模型名、送审内容、投递方式、截断/滑窗大小与重叠、灰区上下限、目录上限、**凭据名 `credentialRef`**（**不含密钥本身、不含模型侧步长**） |
 | 写入 | 面板「保存」→ `PUT /api/calibguard/settings`；原子写，非法值不落盘（校验口径与 CG_GUI 一致） |
 | 读取 | 面板加载时回填；AI 每次调用时由引擎合并，**改完立即生效、无需重启** |
 | 重置 | 面板「重置」→ 清空为「跟随插件配置默认值」 |
-| API Key | 面板输入框 → `PUT /api/calibguard/credential` → 写入 DSH 凭据库，不落设置文件 |
+| API Key | 面板「凭据名 + API Key」→ `PUT /api/calibguard/credential` → 值写入 DSH 凭据库（不落设置文件），名字记入共享设置 `credentialRef`（便于下次启动找到） |
 
 ## 五、环境变量
 
 | 变量 | 作用 |
 |---|---|
 | `DSH_CALIBGUARD_PYTHON` | 指定桥接进程使用的 Python 解释器（优先于 `<engineRoot>/.venv`） |
+| `DSH_CALIBGUARD_CPU_ONLY` | 设为 `1` 强制使用 CPU 版 torch（跳过 GPU 定档） |
+| `DSH_CALIBGUARD_FORCE_CUDA` | 设为 `1` 强制安装 CUDA 版 torch（跳过 CUDA 版本/算力检查，风险自负） |
+| `DSH_CALIBGUARD_DOWNLOAD_CONNECTIONS` | 大文件并发分段下载的连接数（默认 4；模型/引擎包下载提速） |
+| `DSH_CALIBGUARD_TORCH_INDEX` | CUDA 版 torch 的安装索引（默认 `https://download.pytorch.org/whl/cu128`） |
+| `DSH_CALIBGUARD_PIP_INDEX` | 指定 pip 主索引（默认依次尝试 清华 → 阿里 → 中科大 → 腾讯 → 官方） |
 | `DSH_HOME` | DSH 主目录（默认 `~/.dsh`）；决定共享设置文件位置 |
 
 ## 六、宿主 HTTP 路由（浏览器面板使用）

package/docs/troubleshooting.md

@@ -9,6 +9,12 @@
 | 每份文件都 `manual_review` + `CUDA error: no kernel image` | 设备定档失效：确认 `device` 未被强制成 `cuda` |
 | 灰区全部转人工、`llm.status=api_error` | 没配凭据（预期降级）→ 设 `credentialRef`（推荐）或在 DSH Models 页配置 |
 | `凭据引用 X 未配置` 告警 | `credentialRef` 指向的引用在 DSH 凭据库里没有值；在 Models 页填 Key 或用 `llmApiKey` |
+| **面板保存 API Key 报「需要 credentialRef」** | 升级到 ≥0.3.3：面板「凭据名」直接填（如 `DEEPSEEK_API_KEY`）并保存，会记进共享设置；旧版本只能把 `credentialRef` 写进插件配置 |
+| **审计结果在哪里 / 怎么清空** | 引擎 `reports/` 目录（默认 `<engineRoot>/reports`）：每次审计生成 JSON + Markdown；面板结果区显示路径并有「清空结果」，工具返回 `report_md_path` / `report_json_path` |
+| **每次审计都提示"首次会加载模型"** | 0.3.3 起仅在模型未加载时提示；加载后不再出现，顶部状态显示「模型 已加载」 |
+| **有 NVIDIA 显卡但引擎显示 CPU** | 装的是 CPU 版 torch。升级到 ≥0.3.3（面板顶部会提示），然后在插件目录运行 `node setup.mjs --reinstall-torch`（约 2.5 GB）装 CUDA 版；装完重启 DSH。`DSH_CALIBGUARD_CPU_ONLY=1` 可反向强制 CPU |
+| **想强制装 GPU / CPU 版 torch** | 安装时加 `--force-cuda` / `--cpu`（可配合 `--reinstall-torch` 覆盖已装版本）；CPU 版与 CUDA 版不能共存于同一 venv，CUDA 版在无 GPU 时会自动回落 CPU |
+| **首次安装特别慢 / 提示某个源不可用** | 模型默认 4 路并发分段下载（`DSH_CALIBGUARD_DOWNLOAD_CONNECTIONS` 可调），GitHub 失败自动换 gh-proxy/ghfast/ghproxy 镜像；pip 自动在 清华/阿里/中科大/腾讯/官方 之间回退。实在慢可手动下载 `calibguard-model-1.0.0.zip` 放到缓存目录（见下一条） |
 | **模型下载失败 / 想离线** | 手动下载 `calibguard-model-1.0.0.zip`（Release `model-v1.0.0`），解压出 `model.safetensors` 放到 `~/.dsh/calibguard-tools/model-cache/model.safetensors`（或 `<engineRoot>/models/codebert_finetuned/`），重跑安装即会校验 SHA 并跳过下载 |
 | **首次运行卡在"正在准备环境"** | 正常：首次下载模型（约 442 MB，自动镜像回退）+ 装依赖（1–3 GB），约 10–20 分钟；面板顶部有进度与输出尾巴。若长时间无进度，可看 `~/.dsh/calibguard-tools/model-cache` 是否在增长 |
 | 环境准备失败 | 面板会显示失败原因与最后几行输出；在本插件目录跑 `node setup.mjs` 看完整输出后重试（也支持 `--from` 离线包） |

package/lib/client.js

@@ -340,6 +340,11 @@ window.__ModuleLoader__.load({
       var apiKey = apiKeyState[0]
       var setApiKey = apiKeyState[1]
 
+      // 凭据名（保存位置的名字）；留空则用插件配置里的 credentialRef
+      var credNameState = useState('')
+      var credName = credNameState[0]
+      var setCredName = credNameState[1]
+
       var busyState = useState(false)
       var busy = busyState[0]
       var setBusy = busyState[1]
@@ -387,6 +392,7 @@ window.__ModuleLoader__.load({
           writable: Boolean(payload && payload.credentialWritable),
           configured: Boolean(llm.configured),
         })
+        setCredName(function (prev) { return prev || (payload && payload.credentialRef) || '' })
         setForm(function (current) {
           var next = update(current, 'llmEnabled', llm.enabled !== false)
           next = update(next, 'allowThreshold', gate.allowThreshold !== undefined ? gate.allowThreshold : current.allowThreshold)
@@ -448,6 +454,9 @@ window.__ModuleLoader__.load({
         // 只保留「工具参数 / 插件配置」两个入口，避免多一个难懂的概念。
         if (String(form.llmBaseUrl || '').trim()) payload.llmBaseUrl = String(form.llmBaseUrl).trim()
         if (String(form.llmModel || '').trim()) payload.llmModel = String(form.llmModel).trim()
+        // 凭据名（保存位置）由面板填写，也存进共享设置，下次启动审计仍能找到
+        var credentialName = String(credName || '').trim() || (credential.ref || '')
+        if (credentialName) payload.credentialRef = credentialName
 
         apiFetch('/settings', {
           method: 'PUT',
@@ -463,11 +472,13 @@ window.__ModuleLoader__.load({
           return apiFetch('/credential', {
             method: 'PUT',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ apiKey: apiKey }),
-          }).then(function () {
+            body: JSON.stringify({ apiKey: apiKey, name: credentialName }),
+          }).then(function (outcome) {
             setApiKey('')
-            setSettingsMsg('已保存 ✓ 参数共用；API Key 已写入 DSH 凭据库')
+            if (outcome && outcome.credentialRef) setCredName(outcome.credentialRef)
+            setSettingsMsg('已保存 ✓ 参数共用；API Key 已写入 DSH 凭据库（' + ((outcome && outcome.credentialRef) || credentialName) + '）')
             refreshStatus()
+            loadSettings()
           }).catch(function (err) {
             setSettingsMsg('参数已保存，但 API Key 写入失败：' + String((err && err.message) || err))
           })
@@ -536,12 +547,19 @@ window.__ModuleLoader__.load({
         }).then(function (body) {
           setResult(body.result)
           setBusy(false)
+          refreshStatus()
         }).catch(function (err) {
           setBusy(false)
           setError(String((err && err.message) || err))
         })
       }
 
+      function clearResult() {
+        setResult(null)
+        setReport(null)
+        setError('')
+      }
+
       function openReport(name) {
         setReport({ name: name, text: '加载中…' })
         fetch(API + '/report?name=' + encodeURIComponent(name))
@@ -586,12 +604,23 @@ window.__ModuleLoader__.load({
 
       var envInfo = status && status.environment ? status.environment : null
       var engineInfo = status && status.status ? status.status : null
+      var reportDir = (engineInfo && engineInfo.reportDir)
+        || (status && status.settings && status.settings.reportDir)
+        || (result && result.config && result.config.reportDir)
+        || ''
+      var devicePolicy = (engineInfo && engineInfo.devicePolicy) || null
+      var setupScript = (status && status.setupScript) || '<插件目录>/setup.mjs'
+      // 有 NVIDIA 显卡、但 torch 没启用 CUDA（装的是 CPU 版）→ 提示怎么开 GPU
+      var gpuTorchHint = engineInfo && engineInfo.cudaAvailable === false
+        && devicePolicy && devicePolicy.gpuName ? devicePolicy.gpuName : ''
       var engineReady = Boolean(engineInfo)
       var envBusy = Boolean(envInfo) && !engineReady && envInfo.state !== 'failed'
       var envFailed = Boolean(envInfo) && !engineReady && envInfo.state === 'failed'
 
       var statusText = engineInfo
-        ? '引擎就绪：' + engineInfo.device + ' ｜ 阈值 ' + engineInfo.gate.allowThreshold + '/' + engineInfo.gate.blockThreshold
+        ? '引擎就绪：' + engineInfo.device
+          + ' ｜ 模型 ' + (engineInfo.loaded ? '已加载' : '待加载')
+          + ' ｜ 阈值 ' + engineInfo.gate.allowThreshold + '/' + engineInfo.gate.blockThreshold
           + ' ｜ 云端复核 ' + (engineInfo.llm.enabled ? (engineInfo.llm.configured ? '可用' : '已启用但无凭据') : '关闭')
         : (envFailed ? '环境准备失败' : (envBusy ? '首次运行：正在准备引擎与依赖…' : '状态读取中…'))
 
@@ -609,6 +638,23 @@ window.__ModuleLoader__.load({
               ],
             }),
             statusError ? jsx('div', { style: S.err, children: statusError }) : null,
+            engineInfo && devicePolicy && devicePolicy.reason
+              ? jsx('div', {
+                style: S.muted,
+                children: '推理设备：' + engineInfo.device
+                  + (devicePolicy.gpuName ? '（' + devicePolicy.gpuName + '）' : '')
+                  + ' ｜ ' + devicePolicy.reason,
+              })
+              : null,
+            gpuTorchHint
+              ? jsx('div', {
+                style: S.note,
+                children: '检测到 NVIDIA ' + gpuTorchHint + '，但当前 torch 是 CPU 版，审计会走 CPU。'
+                  + '要启用 GPU（RTX 20/30/40 系需算力 ≥7.5 且 CUDA ≥12.8）：'
+                  + '在插件目录运行 node "' + setupScript + '" --reinstall-torch（约 2.5 GB），'
+                  + '装完重启 DSH；或重装插件到最新版会自动选 CUDA 版 torch。',
+              })
+              : null,
 
             // ---------- 首次运行：自动准备环境（对齐 CG_GUI 首启装环境） ----------
             envInfo && !engineReady
@@ -676,6 +722,21 @@ window.__ModuleLoader__.load({
                 jsxs('div', {
                   style: Object.assign({}, S.group, llmOn ? null : S.groupOff),
                   children: [
+                    jsxs('label', {
+                      style: S.field,
+                      children: [
+                        jsx('span', { style: S.label, children: '凭据名（保存位置的名字，不是密钥）' }),
+                        jsx('input', {
+                          style: S.input,
+                          type: 'text',
+                          autoComplete: 'off',
+                          placeholder: credential.ref || 'DEEPSEEK_API_KEY',
+                          value: credName,
+                          disabled: !llmOn,
+                          onChange: function (event) { setCredName(event.target.value) },
+                        }),
+                      ],
+                    }),
                     jsxs('label', {
                       style: S.field,
                       children: [
@@ -686,7 +747,7 @@ window.__ModuleLoader__.load({
                           autoComplete: 'off',
                           placeholder: credential.configured
                             ? '已配置（留空表示不修改）'
-                            : (credential.ref ? '未配置，填入后保存到 DSH 凭据库' : '需插件配置 credentialRef 后才能保存'),
+                            : '未配置，填入后点「保存」写入 DSH 凭据库',
                           value: apiKey,
                           disabled: !llmOn,
                           onChange: function (event) { setApiKey(event.target.value) },
@@ -879,7 +940,9 @@ window.__ModuleLoader__.load({
                 jsx('div', {
                   style: S.note,
                   children: '设置保存在本地 ' + (settingsFile || '$DSH_HOME/calibguard-settings.json')
-                    + '（GUI 与 AI 工具共用）；API Key 写入 DSH 凭据库，不落此文件。',
+                    + '（GUI 与 AI 工具共用）；API Key 写入 DSH 凭据库，不落此文件。'
+                    + '「凭据名」只是保存位置的名字（可留空=用插件配置 credentialRef）；'
+                    + '审计结果（JSON + Markdown）保存在引擎的 reports 目录，见下方「审计结果」。',
                 }),
                 jsxs('div', {
                   style: S.row,
@@ -968,18 +1031,40 @@ window.__ModuleLoader__.load({
                         busy || !engineReady ? { opacity: 0.6, cursor: 'default' } : null),
                       onClick: busy || !engineReady ? function () {} : run,
                       children: busy
-                        ? '审计中…（首次会加载模型）'
+                        ? '审计中…' + (engineInfo && engineInfo.loaded === false ? '（首次会加载模型）' : '')
                         : (!engineReady ? '环境准备完成后可审计' : '开始审计'),
                     }),
                     jsx('span', { style: S.muted, children: '使用上面「设置」里保存的参数（与 AI 工具一致）' }),
                   ],
                 }),
+                engineReady && reportDir
+                  ? jsx('div', {
+                    style: S.muted,
+                    children: '审计结果（JSON + Markdown）保存到：' + reportDir,
+                  })
+                  : null,
               ],
             }),
 
             error ? jsx('div', { style: S.err, children: error }) : null,
 
             // ---------- 结果 ----------
+            result
+              ? jsxs('div', {
+                style: S.row,
+                children: [
+                  jsx('div', { style: S.cardTitle, children: '审计结果' }),
+                  jsx('button', { style: S.button, onClick: clearResult, children: '清空结果' }),
+                ],
+              })
+              : null,
+            result && reportDir
+              ? jsx('div', {
+                style: S.muted,
+                children: '结果文件保存在：' + reportDir
+                  + '（每次审计生成 JSON + Markdown；点条目里的「查看 Markdown 报告」可直接打开）',
+              })
+              : null,
             summary
               ? jsxs('div', {
                 style: S.summary,

package/lib/engine.js

@@ -11,7 +11,7 @@
  * 凭据（**零硬编码**）：
  *   - 子进程环境经 `buildChildEnv()` 清洗：`*KEY*` / `*PASSWORD*` / `*SECRET*` / `*TOKEN*`
  *     与 `DSH_*` 一律不传，与 DSH 自己的 `scrubbedParentEnv()` 同源（能导入就直接用它的）；
- *   - 云端复核 Key 的唯一来源是配置：`llmApiKey`（字面值）或 `credentialRef`
+ *   - 云端复核 Key 的来源：`llmApiKey`（字面值）或 `credentialRef`（插件配置，或面板「凭据名」保存进共享设置）
  *     （交给 `ctx.credentials.resolve()` 解析，优先级 env > 凭据库 > .env，随 DSH 策略演进）；
  *   - 解析结果**每次操作重新解析**（凭据轮换即时生效），并只通过 subprocess 的 stdin
  *     私有管道随请求下发 —— 不进 argv（进程列表可见）、不进子进程环境变量。
@@ -124,14 +124,25 @@ export class CalibGuardEngine {
 
   // ============================== 凭据解析 ==============================
 
+  /**
+   * 生效的凭据名：插件配置 `credentialRef` 优先，其次是面板保存进共享设置的 `credentialRef`。
+   * 两者都只是"名字"，值在 DSH 凭据库/环境里，不会进配置文件。
+   */
+  effectiveCredentialRef() {
+    const fromConfig = typeof this.config.credentialRef === 'string' ? this.config.credentialRef.trim() : ''
+    if (fromConfig) return fromConfig
+    const fromSettings = this.settings()?.credentialRef
+    return typeof fromSettings === 'string' ? fromSettings.trim() : ''
+  }
+
   /**
    * 解析云端复核使用的 Key。**每次操作都重新解析**，因此凭据轮换无需重启进程。
    *
    * 顺序：
    *   1. `config.llmApiKey`（配置里的字面值，最低推荐度）；
-   *   2. `config.credentialRef` → `ctx.credentials.resolve(ref)`（DSH 的分层解析：
+   *   2. 生效的 `credentialRef` → `ctx.credentials.resolve(ref)`（DSH 的分层解析：
    *      继承环境 > 凭据库 > .env 文件，具体层由来源 `source` 报告）；
-   *   3. 若凭据服务不可用，则按同名环境变量读取（名字来自配置，不是硬编码）。
+   *   3. 若凭据服务不可用，则按同名环境变量读取（名字来自配置/面板，不是硬编码）。
    *
    * @returns {Promise<{key: string|undefined, source: string}>}
    */
@@ -142,7 +153,7 @@ export class CalibGuardEngine {
       return { key: config.llmApiKey, source: this.lastCredential.source }
     }
 
-    const ref = config.credentialRef
+    const ref = this.effectiveCredentialRef()
     if (!ref) {
       this.lastCredential = { source: 'none', configured: false }
       return { key: undefined, source: 'none' }
@@ -182,17 +193,29 @@ export class CalibGuardEngine {
    * @param {string} value API Key
    * @returns {Promise<{ref: string, saved: boolean}>}
    */
-  async setCredential(value) {
+  async setCredential(value, name) {
     if (typeof value !== 'string' || value.trim() === '') throw new Error('API Key 不能为空')
-    const ref = this.config.credentialRef
+    const requested = typeof name === 'string' ? name.trim() : ''
+    if (requested && !/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(requested)) {
+      throw new Error('凭据名不合法：只允许字母/数字/下划线，且以字母或下划线开头（如 DEEPSEEK_API_KEY）')
+    }
+    const ref = requested || this.effectiveCredentialRef()
     if (!ref) {
-      throw new Error('未配置 credentialRef：请在插件配置里指定凭据名（如 DEEPSEEK_API_KEY），'
-        + '或改用 DSH 的 Models 页配置 Key')
+      throw new Error('还没有凭据名：请在面板「凭据名」里填一个（如 DEEPSEEK_API_KEY），'
+        + '或在插件配置里设置 credentialRef。凭据名不是密钥本身，只是"保存位置"的名字。')
     }
     if (typeof this.credentials?.set !== 'function') {
-      throw new Error('当前环境不支持写入凭据库：请在 DSH Models 页配置，或用插件配置 llmApiKey')
+      throw new Error('当前环境不支持写入 DSH 凭据库：请在 DSH Models 页配置 Key，或用插件配置 llmApiKey')
     }
     await this.credentials.set(ref, value.trim())
+    // 记住这个名字（只存名字，不存密钥），下次启动后审计仍能找到它
+    if (this.settingsStore) {
+      try {
+        this.settingsStore.save({ ...this.settings(), credentialRef: ref })
+      } catch (error) {
+        this.logger?.warn?.(`[calibguard] 记住凭据名失败（不影响本次写入）：${error?.message ?? error}`)
+      }
+    }
     this.lastCredential = { source: 'credentials:set', configured: true }
     this.logger?.info?.(`[calibguard] 已写入凭据引用 ${ref}（值不落日志）`)
     return { ref, saved: true }
@@ -207,6 +230,8 @@ export class CalibGuardEngine {
    */
   async #prepare(options) {
     const merged = { ...this.baseOptions, ...this.settings(), ...options }
+    // credentialRef 是本插件 Node 侧的配置，不下发给桥接进程
+    delete merged.credentialRef
     if (!merged.llmApiKey) {
       const { key } = await this.resolveCredential()
       if (key) merged.llmApiKey = key
@@ -475,7 +500,7 @@ export class CalibGuardEngine {
       pendingRequests: this.pending.size,
       lastExit: this.lastExit,
       credential: { ...this.lastCredential },
-      credentialRef: this.config.credentialRef || null,
+      credentialRef: this.effectiveCredentialRef() || null,
       credentialWritable: typeof this.credentials?.set === 'function',
       environment: this.bootstrap.snapshot(),
       settings: this.settings(),

package/lib/routes.js

@@ -130,6 +130,9 @@ export function createCalibGuardRoutes({ engine, config, logger, settingsStore }
     }
   }
 
+  /** 面板提示用：`node <setupScript> --reinstall-torch` 的绝对路径。 */
+  const setupScript = join(config.packageRoot ?? '', 'setup.mjs')
+
   /** GET /status */
   async function handleStatus(req, res) {
     if (req.method !== 'GET') return sendJson(res, 405, { error: '仅支持 GET' })
@@ -145,6 +148,7 @@ export function createCalibGuardRoutes({ engine, config, logger, settingsStore }
           credential: diagnostics.credential,
           credentialRef: diagnostics.credentialRef ?? null,
           credentialWritable: Boolean(diagnostics.credentialWritable),
+          setupScript,
           settings: engine.settings(),
           settingsFile: settingsStore?.file ?? null,
         })
@@ -158,6 +162,7 @@ export function createCalibGuardRoutes({ engine, config, logger, settingsStore }
         credential: diagnostics.credential,
         credentialRef: diagnostics.credentialRef ?? null,
         credentialWritable: Boolean(diagnostics.credentialWritable),
+        setupScript,
         settings: engine.settings(),
         settingsFile: settingsStore?.file ?? null,
       })
@@ -174,6 +179,7 @@ export function createCalibGuardRoutes({ engine, config, logger, settingsStore }
           credential: diagnostics.credential,
           credentialRef: diagnostics.credentialRef ?? null,
           credentialWritable: Boolean(diagnostics.credentialWritable),
+          setupScript,
           settings: engine.settings(),
           settingsFile: settingsStore?.file ?? null,
         })
@@ -196,10 +202,14 @@ export function createCalibGuardRoutes({ engine, config, logger, settingsStore }
       }
       const apiKey = typeof payload?.apiKey === 'string' ? payload.apiKey : ''
       if (!apiKey.trim()) return sendJson(res, 400, { error: 'apiKey 不能为空' })
+      // 凭据名可以由面板填写（不写死在代码里）；留空则用插件配置里的 credentialRef
+      const name = typeof payload?.name === 'string' ? payload.name.trim() : ''
       if (typeof engine.setCredential !== 'function') {
         return sendJson(res, 503, { error: '当前插件版本不支持写入凭据' })
       }
-      const result = await engine.setCredential(apiKey)
+      const result = await engine.setCredential(apiKey, name || undefined)
+      const ref = result && result.ref ? result.ref : null
+      sendJson(res, 200, { ok: true, ...result, credentialRef: ref, settings: engine.settings() })
       sendJson(res, 200, { ok: true, ...result })
     } catch (error) {
       sendJson(res, 400, { error: String(error?.message ?? error) })

package/lib/settings.js

@@ -33,6 +33,8 @@ export const SETTINGS_KEYS = [
   'llmWindowChars',
   'llmWindowOverlap',
   'maxFiles',
+  // 凭据名（保存位置的名字，不是密钥本身）。只在本插件 Node 侧使用，不会下发给桥接进程。
+  'credentialRef',
 ]
 
 /** DSH home：优先环境变量，其次 `~/.dsh`。 */
@@ -69,6 +71,12 @@ export function validateSettings(raw) {
     throw new Error('设置必须是 JSON 对象')
   }
   const picked = pickSettings(raw ?? {})
+  if (picked.credentialRef !== undefined) {
+    if (typeof picked.credentialRef !== 'string'
+      || !/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(picked.credentialRef)) {
+      throw new Error('credentialRef 必须是合法凭据名（字母/数字/下划线，且以字母或下划线开头，如 DEEPSEEK_API_KEY）')
+    }
+  }
   validateAuditOptions(picked)
   return picked
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-calibguard",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "publishConfig": {
     "access": "public"
   },

package/setup.mjs

@@ -28,14 +28,22 @@ import { spawn, spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { homedir } from 'node:os'
 import { Readable } from 'node:stream'
+import { pipeline as streamPipeline } from 'node:stream/promises'
 
 const PKG_ROOT = dirname(fileURLToPath(import.meta.url))
 /** torch 官方轮子目前覆盖的 Python 版本上限（3.13/3.14 装不上 torch）。 */
 const PY_MIN = 10
 const PY_MAX = 12
 
-/** 引擎下载的镜像前缀：GitHub 直连失败时依次重试。 */
-const ENGINE_MIRRORS = ['https://gh-proxy.com/', 'https://ghfast.top/', 'https://ghproxy.cn/']
+/** 引擎/模型下载的镜像前缀：GitHub 直连失败时依次重试（均实测支持 Range 分段）。 */
+const ENGINE_MIRRORS = ['https://gh-proxy.com/', 'https://ghfast.top/', 'https://ghproxy.net/']
+
+/** CUDA 版 torch（与 CG_GUI launcher 相同的定档口径）。 */
+const TORCH_CUDA_INDEX = process.env.DSH_CALIBGUARD_TORCH_INDEX || 'https://download.pytorch.org/whl/cu128'
+const CUDA_MIN = [12, 8]
+const CUDA_MIN_COMPUTE_CAP = [7, 5]
+/** 并发分段下载的段数（0/负数 = 单连接）。 */
+const DOWNLOAD_CONNECTIONS = Number(process.env.DSH_CALIBGUARD_DOWNLOAD_CONNECTIONS || 4)
 /** pip 索引：默认清华镜像，失败回退官方 PyPI。 */
 const DEFAULT_PIP_INDEX = 'https://pypi.tuna.tsinghua.edu.cn/simple'
 const OFFICIAL_PIP_INDEX = 'https://pypi.org/simple'
@@ -71,10 +79,94 @@ function mirroredUrls(url) {
   return urls
 }
 
-/** pip 索引候选（自定义 → 清华镜像 → 官方源）。 */
+/** pip 索引候选（自定义 → 清华 → 阿里 → 中科大 → 腾讯 → 官方）。 */
 function pipIndexes() {
   const custom = String(process.env.DSH_CALIBGUARD_PIP_INDEX || process.env.PIP_INDEX_URL || '').trim()
-  return [...new Set([custom, DEFAULT_PIP_INDEX, OFFICIAL_PIP_INDEX].filter(Boolean))]
+  return [...new Set([
+    custom,
+    DEFAULT_PIP_INDEX,
+    'https://mirrors.aliyun.com/pypi/simple/',
+    'https://pypi.mirrors.ustc.edu.cn/simple/',
+    'https://mirrors.cloud.tencent.com/pypi/simple',
+    OFFICIAL_PIP_INDEX,
+  ].filter(Boolean))]
+}
+
+/** 比较版本元组：[a,b] vs [c,d]。 */
+function cmpVersion(a, b) {
+  return (a[0] - b[0]) || ((a[1] ?? 0) - (b[1] ?? 0))
+}
+
+function fmtVersion(version) {
+  return Array.isArray(version) ? version.slice(0, 2).join('.') : '未知'
+}
+
+/** 用 nvidia-smi 探测 GPU：返回 { hasNvidia, gpuName, computeCap, cudaVersion }。 */
+function detectGpu() {
+  const probe = (args) => {
+    const result = spawnSync('nvidia-smi', args, { encoding: 'utf8', timeout: 20_000 })
+    if (result.error || result.status !== 0) return ''
+    return String(result.stdout || '').trim()
+  }
+  const csv = probe(['--query-gpu=name,compute_cap', '--format=csv,noheader'])
+  if (!csv) return { hasNvidia: false, gpuName: null, computeCap: null, cudaVersion: null }
+  const first = csv.split(/\r?\n/)[0] || ''
+  const parts = first.split(',').map((item) => item.trim())
+  const gpuName = parts[0] || null
+  let computeCap = null
+  if (parts[1] && /^\d+\.\d+$/.test(parts[1])) {
+    computeCap = parts[1].split('.').map(Number)
+  }
+  const header = probe([])
+  const match = /CUDA Version:\s*(\d+)\.(\d+)/.exec(header)
+  const cudaVersion = match ? [Number(match[1]), Number(match[2])] : null
+  return { hasNvidia: true, gpuName, computeCap, cudaVersion }
+}
+
+/**
+ * 是否需要安装 CUDA 版 torch。
+ * 优先级（高 → 低）：--cpu / DSH_CALIBGUARD_CPU_ONLY=1 ＞ --force-cuda / DSH_CALIBGUARD_FORCE_CUDA=1
+ * ＞ auto（CG_GUI launcher 同款「CUDA 版本 + 算力」双检）。
+ * 说明：CUDA 版 torch 在没有 GPU 时也能正常跑 CPU，所以「强制 CUDA」只是安装时跳过兼容性检查；
+ * 风险：cu128 轮子里没有该显卡算力的 kernel 时，运行期会回落 CPU 或报错（自担）。
+ */
+function decideCudaTorch(gpu, options = {}) {
+  if (options.forceCpu || String(process.env.DSH_CALIBGUARD_CPU_ONLY || '') === '1') {
+    return { useCuda: false, reason: options.forceCpu ? '--cpu 指定' : 'DSH_CALIBGUARD_CPU_ONLY=1，强制 CPU' }
+  }
+  if (options.forceCuda || String(process.env.DSH_CALIBGUARD_FORCE_CUDA || '') === '1') {
+    return {
+      useCuda: true,
+      forced: true,
+      reason: options.forceCuda
+        ? '--force-cuda 显式强制（跳过 CUDA/算力检查，风险自负）'
+        : 'DSH_CALIBGUARD_FORCE_CUDA=1 强制（跳过 CUDA/算力检查，风险自负）',
+    }
+  }
+  if (!gpu.hasNvidia) return { useCuda: false, reason: '未检测到 NVIDIA 显卡（nvidia-smi 不可用）' }
+  if (!gpu.cudaVersion || cmpVersion(gpu.cudaVersion, CUDA_MIN) < 0) {
+    return {
+      useCuda: false,
+      reason: `CUDA 版本 ${fmtVersion(gpu.cudaVersion)} < ${fmtVersion(CUDA_MIN)}（或无法探测）`,
+    }
+  }
+  if (gpu.computeCap && cmpVersion(gpu.computeCap, CUDA_MIN_COMPUTE_CAP) < 0) {
+    return {
+      useCuda: false,
+      reason: `算力 ${fmtVersion(gpu.computeCap)} < ${fmtVersion(CUDA_MIN_COMPUTE_CAP)}（cu128 轮子无对应 kernel）`,
+    }
+  }
+  return { useCuda: true, reason: `算力 ${fmtVersion(gpu.computeCap)} ｜ CUDA ${fmtVersion(gpu.cudaVersion)}` }
+}
+
+/** 已安装 torch 的 CUDA 版本（空串 = CPU 版；null = 未安装/无法导入）。 */
+function installedTorchCuda(python) {
+  const result = spawnSync(python, ['-c', 'import torch;print(torch.version.cuda or "")'], {
+    encoding: 'utf8',
+    timeout: 180_000,
+  })
+  if (result.error || result.status !== 0) return null
+  return String(result.stdout || '').trim()
 }
 
 /** 插件内置引擎目录：CG_GUI 核心文件（代码 / 词表 / 校准参数），不含 476 MB 模型权重。 */
@@ -122,7 +214,7 @@ async function fetchModelWeights(dest) {
     for (const url of mirroredUrls(MODEL_URL)) {
       try {
         log(`下载模型权重（约 442 MB）：${url}`)
-        await download(url, zipPath)
+        await downloadParallel(url, zipPath)
         const size = statSync(zipPath).size
         if (size < MODEL_ZIP_MIN_BYTES) {
           throw new SetupError(`下载内容异常（${bytes(size)}，预期约 442 MB，可能是镜像错误页）`)
@@ -233,6 +325,9 @@ function parseArgs(argv) {
     force: false,
     noPortablePython: false,
     forcePortablePython: false,
+    reinstallTorch: false,
+    forceCuda: false,
+    forceCpu: false,
     help: false,
   }
   for (let i = 0; i < argv.length; i += 1) {
@@ -255,6 +350,9 @@ function parseArgs(argv) {
       case '--force': options.force = true; break
       case '--no-portable-python': options.noPortablePython = true; break
       case '--force-portable-python': options.forcePortablePython = true; break
+      case '--reinstall-torch': options.reinstallTorch = true; break
+      case '--force-cuda': options.forceCuda = true; break
+      case '--cpu': options.forceCpu = true; break
       default: fail(`未知参数：${arg}（用 --help 查看用法）`)
     }
   }
@@ -280,6 +378,9 @@ function printHelp() {
   --force           覆盖已有引擎目录 / 重建 venv
   --no-portable-python  本机没有 Python 时不自动下载便携版（默认会自动下载）
   --force-portable-python  跳过本机 Python 检测，强制用便携版（测试用）
+  --reinstall-torch 重新安装 torch（检测到 NVIDIA 时装 CUDA/cu128 版，约 2.5 GB）
+  --force-cuda      安装时强制选 CUDA 版 torch（跳过 CUDA版本/算力检查，风险自负）
+  --cpu             安装时强制选 CPU 版 torch
   -h, --help        显示本帮助
 
 示例：
@@ -297,8 +398,13 @@ function printHelp() {
   • pip 默认用清华镜像（pypi.tuna.tsinghua.edu.cn），失败自动回退官方 PyPI；
     可用 DSH_CALIBGUARD_PIP_INDEX 指定其它索引；
   • 从 npm 安装时引擎默认放在 ~/.dsh/calibguard-engine（可用 --dest 或插件配置 engineRoot 指定）；
-  • 默认用 CPU 版 torch（低算力显卡本来也会被定档到 CPU）；
-    要用 GPU 请按 PyTorch 官网自行安装对应 CUDA 轮子。
+  • GPU 自动定档：检测到 NVIDIA 且 CUDA≥12.8、算力≥7.5（如 RTX 20/30/40 系）时
+    自动安装 CUDA（cu128）版 torch；否则用 CPU 版；
+    - 手动覆盖：--force-cuda（强制 GPU 版）/ --cpu（强制 CPU 版），
+      或环境变量 DSH_CALIBGUARD_FORCE_CUDA=1 / DSH_CALIBGUARD_CPU_ONLY=1；
+    - CUDA 版 torch 在无 GPU 时也能跑 CPU，两者**不能同时装在同一个 venv**（同名包互斥）；
+  • 大文件（模型/引擎包）默认 4 路并发分段下载，可用 DSH_CALIBGUARD_DOWNLOAD_CONNECTIONS 调整；
+  • 装完想换 GPU/CPU 版 torch：node setup.mjs --reinstall-torch。
 `)
 }
 
@@ -410,6 +516,119 @@ async function download(url, file) {
   log(`下载完成：${bytes(received)}（用时 ${Math.round((Date.now() - startedAt) / 1000)} 秒）`)
 }
 
+/** 下载一个区间的分片（支持断点续传/重试）。 */
+async function downloadRange(url, file, start, end, { attempts = 3, idleMs = 120_000 } = {}) {
+  const total = end - start + 1
+  let lastError = null
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const offset = existsSync(file) ? statSync(file).size : 0
+    if (offset >= total) return
+    const controller = new AbortController()
+    let idleTimer = null
+    const resetIdle = () => {
+      if (idleTimer) clearTimeout(idleTimer)
+      idleTimer = setTimeout(() => controller.abort(new Error(`${Math.round(idleMs / 1000)} 秒没有收到数据`)), idleMs)
+    }
+    let response
+    try {
+      resetIdle()
+      response = await fetch(url, {
+        redirect: 'follow',
+        signal: controller.signal,
+        headers: { Range: `bytes=${start + offset}-${end}` },
+      })
+    } catch (error) {
+      if (idleTimer) clearTimeout(idleTimer)
+      lastError = error
+      warn(`分片 ${start}-${end} 第 ${attempt} 次失败：${error.message}`)
+      continue
+    }
+    if (response.status !== 206 && !(response.status === 200 && offset === 0 && start === 0)) {
+      if (idleTimer) clearTimeout(idleTimer)
+      lastError = new SetupError(`分片请求返回 HTTP ${response.status}`)
+      continue
+    }
+    const sink = createWriteStream(file, { flags: offset > 0 ? 'a' : 'w' })
+    const reader = Readable.fromWeb(response.body)
+    try {
+      await new Promise((resolvePromise, rejectPromise) => {
+        reader.on('data', (chunk) => { resetIdle() })
+        reader.on('error', (error) => { clearTimeout(idleTimer); rejectPromise(error) })
+        sink.on('error', (error) => { clearTimeout(idleTimer); rejectPromise(error) })
+        sink.on('finish', () => { clearTimeout(idleTimer); resolvePromise() })
+        reader.pipe(sink)
+      })
+    } catch (error) {
+      lastError = error
+      warn(`分片 ${start}-${end} 第 ${attempt} 次中断：${error.message}（已保留断点）`)
+      continue
+    }
+    if (statSync(file).size >= total) return
+    lastError = new SetupError('分片下载不完整')
+  }
+  throw new SetupError(`分片 ${start}-${end} 下载失败：${lastError?.message ?? '未知错误'}`)
+}
+
+/**
+ * 并发分段下载（大幅提升 GitHub/镜像的单连接限速场景）。
+ * 先探测是否支持 Range；不支持或文件不够大时自动退回单连接 download()。
+ */
+async function downloadParallel(url, file, { connections = DOWNLOAD_CONNECTIONS } = {}) {
+  if (!connections || connections < 2) return download(url, file)
+  let total = 0
+  let supportsRange = false
+  try {
+    const probe = await fetch(url, {
+      redirect: 'follow',
+      headers: { Range: 'bytes=0-0' },
+      signal: AbortSignal.timeout(60_000),
+    })
+    if (probe.ok) {
+      supportsRange = probe.status === 206
+      const contentRange = probe.headers.get('content-range') || ''
+      const sizePart = contentRange.split('/')[1]
+      total = Number(sizePart || probe.headers.get('content-length') || 0)
+      try { await probe.arrayBuffer() } catch { /* 忽略探测体 */ }
+    }
+  } catch {
+    supportsRange = false
+  }
+  if (!supportsRange || !(total > 0) || total < 32 * 1024 ** 2) return download(url, file)
+
+  const chunk = Math.ceil(total / connections)
+  const parts = []
+  for (let index = 0; index < connections; index += 1) {
+    const start = index * chunk
+    const end = Math.min(total - 1, start + chunk - 1)
+    if (start > end) break
+    parts.push({ start, end, file: `${file}.part${index}`, percent: 0 })
+  }
+  log(`分段并发下载：${parts.length} 路，共 ${bytes(total)}（单连接慢时明显提速）`)
+  const startedAt = Date.now()
+  let finished = 0
+  await Promise.all(parts.map(async (part) => {
+    await downloadRange(url, part.file, part.start, part.end)
+    finished += 1
+    log(`  分片 ${finished}/${parts.length} 完成（${bytes(statSync(part.file).size)}）`)
+  }))
+  log(`分段下载完成：${bytes(total)}（用时 ${Math.round((Date.now() - startedAt) / 1000)} 秒），开始合并…`)
+  const temp = `${file}.merging`
+  deleteFile(temp)
+  await streamPipeline((async function* generate() {
+    for (const part of parts) {
+      for await (const chunkData of createReadStream(part.file)) yield chunkData
+    }
+  })(), createWriteStream(temp))
+  for (const part of parts) deleteFile(part.file)
+  if (statSync(temp).size !== total) {
+    deleteFile(temp)
+    throw new SetupError(`合并后大小不符：${bytes(statSync(temp).size)} / ${bytes(total)}`)
+  }
+  deleteFile(file)
+  renameSync(temp, file)
+  log(`✓ 分段下载合并完成：${file}（${bytes(statSync(file).size)}）`)
+}
+
 // ============================== 解压 ==============================
 
 function extract(zipFile, dest) {
@@ -688,7 +907,7 @@ async function main() {
         let lastError = null
         for (const candidate of candidates) {
           try {
-            await download(candidate, downloadedZip)
+            await downloadParallel(candidate, downloadedZip)
             if (statSync(downloadedZip).size < 100 * 1024 ** 2) {
               throw new SetupError('下载内容明显偏小，可能是镜像错误页')
             }
@@ -804,7 +1023,43 @@ async function main() {
       throw lastError ?? new SetupError('pip 安装失败')
     }
     await installWithMirrors(['--upgrade', 'pip', '--quiet'])
-    await installWithMirrors(['-r', requirements])
+
+    // GPU 定档：有可用 NVIDIA（CUDA≥12.8、算力≥7.5）时先装 CUDA 版 torch，
+    // 与 CG_GUI launcher 的口径一致；否则装 CPU 版 torch。
+    const gpu = detectGpu()
+    const decision = decideCudaTorch(gpu, options)
+    if (decision.forced && !gpu.hasNvidia) {
+      warn('强制 CUDA 但未检测到 NVIDIA 显卡：torch 会安装成功，但运行期仍会回落 CPU。')
+    }
+    const gpuLabel = gpu.gpuName ? `（${gpu.gpuName}）` : ''
+    log(`GPU 定档：${decision.useCuda ? 'CUDA（cu128）' : 'CPU'} —— ${decision.reason}${gpuLabel}`)
+    const existingTorchCuda = installedTorchCuda(python)
+    if (decision.useCuda && (!existingTorchCuda || options.reinstallTorch)) {
+      step(`安装 CUDA 版 torch（cu128，约 2.5 GB${existingTorchCuda ? '，重装' : ''}）`)
+      if (options.reinstallTorch) {
+        try {
+          await runLive(python, ['-m', 'pip', 'uninstall', '-y', 'torch'])
+        } catch { /* 未安装则忽略 */ }
+      }
+      try {
+        await runLive(python, [
+          '-m', 'pip', 'install', 'torch', '--index-url', TORCH_CUDA_INDEX,
+          '--timeout', '300', '--retries', '3',
+        ])
+      } catch (error) {
+        warn(`CUDA 版 torch 安装失败（${error.message}），回退 CPU 版 torch`)
+      }
+    } else if (existingTorchCuda) {
+      log(`✓ 已安装 CUDA 版 torch（CUDA ${existingTorchCuda}）`)
+    }
+
+    await installWithMirrors(['-r', requirements, '--prefer-binary'])
+    const finalTorchCuda = installedTorchCuda(python)
+    log(`torch CUDA：${finalTorchCuda || '无（CPU 版）'}`)
+    if (decision.useCuda && !finalTorchCuda) {
+      warn('当前 torch 是 CPU 版：审计仍可运行，只是用 CPU。'
+        + '可重跑：node setup.mjs --reinstall-torch（或 --force-cuda 跳过兼容性检查）')
+    }
     log('✓ 依赖安装完成')
   }