youchen-yc/dsh-system-guard

⚠️ 安全提示（发布说明，连续 3 个新版本保留）

1.0.1 以前的版本存在代码安全与分发自检问题，不安全，请不要再下载或安装。请使用 1.0.1 及以上版本。

具体问题：旧版运行时文件里带本机绝对路径（别人安装后可能找不到 helper）、前端存在被静态检查误判的字符串拼接形态； 1.0.1 已修复并补齐安全防御（SECURITY.md、CI 静态与供应链检查、SBOM、Ed25519 发布签名、分发自检）。

当前源码版本：1.0.3（本地修复，尚未发布）：P0/P1 安全与分发链修复已提交并通过本地测试； 重新封存 integrity.json、打包与发布在最后一步完成，本篇描述的是源码状态。

守护电脑系统文件的 DSH 插件：分析并分类本机系统文件，隐藏备份核心系统文件，定期巡查完整性， 发现损坏或被篡改时告警并修复；系统运行时产生的垃圾文件只做整理归类，要不要删由你打钩决定。

交流人格：鲸進進。技术结论以证据为准，没验证过的能力会明确标注「未验证」。

---

一、先说清楚能力边界（不夸大）

用户要的「最高权限」在这个插件里的真实含义是：用户点「授予守护权限」并通过 UAC 后， 插件以管理员身份执行保护类操作。它换来的是真正能做备份、修复、清理系统文件的能力； 但它不是操作系统内核级特权，也不是「凌驾于所有插件之上」的权限。

需求	本插件的实现	做不到 / 限制
向用户申请最高权限	面板「授予守护权限」→ 弹 UAC → 以管理员运行受控 helper	需要你在 UAC 弹窗点「是」；插件不会也不能静默提权
权限只能用来保护系统	lib/privilege.js 里冻结（Object.freeze）的动作白名单，所有写系统动作必须过 assertSystemAction()	这是插件进程内的单点门控，不是内核强制
底层逻辑不可修改、不可删除	白名单写死在代码里、不读配置；发布前生成 integrity.json，运行时自校验核心代码，封存后被改则拒绝一切写操作并告警	有文件写权限的人终究能改代码；自校验只能发现，不能物理阻止
拦截恶意篡改	巡查发现核心文件哈希/大小异常 → 告警 → 可从隐藏备份还原	没有文件系统过滤驱动，不能在内核层阻断写入，只能事后检测 + 回滚
备份被删除时拦截	备份目录隐藏（attrib +h +s）+ 保护 ACL + 清单冗余 + 删除检测告警	不能阻止管理员手动删；只能检测并尽量恢复
联网校准系统文件版本	用 DSH 的联网能力查询官方渠道，核对系统版本与支持状态，生成校准报告	微软等官方站不提供逐文件哈希清单，校准是「官方版本信息 + 本地完整性验证」，不是逐文件下载比对
不管 Windows 更新系统文件	巡查会识别「最近系统更新窗口」内的文件变化并标记为豁免，不告警、不修复	更新窗口靠本机补丁安装时间推算，可能有个别误判
定期巡查	插件随 DSH 运行；到设置的间隔自动巡查，也可手动点「巡查」	DSH 关闭期间不巡查；不是常驻 Windows 服务

关于系统记忆类文件：内存转储、休眠文件、页面文件、崩溃转储、事件日志这类 「系统记忆类」文件会单独归为一类展示，永久不参与删除，避免影响系统运行与排障。

隐私边界（如实说明）：联网校准经 DSH 的 ctx.web 检索，请求只携带系统版本信息 （osName / osBuild / osVersion）；DSH 的搜索 provider 在 sendOriginalQuestion 开启时 （默认开启）会附带本会话最近一次提问的前 128 字作为 ori_question，可在 DSH 设置里关闭； 本插件不发送文件路径清单与用户名，也不上传文件内容。

---

二、安装

插件以本地 bundle 形式安装（不影响其它插件）：

plugin_manager install_bundle  target: <插件源码目录>

其中 <插件源码目录> 是你本机 clone 下来的插件源码路径（即包含 package.json 的那个 system-guard 目录），不是本文档里的任何固定路径。

安装后：设置侧栏底部的面板列表里会出现「系统守护」盾牌图标，点它打开面板。 首次打开会在面板顶部显示「还没有建立基线」引导卡，点「点这里开始首次分析」即可。

数据目录：%DSH_HOME%\system-guard（未设置 DSH_HOME 时默认 ~/.dsh/system-guard；设置、状态、基线清单、隔离区）。

---

三、面板使用

按钮	做什么	需要管理员
授予守护权限	弹 UAC，获取仅供保护系统使用的管理员权限	会弹 UAC
分析（首次分析）	读系统信息 → 联网核对版本 → 解析核心文件清单并分类 → 建立基线 → 备份核心文件	否（备份部分需要读权限）
维护	重扫系统运行时垃圾（临时文件、更新缓存、日志、缩略图、错误报告、回收站等）并刷新垃圾分类；不核对备份状态（备份状态看「巡查」或「校验备份」）	否
巡查	逐文件核对核心文件哈希与存在性，检查备份状态；更新窗口内的变化豁免	否
修复	从隐藏备份还原损坏/缺失的核心文件（需二次确认）；当前面板只提供「从备份还原」与单独的「创建系统还原点」入口，SFC / DISM 尚未在面板开放	是
立即备份	把核心系统文件重新备份到剩余容量最大的硬盘	否
校验备份	核对备份文件是否完整、有没有被删	否
创建系统还原点	调 Windows 系统保护创建还原点（需系统保护已启用）	是
立即联网校准	只读查询官方渠道，核对系统版本与支持状态	否

