模式矩阵 /模式白皮书/M3

M3 · Progress Tracking · 进度追踪

它解决什么问题

LLM 没有真正的工作记忆，它的"记忆"全活在 context window 里，而 context window 有 U 形 attention 特性——中间段会被淹没。一个长任务跑两三个小时，中间出现一段 debug 或深挖细节的"打野"，原计划里的剩余任务很容易被注意力遗忘。一个常见的故障是：agent 把前三个文件拆好后陷进一个小 bug 调了二十多轮，调完直接跑去写测试，忘了原计划里还有第四个文件没建。

进度追踪用工程手段兜住这件事：强制把 todos 显式写出来，反复提醒 agent 去看自己的清单。关键在于它不是给人看的，是给 agent 自己看的——agent 看自己写的结构化 todos，比看自己三十轮前夹杂着噪声的对话历史靠谱得多。

为什么坐标是「记忆 × 链式」

• 纵轴 · 记忆：它给 agent 一份"工作日志",跨 step 保留任务上下文，是记忆最简形式（session memory）——记着"我刚做了什么、现在在做什么、接下来做什么"。
• 横轴 · 链式：进度按步序 append-only 写入，每完成一个动作就更新 status，每开始一个动作就标 in_progress。状态沿任务步骤顺序流动，是典型的链式传递。

核心机制

1. 精简的状态机：核心 schema 极简——任务描述、状态枚举（pending / in_progress / completed）、进行时形式。状态机的硬约束是任何时刻只有一个 in_progress，单线程 agent 一次只能聚焦一件事。
2. 状态外部化到对话流：每一轮把进度写出来，让 agent 自己和用户都能看见。这是对抗 LLM 工作记忆缺陷的核心动作——把任务从工作记忆 offload 到外部存储。
3. 全部完成时自动清空：所有 todos 完成后自动清空清单，避免 agent 反复看到"已全部做完"的旧清单干扰新任务判断。这反直觉但必要,因为 LLM 有"看见即注意"的特性。
4. 框架层强制 nudge：单靠 prompt 教 agent 写 todos 不够，框架层必须有机制。两种工业实现:一是 verification nudge（三项以上的清单关闭时若没有验证步骤，自动追加提醒），二是 context-loss detection（做复杂任务却没写 todos 时自动注入提醒，反复不写则递进式升级压力）。
5. 按 agent / session 隔离：每个 agent 或子 agent 维护独立的 todos 池，避免子 agent 的细节 todos 污染主 agent 的高层清单。

适合的生产场景

• 多步长任务：三步以上、跨多轮、容易在中途打野后失忆的任务。代码重构、多文件改造、复杂调试。
• 可恢复的长流程：任务可能中途崩溃需要 resume 的场景。进度持久化后，第二次会话读 progress、跳过已完成、从中断步恢复，不重做。
• 多周持续推进的任务：跨数周对同一目标推进的场景（如投资研究对一只股票的判断），需要双层 todo——高层研究计划跨周保持，会话内具体动作做完合并回高层。

容易出错的地方

• 单次简单任务强行用：三步以内的活、纯对话、单次 Q&A 不需要 todo，强行用是过度工程。
• 允许多个 in_progress：违反状态机硬约束。工程师抱怨"想并行做"通常是伪需求——要么任务该拆给多个 agent，要么该排成 chain 顺序做。
• 缺 active form 字段：UI 显示"正在做什么"时机械地给动词加 -ing，出现"Fix cache bug...ing"这种拼接。用进行时形式字段从写 todo 时就想清楚动词形态。
• main agent 与 sub-agent 共享一个池：main agent 看自己清单时被子 agent 的五到十条细节 todos 淹没，注意力被无关粒度争夺。子 agent 必须独立 todos。
• 没有框架层 nudge：agent 做五步任务却完全没写 todos，框架不提醒，失忆照旧发生。nudge 的递进式压力（建议→要求→强制）三档边界要清楚。

关键指标

• 失忆率（健康区越低越好）：长任务里 agent 遗漏原计划步骤的比例。这是判断进度追踪做对没的首要指标，再漂亮的 todos UI 也救不回高失忆率。
• 验证步骤覆盖率（健康区接近 100%）：三项以上任务在关闭前包含验证步骤的比例。verification nudge 直接拉这个指标。
• resume 成功率（健康区 ≥ 95%）：崩溃后从进度恢复且不重做已完成步骤的比例。
• 单 in_progress 合规率（健康区 100%）：任意时刻只有一个 in_progress 的占比，违反即状态机有 bug。

最小骨架

TodoItem: content（动词原形）/ active_form（进行时）/ status（pending|in_progress|completed）
TodoList（按 owner_id 隔离）：
    start(id)    → 标 in_progress，自动把其他 in_progress 暂停回 pending（一次只一个）
    complete(id) → 标 completed
    all_done()   → 全完成则自动清空
ProgressTracker（框架层强制）：
    context_loss_detected → 复杂任务但没写 todos → 注入 reminder
    nudge 递进：建议 → 要求 → 强制（halting）
    verification_nudge   → 3+ 清单关闭且无验证步骤 → 追加提醒
持久化：增量 append-only + 周期 snapshot + session 兜底

工程落地四个要点：一次只一个 in_progress 必须强制；复杂度估算用便宜模型而非数动词；nudge 递进式压力三档边界清楚；TodoList 按 agent_id 隔离不共享。

企业落地一例

某买方研究机构的投资研究 agent，要跟研究员跨四到十二周持续推进对一只股票的判断。普通单层 todo 不够，这里需要"会话统一状态平面"。SessionState 是机械参数态——严格键值结构，记着每只股票的研究计划、当前投资逻辑、关键风险、反向观点，保证连续多步分析时每一步的入参都有唯一可审计来源（比如"用的是哪天的财报数据"）。SessionNarrative 是叙事对齐态——自然语言摘要，记着"我们整体在做什么、这次具体推进了哪个维度",解决产出写回哪里供后续会话消费的问题。配套设计包括:双层 todo（研究计划跨周保持加会话任务做完合并）、状态存为 git 友好的 markdown（研究员能 git diff 看每周变化）、关键风险和反向观点永不清空（每次会话作为 system prompt 注入）、四状态机（多一个 needs_review 等基金经理审过才算 completed，满足监管"所有判断有人审"要求）、active form 带数据时间戳（逼 agent 检查"我用的数据够新吗"）、周末自动周报合并。

与其他模式的关系

• 分层保留（M1）：进度追踪是分层里最 hot 的那一层。Todo list 是 agent 的寄存器——三到七个 item、频繁更新、每次推理都加载，是会话层里专门管"做到哪了"的部分。
• 失败日记（M4）：孪生关系，同在循环列。进度追踪管"做对的路径",失败日记管"踩过的坑"。一个记成功步骤，一个记失败案例。
• Plan-and-Execute（推理模块）：进度追踪是 Plan 的运行时孪生。规划一次性产出"想做什么"的静态清单，进度追踪循环维护"做到哪了"的动态状态。两件事，不要混。
• Hooks Pipeline（治理模块）：框架层的 nudge 和持久化挂点天然契合 hook 机制，可用 PreToolUse / PostToolUse hook 实现。

一句话记住它

进度追踪不是给用户的进度可视化，是给 agent 的外置工作记忆——它是 agent 时代工作记忆缺陷的工程化补丁，没有它，越聪明的 agent 在长任务里越危险。

本页属于 ADPS 33 模式白皮书。返回 模式矩阵与白皮书目录， 或查看配套 可运行代码目录。