23J1633/DSH-PC-Manager

DSH PC Manager

中文 · English

版本 1.0.0 · Windows 10/11 · MIT 许可证

中文：基于 DeepSeek Harness 的 Windows 桌面电脑管家。应用将只读系统观察、风险结构化、独立审核和可逆清理组织成一条可追踪的 Agent 工作流。

English: A Windows desktop computer manager powered by DeepSeek Harness. It combines read-only system observation, structured findings, independent review and reversible cleanup into a traceable Agent workflow.

中文

1. 项目定位

DSH PC Manager 是一个 Electron 桌面应用，不是浏览器页面，也不是传统的规则库杀毒软件。它把本机系统检查交给 DeepSeek Harness 中的 Agent 执行，并将结果转换为用户可以复核的风险清单。

当前支持两类扫描：

- 硬盘清理扫描：从缓存、临时文件、日志、转储、构建产物、陈旧安装介质、应用残留和大文件中寻找可解释的空间风险。
- 病毒关联扫描：关联进程、父子关系、数字签名、网络连接、防火墙、Defender、启动项、服务、计划任务、注册表和常见持久化位置。

扫描范围必须由调用方明确传入。文件递归、哈希和落点分析受用户所选磁盘或目录限制；进程、网络、Defender 和防火墙等全局运行态可以只读观察，但不会因此扩大文件扫描范围。

2. 技术栈与版本

| 层次 | 技术 |
| --- | --- |
| Desktop shell | Electron 44 |
| UI | React 19、React DOM、Lucide React |
| Language | TypeScript 5.9，严格模式 |
| Frontend build | Vite 8、base: './' |
| Agent runtime | @deepseek-ai/dsh 0.1.5-rc.1 |
| Markdown | react-markdown、remark-gfm |
| Tests | Vitest 5、Node HTTP mock server、真实 Electron/DSH 集成测试 |
| Windows packaging | electron-builder 26，NSIS x64 |

Node.js 版本要求为 >=22.12.0。主进程编译目标为 NodeNext/ES2023，渲染进程编译目标为 ESNext/ES2022。

3. 架构概览

~~~text
┌──────────────────────────────────────────────────────────────┐
│ Renderer: React + TypeScript                                  │
│ App.tsx · styles.css · typed window.pcManager API             │
└──────────────────────────────┬───────────────────────────────┘
│ contextBridge / IPC
┌──────────────────────────────▼───────────────────────────────┐
│ Preload: src/main/preload.cts                                  │
│ Exposes only the allow-listed PcManagerApi                     │
└──────────────────────────────┬───────────────────────────────┘
│ ipcMain.handle / ipcMain.on
┌──────────────────────────────▼───────────────────────────────┐
│ Main: Electron                                                  │
│ main.ts · OperationController · SettingsStore · HistoryStore   │
│ system-overview · connection-test · path-suggestions            │
└───────────────┬──────────────────────────────┬────────────────┘
│ JSON-RPC over stdin/stdout    │ local persistence
┌───────────────▼────────────────────┐  ┌──────▼─────────────────┐
│ DSH child process                  │  │ app.getPath('userData') │
│ dsh --profile sdk --patch ...      │  │ settings/history/data  │
│ PowerShell 和文件工具          │  │ 隔离区              │
└────────────────────────────────────┘  └────────────────────────┘
~~~

渲染进程没有 Node.js 集成、启用 contextIsolation 和 sandbox；所有本机能力都必须通过 preload 暴露的类型化 API 进入主进程。主进程还会校验 IPC 请求来源必须是本地 file: 页面。

4. 一次操作的生命周期

扫描

~~~text
用户选择范围
│
▼
OperationController.validateScanTargets()
│ 绝对路径、存在性、网络目录开关、重复项、数量限制
▼
创建 read-only DshRuntime
│
├─ scanPlanningPrompt()      规划 Agent：只制定 4–7 步计划
│       └─ parseOperationPlan()；失败时使用 fallbackScanPlan()
│
└─ promptForScan()           扫描 Agent：只读调用工具、返回风险 JSON
└─ parseScanReport()；排序、限长、去重、补齐默认值
│
▼
发布 risks / assistant-message / completed 事件
~~~

清理

~~~text
用户勾选风险并确认
│
▼
新建 read-only DshRuntime
│
├─ cleanupAuditPrompt()
│       └─ 独立审核 Agent 逐项返回 allow / deny / manual
│
├─ 没有 allow 项 ──> 全部安全跳过，不产生系统修改
│
└─ 有 allow 项
│ 关闭审核运行时
▼
新建 danger-full-access DshRuntime
│
└─ cleanupPrompt() 只处理审核放行且用户授权的精确目标
└─ parseCleanupReport() -> CleanupReport
~~~

同一时间只允许一个活动操作。扫描、清理和对话都会生成独立的 DSH 会话；清理的审核会话和执行会话也分别创建。取消操作时会关闭 DSH 子进程，必要时在 Windows 上调用隐藏的 taskkill.exe 终止进程树。

5. 目录与模块职责

