16 KiB
训练块 Workout Block
一款以**「极致的自由度」为核心的 Obsidian 训练记录插件。它不预设任何训练体系——你自己定义训练类型**、记录任何你想记录的数据、对记录字段做任意衍生计算；训练计划、肌肉管理、肌肉热力图同样全部由你按自己的方式配置。所有内容以代码块形式呈现，渲染与数据层高度解耦。数据以纯文本（CSV / JSON）存放在你的 vault 中，可被 Dataview 等工具直接查询。
核心主张：没有「固定字段」、没有「标准动作库」、没有「官方模板」。插件只提供一套可无限自定义的骨架，怎么用完全由你决定。
插件 ID：
workout-block｜ 最低 Obsidian 版本：1.12.7｜ 许可证：MIT ｜ 语言：中文 / English
🧭 设计哲学：一切皆可自定义
多数训练 App 把字段、动作、计划写死，你只能被动适配。本插件反其道而行——它把「定义权」还给你：
| 你决定什么 | 怎么决定 | 文档/代码 |
|---|---|---|
| 有哪些训练类型 | 完全自建，如「力量 / 有氧 / 自重 / 敏捷 / 攀岩」任意增删 | 记录录入 §5 |
| 每种类型记录哪些字段 | 任意数量、任意组合（数字 / 时长 / 文本 / 下拉），无系统约束 | 同上 |
| 字段单位 | 重量自动 kg/lb 换算，或自由文本单位（次 / 公里 / 层 / 圈…） | 同上 |
| 记录字段的衍生数据 | 像配训练类型一样配「数据统计」，引导式或写表达式 sum(reps*weight) |
数据统计设计 |
| 训练计划怎么排 | 每个训练项、每一组的目标量自定义；按具体日期或每周周几执行 | 训练计划设计 |
| 肌肉怎么管 | 任意颗粒度：一块肌肉可映射到 1 条或 N 条解剖路径 | 肌肉管理设计 |
| 热力图画什么 | 逐肌选指标 / 时间窗 / 颜色分档，医学解剖级人体图 | 同上 |
下面分模块展开。
✨ 功能特性
1. 完全自定义的训练类型 —— 你练什么，由你定义
训练类型（如「力量」「有氧」「自重」）只是种子默认值，你可以新建任意类型，并为每个类型配置它包含的字段。系统不预设「某类型必须有哪些字段」，字段的「数量、控件、单位」完全由你决定。
- 支持 4 种输入控件自由组合：
number（数字）/duration（时·分·秒，存储为秒）/text（文本）/select（下拉，可自定义选项）。 - 每个类型至少 1 个字段，可任意增删。
- 改一个类型，所有「新建训练项 / 记录」的录入界面随之改变（字段由类型的
fields动态渲染）。
自定义示例：新建「敏捷训练」类型，字段设为 组数(数字) + 距离(数字，单位「公里」) + 组间休息(下拉：30s / 60s / 90s)。—— 换作力量训练，也可以只有 重量 + 次数。没有限制。
2. 记录任何你想训练的数据 —— 自由度落到「每一组」
记录的最小颗粒度是**「一组」（如「卧推 60kg × 8 次」= CSV 一行）。录入时填写的字段完全由所选训练类型决定**，所以你定义了多少种类型、每个类型有多少字段，就能记录多少种数据。
- 上次值记忆：录入下一组时自动带出该训练项上一次的数值，省去重复输入（可在设置关闭）。
- 模糊匹配：训练项搜索支持子串匹配，随手输入即可命中。
- 所有数据落盘为纯文本，字段以 JSON 存于
fields列，表结构与类型定义解耦——新增类型 / 字段不会破坏历史记录。
3. 对记录字段做任意衍生计算 —— 你想要的指标，自己算
内置的「总组数」只是系统预置的一条普通统计，你完全可以删掉它，定义自己关心的派生指标。
- 双模式公式：
- 引导式构建器：求和
sum/ 乘积求和Σ(a×b)/ 平均·最大·最小 / 计数count，点选即可。 - 自由表达式（高级）：直接写
sum(reps * weight)、avg(weight)、max(weight)等。
- 引导式构建器：求和
- 关联训练类型：一条统计可关联一个或多个类型，只在对应类型的代码块里出现（如「总训练量」同时关联力量与自重）。
- 安全：内置受限求值器，禁用
eval/Function，函数白名单 + 字段引用 + 四则运算，保存前做语法与合法性校验，非法公式拦截保存。 - 统计结果渲染时实时计算，不写回 CSV、不污染原始数据。
4. 极高自由度的训练计划 —— 排你自己的练法
训练计划不是被模板框死的，而是完全可配的训练方案实例：
- 逐组目标量：每个训练项、每一组都可以预设不同的目标字段值（因为字段是你自定义的，每组可能不同）。
- 灵活的计划时间：具体到某一天，或「每周一、三、五」这类 ISO 周几循环。
- 基于方案快速建计划：扫描含
workout-plan代码块的笔记作为来源，一键合并训练项；也支持手动添加方案外的项目、单独增删任意训练组。 - 笔记即方案：含
workout-plan代码块的笔记天然就是训练方案，无需额外实体。 - 完成态独立持久化：在代码块里逐组点「完成」即写入记录；完成状态存于配置、独立于训练记录，完成即完成，不做按日 / 周重置，删除记录不影响完成态。
5. 任意颗粒度的肌肉管理 —— 从「一大块肩膀」到「前/中/后束」
肌肉与人体示意图 SVG 的关系是 1 块肌肉 → N 条 SVG 路径的可配置映射，精细度由你定：
- 新手只想看「肩膀」一大块；教练要区分「三角肌前 / 中 / 后束」分别着色——同一个插件都支持。
- 首次引导三档导入（只是初份配置，不是锁死的「模式」）：
- 默认：13 块基础肌肉，按健身群映射到全部解剖路径（最完整，推荐）。
- 精简：每块只映射代表性主路径，图表更干净。
- 手动：映射留空，由你逐个勾选。
- 导入后随时在编辑弹窗增删映射，「想改就改，不被预设绑架」。
- 双语肌肉目录（中文 / 英文解剖名）共 143 条可映射路径，配搜索框应对规模。
6. 医学解剖级的肌肉热力图 —— 看见身体的强弱
基于完整正 / 背面人体解剖 SVG（医学解剖命名，源自 flutter-body-atlas，CC BY 4.0）渲染全身肌肉负荷：
- 正 / 背面一键切换，两份 SVG 均内联，切换只改显示不重算。
- 按训练量（默认「次数」，可逐肌改）给各肌肉着色，颜色分级逐肌可配（级数 ≤ 99，每级颜色与阈值自定义十六进制）。
- 三级回退：肌肉级 → 代码块级（
metric/range参数）→ 全局默认，每块肌肉都能单独定「用什么指标、看多久」。 - 加权着色：主练权重 1.0、辅练 0.5 累加；绝对阈值着色（非全图归一化），多肌命中同路径取贡献最大者分档。
- 进入视口才计算上色（懒渲染），主线程负担低。
7. 代码块呈现、高度解耦 —— 内容长在笔记里
插件接管四类围栏代码块的渲染，直接在笔记里写即可，渲染与数据层完全分离：
| 代码块 | 视角 |
|---|---|
workout-log |
单动作历史表 + 分组聚合统计 |
workout-day |
当日训练总览（项目 / 统计值 / 主辅肌群 / 方案） |
workout-plan |
训练计划完成面板（逐组点完成） |
workout-heatmap |
全身肌肉负荷热力图（正/背切换） |
- 可扩展注册表：内部维护代码块类型注册表，新增一种代码块 = 写一个 handler 并
registerCodeBlock，无需改动既有逻辑。 - 精准重渲染：数据变更时只重画含该训练项的代码块（
rerenderBlocksForExercise），避免全量卡顿；语言切换 / 外部改文件才全局刷新。 - 预览模式与阅读模式均生效，样式作用域隔离，不污染 vault 全局。
8. 中英双语 & 纯文本数据
- 界面随 Obsidian 语言切换，切换即重渲染，代码块表格 / 热力图文字 / 时长 token 均干净无残留。
- 所有数据存于 vault 内的文本文件（CSV + JSON），不使用任何私有二进制格式，可进 Git、随手备份、被 Dataview 等工具直接查询。
📦 安装
方式一：BRAT（推荐，支持自动更新）
- 在 Obsidian 社区插件市场安装 BRAT。
- 打开 BRAT 设置 →
Add a beta plugin，填入本仓库地址。 - 在「社区插件」中启用 训练块 Workout Block。
方式二：手动安装
- 从 Releases 或仓库根目录下载
main.js与manifest.json。 - 把它们放进你的 vault：
<vault>/.obsidian/plugins/workout-block/。 - 在「社区插件」中启用本插件。
首次启动会自动写入默认训练类型、肌肉与统计配置，热力图开箱即用，无需手动初始化。
🚀 快速上手
启用插件后：
- 点击左侧栏的 哑铃图标，或命令面板（
Ctrl/Cmd + P）搜索「记录一组」，即可录入一条训练。 - 想长期跟踪某训练项，在笔记里写一个
workout-log代码块（见下）。 - 想自定义体系：打开设置 → 训练块 → 对应的「管理」弹窗，新建训练类型 / 训练项 / 训练计划 / 统计 / 肌肉映射。
📝 代码块（Code Blocks）
插件接管了以下四种围栏代码块的渲染，直接在笔记里写即可。
workout-log —— 训练记录表（按动作看历史）
展示训练记录，可点「记录 / 编辑 / 删除」交互操作；分组上方显示该组聚合统计。
| 参数 | 说明 | 默认 |
|---|---|---|
exercise |
仅显示指定训练项（按名称） | 显示全部 |
limit / number |
最多显示条数 | 50 |
day |
仅显示最近 N 天的记录 | — |
group_by |
date（按天）/ week（年-周） |
date |
sort |
desc / asc |
desc |
show_add |
是否显示顶部「添加记录」按钮 | true |
```workout-log
exercise: 深蹲
limit: 20
```
workout-day —— 当日训练总览
按天汇总「练了哪些项目」，表格列为：项目 / 数据统计值 / 主肌群 / 辅助肌群 / 训练方案。
| 参数 | 说明 |
|---|---|
day: 2026-07-12 |
查询指定日期 |
day: today |
显示当日（活数据，随日期滚动） |
不写 day |
同样显示当日，并提供「固定为当日」按钮写回日期 |
```workout-day
day: 2026-07-12
```
workout-heatmap —— 肌肉热力图
渲染完整人体肌肉图，按训练量着色。代码块上方有 正面 / 背面 切换按钮；颜色分级（默认 4 级：蓝 / 绿 / 橙 / 红）的级数、每级颜色与阈值，均可在「肌肉管理」里逐肌肉自定义。
| 参数 | 说明 | 默认 |
|---|---|---|
metric |
引用一条数据统计配置（如「次数」） | 全局默认（次数） |
range |
7d / 30d / 90d / all / 日期区间 |
全局默认（7d） |
```workout-heatmap
metric: 次数
range: 7d
```
workout-plan —— 训练计划完成面板
跟踪某个训练方案的完成进度，逐组标记完成。
| 参数 | 说明 |
|---|---|
plan: 计划名 |
指定要展示的训练方案；不写则显示「选择计划」下拉，选中后自动把计划名写回代码块 |
```workout-plan
plan: 推日 A
```
⚙️ 设置与数据管理
在设置页（Ctrl/Cmd + , → 训练块）可配置：
- 训练类型 / 训练项 / 肌肉 / 统计值 / 训练计划：均在对应的「管理」弹窗中增删改——这是插件「自由度」的总开关。
- 语言：中文 / English。
- 重量单位：kg / lb（影响重量类字段的展示与换算）。
- 上次值记忆：开关。
- 数据目录：训练记录 CSV 的存放位置（默认 vault 根目录）。
- 压缩清理 CSV：删除训练记录采用「软删除」（界面即时移除，磁盘空间延迟回收）；点此按钮真正压缩文件、回收空间。
数据存储位置
| 文件 | 内容 |
|---|---|
workout_logs.csv |
所有训练记录（纯 CSV，便于 Dataview 查询） |
workout-config.json |
配置：训练类型、训练项、肌肉及其 SVG 映射、统计值、训练计划 |
两套数据都位于 vault 内（数据目录可在设置中更改），均为纯文本，可放进 Git 或随手备份。
🔧 开发
# 安装依赖
npm install
# 开发模式（监听改动，不压缩）
npm run dev
# 生产构建（输出根目录 main.js）
npm run build
# 运行测试
npm test
# 测试覆盖率
npm run test:coverage
构建产物为根目录的 main.js，配合 manifest.json 即可作为插件运行。
技术栈
📄 许可证
MIT —— 可自由使用、修改与分发。仓库根目录已附带 LICENSE 文件（MIT 全文），以便 GitHub 自动识别许可证。
插件打包的肌肉 SVG 插图来自第三方，遵循 CC BY 4.0（作者 Ryan Graves）与 BSD-3-Clause（flutter-body-atlas, Kit G.）。署名与许可详情见 THIRD-PARTY-NOTICES。