@cacinie/cace-timer 1.0.0 → 1.3.1

package/README.md

@@ -1,333 +1,485 @@
-# CACE TIMER
+# cace-timer
 
-一个极简的时间记录 CLI 工具，配有可爱的短发小女孩动画吉祥物。
+[![npm version](https://img.shields.io/npm/v/@cacinie/cace-timer.svg)](https://www.npmjs.com/package/@cacinie/cace-timer)
+[![npm downloads](https://img.shields.io/npm/dm/@cacinie/cace-timer.svg)](https://www.npmjs.com/package/@cacinie/cace-timer)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](package.json)
+[![license](https://img.shields.io/npm/l/@cacinie/cace-timer.svg)](https://github.com/CacinieP/cace-timer/blob/main/LICENSE)
 
-## 安装
+A gamified time-tracking CLI with an interactive TUI dashboard, points & levels, and a cute mascot.
 
-```bash
-cd timekeeper
-npm link
+```
+npm install -g @cacinie/cace-timer
 ```
 
-安装后全局命令 `tk` 即可使用。
+```
+       ╭──────────╮
+       │  ●   ●   │
+       │    ▽     │
+       │   ───    │
+       ╰──┬────┬──╯
+       ╭──┴────┴──╮
+       │  ╔════╗  │
+       │  ║ CACE║  │
+       │  ╚════╝  │
+       ╰────┬┬────╯
+         ╭──┘└──╮
+         │      │
+         ╰──┬┬──╯
+           ╭┘└╮
+       CACE TIMER
+```
 
-## 快速开始
+## Features
+
+- **Smart Dashboard** — run `tk` and get a context-aware interactive menu
+- **Points & Levels** — earn points for focus, level up from Lv.1 to Lv.99
+- **Daily Streaks** — consecutive days of productivity tracked with 🔥
+- **Pomodoro Timer** — full-screen TUI countdown with mascot and progress bar
+- **Quick Focus** — `tk focus 5/15/30/60` for instant timer
+- **Reflection** — record thoughts when completing tasks
+- **Statistics** — daily/weekly/monthly reports with ASCII charts
+- **Bilingual** — `--lang zh|en`, auto-detects system locale
+- **Export** — CSV or Markdown output
+- **Cloud Sync** — point data file at Dropbox/iCloud/OneDrive
+
+## Quick Start
 
 ```bash
-# 开始一个任务
-tk start "写周报" --tag work --estimate 30
+# Open the interactive dashboard
+tk
 
-# 记录进度节点
+# Or use commands directly
+tk start "写周报" --tag work --tag daily --estimate 30
 tk mark "完成数据分析"
-
-# 查看当前状态
 tk status
-
-# 结束任务（显示效率评分）
 tk stop
 ```
 
-## 命令一览
+## Smart Dashboard
 
-### tk start
+Running `tk` with no arguments opens an interactive TUI dashboard:
 
-开始新任务。
-
-```bash
-tk start <任务名> [选项]
-
-选项:
-  --tag <标签>       添加标签
-  --estimate <分钟>  预估时长（用于计算效率分）
+**No active task:**
 ```
-
-示例：
-```bash
-tk start "开发登录功能" --tag coding --estimate 60
+  [CACE mascot — sleepy]
+  📊 Lv.2 | 20 pts | 🔥 3 day streak
+
+  [s] 🚀 Start task
+  [f] 🍅 Quick focus
+  [b] 📊 Statistics
+  [l] 📋 History
+  [?] ❓ Help
 ```
 
-### tk mark
-
-记录时间节点。
-
-```bash
-tk mark <备注>
+**Active task in progress:**
 ```
+  [CACE mascot — focused]
+  📊 Lv.2 | 20 pts
 
-示例：
-```bash
-tk mark "完成API接口"
-tk mark "开始写测试"
+  🔥 In progress: 写周报 | Elapsed: 15m 30s
+
+  [m] 📍 Mark checkpoint
+  [s] ⏹  Stop task
+  [b] 📊 Statistics
+  [l] 📋 History
+  [?] ❓ Help
 ```
 
-### tk stop
+## Commands
 
-结束当前任务，显示总结和效率评分。
+### `tk start <task> [options]`
 
-```bash
-tk stop
-```
+Start a new task. Supports multiple tags.
 
-效率评分规则：
-- 实际时长 ≤ 预估时长 → 100%（🏆 优秀）
-- 实际时长稍超预估 → 80-99%（💪 良好）
-- 实际时长远超预估 → <50%（💀 需改进）
+| Option | Description |
+|--------|-------------|
+| `--tag <tag>` | Add tag(s). Repeatable: `--tag dev --tag api` or `--tag dev,api` |
+| `--estimate <minutes>` | Estimated duration for efficiency scoring |
 
-### tk status
+### `tk stop [options]`
 
-查看当前进行中的任务状态。
+Stop current task. Shows summary, efficiency score, and points earned.
 
-```bash
-tk status
-```
+| Option | Description |
+|--------|-------------|
+| `--reflection <text>` | Attach a completion note |
 
-### tk list
+In interactive terminals, a TUI input box appears for reflection.
 
-查看历史记录。
-
-```bash
-tk list [选项]
+### `tk mark <note>`
 
-选项:
-  --today         仅显示今天
-  --tag <标签>    按标签筛选
-  --limit <数量>  限制显示数量（默认10）
-```
+Record a time checkpoint within the active task.
 
-示例：
-```bash
-tk list --today
-tk list --tag coding --limit 20
-```
+### `tk status`
 
-### tk search
+Show current task, level, and streak.
 
-搜索历史记录。
+### `tk list [options]`
 
-```bash
-tk search <关键词>
-```
+| Option | Description |
+|--------|-------------|
+| `--today` | Today only |
+| `--tag <tag>` | Filter by tag |
+| `--limit <n>` | Limit count (default 10) |
 
-会搜索任务名、标签、标记备注。
+### `tk search <keyword>`
 
-```bash
-tk search "登录"
-tk search "coding"
-```
+Search across task names, tags, and mark notes.
 
-### tk sync
+### `tk summary [options]`
 
-设置同步文件路径，实现跨设备同步。
+Statistics report with ASCII charts.
 
-```bash
-tk sync <文件路径>
-```
+| Option | Description |
+|--------|-------------|
+| `--today` | Today only |
+| `--week` | This week (Monday start) |
+| `--month` | This month |
+| `--tag <tag>` | Filter by tag |
 
-建议将同步文件放在云盘目录：
-```bash
-tk sync ~/Dropbox/cace-timer.json
-tk sync ~/OneDrive/cace-timer.json
-```
+Shows: total sessions, total/average duration, tag distribution bars, daily hours chart (last 7 days), top 5 longest tasks.
 
-## 数据同步指南
+### `tk delete <id | --last>`
 
-### 工作原理
+Delete a session from history.
 
-CACE TIMER 采用**单文件同步**策略：
+### `tk resume <id | --last>`
 
-```
-┌─────────────┐         ┌─────────────┐
-│   设备 A    │         │   设备 B    │
-│  ~/(本地)   │         │  ~/(本地)   │
-│ .cace-timer │         │ .cace-timer │
-│    .json    │         │    .json    │
-└──────┬──────┘         └──────┬──────┘
-       │                       │
-       ▼                       ▼
-┌─────────────────────────────────────┐
-│         云盘同步目录                  │
-│   Dropbox / iCloud / OneDrive       │
-│        cace-timer.json              │
-└─────────────────────────────────────┘
-```
+Resume a completed task as a new session.
 
-每次执行 `tk` 命令时：
-1. 写入本地 `~/.cace-timer.json`
-2. 同时写入配置的 `syncPath`（如果设置了）
+### `tk export [options]`
 
-### 设置步骤
+| Option | Description |
+|--------|-------------|
+| `--format csv\|markdown` | Output format (default: csv) |
+| `--output <file>` | Write to file (default: stdout) |
 
-#### Dropbox
+### `tk pomodoro <task> [options]`
 
-```bash
-# macOS / Linux
-tk sync ~/Dropbox/cace-timer.json
+Full-screen TUI pomodoro timer with mascot, countdown, and encouragement.
 
-# Windows
-tk sync "%USERPROFILE%\Dropbox\cace-timer.json"
-```
+| Option | Description |
+|--------|-------------|
+| `--work <minutes>` | Work duration (default: 25) |
+| `--break <minutes>` | Break duration (default: 5) |
+| `--rounds <n>` | Number of rounds (default: 4) |
+| `--tag <tag>` | Add tag(s) |
 
-#### iCloud
+### `tk focus <5\|15\|30\|60> [task]`
 
-```bash
-# macOS
-tk sync ~/Library/Mobile\ Documents/com~apple~CloudDocs/cace-timer.json
-```
+Quick one-shot focus timer. Shortcut for `tk pomodoro` with 1 round.
 
-#### OneDrive
+### `tk sync <path>`
 
-```bash
-# macOS
-tk sync ~/OneDrive/cace-timer.json
+Set sync file path for cross-device sync.
 
-# Windows
-tk sync "%USERPROFILE%\OneDrive\cace-timer.json"
-```
+### `--lang <zh|en>`
 
-#### 自建同步 (Syncthing / Resilio)
+Set language. Auto-detects system locale. Persists to config.
 
-```bash
-tk sync ~/Sync/cace-timer.json
-```
+### `tk help`
 
-### 多设备使用
+Show full command reference.
 
-**首次在设备 B 使用：**
+## Gamification
 
-```bash
-# 1. 安装 CACE TIMER
-cd timekeeper && npm link
+### Points System
 
-# 2. 设置同步路径（指向云盘已同步的文件）
-tk sync ~/Dropbox/cace-timer.json
+| Condition | Points |
+|-----------|--------|
+| Complete a task | +10 |
+| Efficiency ≥ 80% | +5 bonus |
+| Efficiency = 100% | +5 bonus |
+| Deep work (≥ 25 min) | +5 bonus |
 
-# 3. 查看同步的数据
-tk list
-```
+### Levels
 
-**注意：** 新设备需要先设置 `tk sync`，然后才能读取云盘数据。
+Progressive XP curve: each level requires `level × 20` more points.
 
-### 同步冲突处理
+| Level | Total Points |
+|-------|-------------|
+| 1 | 0 |
+| 2 | 20 |
+| 3 | 60 |
+| 5 | 200 |
+| 10 | 900 |
 
-由于采用单文件策略，建议：
+### Daily Streak
 
-| 场景 | 建议 |
-|------|------|
-| 多设备同时使用 | 避免同时在多个设备操作 |
-| 云盘同步延迟 | 操作后等待几秒再切换设备 |
-| 冲突文件 | 手动合并 JSON，保留需要的记录 |
+Consecutive days with at least one completed task. Break a day and the streak resets.
 
-### 手动备份
+## CACE Mascot
 
-```bash
-# 导出备份
-cp ~/.cace-timer.json ~/backup/cace-timer-$(date +%Y%m%d).json
+CACE has 5 moods that change based on context:
 
-# 恢复备份
-cp ~/backup/cace-timer-20240302.json ~/.cace-timer.json
-```
+| Mood | Eyes | Mouth | When |
+|------|------|-------|------|
+| Normal | ● ● | ─── | Default display |
+| Happy | ★ ★ | ◡◡◡ | Task completed |
+| Focused | ◆ ◆ | ▬▬▬ | Pomodoro / active task |
+| Celebrating | ◉ ◉ | ▽△▽ | Points earned + arms up |
+| Sleepy | ─ ─ | ～～ | No active task |
 
-### 数据格式
+## Data
 
-同步文件为标准 JSON 格式：
+All data stored in `~/.cace-timer.json`.
 
 ```json
 {
-  "syncPath": "/Users/you/Dropbox/cace-timer.json",
+  "syncPath": "~/Dropbox/cace-timer.json",
+  "lang": "zh",
+  "score": 45,
+  "streak": 3,
+  "lastActiveDate": "2026-05-31",
   "current": null,
   "history": [
     {
       "id": "lq3x9k2",
-      "task": "开发功能",
-      "start": "2024-03-02T10:00:00.000Z",
-      "end": "2024-03-02T11:30:00.000Z",
-      "tags": ["coding"],
-      "marks": [
-        { "time": "2024-03-02T10:30:00.000Z", "note": "完成API" }
-      ],
-      "estimatedMinutes": 60
+      "task": "写周报",
+      "start": "2026-05-31T10:00:00.000Z",
+      "end": "2026-05-31T10:30:00.000Z",
+      "tags": ["work", "daily"],
+      "marks": [{ "time": "...", "note": "完成数据分析" }],
+      "estimatedMinutes": 30,
+      "reflection": "今天效率不错",
+      "pointsEarned": 20
     }
   ]
 }
 ```
 
-### 取消同步
+## Uninstall
+
+```bash
+npm uninstall -g @cacinie/cace-timer
+```
+
+## Changelog
 
-编辑 `~/.cace-timer.json`，删除 `syncPath` 字段即可。
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+MIT
 
 ---
 
-### tk help
+# cace-timer 中文说明
 
-显示帮助信息。
+[![npm version](https://img.shields.io/npm/v/@cacinie/cace-timer.svg)](https://www.npmjs.com/package/@cacinie/cace-timer)
+[![npm downloads](https://img.shields.io/npm/dm/@cacinie/cace-timer.svg)](https://www.npmjs.com/package/@cacinie/cace-timer)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](package.json)
+[![license](https://img.shields.io/npm/l/@cacinie/cace-timer.svg)](https://github.com/CacinieP/cace-timer/blob/main/LICENSE)
+
+游戏化时间追踪 CLI，带交互式 TUI 仪表盘、积分等级系统和可爱吉祥物。
+
+```
+npm install -g @cacinie/cace-timer
+```
+
+## 特性
+
+- **智能仪表盘** — 输入 `tk` 即可打开上下文感知的交互菜单
+- **积分与等级** — 完成任务赚积分，从 Lv.1 升到 Lv.99
+- **每日打卡** — 连续天数追踪，显示火焰 🔥
+- **番茄钟** — 全屏 TUI 倒计时 + 吉祥物 + 进度条
+- **快捷专注** — `tk focus 5/15/30/60` 一键开始
+- **完成心得** — 任务完成时记录感想
+- **统计报表** — 日/周/月统计，ASCII 柱状图
+- **双语支持** — `--lang zh|en`，自动检测系统语言
+- **数据导出** — CSV 或 Markdown 格式
+- **云同步** — 数据文件指向 Dropbox/iCloud/OneDrive
+
+## 快速开始
 
 ```bash
-tk help
+# 打开交互仪表盘
+tk
+
+# 或直接用命令
+tk start "写周报" --tag work --tag daily --estimate 30
+tk mark "完成数据分析"
+tk status
+tk stop
 ```
 
-## CACE 吉祥物
+## 智能仪表盘
 
-CACE 是一个可爱的短发小女孩头像：
+输入 `tk`（无参数）打开 TUI 仪表盘：
 
+**无活跃任务：**
 ```
-   ▄▄▄▄▄▄▄▄▄▄▄
-  █░░░░░░░░░░░█   ← 刘海
-  █░▄▄▄▄▄▄▄▄▄░█
-  █░│ ●   ● │░█   ← 大眼睛
-  █░│   ▽   │░█   ← 小鼻子
-  █░│  ───  │░█   ← 嘴巴
-  ╰───────────╯
+  [CACE 吉祥物 — 困了]
+  📊 Lv.2 | 20 积分 | 🔥 连续 3 天
+
+  [s] 🚀 开始任务
+  [f] 🍅 快捷专注
+  [b] 📊 统计报表
+  [l] 📋 历史记录
+  [?] ❓ 帮助
 ```
 
-**动画表情：**
+**有活跃任务：**
+```
+  [CACE 吉祥物 — 专注中]
+  📊 Lv.2 | 20 积分
 
-| 状态 | 眼睛 | 嘴巴 | 触发场景 |
-|------|------|------|----------|
-| 正常 | ● ● | ─── | 默认状态 |
-| 开心 | ★ ★ | ◡◡◡ | 完成任务 |
-| 眨眼 | ─ ─ | ─── | 动画帧 |
-| 超开心 | ◉ ◉ | ▽△▽ | 动画帧 |
-| 困倦 | ─ ─ | ─── | 无任务时 |
+  🔥 进行中: 写周报 | 已用时: 15m 30s
 
-动画循环：正常 → 眨眼 → 开心 → 超开心（循环2次）
+  [m] 📍 标记进度
+  [s] ⏹  停止任务
+  [b] 📊 统计报表
+  [l] 📋 历史记录
+  [?] ❓ 帮助
+```
 
-## 数据存储
+## 命令
 
-数据保存在 `~/.cace-timer.json`：
+### `tk start <任务名> [选项]`
 
-```json
-{
-  "syncPath": "~/Dropbox/cace-timer.json",
-  "current": null,
-  "history": [
-    {
-      "id": "xxx",
-      "task": "写周报",
-      "start": "2024-03-02T10:00:00Z",
-      "end": "2024-03-02T10:30:00Z",
-      "tags": ["work"],
-      "marks": [
-        { "time": "2024-03-02T10:15:00Z", "note": "完成数据分析" }
-      ],
-      "estimatedMinutes": 30
-    }
-  ]
-}
-```
+开始新任务，支持多标签。
+
+| 选项 | 说明 |
+|------|------|
+| `--tag <标签>` | 多标签：`--tag dev --tag api` 或 `--tag dev,api` |
+| `--estimate <分钟>` | 预估时长（效率评分） |
+
+### `tk stop [选项]`
+
+停止当前任务，显示摘要、效率评分、获得积分。
+
+| 选项 | 说明 |
+|------|------|
+| `--reflection <文本>` | 附加完成心得 |
+
+交互终端中会自动弹出输入框。
+
+### `tk mark <备注>`
+
+在活跃任务中记录时间节点。
+
+### `tk status`
+
+显示当前任务、等级和打卡天数。
+
+### `tk list [选项]`
+
+| 选项 | 说明 |
+|------|------|
+| `--today` | 仅今天 |
+| `--tag <标签>` | 按标签筛选 |
+| `--limit <数量>` | 限制数量（默认 10） |
+
+### `tk search <关键词>`
+
+搜索任务名称、标签和标记备注。
+
+### `tk summary [选项]`
+
+统计报表，带 ASCII 柱状图。
+
+| 选项 | 说明 |
+|------|------|
+| `--today` | 仅今天 |
+| `--week` | 本周（周一开始） |
+| `--month` | 本月 |
+| `--tag <标签>` | 按标签筛选 |
+
+### `tk delete <id | --last>`
+
+删除历史记录。
+
+### `tk resume <id | --last>`
+
+恢复已完成任务为新会话。
+
+### `tk export [选项]`
+
+| 选项 | 说明 |
+|------|------|
+| `--format csv\|markdown` | 输出格式（默认 csv） |
+| `--output <文件>` | 输出到文件（默认 stdout） |
+
+### `tk pomodoro <任务名> [选项]`
+
+全屏 TUI 番茄钟，带吉祥物、倒计时和鼓励语。
+
+| 选项 | 说明 |
+|------|------|
+| `--work <分钟>` | 工作时长（默认 25） |
+| `--break <分钟>` | 休息时长（默认 5） |
+| `--rounds <数量>` | 轮数（默认 4） |
+| `--tag <标签>` | 添加标签 |
+
+### `tk focus <5\|15\|30\|60> [任务名]`
+
+快捷专注，一键启动单轮番茄钟。
+
+### `tk sync <路径>`
+
+设置同步文件路径。
+
+### `--lang <zh|en>`
+
+设置语言，自动检测系统语言，持久化到配置。
 
-## 使用场景
+### `tk help`
 
-- **编程开发**：记录编码时间，评估效率
-- **学习复习**：跟踪学习时长和进度
-- **项目管理**：标记关键节点，回顾时间分配
-- **自由职业**：为客户项目计时
+显示完整命令参考。
+
+## 游戏化
+
+### 积分系统
+
+| 条件 | 积分 |
+|------|------|
+| 完成任务 | +10 |
+| 效率 ≥ 80% | +5 奖励 |
+| 效率 = 100% | +5 奖励 |
+| 深度工作（≥ 25 分钟） | +5 奖励 |
+
+### 等级系统
+
+递增经验曲线：每级需要 `等级 × 20` 积分。
+
+| 等级 | 总积分 |
+|------|--------|
+| 1 | 0 |
+| 2 | 20 |
+| 3 | 60 |
+| 5 | 200 |
+| 10 | 900 |
+
+### 每日打卡
+
+连续每天完成至少一个任务。中断一天则重新计数。
+
+## CACE 吉祥物
+
+CACE 有 5 种心情，根据场景变化：
+
+| 心情 | 眼睛 | 嘴巴 | 时机 |
+|------|------|------|------|
+| 正常 | ● ● | ─── | 默认显示 |
+| 开心 | ★ ★ | ◡◡◡ | 任务完成 |
+| 专注 | ◆ ◆ | ▬▬▬ | 番茄钟 / 活跃任务 |
+| 庆祝 | ◉ ◉ | ▽△▽ | 获得积分 + 举手 |
+| 困了 | ─ ─ | ～～ | 无活跃任务 |
+
+## 数据
+
+所有数据存储在 `~/.cace-timer.json`。
 
 ## 卸载
 
 ```bash
-npm unlink -g cace-timer
+npm uninstall -g @cacinie/cace-timer
 ```
 
-## License
+## 更新日志
+
+详见 [CHANGELOG.md](CHANGELOG.md)。
+
+## 许可
 
 MIT