| 路径 | 职责 |
| --- | --- |
| src/main/main.ts | 创建窗口、初始化服务、注册 IPC、UAC 重启、快捷方式、外部链接和 UI 冒烟截图入口 |
| src/main/preload.cts | 将 PcManagerApi 通过 contextBridge 暴露给 renderer |
| src/main/dsh-runtime.ts | 启动 DSH 子进程、JSON-RPC 请求/响应、通知分发、会话等待、Token 解析和关闭 |
| src/main/operation-controller.ts | 操作互斥、扫描/规划/审核/清理/对话编排、边界验证和操作事件发布 |
| src/main/prompt-library.ts | 内置 Agent 预设、扫描提示词、计划提示词、审核提示词、清理提示词和对话提示词 |
| src/main/result-parser.ts | 提取标记 JSON、校验和归一化计划/风险/审核/清理结果 |
| src/main/settings-store.ts | 设置加载、字段归一化、串行原子写入、safeStorage API Key 和 Token 累计 |
| src/main/history-store.ts | 操作事件持久化、最多 80 条历史记录、清理报告和审核报告归档 |
| src/main/system-overview.ts | Windows 磁盘容量、主机信息、系统根目录和管理员状态 |
| src/main/connection-test.ts | 对兼容 Chat Completions 的模型服务执行一次最小连接请求 |
| src/main/path-suggestions.ts | 为对话中的 @ 引用提供本机路径补全 |
| src/shared/types.ts | renderer/main 共用的数据模型、IPC API、操作事件和 Token 类型 |
| src/renderer/App.tsx | UI 状态机、扫描范围、风险清单、清理确认、聊天、历史、设置和事件消费 |
| src/renderer/styles.css | 桌面布局、明暗主题、弹窗、响应式规则和组件样式 |
| resources/dsh/pc-manager.patch.yml | 注入每轮 DSH 用户消息的电脑管家 persona 与系统边界 |
| tests/ | 解析器、连接、路径、历史、Markdown、设置和真实 DSH 隔离集成测试 |
| scripts/ | Windows 隐藏窗口检查、设置冒烟、快捷方式检查、图标生成和 DSH Windows 补丁 |
| docs/screenshots/ | README 使用的浅色 UI 截图 |

6. 主进程与 DSH 运行时

DshRuntime 启动的实际命令等价于：

~~~text
--profile sdk --patch
~~~

默认运行时 executable 是 Electron 自身，并通过 ELECTRON_RUN_AS_NODE=1 作为 Node 运行。启动环境包括：

| 环境变量 | 来源 | 作用 |
| --- | --- | --- |
| DSH_HOME | userData/dsh-runtime | DSH 会话和运行时数据目录 |
| DSH_PERMISSION_MODE | operation mode | read-only 或 danger-full-access |
| DEEPSEEK_API_KEY | SettingsStore / environment | 模型凭据 |
| DEEPSEEK_BASE_URL | SettingsStore | 模型服务 Base URL |
| DSH_TELEMETRY_DISABLED | telemetry setting | 遥测关闭时设置为 1 |

stdout 每行是一个 JSON-RPC frame。响应按 numeric request id 匹配；无 id 的 frame 作为 DSH notification。session.event 负责转发工具活动和 Token，session.status=idle 表示本次 prompt 完成。stderr 只保留最近一段尾部，在失败消息中用于诊断。

主进程使用 windowsHide: true 启动 PowerShell、DSH 和 taskkill.exe，避免系统检查过程中弹出终端窗口。

7. Renderer、Preload 与 IPC

渲染进程只调用 window.pcManager。接口定义位于 src/shared/types.ts，实现位于 src/main/preload.cts，主进程处理器位于 src/main/main.ts。

| Renderer API | IPC channel | 类型 | 作用 |
| --- | --- | --- | --- |
| bootstrap() | pc-manager:bootstrap | invoke | 读取版本、设置、系统概览、Token 和内置预设 |
| saveSettings() | pc-manager:settings-save | invoke | 归一化并保存设置 |
| startScan() | pc-manager:scan-start | invoke | 启动硬盘或病毒扫描 |
| startCleanup() | pc-manager:cleanup-start | invoke | 启动审核和清理链路 |
| sendChat() | pc-manager:chat-send | invoke | 启动只读对话 |
| cancelOperation() | pc-manager:operation-cancel | invoke | 取消活动操作 |
| testConnection() | pc-manager:connection-test | invoke | 发送最小模型连接请求 |
| chooseDirectory() | pc-manager:directory-choose | invoke | 打开本机目录选择器 |
| suggestPaths() | pc-manager:path-suggest | invoke | 查询本机路径补全 |
| listHistory() | pc-manager:history-list | invoke | 读取操作历史 |
| createDesktopShortcut() | pc-manager:shortcut-create | invoke | 创建 Windows 桌面快捷方式 |
| requestElevation() | pc-manager:elevation-request | invoke | 请求通过 UAC 重新启动 |
| openPath() | pc-manager:path-open | invoke | 用系统程序打开本机路径 |
| openExternal() | pc-manager:external-open | invoke | 仅打开 HTTP/HTTPS 外部链接 |
| onOperationEvent() | pc-manager:operation-event | event | 订阅操作生命周期事件 |
| window. | pc-manager:window- | send | 最小化、最大化/还原、关闭窗口 |

新增 IPC 时要同时修改共享类型、preload allow-list、main handler 和 renderer 调用方，并保留 assertRenderer() 校验。不要把 ipcRenderer、Node API 或任意 shell 能力直接暴露给页面。

8. 共享事件模型

所有后台操作都通过 OperationEvent 更新界面和历史记录，事件使用 operationId 关联：

| 事件 | 主要字段 | 消费方 |
| --- | --- | --- |
| started | 操作类型、模型、思考等级、目标/授权项目 | 初始化 UI 和历史条目 |
| plan | OperationPlan | 展示 Agent 计划 |
| progress | 阶段、消息、百分比、计划步骤 | 更新进度面板 |
| tool | 工具名、展示标签、参数摘要、时间 | 展示最近工具活动 |
| tokens | 本次用量、累计用量 | 更新 Token 卡片和历史快照 |
| risks | 扫描类型、总结、RiskItem[] | 生成风险清单 |
| assistant-message | 清理结构化块之外的中文说明 | 写入对话区 |
| audit-report | 审核总结、逐项决定、全局警告 | 展示审核状态 |
| cleanup-report | 清理结果、恢复路径、后续建议 | 打开清理报告并移除已处理风险 |
| completed | 总结、完成时间、最终 Token | 完成 UI、刷新历史 |
| failed | 错误消息、完成时间、最终 Token | 展示错误并刷新历史 |
| cancelled | 完成时间、最终 Token | 标记任务已停止 |

