拆解CodeSmith工具内部机制：AI工具如何约束模型行为

当工具描述变成模型的"家规"

大多数开发者写工具描述时，关注的是"这个工具做什么"。但CodeSmith的做法揭示了一个截然不同的思路：工具描述首先是写给模型看的,"什么时候用我、什么时候别用别的"远比"我能做什么"重要。

在crates/tui/src/tools/file.rs:32中,read_file的描述是这样写的:

Read a UTF-8 file from the workspace. Use this instead of cat, head, tail, or sed -n '..p' in exec_shell — it's faster, sandbox-aware, and skips the approval prompt.

这段文字值得细读。"用我,别用cat/head/tail/sed"——整个仓库的工具描述里散落着十条这类"Use this instead of ..."的反模式清单。write_file劝阻heredoc,edit_file劝阻sed -i,fetch_url劝阻curl,grep_files劝阻grep -r。

CodeSmith工具内部机制

这些句子不是为人写的文档,而是写给模型的内部规则。模型对shell有天然的偏好(cat和curl在其训练数据中无处不在),而shell恰恰是最昂贵、最危险、最难审批的路径。把"别用那个,用这个"写进工具描述,是成本最低的行为塑造手段——说明书和工具目录一起,在每次请求时都摆在模型眼前。

这套家规在三个层面生效:说明书教导、错误信息纠正、引擎拦截。

说明书如何教导模型

除了反模式清单,八个高频工具还在描述末尾附加了调用示例。read_file的描述以一段静态字符串收尾:

Examples: {"path": "src/main.rs"} (first 200 lines); 
{"path": "src/big.rs", "start_line": 201, "max_lines": 200}

这些示例是字节稳定的静态文本——没有时间戳、没有请求ID——所有前缀缓存不受影响。而一个照抄示例参数形状的模型,直接跳过了一整轮"参数错误→报错→重新调用"的弯路。

这种对示例的投入有实验支撑:给工具描述附上1-5个真实调用示例,某些基准上的工具调用准确率从约72%攀升至90%。JSON Schema能表达类型,但无法传达"时间戳是秒还是毫秒""过滤条件如何嵌套"这类隐式约定,示例是传递它们最直接的方式。

比示例更根本的是描述的取向:"何时使用"比"能做什么"更重要。"搜索相关内容"远不如"当需要实时信息或查找未知事实时使用"——前者描述功能,后者帮助模型做调用决策。而清晰的边界反例(开头那十条"Use this instead of"),往往比能力清单更重要,因为大多数失败调用的根源不是模型不知道工具能做什么,而是不知道它不能做什么。

伴随而来的是一条调试原则:当Agent持续选错工具时,先修描述,再怀疑模型。编辑一份描述的回报,远超升级一个更强的模型。

**前缀缓存(Prefix Caching)**是大模型推理中的一项成本优化技术:当多次请求共享相同的前缀(例如固定的系统提示、工具定义、说明书文本)时,服务端可以复用已经计算过的键值(KV)缓存,只对变化的后缀重新计算。这能显著降低延迟和 token 成本。之所以强调工具描述中的示例必须是"字节稳定的静态文本",正是因为任何细微变化——多一个时间戳、插入一个请求ID——都会让整个前缀的缓存命中失效,导致每次都按全新前缀付费。因此凡是拼进工具描述的内容,都应视为缓存键的一部分,保持其字面恒定。

文件读取:一次一页的兼容性设计

read_file的分页常量设计得相当克制:默认200行,硬上限500行,可见字节16KB。小文件(≤200行且≤16KB,无显式范围)走快速路径原样返回,不做包装——注释明确说这是为了保持历史行为,避免已有会话突然看到新的包装格式。

大文件输出的行号格式是{line_no:>6}│ {line},六列右对齐加一个全角竖线,相当于现代化的cat -n。

两个设计细节值得关注。翻页超过末尾不算错误:start_line超出总行数时返回[NO CONTENT]哨兵而非抛错——如果翻过了最后一页,告诉它书读完了,别惩罚它。

截断通知直接交出下次调用的参数:To continue, call read_file with path="..." start_line=N max_lines=M——模型照抄即可继续读,不需要心算行号。

文件编辑:精确匹配的工程学

edit_file是精确匹配替换的教科书案例。验证链层层堆叠:search == replace直接拒绝;replace_all和occurrence互斥;occurrence必须是基于1的正整数。

然后是最核心的规则——多个匹配即失败,而失败信息本身就是指令:

Search string matched {count} locations in {path}; pass replace_all=true to replace every occurrence, or occurrence=N (1..={count}) to replace a specific one

