From 66775086e0f872cfce656e4043582af5fc9db328 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=AD=A6=E5=BD=93=E5=B1=B1=E9=81=93=E9=95=BF?=
 <233889340+1405264556@users.noreply.github.com>
Date: Tue, 18 Aug 2026 20:18:47 +0800
Subject: [PATCH] add desktop usage and testing guides

---
 CHANGELOG.md              |   8 +
 MANIFEST.in               |   1 +
 README.md                 | 280 ++++++++++++++++++++++++++-------
 docs/TESTING.md           | 194 +++++++++++++++++++++++
 docs/USAGE.zh-CN.md       | 316 ++++++++++++++++++++++++++++++++++++++
 src/robotdev_tools/cli.py |  23 +++
 src/robotdev_tools/gui.py | 244 +++++++++++++++++++++++++++++
 tests/test_gui.py         |  17 ++
 tests/test_report_cli.py  |  26 ++++
 9 files changed, 1051 insertions(+), 58 deletions(-)
 create mode 100644 docs/TESTING.md
 create mode 100644 docs/USAGE.zh-CN.md
 create mode 100644 src/robotdev_tools/gui.py
 create mode 100644 tests/test_gui.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bbc47e8..98b0580 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 All notable changes to RobotDev Tools are documented here.
 
+## Unreleased
+
+- Add a local desktop interface through `robotdev gui` with file/folder selection and automatic
+  report opening.
+- Expand Windows, Linux, PowerShell, CMD, Bash, server, installation, upgrade, and troubleshooting
+  instructions.
+- Add reproducible demo dataset and real-bag acceptance procedures.
+
 ## 0.1.0 - 2026-08-18
 
 - Add ROS-free SQLite3 and MCAP analysis.
diff --git a/MANIFEST.in b/MANIFEST.in
index e221da0..67af251 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -2,3 +2,4 @@ include CHANGELOG.md
 include CONTRIBUTING.md
 recursive-include examples *.yaml
 recursive-include docs/images *.png
+recursive-include docs *.md
diff --git a/README.md b/README.md
index 4da264e..558897b 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,184 @@
 # RobotDev Tools
 
