Tonus 3.1.0

A global energy bar with activity-based fatigue rates

Tonus

Tonus 是一个本地命令行精力管理工具。你每天只有一条全局精力槽，活动决定 精力消耗速度。所有数据保存在本机 SQLite 数据库中。

界面遵循项目的冷淡极简设计系统：低对比冷灰为主、低饱和钢蓝强调、内容 最大宽度 68 列、无动画、无嵌套面板。完整规范见 DESIGN.md。

核心模型

• 每日精力上限默认为 156。
• 每项活动有独立消耗速率。
• 工作一分钟产生的疲劳为：1 分钟 × 活动速率。
• 所有活动共同消耗当天的全局精力。
• 选择新活动时会自动停止当前活动。
• 统计日默认从凌晨 04:00 开始，而不是自然日零点。

例如工作一小时：

• “写代码”速率 1.5，消耗 90 点。
• “开会”速率 1.2，消耗 72 点。
• “阅读”速率 0.5，消耗 30 点。

安装

需要 Python 3.10 或更高版本：

python3 -m venv .venv
.venv/bin/python -m pip install -e .

安装完成后直接使用：

.venv/bin/to

Tab 补全

只需安装一次，然后重启终端：

.venv/bin/to --install-completion
exec zsh

之后可以补全命令和活动名：

to che<Tab>       → to check
to check e<Tab>   → to check email

有多个匹配项时会显示候选列表，可继续使用方向键选择。

快速开始

设置每日精力：

to config --total 200 --reset-hour 4

添加活动：

to add 写代码 --rate 1.5
to add 开会 --rate 1.2
to add 阅读 --rate 0.5

直接运行 to，使用方向键选择活动：

to

选择活动

› 写代码    1.50×
  开会      1.20×
  阅读      0.50×   进行中

↑↓←→ 选择   Enter 确认   Q 取消

该列表不是全屏界面，没有动画，确认后会自动收起。

TUI

需要同时观察精力、当前活动和技能成长时，打开完整界面：

to ui

TUI 保留冷淡极简风格，不使用图标墙和装饰动画。宽终端采用活动、技能双栏； 窄终端自动改为上下布局。

↑↓          选择
←→          切换活动 / 技能区域
Enter/Space 开始选中的活动
S           停止当前活动
R           刷新
Q           退出

to 仍然是最快的非全屏活动选择器，to ui 用于沉浸式查看和操作，两者不会 互相替代。

技能成长

技能与活动分开维护。一个技能可以关联多项活动，所有关联活动的真实记录时长 会共同推动等级。例如“英语阅读”和“英语听力”都可以贡献给“英语”。

to add 英语阅读 --rate 0.8
to add 英语听力 --rate 0.6

to skill add 英语 --level-minutes 60 --activity 英语阅读
to skill link 英语 英语听力

查看成长：

to skill
to skill list
to ui

等级从 LV 1 开始。若每级设置为 60 分钟，则累计 90 分钟后为 LV 2，并 完成下一级的 50%。升级节奏始终固定且透明：

等级 = floor(累计时长 / 每级时长) + 1

技能经验不单独保存，而是实时从历史记录计算。因此补记、修正或删除历史时， 等级会自动同步，不会产生两套互相矛盾的数据。

其他管理命令：

to skill edit 英语 --name English
to skill edit English --level-minutes 90
to skill unlink 英语听力
to skill remove English

移除技能只会将其隐藏，不删除活动和历史；再次添加同名技能会恢复显示。

日常命令

开始活动

通过选择器开始：

to
to start

直接指定活动：

to start 写代码
to start 阅读 --task "阅读技术文档"

开始另一项活动时，会自动结束当前活动。

停止活动

to stop

查看今日状态

to status

状态包含今日剩余精力、当前活动和每项活动的疲劳消耗。

管理活动

to list
to add 写代码 --rate 1.5
to edit 写代码 --name 编程
to edit 编程 --rate 1.2
to edit 编程 --position 1
to remove 编程

再次添加同名活动会更新速率并重新启用。移除只会让活动退出选择列表，不会 删除历史记录。position 从 1 开始，可同时修改名称、速率和位置。

彻底删除活动及其全部历史记录：

to remove 编程 --purge

