KEEL · 龙骨 · A CURRICULUM FOR THE AI ERA
Tool Calling 配套项目：先验证边界，再接真实模型 — keel 龙骨
Tool Calling 的配套项目：Tool Calling 配套项目：先验证边界，再接真实模型
把 Harness 的事件诊断助手作为业务背景，沿着两条路径观察工具调用：
确定性路径：ToolCall -> Registry -> Executor -> ToolResult
真实模型路径：Ollama -> ToolCall -> 确定性执行器 -> Ollama
先跑确定性路径。工具白名单、参数校验、权限、幂等和审批不能依赖模型随机性。
准备环境
python -m pip install -r courses/foundation/tool-calling/course/project/requirements.txt
真实模型实验还需要：
ollama serve
ollama pull qwen3:8b
$env:OLLAMA_MODEL = "qwen3:8b"
按章节运行和观察
第 01 和第 05 章：确定性请求与拒绝
python courses/foundation/tool-calling/course/project/examples/02_validated_dispatch.py
它直接构造合法调用、未知工具、错误参数和未审批写调用。对照流程图，看每个结果在哪一道边界产生。
第 04 章：数据库的静态行 → 可调用对象
python courses/foundation/tool-calling/course/project/examples/07_dynamic_resolution.py
不需要数据库服务，示例用 SQLite 内存库模拟 tools 表。依次观察：本地工具按限定名 import 出来的对象与直接 import 拿到的是同一个、远端工具由转发器动态生成、四种越界 locator 被拒、以及两种 callable 的签名差异。
第 06 / 08 / 09 / 10 章：不装模型的完整链路
python courses/foundation/tool-calling/course/project/examples/08_offline_loop.py
python courses/foundation/tool-calling/course/project/examples/09_offline_advanced.py
ScriptedAdapter 按脚本扮演模型：08 用同一个 Runner 走出五种停止状态；09 覆盖契约两半、输出违约、自修复、并发乱序、审批恢复、流式分片和一次完整运行的事件流。
第 02 和第 06 章：真实单次调用与循环
python courses/foundation/tool-calling/course/project/examples/01_single_tool.py
python courses/foundation/tool-calling/course/project/examples/03_tool_loop.py
真实模型可能直接回答，也可能请求工具。你要观察的是代码如何处理两条分支，以及工具结果如何回到下一轮。
第 07 章：结果未知和幂等
python courses/foundation/tool-calling/course/project/examples/04_idempotency.py
同一个幂等键重复创建工单，第二次应返回第一次结果；同一个 key 配不同参数应冲突。
第 08 章：并行和流式
python courses/foundation/tool-calling/course/project/examples/05_parallel_tools.py
python courses/foundation/tool-calling/course/project/examples/06_streaming_tools.py
先预测部分成功和流中断应该怎样收束，再对照输出和事件。
源码阅读顺序
contracts.py ToolCall、ToolResult、ToolError、ToolDefinition
resolution.py 静态行 -> callable：限定名 import / 动态生成转发器
registry.py 工具白名单和模型可见 schema
executor.py 输入/输出校验、策略、执行和错误
tools.py 事件查询与工单示例工具
ollama_adapter.py 供应商对象转换
scripted_adapter.py 按脚本说话的假模型（离线验证整条链路）
runner.py 多轮循环、call_id 和停止条件
不要从 runner.py 开始。先读 contracts.py，然后看一个固定 ToolCall 怎样经过 Registry 和 Executor。
运行全部测试
python -m unittest discover -s courses/foundation/tool-calling/course/project/tests -v
测试固定验证白名单、输入输出 schema、副作用策略、结构化错误、循环停止、幂等、假模型自身的回放语义，以及第 04 章的三条性质（locator 白名单先于 import、转发器只有泛化签名、限定名配方还原出同一个对象）。真实模型选择质量需要单独评估，不替代这些测试。
目前实现的边界
示例中的幂等记录和业务工具使用内存实现，适合观察协议。生产系统还需要持久化幂等键、事务唯一约束、身份系统、网络超时和外部服务状态查询。