FIT File Analyzer Skill 🏃‍♂️📊

解析 Garmin/Fit 运动记录文件（跑步、骑行、徒步等），提取结构化数据并生成精美的双主题（暖橙/瑞幸式冷蓝，一键切换） HTML 可视化分析报告。

功能特性

🔍 单通道 FIT 解析（官方协议）：FIT 二进制解析走 Node.js + fit-file-parser（完整遵循 Garmin FIT SDK 协议，自动兼容 enhanced_speed 等 v2 字段）
🎨 精美 HTML 报告：双主题（暖色/冷色右上角一键切换，localStorage 记忆）、杂志式 Bento 概览布局（路线缩略图/速度曲线/海拔剖面/运动-暂停活动条内嵌）、GPS 路线图（北在上、等比不变形）、ECharts 图表全部本地内联（离线可用，不依赖 CDN）
📊 AI 表格数据：table_data.json 输出标准列名 + 二维数组，可直接喂给大模型
📤 CSV 导出（单文件 · 零依赖）：fit_data.csv 三段式（汇总/单圈/记录点），UTF-8 BOM 保证 Excel/WPS 不乱码
💾 SQLite 结构化存储：fit_data.db 三表（summary/records/laps），便于跨活动聚合查询
🧠 智能自适应：骑行自动显示"踏频 rpm"、跑步显示"步频 spm"；骑行主打速度、跑步主打配速；无传感器数据时显示友好提示而非空白
✅ 标准化协议：--json-output 严格返回 {success, error, outputs, stats, summary, ai_payload} JSON；文件名固定覆盖写（始终一组产物）

架构说明

              ┌───────────────────────────────────────┐
 Input .fit ─▶│  解析层【JS · Garmin FIT SDK 协议】    │
              │  parser-js/fit_to_json.js             │
              │  enhanced_* 字段自动 fallback          │
              └──────────────┬────────────────────────┘
                             │ stdout JSON（严格 schema）
              ┌──────────────▼────────────────────────┐
              │  统计 & 交付层（Python 标准库零依赖）   │
              │  ├─ export_table_data() → AI JSON      │
              │  ├─ export_csv() → 单文件 CSV          │
              │  ├─ save_to_sqlite() → .db             │
              │  ├─ generate_html_report() → 报告      │
              │  └─ records 兜底回填（双保险）          │
              └───────────────────────────────────────┘

目录结构

fitfile-analyzer/
├── SKILL.md                  # 本文件
├── requirements.txt          # Python 依赖（当前为空：全部标准库）
├── parser-js/                # JS 解析层
│   ├── package.json          # 依赖: fit-file-parser
│   └── fit_to_json.js        # node fit_to_json.js <fit> → stdout JSON
├── lib/
│   ├── fit_parser.py         # JS 适配 + 统计兜底 + CSV/SQLite 导出
│   ├── report_generator.py   # HTML 报告生成（双主题 + ECharts 内联）
│   └── echarts.min.js        # ECharts 5.5.0 本地库（报告内联，离线可用）
└── scripts/
    └── main.py               # CLI 入口

安装依赖

Python 层：零第三方依赖（csv/sqlite3/json 均为标准库）。

JS 解析层（必需，唯一解析链路）：依赖已随包内置（parser-js/node_modules/，仅 ~0.3MB），无需额外安装。若缺失再执行：

cd fitfile-analyzer/parser-js
npm install

运行环境：Python ≥ 3.8 + Node.js ≥ 14。若 Node 不可用将明确报错 JS_PARSER_NODE_NOT_FOUND。

使用方法

# 全量产物（推荐）：JSON + HTML + CSV + SQLite
python fitfile-analyzer/scripts/main.py ./activity.fit \
  -o ./output --json-output --html-report --csv --sqlite

# 仅 AI JSON（Skill 协议模式，stdout 输出标准 JSON）
python fitfile-analyzer/scripts/main.py ./activity.fit --json-only

# 仅 HTML 报告
python fitfile-analyzer/scripts/main.py ./activity.fit --html-only

输出目录固定为 4 个文件（覆盖写，无时间戳）：

output/
├── table_data.json   # AI 接口（summary/laps/records 表格化 + 预计算指标）
├── report.html       # 双主题可视化报告（双击即可打开，离线可用）
├── fit_data.csv      # 三段式单文件 CSV
└── fit_data.db       # SQLite 三表

CLI 参数

| 参数 | 说明 | |------|------| | fit（位置参数）/ -i | 输入 .fit 文件路径 | | -o, --output-dir | 输出目录，默认 ./fit_output | | --json-output | 输出 JSON 并打印标准协议 JSON 到 stdout（Skill 模式） | | --json-only | 仅输出 JSON | | --html-report / --html-only | 生成 / 仅生成 HTML 报告 | | --csv | 导出单文件 fit_data.csv（汇总/单圈/记录点三段） | | --sqlite | 写入 SQLite fit_data.db（三表） | | -q / -v | 静默 / 详细模式 |

JSON 输出协议（--json-output）

{
  "success": true,
  "error": "",
  "outputs": {
    "json_path": "output/table_data.json",
    "html_path": "output/report.html",
    "csv_path": "output/fit_data.csv",
    "sqlite_path": "output/fit_data.db"
  },
  "stats": { "records_count": 6486, "laps_count": 7 },
  "summary": { "sport": "骑行", "total_distance": 32213.5, "avg_speed": 4.93, "...": "..." },
  "ai_payload": {
    "summary_fields": { "columns": [{ "key": "total_distance", "name": "总距离(米)", "value": 32213.5 }] },
    "ai_metrics": { "avg_speed_kmh": { "value": 17.75, "unit": "km/h" } },
    "laps_table": { "columns": [], "rows": [] }
  }
}

限制与注意事项

需要 Node.js 运行时（FIT 解析唯一链路，无 fallback）
图表渲染已采样优化（>500 记录点自动下采样），JSON 导出保持完整
室内活动无 GPS 轨迹时，路线图区域显示友好提示
失败时 success=false，调用方务必检查该字段