Tonus 3.6.1

A global energy bar with activity-based fatigue rates

Tonus

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

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

核心模型

• 每日精力上限默认为 156。
• 每项活动有独立消耗速率。
• 活动归入工作、学习、娱乐、运动、生活或其他分类。
• 分类可以设置每日时间预算；0 表示不限制。
• 工作一分钟产生的疲劳为：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 --category 工作
to add 阅读 --rate 0.5 --category 学习
to add 游戏 --rate 0.3 --category 娱乐

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

to

选择活动

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

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

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

TUI

需要统一管理计时、技能和统计时，打开完整工作台：

to ui

TUI 保留冷淡极简风格，不使用图标墙和装饰动画。默认主题为“自动”，会优先 识别当前终端的背景明暗，再回退到系统外观；也可以固定为深色或浅色。两套主题 共享同一套冷灰、低饱和钢蓝设计语言。它包含六个页面，数字键 1–6 可直接切换：

页面	内容与操作
今日	当前计时、今日分类投入、精力、单次用途和技能进度
活动	添加、分类、编辑、排序、移除和彻底删除活动
技能	添加、编辑、关联活动、验证阶段和移除技能
历史	浏览、修正和删除时间记录
报表	日报、周报、月报和自定义日期统计
设置	主题、精力配置、分类预算、数据库备份、记录导出和恢复

宽终端的今日页采用活动、技能双栏，时间与技能摘要延续相同列线；窄终端自动 改为上下布局，矮终端则保留紧凑双栏，避免压缩主要内容。

↑↓          选择
←→          切换活动 / 技能区域
Enter/Space 开始选中的活动
Tab         在弹框的字段和按钮之间向前切换
Shift+Tab   在弹框的字段和按钮之间向后切换
Enter       激活当前聚焦的按钮
T           选择任务、用途、技能和训练模式后开始
S           停止当前活动
V           为选中技能提交阶段成果
R           刷新
?           查看当前 TUI 的全部操作
Q           退出

在设置页按 H 可以切换 自动 / 深色 / 浅色，选择后立即生效并保存。

to 仍然是最快的非全屏活动选择器，to ui 用于沉浸式查看和操作，两者不会 互相替代。CLI 中的主要功能都在 TUI 对应页面中提供；旧命令别名共享同一功能， 不会在 TUI 中重复出现。

技能成长

技能是通用的能力容器，不绑定英语或任何预设领域。它可以表示编程、乐器、 写作、运动或一项自定义能力。Tonus 使用“有效练习 + 成果验证”衡量成长： 时间推动等级，真实成果决定能否进入下一个能力阶段。

to add 刷题 --rate 0.8
to add 项目实践 --rate 1.0

to skill add 编程 --pace 60 --activity 刷题 --mode study
to skill link 编程 项目实践 --mode output

查看成长：

to skill
to skill list
to ui

有效练习

活动按训练质量折算经验。关联定义活动的默认技能和模式；每次开始时仍可按 T 选择“只统计时间”或临时指定另一个技能。每条记录独立保存分类、技能、 训练模式和权重，未来修改活动不会篡改历史经验。

模式	权重	适用情况
接触 exposure	0.4×	浏览、观看、被动接触
学习 study	0.7×	阅读教材、听课、整理知识
练习 practice	1.0×	有目标的重复训练
挑战 challenge	1.2×	略高于当前水平的问题
产出 output	1.1×	项目、作品、演出或真实交付

例如，学习资料 60 分钟产生 42 分钟有效经验；挑战练习 60 分钟产生 72 分钟。

非线性等级

等级上限为 LV 100。升级会逐渐变慢，标准成长节奏 --pace 60 使用以下累计 有效练习锚点：

等级	能力阶段	累计有效练习
10	基础	约 25h
25	独立	约 140h
45	熟练	约 430h
65	进阶	约 880h
85	专家	约 1500h
100	专家	约 2060h

计算保持透明，n = 等级 - 1：

到达等级所需有效分钟 = pace × (0.2 × n² + n)

