# Script Build Execution Observer

脚本构建系统的只读真实运行观察器。它不再用 Fake Graph 模拟一条固定流水线，而是直接投影 Host 持久化的 TaskLedger、全局 Planner Trace 和 Worker Attempt Trace。

主界面严格对应当前代码的四层结构：

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 或数据库。

## 启动

```bash
cd visualization/backend
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8788
```

```bash
cd visualization/frontend
npm install
NEXT_PUBLIC_API_BASE=http://127.0.0.1:8788 npm run dev
```

访问 `http://127.0.0.1:3008`。

## API

- `GET /api/health`
- `GET /api/runs`
- `GET /api/runs/{script_build_id}/execution`
- `GET /api/runs/{script_build_id}/tasks/{task_id}`

## 验证

```bash
cd visualization/backend && .venv/bin/python -m pytest -q
cd visualization/frontend && npm test && npm run typecheck && npm run build
```

真实数据的投影边界与证据等级见 [DATA_CONTRACT.md](./DATA_CONTRACT.md)。