guettaf-hossam/superdiagnostictoolAI 驱动的 Windows 诊断与自动修复工具，基于 Google Gemini。可检测崩溃、优化性能、扫描恶意软件，并生成 PowerShell 修复脚本。支持通用硬件（1-128+ 核心）。免费且开源。
# SuperDiagnosticTool <p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/11160/8b0da1a673733dc9731164bd4d4a3ecc6a137e583d070725852e8173311ef7fc.png" alt="SuperDiagnosticTool 图标" width="200"/> </p> <p align="center"> <strong>AI 驱动的 Windows 诊断与修复工具</strong> </p> <p align="center"> <a href="https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases"><img src="https://img.shields.io/github/v/release/Guettaf-hossam/SuperDiagnosticTool?style=flat-square" alt="Release"></a> <a href="https://github.com/Guettaf-hossam/SuperDiagnosticTool/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-GPL%20v3.0-blue.svg?style=flat-square" alt="License"></a> <a href="https://github.com/Guettaf-hossam/SuperDiagnosticTool/stargazers"><img src="https://img.shields.io/github/stars/Guettaf-hossam/SuperDiagnosticTool?style=flat-square" alt="Stars"></a> </p> SuperDiagnosticTool 采集实时硬件遥测数据，将其发送至 Google Gemini API 进行分析，并生成 PowerShell 修复脚本以解决检测到的问题。它包含多层验证机制，生成的脚本必须通过这些验证，才会提示用户执行。 --- ## 截图 <p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/11160/eb10d4e2a86193e87d0face0e034418d7a5977df9057fb6fed97b0ea705e4442.png" alt="主界面" width="800"/> </p> *主界面，显示扫描模式选择与问题描述输入* --- ## 核心功能 ### 通用硬件支持 - **动态扩展：** 自动适配任意 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](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases/latest)** — 独立可执行文件（无需 Python） > 该可执行文件未签名。首次运行时 Windows SmartScreen 会显示警告。请参阅 [TRUST_GUIDE.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/TRUST_GUIDE.md) 了解如何继续。如果你希望在运行前进行验证，请改为从源代码构建。 ### 环境要求 - Windows 10 或 Windows 11 - 管理员权限（系统遥测和修复所需） - Google Gemini API 密钥（[获取免费密钥](https://aistudio.google.com/app/apikey)） ### 首次运行 1. 下载并运行 `SuperDiagnosticTool.exe` 2. 在提示时输入你的 Google Gemini API 密钥 3. 描述你的系统问题 4. 选择扫描模式（快速 / 深度 / 完整） 5. 查看 AI 分析和生成的修复脚本 6. 批准执行或查看详细的 HTML 报告 --- ## 安装（面向开发者） ### 先决条件 - Python 3.8 或更高版本 - pip 包管理器 ### 安装依赖 创建一个虚拟环境，使该工具的依赖与其他 Python 项目保持隔离： ```bash python -m venv .venv ``` 在 Windows 命令提示符中激活它，然后安装仓库列出的依赖项： ```bat .venv\Scripts\activate pip install -r requirements.txt ``` 在 PowerShell 中，使用以下命令激活环境： ```powershell .\.venv\Scripts\Activate.ps1 ``` 如果 PowerShell 阻止激活脚本，请以当前用户身份打开 PowerShell 并运行一次 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`，然后再次尝试激活命令。 ### 从源码运行 ```bash python super_diagnose_v2.py ``` 要确认在开始扫描之前源代码树和依赖项已准备就绪，请运行： ```bash python -m compileall src super_diagnose_v2.py ``` 该命令应能无错误完成。该工具在运行时仍需要 Windows 和管理员权限，因为若干诊断功能会使用 PowerShell 和受保护的系统信息。 --- ## 用法 ### API 密钥设置 **选项 A：交互式输入（推荐首次使用时采用）** - 工具在首次运行时提示输入 API 密钥 - 在可用时，密钥通过 Windows DPAPI（`keyring`）安全存储 **选项 B：环境变量** 命令提示符： ```bat set GEMINI_API_KEY=your_api_key_here ``` PowerShell： ```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 隐私政策](https://policies.google.com/privacy) 了解其如何处理这些数据。 ### 其他安全特性 - **API 密钥存储：** 在可用时通过 Windows DPAPI（`keyring`）存储。绝不提交到版本控制。 - **管理员透明度：** 每个修复脚本都会完整显示，并在执行前需要用户明确批准。 - **默认非破坏性：** 注册表和文件修改需要通过 `CriticalPathInterceptor` 检查并获得用户明确确认。 - **开源：** 完整源代码可在 GPL v3.0 下供独立审查。 更多安全文档请参见 [SECURITY.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/SECURITY.md)。 --- ## 故障排除 ### “API 密钥无效”错误 - 在 [Google AI Studio](https://aistudio.google.com/app/apikey) 验证密钥是否正确且有效 - 检查密钥中是否含有隐藏的空白字符或换行符 - 确保该密钥已启用 Gemini API 访问权限 ### “未以管理员身份运行” - 右键单击可执行文件并选择“以管理员身份运行” - 或在工具请求提权时允许 UAC 提示 ### “找不到模块”错误（Python 版本） ```bash pip install --upgrade psutil google-generativeai rich ``` ### PowerShell 脚本执行失败 - 确保已安装 Windows PowerShell 5.1 或更高版本 - 生成的脚本会保存到 `AI_Reports/remediation.ps1` — 请手动检查其中是否有错误 --- ## 从源码构建 ### 自动化构建（推荐） 本项目使用 GitHub Actions 在推送版本标签时构建 Windows 可执行文件： 1. 将你的更改推送到主分支 2. 创建并推送一个版本标签： ```bash git tag -a v1.0.2 -m "Release notes" && git push origin v1.0.2 ``` 3. GitHub Actions 构建 `.exe` 并自动创建发布版本 4. 从 [Releases 页面](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases) 下载 有关发布工作流配置，请参见 [`.github/workflows/release.yml`](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/.github/workflows/release.yml)。 ### 手动构建（用于测试） ```bash pip install pyinstaller pip install -r requirements.txt python build.py ``` 这会生成带有内嵌图标和依赖项的 `dist/SuperDiagnosticTool.exe`。 ### 文件结构 ``` SuperDiagnosticTool/ ├── super_diagnose_v2.py # Main entry point and diagnostic logic ├── build.py # PyInstaller build script ├── icon.ico # Application icon ├── .github/workflows/ │ └── release.yml # Automated build and release workflow ├── docs/ │ ├── icon.png │ └── screenshot_main.png ├── src/ │ ├── safety/ # Script validation and monitored execution │ │ ├── validator.py # ScriptValidator + CriticalPathInterceptor │ │ ├── sandbox.py # SandboxExecutor (monitored subprocess runner) │ │ ├── dry_run.py # DryRunSimulator │ │ ├── restore_point.py # RestorePointManager │ │ ├── enhanced_monitoring.py │ │ └── knowledge_base.py │ └── security/ # CredentialVault (DPAPI-backed key storage) ├── AI_Reports/ # Generated HTML reports and remediation scripts ├── README.md ├── SECURITY.md ├── TRUST_GUIDE.md ├── LICENSE # GPL-3.0 └── .gitignore ``` ## 免责声明 此工具会生成并执行用于修改系统服务、配置和注册表值的 PowerShell 脚本。在批准任何修复脚本之前： - **阅读完整脚本** — 脚本会在允许执行前显示 - 在运行自动修复之前**备份关键数据** - 如果更改范围不明确，**在非关键系统上进行测试** 对于因使用此工具而导致的系统损坏、数据丢失或意外后果，作者不承担责任。 --- ## 贡献 欢迎贡献。贡献方式： 1. Fork 仓库 2. 创建功能分支（`git checkout -b feature/improvement`） 3. 提交更改（`git commit -m 'Add improvement'`） 4. 推送到分支（`git push origin feature/improvement`） 5. 打开 Pull Request --- ## 许可证 本项目采用 **GNU General Public License v3.0** 许可证 — 详情请参阅 [LICENSE](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/LICENSE) 文件。 Copyright (C) 2026 GUETTAF HOUSSEM EDDINE --- ## 作者 **Guettaf Houssem Eddine** 电工技术工程专业学生 Akli Mohand Oulhadj University, Bouira, Algeria 邮箱：[email protected] GitHub：[@Guettaf-hossam](https://github.com/Guettaf-hossam) --- ## 致谢 - **Google Gemini AI** 提供系统分析能力 - **psutil** 提供跨平台系统遥测 - **Rich** 提供终端 UI 渲染 --- <p align="center"> <strong>Version 1.0</strong> | 最后更新：2026 年 8 月 </p> <p align="center"> Akli Mohand Oulhadj University, Bouira, Algeria </p>
