🛠️ AI 工具调用 (Function Calling)

LingChat 将用户对话、主动对话和部分剧本 AI 对话接入统一的工具循环。模型请求工具后，运行时执行工具、把结果回填上下文，并继续生成最终回复。

调用闭环

生成请求 -> 权限计算 -> 下发工具定义 -> 模型请求工具
-> 执行工具 -> 工具结果写入台词树 -> MemoryBuilder 还原历史 -> 下一轮生成

工具由 Rust ToolRegistry 注册并由执行器统一校验、解析和超时控制。调用过程会落入 line 表，以便角色在后续回合保有相关上下文。

权限模型

权限不是单一开关，而是“场景组 x 角色组”的交集：调用来源映射到场景组，角色必须属于启用的角色组，最终可用工具集由两边共同裁剪。

当前工具与执行边界

内置工具按日程、记忆、角色、场景、状态、时间、Skills、文件操作、命令与联网搜索等能力分组。工具循环最多允许有限轮次的调用，并会截断过长工具结果，避免文件内容或命令输出无限撑大存档与模型上下文。

执行器会在调用前进行 JSON Schema 参数校验；工具可声明专用超时。扩展工具时，应实现 Tool trait、注册工具、决定其所属分组、配置权限并补充测试。

权限与设置

权限矩阵位于 <data_dir>/tool_permissions.toml，负责场景与角色的底层放行。当前还提供 tool_settings.toml 和应用内设置，用于按工具分组控制用户可用能力，并把启用的分组同步到权限配置。

WARNING

文件操作、命令执行和联网搜索可能涉及本地数据或外部请求。启用这些分组前，应理解相应工具及审批选项的实际行为。

记忆闭环

工具请求和结果会写入台词树，再由 MemoryBuilder 按当前角色还原为 LLM 工具消息。试玩中止时，生成代号会阻止迟到的工具结果回填到正常存档。

上游的完整实现、扩展与权限说明位于 docs/function_call/。