# 脚本构建真实运行可视化 V8 独立、只读的 FastAPI + Next.js 运行台。V8 只消费最新业务表和结构化运行事件，把真实脚本构建过程整理成非技术人员能够顺着读完的横向故事，并统一四类 Agent 决策的权限、摘要和详情表达。 ```text 创作目标 → 本轮规划 → 实现 Agent 多路方案 → 多方案评审 Agent → 主 Agent 多路决策 → 主脚本整体评审 → 本轮产出 ``` 每轮先发散为多个实现方案。展开方案后，取数阶段将“实现 Agent 直接调用工具”和“委派取数 Agent”放在同一层级；取数 Agent 内部展示多次查询和自己的初筛整理。实现 Agent 的正式数据取舍位于取数阶段之后，不与初筛混合。 ```text 实现任务 → 取数阶段 ├─ 工具取数 └─ Agent 取数 → 多次查询 → 初筛整理 → 实现 Agent 数据取舍 → 候选产出 ``` 所有候选产出在实现 Agent 区结束，随后按真实批次汇入 `script_multipath_evaluator`。评审只提供候选比较和建议；最终采用、暂存或未采用由 `script_build_multipath_decision` 与 Branch 状态共同展示。合并后的主脚本再由 `script_evaluator` 做整体评审。 取数操作按运行时间投影为单项、依次、并行、混合或先后未确认。没有时间重叠时不会仅因为存在多个 Agent 就显示为并行。 ## 数据真实性 - `script_build_data_decision` 只表示实现 Agent 对数据的采用和排除。 - `script_build_multipath_decision` 只表示主 Agent 对一批候选结果的综合决策。 - `script_build_domain_info` 是独立累加的领域事实；即使来源方案后来未采用，已核实事实仍然存在。 - `script_build_event/body` 只补充评审和运行活动，不覆盖业务表事实。 - 当前 `script_build_round.multipath_plan` 是当前保存值，不描述成完整规划历史。 - 当前主脚本是最终 `branch_id=0` 数据，不描述成任何一轮结束时的精确快照。 - 旧语义 `data_decision` 记录不会被解释成主 Agent 决策。 - 没有多路决策记录时明确显示缺失，不用 Branch 状态反推决定。 完整数据优先级和禁止解释见 [DATA_SOURCE_CONTRACT.md](./DATA_SOURCE_CONTRACT.md)。 ## 架构 ```text LocalDatabaseProvider ↓ ScriptBuildRepository（MySQL 会话级只读） ↓ Business Bundle   ├─ RuntimeEventProjector（只负责编排）   │ └─ RuntimeEventIndex（一次建立顺序、父子、scope、actor 和轮次索引）   │ ├─ RetrievalEventProjector   │ ├─ EvaluationEventProjector + EvaluationReportParser   │ └─ MainAgentDecisionProjector   │ ├─ ObjectiveDecisionProjector   │ ├─ RoundGoalDecisionProjector   │ └─ ImplementationPlanDecisionProjector   ├─ CreativeEventProjector   ├─ AgentDecisionProjector   └─ Artifact Projection ↓ ExecutionViewV8 ↓ React Flow 横向发散—收敛画布 ``` 主接口只返回业务摘要和详情引用。完整事件正文、候选快照、数据库行和技术字段在点击卡片后按需读取。最终主脚本使用单独的只读三表查询，不会为打开脚本表重复加载轮次、分支、决策和事件。 主 Agent 前三阶段分别由专用来源投影器还原事实，再统一投影为 `AgentDecisionProjection`。Direction、Tradeoff、Evaluation、Creative 共用一个卡片与详情协议：画布只展示一个主结论和最多三个摘要，完整输入关系、理由、评审对照和技术证据进入 Inspector。 评审报告只通过一个带版本号的解析器进入业务区，解析失败不会把原始 Markdown 倾倒给业务用户。Agent 派发任务和当前版本规则通过独立懒加载接口查看，并明确标注当前规则不是历史运行 Prompt 快照。 产品信息架构、视觉与交互规范、数据真实性边界分别见 [`PRODUCT.md`](./PRODUCT.md)、[`DESIGN.md`](./DESIGN.md) 和 [`DATA_SOURCE_CONTRACT.md`](./DATA_SOURCE_CONTRACT.md)。 ## 启动 ```bash cd aiddit/pattern/patter_from_global_and_build/visualization/backend python3 -m venv .venv source .venv/bin/activate PIP_CACHE_DIR=../.cache/pip pip install -r requirements.txt PATTERN_DB_HOST_OVERRIDE=192.168.202.204 uvicorn app.main:app --host 127.0.0.1 --port 8788 ``` ```bash cd aiddit/pattern/patter_from_global_and_build/visualization/frontend npm_config_cache=../.cache/npm npm install NEXT_PUBLIC_API_BASE=http://127.0.0.1:8788 npm run dev ``` 打开 `http://127.0.0.1:3008`。 ### 环境变量 | 变量 | 默认值 | 作用 | |---|---|---| | `PATTERN_RUNTIME_DIR` | visualization 的父业务目录 | 定位父项目的 `db_manager.py` 和 `models.py` | | `PATTERN_DB_HOST_OVERRIDE` | 空 | 只在 visualization 的独立连接池中替换 DB host | | `VISUALIZATION_CORS_ORIGINS` | `localhost/127.0.0.1:3008` | CORS 白名单 | | `NEXT_PUBLIC_API_BASE` | `http://127.0.0.1:8788` | 前端访问的可视化后端 | 无论是否配置 Host Override，后端都创建独立连接池，并在每个物理连接上执行 `SET SESSION TRANSACTION READ ONLY`。Repository 不包含新增、更新、删除、flush 或 commit。 ## API ```text GET /api/health GET /api/capabilities GET /api/script-builds?limit=30&status= GET /api/script-builds/{id}/execution-view GET /api/script-builds/{id}/rounds/{round_index} GET /api/script-builds/{id}/activities/{activity_id} GET /api/script-builds/{id}/card-data/{detail_ref} GET /api/script-builds/{id}/inspector-view/{detail_ref} GET /api/script-builds/{id}/artifacts/{snapshot_ref} GET /api/script-builds/{id}/decision-prompts/{prompt_ref} ``` 真实 ID 读取失败返回 404/503，不切换为示例数据。生产后端没有示例数据接口、远程旧接口适配器或原始执行日志接口。 ## 前端交互 - 横向 n8n 式画布，轮次从左向右推进。 - 当前轮默认展开，终态 Run 默认折叠历史轮。 - 内容方案和领域信息方案使用不同图标与产出标签。 - 取数 Agent 默认只展示查询统计和初筛结论；用户可在原地展开每次查询，单次查询结果按需读取。 - Mac 双指自由平移、捏合缩放，普通滚轮不缩放；不显示 MiniMap。 - 所有业务卡片可拖动，最小缩放为 60%，操作按钮始终保留。 - 面向业务阅读的 Inspector 保持原有单列展示；独立的“数据来源”Inspector 用于调试对照。 - “数据来源”按“业务详情中的一项｜这一项的数据依据｜对应的原始字段或原文”逐行对齐，来源明确区分数据库、运行事件、产物、确定性计算和日志锚点。 - 最终结果的“查看完整主脚本”会打开近全屏文档表，支持完整表/精简表、脚本元素关联、表头与前两列固定；关闭后回到原画布位置。 真实 Run 的数据来源回归可在后端目录执行： ```bash .venv/bin/python scripts/validate_source_inspector.py --runs 422 443 444 446 --workers 8 ``` - 轮询不会重置画布位置、节点选择、轮次展开或 Inspector 页签。 ## 验证 ```bash cd backend && .venv/bin/pytest -q cd ../frontend && npm test && npm run typecheck && npm run build PLAYWRIGHT_USE_SYSTEM_CHROME=1 npm run test:e2e ``` 所有缓存、截图和测试产物必须留在 `visualization/.cache`、`visualization/exports` 或 `visualization/test-artifacts`。实现不得修改父业务代码或旧 Demo。