debug

2026-01-19 17:51:14 +08:00 · 2025-09-25 12:38:51 +08:00
parent 48cf486725
commit 9f2fd95ef0
3 changed files with 126 additions and 3 deletions
--- a/FUNCTION_CALL_DESIGN.md
+++ b/FUNCTION_CALL_DESIGN.md
@@ -0,0 +1,113 @@
+# Function Call 架构说明
+
+## 总览
+新架构围绕 `function_calls/` 目录构建，所有业务能力都以 Function Call 的形式注册和执行：
+
+- **FunctionSpec / FunctionResult** (`function_calls/spec.py`)：描述函数的元数据（名称、描述、JSON Schema 参数定义、作用域、是否要求 @ 等）以及标准化的执行结果。
+- **Registry** (`function_calls/registry.py`)：集中注册函数，通过 `@tool_function(...)` 装饰器将 handler、参数模型、示例等元信息写入全局注册表，供路由器查询。
+- **Handlers** (`function_calls/handlers.py`)：每个函数的入口，签名统一为 `(ctx: MessageContext, args: TypedModel) -> FunctionResult`，内部调用业务服务，返回结构化结果。
+- **Services** (`function_calls/services/`)：纯业务逻辑层，如提醒、Perplexity、群总结、闲聊兜底等，避免 handler 直接处理外部依赖。
+- **Router** (`function_calls/router.py`)：处理消息分发，负责：
+  1. 准备函数注册表与执行器
+  2. 调用 FunctionCallLLM 与模型交互
+  3. 执行 handler 并发送结果
+- **LLM 协调器** (`function_calls/llm.py`)：包装模型函数调用接口，负责 message 拼装、tool 调用循环、错误处理，确保 schema 传递给支持 function calling 的模型。
+
+`robot.py` 中 `Robot.processMsg` 仅构造 `MessageContext`，传给 `FunctionCallRouter`；若函数调用链返回 `False`，则执行好友申请/欢迎词等特殊逻辑，并最终调用 `run_chat_fallback` 完成闲聊。
+
+## 执行流程
+1. **消息预处理**：`Robot.processMsg` 从 `WxMsg` 构建 `MessageContext`（`commands/context.py`），附带文本内容、群信息、引用图片、历史限制等。
+2. **Function Call 分发**：
+   - `FunctionCallRouter.dispatch` 检索注册函数（`list_functions()`）。
+   - 调用 `FunctionCallLLM.run`，传入 `ctx`、注册表、执行器、tool formatter。
+3. **LLM 协调**：
+   - `_build_functions_for_openai` 将所有函数的 `parameters_schema`、描述、名称转成 OpenAI/DeepSeek 接口的 `functions` 列表。
+   - `_run_native_loop` 调用模型的 `call_with_functions`，处理多轮函数调用：模型返回 `tool_calls` ⇒ executor 调 handler ⇒ formatter 将 `FunctionResult` 序列化后回传，直到模型给出最终回答或达到轮数上限。
+   - 若模型不支持 `call_with_functions`，直接返回 `no_function_call_support` 错误。
+4. **Handler 执行**：
+   - 每个 handler 通过 `@tool_function` 注册，使用 Pydantic 参数模型（`function_calls/models.py`）进行 schema 校验。
+   - 不同功能调用 `function_calls/services` 下的业务函数，如 `create_reminder`、`run_perplexity`、`summarize_messages`，最终返回 `FunctionResult`。
+   - `FunctionResult.dispatch()` 可用于直接下发消息，或统一序列化给 LLM。
+5. **兜底逻辑**：
+   - Model 返回失败或无结果时，`Robot.processMsg` 会处理好友请求、欢迎新成员等特殊事件。
+   - 仍未回应则调用 `run_chat_fallback(ctx)`：使用当前 chat 模型生成闲聊回复，可处理引用图片、XML 格式化历史等。
+
+## 目录结构
+```
+function_calls/
+├── __init__.py
+├── handlers.py            # 统一注册的 Function handlers
+├── init_handlers.py       # 导入 handlers 以触发注册
+├── llm.py                 # 与模型进行函数调用循环
+├── models.py              # Pydantic 参数模型
+├── registry.py            # 全局函数注册表 + 装饰器
+├── router.py              # 对外暴露的 Function Call 分发器
+├── services/              # 业务逻辑模块
+│   ├── __init__.py
+│   ├── chat.py            # 闲聊兜底逻辑
+│   ├── group_tools.py     # 群总结、清理缓存等
+│   ├── perplexity.py      # Perplexity 服务封装
+│   ├── reminder.py        # 提醒业务
+│   └── ...
+└── spec.py                # FunctionSpec / FunctionResult 定义
+```
+
+## 模型支持
+当前架构仅支持原生函数调用接口的模型：
+- `ai_providers/ai_chatgpt.py`
+- `ai_providers/ai_deepseek.py`（新增 `call_with_functions`）
+
+若模型不具备 `call_with_functions` 方法，`FunctionCallLLM.run` 会返回 `no_function_call_support`，提示配置支持函数调用的模型。已移除提示词 fallback 与 JSON 判决逻辑。
+
+## 闲聊兜底
+`function_calls/services/chat.py`：
+- 优先使用 XML 解析器 (`ctx.robot.xml_processor`) 格式化消息。
+- 若引用了图片且模型支持视觉能力，走 `get_image_description`。
+- 否则构造 `[HH:MM] Sender: Content` 提示词，调用 chat 模型生成回复并发送。
+- 缺少 chat 模型或生成失败时会给出基本提示。
+
+## FunctionSpec 与参数 Schema
+- `FunctionSpec.parameters_schema` 由 Pydantic 模型的 `model_json_schema()` 得到，封装为标准 JSON Schema。
+- `_build_functions_for_openai` 会把 schema、函数名、描述传给模型的 `call_with_functions` 接口，使模型在生成函数调用参数时受 schema 约束。
+- handler 通过 `_create_args_instance` 将 JSON 参数加载成 Pydantic 对象，若校验失败会记录日志并把错误信息返回给 LLM。
+
+## 典型 handler 示例
+```python
+@tool_function(
+    name="reminder_set",
+    description="设置提醒",
+    scope="both",
+    require_at=True,
+)
+def handle_reminder_set(ctx: MessageContext, args: ReminderArgs) -> FunctionResult:
+    manager = getattr(ctx.robot, "reminder_manager", None)
+    at = ctx.msg.sender if ctx.is_group else ""
+    if not manager:
+        return FunctionResult(handled=True, messages=["❌ 内部错误：提醒管理器未初始化。"], at=at)
+
+    service_result = create_reminder(
+        manager=manager,
+        sender_wxid=ctx.msg.sender,
+        data=args.model_dump(),
+        roomid=ctx.msg.roomid if ctx.is_group else None,
+    )
+    return FunctionResult(handled=True, messages=service_result.messages, at=at)
+```
+
+## 机器人主流程片段（`robot.py:172-236`）
+1. 记录消息历史 → 选择模型 → 构建 `MessageContext`。
+2. 调用 `FunctionCallRouter.dispatch(ctx)`，若 `handled` 为 `True` 直接返回。
+3. 若未处理，处理好友请求/欢迎词等系统消息；否则执行 `run_chat_fallback(ctx)`。
+
+## 健康检查脚本
+`check_system.py` 被更新为校验：
+- Function Call 核心模块导入
+- handler 注册数量（5 个核心函数）
+- `FunctionCallRouter` 初始化
+- 配置模板包含 Function Call 配置
+
+## 保留的 legacy 内容
+`commands` 目录仅保留 `context.py`（消息上下文定义）和简化后的 `__init__.py`。其余旧路由、正则 handler 已移除，防止双体系并存。
+
+---
+该文档覆盖了当前 Function Call 架构的主要模块、数据流、模型依赖以及兜底策略，供后续扩展与维护参考。
--- a/function_calls/services/perplexity.py
+++ b/function_calls/services/perplexity.py
@@ -29,15 +29,24 @@ def run_perplexity(ctx: MessageContext, query: str) -> PerplexityResult:
    sender_wxid = ctx.msg.sender
    room_id = ctx.msg.roomid if ctx.is_group else None

+    captured_messages: list[str] = []
+
+    def capture_send_text(content: str, at_list: str = "") -> bool:
+        captured_messages.append(content)
+        return True
+
    was_handled, fallback_prompt = perplexity_instance.process_message(
        content=content_for_perplexity,
        chat_id=chat_id,
        sender=sender_wxid,
        roomid=room_id,
        from_group=ctx.is_group,
-        send_text_func=ctx.send_text
+        send_text_func=capture_send_text
    )

+    if captured_messages:
+        return PerplexityResult(success=True, messages=captured_messages, handled_externally=False)
+
    if was_handled:
        return PerplexityResult(success=True, messages=[], handled_externally=True)

--- a/robot.py
+++ b/robot.py
@@ -231,8 +231,9 @@ class Robot(Job):
                    self.sayHiToNewFriend(msg)
                    return

-            if not run_chat_fallback(ctx):
-                self.LOG.warning("闲聊兜底失败或未发送回复")
+            if not (ctx.is_group and not ctx.is_at_bot):
+                if not run_chat_fallback(ctx):
+                    self.LOG.warning("闲聊兜底失败或未发送回复")

        except Exception as e:
            self.LOG.error(f"处理消息时发生错误: {str(e)}", exc_info=True)