它告诉模型匹配了多少处、两条出路、N的合法范围。收到这个错误的模型,下一次调用天然就会做对。好的错误信息不是状态汇报,而是下一步的施工蓝图。

三层模糊回退策略

精确匹配失败后,三级模糊回退启动,每一级都针对真实的失败模式:

第一级容忍受前导空白:即使缩进对不齐(肉眼看着一样的空格和制表符),仍能定位,并用字节映射表将归一化位置映射回原始span。

第二级归一化排版标点:弯引号→直引号,破折号→--,不换行空格→普通空格——注释直言这是为了接住"浏览器/聊天客户端悄悄替换标点"的粘贴失败。模型从网页复制代码片段时,标点早已被污染。

第三级剥离行号前缀:模型把read_file输出中的{n:>6}│行号原样复制进了old_string——回退链在匹配前剥离前缀,同时识别自己的格式以及cat -n/grep -n变体。

护栏是双层的:多行文本要求每行都带前缀且行号严格递增;单行文本则启用行号对齐检查——剥离后的文本必须恰好落在第一个行号所指的那一行。

说个细节,两级模糊回退和行号匹配器的扫描游标都按"跳过整个匹配"前进,绝不用"+1字节"——多字节首字符永远不可能把下一次切割切进字符中间,这正是CJK回归测试守护的边界。

一个行业教训

模糊回退的存在有一个值得引以为戒的行业故事。某版本的Cursor在参数传递层悄悄把中文弯引号转成了英文直引号:读取工具原样返回弯引号,而替换工具的参数在入口处被悄悄拉直——于是"我明明看到的内容,工具说找不到",模型重试失败、再重试再失败,无从诊断。

这违反的是一条工具设计的底线:模型感知的世界和工具操作的世界之间不能存在系统性偏差。归一化可以,但必须写进描述、在返回中声明;否则"聪明的纠正"就制造了一种模型无法自诊断的系统性故障。

CodeSmith的归一化走的是正道:不改参数、不改文件,只在匹配时容忍——用弯引号写的搜索可以命中直引号写的原文,而文件本身一个字节都不动。

TOCTOU 是 Time-of-Check to Time-of-Use 的缩写,指"检查时"与"使用时"之间存在时间窗口、状态可能已被改变的一类竞态漏洞。在网络安全中,攻击者常在"检查"阶段让系统看到一个安全的值,而在"使用"阶段让实际值被翻转。DNS 重绑定正是 TOCTOU 的典型:域名第一次解析返回公网安全 IP(通过验证),连接建立前攻击者修改 DNS 使其指向内网地址(实际连接)。防御手段因此不能只做一次性校验,而要把"校验过的 IP"钉扎(pin)进连接器,使连接目标与验证目标一致。

文件编辑的五种方案与权衡

把镜头拉远,文件编辑的设计空间共有五种方案,各有胜负:

Diff描述 + Apply Model:生成diff交给专用小模型合并——Cursor的旧路线。分工漂亮,但描述与原文不一致时合并步骤会打错位置,基础模型变强后这条路线被放弃。

旧字符串→新字符串:Claude Code、Codex和今天的Cursor的共同选择——可预测、透明。代价是删除大段内容需要逐字引用原文,一个字符的漂移就导致匹配失败。

行号定位:"删除X到Y行"——精确且省token,但每次编辑都会重编号后面的一切;一次思考输出多处编辑时,它们必须都用初始行号,模型容易混淆。

类Vim命令:适合重构代码,但命令语法的学习负担对弱模型是灾难。更深一层,Vim是为"看着小步改"的人类设计的,而模型的工作方式是"想长久,改大块"。

首尾锚点匹配:只引用头几行和尾几行,省略中间——edit_file的search_start + search_end正是这一方案的落地,结合了内容匹配的可靠性和行号方案的token节省。

五种方案面对同一场考试:在人类语言的模糊和机器执行的精确之间,接口究竟在哪里下刀?

搜索工具:先数全,再截断

搜索工具在截断策略上共享一个温和的设计。grep_files上限100条结果,但返回结构中带有"truncated": total_matches > max_results——先数全所有匹配,再截断显示。"共347处命中,这里是前100条"和"这里有100处命中",对模型是两个完全不同的决策依据。

排除目录列表写成双重保险(每个目录两种拼法都列出):node_modules、.git、target、*.min.js、dist、build、__pycache__、.venv。超过10MB的文件直接跳过。

搜索工具的品类本身有四种:

