SuperDiagnosticTool

SuperDiagnosticTool 图标

AI 驱动的 Windows 诊断与修复工具

SuperDiagnosticTool 采集实时硬件遥测数据，将其发送至 Google Gemini API 进行分析，并生成 PowerShell 修复脚本以解决检测到的问题。它包含多层验证机制，生成的脚本必须通过这些验证，才会提示用户执行。

截图

主界面

主界面，显示扫描模式选择与问题描述输入

核心功能

通用硬件支持

动态扩展： 自动适配任意 CPU 配置（1-128+ 核心）
硬件无关逻辑： 从老旧系统（Intel Pentium）到高端工作站（AMD Threadripper、Intel Xeon）均可运行
优雅降级： 安全处理不受支持的硬件查询（CPU 频率、电池、交换内存）
低配优化： 轻量级执行，避免对资源受限的硬件造成压力

智能 AI 分析

Google Gemini 集成： 通过 Gemini API 进行 AI 驱动的系统分析与诊断
上下文感知建议： 将用户报告的问题与采集到的系统遥测数据相关联
安全审计： 扫描可疑进程、资源泄漏及潜在的恶意软件迹象
修复后验证： 生成完成报告，区分自动化修复项与需人工处理项

多层安全架构

Gemini 生成的脚本在提示用户批准执行前，需依次通过四项检查：

验证流水线

知识库匹配： 将 AI 解决方案与一组经过测试、已知良好的修复模式进行交叉比对
试运行模拟： 在任何修改发生前，预览所有预期变更（服务、文件、注册表）
脚本验证（ScriptValidator）： 三级检查——黑名单（对破坏性模式硬性拦截）、可疑模式检测（可识别别名与混淆）、以及 0-100 分制的风险评分
关键路径拦截（CriticalPathInterceptor）： 零信任关卡，任何触及 HKLM/HKCU 注册表键或 System32 路径的脚本都会被暂停，直到用户明确确认

安全限制

系统还原点： 在任何修改前自动创建
执行前后快照： 完整捕获系统状态，以检测并记录每一处变更
回滚生成： 若执行失败，自动生成选择性回滚脚本
执行日志： 每个操作均带时间戳记录至 %TEMP%\superdiagnostic_execution_*.log

PowerShell 执行

管理员权限验证： 脚本在继续执行前会检查是否已提升权限
变量清理： 基于正则表达式的转义可保留 $env: 变量且不会产生语法错误
服务安全检查： 在执行任何 Start/Stop/Set 操作前验证服务是否存在
受监控执行： 脚本通过 subprocess.run 运行，设有 5 分钟硬性超时、完整捕获 stdout/stderr，并自动清理临时文件。这是直接在主机层面执行，而非虚拟机或容器隔离。上述验证层是主要的安全边界。
错误处理： PowerShell 包装器包含 try/catch/finally 块，并逐行报告错误

全面的系统扫描

性能指标： CPU 使用率（总体 + 每核心）、内存明细、资源占用最高的进程
网络情报： 活动接口、DNS 配置、Wi-Fi 信号强度、连通性测试
安全完整性： 防病毒状态、防火墙配置文件、Windows 更新历史
硬件健康： 磁盘 SMART 状态、GPU 信息、电池状态（笔记本电脑）
系统服务： 启动应用程序、失败的服务、关键事件日志
进程审计： 识别资源使用异常或文件位置异常的进程

以人为本的报告

专业 HTML 报告： 深色主题、响应式诊断报告，包含可视化指标
过去时完成语态： 报告使用 [FIXED]、[CLEANED]、[DISABLED] 标签来反映已完成的动作
需人工关注部分： 清晰区分自动修复项与需要用户干预的项
带时间戳的归档： 所有报告保存至 AI_Reports/ 以便历史追踪

快速开始

下载

下载 SuperDiagnosticTool.exe — 独立可执行文件（无需 Python）

该可执行文件未签名。首次运行时 Windows SmartScreen 会显示警告。请参阅 TRUST_GUIDE.md 了解如何继续。如果你希望在运行前进行验证，请改为从源代码构建。

环境要求

Windows 10 或 Windows 11
管理员权限（系统遥测和修复所需）
Google Gemini API 密钥（获取免费密钥）

首次运行

下载并运行 SuperDiagnosticTool.exe
在提示时输入你的 Google Gemini API 密钥
描述你的系统问题
选择扫描模式（快速 / 深度 / 完整）
查看 AI 分析和生成的修复脚本
批准执行或查看详细的 HTML 报告

安装（面向开发者）

先决条件

Python 3.8 或更高版本
pip 包管理器

安装依赖

创建一个虚拟环境，使该工具的依赖与其他 Python 项目保持隔离：

python -m venv .venv

