CodeSmith语法门：写盘前的最后一道防线

在AI编程助手日益普及的今天，模型生成的代码语法错误仍然是最常见的“翻车”场景——少一个括号、行被截断、两个文件内容粘连。CodeSmith v0.5.0 通过引入“语法门”（Syntax Gate）机制，在代码写入磁盘前进行拦截，确保好文件不会被写坏。本文深入解析其设计哲学与实现细节。

为什么需要写盘前的语法检查？

CodeSmith 引擎原本已有三道事后防线：LSP 诊断在编辑后注入编译错误、回合结束时的声明验证器重放测试命令、以及 run_tests 让模型自行运行测试。但这些机制都有一个共同缺陷：它们都是事后防御。当警报响起时，损坏的文件早已落盘——side-git 快照多了一块垃圾、代码索引可能已吞下错误内容、模型下一轮补丁还会基于断裂的语法进行锚定。

语法门将检查点提前到了磁盘写入之前，成为“引擎阻断”原则的新实例。其核心模块仅 455 行，却统一了四个写盘工具（write_file、edit_file、apply_patch、fim_edit）的准入逻辑。

回归式门禁：只判断变化，不判断状态

语法门的契约非常明确：仅当文件在编辑前解析成功、而新内容解析失败时，才拒绝写入。原本就损坏的文件、以及尚不存在的新文件，永远不会被此门锁死。

核心逻辑不到 30 行（parse_gate.rs:47-75）：

pub fn gate(path: &Path, old: Option<&str>, new: &str) -> Result<GateOutcome, ToolError> {
    let Some(lang) = gated_language(path) else {
        return Ok(pass_through(new)); // 非门禁格式：直接放行
    };
    let old_was_valid = old.is_some_and(|old| check(lang, old).is_ok());
    if old_was_valid && let Err(failure) = check(lang, new) {
        return Err(reject(path, lang, new, failure)); // 好变坏：拒绝
    }
    // 通过后：rustfmt 重新规范化（见下文）
}

用大白话说：门禁只比较一个布尔值的变化——可解析性。好变坏，阻断；坏变更坏，放行；从无到有，放行。

为什么允许“坏变更坏”？反过来想就明白了：如果门禁判断的是状态——拒绝所有解析失败的写入——那么已经损坏的工作区将永远无法修复。廉价模型必须能修复破损的工作区，这是它的本职工作。一个锁死修复路径的门禁，比没有门禁更糟糕。

测试固化了这一边界：already_broken_rust_is_never_locked（已损坏文件写得更坏仍通过）、new_file_creation_is_allowed（新文件内容一出生就是坏的也通过）、cargo_lock_is_exempt（Cargo.lock 直接放行）、ungated_extensions_pass_through（管辖范围外的格式照常通行）。

目前只有三种格式受门禁管辖（parse_gate.rs:107-111）：Rust 通过 syn::parse_file，TOML 和 JSON 使用各自的标准解析器。Cargo.lock 被明确豁免——机器生成、体积庞大、无人手动编辑。

LSP（Language Server Protocol） 是一套由微软主导的开放协议，用于让编辑器或 IDE 与语言服务器之间通信，从而获得补全、跳转定义、诊断等能力。在 AI 编程助手的场景里，LSP 诊断常被用作“事后检查”手段：编辑器或工具在文件写入后通知语言服务器解析，语言服务器把编译错误、类型错误以诊断消息的形式回传。它的优势是语义级、覆盖完整类型检查；但缺点是异步且有延迟，错误到达时文件已经落盘，快照与索引可能已被污染。这正是语法门选择在写盘前用轻量解析器做同步拦截、而非依赖 LSP 事后告警的原因：两者互补，LSP 负责深度语义，语法门负责最后一道廉价的“可解析性”闸口。

side-git 快照 指的是工具在每次写入或每轮操作前后，用 Git 的底层对象模型对工作区做的一份轻量快照，用于回滚、差异对比或审计。与用户仓库的正式提交不同，这类快照通常不进入主分支历史，而是存放在独立引用或临时目录中，因此被称为 side-git。它的价值在于任何一次写坏的文件都能被追溯到上一个状态；但如果坏文件已经写入再快照，快照里就会多出一份垃圾对象，回滚时也可能把损坏内容带回来。语法门把检查提前到写盘前，正是为了让 side-git 快照只记录合法状态。

拒绝信的撰写规范

拦截时抛出的错误遵循既定规则：准确说明拒绝了什么、在哪断裂、原样贴回违规行、然后告诉模型下一步该做什么（parse_gate.rs:217-226）。

ToolError::execution_failed(format!(
    "Parse gate rejected write to {}: this file parsed as valid {} before the edit, \
     but the new content does not — line {}, column {}: {}\n{:>4}│ {}\n\
     The file was NOT modified. Fix the syntax error and send the edit again.",
    //......
));

拒绝信自带定位信息：行号、列号、违规行原文（超过 200 字符时在字符边界截断）。坐标转换有两个陷阱：proc-macro2 的 fallback span 只有在启用 span-locations 时才携带真实行列号；syn 行号从 1 开始但列号从 0 开始，输出前必须转换（parse_gate.rs:130-146）。serde_json 的错误尾部已带“at line L column C”，需要剥离避免位置重复声明（parse_gate.rs:172-178）。