正则内容匹配(grep/ripgrep)——知道要找的字面文本时最快最准
文件名模式(glob)——探索项目结构的第一步
语义搜索——代码"意思相近但措辞不同"时使用
符号级查找——IDE式的"跳转定义/查找引用",纯文本搜索无法区分

是否构建语义搜索的嵌入索引曾在业界引发路线之争:Claude Code等终端Agent刻意拒绝,纯grep+glob现场检索,没有索引需要随代码演化保持新鲜,省下整套索引基础设施;Cursor早期走了相反路线,后来也退回了grep+glob。

CodeSmith站在无索引一边——模型的搜索工具面精确地就是grep + glob。

网络策略:三态配置与拒绝优先

网络是另一个国度。策略配置有三态:Allow | Deny | Prompt,其中两个设计决策直接写进了注释。

配置写错不等于隐式允许:未知值全部回退到Prompt——"一个拼写错误绝不能悄悄关闭一条安全策略"。Deny拥有一票否决权:同时匹配allow和deny的主机按deny处理。

域名匹配有一个反直觉的细节:.example.com匹配任意子域名但不匹配裸域——两者都要就都列出。

默认值站在安全一侧:缺少[network]配置段时,配置加载返回default = "prompt"的决定器——网络工具首次触碰未批准主机时,弹出的是标准的内联审批,绝不是静默放行。

Prompt的语义获得了新生。旧实现把Prompt转成permission_denied,错误还指导用户"用/network allow <host>后重跑"——但那是死胡同:照做、写完配置,活着的引擎仍然从不刷新策略快照,重试照样失败。新映射把"询问"交给分发时的内联审批门。

SSRF(Server-Side Request Forgery,服务端请求伪造)指攻击者诱导服务端程序向非预期地址发起请求,常用于探测内网、访问云元数据服务或绕过防火墙。在 Agent 工具场景中,模型受诱导或不慎构造出的 fetch_url 目标,可能指向 127.0.0.1、内网 RFC1918 地址或云厂商的元数据端点(如 169.254.169.254),从而泄露敏感配置或凭证。这就是为何 fetch_url 需要协议白名单、受限 IP 表、DNS 钉扎与逐跳重定向重检等一系列门禁协同工作——单靠"禁用 localhost"不足以覆盖全部攻击面。

fetch_url:一个URL的七道门

fetch_url把SSRF防御做成了一条流水线,按执行顺序:

协议白名单:只认http/https,file:///etc/passwd有专门的测试用例
策略评估:过上面的三态表
localhost主机名拒绝
字面IP检查:含方括号IPv6
受限IP表:环回、RFC1918私网、链路本地、组播、CGNAT、云元数据169.254.169.254、IETF基准范围、E类地址
逐IP DNS验证+钉扎:每个解析地址过受限表,然后把第一个合法IP钉进连接器——这防的是"DNS重绑定(TOCTOU)":验证时域名解析到安全IP,连接时重新解析却可能被翻转向内
逐跳重定向重检:手动跟随重定向(上限5跳),每一跳重走所有门——安全的第一跳不保证安全的第三跳

另一个行为细节:4xx/5xx不算工具错误——返回body和success: false。API的错误响应体通常是一大块JSON,本身就是诊断线索,扔掉可惜。

家规的三层防线

把家规收拢成三层。说明书教导:十条"Use this instead of"把模型从shell拉回结构化工具,从源头节省审批、上下文和风险。错误信息纠正:多匹配错误携带参数、hunk失败携带预览、网络阻断携带原因——每个错误都是下一步的施工蓝图。引擎拦截:分页上限、先数后截、三段路径检查、SSRF七道门、DNS钉扎——模型想犯错都难。

本文拆解的家规防范的是模型的笨拙:颤抖的手、对shell的偏爱、多翻了一页。但上下文里还混入了另一种东西——别人精心植入的恶意。网页里的一句"忽略前面的指令"、AGENTS.md中伪装成项目约定的命令:那是完全另一个量级的对手。

背景补充

**提示注入(Prompt Injection)**是指攻击者将恶意指令隐藏在模型会读取的内容中——网页正文、文件、工具返回值,甚至伪装成项目配置的 AGENTS.md 文本——诱导模型偏离原始任务、泄露信息或执行危险操作。它与本文所述"家规"防范的对象本质不同:家规应对的是模型自身的笨拙与偏好(误用 shell、翻页越界),属于可用描述和校验修正的工程问题;而提示注入是外部对手精心设计的对抗性输入,需要的是信任边界划分、内容与指令的隔离、对工具结果作数据而非命令对待等安全机制。两者的防御思路不可混淆。