在 Windows 命令提示符中激活它，然后安装仓库列出的依赖项：

.venv\Scripts\activate
pip install -r requirements.txt

在 PowerShell 中，使用以下命令激活环境：

.\.venv\Scripts\Activate.ps1

如果 PowerShell 阻止激活脚本，请以当前用户身份打开 PowerShell 并运行一次 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，然后再次尝试激活命令。

从源码运行

python super_diagnose_v2.py

要确认在开始扫描之前源代码树和依赖项已准备就绪，请运行：

python -m compileall src super_diagnose_v2.py

该命令应能无错误完成。该工具在运行时仍需要 Windows 和管理员权限，因为若干诊断功能会使用 PowerShell 和受保护的系统信息。

用法

API 密钥设置

选项 A：交互式输入（推荐首次使用时采用）

工具在首次运行时提示输入 API 密钥
在可用时，密钥通过 Windows DPAPI（keyring）安全存储

选项 B：环境变量 命令提示符：

set GEMINI_API_KEY=your_api_key_here

PowerShell：

$env:GEMINI_API_KEY = "your_api_key_here"

选项 C：手动密钥文件 在工具目录中创建 gemini.key：

your_api_key_here

扫描模式

模式	扫描内容	使用场景
快速扫描	CPU、RAM、基本信息	快速性能检查
深度扫描	系统、网络、安全、日志、蓝牙、进程	全面故障排查
完整扫描	以上所有内容 + 磁盘健康、GPU、启动应用	完整系统审计

示例工作流程

1. Run the tool
   > SuperDiagnosticTool.exe

2. Describe your issue
   > High CPU usage and slow performance

3. Select scan mode
   > 3 (Complete System Scan)

4. Wait for AI analysis
   [Scanning system layers...]
   [Processing telemetry...]

5. Review the generated remediation script
   > Execute? (y/n)

6. View the HTML report
   > Open detailed report? (y/n)

技术细节

代码架构

模块化设计——每个诊断类别都是独立的函数
全面的错误处理，全程使用 try/except 块
硬件无关的查询，对不支持的功能提供优雅降级
所有公共类和方法均带有标准 Python 文档字符串

PowerShell 脚本生成

执行前验证管理员权限
基于正则表达式的变量转义，防止语法错误
环境变量（$env:TEMP、$env:PATH）被正确保留
安全的服务管理，每次操作前均进行存在性检查

Gemini AI 集成

使用分隔段（[ANALYSIS_START]、[FIX_START]）的结构化提示词，以实现可靠的输出解析
基于收集的系统遥测快照进行上下文感知分析
对已完成的修复操作采用过去时报告惯例

安全与隐私

保留在你机器上的内容

所有系统扫描和分析均在本地运行。
本工具不会将任何遥测数据存储到外部服务器。

发送到外部的数据

为生成 AI 建议，遥测快照（CPU 负载、内存、进程名称、事件日志条目、网络状态）会被传输至 Google 的 Gemini API。
你的 API 密钥会随每次请求一并发送给 Google。
请查阅 Google 隐私政策了解其如何处理这些数据。

其他安全特性

API 密钥存储： 在可用时通过 Windows DPAPI（keyring）存储。绝不提交到版本控制。
管理员透明度： 每个修复脚本都会完整显示，并在执行前需要用户明确批准。
默认非破坏性： 注册表和文件修改需要通过 CriticalPathInterceptor 检查并获得用户明确确认。
开源： 完整源代码可在 GPL v3.0 下供独立审查。

更多安全文档请参见 SECURITY.md。

故障排除

“API 密钥无效”错误

在 Google AI Studio 验证密钥是否正确且有效
检查密钥中是否含有隐藏的空白字符或换行符
确保该密钥已启用 Gemini API 访问权限

“未以管理员身份运行”

右键单击可执行文件并选择“以管理员身份运行”
或在工具请求提权时允许 UAC 提示

“找不到模块”错误（Python 版本）

pip install --upgrade psutil google-generativeai rich

PowerShell 脚本执行失败

确保已安装 Windows PowerShell 5.1 或更高版本
生成的脚本会保存到 AI_Reports/remediation.ps1 — 请手动检查其中是否有错误

从源码构建

自动化构建（推荐）

本项目使用 GitHub Actions 在推送版本标签时构建 Windows 可执行文件：

将你的更改推送到主分支

创建并推送一个版本标签：

git tag -a v1.0.2 -m "Release notes" && git push origin v1.0.2

GitHub Actions 构建 .exe 并自动创建发布版本
从 Releases 页面下载

有关发布工作流配置，请参见 .github/workflows/release.yml。

手动构建（用于测试）

pip install pyinstaller
pip install -r requirements.txt
python build.py

这会生成带有内嵌图标和依赖项的 dist/SuperDiagnosticTool.exe。