# Script Build Journey

这是面向非技术人员的“智能创作旅程”：用真实运行数据解释系统为什么规划、如何执行、怎样验收，以及失败后如何返工。

## 三层视图

- **全局**：按 Task 展示一次次“规划 → 执行 → 验收 → 决定”创作回合。
- **步骤**：展开真实 JourneyStep，显示 reasoning、process、input data、output data、并行和 loop back。
- **证据**：按需查看安全 TaskContract、Tool Call、Artifact、Validation 和 PlannerDecision 原始证据。

可视化后端只调用 Host 的只读 API，不读取数据库，也不了解 `.local`、Trace 或合同文件的磁盘布局。没有模型说明文字时，界面只用冻结的 TaskContract 做确定性讲解，并明确标记来源，不冒充隐藏思维链。

## 启动

先启动 Script Build Host。Host 默认地址是 `http://127.0.0.1:8080`。然后分别启动可视化后端和前端：

```bash
cd backend
python -m venv .venv
.venv/bin/pip install -r requirements.txt
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 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: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}/journey`
- `GET /api/runs/{script_build_id}/artifacts/{artifact_version_id}`

## 验证

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

生成目录不属于源码。`.next`、测试报告、截图、`__pycache__` 和工具缓存都在 `.gitignore` 中；`node_modules`、后端 `.venv` 与 Playwright 浏览器属于可重建依赖，不提交到 Git。