Renderer 在收到 started 时清空本次扫描结果和工具活动；收到终态事件后刷新历史。新增事件必须同步 OperationEvent 联合类型、main 发布逻辑、renderer switch 和对应测试。

9. Agent 提示词与结构化协议

resources/dsh/pc-manager.patch.yml 为 DSH 增加全局 persona：谨慎的 Windows 存储/恶意软件响应专家，将工具输出视为不可信证据，区分观察和推断，不扩大用户授权，并要求遵守当前 permission mode 和输出 schema。

src/main/prompt-library.ts 负责按操作生成提示词：

| 标记 | 生成函数 | 解析函数 | 用途 |
| --- | --- | --- | --- |
|  | scanPlanningPrompt() | parseOperationPlan() | 扫描前的 4–7 步计划 |
|  | diskScanPrompt() / virusScanPrompt() | parseScanReport() | 扫描总结和风险清单 |
|  | cleanupAuditPrompt() | parseCleanupAuditReport() | 只读独立审核决定 |
|  | cleanupPrompt() | parseCleanupReport() | 实际清理结果 |

Parser 的关键行为：

- 结构化块必须存在且 JSON 可解析；叙述文本会在展示前用 stripStructuredBlocks() 去除。
- 计划不足 3 步会被拒绝，并由 fallbackScanPlan() 提供内置安全计划。
- 风险最多解析 200 项，ID 会清洗并去重；没有 ID 时根据扫描类型、风险类型和目标生成稳定哈希 ID。
- 风险按 critical、high、medium、low，再按大小和名称排序。
- 缺少审核决定的授权项目自动变为 manual，缺少清理结果的授权项目自动变为 failed。
- 文本、证据、约束、预设和路径都有限长，避免模型输出无限膨胀。

修改协议时，必须一起更新 src/shared/types.ts、提示词、parser 和相关测试。不要直接信任模型返回的 ID、路径、状态或“已完成”描述。

10. 设置与本地数据

默认设置如下：

| 设置 | 默认值 | 归一化规则 |
| --- | --- | --- |
| Provider | deepseek-official | 最长 120 字符 |
| Model | deepseek-v4-flash | 最长 200 字符 |
| Base URL | https://api.deepseek.com | 只允许 HTTP/HTTPS，去除末尾斜杠 |
| Reasoning effort | high | off、low、high、max |
| Theme | system | system、light、dark |
| Font scale | 1.0 | 0.75–1.25，步进 0.05；Electron 基准缩放为 1.25 |
| Scan depth | standard | standard 或 deep |
| Network drives | false | 默认拒绝 UNC 网络路径 |
| Quarantine retention | 30 天 | 1–365 天 |
| Telemetry | false | 默认关闭 |

SettingsStore 使用临时文件加 rename() 原子写入，并通过队列串行化设置和 Token 累计写入。API Key 不通过 publicSettings() 返回；用户输入的 Key 使用 Electron safeStorage 加密后保存。没有本地加密值时，开发环境可使用 DEEPSEEK_API_KEY 作为后备。

运行时数据位于 Electron 的 app.getPath('userData')：

~~~text
settings.json                 设置和加密凭据
operation-history.json        最多 80 条操作历史
dsh-runtime/                  DSH 运行时数据
quarantine//     清理操作的隔离区和 manifest
~~~

这些数据是用户本机状态，不应加入源码版本库、测试 fixture 或截图。

11. 输入限制与边界

| 对象 | 限制 |
| --- | --- |
| 同时活动操作 | 1 |
| 单次扫描范围 | 1–16 个绝对路径 |
| 网络范围 | 设置未开启时拒绝 UNC 路径 |
| 单次清理项目 | 1–200 个 |
| 单次对话引用 | 最多 12 个本机文件/目录 |
| 对话文本 | 最多 20,000 字符 |
| 附带风险上下文 | 最多 50 项 |
| 自定义预设 | 最多 20 项，每个 prompt 最长 12,000 字符 |
| 路径补全 | 最多 32 项 |
| 操作历史 | 最多 80 条 |

主进程会重新验证扫描目标和 @ 引用：必须是绝对路径、目标存在、类型匹配，且去重后才会进入 Agent prompt。renderer 传来的风险和清理指令也会在 OperationController 中检查 ID、模式、重复项和手动说明。

12. 开发环境与启动

准备 Windows 10/11、Node.js 22.12+、npm 和可用的 powershell.exe：

~~~powershell
npm ci
npm start
~~~

npm start 会先执行 TypeScript/Vite 构建，再启动 Electron。开发时也可以使用：

~~~powershell
npm run dev
~~~

两者都使用本地 dist/ 和 dist-electron/。npm run preview 只启动 Vite 静态预览，不包含 Electron preload、IPC 和 DSH 子进程，不适合验证完整应用。

启动后，在“设置 → 模型服务”填写 API Key。也可以在启动 Electron 前设置：

~~~powershell
$env:DEEPSEEK_API_KEY = 'local-development-key'
npm start
~~~

不要把真实凭据写进源码、.env、终端日志、测试 fixture 或提交历史。

