dsh-calibguard 0.2.5 → 0.3.1

package/README.en.md

@@ -53,15 +53,20 @@ file sha256, and the report path.
 
 ### Before you start: engine dependencies are prepared automatically (like CG_GUI's launcher)
 
-This plugin is only the wrapper: the auditing engine (`calibguard/` + **475 MB of model weights**) and its
-Python dependencies must be present. **You don't install them by hand.** After you install the plugin and
-restart DSH, if `<engineRoot>/.venv` is missing the plugin automatically, in the background:
+The plugin **ships the engine code** (`engine/`: `calibguard/`, `audit_service.py`, tokenizer files and
+calibration parameters copied from CG_GUI); only the **475 MB of model weights** and the Python dependencies
+are missing. **You don't install them by hand.** After you install the plugin and restart DSH, if
+`<engineRoot>/.venv` is missing the plugin automatically, in the background:
 
-1. downloads the official CG release `CalibGuard-GUI.zip` (~467 MB) and extracts it to `CG_GUI/`
-   **next to this package**;
-2. creates `.venv` (**no preinstalled Python required**: if no 64-bit 3.10–3.12 is found, a portable Python 3.10.8 is downloaded automatically, ~30 MB);
-3. installs dependencies from `requirements-gui.txt` (1–3 GB);
-4. becomes ready — tools and the panel just work.
+1. copies the bundled `engine/` into `<engineRoot>` (default `~/.dsh/calibguard-engine`);
+2. downloads the model weights from a **release asset of this repository** (~442 MB; GitHub is tried first,
+   then ghproxy-style mirrors; cached in `~/.dsh/calibguard-tools/model-cache`);
+3. creates `.venv` (**no preinstalled Python required**: if no 64-bit 3.10–3.12 is found, a portable Python 3.10.8 is downloaded automatically, ~30 MB);
+4. installs dependencies from `requirements-gui.txt` (1–3 GB, Tsinghua PyPI mirror by default);
+5. becomes ready — tools and the panel just work.
+
+> 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).
 
 **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
@@ -71,7 +76,7 @@ once (depends on network and pip mirror).
 > You can also pre-warm, or install offline, by running the same installer manually (idempotent):
 >
 > ```powershell
-> node setup.mjs                          # download → extract → venv → deps → self-check
+> node setup.mjs                          # bundled engine → npm model shards → venv → deps → self-check
 > node setup.mjs --from D:\CalibGuard-GUI.zip   # use an already-downloaded release zip (offline)
 > node setup.mjs --dest D:\CG_GUI         # custom location (then configure engineRoot)
 > ```
@@ -83,7 +88,7 @@ once (depends on network and pip mirror).
 
 1. **DSH** (DeepSeek Harness) — verified on 0.1.5-rc.2;
 2. **Python**: nothing to install — when no 64-bit 3.10–3.12 is available the installer downloads a portable Python automatically (cached in `~/.dsh/calibguard-tools`; disable with `--no-portable-python`);
-3. **The CG engine** — downloaded automatically, or an existing `CG_GUI/` (with `calibguard/`, `models/` and `.venv`).
+3. **Engine** — bundled with the plugin; model weights are downloaded from npm mirrors automatically. You can also pass `--from <zip>` or point `engineRoot` at an existing `CG_GUI/`.
 
 ### Option 0 — desktop "Add plugin" dialog (easiest, recommended)
 
