dsh-CalibGuard

dsh-calibguard

中文 | English

把 CalibGuard 的文件安全审计引擎接进 DeepSeek Harness（DSH）： 让 AI 在执行 / 安装来路不明的代码之前先过一道本地门控，你也可以在侧边栏面板里直接拖文件审计。

• 🔒 默认离线：本地 CodeBERT + Platt 校准给出可解释的「恶意概率」，文件内容不会上传；
• ☁️ 灰区才上云：只有本地拿不准的文件才发一次云端复核（可关闭）；
• 🧭 四档结论：放行 / 可疑 / 拦截 / 转人工，附证据与 Markdown 报告；
• 🧰 两种用法：AI 工具调用（calibguard_audit / calibguard_status）+ 浏览器面板；
• ⚙️ 一套设置：面板里保存的阈值与送审口径，AI 调用同样生效。

本仓库只是 DSH 插件；审计引擎本体在 CG 仓库的 CG_GUI/，

本仓库不复制、不修改它，通过常驻 Python 子进程调用。

有什么用（典型场景）

场景 · 你怎么用 · 它给你什么 AI 要运行下载的脚本/安装包 · 说一句「安装前先审一下 D:\downloads\setup.py」 · 四档结论 + 触发证据 + 报告路径，AI 据此决定是否继续 手动检查可疑文件 / 压缩包 · 拖进侧边栏面板 · 逐文件结论、可排序、可点开 Markdown 报告 审计一整个目录 · 粘宿主机目录路径 · 递归逐文件审计（超过上限会明确提示「只审了前 N 个」） 不想把代码传到云上 · 默认即离线；需要时关掉云端复核 · 全程本地推理，灰区按本地 0.5 切分 想要更稳/更省 · 面板调阈值、送审内容源、投递方式并保存 · 面板与 AI 共用同一套口径

结论怎么读

标签 · 含义 · 建议动作 BLOCK 拦截 · 本地模型高置信度恶意 · 不要执行；看报告里的证据 MANUAL 转人工 · 拿不准 / 云端复核失败 · 人工确认，或换个送审口径再跑 SUSPICIOUS 可疑 · 中等概率，可能是正常库里的危险 API · 结合报告判断；压缩后的第三方库常落这里或拦截（见 FAQ） ALLOW 放行 · 本地模型判定安全 · 可以继续

结果里还有：校准后概率 p、推理设备（cpu/cuda）、窗口数、文件 sha256、以及报告文件路径。

安装

开始前：引擎依赖会自动准备（对齐 CG_GUI 的「首启装环境」）

本插件自带引擎（engine/：复制自 CG_GUI 的 calibguard/ 包、audit_service.py、词表与校准参数）， 只差 475 MB 模型权重和 Python 依赖。不用手动装——装好插件重启 DSH 后， 若检测到缺少 /.venv，插件会在后台自动：

1. 把内置 engine/ 复制到 `（默认 ~/.dsh/calibguard-engine`）；
2. 从本仓库 Release 下载模型权重 model.safetensors（约 442 MB 压缩包，GitHub 直连失败会自动尝试 ghproxy 等镜像，

缓存于 ~/.dsh/calibguard-tools/model-cache）；

1. 创建 .venv（不需要你预装 Python：本机没有 64 位 3.10–3.12 时会自动下载便携 Python 3.10.8，约 30 MB）；
2. 按 requirements-gui.txt 安装依赖（约 1–3 GB，默认清华 PyPI 镜像）；
3. 就绪后工具/面板自动可用。

默认不再从 GitHub 下载 CG 发行包；只有显式 node setup.mjs --from 或 --url

才会走 CG 发行包，用于离线/指定引擎版本。

进度在哪看：面板顶部会出现「首次运行：正在自动准备引擎与依赖」卡片（含当前步骤与输出尾巴）； 宿主日志里是 [calibguard] 开头的行。准备期间审计按钮不可用，完成后点「刷新状态」即可。 首次约需 10–20 分钟（取决于网速和 pip 源），只需一次。

想提前预热、或断网/锁网环境需要离线安装，也可以手动跑安装器（同一套逻辑，幂等）：