13. NPM scripts

| 命令 | 作用 |
| --- | --- |
| npm install / npm ci | 安装依赖并执行 Windows DSH 补丁校验 |
| npm run build | tsc -b 后执行 Vite production build |
| npm start | 构建并启动 Electron |
| npm run dev | 构建并启动 Electron 的开发入口 |
| npm run typecheck | 只执行 TypeScript project build 检查 |
| npm test | 运行解析器、连接、路径、历史、补丁和 Markdown 单元测试 |
| npm run test:watch | Vitest watch 模式 |
| npm run test:integration | 启动真实 DSH SDK，连接本地模拟模型服务 |
| npm run test:settings | 构建后启动 Electron 设置持久化冒烟测试 |
| npm run test:hidden-window | 监控集成测试期间是否产生新的可见终端窗口 |
| npm run test:shortcut | 检查打包目录中的 Windows 快捷方式目标和工作目录 |
| npm run icon:render | 用 Electron 渲染图标预览 |
| npm run package:dir | 生成 Windows 免安装目录 |
| npm run package | 生成 NSIS x64 安装器 |

npm run package 使用项目内 .electron-builder-cache/，应用目录输出到 release/win-unpacked/，NSIS 安装器文件名由 package.json 的 artifactName 定义。构建配置关闭了 asar，并将 resources/dsh/pc-manager.patch.yml 作为额外资源放入应用资源目录；如果改动 DSH patch 或打包文件选择，必须同时验证开发和打包两种路径。

14. 测试矩阵

npm test 当前覆盖：

- result-parser.test.ts：标记块、字段归一化、风险排序、审核缺失、清理缺失结果。
- connection-test.test.ts：Base URL 归一化、最小请求、超时。
- path-suggestions.test.ts：目录优先、部分名称匹配。
- history-store.test.ts：Token、审核、清理报告持久化。
- dsh-windows-patch.test.ts：Windows DSH 补丁存在且已应用。
- markdown-render.test.tsx：GFM Markdown 渲染和外链行为。

集成测试使用随机临时目录和本地 HTTP/SSE 模拟模型服务，不访问真实模型 API。它会验证：

1. DSH 通过 PowerShell 读取测试夹具。
2. read-only 会话拒绝写入。
3. 风险结果和 Token 使用可以被解析。
4. 规划阶段先于扫描阶段，并按计划发布进度。
5. 审核 Agent 保持只读，清理 Agent 使用新的 full-access 会话。
6. 授权文件只被精确移动到临时隔离区。

Windows 冒烟脚本会在 20ms 间隔内监控新的 PowerShell、cmd、conhost、OpenConsole 或 Windows Terminal 窗口。测试失败时先检查残留的 Electron、DSH 或终端进程，再重试。

15. UI 冒烟与截图

主进程支持通过环境变量启动真实 Electron 窗口并在渲染完成后截图：

| 环境变量 | 说明 |
| --- | --- |
| DSH_PC_MANAGER_USER_DATA | 覆盖临时 userData，避免读取真实设置和历史 |
| DSH_PC_MANAGER_SMOKE_SCREENSHOT | PNG 输出路径；设置后自动截图并退出 |
| DSH_PC_MANAGER_SMOKE_CLICK | 截图前执行一次 CSS selector click |
| DSH_PC_MANAGER_SMOKE_ACTIONS | JSON action 数组，支持 click 和文本输入，最多 20 个动作 |
| DSH_PC_MANAGER_SMOKE_SAFE_METADATA=1 | 使用 Example-PC、Windows 11 和示例磁盘容量，避免截图泄露设备信息 |

示例：

~~~powershell
$env:DSH_PC_MANAGER_USER_DATA = Join-Path $env:TEMP 'dsh-pc-manager-ui-smoke'
$env:DSH_PC_MANAGER_SMOKE_SCREENSHOT = (Join-Path (Get-Location) 'artifacts\ui-smoke.png')
$env:DSH_PC_MANAGER_SMOKE_SAFE_METADATA = '1'
$env:DSH_PC_MANAGER_SMOKE_ACTIONS = '[{"type":"click","selector":"button[aria-label=\"设置\"]"}]'
& '.\node_modules\.bin\electron.cmd' .
~~~

截图 hook 会等待 .app-shell 出现且 .loading-screen 消失，再额外等待 500ms 执行动作。公开截图应使用独立 userData 和安全元数据模式；不要在截图中显示本机主机名、路径、Token、API Key 或历史记录。

16. 安全开发约定

- 扫描功能默认使用 read-only，只有清理执行阶段可以使用 danger-full-access。
- 所有破坏性动作必须绑定用户明确授权的精确风险 ID；禁止让 Agent 自己扩大范围。
- PowerShell 文件操作使用 -LiteralPath 或等价精确参数；不要拼接未转义的 wildcard 命令。
- 不通过删除系统目录解决空间问题；系统维护项优先给出官方维护命令或人工建议。
- 不读取用户文档、照片、聊天记录等正文来“提高判断准确度”。
- 不把未签名、文件较旧、位于 AppData/Temp 或存在外连单独视为恶意。
- shell.openExternal() 只允许 HTTP/HTTPS；本机路径打开前要做长度和类型检查。
- 新增系统权限、子进程或 IPC 时，必须补充输入验证、错误路径和测试。

17. 扩展功能的修改顺序

新增一种操作或安全能力时，建议按下面顺序修改：