@@ -91,7 +96,7 @@ DSH desktop → Settings → **Add plugin**, paste any one of the following (res
 
 | Paste | Example | Notes |
 |---|---|---|
-| **GitHub repository URL** (recommended) | `https://github.com/maomitgd2006/DSH_CG` | Fetches the source and registers the bundle in the current profile |
+| **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`) |
 
@@ -100,7 +105,7 @@ DSH desktop → Settings → **Add plugin**, paste any one of the following (res
 >
 > ```powershell
 > dsh plugin --profile <profile> add dsh-calibguard                          # npm package (recommended)
-> dsh plugin --profile <profile> add https://github.com/maomitgd2006/DSH_CG  # GitHub source
+> dsh plugin --profile <profile> add https://github.com/maomitgd2006/dsh-CalibGuard  # GitHub source
 > dsh plugin --profile <profile> add file:<absolute path to this package>     # local directory
 > ```
 >
@@ -143,7 +148,7 @@ the optional `defineTool` / Config schema support is active (everything still wo
 ### Option C — release archive (offline / no npm)
 
 Download `dsh-calibguard-<version>.zip` (~100 KB, no `test/`) from
-[Releases](https://github.com/maomitgd2006/DSH_CG/releases/latest), extract it to a fixed directory,
+[Releases](https://github.com/maomitgd2006/dsh-CalibGuard/releases/latest), extract it to a fixed directory,
 then point the `name` in "Option B" at `<extracted dir>/lib/index.js`.
 
 ### Verify
@@ -235,7 +240,7 @@ 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 engine (467 MB) is downloaded and dependencies (1–3 GB) are installed once; the panel shows progress |
+| **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 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 |
@@ -250,9 +255,10 @@ Full troubleshooting table: [docs/troubleshooting.md](docs/troubleshooting.md).
 ## Layout
 
 ```
-DSH_CG/
+dsh-CalibGuard/
 ├── lib/                 Node side: plugin entry, engine manager, tools, routes, settings, browser panel
 ├── bridge/              Python bridge: persistent child process, line-delimited JSON protocol
+├── engine/              Bundled engine core copied from CG_GUI (code / tokenizer / calibration, no weights)
 ├── cordis.patch.yml     Bundle patch (inserts the loader row)
 ├── scripts/             link-dsh (dev-time junction), bridge-selftest (engine self-check)
 ├── test/                node --test (95 cases; auto-skip when the engine env is missing)
@@ -274,7 +280,7 @@ DSH_CG/
 
 | Repository | Contents |
 |---|---|
-| **maomitgd2006/DSH_CG** (this repo) | DSH plugin: tools / service / routes + browser panel + Python bridge |
+| **maomitgd2006/dsh-CalibGuard** (this repo) | DSH plugin: tools / service / routes + browser panel + Python bridge |
 | [P-436/CG](https://github.com/P-436/CG) | Engine and benchmark: `CG_GUI/` (desktop shell + engine + model), `CG_Bench/` (training/eval) |
 
 ## License

package/README.md

@@ -48,13 +48,19 @@
 
 ### 开始前：引擎依赖会自动准备（对齐 CG_GUI 的「首启装环境」）
 
-本插件只是"壳"：审计引擎（`calibguard/` + **475 MB 模型权重**）和 Python 依赖需要就位。
-**不用手动装**——装好插件重启 DSH 后，若检测到缺少 `<engineRoot>/.venv`，插件会在**后台自动**：
+本插件**自带引擎**（`engine/`：复制自 CG_GUI 的 `calibguard/` 包、`audit_service.py`、词表与校准参数），
+只差 **475 MB 模型权重**和 Python 依赖。**不用手动装**——装好插件重启 DSH 后，
+若检测到缺少 `<engineRoot>/.venv`，插件会在**后台自动**：
 
-1. 下载 CG 官方发行包 `CalibGuard-GUI.zip`（约 467 MB）并解压为**本包同级的 `CG_GUI/`**；
-2. 创建 `.venv`（**不需要你预装 Python**：本机没有 64 位 3.10–3.12 时会自动下载便携 Python 3.10.8，约 30 MB）；
-3. 按 `requirements-gui.txt` 安装依赖（约 1–3 GB）；
-4. 就绪后工具/面板自动可用。
+1. 把内置 `engine/` 复制到 `<engineRoot>`（默认 `~/.dsh/calibguard-engine`）；
+2. 从**本仓库 Release** 下载模型权重 `model.safetensors`（约 442 MB 压缩包，GitHub 直连失败会自动尝试 ghproxy 等镜像，
+   缓存于 `~/.dsh/calibguard-tools/model-cache`）；
+3. 创建 `.venv`（**不需要你预装 Python**：本机没有 64 位 3.10–3.12 时会自动下载便携 Python 3.10.8，约 30 MB）；
+4. 按 `requirements-gui.txt` 安装依赖（约 1–3 GB，默认清华 PyPI 镜像）；
+5. 就绪后工具/面板自动可用。
+
+> 默认**不再**从 GitHub 下载 CG 发行包；只有显式 `node setup.mjs --from <zip>` 或 `--url <地址>`
+> 才会走 CG 发行包，用于离线/指定引擎版本。
 
 **进度在哪看**：面板顶部会出现「首次运行：正在自动准备引擎与依赖」卡片（含当前步骤与输出尾巴）；
 宿主日志里是 `[calibguard]` 开头的行。准备期间审计按钮不可用，完成后点「刷新状态」即可。
@@ -75,7 +81,7 @@
 
 1. **DSH**（DeepSeek Harness）0.1.5-rc.2 实测可用；
 2. **Python**：无需预装——没有 64 位 3.10–3.12 时安装器会自动下载便携版（缓存在 `~/.dsh/calibguard-tools`，可用 `--no-portable-python` 关闭）；
-3. **CG 引擎**：自动下载，或已有可用的 `CG_GUI/`（含 `calibguard/`、`models/`、`.venv`）。
+3. **引擎**：插件自带；模型权重会自动从 npm 镜像下载。也可用 `--from` 指定 CG 发行包，或把 `engineRoot` 指向已有 `CG_GUI/`。
 
 ### 方式 0：桌面端「添加插件」（最省事，推荐）
 
@@ -83,7 +89,7 @@ DSH 桌面版 → 设置 → **添加插件**，输入框里填以下任意一
 
 | 填什么 | 示例 | 说明 |
 |---|---|---|
-| **GitHub 仓库地址**（推荐） | `https://github.com/maomitgd2006/DSH_CG` | 自动拉取源码并登记到当前 profile 的 bundle |
+| **GitHub 仓库地址**（推荐） | `https://github.com/maomitgd2006/dsh-CalibGuard` | 自动拉取源码并登记到当前 profile 的 bundle |
 | **本地目录路径** | `<你的插件目录>`（例：`D:\code\dsh-calibguard`） | 已 clone / 解压到本地时用 |
 | **包名** | `dsh-calibguard` | ✅ **已发布到 npm**，直接输包名即可（自动装 npm 上的 latest） |
 
@@ -91,7 +97,7 @@ DSH 桌面版 → 设置 → **添加插件**，输入框里填以下任意一
 >
 > ```powershell
 > dsh plugin --profile <profile> add dsh-calibguard                                   # npm 包（推荐）
-> dsh plugin --profile <profile> add https://github.com/maomitgd2006/DSH_CG           # GitHub 源码
+> dsh plugin --profile <profile> add https://github.com/maomitgd2006/dsh-CalibGuard           # GitHub 源码
 > dsh plugin --profile <profile> add file:<本包绝对路径>                                # 本地目录
 > ```
 >
@@ -133,7 +139,7 @@ dsh plugin --profile <profile> add dsh-calibguard
 
 ### 方式 C：发行包（离线 / 不想用 npm）
 
-从 [Releases](https://github.com/maomitgd2006/DSH_CG/releases/latest) 下载
+从 [Releases](https://github.com/maomitgd2006/dsh-CalibGuard/releases/latest) 下载
 `dsh-calibguard-<版本>.zip`（约 100 KB，不含 `test/`），解压到一个固定目录，然后按「方式 B」
 把 `name` 指向解压目录下的 `lib/index.js` 即可。
 
@@ -210,11 +216,11 @@ AI 能看到完整四档结论与证据；若你说「只审高危文件」，
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `enabled` | `true` | 关掉则什么都不注册（临时停用不必删行） |
-| `engineRoot` | `''` | CG_GUI 目录；留空自动取本包**同级**的 `CG_GUI` |
+| `engineRoot` | `''` | 引擎目录；留空自动推导：**npm/桌面端安装**时为 `~/.dsh/calibguard-engine`，源码仓库里为本包同级 `CG_GUI` |
 | `device` | `auto` | 自动做「CUDA 版本 + 算力」双检，低算力显卡回落 CPU |
 | `credentialRef` | `''` | 推荐的云端复核凭据引用名，如 `DEEPSEEK_API_KEY`（交给 DSH 凭据库解析） |
 | `announceToModel` | `true` | 是否把「何时该用 CalibGuard」写进系统提示词 |
-| `autoSetup` | `true` | 首次运行缺 `.venv` 时**自动**下载引擎、按需下载便携 Python、安装依赖；设 `false` 则只报错提示手动 `node setup.mjs` |
+| `autoSetup` | `true` | 首次运行缺 `.venv` 时**自动**准备引擎（内置代码 + npm 模型分片）、按需下载便携 Python、安装依赖；设 `false` 则只报错提示手动 `node setup.mjs` |
 | `maxFiles` | `20` | 目录展开上限；显式给出/上传的文件不受限 |
 
 ---
@@ -224,7 +230,7 @@ AI 能看到完整四档结论与证据；若你说「只审高危文件」，
 | 现象 | 处理 |
 |---|---|
 | 侧边栏没有图标 / 面板报 `not found` | 客户端与路由在宿主启动时加载：**重启 DSH** |
-| **首次运行要等十几分钟** | 正常：首次自动下载引擎（467 MB）并安装依赖（1–3 GB）；面板顶部有进度卡片，只需一次 |
+| **首次运行要等十几分钟** | 正常：首次下载模型（约 442 MB，自动镜像回退）并安装依赖（1–3 GB）；面板顶部有进度卡片，只需一次 |
 | 首次审计很慢 | 正常：要加载约 475 MB 权重（之后走常驻进程） |
 | 大文件审计几十秒 | 正常：全文滑窗逐窗推理，见 [docs/performance.md](docs/performance.md) |
 | 灰区全部转人工 | 没配凭据：设 `credentialRef`（推荐）或在 DSH Models 页配置 |
@@ -239,9 +245,10 @@ AI 能看到完整四档结论与证据；若你说「只审高危文件」，
 ## 项目结构
 
 ```
-DSH_CG/
+dsh-CalibGuard/
 ├── lib/                 Node 侧：插件入口、引擎管理、工具、路由、共享设置、浏览器面板
 ├── bridge/              Python 桥接：常驻子进程，行式 JSON 协议，复用引擎
+├── engine/              从 CG_GUI 复制来的引擎核心（代码/词表/校准参数，不含 475 MB 权重）
 ├── cordis.patch.yml     组合包 patch（把插件行插进 profile 配置树）
 ├── scripts/             link-dsh（开发期挂包）、bridge-selftest（引擎自检）
 ├── test/                node --test（95 个用例；缺引擎环境时自动 skip）
@@ -263,7 +270,7 @@ DSH_CG/
 
 | 仓库 | 内容 |
 |---|---|
-| **maomitgd2006/DSH_CG**（本仓库） | DSH 插件：工具 / 服务 / 路由 + 浏览器面板 + Python 桥接 |
+| **maomitgd2006/dsh-CalibGuard**（本仓库） | DSH 插件：工具 / 服务 / 路由 + 浏览器面板 + Python 桥接 |
 | [P-436/CG](https://github.com/P-436/CG) | 引擎与基准：`CG_GUI/`（桌面壳 + 引擎 + 模型）、`CG_Bench/`（训练/评测） |
 
 ## 许可证

package/cordis.patch.yml

@@ -16,7 +16,8 @@
       config:
         # 是否注册工具（false 时不注册任何东西，便于临时停用而不必删行）
         enabled: true
-        # CalibGuard 引擎目录（含 calibguard/ 包与 models/ 的 CG_GUI 目录）；留空=自动推导为包的同级 CG_GUI
+        # 引擎目录（含 calibguard/ 包与 models/ 的目录）；留空=自动推导：npm/桌面端安装为 ~/.dsh/calibguard-engine，
+        # 源码仓库里为本包同级 CG_GUI
         engineRoot: ''
         # Python 解释器；留空=依次尝试 <engineRoot>/.venv、环境变量 DSH_CALIBGUARD_PYTHON、PATH
         pythonPath: ''

package/docs/configuration.md

@@ -7,12 +7,12 @@
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `enabled` | `true` | 关掉则什么都不注册（临时停用不必删行） |
-| `engineRoot` | `''` | CG_GUI 目录；留空自动推导为**本包同级**的 `CG_GUI` |
+| `engineRoot` | `''` | 引擎目录；留空自动推导：**npm/桌面端安装**时为 `~/.dsh/calibguard-engine`，源码仓库里为本包同级 `CG_GUI` |
 | `pythonPath` | `''` | Python 解释器；留空依次尝试 `<engineRoot>/.venv` → `DSH_CALIBGUARD_PYTHON` → PATH |
 | `device` | `auto` | `auto` 做「CUDA 版本 + 算力」双检；`cpu` / `cuda` 为强制 |
 | `useGuiSettings` | `true` | 复用 `CG_GUI/gui-settings.json`（与桌面壳共享阈值/云端配置） |
 | `announceToModel` | `true` | 是否把「何时该用 CalibGuard」写进系统提示词 |
-| `autoSetup` | `true` | 首次运行缺 `.venv` 时**自动**下载引擎（467 MB）、按需下载便携 Python 3.10.8（约 30 MB，存 `~/.dsh/calibguard-tools`）并安装依赖（1–3 GB）；面板显示进度。设 `false` 则只报错并提示手动 `node setup.mjs` |
+| `autoSetup` | `true` | 首次运行缺 `.venv` 时**自动**准备引擎（复制内置 `engine/` + 从 npm 镜像下载模型分片约 476 MB，缓存 `~/.dsh/calibguard-tools/model-cache`）、按需下载便携 Python 3.10.8、安装依赖（1–3 GB）；面板显示进度。设 `false` 则只报错并提示手动 `node setup.mjs` |
 | `maxFiles` | `20` | **目录展开上限**（1–200）：只限制"给一个目录时递归展开多少个文件"；显式给出/上传的文件全部审计 |
 | `auditTimeoutMs` | `600000` | 单次审计超时（毫秒） |
 | `idleShutdownMs` | `600000` | 空闲多久回收桥接进程（`0`=常驻不回收） |

package/docs/troubleshooting.md

@@ -9,7 +9,8 @@
 | 每份文件都 `manual_review` + `CUDA error: no kernel image` | 设备定档失效：确认 `device` 未被强制成 `cuda` |
 | 灰区全部转人工、`llm.status=api_error` | 没配凭据（预期降级）→ 设 `credentialRef`（推荐）或在 DSH Models 页配置 |
 | `凭据引用 X 未配置` 告警 | `credentialRef` 指向的引用在 DSH 凭据库里没有值；在 Models 页填 Key 或用 `llmApiKey` |
-| **首次运行卡在"正在准备环境"** | 正常：首次自动下载引擎（467 MB）+ 装依赖（1–3 GB），约 10–20 分钟；面板顶部有进度与输出尾巴 |
+| **模型下载失败 / 想离线** | 手动下载 `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` 离线包） |
 | **本机没有 Python** | 会自动用 uv 下载便携 Python 3.10.8（约 30 MB，缓存 `~/.dsh/calibguard-tools`）；若这一步失败会自动给出 python.org 下载链接，也可用 `--python` 指定解释器 |
 | 大文件审计几十秒 | 正常：耗时 ≈ 窗口数 ÷ CPU 吞吐，见 [performance.md](performance.md) |

package/engine/README.md

@@ -0,0 +1,33 @@
+# engine/ —— 内置引擎核心（复制自 CG_GUI）
+
+本目录是 [CG](https://github.com/P-436/CG) 仓库 `CG_GUI/` 里运行审计所需的**核心文件副本**，
+让 `dsh-calibguard` 安装后不必再从 GitHub 下载 CG 发行包：
+
+| 内容 | 说明 |
+|---|---|
+| `calibguard/` | 审计引擎 Python 包（未修改、原样复制） |
+| `audit_service.py` | 桥接进程读取 GUI 设置时复用它的校验逻辑 |
+| `requirements-gui.txt` | 依赖清单（安装到 `.venv`） |
+| `models/calibration_params.json` | Platt 校准参数 |
+| `models/codebert_finetuned/*` | 模型配置与分词器文件（**不含** `model.safetensors`） |
+
+**模型权重（475 MB）不在本仓库的 Git 里**：它作为本仓库的 Release 资产分发
+（`model-v1.0.0` 里的 `calibguard-model-1.0.0.zip`），首次运行时由 `setup.mjs` 下载、按 SHA-256
+校验后释放为 `models/codebert_finetuned/model.safetensors`；已下载的会缓存在
+`~/.dsh/calibguard-tools/model-cache`。
+
+## 与 CG_GUI 同步
+
+引擎代码更新时，把对应文件从 CG 的 `CG_GUI/` 重新复制过来即可（保持原样、不要改逻辑）：
+
+```powershell
+# 在 CG 仓库根目录下执行（把 DSH_CG 换成你本地插件仓库目录）
+Copy-Item CG_GUI\calibguard\*.py <插件仓库>\engine\calibguard\ -Force
+Copy-Item CG_GUI\audit_service.py, CG_GUI\requirements-gui.txt <插件仓库>\engine\ -Force
+Copy-Item CG_GUI\models\calibration_params.json <插件仓库>\engine\models\ -Force
+Copy-Item CG_GUI\models\codebert_finetuned\*.json, CG_GUI\models\codebert_finetuned\merges.txt, `
+          CG_GUI\models\codebert_finetuned\vocab.json <插件仓库>\engine\models\codebert_finetuned\ -Force
+```
+
+如果模型权重本身变化，需要：① 重新压缩成 `calibguard-model-<版本>.zip` 发到本仓库 Release
+（如 `model-v1.0.0`）；② 更新 `setup.mjs` 里的 `MODEL_URL` 与 `MODEL_SHA256`。

package/engine/audit_service.py

@@ -0,0 +1,304 @@
+"""审计任务封装（T-G2.5）：把 calibguard.pipeline 包成“任务”模型供 API 层调用。
+
+铁律：
+  - 后端审计单并发：_JOB_LOCK 一把全局锁，后来的任务排队等待，禁止多 worker 并行；
+  - 逐字复用引擎入口（load_config + AuditPipeline），禁止重写审计逻辑；
+  - 引擎无阶段回调钩子 → stage 只写 "model" → "report" 两档，禁止伪造细粒度进度；
+  - 单文件异常记账后继续下一个文件，异常文本必须能冒泡到 UI。
+
+设置（gui-settings.json，2026-10-05 扩展）：
+  - 是否启用云端 LLM 复核、API Key、Base URL、模型名；
+  - 灰区范围（allow/block 阈值，默认 0.15 / 0.85）；
+  - LLM 送审内容源（精炼证据 / 文件原文）× 投递模式（截断 / 滑窗 / 一次性全部上传）
+    及其随附参数（截断字符数、滑窗字符数与重叠字符数）。
+  - 应用方式：直接改运行中 pipeline 的 cfg 字段 + 重建 LLM 客户端，**不重载模型**
+    （模型加载耗时数十秒，而上述设置都不影响模型权重与校准参数）。
+"""
+import dataclasses
+import json
+import os
+import threading
+import uuid
+
+from calibguard.config import LLM_CONTENT_SOURCES, LLM_DELIVERY_MODES, load_config, validate_config
+from calibguard.llm_analyzer import LLMAnalyzer
+from calibguard.pipeline import AuditPipeline
+
+_ROOT = os.path.dirname(os.path.abspath(__file__))
+SETTINGS_PATH = os.path.join(_ROOT, "gui-settings.json")
+
+_JOB_LOCK = threading.Lock()                    # 全局单并发锁
+_JOBS: dict[str, dict] = {}                     # job_id -> 状态
+_PIPELINE: AuditPipeline | None = None          # 引擎流水线单例（模型只加载一次）
+_PENDING_SETTINGS_REFRESH = False               # 审计运行期间被暂缓的设置应用请求
+
+# 阶段取值封闭集合（引擎无回调钩子，实际只会出现 model / report 两档）
+STAGE_MODEL = "model"
+STAGE_REPORT = "report"
+
+# ============================== 设置 ==============================
+
+# 默认设置（gui-settings.json 缺键时用这些值；与引擎 AppConfig 默认值保持一致）
+DEFAULT_SETTINGS: dict = {
+    "llm_enabled": True,
+    "deepseek_api_key": "",
+    "llm_base_url": "https://api.deepseek.com",
+    "llm_model": "deepseek-chat",
+    "allow_threshold": 0.15,
+    "block_threshold": 0.85,
+    "llm_content_source": "evidence",
+    "llm_delivery_mode": "truncate",
+    "llm_truncate_chars": 3000,
+    "llm_window_chars": 3000,
+    "llm_window_overlap": 500,
+}
+
+# 设置键 → 引擎 AppConfig 字段（用于把设置写进运行中的 cfg）
+_CFG_FIELDS = {
+    "llm_enabled": "llm_enabled",
+    "deepseek_api_key": "llm_api_key",
+    "llm_base_url": "llm_base_url",
+    "llm_model": "llm_model",
+    "allow_threshold": "allow_threshold",
+    "block_threshold": "block_threshold",
+    "llm_content_source": "llm_content_source",
+    "llm_delivery_mode": "llm_delivery_mode",
+    "llm_truncate_chars": "llm_truncate_chars",
+    "llm_window_chars": "llm_window_chars",
+    "llm_window_overlap": "llm_window_overlap",
+}
+
+_SETTINGS: dict = dict(DEFAULT_SETTINGS)
+
+
+def _coerce_settings(raw: dict) -> dict:
+    """把外部输入（JSON）规范化为合法设置字典；任何非法项抛 ValueError（中文说明）。
+
+    只接受已知键；未知键忽略（向前兼容）。
+    """
+    if not isinstance(raw, dict):
+        raise ValueError("设置必须是 JSON 对象")
+    merged = dict(DEFAULT_SETTINGS)
+    for key in DEFAULT_SETTINGS:
+        if key in raw:
+            merged[key] = raw[key]
+
+    if not isinstance(merged["llm_enabled"], bool):
+        raise ValueError("llm_enabled 必须是布尔值")
+    for key in ("deepseek_api_key", "llm_base_url", "llm_model"):
+        if not isinstance(merged[key], str):
+            raise ValueError(f"{key} 必须是字符串")
+    if merged["llm_enabled"] and not merged["llm_base_url"].strip():
+        raise ValueError("启用云端复核时 llm_base_url 不能为空")
+    if merged["llm_enabled"] and not merged["llm_model"].strip():
+        raise ValueError("启用云端复核时 llm_model 不能为空")
+
+    for key in ("allow_threshold", "block_threshold"):
+        try:
+            merged[key] = float(merged[key])
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"{key} 必须是 0~1 之间的数字") from exc
+    if not (0.0 < merged["allow_threshold"] < merged["block_threshold"] < 1.0):
+        raise ValueError(
+            f"灰区范围必须满足 0 < 下限({merged['allow_threshold']}) < "
+            f"上限({merged['block_threshold']}) < 1")
+
+    if merged["llm_content_source"] not in LLM_CONTENT_SOURCES:
+        raise ValueError(f"llm_content_source 必须是 {LLM_CONTENT_SOURCES} 之一")
+    if merged["llm_delivery_mode"] not in LLM_DELIVERY_MODES:
+        raise ValueError(f"llm_delivery_mode 必须是 {LLM_DELIVERY_MODES} 之一")
+    for key in ("llm_truncate_chars", "llm_window_chars", "llm_window_overlap"):
+        try:
+            merged[key] = int(merged[key])
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"{key} 必须是整数") from exc
+    if merged["llm_truncate_chars"] < 1:
+        raise ValueError("截断大小必须 ≥ 1 个字符")
+    if merged["llm_window_chars"] < 1:
+        raise ValueError("滑窗大小必须 ≥ 1 个字符")
+    if not (0 <= merged["llm_window_overlap"] < merged["llm_window_chars"]):
+        raise ValueError(
+            f"滑窗重叠必须满足 0 ≤ 重叠 < 滑窗大小({merged['llm_window_chars']})")
+    return merged
+
+
+def get_settings() -> dict:
+    """返回当前生效设置的副本（供 GET /api/settings 与 UI 回填）。"""
+    return dict(_SETTINGS)
+
+
+def _apply_settings_to_cfg(cfg, settings: dict) -> None:
+    """把设置写进 AppConfig 对应字段（键名映射见 _CFG_FIELDS）。"""
+    for key, field_name in _CFG_FIELDS.items():
+        setattr(cfg, field_name, settings[key])
+
+
+def _build_llm(cfg):
+    """按 cfg 构造云端 LLM 客户端（Key/BaseURL/模型名变更后重建）。"""
+    return LLMAnalyzer(
+        api_key=cfg.llm_api_key, base_url=cfg.llm_base_url, model=cfg.llm_model,
+        temperature=cfg.llm_temperature, max_tokens=cfg.llm_max_tokens,
+        timeout=cfg.llm_timeout, evidence_max_chars=cfg.evidence_max_chars)
+
+
+def _apply_settings_locked() -> None:
+    """把当前设置应用到运行中的 pipeline（调用方必须已持有 _JOB_LOCK）。
+
+    只改 cfg 字段 + 重建 LLM 客户端，**不重载模型**：这样设置变更绝不会与正在进行的
+    审计并发改写状态（补丁 11 约束），也不付出模型加载代价。
+    """
+    global _PENDING_SETTINGS_REFRESH
+    if _PIPELINE is None:
+        _PENDING_SETTINGS_REFRESH = False        # 流水线未建：下次创建自然读新设置
+        return
+    _apply_settings_to_cfg(_PIPELINE.cfg, _SETTINGS)
+    _PIPELINE.llm = _build_llm(_PIPELINE.cfg)
+    _PENDING_SETTINGS_REFRESH = False
+
+
+def _refresh_settings() -> bool:
+    """在 _JOB_LOCK 保护下应用设置；审计运行中则暂缓（不阻塞等待）。
+
+    不阻塞的原因：设置请求若等锁，会在审计期间把 HTTP 请求挂住；补丁 11 要求
+    “审计运行中禁止触发重建，UI 提示当前任务完成后生效”，故记待办后立即返回。
+    第二次尝试用于消解与任务收尾的竞态（锁刚释放时仍可即时生效）。
+    """
+    global _PENDING_SETTINGS_REFRESH
+    for _ in range(2):
+        if _JOB_LOCK.acquire(blocking=False):
+            try:
+                _apply_settings_locked()
+                return True
+            finally:
+                _JOB_LOCK.release()
+        _PENDING_SETTINGS_REFRESH = True         # 有任务在跑：暂缓
+    return False
+
+
+def load_settings() -> None:
+    """读 gui-settings.json，刷新内存设置，并把 Key 注入环境变量 DEEPSEEK_API_KEY。
+
+    引擎的 load_config 从环境变量读取 Key（主文档 6.2），本函数是 GUI 侧唯一注入点。
+    铁律：禁止读写 calibguard 的 config.yaml；禁止把 Key 写进任何日志。
+    """
+    global _SETTINGS
+    if not os.path.isfile(SETTINGS_PATH):
+        return
+    with open(SETTINGS_PATH, "r", encoding="utf-8") as handle:
+        payload = json.load(handle)
+    if not isinstance(payload, dict):
+        raise ValueError(f"设置文件格式错误（应为 JSON 对象）：{SETTINGS_PATH}")
+    _SETTINGS = _coerce_settings(payload)
+    _inject_api_key(_SETTINGS["deepseek_api_key"])
+
+
+def _inject_api_key(key: str) -> None:
+    """把 Key 注入（或清除）环境变量：留空即不使用云端（不留残余环境值）。"""
+    if key:
+        os.environ["DEEPSEEK_API_KEY"] = key
+    else:
+        os.environ.pop("DEEPSEEK_API_KEY", None)
+
+
+def save_settings(payload: dict) -> bool:
+    """合并并落盘设置（UTF-8 无 BOM），立即让配置生效。
+
+    支持部分更新：payload 中未出现的键保持当前值（旧版只传 deepseek_api_key 的调用
+    仍然可用）。返回设置是否已即时生效：False 表示当前有审计任务在跑（_JOB_LOCK 被
+    占用），应用已暂缓，等当前任务结束由 _run_job 落地（补丁 11 约束一）。
+    """
+    global _SETTINGS
+    if not isinstance(payload, dict):
+        raise ValueError("设置必须是 JSON 对象")
+    merged = dict(_SETTINGS)
+    merged.update(payload)
+    settings = _coerce_settings(merged)
+
+    with open(SETTINGS_PATH, "w", encoding="utf-8") as handle:
+        json.dump(settings, handle, ensure_ascii=False, indent=2)
+    _SETTINGS = settings
+    _inject_api_key(settings["deepseek_api_key"])
+    return _refresh_settings()
+
+
+def _get_pipeline() -> AuditPipeline:
+    """引擎流水线单例：首次调用加载模型（可耗时数十秒），之后全程复用。"""
+    global _PIPELINE
+    if _PIPELINE is None:
+        # 铁律 7：禁止读写 calibguard 的 config.yaml → 传 None 走引擎内置默认值，
+        # 相对路径（models/、reports/）由 server 的 cwd（项目根）解析。
+        cfg = load_config()
+        _apply_settings_to_cfg(cfg, _SETTINGS)
+        error = validate_config(cfg)
+        if error:
+            raise ValueError(f"设置非法，无法初始化引擎：{error}")
+        _PIPELINE = AuditPipeline(cfg)
+    return _PIPELINE
+
+
+# ============================== 任务模型 ==============================
+
+def create_job(paths: list[str]) -> str:
+    """建 job（排队态），返回 job_id；执行交给 daemon 线程 + 全局单并发锁。"""
+    job_id = uuid.uuid4().hex[:12]
+    _JOBS[job_id] = {
+        "state": "queued",
+        "paths": list(paths),
+        "stage": "",
+        "done": 0,
+        "total": len(paths),
+        "results": [],
+    }
+    threading.Thread(target=_run_job, args=(job_id,), daemon=True).start()
+    return job_id
+
+
+def job_status(job_id: str) -> dict:
+    """查询任务状态/进度/结果；未知 id 抛 KeyError（API 层转 404）。
+
+    返回浅拷贝：handler 线程序列化时后台线程仍在推进 job，避免“字典迭代期间改变大小”。
+    """
+    return dict(_JOBS[job_id])
+
+
+def _report_to_dict(report) -> dict:
+    """引擎报告归一化：CGv0.2.2 的 audit_file 直接返回 dict，原样透传（不增删字段）。"""
+    if isinstance(report, dict):
+        return report
+    if hasattr(report, "to_dict"):
+        return report.to_dict()
+    if dataclasses.is_dataclass(report):
+        return dataclasses.asdict(report)
+    raise TypeError(f"引擎返回了无法序列化的报告对象：{type(report).__name__}")
+
+
+def _run_job(job_id: str) -> None:
+    """单并发执行任务：逐文件调用引擎，单文件异常记账后继续。"""
+    job = _JOBS[job_id]
+    with _JOB_LOCK:                                  # 后来的任务在此排队等待
+        job["state"] = "running"
+        try:
+            pipeline = _get_pipeline()
+        except Exception as exc:
+            # 模型/校准参数/设置不可用属全局失败：显式暴露，绝不假成功
+            job["error"] = f"引擎初始化失败：{type(exc).__name__}: {exc}"
+            job["stage"] = STAGE_REPORT
+            for path in job["paths"]:
+                job["results"].append({"error": job["error"], "path": path})
+            job["done"] = job["total"]
+            job["state"] = "error"
+        else:
+            for path in job["paths"]:
+                job["stage"] = STAGE_MODEL               # 引擎无回调钩子：粗粒度两档
+                try:
+                    report = pipeline.audit_file(path)
+                    job["results"].append(_report_to_dict(report))
+                except Exception as exc:
+                    job["results"].append({"error": f"{type(exc).__name__}: {exc}", "path": path})
+                job["stage"] = STAGE_REPORT
+                job["done"] += 1
+            job["state"] = "done"
+
+    # 任务已结束（锁已释放）：落地审计运行期间被暂缓的设置更新（补丁 11 约束一）
+    if _PENDING_SETTINGS_REFRESH:
+        _refresh_settings()

package/engine/calibguard/__init__.py

@@ -0,0 +1,2 @@
+"""CalibGuard：本地 CodeBERT 校准门控 + 云端 LLM 按需分析的安全审计工具。"""
+__version__ = "1.0.0"

package/engine/calibguard/__main__.py

@@ -0,0 +1,4 @@
+from calibguard.cli import main
+
+if __name__ == "__main__":
+    main()