进程级外部 Toolset Preset 注册表

Grok Build · 工具配置进程级外部 Toolset Preset 注册表 config.rs 允许 crate 外的扩展代码在当前进程内注册按名称解析的工具集构建函数，并用 Public 与 Internal 控制是否进入公开枚举。一句话速览理解构建函数、Public 与 Internal 可见性，以及晚注册对后续解析的影响

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

核心视觉 · 教学化结构图

TOOLSET_PRESETS OnceLock<Mutex<HashMap<...>>> name → (builder, visibility) builder: fn() → ToolServerConfig Public 可枚举，也可按名解析 Internal 仅按名解析，不公开枚举 registered_toolset_preset(name) 取出函数并立即构建新配置

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

三个必须分清的事实

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。代码块保留所展示字段、函数与字符串的源码原文。

课堂练习

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

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