Vega-Starboard/vega-pomodoro-log

# Vega Pomodoro Log [](https://github.com/Vega-Starboard/vega-pomodoro-log/releases) [](https://www.python.org/) [](#design-boundary) [](#privacy) [](#privacy) [](LICENSE) 极简的番茄工作法计时器，专为那些想要一个纯粹本地工作日志，而不是账户、仪表盘、同步服务或生产力信息流的人设计。 Vega Pomodoro Log 是一个无依赖的 Python CLI。它运行专注计时器，将 会话追加到 CSV，汇总时间窗口，并将会话导出到 iCalendar `.ics` 文件，以便用于日历或电子表格工作流。 ## 为什么 小型的安全研究和开发会话很容易被遗忘。一个 25 分钟的 HackerOne 侦察模块、一次 Bug 重现窗口、一次审查过程，或者一次学习 会话，都应该留下清晰的记录，而无需创建另一个云账户。 此工具将记录保存为枯燥、可检查的数据： - 本地 CSV 日志 - UTC 时间戳 - 人类可读的任务、标签和笔记 - 可选的 iCalendar 导出 - 无网络代码 - 无遥测 - 无数据库 - 无后台守护进程 ## 功能 - 从终端运行番茄工作法专注计时器。 - 手动记录已完成或部分的会话。 - 将所有记录存储在简单的 CSV 文件中。 - 按今天、本周、本月或日期范围过滤会话列表和统计信息。 - 将过滤后的会话导出为 iCalendar `.ics`。 - 通过 `--log-file` 或 `VEGA_POMODORO_LOG` 覆盖日志路径。 - 仅使用 Python 标准库。 ## 安装 克隆仓库并从源码运行： ``` git clone https://github.com/Vega-Starboard/vega-pomodoro-log.git cd vega-pomodoro-log PYTHONPATH=src python3 -m vega_pomodoro_log --help ``` 对于可编辑的本地命令： ``` python3 -m pip install --user -e . vega-pomodoro-log --help ``` 此项目不会安装任何包依赖。 ## 快速入门 运行一个正常的 25 分钟专注模块，外加 5 分钟休息： ``` vega-pomodoro-log start --task "HackerOne recon block" --tag bug-bounty ``` 运行一个较短的模块并跳过休息： ``` vega-pomodoro-log start --focus 15 --skip-break --task "Review report draft" --tag writing ``` 事后记录一次会话： ``` vega-pomodoro-log log --task "CSP notes" --minutes 25 --tag headers --notes "Reviewed policy gaps" ``` 显示最近的会话： ``` vega-pomodoro-log list ``` 显示本周的统计信息： ``` vega-pomodoro-log stats --window week ``` 将本月的会话导出到 iCalendar 文件： ``` vega-pomodoro-log export-ics --window month --output pomodoro-month.ics ``` 打印并初始化活动日志路径： ``` vega-pomodoro-log path ``` ## 命令 ### `start` 运行倒计时器并将结果追加到 CSV。 ``` vega-pomodoro-log start \ --focus 25 \ --break 5 \ --task "Endpoint review" \ --tag bug-bounty \ --notes "Scoped program only" ``` 如果使用 `Ctrl+C` 中断，已进行的专注会话仍会被记录为 未完成。 ### `log` 在不运行计时器的情况下追加一次手动会话。 ``` vega-pomodoro-log log \ --task "Write notes" \ --minutes 30 \ --kind review \ --tag report ``` 接受的类型： - `focus` - `break` - `planning` - `review` ### `list` 在终端表格中显示最近的行。 ``` vega-pomodoro-log list --window today vega-pomodoro-log list --from-date 2026-05-01 --to-date 2026-05-09 --limit 50 ``` ### `stats` 汇总计数、完成计数、总分钟数、专注分钟数以及按 标签划分的时间。 ``` vega-pomodoro-log stats --window week ``` ### `export-ics` 将过滤后的会话写入 iCalendar 文件。 ``` vega-pomodoro-log export-ics --from-date 2026-05-01 --output may-focus.ics ``` 传递 `--force` 以覆盖现有文件。 ### `path` 如需要则创建 CSV 文件并打印其位置。 ``` vega-pomodoro-log path ``` ## CSV 结构 默认路径： ``` ~/.local/share/vega-pomodoro-log/sessions.csv ``` 使用以下任一方式覆盖： ``` VEGA_POMODORO_LOG=/path/to/sessions.csv vega-pomodoro-log list vega-pomodoro-log --log-file /path/to/sessions.csv list ``` 字段： | 列 | 含义 | | --- | --- | | `id` | 稳定的短派生 SHA-256 会话 ID | | `started_at_utc` | UTC ISO-8601 会话开始时间 | | `ended_at_utc` | UTC ISO-8601 会话结束时间 | | `duration_minutes` | 十进制持续时间 | | `kind` | `focus`、`break`、`planning` 或 `review` | | `task` | 人类可读的任务标签 | | `tag` | 可选的分组标签 | | `notes` | 可选的笔记 | | `completed` | `true` 或 `false` | | `source` | `timer` 或 `manual` | 示例： ``` id,started_at_utc,ended_at_utc,duration_minutes,kind,task,tag,notes,completed,source 7e2d4a0aef8d57aa,2026-05-09T15:00:00Z,2026-05-09T15:25:00Z,25,focus,HackerOne recon block,bug-bounty,Scoped target review,true,manual ``` ## iCalendar 导出 `export-ics` 生成一个普通的 `.ics` 文件，每个会话对应一个 `VEVENT`。时间以 UTC 写入，包含 `DTSTART`、`DTEND` 和 `DTSTAMP` 值。输出 旨在导入到能够理解 iCalendar 文件的日历工具中。 导出器遵循 RFC 5545 iCalendar 数据的核心结构： - `BEGIN:VCALENDAR` / `END:VCALENDAR` - `VERSION:2.0` - `VEVENT` 条目 - 折叠长行 - 转义文本值 - 以 `Z` 结尾的 UTC 时间戳 ## 隐私 仅限本地。 Vega Pomodoro Log 不会将数据发送到任何地方。它不包含 HTTP 客户端、 套接字、分析、遥测、崩溃报告、远程同步、账户创建 或后台服务。无遥测意味着在正常使用中没有隐藏的收集路径。 CSV 和 `.ics` 文件归您所有。请将它们视为工作记录；它们可能包含 您输入的任务名称或笔记。 ## 设计边界 这是刻意保持小巧的： - 仅限 Python 标准库 - 仅限终端界面 - 仅限本地文件 - 无浏览器自动化 - 无外部日历 API - 无云同步 - 无秘密存储 对于安全研究工作流，请将其用作合法、 授权工作的时间/责任日志。它不是扫描器、漏洞利用工具或目标交互工具。 ## 验证 运行包含的验证器： ``` python3 scripts/verify_pomodoro.py ``` 验证器检查： - CLI 语法是否能编译 - 包中是否没有明显的网络/进程标记 - 手动 CSV 日志记录是否正常工作 - 列表输出是否包含已记录的工作 - 统计输出是否汇总了专注时间 - iCalendar 导出是否包含必需的标记 - 文档是否保持了仅限本地的边界可见性 ## 文档说明 其实现围绕以下官方文档进行设计： - Python `argparse` 命令行解析 - Python `csv` 读写 - Python `datetime` UTC 处理 - RFC 5545 iCalendar 文件结构 - 本 README 中使用的 shields.io 徽章 URL ## 提供者说明 Vega 使用 DeepSeek 对 README 的定位、徽章创意、 边缘情况和验证创意进行了有限范围的批量处理。Codex/GPT 负责处理实现、审查、 验证和发布打包。 ## 标签 `pomodoro-timer`、`cli`、`python`、`time-tracking`、`csv-logging`、 `ics-export`、`productivity`、`local-first`、`no-telemetry`、`hacker-tools`、 `bug-bounty`、`standard-library` ## 状态 版本：`0.1.0` 当前状态：可从源码使用，已在本地验证。

标签：CSV日志, HackerOne, iCalendar, ICS导出, Python, 任务计时, 开发辅助工具, 效率工具, 数据导出, 无依赖, 无后门, 无遥测, 时间管理, 时间记录, 时间跟踪, 本地应用, 番茄工作法, 离线工具, 纯本地存储, 网络安全, 逆向工具, 隐私保护