跳转至

编排器参考

本页回答“当前聊天运行时到底由哪些模块组成，以及改某类行为时应该先去哪里”。

运行时分层

层 关键文件 作用
插件注册层 ai_service/orchestrator/registry.py 管理 chat orchestrator 插件，当前至少有默认 chameleon_chat_v1 和可选 langgraph_react_agent_v1
默认运行时 ai_service/orchestrator/graph.py 当前主聊天编排器
ReAct 运行时 ai_service/orchestrator/react_agent.py 预置 LangGraph ReAct loop，支持把 mounted Skill / MCP 暴露成工具
共享内核 ai_service/orchestrator/runtime_kernel.py 给不同运行时复用 turn-level trace、event handling、message type 解析
状态与输入输出 ai_service/orchestrator/state.py ai_service/orchestrator/runtime_types.py 编排器状态、输入、结果、trace context
能力阶段组织 ai_service/orchestrator/capability_pipeline.py 把 RAG、MCP、Skill、响应策略等阶段拼成一条能力链

当前关键行为入口

运行时选择

  • Agent 级运行时切换入口在 ai_service/orchestrator/registry.py
  • Agent 记录里通过 orchestrator_key 选择具体 chat runtime
  • 当你要新增另一套聊天 runtime 时，通常从新增插件和 runtime 类开始，而不是直接改默认 graph

事件与 trace

  • ai_service/orchestrator/runtime_kernel.py 负责统一处理 session event 到 SessionStatus 的映射
  • 同一 turn 的 root trace id 在这里生成，并注入 tracing metadata
  • 如果你要改 Langfuse trace 结构、message type 识别或 root span 行为，优先看这里

MCP 行为

路径 用途
ai_service/orchestrator/mcp_runtime_config.py Agent 级 MCP runtime 覆盖配置
ai_service/orchestrator/mcp_response_config.py direct response、quick match、intent gate、field catalog
ai_service/orchestrator/mcp_passthrough.py passthrough 决策与最终响应渲染

模型与响应控制

路径 用途
ai_service/orchestrator/model_routing.py agent 级模型路由策略
ai_service/orchestrator/response_grounding_config.py grounding 相关响应约束
ai_service/orchestrator/checkpoint_state.py approval request、checkpoint state、审批阶段常量

API 与会话侧联动

编排器不只由 orchestrator/ 目录决定，下面这些入口也直接影响聊天运行时行为：

路径 作用
ai_service/api/routers/core.py /stream、/models、/release-metadata，以及 MCP passthrough / checkpoint 触发面
ai_service/conversations/interfaces/http/router.py session、turn、WebSocket、turn context、knowledge correction、takeover / release
ai_service/services/infra/runtime/session_runtime.py 把一次 session turn 执行包装成服务层入口
ai_service/services/runtime_checkpoint_service.py checkpoint 持久化、恢复与审批挂起
ai_service/api/session_broadcasts.py session WebSocket 房间广播

读代码时的典型切入点

想改默认聊天链路

  1. ai_service/orchestrator/graph.py
  2. ai_service/orchestrator/capability_pipeline.py
  3. ai_service/orchestrator/state.py

想改 ReAct Agent runtime

  1. ai_service/orchestrator/react_agent.py
  2. ai_service/orchestrator/react_tools.py
  3. ai_service/orchestrator/registry.py

想改审批、checkpoint 或 takeover

  1. ai_service/orchestrator/checkpoint_state.py
  2. ai_service/services/runtime_checkpoint_service.py
  3. ai_service/api/routers/core.py
  4. ai_service/conversations/interfaces/http/router.py

想改模型路由或 MCP 直接响应

  1. ai_service/orchestrator/model_routing.py
  2. ai_service/orchestrator/mcp_response_config.py
  3. ai_service/orchestrator/mcp_passthrough.py

当前文档之外但必须知道的现实

  • 这里不是单一 runtime 项目，chat runtime 已经被插件化
  • approval / checkpoint / passthrough / response config 已经是运行时一等公民
  • 运营侧与 Studio 控制面对编排器行为有直接影响，不只是后端内部模块

相关文档