Canonical input 是稳定投影
用 CanonicalToolMeta 和输入投影解释跨工具实现的稳定合约
本页解决的问题
先给结论「Canonical input 是稳定投影」要解决的关键问题是什么？
用 CanonicalToolMeta 和输入投影解释跨工具实现的稳定合约
让这个结论先证明自己值得留下。 把这一页当成决策工具，而不是需要背下来的定义。把概念连到一个真实任务、一个可观察结果，以及一个能改变你判断的失败上。
写下一个问题：试完这个方法后，你能用什么证据回答它？
结论听起来很完整，却没有检查最关键的假设。
CanonicalToolMeta 字段与 version = 1，并能解释 input 为何允许缺字段或整体省略。
path文件或搜索路径
offset归一化起始位置
limit读取或结果上限
command待执行命令
description命令描述
cwd工作目录词汇
directory目录列表目标
pattern搜索模式
CanonicalToolMeta 的真实字段
version 是数字 1。input 为可选 JSON value，没有稳定投影时会整体省略。
input 保持轻量
它是 canonical projection，不能当作 raw input 镜像。grep flags、replace_all 等非共享字段可能被丢弃；编辑前后文本与完整写入内容等大字段不会进入投影，可从 raw_input 获取。
file_path、offset、limit。Grok Build 的归一化层将自身各工具输入映射到共同字段，例如 path。此处只比较公开可见的工具输入命名，不推断 Claude Code 内部实现。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，旧页面中的虚构元数据字段与版本示例均已移除。为一次编辑调用制作投影
原始输入含 file_path、old_string、new_string、replace_all。写出 canonical input，再指出哪些字段应留在 raw_input。
path/offset/limit/command/description/cwd/directory/pattern，元数据版本为数字 1。input 可以省略敏感或体量大的字段。
「核心视觉 · 教学化投影图」的能力藏在每次交接里
「version 是数字 1。」说明，Agent 的表现不只由模型决定。模型、上下文、工具、状态、权限和人之间的每次交接，都会改变任务能否继续以及出了问题能否恢复。
先写清状态，再增加能力
从「它是 canonical projection，不能当作 raw input 镜像。grep flags、 replace_all 等非共享字段可能被丢弃；编辑前后文本与完整写入内容等大字段不会进入投影，可从 raw_input 获取」出发，可以把流程拆成起始状态、下一步动作、工具返回、状态更新和停止条件。这样调试时找的是第一处丢失信息或权限的位置，而不是笼统地说“模型变笨了”。
成功路径不能代表系统可靠
用「原始输入含 file_path 、 old_string 、 new_string 、 replace_all 。写出 canonical input ，再指出哪些字段应留在 raw_input」重放一次成功和一次失败，记录每一轮真正传入的上下文、工具结果和负责人；只要第二个人能复述这条链，系统才有可维护性。
从「核心视觉 · 教学化投影图」走到「八个 canonical fields」
「核心视觉 · 教学化投影图」先把问题落在「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, of…」上；到了「八个 canonical fields」，讨论继续推进到「path 文件或搜索路径 offset 归一化起始位置 limit 读取或结果上限 command 待执行命令 description 命令描述 cwd 工作目录词汇 directory 目录列表目标 pattern 搜索模式」。两段连起来，重点就不只是记住一个结论，而是看清它成立所依赖的条件。
把这条判断带到下一个场景
分析 Agent 时，沿着状态、动作、工具结果和下一步的顺序走一遍；每次交接都要能说明信息从哪里来、由谁确认、失败时停在哪里。
- 「核心视觉 · 教学化投影图」：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, of…
- 「八个 canonical fields」：path 文件或搜索路径 offset 归一化起始位置 limit 读取或结果上限 command 待执行命令 description 命令描述 cwd 工作目录词汇 directory 目录列表目标 pattern 搜索模式
- 「为一次编辑调用制作投影」：原始输入含 file_path 、 old_string 、 new_string 、 replace_all 。写出 canonical input ，再指出哪些字段应留在 raw_input
最后的「为一次编辑调用制作投影」把讨论落到「原始输入含 file_path 、 old_string 、 new_string 、 replace_all 。写出 canonical input ，再指出哪些字段应留在 raw_input」。回看这条线索时，最值得保留的是：当输入、规模或风险改变，哪些判断需要重新做一遍。
我把这篇文章里的一个判断改写成了今天可以验证的小实验。比记住结论更有用的是，知道下一步要观察什么。
读完以后我先回头找它成立的条件，而不是直接把方法搬进项目。这个顺序让后面的取舍清楚很多。
如果把这个判断放到真实工作里，最先需要补的约束是什么？我想知道从阅读到第一次实践之间，哪一步最值得先做。
还没有这篇文章的讨论。