有一次我完成了一个计划，改了好几个文件，验证了结果，然后就去休息了。过了两天，我回头想继续做这个计划的下一个版本，或者想基于这个计划的结果做点别的事情。结果我发现，我不知道该从哪里开始了。
不是我不记得做了什么。IMPLEMENTATION_LOG.md 里有记录，TASKS.md 里任务状态也更新了。但问题是：这些记录是给人看的，不是给执行系统看的。
当我让另一个 Agent 继续执行时，它看到的只是一个标记着 done 的计划，和一堆更新过的文件。它不知道哪些变化是这次执行产生的，哪些变化是之前就有的，哪些变化是执行过程中临时产生的但最后没保留。
这就是执行 marker 要解决的问题。
没有 marker 时会发生什么
想象一个常见的场景。
你有一个计划，执行了一部分，然后去做了别的事情。过了几天，你回来想继续。或者你让另一个 Agent 接手。
如果没有执行 marker，执行系统只能看到：
- 计划的状态是
in_progress还是done - 文件的最近修改时间
- 日志文件里的内容
这些信息不够。
计划状态只能告诉你"做完了没有"，不能告诉你"做完到哪里了"。
文件修改时间只能告诉你"哪些文件变了"，不能告诉你"为什么变、变成什么样、是不是最终结果"。
日志文件里可能有你需要的所有信息，但它是一段叙述，不是结构化数据。执行系统可以读，但读完后依然不知道该从哪里继续。
我第一次遇到这个问题时，我的做法是：在继续执行前，先让 Agent review 一下前面的所有记录，然后基于理解继续。
这个方法在人类协作中可能可行，但在多 Agent 自动执行中不行。因为：
第一，review 整个历史很慢，而且容易遗漏关键细节。
第二，不同 Agent 对"理解"的把握不一样，有的认为看过了就行，有的会深入检查，有的会误判状态。
第三，如果历史很长，review 本身就会变成一个模糊任务，回到我们之前说的"当前任务不能写成 review"的问题。
所以需要一种更结构化的方式，来标记"这次执行到哪里结束了，下次从哪里开始"。
marker 不是日志，而是边界
一开始我以为，执行 marker 就是写一段执行日志。比如：
{
"timestamp": "2026-05-31T10:00:00",
"action": "executed step 1-3",
"result": "success"
}
后来发现这样不够。因为日志描述的是"我做了什么"，而 marker 描述的是"执行边界在哪里"。
日志是给人看的记录，marker 是给执行系统看的坐标。
一个合格的执行 marker 应该包含这些信息：
- 计划 ID：这次执行的是哪个计划
- 执行时间：什么时候执行的
- 执行边界：从哪个状态到哪个状态
- 产出物：这次执行产生了哪些新文件、改了哪些文件
- 下一个起点：如果要继续，应该从哪里开始
用 JSON 格式表达大概是：
{
"plan_id": "jp091-t100-dd-apple64",
"executed_at": "2026-05-31T10:00:00+08:00",
"executor": "agent-ceo-router",
"workdir": "/Users/apple64/Documents/jianfei-blog/articles/qclaw-backlog/apple64",
"executed_steps": [1, 2, 3],
"outputs": [
"20260531-计划系统当前任务不能是review.md"
],
"next_start": "step 4: write execution marker article"
}
这个文件和日志的区别是：它是结构化的，可以被执行系统直接解析和使用。
下次执行时，系统只需要读这个 marker，就知道上一次做到了哪里，这次应该从哪里开始，不需要重新 review 整个历史。
为什么状态文件不够
你可能会问：计划里不是已经有 STATE.md 了吗？为什么还要单独的 marker？
这是一个很好的问题。答案是：STATE.md 记录的是计划的长期状态，marker 记录的是单次执行的边界。
举个例子。
一个计划可能有这些长期状态：
- 当前阶段：implementation
- 已完成任务：1, 2, 3
- 未完成任务：4, 5
- 已知问题：配置路径在另一台机器上不同
这些状态是跨多次执行的。它们告诉任何打开这个计划的人，这个计划整体上处于什么状态。
但 marker 记录的是：在今天这次执行中，从打开计划到关闭计划这段时间里，具体发生了什么。
这两次信息粒度不同，用途不同。
STATE.md 回答的是："这个计划整体上做到哪里了？"
marker 回答的是："上一次执行具体产出什么？这次执行该从哪里接？"
如果只有 STATE.md，没有 marker，那么当执行历史变复杂时（比如一个计划被多次暂停、恢复、修改），你就很难还原每一次执行的具体边界。
如果只有 marker，没有 STATE.md，那么你就失去了计划的整体视图，每次都要从 marker 链里推断计划状态，效率很低。
它们是两个不同层次的信息，缺一不可。
多 Agent 协作中的关键作用
执行 marker 在多 Agent 协作中尤其重要。
假设这样一个场景：
你在机器 A 上开始执行一个计划，执行到一半，你去睡觉了。第二天，你在机器 B 上想继续这个计划。
如果没有 marker，机器 B 上的 Agent 只能看到计划文件，但不知道你昨天在机器 A 上具体做了什么、做到哪里了、有没有产生中间产物、中间产物保存在哪里。
你可能会说：不是有 git 吗？不是有日志吗？
git 能告诉你文件变了，但不能告诉你"为什么要变"、"是不是最终结果"、"有没有临时文件需要清理"。
日志能告诉你你做了什么，但它是叙述性的，不同 Agent 对日志的理解可能有偏差。
marker 做的是：把一个执行过程的关键信息，用结构化的方式固定下来，让任意一个 Agent，在任意一台机器上，都能准确地接手。
这不是为了应付当前这次执行，而是为了让整个协作系统能够长期稳定运行。
当我们有三个、五个、十个 Agent 在不同时候、不同机器上协作时，marker 就是它们之间的"握手协议"。没有这个协议，协作就会变成各自为战，最后状态混乱。
一个容易忽略的点：marker 本身也要版本化
写过几次 marker 后，我发现了一个问题：marker 本身也需要被追踪。
如果每次执行都覆盖同一个 marker 文件，那么你就失去了执行历史。你只知道上一次执行到哪里了，但不知道上上次、上上上次。
如果每次执行都创建一个新的 marker 文件，那么 marker 文件就会越来越多，最后和日志文件一样难以管理。
我目前的做法是：marker 作为一个 JSON 文件，内部维护一个执行历史数组。每次执行追加一条记录，而不是覆盖。
{
"plan_id": "jp091-t100-dd-apple64",
"execution_history": [
{
"executed_at": "2026-05-30T10:00:00+08:00",
"executor": "agent-ceo-router",
"executed_steps": [1],
"outputs": ["draft1.md"],
"next_start": "step 2"
},
{
"executed_at": "2026-05-31T10:00:00+08:00",
"executor": "agent-ceo-router",
"executed_steps": [2, 3],
"outputs": ["draft2.md", "draft3.md"],
"next_start": "step 4"
}
]
}
这样，marker 文件既是下次执行的入口，也是执行历史的可追溯记录。
下次我会怎么做
下次完成一个计划执行后，我会按照这个顺序做四件事。
第一，更新任务状态。 把 TASKS.md 里完成的任务标记为 done，未完成的更新状态。
第二，记录验证结果。 在 IMPLEMENTATION_LOG.md 里写清楚这次执行验证了什么，结果是什么，有没有遗留问题。
第三，写执行 marker。 用结构化格式记录这次执行的边界：什么时候执行的、执行了哪些步骤、产出了什么、下次从哪里开始。
第四，把 marker 路径写入计划的主文件。 在计划的摘要部分加一行：最新执行记录：EXECUTION_MARKER.json。这样任何人打开计划，都知道去哪里找执行边界。
这四件事看起来有点繁琐。但做过几次没有 marker 的继续执行后，你就会发现，花几分钟写一个 marker，比后面花几个小时还原执行历史要划算得多。
执行 marker 的本质，不是多写一个文件，而是把执行过程的关键信息，用一种可以让机器无歧义理解的方式保存下来。
这是多 Agent 协作能够长期稳定运行的基础之一。没有它，协作就会一直停留在"靠人记忆"的阶段，无法真正自动化。