确认后会先在数据目录自动创建完整数据库备份，再用同一个事务删除活动及其 全部历史记录。自动化脚本可加 --yes 跳过确认；该参数必须和 --purge 一起使用。已经普通移除、当前不在活动列表中的活动也可以通过完整名称清理。

查看与修正历史

to history
to history --limit 50

每条记录带有稳定 ID。修正活动、时间或任务描述：

to amend 12 --activity 阅读
to amend 12 --start "2026-07-15 09:30" --stop "10:20"
to amend 12 --task "整理设计规范"

删除错误记录：

to discard 12

进行中的记录只能修改开始时间和任务描述；更换活动、补结束时间或删除前， 应先执行 to stop。

查看配置

to config

修改配置：

to config --total 200
to config --reset-hour 4

统计报表

报表是普通静态终端输出，不会进入全屏界面。

周报

默认展示最近 7 个统计日：

to report
to report week

日报

to report today

月报

展示最近 30 个统计日：

to report month

自定义周期

to report --days 14
to report -d 90

周期支持 1 到 366 天。

指定日期范围

to report --from 2026-07-01 --to 2026-07-15
to report --from 2026-07-01
to report --to 2026-07-15 --days 30

日期代表统计日，仍然遵循配置的凌晨重置时间。

报表以低信息密度和快速阅读为目标，只保留四层内容：

1. 关键数字：投入时间、疲劳消耗、平均专注和活动切换。
2. 趋势：日报和周报按天展示；超过 14 天自动按周折叠，避免月报过长。
3. 活动：只展示主要活动，次要活动合并为“其他”。
4. 节奏：最长专注、高峰时段、最活跃星期和短记录数量。

超限天数、休息日和总记录数会以一行淡色说明放在报表底部。所有报表均使用 统一宽度、留白和对齐方式，不会堆叠大量表格。

统计准确性

• 每条记录保存创建时的活动速率；以后修改活动速率不会改写历史疲劳。
• 每日精力上限保留修改历史，历史利用率不会统一套用当前配置。
• 跨越凌晨 4 点的记录会按实际重叠时间拆分到两个统计日。
• 正在进行的活动按当前时间实时计算。
• 被移除活动的历史记录仍然参与报表。

从旧版本升级时，数据库会自动增加所需字段。旧记录无法还原当时未保存的 速率，因此首次迁移会使用该活动当前速率进行回填；迁移后的新记录保持准确。 升级前会在数据目录自动生成 fatigue-before-v3.db 原始副本。

开始、切换和停止活动均在单个 SQLite 写事务中完成。数据库会保证全局最多 只有一条进行中记录；升级时如发现旧版本留下的重复记录，会保留最新一条并 安全结束其余记录。

备份、恢复与导出

创建完整数据库备份：

to backup
to backup ~/Documents/tonus.db

导出全部历史记录：

to export
to export records.csv
to export records.json --format json

恢复备份会先自动保存一份当前数据库，且必须显式确认：

to restore ~/Documents/tonus.db --yes

backup 用于完整恢复；export 用于分析或迁移到其他工具。

兼容旧命令

以下旧命令仍然可用，但不会显示在帮助列表中：

旧命令	推荐命令
to open	to start
to close	to stop
to check / to checkall	to status
to delete	to remove
to settings	to config

数据位置

~/.config/mana/data/fatigue.db
~/.config/mana/data/config.json

新安装默认关闭 Timewarrior 集成。如需启用，编辑 config.json：

{
  "enable_timew": true
}

Timewarrior 属于可选同步。即使它未安装、超时或执行失败，Tonus 的本地计时 仍会正常完成，并显示一条警告。

测试

测试只使用 Python 标准库：

.venv/bin/python -m unittest discover -s tests -v

代码结构

package/entity       领域对象与服务结果
package/data         SQLite 与兼容数据访问层
package/service      活动和记录业务流程
package/reporting    纯报表计算
package/integrations 可选外部集成
package/ui           主题、选择器、状态、报表和反馈
package/tui          Textual 双栏交互界面
package/cli          Typer 命令与旧入口兼容

核心业务流程不直接输出终端内容，报表计算不依赖 Rich；所有颜色、间距、宽度 和组件统一由 package/ui 管理。旧入口仅作为兼容转发层保留。