Function Calling：模型请求，服务端执行

1. 解决什么问题

模型无法凭自然语言直接检索数据库或制作文件。Function Calling 把意图表达为带类型的请求，应用校验后执行。工具调用是受控接口，不是允许模型运行任意 Python。

2. 原理与术语

工具说明包含名称、描述和参数 Schema。模型返回 tool_calls；应用按调用 ID 回传结果；模型可能继续调用或提交最终对象。tool_choice='required' 要求发出工具请求，但不保证选中的工具和参数符合业务要求。

3. 执行过程

本系统每轮发送角色可见工具和 submit_result。普通工具交由 ToolSession.execute，最终结果走 Pydantic 校验。素材工具只收集计划，不在模型调用线程里直接访问图片或语音服务。

角色	可执行工具
generator / reviewer / reviser	search_sources、load_rules
producer	plan_asset
任一角色	提交本角色的结构化结果，由适配器处理

4. 容易混淆

“请求已接受”不同于“素材已生成”。plan_asset 返回 executed=false，真正工作由 worker 执行。工具白名单也不能只靠提示词：服务端必须再次检查调用者角色，尤其防范模型发出没有展示给它的工具名。

5. 最小示例

下面直接检查项目注册表，不调用模型或外部服务：

from app.tools import ToolSession
reviewer = ToolSession("reviewer", "reading-example", {})
names = {x["function"]["name"] for x in reviewer.specifications()}
assert names == {"search_sources", "load_rules"}
assert "plan_asset" not in names

6. 实际实现

REGISTRY 同时记录参数模型和角色集合。execute 先授权、后验证参数。检索范围来自任务上下文，不允许模型在 SearchArgs 中覆写地区；素材目标必须是现有 lesson 类型块。计划被去重，完整性由 graph.produce 再核对。

7. 源码与数据结构

阅读 system/app/tools.py::REGISTRY/ToolSession，再读 schemas.py::SearchArgs/AssetArgs、providers.py::run_model 与 graph.py::produce。工具事件记录角色、名称和参数；计划输出是 proposals，与数据库 tasks 不属于同一层。

8. 设计取舍

工具数量少时本地注册表比远程协议更易观察。若需要跨应用共享能力可研究 MCP，但它不会替代业务授权。本项目的文本角色限制十轮调用，素材计划按块数设有限预算，并禁止并行工具请求，便于学习和控制预算；吞吐提升应在保持顺序约束的前提下评估。

9. 实验与验收

先启动系统，在 system 目录执行服务端拒绝实验：

docker compose exec -T api python - <<'PY'
from app.tools import ToolSession, ToolDenied
try:
    ToolSession('reviewer', 'permission-lab', {}).execute('plan_asset', {'block_id':'b1','kind':'image'})
except ToolDenied:
    print('PASS: reviewer denied before execution')
PY

预期拒绝并记录 tool_denied，不产生素材任务。随后在已审核任务中检查 producer 的计划事件与实际 tasks，证明模型请求和程序调度分离。

10. 故障排查

先区分未发调用、未知工具、参数错误、权限拒绝和执行失败。工具名正确仍可能指向不存在的块；这应返回业务错误。不要把任意工具参数拼成 shell 命令，也不要让模型传入供应商密钥或文件路径。

11. 面试题与追问

问：模型能调用审核角色没有的工具吗？ 它可能尝试，但服务端拒绝。追问：只隐藏工具够吗？ 不够，隐藏影响模型可见性，授权约束实际执行。再追问：素材计划漏一项？ produce 比较必需集合，计划不完整不会静默交付。

STAR 应用：假设实验场景，R 为应核对的证据

对应	S：情境	T：目标	A：行动	R：验收证据
主问	评审角色要求制作图片	保护职责边界	服务端按role检查REGISTRY	出现tool_denied且无素材执行
追问一	模型猜到未展示的工具名	抵抗越权尝试	再次授权而非只过滤可见工具	调用在参数执行前被拒绝
追问二	素材计划遗漏音频	避免不完整交付	比较计划集合与必需集合	计划失败，不能把complete=true当充分证据

这些是设计讨论的参考表达，实际执行前不能改写为已取得的历史成果。

12. 官方资料与版本

OpenAI Function Calling、Claude Tool use。核验日期 2026-11-03；本项目实现 Chat Completions 的客户端函数工具，不代表支持所有厂商的托管工具协议。