Grok Build · 工具配置

进程级外部 Toolset Preset 注册表

config.rs 允许 crate 外的扩展代码在当前进程内注册按名称解析的工具集构建函数，并用 Public 与 Internal 控制是否进入公开枚举。

课程目标读懂 registry 保存什么、Public 与 Internal 的边界，以及晚注册对「已解析配置」和「后续解析」的不同影响。

核心视觉 · 教学化结构图

教学化结构图：节点与连线用于解释源码关系，内容经过课程化整理。

三个必须分清的事实

Builder 是函数指针

ToolsetPresetBuilder = fn() -> ToolServerConfig。注册表保存构建函数，查询时调用函数生成配置。

Visibility 只管枚举

Public 会进入 preset_names 与公开 preset 集合。Internal 不进入公开枚举，但仍能被 toolset_for_preset 按名称解析。

Registry 属于进程

OnceLock 与 Mutex 包住全局 HashMap，生命周期覆盖当前进程，并支持受锁保护的读写。

注册时序的准确含义

配置 A 已经解析

随后注册的新 preset 不会回写到配置 A。现有 ToolServerConfig 保持原样。

配置 B 之后解析

后续调用会重新查询全局 registry，因此能看到晚注册的 preset。源码注释仍要求尽量在第一次解析前完成注册，以保证启动行为一致。

真实源码证据

crates/codegen/xai-grok-agent/src/config.rs第 38 至 81 行节选

pub type ToolsetPresetBuilder = fn() -> ToolServerConfig;

enum PresetVisibility {
    Public,
    Internal,
}

pub fn register_toolset_preset(name: &str, builder: ToolsetPresetBuilder) {
    toolset_preset_registry().lock().expect("toolset preset registry poisoned")
        .insert(name.to_string(), (builder, PresetVisibility::Public));
}

pub fn register_internal_toolset_preset(name: &str, builder: ToolsetPresetBuilder) {
    toolset_preset_registry().lock().expect("toolset preset registry poisoned")
        .insert(name.to_string(), (builder, PresetVisibility::Internal));
}

fn registered_toolset_preset(name: &str) -> Option<ToolServerConfig> {
    toolset_preset_registry().lock().expect("toolset preset registry poisoned")
        .get(name).map(|(f, _)| f())
}

源码快照说明：依据本地仓库 grok-build-main，核对文件 crates/codegen/xai-grok-agent/src/config.rs，核对日期 2026-07-17。代码块保留所展示字段、函数与字符串的源码原文。

课堂练习

设计一个仅供测试 harness 使用的 preset

写出应调用的注册函数、builder 的完整类型，以及它能否出现在 preset_names() 中。再说明：若会话配置已经解析，注册后该会话是否自动变化。

Takeaway：外部 preset registry 保存「名称到构建函数与可见性」的映射。Public 与 Internal 的核心差异是公开枚举范围。晚注册不会改变已解析配置，后续解析仍能查询到新条目。