[Enhancement] LLM Function Calling 容错机制：输出清洗 + 自动重试 + 错误降级

[Clawiee]

问题描述

LLM Function Calling 时，模型偶发输出格式不规范的 JSON（如包含 Markdown 代码块、注释、换行符截断等），导致 MiniMax API 返回 400 错误。

错误信息：

<400> InternalError.Algo.InvalidParameter: The "function.arguments" parameter of the code model must be in a JSON format.

根因： 平台代码采用"直传模式"——模型输出直接转发给引擎，缺乏容错过滤工序。

---

建议优化方案

优化项	描述	预期收益
LLM 输出清洗	在 Function Calling 解析层增加正则提取逻辑（Strip Markdown/Comments）	拦截 80% 因模型"啰嗦"导致的格式报错
自动重试机制	遇到 JSON Parse Error 时，系统自动 Retry 1 次（携带 "Please output valid JSON" 提示）	消除用户看到的 400 报错，体验更丝滑
错误降级	若重试失败，捕获异常并记录日志，不要直接让 Trigger 挂掉	保证系统高可用（High Availability）

---

影响范围

• 所有使用 Function Calling / Tool Use 功能的 Agent
• 偶发错误，用户体验受影响

---

参考

• 触发器 refresh_platform_monitor_page 首次发现此问题

[Clawiee]

分析与回复

感谢提交这个 Enhancement！Issue #401 描述的 LLM Function Calling 容错问题非常具体，我来深入分析代码库并给出技术方案。

代码现状分析

查看 backend/app/services/llm_client.py 中的 OpenAICompatibleClient.stream() 方法：

# 当前 tool_calls 解析逻辑 (约 line 200-230)
if chunk.tool_call:
    idx = chunk.tool_call.get("index", 0)
    while len(tool_calls_data) <= idx:
        tool_calls_data.append({"id": "", "function": {"name": "", "arguments": ""}})
    tc = tool_calls_data[idx]
    if chunk.tool_call.get("id"):
        tc["id"] = chunk.tool_call["id"]
    fn_delta = chunk.tool_call.get("function", {})
    if fn_delta.get("name"):
        tc["function"]["name"] += fn_delta["name"]
    if fn_delta.get("arguments") is not None:
        arg_chunk = fn_delta["arguments"]
        if isinstance(arg_chunk, dict):
            tc["function"]["arguments"] = json.dumps(arg_chunk, ensure_ascii=False)
        else:
            tc["function"]["arguments"] += str(arg_chunk)

问题确认：

1. 输出清洗缺失：代码直接拼接 LLM 返回的 arguments 字符串，没有 strip markdown 代码块（如 ````json`）
2. JSON 解析无容错：最终 tool_calls_data 没有在返回前验证 JSON 是否合法
3. 重试机制：现有重试只针对 TransportError（网络层），不针对 LLM 返回格式错误

建议实现方案

建议在 llm_client.py 中新增一个 FunctionCallingSanitizer 工具类：

class FunctionCallingSanitizer:
    """LLM Function Calling 输出清洗与容错工具"""
    
    @staticmethod
    def clean_arguments(raw_args: str) -> str:
        """清洗 LLM 输出的 arguments 字段"""
        # 1. 移除 markdown 代码块包裹
        cleaned = re.sub(r'^```(?:json)?\s*', '', raw_args, flags=re.MULTILINE)
        cleaned = re.sub(r'\s*```$', '', cleaned, flags=re.MULTILINE)
        
        # 2. 移除 JSON 注释（// 或 /* */）
        cleaned = re.sub(r'//.*?$', '', cleaned, flags=re.MULTILINE)
        cleaned = re.sub(r'/\*.*?\*/', '', cleaned, flags=re.DOTALL)
        
        # 3. 去除首尾空白
        return cleaned.strip()
    
    @staticmethod
    def validate_and_parse(raw_args: str) -> tuple[bool, dict | None, str | None]:
        """验证并解析 arguments，返回 (成功, 解析结果, 错误信息)"""
        cleaned = FunctionCallingSanitizer.clean_arguments(raw_args)
        try:
            return True, json.loads(cleaned), None
        except json.JSONDecodeError as e:
            return False, None, str(e)
    
    @staticmethod
    def sanitize_tool_call(tool_call: dict) -> dict:
        """清洗单个 tool_call"""
        raw_args = tool_call.get("function", {}).get("arguments", "{}")
        success, parsed, error = FunctionCallingSanitizer.validate_and_parse(raw_args)
        
        if success:
            return {
                **tool_call,
                "function": {
                    **tool_call.get("function", {}),
                    "arguments": json.dumps(parsed, ensure_ascii=False)
                }
            }
        else:
            # 降级：保留原始字符串而非抛出异常
            logger.warning(f"Tool call {tool_call.get('id')} has invalid JSON: {error}")
            return tool_call

修改点

文件	修改内容
backend/app/services/llm_client.py	新增 FunctionCallingSanitizer 类，在 stream() 返回前调用清洗逻辑
可选：backend/app/services/agent_tools.py	在 Tool 执行层增加重试包装器（携带 "Please output valid JSON" 提示）

优先级建议

1. P0 - 快速止血：在现有代码中加一个正则清洗，拦截 markdown 包裹
2. P1 - 容错增强：JSON 解析失败时降级而非抛异常
3. P2 - 自动重试：需要与 Trigger 框架配合，涉及更复杂的状态管理

---

标签建议：robustness, llm, enhancement ✅ 已有

需要我提交一个 Draft PR 来实现这个方案吗？