一段三百行的 TypeScript 文件，在主流开源 AI 编程代理 OpenCode 的代码仓库中静静运行了不知多少个迭代周期。它的工作并不复杂——对每一次会话中模型发出的请求，做一次 substring 判定：如果模型名称字符串里包含 gpt- 三个字符，就把 edit 这个工具从模型可见列表中悄悄剔除；如果不包含，则保留全部 17 个内置工具中的 11 个默认开放给模型。这是隐藏在 packages/opencode/src/tool/registry.ts 第 300 行附近的过滤器，在官方文档里从未被披露。在用户能看到的说明里，edit 与 write 被并列描述为"模型修改代码的主要方式"，并各自占据独立的章节；然而任何用户，无论翻阅 README、配置文件范例、还是插件钩子列表，都无从得知这款号称支持 62 款模型的开源工具，对其中 20 款悄悄关闭了 edit 入口，且这 20 款无一例外，全部属于 GPT 家族。
当一项核心能力被 substring 这种最原始的字符匹配悄然分流，它揭示的就不仅是一处代码瑕疵，而是 AI Agent 时代软件供应链里那种"代码即契约、契约无文档"的结构性脆弱。开发者社区偶然翻出这段代码的过程，像极了 2015 年第三方研究机构在 Volkswagen 柴油车 ECU 中发现"基于参数识别受检场景"逻辑时的那一幕——一段埋在固件深处的判定，悄悄改写了数十万用户对系统行为的预期。区别只在于，这一次被改写的不是尾气排放，而是软件生产力本身。
工具与模型耦合的产业图景
理解这件事的关键，是先看清它所处的产业图景。2026 年的 AI 编程代理市场已经形成了一个"模型可选、工具统一"的默认范式：开发者在一个工具界面下，可以切换 OpenAI、Anthropic、Google、Meta、Mistral 等多家厂商的模型，而工具层的命令、钩子、权限、能力描述则保持稳定。这种范式之所以诱人，是因为它让开发者不必为每款模型重新学习工具用法；它之所以危险，是因为它把"不同模型之间是否存在能力差异"这一关键判断，完全推给了工具层去悄悄处理。
当工具层用结构化的 family 字段、能力等级、调用模式元数据去处理这种差异时，结果是清晰的；当工具层用 substring、startsWith、includes 这种"够用就行"的字符串函数去处理这种差异时，结果就埋下了隐患。在 OpenCode 这件事里，被默认 Claude 会话保留的 11 个工具包括 edit、write、bash、glob、grep、read、fetch、task、todowrite、websearch、question 等；GPT 家族模型则在 11 个基础上减少了 2 个、多出 1 个专属辅助工具，组成了一个总计 10 件工具的子集。这种差异不是"工具可能调用失败"，而是"工具根本不会被列出"——模型在系统提示中看不到这些工具，自然不会尝试调用；上层开发者也无法通过任何配置或 flag 让它重新可见。
这种"被隐藏的能力"比"显式禁用的能力"更危险：前者让模型在生成代码时绕道而行，间接降低编辑效率，用户却感知不到原因；后者至少会被用户和模型共同察觉，从而触发反馈和修正。隐式契约把异常处理的责任全部压在了"开发者主动翻源码"这一极低概率事件上，这正是产业图景中最值得警惕的角落。
被压缩的能力契约
软件工程中有一个朴素却常被忽视的原则：判断条件应该显式，而非隐式。当一段代码用 modelName.includes('gpt-') 来决定工具可见性，它事实上把"谁是 GPT 模型"这一语义判断转译成了"哪个字符串里碰巧有 gpt-“这一字符判断。在当前 62 款模型清单下，这种简化恰好与命名约定重合，因此没有出现误判——但这种"恰好”，正是隐式抽象最大的隐患。
把"能力差异"和"权限差异"画等号，是软件工程里典型的"用错误的抽象层级解决问题"。一个工具对某个模型不开放，应当是一个可声明、可配置、可追溯的决策，而非一段隐藏在 substring 里的副作用。这种抽象层级的错位，在 AI Agent 时代尤其危险，因为 Agent 的"能力"本身就是由"可用工具 + 模型推理 + 上下文"三者共同决定的。任何一个变量被悄悄改变，整个 Agent 的行为就会偏离开发者预期，而这种偏离在用户看来会呈现为"这个模型不顺手"，但真实的根因却远在模型之外。
我们不妨设想三种真实场景。场景一：一位资深后端工程师在本地用某款 GPT 模型跑 OpenCode 完成一项重构，他习惯了 Claude 模型下 edit 工具的精确补丁能力，但在 GPT 模型下他发现模型只能用 write 整体覆盖文件。他把这种"不顺手"归因于模型本身的差异，于是更换到 Claude 模型，并最终得出结论"Claude 更适合代码编辑"——他不会知道，这一判断在很大程度上是被 substring 过滤器的隐式偏向所塑造的。场景二：一家 SaaS 公司在 CI 流水线里集成 OpenCode，用于自动修复 lint 错误。其工程团队基于 edit 工具的语义编写了一套审计规则，记录每次 edit 调用的范围与 diff。如果流水线在某次任务中切换到 GPT 模型，整套审计规则会突然失效——因为 GPT 模型下根本没有 edit 工具可供触发，tool.execute.before 钩子也不会被调用，问题直到合规审查时才会浮现。场景三：一位独立开发者 fork 了 OpenCode，希望在其基础上接入一款新训练的代码模型。他翻遍文档、配置文件、命令行参数，发现找不到任何"工具可见性"的开关。他最终只能去翻源码，在 registry.ts 中找到了那段 substring，并在自己 fork 的版本里删掉了它——但他的修改从未回到上游，因为他不知道原作者的判定理由：是规避函数调用格式差异？出于某种商业压力？还是单纯的路径依赖？这三种场景共同指向同一个结论：在 AI Agent 时代，“代码即契约"必须升级为"代码即显式契约”。
字符串匹配的脆弱性
仅以 substring 作为判定依据，在工程上是不稳定的。可以设想这样几种场景：第一，OpenAI 在某个版本里把模型名从 gpt-5-turbo 改为 gpt5-turbo（去掉连字符），整个 substring 逻辑瞬间失效，GPT 模型一夜之间重新获得 edit 权限；第二，第三方模型聚合商在内部以 openai/gpt-5 这种带前缀的方式暴露模型，substring 仍可命中，但语义已经从"OpenAI 的 GPT"变成了"通过某聚合商路由的 GPT"，调用模式与限速策略可能完全不同；第三，开发者本地部署一个名为 my-finetuned-gpt-style 的微调模型，substring 同样会命中，导致这个本地模型意外失去 edit。
这三种情形都不是假想，而是 substring 抽象层级过低带来的真实风险。工程上更稳妥的做法，是引入模型族（family）字段、能力等级（capability tier）字段、调用模式（calling pattern）字段等结构化元数据，让判定条件从"字符串里碰巧有什么"升级为"元数据里明确声明了什么"。这种升级不仅仅是技术洁癖，而是 AI Agent 时代软件供应链的基本要求。
更进一步，当 substring 出现在插件钩子层，整条调用链的可观测性就被打破。OpenCode 的插件机制允许开发者监听每一次工具执行，但若插件作者仅监听 edit 工具，那么在 GPT 模型下，这个钩子可能从头到尾都不会被触发——而插件作者和上层用户都不会收到任何提示。这种"幽灵失效"对调试、对安全审计、对工作流编排都是一种系统性风险。当一次代码评审追问"为何审计日志中缺失 edit 调用记录"时，开发者面临的将不只是排查模型决策，而是要重新理解整个工具层在悄然改变其可见性。
与历史镜头的对照
把视野拉远一些，这件事并非软件史上第一次因为隐式判定而引发大规模争议。2015 年 Volkswagen 排放门曝光时，全球范围内的关注焦点，是大众集团在发动机 ECU 中嵌入的一段"基于参数识别受检场景"的判定逻辑：当方向盘转角、车速、发动机运行时间、大气压力等参数符合实验室台架测试的特征时，ECU 会激活完整的尾气处理系统，使 NOx 排放降至合规水平；一旦车辆驶入真实道路，相同的 ECU 又会自动切换到低排放控制模式，使 NOx 飙至法定上限的 5 倍乃至 40 倍。
大众事件与 OpenCode 事件在结构上具有惊人的相似性。其一，判定逻辑都隐藏在底层代码深处，用户手册、维修指南、合规审计中均无说明；其二，判定逻辑都基于一组"看似合理"的输入参数——大众看的是方向盘转角和车速，OpenCode 看的是模型名字符串；其三，判定逻辑都在不同场景下改变系统行为——大众在台架与真实道路之间切换，OpenCode 在 GPT 与非 GPT 之间切换。其四，事件的曝光都依赖于外部独立研究——大众由 ICCT 与西弗吉尼亚大学联合调查发现，OpenCode 由社区开发者偶然翻源码发现。
大众事件的最终制度回应，是车载诊断系统（OBD-II）的强制标准化、真实驾驶排放（RDE）测试的全球推行，以及对"基于参数识别受检场景"这一类设计模式的全面禁令。其核心原则是：让"何时进入哪种行为模式"必须可被外部观测，不可被内部隐式判定。AI Agent 行业今天面对的，恰恰是同一种"隐式行为模式切换"的雏形。
更近的例子来自消费电子。2017 年起，多家智能手机厂商被发现通过系统更新降低旧设备的处理器频率以"延长电池寿命"，但未向用户披露。事后多国监管机构推动的解决方案，是要求厂商在性能管理时显式声明、提供用户级开关、并保留可观测日志。苹果在 2018 年公开道歉并提供 29 美元电池更换折扣，三星、华为等厂商也相继引入"性能模式"开关。这一过程再次确认了"显式优于隐式"的工程伦理——而 OpenCode 的 substring 筛选器，正是这种工程伦理在 AI Agent 时代的一次迟到演练。
信息不对称与生态偏向
如果从经济学视角切入，这件事揭示的是一种隐蔽的市场偏向：当一款工具用 substring 决定 20 款模型的工具权限时，它事实上在用户层面制造了一个"模型可见工具集"的不对称，而这种不对称不会出现在任何用户能看到的界面上。
1970 年，George Akerlof 在《经济学季刊》上发表了"柠檬市场"理论，论证了当买卖双方存在产品质量信息不对称时，市场可能陷入低质品驱逐高质品的恶性循环。在 AI Agent 时代，开发者（即"买方"）看到的工具描述是完整的、统一的，而工具实际暴露给模型的清单却被框架悄悄裁剪——这种"信息不对称"不会立即导致劣币驱逐良币，但会让开发者无法准确评估"为什么 GPT 模型在这一项目上看起来总是不够顺手"，继而把原因归到模型本身，而不是工具链的隐性偏向。
更进一步，当 OpenCode 这类开源代理被嵌入企业 IT 体系，“工具是否真的可用"就成为合规评估的关键证据。一份代码修改记录显示"模型未触发 edit 工具”，合规审计方需要回溯的不仅有模型本身的决策日志，还应当包括工具层的可见性配置——而 substring 这样的隐式判定，几乎让这种回溯不可能完成。换言之，隐式契约影响的不仅是开发体验，更是企业级合规与可审计性的根基。
走向显式能力声明
如果说这件事给我们留下了什么建设性启示，那应该是行业需要在"模型-工具"耦合关系上，建立类似 SBOM（Software Bill of Materials，软件物料清单）的标准化描述——姑且称之为"工具能力清单"（Tool Capability Manifest，TCM）。一个完整的 TCM 应当至少包括四项内容：模型族与版本的结构化标识、可用工具集的精确列表、不可用工具集的精确列表，以及不可用工具的原因的可读说明。这份清单应当以机器可读、可校验、可追溯的方式对外发布，使任何上层应用、任何插件、任何审计系统都能在第一时间获知真实的能力边界。
事实上，国际组织已经在为这一方向铺路。OWASP 在 2025 年 12 月发布的《Agentic Applications Top 10 for 2026》中，已经将"工具滥用"（Tool Misuse）与"身份滥用"（Identity Abuse）列为前两类核心风险；欧盟 AI 法案的高风险义务在 2026 年 8 月正式生效；美国科罗拉多州 AI 法案 2026 年 6 月进入可执行阶段；微软在 2026 年 4 月推出基于 MIT 协议的 Agent Governance Toolkit，提供包括 ToolCallInterceptor、PluginInterface、PolicyProviderInterface 等可扩展接口，把"执行前策略拦截"作为治理核心。制度层面的标准正在快速成型，但技术层面的实践还远远滞后。OpenCode 的 substring 筛选器，正是这种"制度走在前面、工程走在后面"的典型缩影。
值得强调的是，“显式优于隐式"并不意味着对开发者的苛求，而是对工具链友好度的提升。当一份 TCM 在每个项目根目录以 YAML 形式存在，开发者只需在 IDE 插件中加载它就能即时看到"当前模型在当前项目下能做什么、不能做什么”，从而避免把工具问题误判为模型问题。这种透明度的边际成本极低，但带来的开发体验提升与生态信任度增长却不可估量。
中国开源生态的机会窗口
在更宏观的产业图景里，开源 AI 编程代理生态正在经历剧烈洗牌。据 OpenHands 在 2026 年 6 月的盘点，过去一年里开源阵营发生了多起重大事件：Continue.dev 被 Cursor 收购，Roo Code 在 2026 年 5 月被归档，那些曾依赖闭源商用层的中立工具开始面临维护风险。这意味着越来越多的开发者将被迫迁移到新平台，工具链的"治理范式"正在被重新书写。
与此同时，中国的开源力量正在以另一种姿态介入。2026 年 6 月，Z.ai 发布 GLM-5.2，一款约 7440 亿参数的混合专家模型，约 400 亿激活参数，100 万 token 上下文窗口，采用 MIT 协议。开放权重模型的能力首次具备与闭源前沿相抗衡的实力。如果中国主导的开源 AI 编程代理项目，能够在设计层面主动拥抱"显式能力声明"、“结构化工具 manifest”、“可机读契约"等治理范式，就有机会在全球范围内抢占"AI Agent 透明治理"的标准话语权。
从软件供应链的 SBOM（美国 NTIA 在 2021 年发布最小元素标准），到 AI 模型卡（Model Card）的早期实践（2018 年 Mitchell 等人倡导），再到今天的工具能力清单，每一次标准的话语权都曾经历过一个开放的窗口期。在这个窗口期里，谁能率先把"显式优于隐式"的原则落到代码、落到文档、落到插件契约，谁就能在下一轮 AI 工具标准化中占据主动。对中国开源生态而言，这不仅是一次技术升级，更是一次治理范式的输出机会。当模型可替换、工具可插拔、契约可机读成为新基线，开源 AI 编程代理才能真正承担起企业级基础设施的职责。
当 substring 决定工具命运
回到这次具体的事件本身，它最终的归宿很可能是社区提交一个 Pull Request，把 substring 替换为基于 family 字段的显式判定，并在文档中增补一段说明。但比起修复本身，更值得行业深思的是：是什么动力让一位开源作者选择用 substring 来实现这种关键的能力分配？是路径依赖——在项目早期只支持单一模型时根本不需要这种判定？是为了规避某种函数调用格式差异？还是仅仅是一种临时方案，被时间遗忘在三百行代码深处？
无论原因为何，这件事提醒我们：在 AI Agent 时代，每一个看似细微的隐式判定，都可能在用户不知情的情况下重塑能力边界。这种重塑并不必然带来恶意，但其后果——开发者困惑、插件失效、审计失败、模型表现参差——却是真实且广泛的。当一行字符串能够决定二十款模型的工具命运时，我们需要的不是更聪明的 substring，而是更诚实的 manifest。
未来的 AI 编程代理生态，应当朝着这样的方向演进：每一份模型与工具的耦合关系都应有显式契约，每一个判定都应有可追溯的理由，每一份契约都应对开发者透明可见。这不是对工具理性的浪漫呼唤，而是工程实践在 AI 时代必须补上的基础课。