编排器

ChameleonOrchestrator 使用 LangGraph 构建状态机，根据会话状态在 AI 与人工响应间切换，并集成 RAG 检索、沙箱执行与可观测性追踪。

架构概览

stateDiagram-v2
    [*] --> AI_ACTIVE
    AI_ACTIVE --> HUMAN_ACTIVE: AGENT_TAKEOVER
    HUMAN_ACTIVE --> AI_ACTIVE: AGENT_RELEASE

    state AI_ACTIVE {
        [*] --> IntentParse
        IntentParse --> RAGRetrieval: 需要知识检索
        IntentParse --> ToolExecution: 需要工具调用
        IntentParse --> DirectGenerate: 直接回复
        RAGRetrieval --> Generate
        ToolExecution --> SandboxExec
        SandboxExec --> Generate
        DirectGenerate --> Generate
        Generate --> [*]
    }

核心节点

意图解析节点

解析用户输入，决定后续处理路径：

知识检索：触发 RAG 节点
工具调用：触发沙箱执行
直接回复：跳过检索，直接生成

RAG 检索节点

从向量数据库检索相关上下文：

async def rag_retrieval_node(state: OrchestratorState) -> OrchestratorState:
    """RAG 检索节点，获取相关知识上下文。"""
    query = state.user_message
    results = await rag_service.search(query, top_k=5)
    state.rag_context = format_context(results)
    return state

沙箱执行节点

在隔离环境中执行 AI 生成的代码：

async def sandbox_exec_node(state: OrchestratorState) -> OrchestratorState:
    """沙箱执行节点，运行工具代码。"""
    code = state.tool_code
    result = await sandbox_manager.execute(
        code=code,
        timeout=30,
        memory_limit="128m",
        network="isolated"
    )
    state.tool_result = result
    return state

可观测性

Span 覆盖

编排器在关键节点注入 OpenTelemetry Span：

Span 名称	覆盖范围	关键属性
`orchestrator.intent`	意图解析	`intent_type`
`orchestrator.rag`	RAG 检索	`top_k`, `latency_ms`
`orchestrator.sandbox`	沙箱执行	`timeout`, `exit_code`
`orchestrator.generate`	LLM 生成	`model`, `tokens`

指标采集

关键指标通过 /metrics 端点暴露：

orchestrator_node_duration_seconds - 各节点执行耗时
orchestrator_rag_hits_total - RAG 命中次数
orchestrator_sandbox_executions_total - 沙箱执行次数

错误处理与降级

降级策略

故障场景	降级行为
RAG 服务不可用	跳过检索，直接生成
沙箱执行超时	返回超时提示，记录日志
LLM 调用失败	返回 fallback 文案
向量库连接失败	使用缓存结果或跳过

重试机制

@retry(max_attempts=3, backoff=exponential(base=1, max=10))
async def call_llm_with_retry(prompt: str) -> str:
    """带重试的 LLM 调用。"""
    return await llm_client.generate(prompt)

关键流程

AI_ACTIVE：处理 user 消息，执行 RAG 检索与生成
HUMAN_ACTIVE：处理 agent 消息并直接回传
模型不可用或调用失败时返回 fallback 文案

API 参考

详细字段与方法说明请查看「API 参考 → 编排器」。

编排器