docs(可视化运行): 更新真实 agent-data 启动与验证方式

说明 SCRIPT_BUILD_AGENT_DATA_ROOT、后端和前端启动命令、真实 API 路由及测试流程。删除 fake fixture 与旧 Host 合同生成说明，补充当前只读真实运行模式的限制。

visualization/README.md

@@ -1,8 +1,39 @@
-# Script Build Mission Control
+# Script Build Execution Observer
 
-当前智能创作构建系统的独立可视化。后端是只提供确定性 fake 数据的 FastAPI，前端是 Next.js + React Flow 的 n8n 风格节点画布。
+脚本构建系统的只读真实运行观察器。它不再用 Fake Graph 模拟一条固定流水线，而是直接投影 Host 持久化的 TaskLedger、全局 Planner Trace 和 Worker Attempt Trace。
 
-画布按真实新流程展开：输入快照与 Mission Binding → Direction → 多路 Evidence → Structure / Paragraph / ElementSet → Compare / Compose / Portfolio → Phase 3 Root Delivery → 原子发布 → 旧 API 回读。每个任务继续细分为冻结合同、Operation、Worker Attempt、Artifact、Validator、Validation 和 Planner Decision。
+主界面严格对应当前代码的四层结构：
+
+1. 一个围绕创作总目标持续运行的全局 Planner；
+2. Planner 逐步创建、派发和调整的一棵动态 Task 树；
+3. 每个 Task 的 `创建 → Attempt → Validation → Decision` 受控生命周期；
+4. 每个 Attempt 内部的 Worker `说明 → 工具调用 → 工具结果 → 提交` 循环。
+
+界面中的 Reasoning 只指模型主动输出的说明、工具参数、工具结果、Validation 理由和 Planner Decision，不声称展示隐藏思维链。
+
+## 数据源
+
+默认只读同仓库下的：
+
+```text
+script_build_host/.local/agent-data/
+├── task-ledger/<root_trace_id>/orchestration/ledger.json
+├── traces/<trace_id>/messages/*.json
+└── script-task-contracts/<root_trace_id>/sha256/*
+```
+
+可用环境变量覆盖数据根目录：
+
+```bash
+export SCRIPT_BUILD_AGENT_DATA_ROOT=/absolute/path/to/agent-data
+```
+
+当前真实 E2E 验证基线：
+
+- `900029`：11 Tasks、10 Attempts，包含 Structure 与 5 个 Paragraph Task。
+- `900031`：8 Tasks、5 Attempts，包含 cancelled Retrieval 和 Compose 回流。
+
+数据会随真实运行继续写入；前端每 15 秒重新读取一次当前持久化快照，不修改 ledger、trace 或数据库。
 
 ## 启动
 
@@ -19,31 +50,20 @@ npm install
 NEXT_PUBLIC_API_BASE=http://127.0.0.1:8788 npm run dev
 ```
 
-访问 `http://127.0.0.1:3008`。后端不会读取数据库；所有接口都明确返回 `data_mode=fake`。
+访问 `http://127.0.0.1:3008`。
 
 ## API
 
 - `GET /api/health`
 - `GET /api/runs`
-- `GET /api/runs/{script_build_id}/graph`
-- `GET /api/runs/{script_build_id}/nodes/{node_id}`
-- `GET /api/schema-catalog`
+- `GET /api/runs/{script_build_id}/execution`
+- `GET /api/runs/{script_build_id}/tasks/{task_id}`
 
 ## 验证
 
 ```bash
-cd visualization/backend && python -m pytest -q
+cd visualization/backend && .venv/bin/python -m pytest -q
 cd visualization/frontend && npm test && npm run typecheck && npm run build
 ```
 
-在父项目依赖已安装的开发环境中，还可直接用当前 Host/Agent constructors、Pydantic wire models 与 SQLAlchemy table metadata 交叉验证：
-
-```bash
-cd visualization/backend
-PYTHONPATH=.:/tmp/scriptbuild-dbdeps:../../agent:../../script_build_host/src \
-  ../../agent/.venv/bin/python scripts/validate_host_contracts.py
-```
-
-`backend/app/contracts.py` 固化了当前项目领域对象与 Agent wire model 的字段清单。测试要求每个 fake payload 与对应清单完全同键，防止为了展示而发明字段或漏字段。
-
-字段来源、开放 JSON 边界和接真实数据仍缺的接口见 [DATA_CONTRACT.md](./DATA_CONTRACT.md)。
+真实数据的投影边界与证据等级见 [DATA_CONTRACT.md](./DATA_CONTRACT.md)。