-[中文](#中文) · [English](#english)
+[中文](#中文) · [English](#english) · [详细使用指南](docs/USAGE.zh-CN.md) ·
+[测试数据与验收](docs/TESTING.md)
 
 ![RobotDev Tools report preview](docs/images/report-preview.png)
 
 ## 中文
 
-RobotDev Tools 是一个面向机器人实验室的 **ROS 2 实验验收工具**。它直接读取
+RobotDev Tools 是面向机器人实验室的 **ROS 2 离线实验验收工具**。它直接读取
 rosbag2（SQLite3 / MCAP），自动计算 Topic 健康度和里程计运动指标，并生成
-PASS / WARN / FAIL 质量门禁结果、可离线分享的 HTML 报告以及 CI 可读取的 JSON。
+PASS / WARN / FAIL 质量门禁、自包含 HTML 可视化报告以及适合 CI 的 JSON 结果。
 
-它不是另一个 bag 播放器：核心目标是把“这次实验数据是否合格？”变成可复现的检查。
-分析完全在本机进行，不上传数据，也不要求安装 ROS。
+- 不需要安装 ROS 2。
+- 数据只在本机处理，不上传 bag。
+- Windows 和 Linux 均支持 Python 3.10–3.13。
+- 可使用终端批处理，也可使用本地桌面界面选择文件。
 
-### 30 秒开始
+### 应该选择哪种使用方式？
 
-要求 Python 3.10–3.13。
+| 使用方式 | 适合场景 | 启动方法 | 结果查看 |
+|---|---|---|---|
+| 桌面界面 | 首次体验、单次分析、不熟悉命令行 | `robotdev gui` | 完成后自动在浏览器打开 |
+| 终端命令 | 批量实验、脚本、服务器、CI | `robotdev analyze ...` | 手动打开 `report.html` |
+| 演示数据 | 验证安装、了解 PASS/FAIL 报告 | `robotdev demo ...` | 打开演示目录的 `index.html` |
+
+桌面界面和 HTML 报告都是本地界面，不会启动云服务。无桌面的 Linux 服务器请使用终端模式。
+
+### Windows 快速开始
+
+推荐使用 **PowerShell**。先安装 64 位 Python 3.10–3.13，并在安装器中选中
+“Add Python to PATH”和 Tcl/Tk。然后执行：
+
+```powershell
+# 1. 检查 Python
+py -3.11 --version
+
+# 2. 安装 pipx，并让 robotdev 命令进入 PATH
+py -3.11 -m pip install --user pipx
+py -3.11 -m pipx ensurepath
+
+# 3. 关闭并重新打开 PowerShell，再从 GitHub 安装
+pipx install git+https://github.com/1405264556/robotdev-tools.git
+
+# 4A. 打开本地桌面界面
+robotdev gui
+
+# 4B. 或直接在终端分析；带中文和空格的路径必须加引号
+robotdev analyze "D:\实验数据\run 01" `
+  --config "D:\实验数据\robotdev.yaml" `
+  --output "D:\实验报告\run 01"
+
+# 5. 手动打开报告
+Start-Process "D:\实验报告\run 01\report.html"
+```
+
+如果使用传统 CMD，分析命令相同，但换行符应使用 `^`，打开报告使用：
+
+```bat
+start "" "D:\实验报告\run 01\report.html"
+```
+
+若 PowerShell 提示找不到 `robotdev`，重新打开终端后运行 `pipx ensurepath`；仍有问题可直接使用：
+
+```powershell
+py -3.11 -m pipx run --spec git+https://github.com/1405264556/robotdev-tools.git robotdev --help
+```
+
+### Linux 快速开始
+
+Ubuntu / Debian 桌面版：
 
 ```bash
-# 从 GitHub 安装（推荐使用 pipx 隔离环境）
+# 1. 安装 Python、pipx；桌面界面额外需要 python3-tk
+sudo apt update
+sudo apt install python3 python3-pip pipx python3-tk
+pipx ensurepath
+
+# 2. 重新打开终端，安装 RobotDev Tools
 pipx install git+https://github.com/1405264556/robotdev-tools.git
 
-# 生成正常、低频和里程计跳变三个可重复示例
-robotdev demo --output demo-output
+# 3A. 桌面环境中打开本地界面
+robotdev gui
 
-# 分析自己的 rosbag2
-robotdev analyze /path/to/rosbag2 \
-  --config robotdev.yaml \
-  --output report
+# 3B. 或使用终端分析
+robotdev analyze "/data/实验记录/run 01" \
+  --config "$HOME/robotdev.yaml" \
+  --output "$HOME/reports/run-01"
+
+# 4. 桌面环境中手动打开报告
+xdg-open "$HOME/reports/run-01/report.html"
 ```
 
-Windows PowerShell：
+Fedora 桌面界面的 Tk 依赖为 `sudo dnf install python3-tkinter`。SSH、服务器或容器通常没有
+图形显示环境，应直接使用 `robotdev analyze`，再把生成的 `report.html` 下载到本机浏览器查看。
+
+### 可视化界面使用方法
+
+运行 `robotdev gui` 后：
+
+1. 在 **Bag 数据** 中选择标准 rosbag2 目录，或直接选择 `.db3` / `.mcap` 文件。
+2. 在 **Config 门禁** 中选择质量门禁 YAML；可以留空，此时只计算指标，状态为 `NOT_EVALUATED`。
+3. 在 **Output 报告** 中选择报告目录。
+4. 点击 **开始分析**。分析在后台运行，界面不会上传数据。
+5. 完成后默认打开 `report.html`；也可点击 **打开上次报告** 再次查看。
+
+可以预填路径，减少重复选择：
 
 ```powershell
-robotdev analyze "D:\实验数据\run 01" -c robotdev.yaml -o report
-Start-Process report\report.html
+robotdev gui --bag "D:\bags\run 01" -c ".\robotdev.yaml" -o ".\report"
+```
+
+```bash
+robotdev gui --bag "/data/bags/run-01" -c "./robotdev.yaml" -o "./report"
+```
+
+### 终端分析方法
+
+```text
+robotdev analyze BAG_PATH [--config CONFIG] [--output DIRECTORY] [--sample-limit N]
 ```
 
-也可以从 [GitHub Releases](https://github.com/1405264556/robotdev-tools/releases)
-下载 wheel 后运行 `pipx install robotdev_tools-0.1.0-py3-none-any.whl`，或克隆源码后执行
-`python -m pip install .`。
+常见示例：
+
+```bash
+# 只计算指标，不执行 PASS/FAIL 门禁
+robotdev analyze ./bag --output ./report
+
+# 使用实验室门禁配置
+robotdev analyze ./bag --config ./robotdev.yaml --output ./report
+
+# 直接分析单个存储文件
+robotdev analyze ./bag/rosbag2_0.db3 -c ./robotdev.yaml -o ./report
+robotdev analyze ./bag/rosbag2_0.mcap -c ./robotdev.yaml -o ./report
+
+# 限制每个 Topic 的图表采样点；不影响消息总数等在线统计
+robotdev analyze ./large-bag -c ./robotdev.yaml -o ./report --sample-limit 10000
+```
+
+退出码可用于脚本和 CI：
+
+| 退出码 | 含义 |
+|---:|---|
+| `0` | PASS、WARN，或未配置门禁的 `NOT_EVALUATED` |
+| `2` | 至少一个硬性门禁 FAIL |
+| `1` | 路径、配置或处理错误 |
+
+### 安装、升级与卸载
+
+推荐源码安装方式始终获取 GitHub 主分支的最新版本：
+
+```bash
+pipx install git+https://github.com/1405264556/robotdev-tools.git
+pipx upgrade robotdev-tools
+pipx uninstall robotdev-tools
+```
+
+如果需要固定版本，可从 [GitHub Releases](https://github.com/1405264556/robotdev-tools/releases)
+下载 wheel，然后在文件所在目录执行：
+
+```powershell
+pipx install .\robotdev_tools-0.1.0-py3-none-any.whl
+```
+
+```bash
+pipx install ./robotdev_tools-0.1.0-py3-none-any.whl
+```
+
+开发者从源码安装：
+
+```bash
+git clone https://github.com/1405264556/robotdev-tools.git
+cd robotdev-tools
+python -m venv .venv
+# Windows: .venv\Scripts\python -m pip install -e ".[dev]"
+# Linux:   .venv/bin/python -m pip install -e ".[dev]"
+```
 
 ### 配置质量门禁
 
-复制 [`examples/robotdev.yaml`](examples/robotdev.yaml)：
+复制 [`examples/robotdev.yaml`](examples/robotdev.yaml)，再按机器人和传感器规格调整：
 
 ```yaml
 version: 1
@@ -64,29 +199,32 @@ odometry:
   max_position_jump_m: 0.5
 ```
 
-- 突破硬阈值或缺少必需 Topic：`FAIL`，CLI 退出码为 `2`。
-- 距离阈值不足 `warn_margin_pct`：`WARN`。
-- 未提供配置：仍生成全部指标，但明确标记为 `NOT_EVALUATED`。
-- 输入或配置错误：退出码为 `1`。
+- 必需 Topic 缺失或突破硬阈值：`FAIL`。
+- 距离硬阈值不足 `warn_margin_pct`：`WARN`。
+- 全部满足：`PASS`。
+- 未传入配置：`NOT_EVALUATED`，避免把“仅完成分析”误认为“测试通过”。
 
-每次分析会生成：
+每次分析生成：
 
 ```text
 report/
-├── report.html    # 自包含、无需服务器的可视化报告
+├── report.html    # 单文件、可离线打开的可视化报告
 └── summary.json   # schema_version=1.0 的机器可读结果
 ```
 
-### v0.1.0 指标
+详细参数解释、路径规则、CI 示例和故障排查见
+[`docs/USAGE.zh-CN.md`](docs/USAGE.zh-CN.md)。
 
-所有 Topic：消息数、观测时长、平均/中位频率、周期抖动、最大间隔、断流数、
-重复和倒退时间戳。
+### 指标与数据规模
 
-`nav_msgs/msg/Odometry`：XY 轨迹、累计里程、位移、平均/最大/P95 线速度与角速度、
+所有 Topic：消息数、观测时长、平均/中位频率、周期抖动、最大间隔、断流数、重复和
+倒退时间戳。
+
+`nav_msgs/msg/Odometry`：XY 轨迹、累计里程、起终点位移、平均/最大/P95 线速度与角速度、
 最大加速度、位置跳变及阈值违规次数。
 
-为控制大 bag 的内存占用，消息数、均值、标准差和最大值使用在线统计；图表和分位数
-使用每个流最多 20,000 点的确定性蓄水池采样，并在报告中明确标注。
+消息数、均值、标准差和最大值采用在线统计；图表和分位数默认每个流最多保留 20,000 点，
+因此大 bag 不会因图表数据无限增长而耗尽内存。报告会明确标注是否发生采样。
 
 ### Python API
 
@@ -99,45 +237,71 @@ write_report(result, "report")
 print(result.status, result.to_dict())
 ```
 
-### 当前限制和路线图
+### 测试数据集与验收方法
+
+仓库不提交二进制 bag；`robotdev demo` 会在本机生成三套确定性 ROS 2 测试数据和对应报告：
+
+| 数据集 | 注入情况 | 预期状态 |
+|---|---|---|
+| `normal` | 10 Hz `/scan` 与连续里程计 | `PASS` |
+| `low_rate` | 低频和断流 | `FAIL` |
+| `jump` | 里程计位置跳变及速度/加速度异常 | `FAIL` |
+
+Windows：
+
+```powershell
+robotdev demo --output ".\robotdev-demo"
+Start-Process ".\robotdev-demo\index.html"
+Get-Content ".\robotdev-demo\normal\summary.json"
+```
 
-v0.1 聚焦 ROS 2 离线实验，不包含 GUI、云上传、AI 对话、PDF、ROS 1、ATE/RPE、
-多次实验对比或实时节点监控。未知自定义消息无法反序列化时，仍会保留无需解码的
-Topic 时间指标。
+Linux：
 
-- v0.2：实验对比、基线回归、CSV 导出、CI 门禁模板。
-- v0.3：SLAM/Nav2 插件、ATE/RPE、任务成功率和批量实验。
-- 商业服务：实验室指标模板、报告定制、ROS 2 排障和私有 CI 集成。
+```bash
+robotdev demo --output ./robotdev-demo
+xdg-open ./robotdev-demo/index.html
+cat ./robotdev-demo/normal/summary.json
+```
 
-欢迎实验室提交匿名化后的 `summary.json`、使用反馈或
-[Issue](https://github.com/1405264556/robotdev-tools/issues)。请不要公开上传包含敏感信息的原始 bag。
+验收时确认正常报告为 PASS，两类故障报告为 FAIL，并检查 Topic 时序图、断流检查和里程计
+轨迹是否与注入故障一致。完整的真实 bag 验收表、退出码检查和开发者测试命令见
+[`docs/TESTING.md`](docs/TESTING.md)。
 
 ## English
 
-RobotDev Tools is a ROS-free experiment acceptance tool for robotics teams. It reads ROS 2
-SQLite3 and MCAP bags, calculates topic timing and odometry health, evaluates reproducible
-quality gates, and creates a self-contained HTML report plus compact JSON for CI.
+RobotDev Tools is a local, ROS-free experiment acceptance tool for robotics teams. It reads ROS 2
+SQLite3 and MCAP bags, evaluates topic timing and odometry health, and writes a self-contained HTML
+report plus stable JSON output.
+
+Choose either workflow:
 
 ```bash
-pipx install git+https://github.com/1405264556/robotdev-tools.git
-robotdev demo --output demo-output
+# Local desktop interface
+robotdev gui
+
+# Terminal / server / CI
 robotdev analyze /path/to/rosbag2 --config examples/robotdev.yaml --output report
+
+# Reproducible PASS and FAIL demo datasets
+robotdev demo --output demo-output
 ```
 
-Use `robotdev analyze BAG` without a config for metrics-only mode. The result is intentionally
-`NOT_EVALUATED` until explicit thresholds are supplied. Hard gate failures return exit code 2;
-invalid input or configuration returns exit code 1.
+Install from GitHub with `pipx`:
+
+```bash
+pipx install git+https://github.com/1405264556/robotdev-tools.git
+```
 
-Supported in v0.1.0:
+On Ubuntu/Debian, install `python3-tk` before using the desktop interface. Headless Linux machines
+should use `robotdev analyze`. Windows paths containing spaces or non-ASCII characters are supported;
+quote them in PowerShell or CMD.
 
-- ROS 2 rosbag2 directories, raw `.db3`, and `.mcap` files.
-- Python 3.10–3.13 on Windows and Linux (macOS is expected but not yet in CI).
-- Per-topic frequency, jitter, gaps, and timestamp integrity.
-- `nav_msgs/msg/Odometry` path, distance, velocity, acceleration, and jump checks.
-- Bounded-memory sampling and local-only processing.
+Supported: Python 3.10–3.13 on Windows/Linux, rosbag2 directories, raw `.db3`/`.mcap`, bounded-memory
+topic timing metrics, and `nav_msgs/msg/Odometry` motion checks. Analysis is local-only. Unknown custom
+messages retain timing metrics when their payload cannot be decoded.
 
-See [`examples/robotdev.yaml`](examples/robotdev.yaml) for the stable version-1 configuration.
-Contributions are welcome; read [CONTRIBUTING.md](CONTRIBUTING.md) before sending a change.
+Read the [detailed Chinese guide](docs/USAGE.zh-CN.md), [test dataset and acceptance guide](docs/TESTING.md),
+and [contribution guide](CONTRIBUTING.md).
 
 ## License
 
diff --git a/docs/TESTING.md b/docs/TESTING.md
new file mode 100644
index 0000000..4a72420
--- /dev/null
+++ b/docs/TESTING.md
@@ -0,0 +1,194 @@
+# RobotDev Tools 测试数据集与验收方法
+
+本页用于验证安装是否正确、质量门禁是否能区分正常与故障数据，以及如何提交真实 bag 反馈。
+
+## 1. 内置合成数据集
+
+为了保持仓库轻量、避免 Git LFS 和平台下载差异，仓库不提交生成后的二进制 bag。
+`robotdev demo` 会使用固定参数在本机生成可重复的小型 rosbag2 数据：
+
+| 名称 | Topic | 故障注入 | 预期结果 |
+|---|---|---|---|
+| `normal` | `/scan`、`/odom` | 无；扫描约 10 Hz，轨迹连续 | PASS |
+| `low_rate` | `/scan`、`/odom` | 扫描低频并包含明显断流 | FAIL |
+| `jump` | `/scan`、`/odom` | 里程计位置瞬间跳变，导致速度/加速度异常 | FAIL |
+
+数据目录和报告目录一次生成：
+
+```text
+robotdev-demo/
+├── bags/
+│   ├── normal/
+│   ├── low_rate/
+│   └── jump/
+├── normal/report.html
+├── normal/summary.json
+├── low_rate/report.html
+├── low_rate/summary.json
+├── jump/report.html
+├── jump/summary.json
+├── robotdev.yaml
+└── index.html
+```
+
+## 2. Windows 验收
+
+PowerShell：
+
+```powershell
+robotdev --version
+robotdev demo --output ".\robotdev-demo"
+Start-Process ".\robotdev-demo\index.html"
+```
+
+检查 JSON 状态：
+
+```powershell
+$normal = Get-Content ".\robotdev-demo\normal\summary.json" -Raw | ConvertFrom-Json
+$lowRate = Get-Content ".\robotdev-demo\low_rate\summary.json" -Raw | ConvertFrom-Json
+$jump = Get-Content ".\robotdev-demo\jump\summary.json" -Raw | ConvertFrom-Json
+$normal.status
+$lowRate.status
+$jump.status
+```
+
+预期依次输出 `PASS`、`FAIL`、`FAIL`。
+
+单独验证终端退出码：
+
+```powershell
+robotdev analyze ".\robotdev-demo\bags\normal" `
+  -c ".\robotdev-demo\robotdev.yaml" -o ".\check-normal"
+$LASTEXITCODE
+
+robotdev analyze ".\robotdev-demo\bags\jump" `
+  -c ".\robotdev-demo\robotdev.yaml" -o ".\check-jump"
+$LASTEXITCODE
+```
+
+预期正常数据退出码为 `0`，跳变数据退出码为 `2`。
+
+## 3. Linux 验收
+
+```bash
+robotdev --version
+robotdev demo --output ./robotdev-demo
+xdg-open ./robotdev-demo/index.html
+```
+
+服务器没有桌面时可直接读取 JSON：
+
+```bash
+python3 - <<'PY'
+import json
+from pathlib import Path
+
+root = Path("robotdev-demo")
+for name in ("normal", "low_rate", "jump"):
+    data = json.loads((root / name / "summary.json").read_text())
+    print(name, data["status"])
+PY
+```
+
+检查退出码：
+
+```bash
+robotdev analyze ./robotdev-demo/bags/normal \
+  -c ./robotdev-demo/robotdev.yaml -o ./check-normal
+echo "normal exit code: $?"
+
+robotdev analyze ./robotdev-demo/bags/jump \
+  -c ./robotdev-demo/robotdev.yaml -o ./check-jump
+echo "jump exit code: $?"
+```
+
+预期分别为 `0` 和 `2`。
+
+## 4. 报告人工核对
+
+打开 `index.html`，逐项检查：
+
+### normal
+
+- 总体状态为 PASS。
+- `/scan` 频率接近期望值，最大间隔和抖动在阈值内。
+- `/odom` XY 轨迹连续，无明显位置跳变。
+- Checks 中没有 FAIL。
+
+### low_rate
+
+- 总体状态为 FAIL。
+- `/scan` 的频率检查和/或最大间隔检查为 FAIL。
+- Topic 时序图能看到稀疏区间或断流。
+- 建议内容与低频/断流原因一致。
+
+### jump
+
+- 总体状态为 FAIL。
+- XY 轨迹出现明显不连续。
+- 位置跳变、速度或加速度相关检查至少一项为 FAIL。
+- HTML 指标与 `summary.json` 对应字段一致。
+
+## 5. 真实 bag 验收矩阵
+
+建议至少使用三份真实数据：一份已知正常、一份传感器断流、一份运动异常或定位跳变。
+
+| 检查项 | 数据/步骤 | 通过标准 |
+|---|---|---|
+| 安装 | Windows 与 Linux 各运行 `robotdev --version` | 命令可执行 |
+| 格式 | `.db3` 与 `.mcap` 各分析一份 | 均生成 HTML/JSON |
+| 路径 | 使用含中文和空格的目录 | 不报路径错误 |
+| 正常数据 | 使用实验室门禁分析 | PASS 或可解释的 WARN |
+| 断流数据 | 移除/停止关键传感器 | required、rate 或 gap 为 FAIL |
+| 轨迹异常 | 使用已知定位跳变数据 | jump/speed/accel 检查为 FAIL |
+| 无配置 | 不传 `--config` | NOT_EVALUATED，退出码 0 |
+| 未知类型 | 包含自定义 Topic | 保留时间指标，不导致整体崩溃 |
+| 离线报告 | 断网后打开 HTML | 图表仍可用 |
+| 安全 | bag 路径/元数据含 `<script>` 等文本 | 仅显示文本，不执行脚本 |
+
+## 6. 反馈记录模板
+
+不要在公开 Issue 上传含敏感信息的原始 bag。推荐提供匿名化后的 `summary.json` 和以下信息：
+
+```text
+系统：Windows 11 / Ubuntu 24.04 / ...
+Python：3.11.x
+存储格式：SQLite3 / MCAP
+bag 大小与时长：
+机器人/传感器类型：可匿名
+使用方式：GUI / PowerShell / Bash / CI
+预期结果：
+实际结果：
+是否重复使用：是 / 否；原因：
+可公开的 summary.json：附加或粘贴关键字段
+```
+
+反馈入口：[GitHub Issues](https://github.com/1405264556/robotdev-tools/issues)。
+
+## 7. 开发者测试
+
+安装开发依赖：
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+运行全部检查：
+
+```bash
+ruff check .
+mypy src/robotdev_tools
+pytest --cov=robotdev_tools --cov-report=term-missing
+python -m build
+```
+
+Windows 使用虚拟环境解释器时：
+
+```powershell
+.\.venv\Scripts\python -m ruff check .
+.\.venv\Scripts\python -m mypy src\robotdev_tools
+.\.venv\Scripts\python -m pytest --cov=robotdev_tools --cov-report=term-missing
+.\.venv\Scripts\python -m build
+```
+
+仓库的 GitHub Actions 会在 Ubuntu/Windows 和 Python 3.10–3.13 的八种组合上运行测试。
diff --git a/docs/USAGE.zh-CN.md b/docs/USAGE.zh-CN.md
new file mode 100644
index 0000000..ada2d8e
--- /dev/null
+++ b/docs/USAGE.zh-CN.md
@@ -0,0 +1,316 @@
+# RobotDev Tools 详细使用指南
+
+本指南覆盖 Windows、Linux、终端和桌面界面四种使用环境。RobotDev Tools 的分析过程和
+报告生成全部发生在本机，不需要 ROS 2，也不会上传 rosbag2。
+
+## 1. 环境要求
+
+| 项目 | 要求 |
+|---|---|
+| Python | 3.10、3.11、3.12 或 3.13，推荐 3.11/3.12 |
+| 系统 | Windows 10/11；常见 x86-64 Linux 发行版 |
+| ROS | 不需要 |
+| 浏览器 | 用于打开生成的自包含 HTML 报告 |
+| 桌面界面 | Windows Python 通常自带；Linux 需安装 Tkinter |
+
+支持的输入形式：
+
+- 标准 rosbag2 目录：包含 `metadata.yaml` 和一个或多个存储文件。
+- SQLite3 存储文件：扩展名为 `.db3`。
+- MCAP 存储文件：扩展名为 `.mcap`。
+- Windows/Linux 中带空格、中文或其他 Unicode 字符的路径。
+
+## 2. Windows 安装
+
+### 2.1 安装 Python 与 pipx
+
+从 [python.org](https://www.python.org/downloads/windows/) 安装 64 位 Python。若要使用
+`robotdev gui`，安装器中的 Tcl/Tk 组件不能取消。打开 PowerShell：
+
+```powershell
+py --list
+py -3.11 --version
+py -3.11 -m pip install --user --upgrade pip pipx
+py -3.11 -m pipx ensurepath
+```
+
+关闭并重新打开 PowerShell，让 PATH 设置生效。然后安装：
+
+```powershell
+pipx install git+https://github.com/1405264556/robotdev-tools.git
+robotdev --version
+robotdev --help
+```
+
+若实验室机器不允许修改 PATH，可以使用下面的临时运行方式：
+
+```powershell
+py -3.11 -m pipx run --spec git+https://github.com/1405264556/robotdev-tools.git robotdev --help
+```
+
+### 2.2 PowerShell、CMD 路径差异
+
+PowerShell 多行命令使用反引号，CMD 使用 `^`。路径包含空格或中文时，两者都应加双引号。
+
+PowerShell：
+
+```powershell
+robotdev analyze "D:\实验数据\导航实验 01" `
+  -c "D:\实验配置\robotdev.yaml" `
+  -o "D:\实验报告\导航实验 01"
+$LASTEXITCODE
+Start-Process "D:\实验报告\导航实验 01\report.html"
+```
+
+CMD：
+
+```bat
+robotdev analyze "D:\实验数据\导航实验 01" ^
+  -c "D:\实验配置\robotdev.yaml" ^
+  -o "D:\实验报告\导航实验 01"
+echo %ERRORLEVEL%
+start "" "D:\实验报告\导航实验 01\report.html"
+```
+
+## 3. Linux 安装
+
+### 3.1 Ubuntu / Debian
+
+```bash
+sudo apt update
+sudo apt install python3 python3-pip pipx
+pipx ensurepath
+pipx install git+https://github.com/1405264556/robotdev-tools.git
+robotdev --version
+```
+
+桌面界面额外安装：
+
+```bash
+sudo apt install python3-tk
+robotdev gui
+```
+
+### 3.2 Fedora
+
+```bash
+sudo dnf install python3 pipx
+pipx ensurepath
+pipx install git+https://github.com/1405264556/robotdev-tools.git
+```
+
+桌面界面额外安装：
+
+```bash
+sudo dnf install python3-tkinter
+```
+
+### 3.3 服务器或 SSH
+
+无图形桌面时不要运行 `robotdev gui`。直接分析并把 HTML 下载到本机：
+
+```bash
+robotdev analyze /data/bags/run-01 \
+  -c /opt/robotdev/robotdev.yaml \
+  -o /data/reports/run-01
+echo $?
+```
+
+例如从自己的电脑下载报告：
+
+```bash
+scp user@robot-server:/data/reports/run-01/report.html ./run-01-report.html
+```
+
+`report.html` 已内嵌 Plotly 和全部数据，查看时不需要服务器或互联网。
+
+## 4. 桌面界面
+
+### 4.1 启动
+
+```bash
+robotdev gui
+```
+
+也可以预填路径：
+
+```bash
+robotdev gui --bag /data/bags/run-01 -c ./robotdev.yaml -o ./reports/run-01
+```
+
+界面字段：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| Bag 数据 | 是 | rosbag2 目录、`.db3` 或 `.mcap` 文件 |
+| Config 门禁 | 否 | 版本化门禁配置；留空则结果为 `NOT_EVALUATED` |
+| Output 报告 | 是 | 保存 `report.html` 和 `summary.json` 的目录 |
+| 完成后打开报告 | 否 | 分析完成后用系统默认浏览器打开报告 |
+
+点击 **开始分析** 后，读取和统计在后台线程执行。状态栏会显示最终状态和两个输出文件。
+输出目录可以已存在；同名报告文件会被新结果替换，因此建议每次实验使用独立目录。
+
+### 4.2 界面无法启动
+
+- Windows 出现 Tcl/Tk 错误：使用 python.org 安装器修改 Python，启用 Tcl/Tk。
+- Ubuntu/Debian 提示 Tkinter 缺失：`sudo apt install python3-tk`。
+- Fedora：`sudo dnf install python3-tkinter`。
+- Linux 提示没有 graphical desktop/display：当前为 SSH 或无桌面会话，改用终端模式。
+
+## 5. 终端命令
+
+### 5.1 analyze
+
+```text
+robotdev analyze BAG_PATH [OPTIONS]
+
+Options:
+  -c, --config PATH       RobotDev YAML 配置
+  -o, --output PATH       输出目录，默认 report
+      --sample-limit N    每个 Topic 最多保留的图表点数，默认 20000
+```
+
+不带配置：
+
+```bash
+robotdev analyze ./bag -o ./report
+```
+
+这会生成完整指标，但总体状态为 `NOT_EVALUATED`。只有明确提供阈值配置后才会出现 PASS/WARN/FAIL。
+
+带配置：
+
+```bash
+robotdev analyze ./bag -c ./robotdev.yaml -o ./report
+```
+
+### 5.2 demo
+
+```bash
+robotdev demo --output ./robotdev-demo
+```
+
+输出目录必须为空，避免误覆盖现有数据。该命令生成 `normal`、`low_rate` 和 `jump` 三套
+合成 bag、配置、三份报告以及总入口 `index.html`。
+
+### 5.3 gui
+
+```text
+robotdev gui [--bag PATH] [-c CONFIG] [-o OUTPUT]
+```
+
+它只是对同一个 `analyze_bag` 接口的本地桌面封装，指标和终端模式完全一致。
+
+## 6. 配置说明
+
+```yaml
+version: 1
+warn_margin_pct: 10
+
+topics:
+  /scan:
+    required: true
+    expected_rate_hz: 10
+    rate_tolerance_pct: 10
+    max_gap_ms: 250
+    max_jitter_ms: 20
+
+odometry:
+  topic: /odom
+  max_speed_mps: 1.5
+  max_accel_mps2: 2.0
+  max_position_jump_m: 0.5
+```
+
+建议为不同机器人或实验类型分别保存配置，例如：
+
+```text
+configs/
+├── mobile-base-indoor.yaml
+├── mobile-base-outdoor.yaml
+└── nav2-regression.yaml
+```
+
+阈值应来自设备规格、历史正常实验分布和任务安全边界，而不是直接复制示例值。先用无配置模式
+分析 5–10 次正常实验，再设置预期频率、间隔和运动上限会更可靠。
+
+## 7. 输出解释
+
+`report.html` 包含总览、Topic 表格、时序图、里程计轨迹、检查结果和建议。可直接发给同事，
+但报告中可能包含 Topic 名称、路径和实验元数据，外发前仍应检查敏感信息。
+
+`summary.json` 用于程序处理，顶层至少包含：
+
+- `schema_version`
+- bag 元数据
+- Topic 指标
+- odometry 指标（可用时）
+- checks
+- 总体 `status`
+
+退出码：
+
+- `0`：PASS、WARN、NOT_EVALUATED。
+- `2`：FAIL。
+- `1`：输入、配置或处理错误。
+
+Linux CI 示例：
+
+```bash
+set +e
+robotdev analyze "$BAG_PATH" -c robotdev.yaml -o artifacts/robotdev
+code=$?
+set -e
+test "$code" -eq 0
+```
+
+PowerShell 自动化示例：
+
+```powershell
+robotdev analyze $env:BAG_PATH -c robotdev.yaml -o artifacts\robotdev
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+```
+
+## 8. 更新和清理
+
+```bash
+pipx upgrade robotdev-tools
+pipx reinstall robotdev-tools
+pipx uninstall robotdev-tools
+```
+
+工具不会写入 bag 目录。删除不再需要的报告目录和 demo 目录即可清理输出。
+
+## 9. 常见问题
+
+### 为什么没有配置时不是 PASS？
+
+因为没有门禁阈值就不能证明实验合格，`NOT_EVALUATED` 可以避免产生错误的通过结论。
+
+### 自定义消息类型会导致整个分析失败吗？
+
+通常不会。无法反序列化的自定义类型仍保留消息数、时间范围、频率、间隔等无需解码的指标；
+只有需要消息字段的专项指标会降级并给出提示。
+
+### 能直接读取正在录制的 bag 吗？
+
+不建议。应在 rosbag2 正常关闭并写完 metadata 后分析，避免 SQLite 锁和不完整消息造成误判。
+
+### 为什么大 bag 的图表点数少于消息数？
+
+图表使用最多 20,000 点的确定性采样，消息总数、均值和极值等核心统计仍在线计算。
+
+### 是否支持 ROS 1、ATE/RPE 或实时节点？
+
+当前版本不支持。这些功能属于后续路线图。
+
+## 10. 测试数据和验收
+
+首次安装后建议先运行合成数据验收，再分析真实实验：
+
+```bash
+robotdev demo --output ./robotdev-demo
+```
+
+预期 `normal=PASS`、`low_rate=FAIL`、`jump=FAIL`。完整检查步骤和真实 bag 反馈模板见
+[`TESTING.md`](TESTING.md)。
diff --git a/src/robotdev_tools/cli.py b/src/robotdev_tools/cli.py
index 344a1f1..4adaa8a 100644
--- a/src/robotdev_tools/cli.py
+++ b/src/robotdev_tools/cli.py
@@ -114,5 +114,28 @@ def demo(
     typer.echo(f"Demo ready: {(output / 'index.html').resolve()}")
 
 
+@app.command()
+def gui(
+    bag_path: Annotated[
+        Path | None, typer.Option("--bag", help="Preselect a rosbag2 directory, .db3, or .mcap")
+    ] = None,
+    config: Annotated[
+        Path | None, typer.Option("--config", "-c", help="Preselect a RobotDev YAML config")
+    ] = None,
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="Preselect the report output directory")
+    ] = None,
+) -> None:
+    """Open the local desktop interface."""
+
+    from robotdev_tools.gui import GUIUnavailableError, launch_gui
+
+    try:
+        launch_gui(bag_path=bag_path, config_path=config, output_path=output)
+    except GUIUnavailableError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
 if __name__ == "__main__":
     app()
diff --git a/src/robotdev_tools/gui.py b/src/robotdev_tools/gui.py
new file mode 100644
index 0000000..0df25bf
--- /dev/null
+++ b/src/robotdev_tools/gui.py
@@ -0,0 +1,244 @@
+"""Small local desktop interface for RobotDev Tools."""
+
+from __future__ import annotations
+
+import os
+import platform
+import threading
+import webbrowser
+from pathlib import Path
+
+from robotdev_tools.analyzer import AnalysisError, analyze_bag
+from robotdev_tools.config import ConfigError
+from robotdev_tools.report import write_report
+
+
+class GUIUnavailableError(RuntimeError):
+    """Raised when the optional Tk desktop runtime is unavailable."""
+
+
+def tkinter_install_hint() -> str:
+    """Return a platform-specific hint for installing Tkinter."""
+
+    if platform.system() == "Linux":
+        return (
+            "Tkinter is not installed. On Ubuntu/Debian run "
+            "'sudo apt install python3-tk'; on Fedora run 'sudo dnf install python3-tkinter'."
+        )
+    return "Tkinter is unavailable. Reinstall Python from python.org with the Tcl/Tk option."
+
+
+def launch_gui(
+    bag_path: Path | None = None,
+    config_path: Path | None = None,
+    output_path: Path | None = None,
+) -> None:
+    """Launch the local Tk desktop interface.
+
+    Tkinter is imported lazily so terminal-only installations keep working on
+    Linux machines that do not ship the optional Tk runtime.
+    """
+
+    try:
+        import tkinter as tk
+        from tkinter import filedialog, messagebox, ttk
+        from tkinter import font as tkfont
+    except ImportError as exc:  # pragma: no cover - depends on the host Python build
+        raise GUIUnavailableError(tkinter_install_hint()) from exc
+
+    try:
+        root = tk.Tk()
+    except tk.TclError as exc:  # pragma: no cover - depends on desktop/display availability
+        raise GUIUnavailableError(
+            "A graphical desktop is not available. Use 'robotdev analyze' in the terminal, "
+            "or run 'robotdev gui' inside a desktop session."
+        ) from exc
+
+    root.title("RobotDev Tools")
+    root.geometry("780x540")
+    root.minsize(680, 500)
+
+    default_output = output_path or Path.cwd() / "robotdev-report"
+    bag_var = tk.StringVar(value=str(bag_path or ""))
+    config_var = tk.StringVar(value=str(config_path or ""))
+    output_var = tk.StringVar(value=str(default_output))
+    open_report_var = tk.BooleanVar(value=True)
+    status_var = tk.StringVar(value="Select a rosbag2 directory, .db3, or .mcap file.")
+    last_report: dict[str, Path | None] = {"path": None}
+
+    style = ttk.Style(root)
+    if "vista" in style.theme_names() and os.name == "nt":
+        style.theme_use("vista")
+    title_font = tkfont.nametofont("TkDefaultFont").copy()
+    title_font.configure(size=18, weight="bold")
+    style.configure("Title.TLabel", font=title_font)
+    style.configure("Hint.TLabel", foreground="#4b5563")
+    style.configure("Status.TLabel", foreground="#1d4ed8")
+
+    frame = ttk.Frame(root, padding=24)
+    frame.grid(row=0, column=0, sticky="nsew")
+    root.columnconfigure(0, weight=1)
+    root.rowconfigure(0, weight=1)
+    frame.columnconfigure(1, weight=1)
+
+    ttk.Label(frame, text="RobotDev Tools", style="Title.TLabel").grid(
+        row=0, column=0, columnspan=4, sticky="w"
+    )
+    ttk.Label(
+        frame,
+        text="本地分析 ROS 2 bag / Analyze locally — 无需 ROS，不上传数据",  # noqa: RUF001
+        style="Hint.TLabel",
+    ).grid(row=1, column=0, columnspan=4, sticky="w", pady=(4, 24))
+
+    ttk.Label(frame, text="Bag 数据").grid(row=2, column=0, sticky="w", pady=7)
+    ttk.Entry(frame, textvariable=bag_var).grid(row=2, column=1, sticky="ew", padx=10)
+
+    def choose_bag_file() -> None:
+        selected = filedialog.askopenfilename(
+            title="Select rosbag2 file",
+            filetypes=[
+                ("ROS 2 bags", "*.db3 *.mcap"),
+                ("SQLite3", "*.db3"),
+                ("MCAP", "*.mcap"),
+                ("All files", "*.*"),
+            ],
+        )
+        if selected:
+            bag_var.set(selected)
+
+    def choose_bag_folder() -> None:
+        selected = filedialog.askdirectory(title="Select rosbag2 directory")
+        if selected:
+            bag_var.set(selected)
+
+    ttk.Button(frame, text="文件…", command=choose_bag_file).grid(row=2, column=2, padx=(0, 6))
+    ttk.Button(frame, text="文件夹…", command=choose_bag_folder).grid(row=2, column=3)
+
+    ttk.Label(frame, text="Config 门禁").grid(row=3, column=0, sticky="w", pady=7)
+    ttk.Entry(frame, textvariable=config_var).grid(row=3, column=1, sticky="ew", padx=10)
+
+    def choose_config() -> None:
+        selected = filedialog.askopenfilename(
+            title="Select RobotDev YAML config",
+            filetypes=[("YAML", "*.yaml *.yml"), ("All files", "*.*")],
+        )
+        if selected:
+            config_var.set(selected)
+
+    ttk.Button(frame, text="浏览…", command=choose_config).grid(row=3, column=2, columnspan=2)
+    ttk.Label(
+        frame,
+        text="可留空；不提供配置时只计算指标，结果为 NOT_EVALUATED。",  # noqa: RUF001
+        style="Hint.TLabel",
+    ).grid(row=4, column=1, columnspan=3, sticky="w", padx=10)
+
+    ttk.Label(frame, text="Output 报告").grid(row=5, column=0, sticky="w", pady=(18, 7))
+    ttk.Entry(frame, textvariable=output_var).grid(
+        row=5, column=1, sticky="ew", padx=10, pady=(18, 7)
+    )
+
+    def choose_output() -> None:
+        selected = filedialog.askdirectory(title="Select report output directory")
+        if selected:
+            output_var.set(selected)
+
+    ttk.Button(frame, text="浏览…", command=choose_output).grid(
+        row=5, column=2, columnspan=2, pady=(18, 7)
+    )
+    ttk.Checkbutton(
+        frame,
+        text="完成后在默认浏览器中打开 HTML 报告",
+        variable=open_report_var,
+    ).grid(row=6, column=1, columnspan=3, sticky="w", padx=10, pady=(2, 20))
+
+    progress = ttk.Progressbar(frame, mode="indeterminate")
+    progress.grid(row=7, column=0, columnspan=4, sticky="ew", pady=(0, 10))
+    ttk.Label(frame, textvariable=status_var, style="Status.TLabel", wraplength=700).grid(
+        row=8, column=0, columnspan=4, sticky="w", pady=(0, 20)
+    )
+
+    button_frame = ttk.Frame(frame)
+    button_frame.grid(row=9, column=0, columnspan=4, sticky="ew")
+    button_frame.columnconfigure(0, weight=1)
+
+    def open_report() -> None:
+        report = last_report["path"]
+        if report is not None:
+            webbrowser.open(report.resolve().as_uri())
+
+    open_button = ttk.Button(button_frame, text="打开上次报告", command=open_report)
+    open_button.grid(row=0, column=1, padx=(0, 10))
+    open_button.state(["disabled"])
+
+    def finish_success(status: str, html_path: Path, json_path: Path) -> None:
+        progress.stop()
+        analyze_button.state(["!disabled"])
+        last_report["path"] = html_path
+        open_button.state(["!disabled"])
+        status_var.set(f"{status} — HTML: {html_path} — JSON: {json_path}")
+        if open_report_var.get():
+            open_report()
+
+    def finish_error(message: str) -> None:
+        progress.stop()
+        analyze_button.state(["!disabled"])
+        status_var.set(f"Analysis failed: {message}")
+        messagebox.showerror("RobotDev Tools", message)
+
+    def analyze_worker(selected_bag: Path, selected_config: Path | None, output: Path) -> None:
+        try:
+            result = analyze_bag(selected_bag, selected_config)
+            html_path, json_path = write_report(result, output)
+        except (AnalysisError, ConfigError, OSError, ValueError) as exc:
+            root.after(0, finish_error, str(exc))
+            return
+        root.after(0, finish_success, result.status, html_path, json_path)
+
+    def start_analysis() -> None:
+        selected_bag_text = bag_var.get().strip()
+        output_text = output_var.get().strip()
+        if not selected_bag_text:
+            messagebox.showwarning("RobotDev Tools", "Select a rosbag2 file or directory first.")
+            return
+        if not output_text:
+            messagebox.showwarning("RobotDev Tools", "Select an output directory.")
+            return
+
+        selected_bag = Path(selected_bag_text).expanduser()
+        selected_config_text = config_var.get().strip()
+        selected_config = Path(selected_config_text).expanduser() if selected_config_text else None
+        output = Path(output_text).expanduser()
+        if not selected_bag.exists():
+            messagebox.showerror("RobotDev Tools", f"Bag path does not exist:\n{selected_bag}")
+            return
+        if selected_config is not None and not selected_config.is_file():
+            messagebox.showerror(
+                "RobotDev Tools", f"Config file does not exist:\n{selected_config}"
+            )
+            return
+
+        analyze_button.state(["disabled"])
+        open_button.state(["disabled"])
+        status_var.set("Reading bag and calculating metrics…")
+        progress.start(12)
+        threading.Thread(
+            target=analyze_worker,
+            args=(selected_bag, selected_config, output),
+            daemon=True,
+        ).start()
+
+    analyze_button = ttk.Button(button_frame, text="开始分析", command=start_analysis)
+    analyze_button.grid(row=0, column=2)
+
+    ttk.Separator(frame).grid(row=10, column=0, columnspan=4, sticky="ew", pady=(28, 14))
+    ttk.Label(
+        frame,
+        text=(
+            "隐私说明：分析完全在本机运行，bag 不会上传；仅在所选目录写入 "  # noqa: RUF001
+            "report.html 和 summary.json。"
+        ),
+        style="Hint.TLabel",
+        wraplength=700,
+    ).grid(row=11, column=0, columnspan=4, sticky="w")
+
+    root.mainloop()
diff --git a/tests/test_gui.py b/tests/test_gui.py
new file mode 100644
index 0000000..35634aa
--- /dev/null
+++ b/tests/test_gui.py
@@ -0,0 +1,17 @@
+from unittest.mock import patch
+
+from robotdev_tools.gui import tkinter_install_hint
+
+
+def test_linux_tkinter_hint_has_package_commands() -> None:
+    with patch("platform.system", return_value="Linux"):
+        hint = tkinter_install_hint()
+    assert "python3-tk" in hint
+    assert "apt install" in hint
+
+
+def test_windows_tkinter_hint_mentions_python_installer() -> None:
+    with patch("platform.system", return_value="Windows"):
+        hint = tkinter_install_hint()
+    assert "python.org" in hint
+    assert "Tcl/Tk" in hint
diff --git a/tests/test_report_cli.py b/tests/test_report_cli.py
index 05e1a53..34f1a87 100644
--- a/tests/test_report_cli.py
+++ b/tests/test_report_cli.py
@@ -1,5 +1,6 @@
 import json
 from pathlib import Path
+from unittest.mock import patch
 
 from typer.testing import CliRunner
 
@@ -44,3 +45,28 @@ def test_cli_version() -> None:
     result = runner.invoke(app, ["--version"])
     assert result.exit_code == 0
     assert "0.1.0" in result.stdout
+
+
+def test_cli_gui_forwards_preselected_paths(tmp_path: Path) -> None:
+    bag = tmp_path / "bag"
+    config = tmp_path / "robotdev.yaml"
+    output = tmp_path / "report"
+    with patch("robotdev_tools.gui.launch_gui") as launch_gui:
+        result = runner.invoke(
+            app,
+            [
+                "gui",
+                "--bag",
+                str(bag),
+                "--config",
+                str(config),
+                "--output",
+                str(output),
+            ],
+        )
+    assert result.exit_code == 0
+    launch_gui.assert_called_once_with(
+        bag_path=bag,
+        config_path=config,
+        output_path=output,
+    )