```powershell

node setup.mjs # 一键：下载 → 解压 → venv → 依赖 → 自检

node setup.mjs --from D:\CalibGuard-GUI.zip # 用已下载的发行包，不联网

node setup.mjs --dest D:\CG_GUI # 装到自定义位置（之后配置 engineRoot）

`

已有可用 CG_GUI/（含 .venv）的机器不会重复安装。

如果不想让插件自动联网，把插件配置 autoSetup 设为 false（此时缺环境会直接报错并提示手动安装）。

前提

1. DSH（DeepSeek Harness）0.1.5-rc.2 实测可用；
2. Python：无需预装——没有 64 位 3.10–3.12 时安装器会自动下载便携版（缓存在 ~/.dsh/calibguard-tools，可用 --no-portable-python 关闭）；
3. 引擎：插件自带；模型权重会自动从 npm 镜像下载。也可用 --from 指定 CG 发行包，或把 engineRoot 指向已有 CG_GUI/。

方式 0：桌面端「添加插件」（最省事，推荐）

DSH 桌面版 → 设置 → 添加插件，输入框里填以下任意一种即可（装完按提示重启 DSH）：

填什么 · 示例 · 说明 GitHub 仓库地址（推荐） · https://github.com/maomitgd2006/dsh-CalibGuard · 自动拉取源码并登记到当前 profile 的 bundle 本地目录路径 · `（例：D:\code\dsh-calibguard） · 已 clone / 解压到本地时用 **包名** · dsh-calibguard` · ✅ 已发布到 npm，直接输包名即可（自动装 npm 上的 latest）

等价命令行（已实测：安装后 DSH 会自动把包加进 profile 的 dsh.profile.bundles）：

```powershell

dsh plugin --profile add dsh-calibguard # npm 包（推荐）

dsh plugin --profile add https://github.com/maomitgd2006/dsh-CalibGuard # GitHub 源码

dsh plugin --profile add file: # 本地目录

`

npm 包页：

无论用哪种方式，装好后首次运行都不需要手动装引擎——插件会自动准备（见下一节）。

方式 A：命令行安装（npm 包，适合非桌面版 / 脚本化）

dsh plugin --profile <profile> add dsh-calibguard

之后同样在 profile 的 cordis.patch.yml 里插一行，name 直接写包名 dsh-calibguard （本包自带的 cordis.patch.yml 会自动把插件行叠加进配置树）。

desktop profile 被 Electron 独占，CLI 拒绝管理它 —— 桌面版请用「方式 0」，

或「方式 B」的 file:// 行。

方式 B：源码方式（file:// 行，适合本地开发 / 离线）

在 profile 的 cordis.patch.yml 末尾追加（路径改成你的实际位置）：

- insert:
    - id: calibguard
      name: 'file:///<本包绝对路径>/lib/index.js'
      config:
        enabled: true
        device: auto
        announceToModel: true

insert 行的路径会被 DSH 自动改写成 file:// URL；桌面版的 profile 在 /profiles/desktop/cordis.patch.yml（` 默认 ~/.dsh`）。

