为编程代理做一个不假装精确的 ETA 显示

上一篇文章讨论了等待与切换任务的时间安排。这里做一个简单的本地状态记录，显示下一次可能需要人回应的大致时间范围。

示例不会自动预测任务耗时。时间范围由你或代理在有依据时主动填入，显示程序只负责呈现，并提醒估算何时已过期。

1. 独立运行示例

需要 macOS 或 Linux 终端中的 Python 3。用 python3 --version 检查。下载并检查 agent-eta.py后，放进临时工作目录，再在该目录运行命令。不需要额外安装软件包，也不修改 Claude Code 的设置。

每个任务使用独立的本地 JSON 文件，多个代理不要共用一个写入目标。上级目录须事先存在。

python3 agent-eta.py --file ./eta-demo.json write --state working --phase verification --min 5 --max 12
python3 agent-eta.py --file ./eta-demo.json show

初始输出大致如下：

verification | WORKING | rough next-attention window 5-12m | declared, not calibrated

五到十二分钟只是虚构的演示输入，不是实测结果，也不是完成承诺。它指的是下一次可能需要你回应的时间范围，而不是整个任务何时完成。

2. 不知道时就明确说明

没有估算依据时，只报告状态：

python3 agent-eta.py --file ./eta-demo.json write --state working --phase research

显示为 next attention window unknown，不会把缺失估算变成零。存在范围时，显示会扣除经过的时间。超过上限后，提示 declared window expired; refresh needed，而不是一直停在零。

3. 报告真实的输入需求

python3 agent-eta.py --file ./eta-demo.json write --state needs-input --phase implementation
python3 agent-eta.py --file ./eta-demo.json write --state waiting --phase external
python3 agent-eta.py --file ./eta-demo.json write --state ready --phase review

应在相应状态实际发生时分别执行，不要机械地依次运行。INPUT NEEDED 优先于时间范围。READY FOR REVIEW 不表示测试已经通过。未提供范围的外部等待仍然是未知时间。

脚本看不到真实的批准对话框，也不能自行判断测试结果。记录是否可信，取决于写入者有没有及时、如实更新。

4. 明确加入更新步骤

第一次试用时，先在阶段变化后手动更新。以后也可以要求代理使用已检查的脚本和专用文件，在提问前、工作结束后更新状态；没有依据，就不填写时间范围。

这是工作流程约定，不是已经验证的 Claude Code 自动集成。接入状态行或生命周期钩子，仍是后续工作。show 只打印快照，不会建立持续刷新的仪表盘。

观察这份信息是否有助于安排空档。数字不能保证你可以放心离开，因为代理也可能提前遇到问题。

5. 测试边界并清理

示例使用人工时钟和合成输入进行测试，覆盖文件缺失或损坏、时间范围未知或过期、需要输入、无效数值和时钟变化。超过 24 小时的记录标为过时，但没有测量它对真实任务的预测准确率。

文件只记录固定状态、阶段名称、更新时间和声明的时间范围；不发网络请求，不采集提示词，也不保存历史。每次更新覆盖同一文件，但不会自动删除。试用后，可用文件管理器删除 eta-demo.json。删除脚本和记录即可撤销示例，无需恢复代理设置。

等积累足够多、可以相互比较的已完成任务，再考虑校准历史估算。在那之前，说明有效期的粗略范围，比没有依据的精确数字更可信。