进程级外部 Toolset Preset 注册表
理解构建函数、Public 与 Internal 可见性，以及晚注册对后续解析的影响
本页解决的问题
先给结论「进程级外部 Toolset Preset 注册表」要解决的关键问题是什么？
理解构建函数、Public 与 Internal 可见性，以及晚注册对后续解析的影响
让这个结论先证明自己值得留下。 把这一页当成决策工具，而不是需要背下来的定义。把概念连到一个真实任务、一个可观察结果，以及一个能改变你判断的失败上。
写下一个问题：试完这个方法后，你能用什么证据回答它？
结论听起来很完整，却没有检查最关键的假设。
Builder 是函数指针ToolsetPresetBuilder = fn() -> ToolServerConfig。注册表保存构建函数，查询时调用函数生成配置。
Visibility 只管枚举Public 会进入 preset_names 与公开 preset 集合。Internal 不进入公开枚举，但仍能被 toolset_for_preset 按名称解析。
Registry 属于进程OnceLock 与 Mutex 包住全局 HashMap，生命周期覆盖当前进程，并支持受锁保护的读写。
随后注册的新 preset 不会回写到配置 A。现有 ToolServerConfig 保持原样。
后续调用会重新查询全局 registry，因此能看到晚注册的 preset。源码注释仍要求尽量在第一次解析前完成注册，以保证启动行为一致。
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() 中。再说明：若会话配置已经解析，注册后该会话是否自动变化。
「核心视觉 · 教学化结构图」为什么要看操作
「ToolsetPresetBuilder = fn() -> ToolServerConfig 。注册表保存构建函数，查询时调用函数生成配置」把结构落到了一个具体动作。这里真正要比较的不是名词谁更高级，而是数据如何被放置，以及最常发生的操作需要走多远。
读懂结构，要同时看访问方式和变化方式
「Public 会进入 preset_names 与公开 preset 集合。Internal 不进入公开枚举，但仍能被 toolset_for_preset 按名称解析」揭示了一个容易被忽略的取舍：按位置读取、按键查找、从两端进出、插入新元素和遍历关系，适合的组织方式并不相同。一个结构在某个操作上很快，不代表它在所有操作上都快。
把规模和更新频率一起算进去
实践时可以把「写出应调用的注册函数、builder 的完整类型，以及它能否出现在 preset_names() 中。再说明：若会话配置已经解析，注册后该会话是否自动变化」当作边界提醒：先写下数据量、最常用的操作和允许的延迟，再看 AI 给出的结构是否真的匹配。
从「核心视觉 · 教学化结构图」走到「三个必须分清的事实」
「核心视觉 · 教学化结构图」先把问题落在「注册 API register_toolset_preset register_internal_toolset_preset TOOLSET_PRESETS OnceLock >> name → (builder, visibility) builder: fn() → ToolServerConfig Public 可枚举，也可按名解析 Internal 仅按名解析，不公开枚举…」上；到了「三个必须分清的事实」，讨论继续推进到「ToolsetPresetBuilder = fn() -> ToolServerConfig 。注册表保存构建函数，查询时调用函数生成配置」。两段连起来，重点就不只是记住一个结论，而是看清它成立所依赖的条件。
把这条判断带到下一个场景
遇到一个新的数据结构时，不要从定义开始背。先写出最频繁的操作，再估计数据量和更新方式，最后检查结构是否让这三个条件同时成立。
- 「核心视觉 · 教学化结构图」：注册 API register_toolset_preset register_internal_toolset_preset TOOLSET_PRESETS OnceLock >> name → (builder, visibility) builder: fn() → ToolServerConfig Public 可枚举，也可按名解析 Internal 仅按名解析，不公开枚举…
- 「三个必须分清的事实」：ToolsetPresetBuilder = fn() -> ToolServerConfig 。注册表保存构建函数，查询时调用函数生成配置
- 「最后的要点」：后续调用会重新查询全局 registry，因此能看到晚注册的 preset。源码注释仍要求尽量在第一次解析前完成注册，以保证启动行为一致
最后的「最后的要点」把讨论落到「后续调用会重新查询全局 registry，因此能看到晚注册的 preset。源码注释仍要求尽量在第一次解析前完成注册，以保证启动行为一致」。回看这条线索时，最值得保留的是：当输入、规模或风险改变，哪些判断需要重新做一遍。
我把这篇文章里的一个判断改写成了今天可以验证的小实验。比记住结论更有用的是，知道下一步要观察什么。
读完以后我先回头找它成立的条件，而不是直接把方法搬进项目。这个顺序让后面的取舍清楚很多。
如果把这个判断放到真实工作里，最先需要补的约束是什么？我想知道从阅读到第一次实践之间，哪一步最值得先做。
还没有这篇文章的讨论。