Metadata-Version: 2.4
Name: Tonus
Version: 3.6.1
Summary: A global energy bar with activity-based fatigue rates
Author-email: firefly <your.email@example.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer<1,>=0.12
Requires-Dist: rich<16,>=14.2
Requires-Dist: textual<7,>=6.12
Requires-Dist: typing_extensions>=4.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"

# Tonus

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

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

## 核心模型

- 每日精力上限默认为 `156`。
- 每项活动有独立消耗速率。
- 活动归入工作、学习、娱乐、运动、生活或其他分类。
- 分类可以设置每日时间预算；`0` 表示不限制。
- 工作一分钟产生的疲劳为：`1 分钟 × 活动速率`。
- 所有活动共同消耗当天的全局精力。
- 选择新活动时会自动停止当前活动。
- 统计日默认从凌晨 `04:00` 开始，而不是自然日零点。

例如工作一小时：

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

## 安装

需要 Python 3.10 或更高版本：

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

安装完成后直接使用：

```bash
.venv/bin/to
```

### Tab 补全

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

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

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

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

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

## 快速开始

设置每日精力：

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

添加活动：

```bash
to add 写代码 --rate 1.5
to add 开会 --rate 1.2 --category 工作
to add 阅读 --rate 0.5 --category 学习
to add 游戏 --rate 0.3 --category 娱乐
```

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

```bash
to
```

```text
选择活动

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

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

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

## TUI

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

```bash
to ui
```

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

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

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

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

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

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

## 技能成长

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

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

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

查看成长：

```bash
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`：

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

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

### 能力验证

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

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

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

其他管理命令：

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

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

## 日常命令

### 开始活动

通过选择器开始：

```bash
to
to start
```

直接指定活动：

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

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

### 停止活动

```bash
to stop
```

### 查看今日状态

```bash
to status
```

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

### 管理活动

```bash
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` 开始，可同时修改名称、速率和位置。

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

```bash
to remove 编程 --purge
```

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

### 查看与修正历史

```bash
to history
to history --limit 50
```

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

```bash
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
```

删除错误记录：

```bash
to discard 12
```

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

### 查看配置

```bash
to config
```

修改配置：

```bash
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 个统计日：

```bash
to report
to report week
```

### 日报

```bash
to report today
```

### 月报

展示最近 30 个统计日：

```bash
to report month
```

### 自定义周期

```bash
to report --days 14
to report -d 90
```

周期支持 `1` 到 `366` 天。

### 指定日期范围

```bash
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 写事务中完成。数据库会保证全局最多
只有一条进行中记录；升级时如发现旧版本留下的重复记录，会保留最新一条并
安全结束其余记录。

## 备份、恢复与导出

创建完整数据库备份：

```bash
to backup
to backup ~/Documents/tonus.db
```

导出全部历史记录：

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

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

```bash
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` |

## 数据位置

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

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

```json
{
  "enable_timew": true
}
```

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

## 测试

测试只使用 Python 标准库：

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

## 代码结构

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

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