文档：说明 Journey 可视化架构与真实数据边界

更新运行方式、Host API 依赖、前后端职责和测试命令，删除已过时的静态 DATA_CONTRACT，明确界面只展示真实持久化任务链路。

visualization/DATA_CONTRACT.md

@@ -1,46 +0,0 @@
-# 真实运行可视化数据合同
-
-## 事实来源
-
-后端是只读适配器，不复制 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。
-
-这些是可观察运行证据，不等同于、也不命名为隐藏思维链。

visualization/README.md

@@ -1,67 +1,57 @@
-# Script Build Execution Observer
+# Script Build Journey
 
-脚本构建系统的只读真实运行观察器。它不再用 Fake Graph 模拟一条固定流水线，而是直接投影 Host 持久化的 TaskLedger、全局 Planner Trace 和 Worker Attempt Trace。
+这是面向非技术人员的“智能创作旅程”：用真实运行数据解释系统为什么规划、如何执行、怎样验收，以及失败后如何返工。
 
-主界面严格对应当前代码的四层结构：
+## 三层视图
 
-1. 一个围绕创作总目标持续运行的全局 Planner；
-2. Planner 逐步创建、派发和调整的一棵动态 Task 树；
-3. 每个 Task 的 `创建 → Attempt → Validation → Decision` 受控生命周期；
-4. 每个 Attempt 内部的 Worker `说明 → 工具调用 → 工具结果 → 提交` 循环。
+- **全局**：按 Task 展示一次次“规划 → 执行 → 验收 → 决定”创作回合。
+- **步骤**：展开真实 JourneyStep，显示 reasoning、process、input data、output data、并行和 loop back。
+- **证据**：按需查看安全 TaskContract、Tool Call、Artifact、Validation 和 PlannerDecision 原始证据。
 
-界面中的 Reasoning 只指模型主动输出的说明、工具参数、工具结果、Validation 理由和 Planner Decision，不声称展示隐藏思维链。
-
-## 数据源
-
-默认只读同仓库下的：
-
-```text
-script_build_host/.local/agent-data/
-├── task-ledger/<root_trace_id>/orchestration/ledger.json
-├── traces/<root_trace_id>/meta.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
-```
-
-观察器不再绑定固定的历史 Build ID。它从 TaskLedger 发现 Root Trace，并优先从
-Root `meta.json` 的受保护上下文读取 `script_build_id`；`goal.json` 和早期消息只作为旧运行的兼容回退。
-新的真实 E2E 持久化后会自动出现在列表中。前端每 15 秒重新读取快照，不修改 ledger、trace 或数据库。
+可视化后端只调用 Host 的只读 API，不读取数据库，也不了解 `.local`、Trace 或合同文件的磁盘布局。没有模型说明文字时，界面只用冻结的 TaskContract 做确定性讲解，并明确标记来源，不冒充隐藏思维链。
 
 ## 启动
 
+先启动 Script Build Host。Host 默认地址是 `http://127.0.0.1:8080`。然后分别启动可视化后端和前端：
+
 ```bash
-cd visualization/backend
+cd 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
+SCRIPT_BUILD_HOST_API_BASE=http://127.0.0.1:8080 \
+  .venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8788
 ```
 
 ```bash
-cd visualization/frontend
+cd frontend
 npm install
 NEXT_PUBLIC_API_BASE=http://127.0.0.1:8788 npm run dev
 ```
 
-访问 `http://127.0.0.1:3008`。
+默认前端为 `http://127.0.0.1:3008`，可视化后端为 `http://127.0.0.1:8788`。浏览器带上的 Host 登录 Cookie 或 Authorization 会由后端按白名单转发。
+
+## 数据边界
+
+- Host 是 Mission、TaskContract、InputSnapshot 和 Artifact 的唯一权威来源。
+- 可视化只做只读投影，不改变 Agent、TaskLedger、Phase 状态机或发布逻辑。
+- `JourneyEdge` 是步骤关系的唯一权威来源；Step 不重复保存返工目标。
+- Input Summary 只返回主题、Persona/Strategy 摘要和快照标识，不返回 Prompt、密钥、数据库信息或 Strategy 原文。
+- Artifact 内容只在用户打开证据层时按需读取。
+
+可视化后端复用一个 Host HTTP 连接池。Input Summary 和同一 Spec 的 TaskContract 会缓存；Orchestration Event 和 Trace Message 按 cursor/sequence 增量追加。前端只轮询运行中的 Build，完成态停止自动刷新。
 
 ## API
 
 - `GET /api/health`
 - `GET /api/runs`
-- `GET /api/runs/{script_build_id}/execution`
-- `GET /api/runs/{script_build_id}/tasks/{task_id}`
+- `GET /api/runs/{script_build_id}/journey`
+- `GET /api/runs/{script_build_id}/artifacts/{artifact_version_id}`
 
 ## 验证
 
 ```bash
-cd visualization/backend && .venv/bin/python -m pytest -q
-cd visualization/frontend && npm test && npm run typecheck && npm run build
+cd backend && .venv/bin/python -m pytest -q && .venv/bin/ruff check app tests
+cd frontend && npm test && npm run typecheck && npm run build
 ```
 
-真实数据的投影边界与证据等级见 [DATA_CONTRACT.md](./DATA_CONTRACT.md)。
+生成目录不属于源码。`.next`、测试报告、截图、`__pycache__` 和工具缓存都在 `.gitignore` 中；`node_modules`、后端 `.venv` 与 Playwright 浏览器属于可重建依赖，不提交到 Git。