script-build-and-framework-tmp/visualization

脚本构建真实运行可视化 V8

独立、只读的 FastAPI + Next.js 运行台。V8 只消费最新业务表和结构化运行事件，把真实脚本构建过程整理成非技术人员能够顺着读完的横向故事，并统一四类 Agent 决策的权限、摘要和详情表达。

创作目标 → 本轮规划 → 实现 Agent 多路方案 → 多方案评审 Agent → 主 Agent 多路决策 → 主脚本整体评审 → 本轮产出

每轮先发散为多个实现方案。展开方案后，取数阶段将“实现 Agent 直接调用工具”和“委派取数 Agent”放在同一层级；取数 Agent 内部展示多次查询和自己的初筛整理。实现 Agent 的正式数据取舍位于取数阶段之后，不与初筛混合。

实现任务
  → 取数阶段
      ├─ 工具取数
      └─ 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。

架构

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、DESIGN.md 和 DATA_SOURCE_CONTRACT.md。

启动

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

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

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 的数据来源回归可在后端目录执行：

.venv/bin/python scripts/validate_source_inspector.py --runs 422 443 444 446 --workers 8

• 轮询不会重置画布位置、节点选择、轮次展开或 Inspector 页签。

验证

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。