1. 为什么我坚持用命令行做待办事项管理
我一直有个执念：日常待办这件事，不应该被一个占着几百兆内存的图形应用绑架。两年前我换回命令行做待办事项应用，把任务管理彻底搬进终端之后，最大的感受不是"变酷了"，而是"负担消失了"。打开手机备忘录要解锁、找图标、等加载、点新建，再输两三行字，这一套流程下来快也要十秒；而命令行只需要一个固定命令，输入任务名，回车，完事。这个差距在一天只记三五条时不明显，但当它变成每天要操作几十次的高频动作时，操作成本直接决定了你愿不愿意用。
我构建的这套东西，本质上是一个"任务记录与执行状态跟踪器"。它能让你在终端里随时随地新增任务、列出未完成事项、标记完成、删除误录条目，还能按优先级排序、模糊搜索、输出统计报表。听起来功能不多，但恰恰是这些有限的、明确的功能，构成了一个稳定的日常中枢。它适合三类人：一是日常重度使用终端、不想切换上下文的开发者；二是习惯GTD但讨厌被花哨UI带偏节奏的效率控；三是对数据归属极其敏感，希望待办记录以纯文本形式掌握在自己手里的使用者。
很多朋友会问：市面上Todoist、滴答清单、Microsoft To Do不都挺好吗？功能又多又好看，你这不是自己造轮子吗？我的回答是：是，但也不完全是。图形工具的打卡、日历联动、云同步确实香，但它们的核心交互逻辑是"打开应用、找到位置、点击按钮"，而命令行的核心逻辑是"输入指令、直接执行"。前者适合"在App内浏览和管理任务"，后者适合"在任何界面下无脑添加任务并快速看到结果"。如果你的工作主战场就是终端，那么一个工具如果不在终端里，它就不存在。这才是命令行待办事项应用最大的意义——它把任务管理从一次"任务"变成了一次"操作"。
本文会把我从设计到实现、再到日常打磨的全部过程拆开来讲，包含数据存储选型、命令解析逻辑、显示优化、Shell集成、常见坑位，以及我是如何去平衡"够用就好"和"持续演化"这两件事的。如果你也想做一个自己真正会天天用的命令行小工具，这篇应该能帮你少走不少弯路。
2. 定位与方案选型：这不只是一段脚本，而是一个"随手就能用"的系统
2.1 从一次随手记录开始的产品边界
做命令行工具最大的诱惑是"无限加功能"。今天想加个日历视图，明天想加个番茄钟，后天想接入云同步，功能越加越多，最终变成一个窝在终端里的四不像。我在第一版就给自己划定了边界：它只做四件事——记录任务、查看任务、变更状态、删除任务。辅助能力只保留两项：按优先级或时间过滤、统计完成情况。除此之外的一切功能，都通过"开放数据"去交给外部工具完成，而不是全部塞进应用本身。
这个思路来自一个很朴素的观察：待办事项这个品类的核心价值不是"管理"而是"记录与提醒"。图形应用把大量精力花在日历、分类、标签、项目、协作上，但对个人高频使用来说，真正每天被重度调用的还是"我接下来要做什么"和"这件事做完了没有"两件事。其余的记录周期越长的功能，越不常用，也就越不值得为它增加应用复杂度。
确定边界后，我在纸上列了一张功能优先级表：
| 优先级 | 功能 | 核心诉求 | 实现复杂度 |
|---|---|---|---|
| P0 | 新增任务 (add) | 最快的路径记下待办 | 低 |
| P0 | 列出任务 (list) | 一眼看清今天剩什么 | 低 |
| P0 | 完成任务 (done) | 状态流转 | 低 |
| P0 | 删除任务 (delete) | 误录后的兜底 | 低 |
| P1 | 编辑内容 (edit) | 修正任务描述 | 中 |
| P1 | 按优先级/日期过滤 | 聚焦高价值事项 | 中 |
| P2 | 统计报表 | 周度/月度自我回顾 | 低 |
| P2 | 自然语言添加 | 如"明天上午9点开会" | 高 |
P0是上线第一天必须有的，P1是第二周迭代的，P2则属于"有空再想想"的范畴。实际经验告诉我，P2这两项的优先级后来证明排得很对——统计功能确实做完了且很好用，但自然语言解析被我砍掉了，因为引入时间解析库的收益远不如在输入时用固定格式写日期来得直接。
2.2 数据存储选型：JSON文件为什么比SQLite和CSV都顺手
存储方案是我最先纠结的点。围绕这个问题，我认真对比了三种主流方案：CSV纯文本、JSON结构化文件、SQLite嵌入式数据库。它们的差异看似只在技术层面，实际上直接决定了这个工具的备份方式、可调试性和后期扩展空间。
CSV的问题在于表达能力太弱。任务描述里的逗号、换行、引号需要转义，优先级、创建时间、完成时间、标签这些字段要么拆列，要么挤在一个格子里。一旦字段结构有变化，CSV的解析逻辑就要跟着乱。早期我也试过用CSV做速记版TaskManager，到后面基本只能应付"任务名+完成状态"两列，再想往里面加"截止日期"和"标签"就得重构。
SQLite是很多人的第一反应：用数据库嘛，稳、支持并发、查询灵活。但放到这个场景里，SQLite有点杀鸡用牛刀。待办事项数据量撑死几千条，单机单人写入频率不高，而且SQLite文件不可直接用文本编辑器查看，想快速改一条数据还要装个客户端或敲SQL语句，这对一个"务求随手"的命令行工具来说反而增加了心智负担。还有一个最实际的问题：如果把待办数据放在SQLite里，git仓库的diff就完全不可读了，我无法用版本管理看到"今天改了哪条任务"。
最终我选择了JSON文件。理由有三：一是结构表达能力强，嵌套字段清晰，字段变更时兼容性好；二是人类可读，随时随地打开文件用编辑器改，改动后应用重新读取即可；三是和版本管理天然亲和，每一条待办的增删改都能在git diff里清清楚楚地看到。配套做一个简单的原子写入（先写临时文件再替换），就能规避掉大部分数据损坏风险。
2.3 文件放哪里：用户目录与当前目录的边界
数据文件放在哪里，直接影响这个工具在多目录下的一致性。我最初犯过一个低级错误：把待办数据存在当前工作目录下的todo.json里，结果换个文件夹打开终端就看不到之前的任务了。后来改成统一放在用户主目录下的隐藏配置目录，比如~/.local/todo/tasks.json（Linux/macOS）和%USERPROFILE%\.todo\tasks.json（Windows），工具内部通过环境变量自动判断系统类型，再拼接出完整路径。这样无论你在哪个目录下敲命令，读到的都是同一份全局待办列表。
当然，有些偏执的用法是把任务文件和项目绑定，比如每个Git仓库都有自己的TODO.json，配合Commit信息做项目级任务管理。这个我后来也支持了，使用规则是：如果当前目录有一个显式的./.todo.json，优先读它；否则读全局文件。两种模式互相不干扰，全局管"生活日常"，项目级管"开发任务"，各有各的使用场景。
2.4 原子性写入：防止断电和异常把数据写坏
命令行工具最怕的是写文件写一半崩了，导致整份待办丢失。我采用的方案很朴素：每次写数据时，先把内存中的数据序列化到一个临时文件，比如tasks.json.tmp，写完后再用os.replace()把临时文件改名为正式文件。这个操作的原子性由操作系统底层保证，要么旧文件还在，要么新文件完整替换，不会出现"读到半个文件"的情况。
此外，我还在启动时做了一个快速自检：读文件后立刻用JSON解析器验证，如果解析失败，不直接覆盖写入，而是在当前目录生成一个tasks.json.corrupted-时间戳.bak，保留现场以便事后恢复。这个机制看起来不起眼，但真的救过我一命——有一次我手动编辑文件时语法写错了一半，如果应用不管三七二十一直接写入，数据就彻底废了。因为有这层保护，我只需要从备份文件里手工恢复那一次没保存的改动就行。
3. 核心命令链路设计：add、list、done、delete是怎么互相配合的
3.1 命令解析：手写解析器还是用argparse
很多入门教程教你用argparse做一个带子命令的工具：todo add "买牛奶"，todo list，todo done 3。可是真到了"每天要敲几十次"的场景，argparse那种带帮助信息、位置参数、可选参数的交互方式会显得笨重。比如todo add --priority high "写方案"，每次都要敲--priority，手速快不起来。
我最终的实现是两者结合：外层用argparse做标准的命令分发和帮助文档，但给高频选项做了短标志和默认值。比如优先级默认是"中"，想标记高优先级，只需todo add -p high 任务名。同时为了兼容"随手输入"的习惯，我允许todo a 任务名这样的短命令。命令设计的原则只有一条：减少手指移动。所有常用操作的按键次数不能超过15次。
命令的规划如下：
| 命令 | 别名 | 作用 | 示例 |
|---|---|---|---|
| add | a | 新增任务 | todo a 写周报 -p high |
| list | ls | 列出未完成任务 | todo ls或todo ls --all |
| done | d | 标记完成 | todo d 12 |
| delete | rm | 删除任务 | todo rm 12 |
| edit | e | 修改内容/优先级 | todo e 12 --new "新内容" |
| stats | s | 查看完成统计 | todo s --week |
3.2 数据结构的核心字段：状态机越简单越不容易错
每一条任务在JSON里是一个对象，长这样：
{ "id": 12, "content": "完成项目复盘文档", "priority": "high", "created_at": "2025-04-01 09:30:00", "done": false, "completed_at": null }字段设计上我刻意保持克制。id是自增整数，用于定位任务；content是任务内容；priority只取low、normal、high三档；created_at和done是必填项；completed_at只有任务被标记完成时才写入，方便后续统计耗时。没有label、没有project、没有assignee，个人工具用不到这些。
done用布尔值而不是"状态枚举"，是因为任务状态本质是线性流转的：未做 -> 已完成。如果你设计了"待办/进行中/已完成/已取消"四态，那每个状态的迁移都是逻辑分支，排查起来反而费劲。想让状态更丰富的同学，可以在content里写[进行中] 改完登录页，让文本自己记录进度，状态字段保持最朴素的两态即可。
3.3 list命令的显示策略：默认只看未完成，别让历史刷屏
list是使用频率最高的命令，它的显示策略直接决定了工具好不好用。我的规则是：默认只列未完成且按日期过滤的任务；--all才展示所有历史。
每条任务的展示格式为：
[3] 高 写季度OKR (04-01 创建) [7] 中 预约牙医 (04-02 创建)方括号里是任务ID，中间是优先级，然后是内容和创建日期。ID在列表里靠左显示，是为了一眼定位，配合done命令快速操作。如果你有任务忘记录日期，我还会在内容后面加一个(:日期未设置)的提示，提醒你补时间，让这个工具不仅仅是记录，也在倒逼你用"时间锚点"来管理任务。
3.4 done和undo：状态流转的完整闭环
标记完成是todo done <id>，核心逻辑就是找到那条任务，把done改成true，写入completed_at。实现不复杂，但我在实际使用中很快发现一个需求：误标完成怎么办？于是加了undo命令：todo undo 12，把done改回false、清空completed_at。这个命令让状态流转形成了闭环——可以正向推进，也可以回滚，数据不会因为一次误操作卡在错误的状态里。
3.5 任务序号与删除间的处理策略
任务ID是自增整数，删除一个任务后，后面新加的ID继续递增，不会回头补号。这个小建模决定在初期引起过争议，有朋友建议删除后重新排序ID，让显示更连续。但我的经验是：ID一旦被引用，就不应该变化。因为同事之间互相分享"帮忙看下第12条任务"时，如果重新排序，别人的引用就失效了。ID只是定位用的临时标识，不连续并不影响使用，反而避免了很多混乱。
4. 让终端里的待办真正好用的显示与交互优化
4.1 颜色与状态：用最少的信息跳跃区分关键内容
命令行输出的颜色设计很容易走极端。有人每行都上色，结果整屏大红大绿，视觉噪音比价值还大。我的原则是"颜色只承载两类信号"：高优先级任务用红色系标记，已完成任务在--all模式下用灰色/弱化色呈现。优先级中的normal默认用普通默认色，不出现在屏幕上造成额外负担。这样一眼扫过去，哪些事最紧急、哪些事已经结束，立刻就能分辨出来，不至于在五颜六色里重新做一次信息筛选。
在实现上，我写了一个极简的色彩包装函数，使用ANSI转义码，不依赖任何第三方库：
def c(text, code): return f"\033[{code}m{text}\033[0m" red = lambda s: c(s, "31;1") gray = lambda s: c(s, "90")判断当前输出是否为终端，其实也值得留个心眼——当你把输出重定向到文件时，ANSI颜色码会混进文本。为此我加了一个检测：如果不是TTY，就关闭所有颜色转义，直接输出纯文本。这个细节不注意的话，你在管道里一重定向，日志文件里就全是什么\033[31;1m之类的乱码。
4.2 模糊查找与ID定位：两种方式应对不同场景
ID定位适合任务多、能确定序号时快速操作，但日常中最常用到的反而是模糊搜索。我把搜索能力放进了list命令里：todo ls 关键词，匹配成功的结果会在界面里高亮显示，可以多次叠加关键词做精确筛选。这比单独做一个search子命令更顺手，因为它没有退出当前的"列任务"上下文。
这里有个搜索性能的疑问：几千条任务遍历一遍会不会慢？完全不会。单文件JSON在几千条量级下，全文匹配的时间在毫秒级，压根不需要索引。那些数据上了几万条才开始考虑的搜索优化，在这个场景下属于过早优化。
4.3 Shell集成：别名、Tab补全、自动提示
命令行工具要真正融入日常，光有软件本身还不够，外壳配合至关重要。我把关键操作绑定了别名，比如t、ta、td、tl，让手指工作量大减。这一步的体验提升比任何内部功能优化都明显：
# ~/.zshrc 或 ~/.bashrc alias t='todo' alias ta='todo add' alias tl='todo ls' alias td='todo done'Tab补全则解决了"不记得命令长什么样"的问题。给工具配了简单的补全脚本后，在zsh里敲todo d然后按Tab，会直接列出done、delete等候选，在待办条目很多时，盯着屏幕想想"它到底叫什么名"这个心智负担就被移除了。
此外我还在Shell的提示符（Promote）里加了未完成任务数。比如在~/.zshrc里读取待办文件的未完成数，显示为[TODO:5]。这个设计极其管用——你不需要主动打开列表，任务数量就一直在提示符里盯着你。当数字是0时候，那种"今天可以收了"的感觉，是很有成就感的。
4.4 多终端协同：让待办数据跟到每一台设备上
我有一台办公主机、一台家庭本和一个云服务器，三台机器都装在终端里调同一个待办列表。做法是把存储目录放到一个同步盘上（比如Dropbox或坚果云的本地同步目录），再让各个机器上的工具都指向同一个文件路径。因为JSON文件本身是纯文本，同步进程对它的"低冲突写入"非常友好。虽然技术上极端情况下两个终端同时写会有一次冲突，但个人场景下这个概率极低。这块如果不想折腾，也可以退回"主用一台机器"——关键是，命令行方案天然让"待办数据到底在哪"这件事完全由你掌控，这是云服务给不了的确定性。
5. 统计、提醒与系统能力接入：让工具不再只是一份清单
5.1 完成率与耗时分析：用统计回归数据价值
当任务被记录了日期和完成时间，统计就有了原料。我给工具加了stats子命令，支持查看当日完成数、本周累计完成数、全量完成率，还能算出平均每项任务从创建到完成的时间。这些指标一个月的积累后，看自己的"真实产出"比任何打卡软件都更直观。
统计的实现不复杂，遍历一次JSON文件即可：
def week_summary(tasks): now = datetime.now() week_start = now - timedelta(days=now.weekday()) done_in_week = [t for t in tasks if t["done"] and parse(t["completed_at"]) >= week_start] return { "week_done": len(done_in_week), "total_done": len([t for t in tasks if t["done"]]), "avg_hours": average_duration(tasks), }这种设计带来的隐性收益是：我开始对自己的"时间感"有更实际的锚点。原来总觉得一天做了很多事，可统计上只有两条任务完成；有些天只标了两三条任务，但都是硬骨头。数字帮你校准主观感受，这是待办工具最被低估的价值。
5.2 终端通知：任务到期提醒的正确姿势
命令行工具最缺的就是"主动提醒"能力——用户不开终端，它就沉默。我的解决方案是配合操作系统的通知服务，做了一层轻量提醒。在Linux上用notify-send弹出桌面通知，macOS用osascript -e 'display notification ...'，Windows则走PowerShell的[System.Windows.Forms.NotifyMessage]。工具本身只管"当前时间有没有快到截止时间的任务"，提醒的具体方式交给系统去适配。
用法上，我在安装了这层提醒能力后，配置了一个crontab任务每30分钟检查一次：
*/30 * * * * /usr/bin/python3 ~/bin/todo.py remind --due-in 60这样终端不常开的人也能收到通知。对于那些全程在终端里的朋友，甚至不需要系统通知——直接在todo ls里高亮"今天到期的任务"就足够，配合Shell欢迎语里的待办数字，实现每日自动播报。
5.3 自然语言日期解析：妥协和取舍
我之前说砍掉了自然语言解析，但在提醒功能做到一半时，还是忍不住做了一个极简版本。支持了今天、明天、下周X和MM-DD四种表达式，其余一律走完整日期输入。这个设计避开了引入dateutil之类的重型依赖，也能覆盖八成使用场景：
todo a "下班取快递" --due 今天 todo a "周会材料" --due 明天 todo a "纪念日准备" --due 07-01解析逻辑用正则实现，十来行代码，至今没出过毛病。如果你判断自己的工具用户对自然语言的诉求很强，再去上大而全的解析器，否则大部分Web应用里的"明天下午3点"在命令行里完全可以被2025-04-02 15:00替代，因为敲下的成本并没有高到不可接受。
5.4 一个Bash最小版本：当你连Python都没有时
有时候你在别人的服务器上，临时要记一条待办，又不想搬一套Python脚本过去。这种情况下，一个3行Bash的函数也能顶一阵子：
todo() { local f="$HOME/.todo.list" [ ! -f "$f" ] && touch "$f" case "$1" in add) echo "$2 $3" >> "$f" ;; ls) cat -n "$f" ;; done) sed -i '' "$2d" "$f" 2>/dev/null || sed -i "$2d" "$f" ;; esac }这段函数极其简陋，连优先级和日期都不支持，但它能在完全依赖Bash的机器上完成"记、看、删"三连操作。更重要的是它再次印证了我的核心观点：待办工具的实质不是技术架构多恢弘，而是"能以零负担的速度进入你的工作流"。真正复杂的版本，都是在满足这个前提之后，再慢慢长出来的。
6. 实战避坑：从"能用"到"经得起每天用"的几道坎
6.1 Windows与Linux/macOS的编码差异
如果只在macOS或Linux上跑，编码问题几乎不用操心。但一旦要在Windows的cmd或PowerShell里显示中文，坑就来了。第一次在Windows上跑todo ls时，列表里的中文全部变成了乱码，排查一圈发现是编码问题：Python默认按UTF-8写入JSON文件，而Windows控制台的默认编码是GBK。
解决方案分两层：输出时统一用sys.stdout.reconfigure(encoding="utf-8")强制标准输出按UTF-8处理；同时提醒用户在cmd里先执行chcp 65001切换到UTF-8代码页。如果用的是Windows Terminal而不是老旧的conhost，这个问题基本绝迹。现在跨平台测试时，我第一关注点就放在中文输出上，这一道坎我一共踩过三次，教训是：永远不要假设控制台编码和你预期一致。
6.2 多人同时操作同一份数据的缓存问题
虽然工具定位是"个人待办"，但我确实遇到过一次真·并发场景：手机端通过SSH连到服务器，同时家里的电脑也在跑着同一个工具。两个进程各自读取了JSON文件的一份缓存，然后分别写入，结果后写的人把先写的人那条记录覆盖了。这个问题严格来说不是命令行工具该操心的，但既然发生了，我把写入逻辑调整成了"写前重新读取最新数据，再把改动合并进最新数据"的方式，从根源上缓解了覆盖风险。
对于99%的个人用户来说，这个问题不需要上线时解决，但设计数据结构时保留updated_at字段会在将来省很多事——冲突发生时，至少能判断谁是"更新"的版本。
6.3 自动备份：放在Dropbox里不等于有备份
我把待办文件放在同步盘里之后，曾一度觉得"同步就是备份"，直到一次校验中误操作把整个文件清空，同步盘立刻把空文件同步到了所有设备。那次教训让我意识到：同步是同步，备份是备份，不要把两者混淆。
现在我给工具加了一个策略：每次启动时自动备份昨天的文件到backup/tasks-日期.json，只保留最近30份。这样即使文件被清空或错误写入，也能找到当天较早的备份。这个设计用了大概十行代码，但它是整个工具里最值得的十行之一。
6.4 从玩具到工具的分水岭：放弃频繁重构
早期的我特别喜欢重构——今天改存储结构，明天换命令格式，结果数据迁来迁去，命令换来换去，工具停摆了好几周，最后还是回退到最初的用法。后来我给自己定了一条规矩：存储结构和命令名是"稳定接口"，一旦稳定下来，至少半年内不动。功能可以加，入口不能轻易改。
真正的分水岭不是我加了多炫酷的提醒，而是我终于意识到：工具的需求是使用者的习惯沉淀出来的，不是凭空设计出来的。我砍掉了很多潜在功能的冲动，把时间花在让add快一点、让ls更清楚一点、让done更不容易手抖上。投入的这些琐碎改进，最终让这个命令行待办事项应用从一个技术玩具，长成了我每天都离不开的基础设施。
7. 末尾：一个值得一试的扩展方向
最后分享一个我最近在做的小扩展：把待办和Git提交记录联动。每当我标记一个任务完成时，工具会生成一条包含任务ID和内容的commit消息模板，配合我惯用的commit规范自动落地。这样一来，项目管理里的"任务完成"和代码仓库里的"变更记录"就自然挂上了钩。
如果你也想从零构建一个命令行待办事项应用，我的建议是把第一版控制在一百行代码以内：支持add、ls、done、delete四个命令，加上JSON存储，就够了。后续的颜色、提醒、统计、同步，都是在你已经把"每次打开终端会下意识敲一下t"这个习惯养成了之后，再慢慢加进去的。工具做到最后，真正的壁垒不是技术，而是你愿意每天维护它的那一点点惯性。
