缘起
我一直在用 worklog 做时间记录——一个简单的 CLI 工具,记录什么时候开始做什么、花了多久、每天/周/月统计。它管的是过去:你干过什么,花了多少时间。
但慢慢觉得缺了点什么。worklog 不关心你为什么要做一件事,不关心你预期做成什么样,也不关心你打算怎么做。它只告诉你「昨天写了 3 小时代码」,但不知道那代码解决什么问题、做到什么程度才算完、下一步该做什么。
于是有了 planx。
设计哲学
planx 不是 worklog 的替代品,它是另一个方向的工具。
反身性设计(Reflexivity)
每个任务创建时必须填写三个字段。不填不行,CLI 会强制你填:
- 意义(significance)——为什么做这件事?不做会怎样?
- 预期(outcome)——做完之后,成果是什么?怎么算「完成」?
- 路径(approach)——怎么达成?第一步做什么?
这三个字段加起来,就是让一个任务不是单纯的 todo 条目,而是有「来龙去脉」的意图单元。
现象学记录
任务执行过程中可以随时记两样东西:
- 反思笔记(note)——写到哪了,卡在哪里,有什么新发现
- 上下文快照(context log)——当时的情绪状态、遇到的障碍、备注
这些不是靠回忆补填的,而是在任务进行中记的。回头看的时候,时间线上能看到:当时是什么状态、卡在什么问题上、最后是怎么解决的。
推送通知
既然是手机上的 Termux 工具,通知系统是必须的。planx 的 remind 子系统用了 Termux API:
- 定时提醒——某天某时提醒你做某个任务
- 延时提醒——「30 分钟后提醒我」
- 优先级驱动的通知策略——P1 任务每 15 分钟震动+语音提醒,P5 只出现在每日汇总
- 后台 Job 调度——注册两个 termux-job-scheduler 任务:每天 9:00 做当日汇总推送,每 30 分钟检查到期提醒
架构一览
| 模块 | 职责 | 核心文件 |
|---|---|---|
project | 项目 CRUD,任务按项目归类 | core/project.py |
task | 任务 CRUD,反身性字段,生命周期状态机 | core/task.py |
remind | Termux 通知,定时/延时提醒,优先级策略 | core/reminder.py |
context | 上下文快照,情绪/障碍/备注,绑定任务 | core/context.py |
schedule | termux-job-scheduler 注册 | core/scheduler.py |
notifier | 通知本质逻辑(TTS/震动/按钮回复) | core/notifier.py |
数据层用 SQLite,4 张表(projects / tasks / reminders / context_log),WAL 模式,外键约束。
任务状态机:
todo → in_progress → done
→ cancelled
→ blocked → reopen → todo
一个使用流程的缩影
# 1. 创建一个项目
px project add "个人博客" "建立个人技术品牌"
# 2. 创建一个任务(必须填意义/预期/路径)
px task add "个人博客" "写一篇关于设计模式的文章" \
-s "用输出倒逼输入,加深对设计模式的理解" \
-o "一篇 3000 字以上的技术博客,配代码示例" \
-a "选题→大纲→初稿→审校→发布" \
-p 2
# 3. 开始执行
px task start 0cae8d49
# 4. 记录反思
px task note 0cae8d49 "今天开始写策略模式章节,感觉可以结合实际项目例子切入"
# 5. 记录上下文(当时的状态)
px context log 0cae8d49 -m 专注 -b 无 -n "今天状态很好,冲"
# 6. 完成
px task done 0cae8d49 -o "完成了一篇 2500 字技术博客并发布"
# 7. 查看任务详情——反思和上下文会显示在时间线上
px task show 0cae8d49
一个值得记下来的 Bug
开发过程中遇到一个有意思的坑。所有 ID 都用 32 位 UUID hex 字符串,CLI 显示只截取前 8 位方便阅读。但内部所有模块(task/context/reminder)的 INSERT/UPDATE/DELETE 都直接用短 ID 操作数据库——外键约束全炸了。
修复模式很统一:在执行任何需要确切 FK 值的操作之前,先通过 LIKE 前缀匹配从数据库 resolve 出完整的 UUID。 最终在三个模块里用了同样的模式:
def _resolve_task_id(self, task_id: str) -> Optional[str]:
row = conn.execute("SELECT id FROM tasks WHERE id = ?", (task_id,)).fetchone()
if not row and len(task_id) < 32:
rows = conn.execute("SELECT id FROM tasks WHERE id LIKE ?", (task_id + "%",)).fetchall()
if len(rows) == 1:
row = rows[0]
return row["id"] if row else None
教训:短 ID 显示和全量 ID 存储是两套东西,中间一定要有一个 resolve 层。
Planx vs Worklog:站在一起的两种视角
做完 planx 后,我认真想了一个问题:这个工具需要和 worklog 配合吗?还是它本质上已经覆盖了 worklog?
答案是:不需要集成,但可以互补。
| 维度 | planx | worklog |
|---|---|---|
| 时间方向 | 面向未来(计划、项目管理、提醒) | 面向过去(时间记录、统计) |
| 数据模型 | SQLite 关系型,4 表 FK | JSON 扁平文件 |
| 核心字段 | 意义/预期/路径/情绪/障碍 | start_time/end_time/duration |
| 通知 | Termux 震动+TTS+按钮回复 | 无 |
| 统计 | 无(当前不关心花了多久) | 今日/周/月时长统计 |
| 导出 | 无 | CSV/JSON 导出 |
planx 管的是「为什么做、做什么、怎么做」,worklog 管的是「什么时候做、花了多久」。方向不同,数据模型也不同(SQLite vs JSON),强行集成反而会让事情变复杂。
但它们恰好可以各自回答对方不关心的问题:
- planx 不关心实际耗时 → 可以用 worklog 补
- worklog 不关心任务的意义和上下文 → 可以用 planx 补
如果将来需要桥接,一个简单的脚本就够了——从 planx 任务标题联动到 worklog start,从 worklog 的实际耗时回写到 planx 的 actual_minutes 字段。
但目前不打算做这个桥接。先让 planx 自己成熟起来(尤其是通知系统的稳定性),worklog 继续独立工作。
现状
planx v1.0 完工,代码在自己的 Termux 上跑通了全部流程。GitHub 还没公开,目前是个自用工具。
如果你也在用 Termux 做生产力工具,欢迎交流想法。