Canonical input 是稳定投影

Grok Build · 跨工具归一化 Canonical input 是稳定投影不同 harness 可以使用不同原始参数名。Grok Build 把少量稳定语义投影到 x.ai/tool 元数据中，让展示、遥测和跨工具分析拥有共同词汇。一句话速览用 CanonicalToolMeta 和输入投影解释跨工具实现的稳定合约

课程目标记住八个 canonical fields、七个 CanonicalToolMeta 字段与 version = 1 ，并能解释 input 为何允许缺字段或整体省略。

核心视觉 · 教学化投影图

raw_input A file_path · old_string new_string · replace_all raw_input B path · offset · limit 其他 harness 字段

canonical projection

x.ai/tool · version 1 name · kind · namespace · label read_only input: { path, offset, limit } 仅保留稳定、轻量的交叉字段

教学化结构图：投影可能丢弃字段，完整原始输入仍由 raw_input 承载。

八个 canonical fields

path 文件或搜索路径 offset 归一化起始位置 limit 读取或结果上限 command 待执行命令 description 命令描述 cwd 工作目录词汇 directory 目录列表目标 pattern 搜索模式

元数据合约与省略规则

CanonicalToolMeta 的真实字段 version name kind namespace label read_only input version 是数字 1。 input 为可选 JSON value，没有稳定投影时会整体省略。

input 保持轻量它是 canonical projection，不能当作 raw input 镜像。grep flags、 replace_all 等非共享字段可能被丢弃；编辑前后文本与完整写入内容等大字段不会进入投影，可从 raw_input 获取。

公开行为对照： Claude Code 公开文档中的 Read 工具使用 file_path 、 offset 、 limit 。Grok Build 的归一化层将自身各工具输入映射到共同字段，例如 path 。此处只比较公开可见的工具输入命名，不推断 Claude Code 内部实现。

真实源码证据

crates/codegen/xai-grok-tools/src/tool_taxonomy.rs · 第 12 至 30、190 至 200 行

pub mod field {
 pub const PATH: &str = "path";
 pub const OFFSET: &str = "offset";
 pub const LIMIT: &str = "limit";
 pub const COMMAND: &str = "command";
 pub const DESCRIPTION: &str = "description";
 pub const CWD: &str = "cwd";
 pub const DIRECTORY: &str = "directory";
 pub const PATTERN: &str = "pattern";
}
pub const TOOL_META_VERSION: u32 = 1;

pub struct CanonicalToolMeta {
 pub version: u32,
 pub name: String,
 pub kind: ToolKind,
 pub namespace: ToolNamespace,
 pub label: Cow<'static, str>,
 pub read_only: bool,
 pub input: Option<serde_json::Value>,
}

源码快照说明：依据本地仓库 grok-build-main 的 xai-grok-tools/src/tool_taxonomy.rs 与 normalization.rs ，核对日期 2026-07-17。源码中不存在 content canonical field，旧页面中的虚构元数据字段与版本示例均已移除。

课堂练习

04 为一次编辑调用制作投影原始输入含 file_path 、 old_string 、 new_string 、 replace_all 。写出 canonical input ，再指出哪些字段应留在 raw_input 。

Takeaway： canonical 层追求跨 harness 的稳定公共语义。当前字段只有 path/offset/limit/command/description/cwd/directory/pattern ，元数据版本为数字 1。 input 可以省略敏感或体量大的字段。