# 真实运行可视化数据合同

## 事实来源

后端是只读适配器，不复制 Agent 业务状态，也不向领域模型写入可视化坐标。

| 界面信息 | 权威来源 | 证据等级 |
| --- | --- | --- |
| Task 树、状态、父子关系、Attempt/Validation/Decision 数量 | `TaskLedger` | 已持久化事实 |
| Planner 步骤、工具参数、模型主动说明 | Root Planner Trace messages | 已持久化事实 |
| 某一步后已经出现的 Task | Planner 工具结果累计集合 | 确定性投影 |
| Worker 工具循环与确认读取 | Worker Trace messages | 已持久化事实 |
| 冻结输入闭包 | TaskSpec context refs + ScriptTaskContract | 已持久化事实 |
| Artifact 输出 | Attempt submission | 已持久化事实 |
| 采用、重试、取消、回退 | PlannerDecision | 已持久化事实 |

## 历史回放边界

当前 Ledger 只保存最新 Task 状态。因此选择旧 Planner 步骤时：

- Task 是否已经出现，按当时 Planner 工具结果累计回放；
- Task 的状态仍显示当前 Ledger 状态；
- UI 明示“Planner 工具调用顺序 + 当前 TaskLedger 持久化快照”，不伪造历史状态。

如果以后需要逐 revision 的精确状态回放，应新增 Host 事件投影或 Ledger revision snapshot；不能由前端猜测。

## Data 使用边界

详情中的数据分成四组，不能混称为“模型用过”：

1. `进入 Task 的数据`：在冻结输入闭包或合同中，只能证明可用；
2. `Worker 确认读取`：Worker Trace 中出现真实 read/get/search/query/inspect 工具调用；
3. `Task 产生的数据`：Attempt submission 中的 Artifact 引用；
4. `采用与回退`：PlannerDecision 的实际 action 与 reason。

## Reasoning 边界

`reasoning_content` 在当前真实 Qwen Trace 中可能为空。界面只展示：

- assistant `text`；
- 工具调用名和参数；
- 工具结果摘要；
- Validator recommendation / criterion reason；
- PlannerDecision reason。

这些是可观察运行证据，不等同于、也不命名为隐藏思维链。