缘起

我一直在用 worklog 做时间记录——一个简单的 CLI 工具,记录什么时候开始做什么、花了多久、每天/周/月统计。它管的是过去:你干过什么,花了多少时间。

但慢慢觉得缺了点什么。worklog 不关心你为什么要做一件事,不关心你预期做成什么样,也不关心你打算怎么做。它只告诉你「昨天写了 3 小时代码」,但不知道那代码解决什么问题、做到什么程度才算完、下一步该做什么。

于是有了 planx。

设计哲学

planx 不是 worklog 的替代品,它是另一个方向的工具。

反身性设计(Reflexivity)

每个任务创建时必须填写三个字段。不填不行,CLI 会强制你填:

  • 意义(significance)——为什么做这件事?不做会怎样?
  • 预期(outcome)——做完之后,成果是什么?怎么算「完成」?
  • 路径(approach)——怎么达成?第一步做什么?

这三个字段加起来,就是让一个任务不是单纯的 todo 条目,而是有「来龙去脉」的意图单元。

现象学记录

任务执行过程中可以随时记两样东西:

  1. 反思笔记(note)——写到哪了,卡在哪里,有什么新发现
  2. 上下文快照(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
remindTermux 通知,定时/延时提醒,优先级策略core/reminder.py
context上下文快照,情绪/障碍/备注,绑定任务core/context.py
scheduletermux-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?

答案是:不需要集成,但可以互补。

维度planxworklog
时间方向面向未来(计划、项目管理、提醒)面向过去(时间记录、统计)
数据模型SQLite 关系型,4 表 FKJSON 扁平文件
核心字段意义/预期/路径/情绪/障碍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 做生产力工具,欢迎交流想法。