# 沧溟 - 微澜

**Repository Path**: fangyu_fy/mem-sight

## Basic Information

- **Project Name**: 沧溟 - 微澜
- **Description**: 一款轻量级 Windows 桌面监控工具：实时监控多进程 CPU / 内存 / 句柄 / 线程，透视 .NET 进程的 GC 分代与 LOH，并能对托管堆拍摄对象级快照做 Diff 对比，直接定位内存泄漏嫌疑最大的类型。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MemSight · Windows 进程深度监控工具

> 当前版本：**0.9 beta**

任务管理器只能告诉你「内存涨了多少」，MemSight 回答「**是哪个对象在涨**」。

一款轻量级 Windows 桌面监控工具：实时监控多进程 CPU / 内存 / 句柄 / 线程，透视 .NET 进程的 GC 分代与 LOH，并能对托管堆拍摄**对象级快照**做 Diff 对比，直接定位内存泄漏嫌疑最大的类型。

## 功能特性

- **进程发现与多目标监控**：全量进程列表（3s 增量刷新），按名称 / PID 搜索过滤，勾选即监控；当目标进程重启后按名称自动重绑定到新 PID
- **L1 宏观指标（1s 采样）**：CPU（双采样点时间差算法，多核折算）、工作集、私有字节、虚拟内存、句柄数、线程数
- **L2 .NET 透视（3s 采样）**：Gen 0/1/2 堆大小、LOH、GC 次数（CLR 性能计数器，PID 动态映射实例名）；非托管内存估算 = 私有字节 − 托管堆总量
- **L3 托管堆快照（核心）**：ClrMD 附加目标进程，一次堆遍历即时聚合为「类型 → (数量, 字节)」；双快照 Diff 按 ΔBytes 降序排列，新增类型高亮，列头点击排序
- **阈值告警**：当 CPU / 内存超过阈值时播放提示音，可配置超标自动拍摄快照（60s 告警冷却 / 5min 自动快照冷却）
- **导出**：监控数据导出 CSV；快照 Diff 导出 JSON / HTML 报告
- **架构兼容**：主程序为 x64，内嵌 32 位 Helper（Named Pipes IPC），可采集 x86 .NET 进程
- **体验**：关闭窗口时确认「退出 / 最小化到托盘 / 取消」；快照期间目标进程冻结，有明确提示并支持强制取消

界面为三个 Tab 页：**进程与监控**（进程列表 + 监控面板）、**趋势**（CPU / 内存双图 + GridSplitter）、**托管堆快照**（拍摄 / 列表 / Diff 表 / 导出）。

## 技术栈

| 模块 | 选型 | 版本 |
| :--- | :--- | :--- |
| UI 框架 | Avalonia UI | 12.1.2 |
| 组件体系 | AtomUI（Ant Design 6 视觉）+ FluentTheme 兜底 | 6.1.9 |
| 数据表格 | AtomUI DataGrid（`IDataGridSource` 虚拟化数据源） | 6.1.9 |
| 图表 | LiveCharts2 (SkiaSharp) | 2.1.0-dev |
| MVVM | CommunityToolkit.Mvvm（源生成器） | 8.4.2 |
| 深度内存分析 | Microsoft.Diagnostics.Runtime (ClrMD) | 4.1 |
| DI / 日志 | Microsoft.Extensions.DependencyInjection / Serilog | 10.0 / 4.4 |
| 目标框架 | .NET 10（net10.0-windows），x64 | SDK 10.0.401 |
| 序列化 | System.Text.Json **源生成**（无反射） | — |

> 技术选型演进（Req.md 初稿为 WPF，已调整为 Avalonia + AtomUI）及各难点决策见 [docs/adr](docs/adr)。

## 快速开始

环境要求：Windows 10/11 x64，.NET SDK 10.0.401+。

```bash
# 还原 + 构建（Helper.x86 不在解决方案中，主项目构建时自动发布并嵌入）
dotnet build Cangming.MemSight.slnx

# 运行
dotnet run --project src/Cangming.MemSight

# 单文件发布（推荐分发方式，产物含 helper-x86/ 目录）
dotnet publish src/Cangming.MemSight/Cangming.MemSight.csproj -c Release -r win-x64 \
  --self-contained -p:PublishSingleFile=true
```