pace 是整条曲线的倍率：30 适合较轻量的技能，60 是默认，120 适合 训练周期很长的深度能力。技能经验仍从历史记录实时计算，补记、修正或删除 历史后会自动同步。

能力验证

单靠时间不能证明真实能力。达到 LV 10 / 25 / 45 / 65 / 85 时，等级会停在 上一阶段上限，并提示“待验证”。提交一条具体、可复核的成果后才会解锁：

to skill verify 编程 "独立完成并发布一个可使用的命令行工具"

也可以在 to ui 中选择技能，按 V 输入成果。验证记录会永久保留；它不是 自动颁发的游戏徽章，而是你判断真实能力时的证据索引。

其他管理命令：

to skill edit 编程 --name 软件工程
to skill edit 软件工程 --pace 90
to skill unlink 项目实践
to skill remove 软件工程

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

日常命令

开始活动

通过选择器开始：

to
to start

直接指定活动：

to start 写代码
to start 阅读 --task "阅读技术文档"
to start 电影 --time-only
to start 电影 --skill 英语 --mode exposure

开始另一项活动时，会自动结束当前活动。--time-only 明确表示本次不产生任何 技能经验；--skill 和 --mode 只覆盖这一次记录。

停止活动

to stop

查看今日状态

to status

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

管理活动

to list
to add 写代码 --rate 1.5 --category 工作
to add 游戏 --rate 0.3 --category 娱乐
to edit 写代码 --name 编程
to edit 编程 --rate 1.2
to edit 编程 --category 学习
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 amend 12 --time-only
to amend 12 --skill 英语 --mode study

删除错误记录：

to discard 12

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

查看配置

to config

修改配置：

to config --total 200
to config --reset-hour 4
to config --theme auto
to config --theme light
to config --budget 娱乐=120
to config --budget 学习=180

分类预算按天设置，报表会按所选周期自动换算。例如娱乐每日 120 分钟，在 周报中对应 14 小时预算。填写 娱乐=0 可取消限制。

统计报表

报表既可以作为普通静态终端输出，也可以在 to ui 的“报表”页面中交互查看。 TUI 会将时间作为主指标，显示总投入、分类预算、日均投入、会话数、最长专注、 活动耗时排行和每日趋势；疲劳仍作为精力规划指标保留在静态报表中。

报表会按终端宽度自动调整：窄终端把四个摘要指标排成平衡的两行，宽终端再展开 为单行。分类、活动和趋势共用同一套“名称 / 进度 / 数值”栅格，并按终端显示 宽度而不是字符串长度计算位置，因此中文、英文和数字混排时仍能严格对齐。

周报

默认展示最近 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. 分类：工作、学习、娱乐等实际投入与周期预算。
3. 趋势：日报和周报按天展示；超过 14 天自动按周折叠，避免月报过长。
4. 活动：按实际投入时间排序，只展示主要活动，次要活动合并为“其他”。
5. 节奏：最长专注、高峰时段、最活跃星期和短记录数量。

超限天数、休息日和总记录数会以一行淡色说明放在报表底部。所有报表均使用 统一宽度、留白和对齐方式，不会堆叠大量表格；TUI 的主要内容只保留一条低 对比度左边线，区块依靠留白分组，减少盒子感。

统计准确性

• 每条记录保存创建时的活动速率；以后修改活动速率不会改写历史疲劳。
• 每条记录保存分类、技能、模式和权重；活动后来改名、换分类或重新关联技能， 都不会改变过去的统计。
• 未关联技能或明确选择“只统计时间”的记录，技能权重固定为 0。
• 每日精力上限保留修改历史，历史利用率不会统一套用当前配置。
• 跨越凌晨 4 点的记录会按实际重叠时间拆分到两个统计日。
• 正在进行的活动按当前时间实时计算。
• 被移除活动的历史记录仍然参与报表。

从旧版本升级时，数据库会自动增加所需字段。旧记录无法还原当时未保存的 速率，因此首次迁移会使用该活动当前速率进行回填；迁移后的新记录保持准确。 升级前会在数据目录自动生成 fatigue-before-v6.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 管理。旧入口仅作为兼容转发层保留。