Metadata-Version: 2.4
Name: Tonus
Version: 2.0.0
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<15,>=13
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`。
- 每项活动有独立消耗速率。
- 工作一分钟产生的疲劳为：`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
to add 阅读 --rate 0.5
```

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

```bash
to
```

```text
选择活动

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

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

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

## 日常命令

### 开始活动

通过选择器开始：

```bash
to
to start
```

直接指定活动：

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

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

### 停止活动

```bash
to stop
```

### 查看今日状态

```bash
to status
```

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

### 管理活动

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

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

### 查看与修正历史

```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 "整理设计规范"
```

删除错误记录：

```bash
to discard 12
```

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

### 查看配置

```bash
to config
```

修改配置：

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

## 统计报表

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

### 周报

默认展示最近 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. **趋势**：日报和周报按天展示；超过 14 天自动按周折叠，避免月报过长。
3. **活动**：只展示主要活动，次要活动合并为“其他”。
4. **节奏**：最长专注、高峰时段、最活跃星期和短记录数量。

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

## 统计准确性

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

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

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