可选：node scripts/link-dsh.mjs 把 DSH 自带的 @deepseek-ai/* 以目录联接挂到本包，让 defineTool / Config 结构校验这两个可选能力生效（不做也能跑）。

方式 C：发行包（离线 / 不想用 npm）

从 Releases 下载 dsh-calibguard-.zip（约 100 KB，不含 test/），解压到一个固定目录，然后按「方式 B」 把 name 指向解压目录下的 lib/index.js 即可。

验证

• 重启 DSH 后，左侧边栏出现盾牌图标；面板顶部显示「引擎就绪 / 阈值 / 云端复核」状态；
• 或在对话里让我调用 calibguard_status，应返回设备、模型、阈值、凭据是否就绪；
• 命令行自检（不经 DSH，直接测引擎）：

node scripts/bridge-selftest.mjs                       # 只看引擎状态
node scripts/bridge-selftest.mjs "<engineRoot>/samples" # 状态 + 试审计

⚠️ 改完 patch / 面板代码后必须重启 DSH：客户端 bundle 在宿主启动时加载，

已加载的 ESM 模块也有缓存。

使用

1) 让 AI 审计（工具调用）

直接说自然语言即可，AI 会调用 calibguard_audit：

「安装前先审一下 D:\downloads\setup.py」
「这个压缩包安全吗？D:\downloads\vendor.zip」
「把 D:\projects\vendor 目录里可疑的文件过一遍」

AI 能看到完整四档结论与证据；若你说「只审高危文件」，它还能按次改阈值（不影响你的全局设置）。

2) 面板（浏览器 UI）

侧边栏盾牌图标 → 拖文件进虚线框（或点击选择、或粘贴宿主机路径）→「开始审计」。

• 压缩包由引擎在内存中解包后逐文件审计；上传只写系统临时目录、审计完即删；
• 大文件会按实测吞吐预估耗时（例如「预计 287 个滑窗，约 76 秒」），不会让你以为卡死；
• 结果按严重度排序，可点「查看 Markdown 报告」。

3) 共享设置（面板 ↔ AI 打通）

面板「设置」区照搬 CG_GUI 的设置面板：云端复核开关 → API Key / Base URL / 模型名称 / 送审内容 / 投递方式（截断或滑窗，参数联动显隐）→ 灰区范围。

点「保存」后：

• 参数写入 $DSH_HOME/calibguard-settings.json（默认 ~/.dsh，不写进仓库）；
• AI 调用同样使用这份设置（优先级：插件配置 < 共享设置 < 本次调用参数）；
• 改完立即生效，不用重启；
• API Key 写入 DSH 凭据库（ctx.credentials），不落入该设置文件。

4) 工具参数（按次覆盖，写给进阶用户）

参数 · 说明 paths · 必填；文件或目录绝对路径（相对路径按会话工作目录解析） include_evidence · 是否返回证据详情（默认 true） max_files · 目录递归展开上限（默认 20，1–200） allow_threshold / block_threshold · 本次的灰区上下限（0<p<1） llm_enabled · 本次是否启用云端复核 llm_content_source · evidence（精炼证据）/ raw（文件原文） llm_delivery_mode · truncate / window / all truncate_chars / window_chars / window_overlap · 送审分片参数 window_stride · 模型侧全文滑窗步长（1–511，默认 256；大文件可设 510 提速）

配置

插件行 config 里常用的几项（完整表见 docs/configuration.md）：

键 · 默认 · 说明 enabled · true · 关掉则什么都不注册（临时停用不必删行） engineRoot · '' · 引擎目录；留空自动推导：npm/桌面端安装时为 ~/.dsh/calibguard-engine，源码仓库里为本包同级 CG_GUI device · auto · 自动做「CUDA 版本 + 算力」双检，低算力显卡回落 CPU credentialRef · '' · 推荐的云端复核凭据引用名，如 DEEPSEEK_API_KEY（交给 DSH 凭据库解析） announceToModel · true · 是否把「何时该用 CalibGuard」写进系统提示词 autoSetup · true · 首次运行缺 .venv 时自动准备引擎（内置代码 + npm 模型分片）、按需下载便携 Python、安装依赖；设 false 则只报错提示手动 node setup.mjs maxFiles · 20 · 目录展开上限；显式给出/上传的文件不受限

常见问题

现象 · 处理 侧边栏没有图标 / 面板报 not found · 客户端与路由在宿主启动时加载：重启 DSH 首次运行要等十几分钟 · 正常：首次下载模型（约 442 MB，自动镜像回退）并安装依赖（1–3 GB）；面板顶部有进度卡片，只需一次 首次审计很慢 · 正常：要加载约 475 MB 权重（之后走常驻进程） 大文件审计几十秒 · 正常：全文滑窗逐窗推理，见 docs/performance.md 灰区全部转人工 · 没配凭据：设 credentialRef（推荐）或在 DSH Models 页配置 正规第三方库被判 BLOCK · 压缩库充满 eval/base64 等特征，模型语料偏 Python 生态 → 属已知误报倾向，见 docs/troubleshooting.md 面板报 401/403 · 浏览器会话未通过宿主鉴权：刷新页面/重新登录 改了参数 AI 没变 · 面板里需点「保存」（只改表单不保存 = 仅影响那一次）

完整排错表：docs/troubleshooting.md。

项目结构

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）
├── .github/workflows/   publish.yml：npm 可信发布（OIDC，可选）
└── docs/                配置全表、性能、排错、插件契约、实现决策