### 制作安装包（Inno Setup）

环境要求：Inno Setup 6（脚本以 `ISCC.exe` 位于 `C:\Program Files (x86)\Inno Setup 6\` 为准）。

```bash
# 1. 先发布到 artifacts/publish
dotnet publish src/Cangming.MemSight/Cangming.MemSight.csproj -c Release -r win-x64 \
  --self-contained -p:PublishSingleFile=true -o artifacts/publish

# 2. 编译安装包（产物：artifacts/installer/MemSight-Setup-0.9-beta.exe）
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer/MemSight.iss
```

安装包为**每用户安装**（免管理员），默认目录 `%LocalAppData%\Programs\MemSight`，含开始菜单快捷方式与可选桌面图标。

> Git Bash 环境提示：由于该 shell 缺少部分 Windows 环境变量，当 dotnet 命令出现异常时，在命令前注入 `OS=Windows_NT` 等变量即可。

`samples/LeakSample` 是内置的内存泄漏示例程序，可用于验证快照 Diff：对 LeakSample 连拍两次快照后，Diff 榜首应为 `System.Byte[]`。

## 项目结构

```
├─ Cangming.MemSight.slnx          # 解决方案（主项目 + LeakSample）
├─ Req.md                      # 需求分析与技术路线说明
├─ docs/
│  ├─ adr/                     # 架构决策记录（ADR-001~005）
│  └─ plans/phase-plan.md      # 四阶段实施计划
├─ src/
│  ├─ Cangming.MemSight/           # 主程序（x64）
│  │  ├─ Services/             # 进程发现 / 指标采集 / GC 指标 / 快照 / 告警
│  │  ├─ ViewModels/           # MVVM 视图模型（源生成器属性与命令）
│  │  ├─ Models/               # 数据模型
│  │  ├─ Infrastructure/       # 日志、导出、格式化、系统声音
│  │  └─ MainWindow.axaml      # 三 Tab 主界面
│  ├─ Cangming.MemSight.Helper.x86/# 32 位快照 Helper（Named Pipes，随主程序嵌入）
│  └─ Shared/                  # 主程序与 Helper 共用的堆聚合器 + 快照 JSON 格式
├─ samples/LeakSample/         # 内存泄漏示例（验收用）
└─ tools/                      # Phase3 / Phase4 自动化验收脚本
```

## 核心设计（摘要）

- **快照即聚合**（ADR-004）：由于快照只保留 `类型 → (数量, 字节)` 聚合结果而不存对象地址级明细，因此单快照体积从 GB 级降到 MB 级，Diff 随之退化为字典合并，可在毫秒级完成
- **CPU 时间差算法 + 采样分级**（ADR-003）：L1 1s / L2 3s / 进程列表 3s，工具自身 CPU 占用远低于 1%
- **x86 兼容**（ADR-004）：由于 ClrMD 要求采集方与目标位数一致，因此检测目标位数后，x86 目标由 32 位 Helper 经 Named Pipes 代为采集，协议为长度前缀 JSON
- **MVVM + DI**（ADR-002）：由于采集回调在后台线程触发，因此 ViewModel 统一经 `Dispatcher.UIThread` 编组更新

## 数据与日志位置

| 内容 | 路径 |
| :--- | :--- |
| 告警配置 | `%APPDATA%\MemSight\config.json` |
| 快照文件 | `%APPDATA%\MemSight\snapshots\*.json` |
| 运行日志 | `%APPDATA%\MemSight\logs\memsight-*.log` |

## 注意事项

- 快照期间 ClrMD 会**挂起目标进程**（堆越大冻结越久），因此界面会在拍摄前明确提示，并支持强制取消（取消即恢复目标进程）
- 当目标进程受保护（反调试 / 权限不足）时自动降级为基础监控；读取其他用户或高权限进程需以管理员身份运行 MemSight