mdtask 源码精读:2576 行 2 个依赖,spec 不漂移

导读

一个任务管理工具，把「完成任务」的命令删了。mdtask 全部实现只有 2576 行 TypeScript、2 个运行时依赖：没有数据库，没有服务器，spec 和任务住进同一个 Markdown 文件，关任务的编辑和代码进同一个 commit。

The toggle command is unnecessary — agents and users edit markdown files directly.

这个痛点估计你也有。spec 写在某个 docs 目录里，任务躺在 Jira 里，代码在 git 里。三个系统，靠人肉同步。spec 永远是上个版本的样子，任务状态永远慢半拍。

人写代码的时候，这事只是烦。agent 写代码的时候，这事是事故：agent 把过期的 spec 当真相，照着盖楼，盖完才发现地基早改了。

mdtask 的解法一句话：把 spec 和任务放进同一个 Markdown 文件，跟代码住同一个 repo，关任务的那次编辑和代码改动进同一个 commit。文件是唯一的真相源，git 是唯一的同步机制。

具体长这样。一个 spec 文件，上半部分是散文，写的是「系统现在是什么样」（手册）；下半部分一个 # Tasks 标题，下面是 checkbox 任务（待办加历史）：

任务行后面可以挂三种元数据：#tag、!high（优先级）、@key:value（属性）。所有属性里只有一个有内置行为：@blocked_by:KTL-001。被阻塞的任务默认从 list 里隐藏，阻塞解除了才冒出来。其余的 @status:doing 之类，工具一概不管语义，纯项目内部约定。

docs/mdtask.md 里有段话，我认为是整个项目的「独立宣言」：

这句话解释了后面所有的设计决策。因为 CLI 不拥有数据，所以不需要 done 命令；因为行就是记录，所以解析器不需要 Markdown AST，逐行扫正则就够；因为文件是真相，所以所有写操作都按「直接编辑文本」的纪律来做。

读解析器之前，我以为元数据是从左往右切的：碰到第一个 # 或 ! 就开始算。mdtask 反着来，从右往左扫（task.ts:66-76）：

为什么必须从右边扫？两个例子就懂了：

元数据的定义是「行尾连续的元数据 token 串」。从右往左，碰到第一个不像元数据的词就停。从左往右扫没法区分上面两种情况，从右往左天然正确。配套还有个细节：tag 正则要求字母开头（/^#[A-Za-z][\w-]*$/），所以纯数字的 #123 永远不可能被当成 tag。双保险。

另外留了个逃生门：万一标题真的以元数据词结尾，用两个 tab（\t\t）显式分隔标题和元数据，解析器优先认这个。

第二个精巧处是 fence mask。spec 文件里经常要放示例，比如文档里演示任务格式长什么样，这些示例 checkbox 写在代码块里。不处理的话，mdtask list 会把文档示例当真任务列出来，mdtask ids 甚至会给示例发 ID。

mdtask 的解法是手搓了一个 CommonMark 围栏状态机（task.ts:99-134）：先把整个文件扫一遍，给每一行打上「是否在代码块内」的标记，之后所有命令扫描时跳过这些行。

这个状态机认真得有点可爱：开围栏要 3 个以上反引号或波浪号、缩进 0 到 3 个空格（tab 不算数）；反引号开的围栏，info string 里不能再含反引号；闭围栏必须字符相同、长度不小于开围栏、后面只能跟空白；没闭合的围栏一直延伸到文件结尾。全是 CommonMark 规范里的边角规则，一条没落。

这个功夫没白花。你没法要求用户「别在 spec 里写示例」，只能让工具聪明一点。

同类纪律还有一处：任务 body（header 下面缩进的行）的边界，全项目只有一个函数说了算：findTaskBlockRange。view 用它决定打印多少，move 用它决定剪切多少，archive 用它决定搬走多少。「任务块是什么」这个定义，不可能在三处各自漂移。

任务 ID 是 PREFIX-NNN 格式，比如 CLI-087。有意思的是这条规则：NNN 这个数字跨前缀全局唯一。CLI-087 和 PRJ-087 不该同时存在，validate 会对撞号发警告，纯数字查找遇到撞号直接报歧义错误。