1. 在 src/shared/types.ts 定义输入、输出和事件类型。
2. 在 prompt-library.ts 明确边界、工具范围和结构化输出。
3. 在 result-parser.ts 添加严格解析、限长、去重和缺失字段策略。
4. 在 operation-controller.ts 添加验证、运行时权限和生命周期。
5. 如需页面能力，同步更新 preload.cts、main.ts IPC handler 和 App.tsx。
6. 添加单元测试、集成测试或 Electron 冒烟测试。
7. 执行 typecheck、unit tests、integration tests 和 build；涉及 UI 时重新检查截图。

18. License

MIT，见 LICENSE。

English

1. Project scope

DSH PC Manager 是一个独立的 Electron 桌面应用程序，不是浏览器页面，也不是传统的基于特征库的杀毒软件。它将本地系统观察委托给通过 DeepSeek Harness 运行的 Agents，并将输出转化为用户可以审阅的发现结果。

该应用程序目前提供两种扫描模式：

- 磁盘清理扫描：识别缓存、临时文件、日志、转储、构建产物、过期安装程序、应用程序残留和大文件中可解释的空间风险。
- 病毒相关扫描：关联进程、父子关系、签名、网络连接、防火墙、Defender、启动项、服务、计划任务、注册表和常见持久化位置。

调用方必须明确提供扫描范围。递归文件检查、哈希计算和载荷位置检查仅限于选定的磁盘或目录。进程、网络、Defender 和防火墙等全局运行时状态可以只读方式观察，但不会扩大文件扫描范围。

2. Technology and versions

| Layer | Technology |
| --- | --- |
| Desktop shell | Electron 44 |
| UI | React 19, React DOM, Lucide React |
| Language | TypeScript 5.9 with strict mode |
| Frontend build | Vite 8 with base: './' |
| Agent runtime | @deepseek-ai/dsh 0.1.5-rc.1 |
| Markdown | react-markdown, remark-gfm |
| Tests | Vitest 5, Node HTTP mock server, real Electron/DSH integration tests |
| Windows packaging | electron-builder 26, NSIS x64 |

需要 Node.js >=22.12.0。主进程面向 NodeNext/ES2023，而渲染进程面向 ESNext/ES2022。

3. Architecture

~~~text
┌──────────────────────────────────────────────────────────────┐
│ Renderer: React + TypeScript                                  │
│ App.tsx · styles.css · typed window.pcManager API             │
└──────────────────────────────┬───────────────────────────────┘
│ contextBridge / IPC
┌──────────────────────────────▼───────────────────────────────┐
│ Preload: src/main/preload.cts                                  │
│ Exposes only the allow-listed PcManagerApi                     │
└──────────────────────────────┬───────────────────────────────┘
│ ipcMain.handle / ipcMain.on
┌──────────────────────────────▼───────────────────────────────┐
│ Main: Electron                                                  │
│ main.ts · OperationController · SettingsStore · HistoryStore   │
│ system-overview · connection-test · path-suggestions            │
└───────────────┬──────────────────────────────┬────────────────┘
│ JSON-RPC over stdin/stdout    │ local persistence
┌───────────────▼────────────────────┐  ┌──────▼─────────────────┐
│ DSH 子进程                          │  │ app.getPath('userData') │
│ dsh --profile sdk --patch ...      │  │ settings/history/data  │
│ PowerShell 和文件工具               │  │ quarantine              │
└────────────────────────────────────┘  └────────────────────────┘
~~~

渲染进程没有 Node.js 集成，并使用 contextIsolation 和沙箱。每一项本地能力都必须通过类型化的预加载 API。主进程还会检查 IPC 发送方是否来自本地 file: 页面。

4. 操作生命周期

扫描

~~~text
用户选择目标
│
▼
OperationController.validateScanTargets()
│ 绝对路径、存在性、网络驱动器策略、重复项、限制
▼
创建只读 DshRuntime
│
├─ scanPlanningPrompt()      规划 Agent：4–7 个只读步骤
│       └─ parseOperationPlan(); 失败时 fallbackScanPlan()
│
└─ promptForScan()           扫描 Agent：只读工具和风险 JSON
└─ parseScanReport(); 规范化、限制、去重、排序
│
▼
发布 risks / assistant-message / completed 事件
~~~

清理

~~~text
用户选择发现项并确认
│
▼
创建新的只读 DshRuntime
│
├─ cleanupAuditPrompt()
│       └─ 独立审查 Agent：逐项 allow / deny / manual
│
├─ 没有 allow 项 ──> 跳过所有内容，不进行系统更改
│
└─ 存在 allow 项
│ 关闭审查运行时
▼
创建新的 danger-full-access DshRuntime
│
└─ cleanupPrompt(): 仅限用户明确授权且已审查的目标
└─ parseCleanupReport() -> CleanupReport
~~~

同一时间只能有一个操作处于活动状态。扫描、清理和聊天会创建独立的 DSH 会话；清理审查和清理执行也使用单独的会话。取消操作会关闭 DSH 子进程，并且在 Windows 上必要时使用隐藏的 taskkill.exe 进程树终止。

5. 目录和模块职责

