# V8 数据源与决策真实性契约

## 业务事实表

| 表 | V8 中的唯一业务含义 |
|---|---|
| `script_build_record` | Run 状态、当前创作方向、最终总结和模型配置 |
| `script_build_round` | 轮次目标和当前保存的多路规划 |
| `script_build_branch` | 实现任务、方案类型、当前处置状态和理由 |
| `script_build_data_decision` | 实现 Agent 对取数结果的采用、组合和排除 |
| `script_build_multipath_decision` | 主 Agent 对 `branch_ids` 指向的一批候选结果作出的综合决策 |
| `script_build_domain_info` | 已核实并独立保存的领域事实 |
| 段落、元素、关联三表 | 当前主脚本和内容方案候选产物 |

## 运行记录表

`script_build_event` 和 `script_build_event_body` 只用于补充：

- `script_multipath_evaluator` 对候选方案的逐支评审、跨方案比较和建议；
- `script_evaluator` 对主 Agent 决策后的主脚本进行整体评审；
- 实现 Agent 直接调用的取数 Tool；
- 取数 Agent 实例、Agent 内多次查询和 Agent 输出的初筛整理；
- 规划工具在运行时留下的修订记录；
- Inspector 中的原始输入输出。

## 主 Agent 前三阶段决策链

- 创作目标的当前业务事实是 `script_build_record.script_direction`；成功的 `save_script_direction` 只用来还原它何时保存及保存前主 Agent 直接读取了什么。
- 本轮目标的当前业务事实是 `script_build_round.goal`。`begin_round` 调用前携带的 `round_index` 仍是旧轮次，新轮次优先取成功返回中的 `round_index`，其次才取紧随的 `round_begin` marker。
- 实现规划的当前业务事实是 `multipath_plan / race_or_divide / plan_note`。成功的 `record_multipath_plan` 保留为同轮修订版本，失败调用只进技术记录。
- “主 Agent 直接读取”只认 `agent_role=main + agent_depth=0 + 真实主 scope`；评审 Agent 内部的工具调用不得并入。
- “主 Agent 收到评审”要求评审 Agent 明确返回主 scope；只有结构化轮次和时间顺序时，只能写“形成前可见”，不得写成已采用依据。
- 评审报告正文里的轮次文字与结构化事件冲突时，以事件的 `round_index` 为准。

## 统一 Agent 决策契约

- `direction`：创作目标、本轮目标、实现规划，由主 Agent 最终决定。
- `tradeoff`：实现 Agent 数据取舍仅在当前方案内有效；主 Agent 多路决策是候选方案的最终取舍。
- `evaluation`：多方案评审与主脚本整体评审只提供判断、问题和建议，不直接决定 Branch 状态或 Run 状态。
- `creative`：只有安全关联的实现 Agent `think_and_plan` 与写入事件才能形成创作处理；候选脚本本身不能反推创作过程。
- 所有输入同时标记“观察到的关系”和“是否明确作为依据”。读取过的数据默认只能说明形成前可见，不能自动升级为已采用依据。

评审正文只由带版本号的 `EvaluationReportParser` 解析。业务区只展示结构化的评审对象、标准、逐项结论、达成项、问题、总结论和建议；原始 Markdown、表格和正文中的内部 ID 只进入技术记录。报告正文中的构建 ID 和轮次不参与关联。

## Prompt 准确性

- Agent 派发事件中保存的任务可显示为“本次真实任务”。
- 当前 system prompt 从当前数据库配置或当前文件读取，只能显示为“当前版本规则”。
- 系统没有保存每次 Run 的完整 Prompt 快照，因此当前规则不得描述成“当次运行完整 Prompt”。
- Prompt 只通过懒加载接口读取，统一脱敏、限制长度，不进入 execution-view 主响应。

实现 Agent 与取数 Agent 的归属仅使用 `parent_event_id` / `scope_event_id` 及明确的 `round_index + branch_id`。缺少父子关系时进入未归属技术记录，不通过中文任务文本猜测。

