跳转至

Fusion 运维

本页回答“Fusion 在日常维护里到底怎么跑”，重点不是旧的 definition 编辑体验，而是 run 为什么失败、为什么输出不合约、为什么 binding 看起来没生效。

日常维护对象

Fusion 运行面至少有 4 个核心对象：

  1. live agent draft
  2. immutable agent_version snapshot
  3. fusion_run
  4. governance_context

其中真正可执行的是 immutable agent_version，而不是 live draft。

标准运维路径

  1. 创建或更新 live Fusion draft
  2. 显式 publish，生成新的 agent_version
  3. 发起 run，并确认选中的 agent_version_id
  4. 查看 run 的输入、输出、状态和治理快照
  5. 若结果异常，判断是 contract、binding、artifact 还是模型输出问题
  6. 修 draft 后重新 publish 新 snapshot，而不是直接篡改历史 run

发版前检查

在把某个 published snapshot 给业务方或评测使用前，至少检查：

  • input_contract 和 output_contract 是否可被当前前端或上游满足
  • execution_policy 是否符合当前运行模式
  • capability binding 是否都能解析到真实资源
  • owning agent 上的治理配置是否仍然有效
  • 需要文件输入时，artifact 准备路径是否可达

Run 排查顺序

1. 先确认 run 绑定了哪个 snapshot

不要先看模型输出。先看 run record 的：

  • agent_id
  • agent_version_id
  • execution_mode
  • governance_context_json

这是最常见的误判点之一。很多“同一个 Agent 为什么今天结果不一样”本质上是 snapshot 变了。

兼容性说明：

  • 新创建的 run 仍应绑定一个明确的 agent_version_id
  • 如果读取到历史或迁移前遗留的 run 返回 agent_version_id = null，说明该行缺少快照绑定；当前 API 会继续返回该 run，避免整个列表因单条坏数据而 500

2. 再看输入有没有在 contract 层被拒绝

当前运行时会先做：

  • snapshot contract 自校验
  • run 输入校验
  • 通过后再持久化成 FusionRunInput

如果 run 很早失败，优先怀疑：

  • required input slot 缺失
  • 输入类型不匹配
  • output contract 本身不合法

3. 再看 governance context 和 binding

FusionRunService.create_run() 在创建 run 时就会持久化治理快照，而不是执行时临时推断。

排查时重点看：

  • rag_enabled
  • rag_agent_id
  • rag_top_k
  • mcp_enabled
  • mcp_agent_id
  • allowed_tool_names
  • mounted_server_ids

如果绑定看起来“没生效”，先看 persisted governance context，而不是只看 live draft。

4. 最后再看模型或工具阶段

当 contract 和 binding 都正常后，再查：

  • prompt 构建
  • artifact 准备
  • RAG retrieval
  • MCP invocation
  • output normalization

常见症状与动作

Run 一创建就报 version_not_runnable

先看：

  1. 是否没有 published agent_version
  2. 请求里传入的 agent_version_id 是否不存在
  3. snapshot 是否与当前 agent_id 不匹配

Run 状态成功，但输出为空或缺 slot

先看：

  1. output_contract 是否要求结构化 slot
  2. output_mapper 是否把模型返回映射到了正确 key
  3. validate_output_payloads() 是否拒绝了不合法字段

Binding 已配置，但运行时没走 RAG 或 MCP

先看：

  1. governance_context_json 是否已持久化成启用状态
  2. owning agent 的挂载是否有效
  3. 绑定解析后是否被执行模式或 policy 跳过

live draft 改了，但旧 run 没变化

这是正常行为。run 绑定 immutable snapshot，历史 run 不会追随 live draft 变化。

某次 run 和上一版结果差异很大

优先确认：

  1. agent_version_id 是否变化
  2. binding 是否变化
  3. owning agent 的治理上下文是否变化
  4. execution mode 是否变化

代码入口

路径 作用
ai_service/api/routers/agents.py live draft 更新、publish、rollback
ai_service/fusion/application/use_cases/create_run.py run 创建、snapshot 选择
ai_service/fusion/infrastructure/adapters/governance.py capability binding 到治理快照的解析
ai_service/fusion/infrastructure/runtime/runner.py run 执行入口
ai_service/fusion/infrastructure/runtime/graph.py runtime 图执行主链路
ai_service/fusion/infrastructure/runtime/output_mapper.py 输出归一化与 slot 映射
ai_service/storage/model_domains/fusion.py run / input / output 持久化
ai_service/storage/model_domains/agents.py live draft 与 immutable snapshot 持久化

什么时候该回滚

Fusion 的正确回滚动作通常不是“改历史 snapshot”，而是：

  1. 将 live agent rollback 到已知稳定的 agent_version
  2. 或基于旧 snapshot 重新 publish 一个修正版

只有这样，run 结果和治理快照才能继续可复盘。

适合谁看

  • 维护 Fusion 工作流的研发
  • 排查 run 输入输出契约问题的平台同学
  • 需要确认 snapshot / binding / 治理快照是否正确的实施同学