| 路径 | 职责 |
| --- | --- |
| src/main/main.ts | 窗口创建、服务初始化、IPC、UAC 重启、快捷方式、外部链接和 UI 冒烟捕获 |
| src/main/preload.cts | 通过 contextBridge 向渲染进程暴露 PcManagerApi |
| src/main/dsh-runtime.ts | DSH 子进程、JSON-RPC 帧、通知、会话等待、令牌解析和关闭 |
| src/main/operation-controller.ts | 操作互斥、扫描/规划/审查/清理/聊天编排、验证和事件发布 |
| src/main/prompt-library.ts | 内置预设以及所有规划、扫描、审查、清理和聊天提示词 |
| src/main/result-parser.ts | 提取标记 JSON 并规范化计划、风险、审查决策和清理结果 |
| src/main/settings-store.ts | 设置加载、规范化、序列化原子写入、safeStorage 凭据和生命周期令牌 |
| src/main/history-store.ts | 操作事件持久化，最多保留 80 条历史记录 |
| src/main/system-overview.ts | Windows 卷容量、主机信息、根路径和提权状态 |
| src/main/connection-test.ts | 向兼容 Chat Completions 的模型端点发送一次最小请求 |
| src/main/path-suggestions.ts | 为 @ 引用提供本地路径补全 |
| src/shared/types.ts | 共享模型、IPC API、操作事件和令牌类型 |
| src/renderer/App.tsx | UI 状态机、范围选择器、发现项、清理确认、聊天、历史、设置和事件消费 |
| src/renderer/styles.css | 桌面布局、主题、对话框、响应式规则和组件样式 |
| resources/dsh/pc-manager.patch.yml | 注入到每个用户轮次的 DSH 人设和系统边界 |
| tests/ | 解析器、连接、路径、历史、Markdown、设置和真实 DSH 隔离测试 |
| scripts/ | 隐藏窗口、设置、快捷方式、图标和 Windows DSH 补丁工具 |
| docs/screenshots/ | 本 README 使用的浅色主题 UI 截图 |

6. 主进程与 DSH 运行时

DshRuntime 启动的命令等价于：

~~~text
--profile sdk --patch
~~~

默认情况下，运行时可执行文件就是 Electron 本身，以 Node 方式启动，并设置 ELECTRON_RUN_AS_NODE=1。子进程环境包含：

| 变量 | 来源 | 用途 |
| --- | --- | --- |
| DSH_HOME | userData/dsh-runtime | DSH 会话和运行时数据 |
| DSH_PERMISSION_MODE | 操作模式 | read-only 或 danger-full-access |
| DEEPSEEK_API_KEY | SettingsStore/环境 | 模型凭据 |
| DEEPSEEK_BASE_URL | SettingsStore | 模型服务基础 URL |
| DSH_TELEMETRY_DISABLED | 遥测设置 | 禁用遥测时设置为 1 |

stdout 是换行分隔的 JSON-RPC。响应通过数字请求 id 进行匹配；没有 id 的帧是 DSH 通知。session.event 携带工具活动和令牌用量，而 session.status=idle 标记提示完成。仅保留最近的 stderr 尾部用于诊断。

主进程以 windowsHide: true 启动 PowerShell、DSH 和 taskkill.exe，因此系统检查不会创建可见的终端窗口。

7. 渲染进程、预加载与 IPC

渲染进程仅调用 window.pcManager。该接口定义在 src/shared/types.ts 中，在 src/main/preload.cts 中实现，并在 src/main/main.ts 中处理。

| 渲染进程 API | IPC 通道 | 类型 | 用途 |
| --- | --- | --- | --- |
| bootstrap() | pc-manager:bootstrap | invoke | 版本、设置、系统概览、令牌和预设 |
| saveSettings() | pc-manager:settings-save | invoke | 规范化并持久化设置 |
| startScan() | pc-manager:scan-start | invoke | 启动磁盘或病毒扫描 |
| startCleanup() | pc-manager:cleanup-start | invoke | 启动审查和清理工作流 |
| sendChat() | pc-manager:chat-send | invoke | 启动只读聊天操作 |
| cancelOperation() | pc-manager:operation-cancel | invoke | 取消当前操作 |
| testConnection() | pc-manager:connection-test | invoke | 发送最小模型请求 |
| chooseDirectory() | pc-manager:directory-choose | invoke | 打开原生目录选择器 |
| suggestPaths() | pc-manager:path-suggest | invoke | 查询本地路径建议 |
| listHistory() | pc-manager:history-list | invoke | 读取操作历史 |
| createDesktopShortcut() | pc-manager:shortcut-create | invoke | 创建 Windows 桌面快捷方式 |
| requestElevation() | pc-manager:elevation-request | invoke | 请求 UAC 重启 |
| openPath() | pc-manager:path-open | invoke | 使用系统打开本地路径 |
| openExternal() | pc-manager:external-open | invoke | 仅打开 HTTP/HTTPS 外部链接 |
| onOperationEvent() | pc-manager:operation-event | event | 订阅生命周期事件 |
| window. | pc-manager:window- | send | 最小化、最大化/还原和关闭 |

添加 IPC 时，请同时更新共享类型、预加载允许列表、主进程处理器和渲染进程调用方。保留 assertRenderer()。不要向页面暴露 ipcRenderer、Node API 或任意 shell 能力。

8. 共享事件模型

所有后台操作都通过 OperationEvent 更新 UI 和历史记录，并通过 operationId 进行关联：

| 事件 | 主要字段 | 消费者 |
| --- | --- | --- |
| started | 类型、模型、推理级别、目标/已授权项 | 初始化 UI 和历史记录 |
| plan | OperationPlan | 显示 Agent 计划 |
| progress | 阶段、消息、百分比、计划步骤 | 进度面板 |
| tool | 工具名称、标签、参数摘要、时间戳 | 最近工具活动 |
| tokens | 操作和生命周期用量 | Token 卡片和历史快照 |
| risks | 扫描类型、摘要、RiskItem[] | 发现列表 |
| assistant-message | 结构化块之外的叙述 | 聊天区域 |
| audit-report | 摘要、决策和全局警告 | 审查状态 |
| cleanup-report | 结果、还原路径和后续操作 | 清理报告和发现项移除 |
| completed | 摘要、完成时间和最终用量 | 完成状态和历史刷新 |
| failed | 错误、完成时间和最终用量 | 错误状态和历史刷新 |
| cancelled | 完成时间和最终用量 | 已取消状态 |

