LoopX证据与回写（Evidence + Writeback）机制：长任务为何可复盘——新手完整指南

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 认为，一次"看起来完成了"和"控制面已接受"之间，隔着五个层次：

关键顺序是：验证先于回写，回写先于记账。缺任何一层，故障形态都不同——这也是 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）如何让状态可恢复？

回写不是"发条消息"，而是一次有语义的状态事务。典型流程：

1. Agent 完成动作后，通过loopx refresh-state等命令写入 run 分类、交付结果、进度；
2. 事件被追加到只增不改的回滚事件日志（rollout-event-log），如todo_update、validation、quota_spend等类型化事件；
3. 状态投影、看板、历史自动同步更新，任何后续 Agent 都能从持久状态恢复，而不依赖某次会话的记忆。

对多 Agent 场景，LoopX 还提供Agent 作用域的证据账本（evidence ledger）：每个 Agent 能看到自己的时间线事件 + 其他 Agent 的压缩 frontier，既够 replan 用，又不会泄露彼此的原始工作轨迹。

🛡️ 安全边界：Public-Safe 与失败即关闭

回写给外部运行时（Runtime）时同样讲究边界，核心原则有两条：

• Public-Safe（公开安全）：回写 payload 只能是紧凑的元数据——决策 id、摘要、证据指针数量；严禁复制原始转录、本地路径、凭据或私有文档。LoopX 在写入时会自动扫描并拒绝含敏感标记的内容；
• 失败即关闭（Fail Closed）：源事件不存在、投影缺失、运行时不可用时，写回直接拒绝或记为skipped/failed，绝不"猜"。回写失败不会让原本正确的决策失效——它只表示"宿主还没收到这份紧凑反射"，下次重试即可。

这套边界让证据可以放心共享、复盘和审计，而不会变成隐私泄露。

🚀 新手三步用上证据与回写

1. 看状态：loopx status投影当前状态、todo 索引、Agent 车道与事件摘要，回答"现在什么是对的"；
2. 打包复盘：loopx review-packet把状态与关注项打包成审查/交接包，随时可以"断点续传"；
3. 查账本：通过 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