FrameWatch · 帧境

把一次卡顿，变成一段可以回看的证据。

FrameWatch 是一个在本机运行的游戏性能分析工作台：记录 Windows 硬件负载、导入 PresentMon 逐帧数据、对齐两种采样、查看异常事件，并比较两次测试。React + TypeScript 前端，FastAPI + SQLite 后端，独立线程采样，原始数据可导出。

能做什么

• 真实硬件采样：CPU 总负载 / 逐核负载、内存、频率、磁盘吞吐、后台进程；Windows GPU 3D 负载和独立显存占用采用异步性能计数器读取。
• 逐帧分析：导入单进程、单交换链的 PresentMon CSV，计算平均 FPS、1% Low、P95 / P99 帧时间及卡顿事件。
• 帧与硬件对齐：指定两次记录的时间偏移，生成可追溯的合并记录。超过 2 秒没有硬件样本时保留缺失值。
• 交互时间线：缩放、选取时间范围、查看事件证据；曲线展示会降采样，统计始终基于原始逐帧记录。
• 历史对比：比较优化前后的帧率、帧时间和硬件负载。
• 本地存储与导出：SQLite 持久化，CSV / JSON 原始数据和 Markdown 报告；中断记录可在重启后恢复查看。
• 明确的演示模式：首次运行提供有标签的合成示例，可立即体验完整分析流程。

快速启动（Windows）

需要 Python 3.11+、Node.js 22.12+（或 24+）和 pnpm 11.19.0。首次安装需要联网，安装完成后采样与分析可离线运行。

git clone https://github.com/ZTLNB/framewatch.git
cd framewatch
.\start.ps1

start.ps1 会创建项目内的 .venv、安装依赖、构建前端，然后启动服务并打开浏览器。默认地址：**http://127.0.0.1:8765**。再次运行会复用已安装依赖和前端构建。源码更新后执行 ./start.ps1 -Rebuild。

如果 PowerShell 的执行策略不允许运行脚本，可逐条执行以下命令，无需修改系统策略：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt -e .
cd web
pnpm install --frozen-lockfile
pnpm build
cd ..
.\.venv\Scripts\python.exe -m framewatch

没有 pnpm 时可先通过 Node.js 提供的 npm 安装：npm install -g pnpm@11.19.0。也可以使用已安装的兼容 pnpm 版本。

开始一次有效测试

1. 打开 FrameWatch，点击开始采样，给记录命名，例如“场景 A · 优化前”。默认间隔为 1 秒。
2. 同时使用 Intel PresentMon 为目标游戏记录单进程、单交换链的 CSV。使用默认相对时间输出；FrameWatch 不下载驱动或执行 PresentMon。
3. 在游戏中复现固定路线或场景，停止两边的记录。
4. 导入 PresentMon CSV；选择“对齐硬件记录”，按实际开始时间填写偏移：帧时间 + 偏移秒数 = 硬件时间。例如 PresentMon 比硬件采样晚开始 5 秒，填写 5。
5. 查看卡顿时间点、同期硬件变化和后台进程。重复相同场景，再在对比视图选择两份记录。

也可以只做硬件采样；这时 FPS / 1% Low 会显示未采集，不会推算或伪造。

指标与边界

平均 FPS 为 1000 / 平均帧时间；1% Low 为 1000 / 最慢 1% 帧时间的均值。卡顿阈值同时参考绝对帧时间和最近两秒的基线。详情见 分析口径。

• 实时采样记录硬件状态，不直接捕获游戏帧时间。真实逐帧指标由 PresentMon CSV 提供。
• 单次 CSV 最多 25 MB、20,000 条样本；实时采样最多 20,000 条。超过限制会明确拒绝或自动结束，不会静默截断导入记录。
• GPU 计数器因驱动/权限/启动预热可能暂时不可用；缺失值保留为空。显存指标是占用量，不是显卡容量。
• 硬件采样分辨率低于帧数据，对齐后的关联提示不能证明因果，也不能单独判定硬件故障。
• 不支持自动对齐机器时钟、温度/功耗传感器、游戏内覆盖层或自动更改系统设置。
• 服务只监听本机回环地址，不含远程访问认证。请保持默认本地用途。

导入格式和错误处理见 CSV 指南，采样实现见 采集器说明。

开发与测试

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -q
# Terminal 1
.\.venv\Scripts\python.exe -m framewatch --no-browser
# Terminal 2
cd web
pnpm dev

Vite 开发地址为 http://localhost:5173，/api 自动代理至 127.0.0.1:8765。API 文档在 http://127.0.0.1:8765/api/docs。

当前已通过本地测试与前端构建。仓库提供 GitHub Actions 模板，包含 Windows / Linux、Python 3.11 / 3.13 测试和前端构建，尚未启用云端 CI。启用时将模板复制到 .github/workflows/ci.yml 并推送；GitHub 凭据需要具备 workflow 权限。

framewatch/
  api.py          HTTP API、导入导出、本地来源校验
  storage.py      SQLite WAL、原始样本持久化
  recording.py    独立采样线程、并发保护、中断处理
  collector.py    psutil 与 Windows GPU 性能计数器
  csv_import.py   PresentMon / FrameWatch CSV 校验
  analytics.py    帧统计、事件检测、解释性证据
  correlation.py 有界时间对齐
web/              React / TypeScript / Recharts 界面
tests/            算法、输入校验、采集器、API 集成测试

架构说明 · 贡献指南 · 安全说明

容器：分析与导入模式

docker build -t framewatch .
docker run --rm -p 127.0.0.1:8765:8765 -v framewatch-data:/app/data framewatch

容器用于体验示例、导入和分析。容器中的实时硬件采样反映容器所见环境，不能代替 Windows 主机游戏采样。Windows 实测请使用上面的原生启动方式。

数据与许可证

默认数据保存在项目的 data/ 中；可通过 --data-dir 或 FRAMEWATCH_DATA_DIR 更改。数据库、日志、虚拟环境和本地配置已加入 .gitignore。公开仓库只包含源码、测试和合成演示内容。

MIT License。项目与 Intel PresentMon 无隶属关系。