渲染进程在 started 时清除当前扫描发现项和工具活动，然后在终止事件时刷新历史记录。新事件必须更新共享联合类型、主进程发布逻辑、渲染进程 switch 和测试。

9. Agent 提示词和结构化协议

resources/dsh/pc-manager.patch.yml 添加了一个全局角色：一位谨慎的 Windows 存储和恶意软件响应专家，将工具输出视为不可信证据，区分观察与推断，绝不扩大用户授权范围，并遵循当前权限模式和 schema。

src/main/prompt-library.ts 生成特定于操作的提示词：
| 标记 | 生成器 | 解析器 | 用途 |
| --- | --- | --- | --- |
|  | scanPlanningPrompt() | parseOperationPlan() | 扫描前的 4–7 步计划 |
|  | diskScanPrompt() / virusScanPrompt() | parseScanReport() | 扫描摘要和发现项 |
|  | cleanupAuditPrompt() | parseCleanupAuditReport() | 独立的只读审查 |
|  | cleanupPrompt() | parseCleanupReport() | 实际清理结果 |

解析器保证包括：

- 必须存在一个结构化块并包含有效的 JSON；叙述性文本在显示前通过 stripStructuredBlocks() 移除。
- 少于三个步骤的计划会被拒绝，并由 fallbackScanPlan() 替换。
- 最多解析 200 个发现项。ID 会被清理和去重；缺失的 ID 会根据扫描类型、风险类型和目标获得一个稳定的哈希值。
- 发现项按严重程度 critical、high、medium、low 排序，然后按大小和名称排序。
- 缺失的审计决策变为 manual；缺失的清理结果变为 failed。
- 文本、证据、约束、预设和路径都受长度限制，以防止模型输出无界。

更改协议时，请同时更新 src/shared/types.ts、提示词、解析器和测试。在没有验证的情况下，绝不要信任模型提供的 ID、路径、状态或完成声明。

10. 设置和本地数据

默认设置：

| 设置 | 默认值 | 规范化 |
| --- | --- | --- |
| 提供商 | deepseek-official | 最多 120 个字符 |
| 模型 | deepseek-v4-flash | 最多 200 个字符 |
| 基础 URL | https://api.deepseek.com | 仅限 HTTP/HTTPS；去除末尾斜杠 |
| 推理强度 | high | off、low、high、max |
| 主题 | system | system、light、dark |
| 字体缩放 | 1.0 | 0.75–1.25，步长 0.05；Electron 基础缩放为 1.25 |
| 扫描深度 | standard | standard 或 deep |
| 网络驱动器 | false | 默认拒绝 UNC 路径 |
| 隔离保留期 | 30 天 | 限制在 1–365 |
| 遥测 | false | 默认禁用 |

SettingsStore 通过临时文件和 rename() 写入以实现原子持久化，并通过队列串行化设置/令牌写入。API 密钥不会由 publicSettings() 返回；用户输入的密钥使用 Electron safeStorage 加密。当不存在加密值时，DEEPSEEK_API_KEY 可作为开发回退使用。

运行时数据位于 Electron 的 app.getPath('userData') 下：

~~~text
settings.json                 设置和加密凭据
operation-history.json        最多 80 条操作历史记录
dsh-runtime/                  DSH 运行时数据
quarantine//     清理隔离区和清单
~~~

这些是本地用户状态文件，不得添加到源代码仓库、测试夹具或截图中。

11. 输入限制和边界

| 对象 | 限制 |
| --- | --- |
| 活动操作 | 1 |
| 扫描目标 | 1–16 个绝对路径 |
| 网络目标 | 除非启用，否则拒绝 UNC 路径 |
| 清理项 | 1–200 |
| 聊天引用 | 最多 12 个本地文件/目录 |
| 聊天消息 | 最多 20,000 个字符 |
| 附加风险上下文 | 最多 50 项 |
| 自定义预设 | 最多 20 个；每个提示最多 12,000 个字符 |
| 路径建议 | 最多 32 个 |
| 操作历史 | 最多 80 条记录 |

主进程会重新验证扫描目标和 @ 引用：它们必须是绝对路径、存在、具有预期类型，并且在进入 Agent 提示之前是唯一的。渲染器提供的风险和清理指令也会由 OperationController 检查 ID、模式、重复项和手动指令。

12. 开发环境设置

使用 Windows 10/11、Node.js 22.12+、npm 以及可用的 powershell.exe：

~~~powershell
npm ci
npm start
~~~

npm start 会先构建 TypeScript/Vite，然后启动 Electron。开发入口也可用：

~~~powershell
npm run dev
~~~

两个命令都使用本地的 dist/ 和 dist-electron/。npm run preview 仅提供 Vite 输出，不提供 Electron 预加载、IPC 或 DSH 子进程，因此它不是完整的应用程序检查。

在 Settings → Model Service 中配置模型，或在启动 Electron 之前设置开发回退：

~~~powershell
$env:DEEPSEEK_API_KEY = 'local-development-key'
npm start
~~~

切勿将真实凭据放入源代码、.env、终端日志、测试夹具或提交历史中。

13. NPM 脚本

