LoopX证据与回写（Evidence + Writeback）机制：长任务为何可复盘——新手完整指南
【免费下载链接】loopxLong-horizon agent control plane for durable, governed work across Codex, Claude Code, and other harnesses.项目地址: https://gitcode.com/GitHub_Trending/lo/loopx
LoopX 是一个面向长时程 Agent 的控制平面（Control Plane），用于让 Codex、Claude Code 等 Agent 框架可靠地持久工作。它的证据（Evidence）与回写（Writeback）机制，让长任务的每一步都可追溯、可验证、可复盘：Agent 做了什么、证据在哪里、状态如何被写回，全程有据可查。
🤔 为什么长任务需要"证据"和"回写"？
让 Agent 跑一个几天甚至几周的长任务，新手最容易遇到三个问题：
- 它说完成了，但完成没？——Agent 的口头声明不可信，需要可验证的证据；
- 中途断了，接着怎么跑？——没有回写持久状态，下一个 Agent（或未来的你）只能从头再来；
- 出了偏差，怎么复盘？——没有事件记录，事后无法回答"当时为什么这么决策"。
LoopX 的答案很简单：每个动作必须留下证据，每次推进必须回写状态。二者缺一不可。
📦 一次可靠交付的五层：从 Artifact 到 Spend
LoopX 认为，一次"看起来完成了"和"控制面已接受"之间，隔着五个层次：
| 层 | 含义 | 缺失的后果 |
|---|---|---|
| 1. Artifact（产物） | 代码、文档、PR、实验结果 | 只有"正在推进"的空话 |
| 2. Validation（验证） | 测试、readback、审查 | 不知道是否真的满足行为 |
| 3. Writeback（回写） | 证据与状态写入持久层 | 下一个 Agent 重复劳动 |
| 4. Refresh（刷新） | 状态、历史、投影同步更新 | 看板信息过期，调度决策错误 |
| 5. Spend（记账） | 只为已验证的推进记一次账 | 配额与预算失真 |
关键顺序是：验证先于回写，回写先于记账。缺任何一层，故障形态都不同——这也是 LoopX 能够精确复盘"卡在哪一步"的基础。
🔍 什么才算"权威证据"？
并非所有输出都能当证据。LoopX 的证据标准很严格：
✅ 有效的权威证据：
- 变更文件 / commit / PR diff 等直接产物；
- 评测输出、聚焦的 smoke/test 结果；
- 外部权威数据源、后继状态（successor state）；
- 具体的 blocker 描述（说明"卡在哪、为什么、需要什么才能恢复"）。
❌ 单独不算数：
- todo 被标记完成、replan 的 ACK、Agent 的"我完成了"声明、
- 没有验收证据的"无事跟进"结论。
一个好的证据引用（evidence ref）足够紧凑，比如pr:2136、commit:<sha>、smoke:todo-lifecycle-cli——可以据此恢复判断，但不复制原始日志。
✍️ 回写（Writeback）如何让状态可恢复？
回写不是"发条消息"，而是一次有语义的状态事务。典型流程：
- Agent 完成动作后，通过
loopx refresh-state等命令写入 run 分类、交付结果、进度； - 事件被追加到只增不改的回滚事件日志（rollout-event-log），如
todo_update、validation、quota_spend等类型化事件； - 状态投影、看板、历史自动同步更新，任何后续 Agent 都能从持久状态恢复，而不依赖某次会话的记忆。
对多 Agent 场景，LoopX 还提供Agent 作用域的证据账本（evidence ledger）：每个 Agent 能看到自己的时间线事件 + 其他 Agent 的压缩 frontier，既够 replan 用，又不会泄露彼此的原始工作轨迹。
🛡️ 安全边界：Public-Safe 与失败即关闭
回写给外部运行时（Runtime）时同样讲究边界，核心原则有两条：
- Public-Safe（公开安全）：回写 payload 只能是紧凑的元数据——决策 id、摘要、证据指针数量；严禁复制原始转录、本地路径、凭据或私有文档。LoopX 在写入时会自动扫描并拒绝含敏感标记的内容；
- 失败即关闭（Fail Closed）：源事件不存在、投影缺失、运行时不可用时，写回直接拒绝或记为
skipped/failed，绝不"猜"。回写失败不会让原本正确的决策失效——它只表示"宿主还没收到这份紧凑反射"，下次重试即可。
这套边界让证据可以放心共享、复盘和审计，而不会变成隐私泄露。
🚀 新手三步用上证据与回写
- 看状态：
loopx status投影当前状态、todo 索引、Agent 车道与事件摘要，回答"现在什么是对的"； - 打包复盘：
loopx review-packet把状态与关注项打包成审查/交接包，随时可以"断点续传"； - 查账本：通过 Agent 作用域证据日志查看类型化事件时间线（todo、validation、quota、refresh），定位推进或停滞的根因。
长任务之所以"跑得久还不迷路"，靠的不是 Agent 的记忆力，而是这套证据 + 回写的机制：每步留痕、每步可验证、每次恢复都有据可查。
📚 延伸资料
- 课程第 8 讲（证据、Refresh 与 Self-Repair）：docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md
- 回滚事件日志实现：loopx/rollout_event_log.py
- Agent 作用域证据账本协议：docs/reference/protocols/agent-scoped-evidence-ledger-v0.md
- 受控回写协议：docs/reference/protocols/session-runtime-controlled-writeback-v0.md
- 监控轮询回写实现：loopx/control_plane/scheduler/monitor_poll_writeback.py
【免费下载链接】loopxLong-horizon agent control plane for durable, governed work across Codex, Claude Code, and other harnesses.项目地址: https://gitcode.com/GitHub_Trending/lo/loopx
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
