第一轮 · 第 7 站 · CORE · 工具分支入门

工具执行:模型提议,谁真正动手?

第 5 站说“执行工具并回填结果”,这不是一个黑箱。模型给出的工具名称和参数,要经过运行时、路由与注册表,才会到达真正执行代码。

本站必背:走路时复述这一段

分清工具定义、工具调用与工具结果
理解 call_id、payload 和 invocation
区分工具可恢复失败与整轮致命错误

第一轮扩展站:深入主链中的工具支路,精读核心数据和分派边界;不在本课穷举所有内置工具、MCP 或 Code Mode 的实现。 讲义已备好 ≠ 已掌握;本页不会改动你的通关状态。

本站必背 · 走路复习

第 7 站:模型提出调用,工具实现动作

先理解,再背这一个完整段落。日常复述约 1–2 分钟;点标题可遮住正文,按下面的顺序提示试着复述。

核心背诵段 · 点击展开或遮住

第七站位于 Core 的工具执行链。工具定义告诉模型有什么能力、参数怎样填写,但定义本身不会执行动作。模型产生具体工具调用后,运行时安排执行与取消,ToolRouter 补齐会话和步骤上下文,ToolRegistry 查找已注册实现,再由具体工具及下游完成相应检查和动作。call_id 用来关联这一次调用及其结果,不是 Turn 编号;找不到工具应明确报错,不能假装执行成功。结果或可反馈的错误会回到后续模型处理,是否终止整轮取决于错误类型和控制流程。记住:模型是调用的提出者,工具实现才连接真实能力;参数能解析,不代表权限和业务条件已经满足。

复述顺序:工具定义 → 具体调用 → 运行时安排 → 路由与注册表 → 实际动作与结果。

背诵用于抓牢主线。理解自测:为什么给模型一份“删除对象”的工具说明,还不等于已经实现了删除功能? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。

核对依据:一次工具调用 · 组装执行上下文 · 查找实现与失败反馈。

配套音频 · AI 合成语音

先听一遍,再对照源码

普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。用“说明书、调用单、执行者、回执”辅助记忆,再回到真实类型。

全长 6:21 · 6 章MP3 · 2.9 MB普通话女声 · 稍慢语速
下载 MP3

点击开始;页面不会自动播放,也不会自动标记课程通关。