| 命令 | 用途 |
| --- | --- |
| npm install / npm ci | 安装依赖并验证 Windows DSH 补丁 |
| npm run build | 运行 tsc -b，然后进行 Vite 生产构建 |
| npm start | 构建并启动 Electron |
| npm run dev | 构建并启动开发 Electron 入口 |
| npm run typecheck | TypeScript 项目构建检查 |
| npm test | 解析器、连接、路径、历史、补丁和 Markdown 单元测试 |
| npm run test:watch | Vitest 监视模式 |
| npm run test:integration | 使用本地模拟模型服务的真实 DSH SDK |
| npm run test:settings | 构建并运行 Electron 设置持久化冒烟测试 |
| npm run test:hidden-window | 在集成期间监控新出现的可见终端窗口 |
| npm run test:shortcut | 在打包目录中验证 Windows 快捷方式目标和工作目录 |
| npm run icon:render | 使用 Electron 渲染图标预览 |
| npm run package:dir | 生成未打包的 Windows 目录 |
| npm run package | 生成 NSIS x64 安装程序 |

npm run package 使用 .electron-builder-cache/，将未打包的应用程序写入 release/win-unpacked/，并通过 package.json 的 artifactName 命名 NSIS 安装程序。当前打包配置禁用 asar，并将 resources/dsh/pc-manager.patch.yml 作为额外资源复制。对 DSH 补丁或打包文件选择的更改必须在开发路径和打包路径中都进行验证。

14. 测试矩阵

npm test 目前涵盖：
- result-parser.test.ts：标记、规范化、排序、缺失的审查决策和缺失的清理结果。
- connection-test.test.ts：Base URL 规范化、最小请求和超时处理。
- path-suggestions.test.ts：目录优先排序和部分名称匹配。
- history-store.test.ts：令牌、审查报告和清理报告的持久化。
- dsh-windows-patch.test.ts：Windows DSH 补丁的存在和应用。
- markdown-render.test.tsx：GFM Markdown 和外部链接行为。

集成测试套件使用随机临时目录和本地 HTTP/SSE 模拟模型服务；它不会联系真实的模型 API。它验证：

1. DSH 通过 PowerShell 读取测试夹具。
2. read-only 会话拒绝写入。
3. 发现项和令牌用量被解析。
4. 规划在扫描之前进行，进度遵循计划。
5. 审查 Agent 保持只读，清理使用新的完全访问会话。
6. 只有授权的夹具被移动到临时隔离区。

Windows 冒烟脚本每 20ms 监控一次新的 PowerShell、cmd、conhost、OpenConsole 或 Windows Terminal 窗口。如果失败，请在重试前检查残留的 Electron、DSH 或终端进程。

15. UI 冒烟测试和截图

主进程可以启动真实的 Electron 窗口，并在渲染器就绪后捕获 PNG：

| 变量 | 描述 |
| --- | --- |
| DSH_PC_MANAGER_USER_DATA | 覆盖临时 userData 以避免真实的设置/历史记录 |
| DSH_PC_MANAGER_SMOKE_SCREENSHOT | PNG 输出路径；设置后捕获并退出 |
| DSH_PC_MANAGER_SMOKE_CLICK | 捕获前点击一个 CSS 选择器 |
| DSH_PC_MANAGER_SMOKE_ACTIONS | 包含 click 和文本输入的 JSON 操作列表，最多 20 个操作 |
| DSH_PC_MANAGER_SMOKE_SAFE_METADATA=1 | 使用 Example-PC、Windows 11 和示例磁盘容量 |

示例：

~~~powershell
$env:DSH_PC_MANAGER_USER_DATA = Join-Path $env:TEMP 'dsh-pc-manager-ui-smoke'
$env:DSH_PC_MANAGER_SMOKE_SCREENSHOT = (Join-Path (Get-Location) 'artifacts\ui-smoke.png')
$env:DSH_PC_MANAGER_SMOKE_SAFE_METADATA = '1'
$env:DSH_PC_MANAGER_SMOKE_ACTIONS = '[{"type":"click","selector":"button[aria-label=\"设置\"]"}]'
& '.\node_modules\.bin\electron.cmd' .
~~~

捕获钩子等待 .app-shell，等待 .loading-screen 消失，然后再等待 500ms 后应用操作。对于公开截图，请使用隔离的 userData 目录和安全元数据。不要在截图中显示主机名、本地路径、令牌历史记录、API 密钥或操作历史记录。

16. 安全开发约定

- 默认将扫描保持在 read-only 模式；只有清理执行可以使用 danger-full-access。
- 将每个破坏性操作绑定到精确的用户授权风险 ID；绝不让 Agent 扩大范围。
- 对 PowerShell 文件操作使用 -LiteralPath 或等效的精确参数；不要从未转义的字符串构建破坏性通配符命令。
- 不要通过删除系统目录来解决磁盘压力；优先使用官方维护命令或手动建议。
- 不要读取个人文档、照片或聊天内容来改进分类。
- 不要仅因为某个项目未签名、陈旧、位于 AppData/Temp 下或与某个连接相关联就将其归类为恶意。
- 在 shell.openExternal() 中仅允许 HTTP/HTTPS，并在打开本地路径前对其进行验证。
- 新的系统权限、子进程或 IPC 需要输入验证、错误路径和测试。

17. 扩展工作流

添加操作或安全能力时：

1. 在 src/shared/types.ts 中定义输入、输出和事件类型。
2. 在 prompt-library.ts 中定义边界、工具范围和结构化输出。
3. 在 result-parser.ts 中添加严格解析、限制、去重和缺失字段行为。
4. 在 operation-controller.ts 中添加验证、运行时权限和生命周期处理。
5. 如果 UI 需要该能力，更新 preload.cts、main.ts IPC 处理器和 App.tsx。
6. 添加单元测试、集成测试或 Electron 冒烟测试覆盖。
7. 运行类型检查、单元测试、集成测试和构建；为 UI 变更刷新截图。

18. 许可证

MIT。参见 LICENSE。