编排器架构

当前聊天编排器已经不是“一个 LangGraph 图 + 一个模型调用”这么简单，而是由状态路由、运行时插件、共享内核、能力管线和观测持久化共同组成的运行系统。

顶层结构

flowchart LR
  Start[start] --> Router[router]
  Router -->|AI_ACTIVE| AINode[ai_node]
  Router -->|HUMAN_ACTIVE| HumanNode[human_node]
  AINode --> Kernel[RuntimeKernel]
  Kernel --> Pipeline[CapabilityPipeline]
  Pipeline --> Retrieval[RAG]
  Pipeline --> Tooling[MCP / Skill]
  Pipeline --> Generation[Generation]
  Pipeline --> Checkpoint[Checkpoint / Approval]
  Pipeline --> Observability[Trace / Turn Context]
  HumanNode --> End[end]
  Observability --> End

当前分层

1. 状态路由层

顶层 LangGraph 图仍然很薄，核心职责是根据 session 当前状态在：

AI_ACTIVE
HUMAN_ACTIVE

之间做路由。

这意味着顶层图不负责展开所有业务阶段，真正复杂的链路都在 ai_node 下沉后的运行层。

2. 运行时插件层

当前 chat runtime 已经是可插拔结构，而不是只有一套默认编排器。

路径	作用
`ai_service/orchestrator/registry.py`	注册 chat orchestrator 插件
`ai_service/orchestrator/graph.py`	默认 `chameleon_chat_v1`
`ai_service/orchestrator/react_agent.py`	`langgraph_react_agent_v1`

这层的作用是让 Agent 通过 orchestrator_key 选择运行时，而不是把所有行为硬写在一个类里。

3. 共享内核层

ai_service/orchestrator/runtime_kernel.py 当前承担这些横切职责：

session event -> SessionStatus 解析
turn 级 trace id 生成
Langfuse root span 包装
message type 解析
统一的 turn 执行包装

这意味着不同 runtime 的公共观测与事件行为已经被抽离出来了。

4. 能力管线层

ai_service/orchestrator/capability_pipeline.py 负责把一轮聊天真正拆成能力阶段。

这里至少会和这些系统联动：

RAG
MCP
Skill
generation
response grounding
观测与 debug payload

5. 状态与持久化层

编排器不是跑完即消失，运行时会把关键状态落到持久化层：

ConversationTurn
RuntimeCheckpoint
SessionTakeoverEvent
MCP / Skill audit

因此当前聊天链路已经具备较强的可追溯性。

当前最重要的输入

输入	作用
`orchestrator_key`	决定使用哪套 chat runtime
`model_routing_config`	决定 generation / tool call 阶段模型路由
`mcp_runtime_config`	决定 MCP 历史窗口、调用策略等
`response_grounding_config`	决定最终响应的 grounding 约束
当前 session 状态	决定顶层路由到 AI 还是 HUMAN
turn 上下文	决定这一次运行能看到哪些记忆、source、audit 线索

编排器与其他系统的连接方式

与 RAG

编排器不自己做检索
但会决定何时触发 RAG、如何把上下文注入 generation

与 MCP / Skill

编排器决定工具选择、参数生成、执行预算、direct response 与 passthrough
MCP / Skill 服务负责底层执行与审计

与 Scheduled Tasks

会话型定时任务最终仍然复用聊天运行时的 turn 执行路径
因此 scheduled task 和在线对话不是两套完全隔离的运行世界

与 Evaluation

evaluation runner 会调用 chat runtime
所以编排器的改动会直接改变评测结果，不是只影响线上聊天

当前架构结论

顶层图负责状态路由，不负责展开所有业务阶段
ai_node 内部已经是多阶段能力系统，不是单步模型调用
编排器既服务在线聊天，也被评测与部分后台运行场景复用
checkpoint / approval / takeover / audit 都已经是架构内建部分，不是边缘补丁

读代码建议

想理解默认聊天主链路

ai_service/orchestrator/graph.py
ai_service/orchestrator/capability_pipeline.py
ai_service/orchestrator/runtime_kernel.py

想理解运行时切换

ai_service/orchestrator/registry.py
ai_service/orchestrator/react_agent.py

想理解审批、checkpoint 与人工接管

ai_service/orchestrator/checkpoint_state.py
ai_service/services/runtime_checkpoint_service.py
ai_service/api/routers/core.py
ai_service/conversations/interfaces/http/router.py