dsh-calibguard 0.3.3 → 0.3.4

package/README.en.md

@@ -77,6 +77,15 @@ mirrors, and pip tries Tsinghua → Aliyun → USTC → Tencent → PyPI in orde
 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**
@@ -268,6 +277,7 @@ Common keys of the loader row `config` (full table: [docs/configuration.md](docs
 | **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

@@ -70,6 +70,15 @@ GitHub 直连失败会自动换 gh-proxy / ghfast / ghproxy 镜像；pip 依赖
 **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 源），只需一次。
@@ -253,6 +262,7 @@ AI 能看到完整四档结论与证据；若你说「只审高危文件」，
 | **审计结果保存在哪 / 想清空** | 保存在引擎 `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) |
 | 灰区全部转人工 | 没配凭据：在面板「凭据名 + API Key」保存，或设 `credentialRef`、或在 DSH Models 页配置 |
 | 正规第三方库被判 BLOCK | 压缩库充满 eval/base64 等特征，模型语料偏 Python 生态 → 属已知误报倾向，见 [docs/troubleshooting.md](docs/troubleshooting.md) |

package/docs/configuration.md

@@ -30,6 +30,9 @@
 
 > **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。
 
 ## 二、参数优先级
 
@@ -70,6 +73,7 @@
 |---|---|
 | `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 主索引（默认依次尝试 清华 → 阿里 → 中科大 → 腾讯 → 官方） |

package/docs/troubleshooting.md

@@ -13,6 +13,7 @@
 | **审计结果在哪里 / 怎么清空** | 引擎 `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` 是否在增长 |

package/package.json

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

package/setup.mjs

@@ -123,10 +123,25 @@ function detectGpu() {
   return { hasNvidia: true, gpuName, computeCap, cudaVersion }
 }
 
-/** 是否需要安装 CUDA 版 torch（与 CG_GUI launcher 同款「CUDA 版本 + 算力」双检）。 */
-function decideCudaTorch(gpu) {
-  if (String(process.env.DSH_CALIBGUARD_CPU_ONLY || '') === '1') {
-    return { useCuda: false, reason: 'DSH_CALIBGUARD_CPU_ONLY=1，强制 CPU' }
+/**
+ * 是否需要安装 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) {
@@ -311,6 +326,8 @@ function parseArgs(argv) {
     noPortablePython: false,
     forcePortablePython: false,
     reinstallTorch: false,
+    forceCuda: false,
+    forceCpu: false,
     help: false,
   }
   for (let i = 0; i < argv.length; i += 1) {
@@ -334,6 +351,8 @@ function parseArgs(argv) {
       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 查看用法）`)
     }
   }
@@ -360,6 +379,8 @@ function printHelp() {
   --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        显示本帮助
 
 示例：
@@ -378,7 +399,10 @@ function printHelp() {
     可用 DSH_CALIBGUARD_PIP_INDEX 指定其它索引；
   • 从 npm 安装时引擎默认放在 ~/.dsh/calibguard-engine（可用 --dest 或插件配置 engineRoot 指定）；
   • GPU 自动定档：检测到 NVIDIA 且 CUDA≥12.8、算力≥7.5（如 RTX 20/30/40 系）时
-    自动安装 CUDA（cu128）版 torch；否则用 CPU 版；可用 DSH_CALIBGUARD_CPU_ONLY=1 强制 CPU；
+    自动安装 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。
 `)
@@ -1003,7 +1027,10 @@ async function main() {
     // GPU 定档：有可用 NVIDIA（CUDA≥12.8、算力≥7.5）时先装 CUDA 版 torch，
     // 与 CG_GUI launcher 的口径一致；否则装 CPU 版 torch。
     const gpu = detectGpu()
-    const decision = decideCudaTorch(gpu)
+    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)
@@ -1030,8 +1057,8 @@ async function main() {
     const finalTorchCuda = installedTorchCuda(python)
     log(`torch CUDA：${finalTorchCuda || '无（CPU 版）'}`)
     if (decision.useCuda && !finalTorchCuda) {
-      warn('检测到可用 GPU 但 torch 是 CPU 版：审计仍可运行，只是用 CPU。'
-        + '可重跑：node setup.mjs --reinstall-torch')
+      warn('当前 torch 是 CPU 版：审计仍可运行，只是用 CPU。'
+        + '可重跑：node setup.mjs --reinstall-torch（或 --force-cuda 跳过兼容性检查）')
     }
     log('✓ 依赖安装完成')
   }