代价是发号麻烦一点（新号码 = 全库最大号码 + 1），收益是 mdtask view 87 不用敲前缀。对人来说省几个按键，对 agent 来说是一个稳定无歧义的寻址方式。对话里引用任务，一个数字就够。

发号命令 mdtask ids 的实现是两阶段的：第一遍扫所有文件、确定每个文件用什么前缀，任何一个文件定不下来，直接报错退出，一个字符都不写；第二遍才发号落盘。前缀的推断链有四级：文件里已有任务的多数派前缀 → 种子行（- [ ] CLI- 标题，有前缀没号码）→ --prefix 参数 → TTY 下开口问你。非 TTY 环境（比如 agent 在跑）问不了人，就报错并附上三种解法。

写操作是这类工具最容易翻车的地方。你在终端跑 mdtask move，编辑器里同时还开着这个文件，怎么办？

mdtask 的答案是三件套。第一，先写目标、后删源（cli.ts:424）：

目标文件写成功了才动源文件。顺序反过来，目标写失败那一刻数据就丢了。archive 同理，归档文件先落盘。

第二，同文件多个任务一起归档时，按行号从大到小倒序删（cli.ts:603）：

从文件尾部往前删，前面的行号才不会在删除过程中失效。文本处理的老把戏，但忘了它的工具我见过不止一个。

第三，乐观并发检查。写之前重新读文件，确认任务还在它该在的那一行：

发现文件被动过就直接退出，不猜、不强写。三件套本质上是在承认一件事：CLI 不拥有数据，用户和 agent 随时可能在改文件，工具得对自己的假设保持怀疑。

到这里还只是个「好用的 CLI」的故事。mdtask 真正值钱的是下面这层分工。README 写得很直白，mdtask 是三层：

第二层是精髓。方法论没有编译进代码，而是写成了 agent 能直接读的 Markdown。比如 mdtask-do 这个 skill，定义了一个任务从挑到提交的标准动作：挑任务 → 写计划 → 把计划发给另一个模型评审 → 实现加行为验证 → 代码评审 → 更新 spec → commit。遇到只有人能拍板的问题，不许猜：给任务打上 #user-required 标签、在任务体里写清楚悬而未决的问题，泊车，下一个。

关任务的动作也定义在 skill 里而不是 CLI 里：打勾、任务体里补一段 **Implemented:**、更新上半部分的手册，三件事和代码改动进同一个 commit。现在回看删 done 命令的那个决定，逻辑圆上了：状态迁移是 API 思维，编辑是文件思维，mdtask 选了文件。

这些 SKILL.md 不锁 Claude Code，任何能加载 SKILL.md 的 agent harness 都能用。mdtask install-skills 把它们软链进 agent 的技能目录，实现里还带版本缓存和「只碰自己创建的链接」的洁癖，不会覆盖你自己建的同名目录。

mdtask 项目本身就是用 mdtask 开发的，证据链完整：

我最喜欢的一个细节是一条挪任务的 commit：Move CLI-065 to PRJ-081: task-journal boundary is an sdd convention, not CLI。意思是：有人（大概率是 agent）把「spec 文件里 # Tasks 这个边界」当成了 CLI 的约束来实现，review 时发现划错层了，这个边界是 sdd 工作流的约定，CLI 根本不该知道。于是挪任务、改归属，整个过程留在 git 历史里。分层不是 PPT 上的图，是犯了错要挪回去的纪律。

最后说个少见的。README 里有一节叫 「What mdtask doesn’t do」，自己拆自己的台：

把自我设限写在明处，反而让人信它做得到承诺的部分。

如果你只是想要个本地 TODO 工具，mdtask 对你是过度设计，编辑器插件就够了；如果你在让 agent 长时间跑任务、被「agent 拿过期 spec 当真相」坑过，这套设计值得抄。不一定要用这个工具，但这三个判断标准可以直接拿去衡量任何同类工具：

59 个 star 的项目，把这些事想得比一堆几千 star 的同类都清楚。源码不长，一晚上能读完，推荐你也读读。

你现在的项目里，spec 和任务是怎么管的？评论区聊聊。觉得有收获的话点个关注，下篇继续拆有意思的源码。

引用来源