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

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。然后分别启动可视化后端和前端：

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

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}

验证

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。