点击任一章,从对应位置开始。

    展开音频文字稿 · 听不清时对照看
    声音中的术语,对应代码里的哪个词?

    AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。

    先定位:这一站到底在讲哪一层?

    这条分支位于 Core。模型服务产出工具调用项目,流事件处理将它转换为内部 ToolCall;ToolCallRuntime 负责执行时机与取消协调;ToolRouter 组织调用上下文;ToolRegistry 查找实际运行实现。

    工具的说明和真正执行它的代码是两份东西。模型看见工具名称、用途和参数约束,并不表示模型自己直接修改了文件或运行了求解器。真正的副作用发生在工具执行实现及其下游。

    1. 1模型看到可用工具说明
    2. 2模型响应包含工具调用
    3. 3运行时安排执行与取消
    4. 4Router 组装 ToolInvocation
    5. 5Registry 找到工具实现
    6. 6结果回填历史并供下一次模型使用
    粒度负责什么不要误认为
    ToolSpec向模型说明可以调用什么、怎样填参数不是实际执行命令的函数体
    ToolCall一次具体调用的工具身份、调用 ID 和载荷不是工具注册定义
    ToolInvocation工具调用加上 Session、步骤上下文和取消等运行信息不是把所有字段直接发给模型
    具体工具实现解析业务参数,执行或调用下游服务,形成输出不允许仅因为模型提出就绕过权限边界

    先拆一份调用单

    工具定义回答“系统能提供什么能力”。工具调用回答“这次请调用哪个能力、传什么参数”。工具结果回答“实际上发生了什么”。三个阶段的数据不能混成同一个“工具”。

    call_id 用来把这一次调用与结果关联起来。同一个工具在同一 Turn 里调用两次,需要区分这两次;不能只用工具名称作为结果匹配键。payload 则是承载具体调用输入的枚举,普通 function 工具与其他调用形式可能不同。

    1. ToolCall:每个字段都属于这一张调用单

    真实源码 · codex-rs/core/src/tools/router.rs:36–42

    代码较长时可左右滑动;下方按语句和术语拆解。

    #[derive(Clone, Debug, PartialEq)]
    pub struct ToolCall {
        pub tool_name: ToolName,
        pub call_id: String,
        pub payload: ToolPayload,
        pub encrypted_function_args: Option<Vec<String>>,
    }
    逐句/逐词这段代码实际做了什么
    #[derive(Clone, Debug, PartialEq)]让类型具备克隆、调试格式和相等比较等派生能力;并不是执行工具。
    tool_name: ToolName工具身份;ToolName 可以表达名称与命名空间,不只是显示用标题。
    call_id: String本次调用的关联标识;不是 Thread ID,也不是整个 Turn ID。
    payload: ToolPayload真正承载参数的内部枚举。具体工具还需要校验和解释其中的数据。
    encrypted_function_args: Option<Vec<String>>此快照还支持可选的加密参数相关材料;普通明文例子不展开该支路,也不能把它理解成一定有密钥。

    具体输入,逐层拆开

    假想 GEODYNA 工具的内部示意,不是现有公开接口或可执行请求。

    工具定义:read_project_summary(只读,假想名称)
    
    第一次调用:
      tool_name = read_project_summary
      call_id = C1
      payload = Function { arguments: "{\"projectId\":\"P1\"}" }
    
    工具结果:
      call_id = C1
      output = 当前项目摘要/结构化错误

    arguments 在这个示意的 Function 载荷里是一段 JSON 字符串;字符串中写了合法 JSON,不等于 projectId 存在,也不等于业务操作合法。语法校验与领域校验需要分开。

    Router 负责组装,不是直接修改工程

    2. 从 ToolCall 组装 ToolInvocation

    真实源码 · codex-rs/core/src/tools/router.rs:358–381

    代码较长时可左右滑动;下方按语句和术语拆解。

            let ToolCall {
                tool_name,
                call_id,
                payload,
                ..
            } = call;
    
            // Keep the legacy ToolInvocation.turn field tied to the same request state until handlers migrate.
            let turn = Arc::clone(&step_context.turn);
            let invocation = ToolInvocation {
                session,
                turn,
                step_context,
                cancellation_token,
                tracker,
                call_id,
                tool_name,
                source,
                payload,
            };
    
            self.registry
                .dispatch_any_with_terminal_outcome(invocation, terminal_outcome_reached)
                .await
    逐句/逐词这段代码实际做了什么
    let ToolCall { tool_name, call_id, payload, .. }解构取出当前需要的字段;两个点忽略没有在这里单独绑定的剩余字段,不是把原始调用随意删坏。
    Arc::clone(&step_context.turn)共享这一模型步骤所对应的 Turn 上下文,避免工具执行时换成另一个请求视图。
    ToolInvocation { session, turn, step_context, ... }在模型调用数据外,补上 Core 内部执行需要的上下文、取消信号、差异追踪与调用来源。
    self.registry.dispatch_any_with_terminal_outcome(...).await向注册表委托分派,并等待输出。实际工具逻辑不写在这个 Router 组装片段中。

    3. 找不到工具,返回明确错误

    真实源码 · codex-rs/core/src/tools/registry.rs:515–537

    代码较长时可左右滑动;下方按语句和术语拆解。

            let dispatch_trace = ToolDispatchTrace::start(&invocation);
            let tool = match self.tool(&tool_name) {
                Some(tool) => tool,
                None => {
                    let message = unsupported_tool_call_message(&invocation.payload, &tool_name);
                    let log_payload = tool_log_payload(&invocation.payload, &invocation.source);
                    let mut tool_result_tags = Vec::with_capacity(2);
                    sandbox_tags.append_metric_tags(&mut tool_result_tags);
                    otel.tool_result_with_tags(
                        &tool_name,
                        &call_id_owned,
                        log_payload.as_ref(),
                        Duration::ZERO,
                        /*success*/ false,
                        &message,
                        &tool_result_tags,
                        /*extra_trace_fields*/ &[],
                    );
                    let err = FunctionCallError::RespondToModel(message);
                    dispatch_trace.record_failed(&err);
                    return Err(err);
                }
            };
    逐句/逐词这段代码实际做了什么
    match self.tool(&tool_name)用工具身份查找当前可用实现,不按模型口头描述临时发明函数。
    Some(tool)找到实现,继续后续检查和执行。
    None没有匹配实现。该分支记录失败信息,然后返回错误,不继续假装执行成功。
    FunctionCallError::RespondToModel(message)这类错误可以作为反馈交回模型,让它知道调用不可用;它不同于整轮致命错误。
    Duration::ZERO / success false此处没进入工具执行,所以用零执行时长及失败标识记录这次分派结果。

    边界提醒:后面还会检查载荷种类、运行 hooks 等。仅在注册表找到名称,不等于业务参数已经全部合法。

    并行不是模型说一句“同时做”就无条件成立

    这个快照的 ToolCallRuntime 会查询工具的 supports_parallel 标记。允许并行的调用通过共享读锁进入,不允许并行的调用取独占写锁。注意:这里的读写锁是执行协调门,不等同于判断该工具在业务上是读操作还是写操作。

    run_turn 中的 Prompt 允许并行工具调用,也不代表所有调用都能安全并发。模型提议、工具元数据、运行时控制与业务事务是不同层。两个修改同一工程对象的动作,还需要正式业务边界保证一致性。

    执行结果下一步应该怎样理解
    成功结果关联 call_id 后回填,模型据此继续解释或规划。
    可反馈的工具失败作为工具反馈告诉模型实际错误;不伪造成功,也不必一律立即终止整个 Turn。
    致命错误或取消走相应终止/取消路径;不能把所有错误都包装成“可以继续重试”。
    工具输出很大结果还要受历史与上下文处理约束;第 9 站再讨论如何避免把所有数据塞进模型。

    4. 工具是否支持并行,由注册信息查询

    真实源码 · codex-rs/core/src/tools/router.rs:235–243

    代码较长时可左右滑动;下方按语句和术语拆解。

        pub fn tool_supports_parallel(&self, call: &ToolCall) -> bool {
            self.registry
                .supports_parallel_tool_calls(&call.tool_name)
                .unwrap_or(false)
        }
    
        pub(crate) fn tool_runtime(&self, tool_name: &ToolName) -> Option<Arc<dyn CoreToolRuntime>> {
            self.registry.tool(tool_name)
        }
    逐句/逐词这段代码实际做了什么
    tool_supports_parallel(&self, call: &ToolCall)根据这次调用的工具身份查询并行能力,而不是把调用参数当并行许可证。
    supports_parallel_tool_calls(&call.tool_name)向 Registry 查询工具元数据。
    unwrap_or(false)如果查询没有结果,默认不并行;这是 Option 的缺省值处理。
    tool_runtime(...) -> Option<Arc<dyn CoreToolRuntime>>可能找到共享运行实现,也可能没有;dyn 表示通过接口使用不同的具体实现。

    把同一个场景换一种条件

    假设模型已经提出一次工具调用,接下来是否真的进入了业务实现?

    仅为本地教学演示,不调用模型或 GEODYNA,不执行任何真实操作。

    先预测会走哪条分支,再点击按钮查看。

    最容易说错的边界

    常见说法准确表述
    给模型写一个工具说明就实现了工具还需要注册可调用实现,并接到真实执行边界。
    call_id 就是 Turn ID它标识一次调用,用于关联该调用及其结果。
    JSON 能解析就可以执行还需要目标、范围、权限、版本和业务不变量校验。
    任何工具报错都必定结束整个 Turn错误类型与当前控制流程决定是否反馈、继续或终止,不能一概而论。

    迁移到你的 GEODYNA 智能体

    以下是设计练习,不代表并行产品线已经实现或通过验收;本次只制作课程,不修改 GEODAMNEW。

    GEODYNA 的写操作应由适配器调用正式 Command API,并复用现有确认、Undo/Redo 和审计边界。课程没有新增这类工具,也没有修改软件源码。

    候选工具先从小而清晰的能力开始:读当前算例摘要、查询校验问题、获取某个结果指标。真正需要写入时,再设计明确目标和参数,而不是向模型开放一个可以随意改全局状态的大洞。

    你要设计的点可验证的证据
    工具契约写清名称、用途、输入、输出、可恢复错误和是否有副作用。
    调用关联同一工具两次调用也能分别找到参数与结果,不把 C1 的结果贴到 C2。
    写入边界正式命令接口负责业务校验和事务;工具适配器不直接篡改 UI 状态。
    评测用例不存在对象、过期版本、权限不足、重复调用和正常路径都要有结果。

    产品经理练习:设计一个只读工具的输入/输出,再列出 3 种失败;工具名可以自拟,但必须标注为设计草案。

    先答小测,再看解析

    每题即时反馈,可反复尝试;答对这些题也不会替代你的源码复述。

    1. 工具说明 ToolSpec 和工具执行实现是什么关系?

    2. 同一工具调用两次,靠哪个字段关联各自结果?

    3. Router 的组装片段有没有直接执行 GEODYNA 写入?

    4. 并行能力查询没有值时,unwrap_or(false) 返回什么?

    5. 工具参数是合法 JSON,但目标对象不存在,如何处理?

    最后一句话交作业

    请用“定义 → 调用 → 运行时 → 路由/注册表 → 实现 → 结果”的顺序,解释模型为什么不是实际执行者;再说出 call_id 的用途。

    展开参考答案(先自己说一遍)

    模型看到工具定义并产生具体调用,Core 运行时安排它,Router 组装执行上下文,Registry 找到实现,实际实现完成检查和动作并返回事实。call_id 关联这一次调用与结果,同一个工具名称可以对应多次不同调用。

    下一轮再回来时:第二轮追 ToolPayload 与 FunctionCallOutput 的数据转换;第四轮再深入不同工具、并发、取消与重试。