测试 rust_regression_is_rejected_with_line_info 逐项断言：错误必须包含“valid Rust”、必须包含“line 2”、必须包含“NOT modified”。错误消息本身就是模型下一轮的输入——写得越精确，下一轮走的弯路越少。

proc-macro2 与 syn 是 Rust 生态中解析源代码的两个基础库。syn 提供把 Rust 源码解析为抽象语法树（AST）的能力，syn::parse_file 就是它的文件级入口；proc-macro2 则是过程宏与编译器之间共享的 token 与 span 抽象。所谓 span，指的是每个语法节点在源码中的位置信息，包括文件、行、列。但 proc-macro2 有一个重要细节：默认构建下 span 只保留“是否存在”，不携带真实行列号；只有启用 span-locations feature 后，fallback span 才会记录具体位置。这直接决定了语法门能否在拒绝信里给出准确的行列坐标——没有这个 feature，错误定位就只能退化为笼统的提示。此外，syn 报告的行号从 1 开始、列号从 0 开始，与用户习惯的“行列都从 1 开始”不一致，输出前必须做一次列号加一转换，否则模型按错误消息定位会偏移一列。

rustfmt 重新规范化：为下一个锚点服务

门禁通过后还有一个附加动作：如果这是 Rust 文件且编辑前是 rustfmt 干净的，待写入内容会先经过 rustfmt --edition 2024（parse_gate.rs:257-283）。

动机藏在一句注释里：保持后续补丁锚点稳定。edit_file 的锚定模式要求模型提供的补丁在文件中找到锚点；每次格式漂移，锚点的匹配面都会改变。编辑前干净的文件，编辑后也规范地输出，锚点坐标系不会移动。

这段实现的防御密度全篇最高：rustfmt 二进制每个进程探测一次，探测本身限时 5 秒（挂起的 rustfmt --version 不得堵塞整个写入路径，parse_gate.rs:240-242）；格式化限时 10 秒；任何失败——二进制缺失、非零退出、超时、非 UTF-8 输出——都静默跳过规范化，将原始文本写入磁盘。

模块文档清晰划分了权限（parse_gate.rs:14-18）：门禁独自决定是否拒绝；rustfmt 只负责排版，没有阻断权。 它也不隐瞒规范化改变了内容——工具结果携带披露说明，告知模型“你写的内容已被重新格式化”。

测试同样整洁：rustfmt_normalizes_only_clean_files 断言编辑前就乱糟糟的文件保持模型给出的布局；missing_rustfmt_disables_normalization 断言没有 rustfmt 时规范化完全退场。

还有一个细节值得记录：syn 将空文件视为有效（无条目 Rust 文件），因此将文件截断为空字符串是允许的——门禁阻断的是破损语法，而不是清空代码库（empty_rust_is_valid_and_passes）。

apply_patch 与 fim_edit 的锚定机制 值得单独说明。apply_patch 要求模型给出“上下文行 + 删除行 + 新增行”的补丁，工具需要在目标文件中找到上下文行作为锚点才能应用；fim_edit 则是 fill-in-the-middle 式编辑，模型给出前缀与后缀，工具在文件中定位这对边界。两者的共同点是：定位依赖文件当前的确切文本。只要文件被重新格式化，空格、换行、括号位置都会变化，原本能匹配的锚点就可能失配，模型不得不重新读取文件、重新构造补丁。因此“编辑前干净、编辑后也干净”的约定，本质上是在维持一个稳定的文本坐标系。这也解释了为什么规范化只对编辑前 rustfmt 干净的文件生效：一个本来就乱的文件，强行格式化反而会制造大规模文本漂移，让锚点全部失效。

总结：门内与门外

将机制串成一条线：

1. 四个写盘工具（write_file / edit_file / apply_patch / fim_edit）在内容落盘前共享同一道门禁；
2. 门禁只看三种格式（Rust/TOML/JSON）的可解析性变化：好变坏拒绝，其余放行；
3. 拒绝信携带行号、列号、原始行；文件保持原样，模型被要求修复语法后重发；
4. 通过后，编辑前干净的 Rust 文件由 rustfmt 重新规范化，为后续补丁保留锚点；
5. 规范化任何失败都静默退让——门禁独自握有拒绝权。

三个特性及其代价：

• 回归式：破损工作区永远可修复——代价是三种格式之外的世界（Python、TS 等）裸奔，在门禁管辖之外；
• 门在盘前：破损内容永不落盘、永不进入快照——代价是每次写入多一次解析，大文件的解析成本进入写入路径（所幸 syn 们很快）；
• 门禁与排版分权：拒绝权与规范化权分离——代价是 rustfmt 的布局可能与模型预期不同，需要披露说明来维持信任。

语法门抓住的是模型的笨拙。但工具结果和文件内容里还藏着别的东西——他人精心埋下的恶意。那不再是扶手能解决的问题，那是城墙的问题。