垃圾文件区：按「用户临时文件 / Windows 临时文件 / 更新缓存 / 系统日志 / 缩略图 / 错误报告 / 回收站 …」分组，每组可展开、可打钩、可全选；点「删除选中项」会二次确认，删除后显示释放了多少空间。 系统记忆类分组单独显示，复选框是禁用的。

设置区：当前只开放两个间隔——自动巡查间隔（天）与联网校准询问间隔（天），范围 1–365 天； 备份盘由插件自动选剩余容量最大的盘（面板不提供选择），也暂未提供「自动备份」开关。

---

四、文件与数据结构

<插件源码目录>\                   ← 插件源码（本机 clone 位置，不写死具体盘符/目录）
├─ index.js                      Host 入口：装配、HTTP、Agent 工具、定时器
├─ client.js                     面板 UI（main 面板 + 侧栏图标）
├─ lib\config.js                 设置/状态存储（原子写、坏文件留档）
├─ lib\privilege.js              守护权限门控 + 不可变底层逻辑 + 代码自校验
├─ lib\core.js                   平台后端路由、任务队列、动作分发
├─ lib\patrol.js                 巡查与校准排期计算
├─ lib\httpapi.js                同源 HTTP 接口
├─ lib\ps.js                     PowerShell 执行（含 UAC 提权）
├─ lib\win-backend.js            Windows 后端
├─ scripts\guard.ps1             Windows 全部系统操作的唯一入口
├─ lib\posix-backend.js          macOS / Linux 后端（未在真机验证）
├─ lib\calibrate.js              联网校准
├─ scripts\seal.mjs              生成 integrity.json（封存）
└─ test\                         真机只读验证 + 契约自测

备份目录（隐藏）：<剩余容量最大的盘>:\SystemGuardBackup\.system-guard\，内含 manifest.json（每个文件的 SHA-256、大小、版本、原路径）与核心文件副本。

---

五、Agent 工具

插件还给 AI 注册了 system_guard 工具（status / analyze / patrol / junk-scan / junk-delete / backup / backup-status / repair / restore-point / calibrate / settings-save）。删除垃圾与修复必须由用户明确同意，工具侧强制要求 confirm: true； 授予守护权限（UAC）永远只能由用户在面板上点，Agent 不能代为授权。

---

六、验证状态

真机验证（Windows 10 专业工作站版 build 19045 / AMD64 / PowerShell 5.1 / 安装时非管理员）：

项目	结果
安装	plugin_manager install_bundle → application: applied；侧栏「系统守护」与主面板两个 slot 的登记均为 active
面板接口	/state、/analysis、/task、/action 真实返回；/state 已裁剪为摘要（约 2KB），明细走 /analysis
首次分析	真实 HTTP 触发，约 17 秒：核心文件 84/84 命中（95.8 MiB，逐个算 SHA-256）、普通系统文件 4175 个、清单 145 条、垃圾分组 11 个
垃圾扫描	可清理约 902 MB；系统记忆类单列（约 48.5 GB 的页面/休眠文件与事件日志），不参与删除
隐藏备份	自动选剩余容量最大盘（本机实测为该盘；盘符不写死），84 文件 / 95.8 MiB；Hidden,System 属性生效；ACL 对 BUILTIN\Users 拒绝删除；manifest.json 逐文件 sha256；重复备份幂等
巡查	145 文件全部一致 → healthy；五种判定（健康/被改/损坏/缺失/更新窗口豁免）用临时文件逐项验证正确
垃圾删除	自建临时文件删除成功（freedBytes 真实）；系统目录路径（如 C:\Program Files，通用示例）被目录白名单拒绝；缺 confirm 被拒
联网校准	宿主未配置搜索凭据时自动降级为直连官方页面，真实抓到 3 篇 learn.microsoft.com 页面并生成报告（如实标注「未使用搜索引擎」）
修复 / 还原点	非管理员时返回 need-elevation，任务标记为 failed，不会假装成功
可取消	AbortSignal 能杀掉 PowerShell 子进程（code=aborted）
Agent 工具	system_guard 已注册并可调用，删除/修复强制要求 confirm: true

未验证（如实说明）

• UAC 提权后的真执行：sfc /scannow、DISM /RestoreHealth、从备份还原系统文件、创建还原点，这四项需要管理员权限， 测试机上非管理员、测试期间没有弹 UAC，因此只验证到提权门控与错误提示。 其中 sfc / DISM 在后端能力里已有实现，但当前面板未开放入口（面板只提供「从备份还原」与「创建系统还原点」）。 请在面板点「授予守护权限」后按需实测。
• 浏览器内渲染：本会话无法控制浏览器做目视检查；slot 注册已 active、接口已真实返回，建议打开面板确认排版与深浅色。
• macOS / Linux：代码已实现（只统计/不删除，修复给出人工步骤），但没有在真机跑过。
• 联网搜索分支：本机没有 DeepSeek 搜索凭据，走的是 fetch 直连官方页面的降级路径；配置搜索凭据后才会走搜索分支。
• 安装时已写入的 Host 代码快照不会热更新：改动过的文件需要重启 DSH 后才全部生效。

---

七、许可

MIT（见 LICENSE）。图标为原创 SVG。