/
← Back to home@maomitgd2006

dsh-CalibGuard

CalibGuard 文件安全审计的 DeepSeek Harness 插件：本地校准 CodeBERT 门控 + 云端复核，以 agent 工具与侧边栏面板两种形态使用

Stars
1
Language
JavaScript
Created
Oct 20, 2026
Updated
Oct 20, 2026
Web UI
GitHub repo

Introduction

dsh-calibguard

中文 | English

license node tests npm

把 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 后， 若检测到缺少 <engineRoot>/.venv，插件会在后台自动：

  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] 开头的行。准备期间审计按钮不可用，完成后点「刷新状态」即可。 首次约需 10–20 分钟（取决于网速和 pip 源），只需一次。

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

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. 引擎：插件自带；模型权重会自动从本仓库 Release 下载（自动镜像回退）。也可用 --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）：

dsh plugin --profile <profile> add dsh-calibguard                                   # npm 包（推荐）
dsh plugin --profile <profile> add https://github.com/maomitgd2006/dsh-CalibGuard           # GitHub 源码
dsh plugin --profile <profile> add file:<本包绝对路径>                                # 本地目录

npm 包页：https://www.npmjs.com/package/dsh-calibguard

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

方式 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 在 <DSH_HOME>/profiles/desktop/cordis.patch.yml（<DSH_HOME> 默认 ~/.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_sourceevidence（精炼证据）/ raw（文件原文）
llm_delivery_modetruncate / window / all
truncate_chars / window_chars / window_overlap送审分片参数
window_stride模型侧全文滑窗步长（1–511，默认 256；大文件可设 510 提速）

配置

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

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

常见问题

现象处理
侧边栏没有图标 / 面板报 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/                配置全表、性能、排错、插件契约、实现决策

文档索引

文档内容
docs/configuration.md完整配置项、参数优先级、凭据来源、共享设置
docs/performance.md大文件为什么慢、两套滑窗（大小/步长/重叠）、提速手段、maxFiles 语义
docs/troubleshooting.md排错表、面板报错解读
docs/design-notes.md三个关键实现决策（设备定档 / 凭据 / 客户端半边）与协议
docs/dsh-plugin-contract.md从 DSH 0.1.5-rc.2 实测提取的插件契约速查（写插件用）

相关仓库

仓库内容
maomitgd2006/dsh-CalibGuard（本仓库）DSH 插件：工具 / 服务 / 路由 + 浏览器面板 + Python 桥接
P-436/CG引擎与基准：CG_GUI/（桌面壳 + 引擎 + 模型）、CG_Bench/（训练/评测）

许可证

MIT © 2026 maomitgd