script-build-and-framework-tmp/visualization/DATA_CONTRACT.md

真实运行可视化数据合同

事实来源

后端是只读适配器，不复制 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。

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