# Function Call 参数调用参考

## 调用流程概览
- Function Call 路由器会将所有消息交给 `FunctionCallLLM.run`，模型基于已注册的函数规格选择要调用的工具（`function_calls/router.py:47`）。
- 每个处理器都通过 `@tool_function` 装饰器注册，它会读取参数类型注解并生成 JSON Schema，用于 LLM 约束和运行期验证（`function_calls/handlers.py:24`, `function_calls/registry.py:64`）。
- LLM 返回的参数会在 `_create_args_instance` 中转为对应的 Pydantic 模型；若字段缺失或类型不符则会抛错并被记录（`function_calls/router.py:147`）。

下表总结了当前仍启用的 5 个函数及其参数 Schema 与业务用途。
所有关键字段已通过 Pydantic `Field(..., description=...)` 写入属性说明，LLM 在工具定义中可以读取这些 `description` 以理解含义。

## 函数明细

### reminder_set
- **Handler**：`function_calls/handlers.py:24`
- **模型**：`ReminderArgs`（`function_calls/models.py:19`）
- **Schema 摘要**：
  ```json
  {
    "type": "object",
    "required": ["type", "time", "content"],
    "properties": {
      "type": {
        "type": "string",
        "enum": ["once", "daily", "weekly"],
        "description": "提醒类型：once=一次性提醒，daily=每天，weekly=每周"
      },
      "time": {
        "type": "string",
        "description": "提醒时间。once 使用 'YYYY-MM-DD HH:MM'，daily/weekly 使用 'HH:MM'"
      },
      "content": {
        "type": "string",
        "description": "提醒内容，将直接发送给用户"
      },
      "weekday": {
        "type": ["integer", "null"],
        "default": null,
        "description": "当 type=weekly 时的星期索引，0=周一 … 6=周日"
      }
    }
  }
  ```
- **参数含义**：
  - `type`：提醒频率。一次性（`once`）用于绝对时间点；`daily` 为每天定时；`weekly` 需要同时给出星期索引。
  - `time`：触发时间。一次性提醒要求未来时间，格式 `YYYY-MM-DD HH:MM`；每日/每周提醒使用 `HH:MM` 24 小时制。
  - `content`：提醒内容文本，最终会被发送给触发对象。
  - `weekday`：仅在 `type=weekly` 时有效，使用 0-6 表示周一到周日。
- **调用方式**：处理器从 `args.model_dump()` 得到完整参数字典并传给提醒服务的 `create_reminder`（`function_calls/handlers.py:37`）。`weekday` 仅在 `type="weekly"` 时使用；未提供值时默认为 `null`。

### reminder_list
- **Handler**：`function_calls/handlers.py:46`
- **模型**：`ReminderListArgs`（`function_calls/models.py:28`）
- **Schema 摘要**：空对象，没有任何必填字段。
- **调用方式**：函数只验证请求体为空对象，然后调用 `list_reminders` 读取当前用户/群的提醒列表（`function_calls/handlers.py:59`）。

### reminder_delete
- **Handler**：`function_calls/handlers.py:63`
- **模型**：`ReminderDeleteArgs`（`function_calls/models.py:33`）
- **Schema 摘要**：
  ```json
  {
    "type": "object",
    "required": ["reminder_id"],
    "properties": {
      "reminder_id": {
        "type": "string",
        "description": "提醒列表中的 ID（日志或界面可显示前几位帮助用户复制）"
      }
    }
  }
  ```
- **参数含义**：`reminder_id` 即提醒列表返回的唯一 ID，用于定位要删除的记录。
- **调用方式**：直接读取 `args.reminder_id` 并转交给 `delete_reminder` 执行删除逻辑（`function_calls/handlers.py:76`）。

### perplexity_search
- **Handler**：`function_calls/handlers.py:80`
- **模型**：`PerplexityArgs`（`function_calls/models.py:39`）
- **Schema 摘要**：
  ```json
  {
    "type": "object",
    "required": ["query"],
    "properties": {
      "query": {
        "type": "string",
        "description": "要搜索的问题或主题"
      }
    }
  }
  ```
- **参数含义**：`query` 即用户想让 Perplexity 查找的自然语言问题或主题。
- **调用方式**：使用 `args.query` 调用 `run_perplexity`，若外部服务已自行回复则返回空消息，否则把搜索结果转成回复文本（`function_calls/handlers.py:87`）。

### summary
- **Handler**：`function_calls/handlers.py:96`
- **模型**：`SummaryArgs`（`function_calls/models.py:49`）
- **Schema 摘要**：空对象，无需参数。
- **调用方式**：只要模型选择该函数即执行 `summarize_messages(ctx)`，返回群聊近期消息总结（`function_calls/handlers.py:104`）。

## 运行时验证逻辑
1. **模型侧约束**：`FunctionCallLLM` 会把上述 Schema 转成 OpenAI 样式的工具定义，使模型在生成参数时遵循字段、类型与枚举限制（`function_calls/llm.py:112`）。
2. **路由二次校验**：收到工具调用后，路由器会再次调用 `validate_arguments` 确认必填字段存在且类型正确（`function_calls/llm.py:215`）。
3. **Pydantic 转换**：最后在 `_create_args_instance` 中实例化 Pydantic 模型，确保所有字段通过严格校验并可在 handler 中以 `args` 访问（`function_calls/router.py:147`）。

若未来新增函数，只需为 handler 的 `args` 参数提供 Pydantic 模型或 dataclass，装饰器会自动生成相应 Schema 并同步到本流程中。