## 取数三层事实

1. **取到什么**：来自 Tool 调用状态和轻量结果摘要。0 条结果是“无结果”，不是失败。
2. **初筛了什么**：只来自取数 Agent 的 `output_content.summary`，不从工具结果自动总结。
3. **正式采用什么**：只来自 `script_build_data_decision`，由实现 Agent 做决定。

`script_build_data_decision.sources` 没有 Agent 事件 ID，因此只做数据类型级对照，不声称某条证据来自同类 Agent 的某一次具体调用。取过但没有进入正式来源的数据，也不自动标记为“被排除”。

## 取数分类

- 工具取数：实现 Agent 直接读取选题、创作总目标、当前脚本、账号段落模式、账号人设或领域信息。
- Agent 取数：解构 Case、知识、外部搜索、Pattern / Relation Agent。每次 `agent_invoke` 是一个独立实例，即使 Agent 类型相同也不合并。
- Agent 内的 `think_and_plan` 和上下文 `get_script_snapshot` 不计入源数据查询次数。

## 禁止解释

1. 不读取或展示 `branch_id <= 0` 的旧语义数据决策。
2. 不用 Branch 的 merged、parked、discarded 状态生成一条不存在的多路决策。
3. 不用事件内容覆盖业务表中的决定、Branch 状态或领域事实。
4. 不把领域事实已经入库解释成其来源内容方案已经进入主脚本。
5. 不把当前规划解释成完整的规划修订历史。
6. 不把候选处置前快照解释成本轮合并后的完整主脚本。
7. 不用模型生成缺失的理由、评审结论或业务影响。
8. 不把取数 Agent 的初筛整理解释成实现 Agent 的正式数据取舍。
9. 不因为同一实现 Agent 调用多个取数 Agent 就显示为并行；必须存在真实时间重叠。
10. 不用模糊的 `evaluator` 名称匹配评审类型；两类评审只认精确事件名。
11. 不把“决策形成前发生过读取”直接解释为“这些数据导致了决策”。
12. 不把评审 Agent 内部读取的数据解释为主 Agent 直接读取。
13. 不把多方案评审或整体评审的建议解释为主 Agent 最终决定。
14. 不从候选脚本或最终主脚本反推实现 Agent 的创作处理过程。
15. 不把当前 Prompt 配置解释成历史 Run 实际使用的完整 Prompt 快照。

## 多批次决策

- 同一轮的多路决策按 `created_at, id` 排序。
- 每条记录独立生成一个收敛节点。
- `branch_ids` 决定进入该节点的连接线。
- 同一 Branch 多次出现时保留全部决策记录，不声明后者覆盖前者。
- 引用不存在的 Branch 时保留决策，但标记为部分完整。
- 有 Branch、无多路决策时显示“未记录主 Agent 多路决策”。

## 多方案评审与主决策关联

- 同一轮允许存在多个收敛批次。
- 多方案评审先用报告中明确的 Branch ID 确认候选范围。
- 只有 Branch 集合相同、且决策时间不早于评审结束时间时，评审和数据库决策才会关联。
- 无法安全关联的评审进入未归属运行记录，不强行挂到某个方案。
- Branch 的当前状态和处置理由只作为主 Agent 决策的逐方案结果展示，不再生成实现 Agent 内部的“方案处理”节点。

## 领域信息方案

- `path_type=领域信息` 的产出来自 `script_build_domain_info`。
- 领域事实按 `script_build_id` 全局累加，`round_index/branch_id` 只用于复盘来源。
- 领域事实数量与 Branch 状态分别展示。
- 领域信息方案不得显示段落、元素或“合入主脚本”的候选统计。

## 只读边界

- 数据库连接使用 visualization 自有连接池。
- 物理连接创建时设置 MySQL Session 为只读。
- Repository 仅允许 Query，不允许 flush、commit 或写操作。
- 活动正文和候选快照按需读取，所有技术输出统一脱敏。