┌─────────────────────────────────────────────────┐
│           六维工具调用校准栈                        │
│                                                   │
│  L6 ┌──────────────────────────────────────┐      │
│     │  延迟容忍度 (Latency Tolerance)       │      │
│  L5 ├──────────────────────────────────────┤      │
│     │  Token成本效率 (Token Economy)        │      │
│  L4 ├──────────────────────────────────────┤      │
│     │  幻觉自检率 (Hallucination Detection) │      │
│  L3 ├──────────────────────────────────────┤      │
│     │  链路一致性 (Chain Coherence)         │      │
│  L2 ├──────────────────────────────────────┤      │
│     │  参数接地性 (Parameter Grounding)     │      │
│  L1 ├──────────────────────────────────────┤      │
│     │  Schema合规率 (Schema Compliance)     │      │
│     └──────────────────────────────────────┘      │
└─────────────────────────────────────────────────┘

class ToolCallGuard:
    def __init__(self, registered_tools: dict[str, ToolDef]):
        self.registry = set(registered_tools.keys())

    def validate(self, tool_call: ToolCall) -> ToolCallResult:
        if tool_call.name not in self.registry:
            return ToolCallResult(
                valid=False,
                error=f"Phantom call: '{tool_call.name}' not in registry",
                correction_hint=f"Did you mean: {self._fuzzy_match(tool_call.name)}?"
            )
        return ToolCallResult(valid=True)

    def _fuzzy_match(self, name: str) -> list[str]:
        """模糊匹配建议可能的正确函数名"""
        from difflib import get_close_matches
        return get_close_matches(name, self.registry, n=3, cutoff=0.6)

┌───────────────────────────────────────────────────────┐
│                    工具调用失败金字塔                     │
│                                                         │
│                 ┌─────────────┐                         │
│                 │ L5 级联崩溃  │  3% — 整条链路报废       │
│               ┌─┴─────────────┴─┐                      │
│               │ L4 链路断裂      │  12% — 上下文丢失     │
│             ┌─┴─────────────────┴─┐                    │
│             │ L3 参数幻觉         │  23% — 凭空填充      │
│           ┌─┴─────────────────────┴─┐                  │
│           │ L2 类型边界违规          │  18% — 值域越界   │
│         ┌─┴─────────────────────────┴─┐                │
│         │ L1 Schema格式违规            │  5% — 最基础   │
│         └─────────────────────────────┘                │
│                                                         │
│    注：剩余39%为非工具调用类Agent失败                      │
└───────────────────────────────────────────────────────┘

TOOL_CALL_SYSTEM_PROMPT = """
## Tool Calling Rules
1. ONLY use tools listed below. Never invent tool names.
2. For each parameter, cite the source — user message, prior tool result, or say "inferred".
3. If a required parameter has no clear source, ASK the user instead of guessing.
4. After receiving tool results, verify they match expected format before using them.

## Error Recovery
If a tool call fails:
- Retry ONCE with corrected parameters
- If still fails, explain the issue and ask user for guidance
- Never silently skip a failed tool call
"""

from pydantic import BaseModel, Field, field_validator
from datetime import date

class SearchParams(BaseModel):
    query: str = Field(..., min_length=1, max_length=500)
    date_range_start: date
    date_range_end: date
    status: list[str] = Field(default=["active"])

    @field_validator("status")
    def validate_status(cls, v):
        allowed = {"active", "inactive", "archived"}
        invalid = set(v) - allowed
        if invalid:
            raise ValueError(f"Invalid status values: {invalid}")
        return v

    @field_validator("date_range_end")
    def validate_date_order(cls, v, info):
        if "date_range_start" in info.data and v < info.data["date_range_start"]:
            raise ValueError("end date must be after start date")
        return v

graph TD
    A[用户请求] --> B{MCP Router}
    B -->|分析意图| C[Tool Selection]
    C --> D{工具是否在注册表?}
    D -->|否| E[幽灵调用拦截]
    E --> F[反馈模型重选]
    D -->|是| G[Schema校验]
    G -->|不合规| H[参数纠偏]
    H --> I[重新生成参数]
    G -->|合规| J[执行工具]
    J --> K{结果验证}
    K -->|异常| L[错误恢复]
    L --> M[重试/降级/询问用户]
    K -->|正常| N[结果注入上下文]
    N --> O{任务完成?}
    O -->|否| A
    O -->|是| P[返回最终结果]

    style E fill:#ff6b6b
    style H fill:#ffd93d
    style L fill:#ff6b6b
    style P fill:#6bcb77

class ParallelToolExecutor:
    def __init__(self, max_concurrent: int = 5, timeout: float = 30.0):
        self.max_concurrent = max_concurrent
        self.timeout = timeout

    async def execute(self, calls: list[ToolCall]) -> list[ToolResult]:
        # 1. 静态依赖分析 — 检测伪并行
        deps = self._analyze_dependencies(calls)
        if deps.has_conflicts:
            return await self._sequential_fallback(calls)

        # 2. 并行执行，带超时和结果大小限制
        results = await asyncio.gather(*[
            self._execute_with_limit(call) for call in calls
        ], return_exceptions=True)

        # 3. 处理部分失败
        final = []
        for call, result in zip(calls, results):
            if isinstance(result, Exception):
                final.append(ToolResult(
                    call_id=call.id, success=False,
                    error=str(result),
                    retry_eligible=self._is_retryable(result)
                ))
            elif result.token_count > self.max_result_tokens:
                final.append(ToolResult(
                    call_id=call.id, success=False,
                    error="Result too large, use pagination"
                ))
            else:
                final.append(result)

        return final

graph LR
    Start[开始评测选型] --> Q1{工具数量?}
    Q1 -->|<10个| A[BFCL v4 Simple]
    Q1 -->|10-50个| Q2{是否并行调用?}
    Q1 -->|50+个| C[MCP-Atlas]

    Q2 -->|是| B[BFCL v4 Parallel]
    Q2 -->|否| Q3{是否多轮?}

    Q3 -->|单轮| A
    Q3 -->|多轮| Q4{有无业务规则?}

    Q4 -->|有| D[Tau-Bench]
    Q4 -->|无| E[BFCL v4 Multi-Turn]

    C --> Q5{是否真实工作流?}
    Q5 -->|是| F[Toolathlon]
    Q5 -->|否| C

    style A fill:#4ecdc4
    style B fill:#4ecdc4
    style C fill:#ff6b6b
    style D fill:#ffd93d
    style E fill:#4ecdc4
    style F fill:#6bcb77