7 篇博文 含有标签「software-architecture」

现代 AI 应用中最危险的一行代码看起来完全无害：

result = await agent.run(user_query)

它读起来就像一个函数调用。它有名称，接受参数，返回数值。你的 IDE 会自动补全它。你的类型检查器也觉得没问题。然而，就在这个单一的 await 背后，隐藏着一个远程的、多跳的、部分失效的分布式系统，而它却套着本地过程的语法外壳。代码看起来的样子与它实际表现出的行为之间的鸿沟，正是大多数生产环境 Agent 事故发生的地方。

内部 API 依赖于一种默契而存在：没人会写下契约，因为每个人都已经心知肚明。那些碰巧存在的字段、调用者在暗地里解析的报错、返回空列表而非 404 的 200 响应 —— 这些都是关键的承重行为。而维系这些行为的基础是，你可以叫出每个调用者的名字，并在做出任何更改之前通过 Slack 联系他们。这种安排一直有效，直到它失效的那天。

当你将一个智能体（Agent）连接到该 API 的那天起，这种默契就失效了。这并非因为智能体怀有恶意或粗心大意，而是因为智能体是一个你无法触及的调用者。它没有 Slack 账号。它没有阅读你的迁移说明。它依赖于从示例载荷或 Schema 快照中吸收的响应形态，并且在你早已更新版本后，它仍会长期依赖这些形态。

一个令人不安的事实是，“内部”从未是 API 本身的属性。它其实是调用者列表的属性。将列表缩减到你认识的人，API 就是内部的；一旦增加一个你无法协调的参与者，API 就是公共的 —— 这意味着你需要承担“公共”一词所暗示的所有严谨规范，尽管你并没有构建任何本应具备的基础设施。

你的代码库中有三种不同方式实现的身份验证逻辑，而且团队中没人在写过其中任何一种。通过 git blame 快速查看，发现这三个文件都出自同一位工程师之手，但去问那位工程师，他们会告诉你他们只是接受了 AI 的建议，而且看起来“没问题”。这种反模式的蔓延并不是因为有人偷懒，而是因为一个对你现有认证模块毫无记忆的 AI 模型，在每次有人打开新文件寻求帮助时，都生成了看起来合理的实现。

这就是“复制粘贴传染病” (copy-paste contagion)，它在结构上与你已知如何应对的经典复制粘贴问题完全不同。

2025 年的一项对照实验让有经验的开发者使用了 AI 编码工具，并测量他们是否变得更快。开发者们预测效率会提升 24%。研究结束后，他们报告自己大约快了 20%。而客观测量显示，他们实际上慢了 19%。

这并不是一个关于 AI 过度炒作的故事。这是一个关于隐性知识的故事——那种存在于每个成熟代码库中、仅靠阅读代码无法恢复的、无文档记录的"为什么"。AI 智能体在全新系统中生产效率出奇地高，正是因为那里几乎没有隐性知识可以违反。它们在成熟代码库中退步，原因完全相同。

这个说法非常诱人：用英语描述行为，模型生成代码，然后交付。提示词（Prompts）变成了源码，产物变成了目标，而 LLM 就像是一个前端界面更友好的 gcc 坐镇其中。如果这个框架成立，那么软件工程的其余部分——评审、重构、架构——都将成为提示词质量的下游产物。但事实并非如此。那些基于这种假设构建的代码库，正以一种现在看来极其乏味的模式走向失败：在大约第六个月，没人能解释为什么某个特定函数长成那样，而且每一次增量变更都会引发一波重复代码。

编译器隐喻才是根本原因，而不是“氛围感编程”（vibe coding）、模型质量或提示词技巧。这是一个范畴错误，它悄无声息地让团队逃避了那些能保持代码库长年连贯性的工作。当你认为模型是编译器时，生成的代码就变成了实现细节，就像汇编语言是 C 程序的实现细节一样。而当你实际在带领一个由非确定性、上下文受限的协作成员组成的团队时，生成的代码才是资产——而提示词比起源码，更像是 Slack 消息。

当今生产环境中最有效的 AI 智能体看起来与框架演示完全不同。它们不是拥有十七种节点类型的有向无环图，也不是通过消息总线协调的多智能体集群。它们是一个提示词、一个工具列表和一个 while 循环——它们比框架重型的对手交付更快、故障更少、维护成本更低。

这不是为了标新立异。这是一个又一个团队在花费数周时间进行框架迁移、抽象调试和 DSL 考古之后得出的结论。这种模式如此一致，值得给它一个名字：后框架时代。

每个 AI 演示都从绿地起步：一个干净的代码仓库、一个全新的 API key，不到一小时就能跑通流式聊天响应。然后有人问："我们能把这个加到真正的产品里吗？"——那个运行在十年老单体系统上、存有无数未记录存储过程的产品，那个部署流程需要三个团队外加一个变更顾问委员会的产品，那个数据模型比 JSON 还古老的产品。

大多数 AI 集成工作都死在这里。不是因为 LLM 不好用，而是因为周围的系统根本不肯配合。超过 75% 的企业 AI 项目都卡在集成边界上——无法将 AI 能力与真正持有所需数据的系统连接起来。

本能反应是计划重写。别这样做。那些真正将 LLM 功能推进生产遗留系统的团队，都是以渐进的方式完成的——通过将现有代码库视为具有已知接口的黑盒的适配器模式。以下是具体做法。