跳转至

Fusion 参考

本页回答“Fusion Runtime 现在已经有哪些真实组成，而不是把它当成一个只有几个 CRUD 接口的页面”。

模块分层

层 路径 作用
Domain contracts ai_service/fusion/domain/contracts.py Fusion definition contract、slot schema、structured output 规则
Application DTO ai_service/fusion/application/dto.py definition / run 用例输入 DTO
Governance adapter ai_service/fusion/infrastructure/adapters/governance.py capability bindings 到 governance context 的归一化
Run use cases ai_service/fusion/application/use_cases/ Run enqueue、lookup、stale recovery、execute claimed run
Worker 服务 ai_service/fusion/infrastructure/workers/fusion_run_worker.py dispatcher、supervisor、claim / lease / stale recovery
Runtime graph ai_service/fusion/infrastructure/runtime/graph.py 执行图装配
Runtime nodes ai_service/fusion/infrastructure/runtime/nodes.py 输入归一化、prompt 组装、capability 调用、输出持久化
Prompt builder ai_service/fusion/infrastructure/runtime/prompt_builder.py multimodal message list 构造
Output mapper ai_service/fusion/infrastructure/runtime/output_mapper.py 模型输出映射到 output slots
Validator ai_service/fusion/domain/validation.py contract / payload 校验
Capability bindings ai_service/fusion/infrastructure/adapters/ model、rag、mcp、image_generation、storage 等绑定
存储层 ai_service/storage/model_domains/fusion.py run、run input、run output ORM 真相源

当前 API 面

Draft / Snapshot

  • PATCH /agents/{agent_id}
  • GET /agents/{agent_id}/versions
  • POST /agents/{agent_id}/publish

Runs

  • POST /agents/{agent_id}/fusion-runs
  • GET /agents/{agent_id}/fusion-runs
  • GET /agents/{agent_id}/fusion-runs/{run_id}

当前 run 创建已经支持 JSON 和 multipart 两种输入方式，这在 ai_service/fusion/interfaces/http/router.py 与 requests.py 中是显式逻辑，而不是约定俗成。

当前运行时的真实特点

Agent 持有 Draft，AgentVersion 持有 Snapshot

  • live Agent 是可编辑 draft
  • AgentVersion 是不可变快照
  • agents.published_agent_version_id 才是运行时默认执行快照

Run 会持久化输入与输出

ai_service/storage/model_domains/fusion.py 里已经有：

  • FusionRun
  • FusionRunInput
  • FusionRunOutput

这意味着 Fusion 不是“只在内存里跑一下”，而是已经具备可追溯的定义驱动执行记录。

当前 run ledger 还显式记录：

  • attempt_count
  • lease_token
  • last_attempt_started_at
  • worker_heartbeat_at

这四个字段是 worker ownership 真相，不再依赖请求线程内存状态。

Governance context 已经进入 run 结果

  • 当前 run response 不只返回状态
  • 还会返回解析后的 governance context
  • 历史 run 缺失该字段时，服务层会做 legacy payload 回填

structured_json 已支持 document-style profile

当前 OutputSlotDefinition 已支持：

  • structured_output_schema: {...}
  • structured_output_profile: "document_field_set"
  • output_instruction_fragment: "..."

这个 profile 只允许挂在 structured_json 输出槽上，用来表达 document-style canonical JSON，而不是新增一个并行 output kind。

当前实现已经包含：

  • Studio / backend 兼容层把 profile preset 实体化到可见的 structured_output_schema
  • prompt builder 只拼接持久化后的 output_instruction_fragment
  • model binding 直接读取显式 nested schema
  • model binding 缺省只会复用全局 config.chat_model 的 provider / model name，不会继承全局 temperature；当 binding 与 fallback 都未声明温度时，运行时固定使用 0.0
  • validator 对 generic nested schema 和 fields / tables / rows / cells / geometry 做校验

这意味着 Fusion 现在不只是“通用浅层 JSON 输出”，已经开始支持文档字段提取这一类 profile-aware structured output。

Agent-owned surface 与内部兼容层边界

  • 对外正式入口是 Agent draft、published AgentVersion snapshot 和 FusionRun
  • Studio authoring 现在直接编辑 Agent-owned contract，并可视化选择 document_field_set
  • hidden definition row 仍可能作为 runtime compatibility state 存在，但它不是 application-facing contract，也不是前端产品模型
  • derived projection 仍然只是读取便利层；canonical persisted output 仍是 output_item_list[].json_value

读代码时的典型切入点

想改 Fusion Draft / Snapshot 结构

  1. ai_service/fusion/domain/contracts.py
  2. ai_service/storage/model_domains/agents.py
  3. ai_service/api/routers/agents.py

想改 Run 输入输出映射

  1. ai_service/fusion/domain/validation.py
  2. ai_service/fusion/infrastructure/runtime/prompt_builder.py
  3. ai_service/fusion/infrastructure/runtime/output_mapper.py
  4. ai_service/fusion/infrastructure/runtime/nodes.py

想改 document-style 输出 profile

  1. ai_service/fusion/domain/contracts.py
  2. ai_service/fusion/domain/output_profiles.py
  3. ai_service/fusion/infrastructure/runtime/prompt_builder.py
  4. ai_service/fusion/domain/validation.py
  5. ai_service/fusion/infrastructure/adapters/model_binding.py

想改 capability binding

  1. ai_service/fusion/infrastructure/adapters/base.py
  2. 对应 binding 文件，例如 rag_binding.py、mcp_binding.py
  3. ai_service/fusion/infrastructure/adapters/governance.py

与主平台的连接点

路径 作用
ai_service/api/routers/agents.py live draft 更新、publish、rollback
ai_service/orchestrator/ chat runtime 与 Fusion runtime 是平行运行时，不要混为一谈

相关文档