骨架是 Thoughtworks 的 Juntao Qiu 于 2023 年 2 月在 martinfowler.com 上连载的 Modularizing React Applications with Established UI Patterns。笔者没有照搬原文，而是用自己的话重新讲了一遍，正文中的图全部取自原文。在此之上，笔者还拉下作者的示例仓库跑了类型检查和测试，并补充了讨论同一问题的其他资料。

React 是 view library

初学 React 时，最有吸引力的想法是：UI 是把数据变成 DOM 的纯函数。这在一定程度上没错。但一旦向服务器发请求或者跳转页面，component 就不再纯粹了。再加上全局 state 和局部 state 交织在一起，代码很快就会变得复杂。

作者的回答是换个视角。并不存在"React 应用"这种特殊的软件。React 是绘制 UI 的 library，计算和业务规则放在哪里，从一开始就不是它关心的事。架在它上面的，是一个普通的 JavaScript 应用。既然如此，就可以直接沿用从桌面 GUI 时代起一直在用的设计，尤其是把代码分成 presentation、domain、data 三层的做法。

真实的前端应用里，除了 view 还有 router、local storage、多层缓存、网络请求、第三方服务集成与登录、安全、日志、性能调优。如果把这些全都塞进 component 和 hook，同一个文件里就会出现这样的情形：请求订单状态的那一行后面，紧跟着一行去掉字符串开头空格的代码，再后面又是一行跳转到别的页面的代码。读代码的人只能不断切换抽象层次，来回翻看。

拆分的理由可以归结为两点。界面比业务规则变得更频繁。而且把两者分开后，一次只需要思考一件事。第二个理由正是 Martin Fowler 在 PresentationDomainDataLayering 中列为这种划分最大好处的一点：三个主题可以相对独立地思考，需要关注的范围因此缩小。

应用成长的五个阶段

在进入重构之前，作者用五张图展示了应用在成长过程中结构如何变化。重要的是进入下一阶段的契机。推动下一阶段的不是某个固定的时间点，而是当前阶段产生的不便。五张图里颜色的含义都一样：浅绿是持有 state 的 container component，深绿是只负责绘制的 presentational component，紫色是 hook，蓝色是 domain object，橙色是网络之类的 infrastructure。

最开始，一个 component 包揽网络请求、state、计算和 render。对小应用或一次性项目来说这就够了，而且代码长得像 HTML，反而更好读。当遍历列表生成条目的代码和配置外部 component 的代码混在一起，读懂到底发生了什么开始变得费时，就该进入下一阶段了。

界面变大之后，就按照最终 HTML 的形状拆分 component。只负责绘制的 component 被分离出来，但最上层的 component 里仍然留着网络请求、把响应转换成界面所需形状的代码，以及收集要发给服务器的数据的代码。这三样都不是 UI，却待在 component 里。

接着把 state 及其变化抽到 custom hook 里。这时 hook 中就剩下了既不是 side effect 也不是 state 的纯计算。

把这段计算抽到与 React 无关的对象里，就得到了 domain object。数据格式转换、null 检查、默认值都搬到这里。对象多起来之后，就开始需要继承或多态。

最后，当你看到一些既不属于 UI、也不在乎数据来自服务器还是 local storage 或缓存的对象时，就把它们单独归成 model layer。

光看图比较抽象。我们用实际代码把这五个阶段走一遍。作者选的例子是在线订单的支付页面。

从一个支付页面出发

支付方式来自服务器配置，每个国家都不一样。只要服务器返回了至少一种，就在末尾追加现金支付并默认选中；一种都没有的话，就什么也不显示。

最初的代码就是教程里常见的样子。在 useEffect 里 fetch，把响应转换成界面所需的形状，追加现金支付，再绘制单选列表。下面是笔者精简后的版本。

export const Payment = ({ amount }: { amount: number }) => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
 
  useEffect(() => {
    fetch(url)
      .then((res) => res.json())
      .then((methods: RemotePaymentMethod[]) => {
        if (methods.length === 0) return setPaymentMethods([]);
        const extended = methods.map((m) => ({ provider: m.name, label: `Pay with ${m.name}` }));
        extended.push({ provider: "cash", label: "Pay in cash" });
        setPaymentMethods(extended);
      });
  }, []);
 
  return (
    <div>
      {paymentMethods.map((method) => (
        <label key={method.provider}>
          <input type="radio" defaultChecked={method.provider === "cash"} />
          {method.label}
        </label>
      ))}
      <button>${amount}</button>
    </div>
  );
};

在这个规模下不成问题。但要修改这个 component，就得同时理解四件事：如何发起网络请求，如何把服务器数据转换成界面认识的形状，如何绘制单个支付方式，以及如何绘制整个支付区域。代码一旦变大，读代码的人就得在这四者之间不停切换。

hook 与 pure component

第一个抽出来的是 state 和 fetch。判断信号很简单。与 render 无关的代码超过 component 主体的一半时，就抽成 hook。usePaymentMethods 负责 fetch 和转换，component 只接收 hook 给的数组并负责绘制。

第二个是绘制列表的 JSX。看到只靠 props 就能绘制的代码块时，就拆成 component。PaymentMethods 是只接收一个支付方式数组的 pure component，因此易于测试和复用。以后即使加上通知选择结果的 onSelect callback，它也不碰外部 state，所以依然是 pure 的。

const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
  useEffect(() => { /* 위의 fetch와 변환 */ }, []);
  return { paymentMethods };
};
 
export const Payment = ({ amount }: { amount: number }) => {
  const { paymentMethods } = usePaymentMethods();
  return (
    <div>
      <PaymentMethods paymentMethods={paymentMethods} />
      <button>${amount}</button>
    </div>
  );
};

作者把这两步都称为重构目录中的 Extract Function，因为在 React 里 component 也是函数。重要的是，这里并没有引入新概念，只是把一个函数拆成了两个。

到这里看起来像是完成了，但还剩两处。view 里有"现金就默认选中"这个判断，hook 里有把响应转换成界面形状的匿名函数。作者把这种业务规则渗漏到 view 和 hook 里的现象称为 logic leak。

收拢到 domain object 的规则

第三个信号是对同一份数据的判断散落在 view 和 hook 中的时候。把渗漏出来的判断和转换收拢到一个 PaymentMethod class 里。就像本博客领域模型一文讲过的那样，把规则放在数据旁边。

class PaymentMethod {
  constructor(private remote: RemotePaymentMethod) {}
  get provider() { return this.remote.name; }
  get label() { return this.provider === "cash" ? "Pay in cash" : `Pay with ${this.provider}`; }
  get isDefaultMethod() { return this.provider === "cash"; }
}
 
const convertPaymentMethods = (methods: RemotePaymentMethod[]) =>
  methods.length === 0
    ? []
    : [...methods.map((m) => new PaymentMethod(m)), new PaymentMethod({ name: "cash" })];

view 里的单选按钮现在通过 defaultChecked={method.isDefaultMethod} 去问对象。默认的现金支付也用同一个 class 的一个实例来表示。服务器给的和应用追加的变成了同一种形状，view 就不需要区分两者。

作者把测试变容易列为这种结构的好处。原文说到这里就停了，但到底容易了多少，看代码更快。下面是笔者写的测试。没有 React，没有渲染器，也没有 fetch mock。

test("서버가 준 결제 수단 끝에 현금 결제를 기본값으로 붙인다", () => {
  const methods = convertPaymentMethods([{ name: "apple" }, { name: "google" }]);
 
  expect(methods.map((m) => m.label)).toEqual(["Pay with apple", "Pay with google", "Pay in cash"]);
  expect(methods.filter((m) => m.isDefaultMethod).map((m) => m.provider)).toEqual(["cash"]);
});
 
test("서버가 아무것도 주지 않으면 현금 결제도 보여 주지 않는다", () => {
  expect(convertPaymentMethods([])).toEqual([]);
});

要在最初的代码里验证同样的规则，得先 render component，拦截 fetch，再等单选按钮画出来。规则一旦变成对象，测试就成了一行函数调用。

另一个好处是，新需求来了以后该去哪里是确定的。此时的文件结构是这样的。

src
├── components
│   ├── Payment.tsx
│   └── PaymentMethods.tsx
├── hooks
│   └── usePaymentMethods.ts
└── models
    └── PaymentMethod.ts

结构是否真的扛得住，要等新需求来了才知道。作者在这里又加了一个功能。

捐赠功能与作为 state machine 的 hook

新需求是把订单金额向上取整，把差额捐给慈善机构。订单是 19.80 美元的话，就询问是否捐 0.20 美元，同意后按钮上显示 20 美元。

作者故意一开始把是否同意的 state 和计算放进支付 component 里。复选框标记、文案分支、合计计算一股脑涌进来，component 又变重了。整理的顺序和前面一样：state 和计算放进 useRoundUp hook，文案拼接放进 helper 函数，复选框标记放进 DonationCheckbox component。

export const useRoundUp = (amount: number) => {
  const [agreeToDonate, setAgreeToDonate] = useState(false);
 
  const { total, tip } = useMemo(() => ({
    total: agreeToDonate ? Math.floor(amount + 1) : amount,
    tip: parseFloat((Math.floor(amount + 1) - amount).toPrecision(10)),
  }), [amount, agreeToDonate]);
 
  const updateAgreeToDonate = () => setAgreeToDonate((v) => !v);
  return { total, tip, agreeToDonate, updateAgreeToDonate };
};

toPrecision(10) 是原文没有解释原因的地方。笔者在 Node 24 上试了一下，20 - 19.8 得到的是 0.1999999999999993。这是用来消除浮点误差的手段。

作者把这样的 hook 看作"view 背后的 state machine"。UI 传来事件就生成新的 state，新的 state 又触发 render。hook 原本是为了让多个 component 共享 logic 而设计的，但作者的立场是，即使只有一处在用，它也能让 component 专注于 render，所以值得抽出来。在此补充一点：正如 React 官方文档的 Reusing Logic with Custom Hooks 指出的，custom hook 共享的是处理 state 的 logic，而不是 state 本身。每个调用 hook 的 component 都会各自生成一个这样的 state machine。

整理完之后，支付 component 变成调用两个 hook、并排摆出两个子 component 和一个按钮的样子。功能多了一个，支付 component 的职责却没变。

各国规则与 shotgun surgery

下一个需求是让各国使用不同的取整单位。日本以 100 日元为单位，丹麦以 10 克朗为单位。作者说"看起来是个简单的修改"，故意先展示了把国家代码作为 prop 传入、再加上分支的做法。

// useRoundUp 안
total: agreeToDonate
  ? countryCode === "JP" ? Math.floor(amount / 100 + 1) * 100 : Math.floor(amount + 1)
  : amount,
 
// 체크박스 문구 helper 안
const currencySign = countryCode === "JP" ? "¥" : "$";
 
// 버튼 JSX 안
<button>{countryCode === "JP" ? "¥" : "$"}{total}</button>

同样的 countryCode === "JP" 判断在 hook、helper、按钮三个地方各出现了一次。加上丹麦，这三处都得重新改；三元运算符撑不住的时候，就会冒出一张按国家代码查货币符号的表。那张表最终也会在多处被分别引用。一处变更需要同时修改多个模块，这种坏味道叫作 shotgun surgery。

这个阶段和前三个阶段的不同之处在于，判断信号不是来自代码，而是来自变更请求。只看现在的代码，三个分支并不难读。要数一数每加一个国家得改几处，问题才会显现。那么，散落的分支该收拢到哪里呢？

用 Strategy 收拢各国差异

作者的回答是把各国的差异本身做成对象。先用 Extract Class 和 Replace Conditional with Polymorphism 做出一个 interface 和各国的实现。

interface PaymentStrategy {
  getRoundUpAmount(amount: number): number;
  getTip(amount: number): number;
}
 
class PaymentStrategyAU implements PaymentStrategy { /* 1달러 단위 */ }
class PaymentStrategyJP implements PaymentStrategy { /* 100엔 단위 */ }

做完一看，各个实现之间不同的只有货币符号和取整函数两样，getTip 之类的其余部分完全一样。于是作者用 Inline Class 把这些实现合并成一个 class，只把不同的部分通过构造函数传入。之所以不必为每个国家建 subclass，而能把取整算法作为函数传进去，是因为在 JavaScript 里函数是值。下面是笔者把结果精简后的版本。

class CountryPayment {
  constructor(readonly currencySign: string, private roundUp: (n: number) => number) {}
  getRoundUpAmount(n: number) { return this.roundUp(n); }
  getTip(n: number) { return parseFloat((this.getRoundUpAmount(n) - n).toPrecision(10)); }
}
 
const japan = new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100);
japan.getRoundUpAmount(3312); // 3400
japan.getTip(3312);           // 88

hook 和 component 现在不再知道国家。它们只是接收这一个对象，使用 strategy.getRoundUpAmount(amount) 和 strategy.currencySign。加一个国家只要多建一个对象就行，不需要改任何文件。

先经过 interface 再合并回去，这个过程看起来可能有些多余。笔者认为这是原文最值得学习的部分。多态不是目的，而是揭示共同点与差异的工具；一旦看到差异缩小到一个函数，就把 class 层级拆掉了。比起引入模式，判断什么时候再把模式拆掉更难。

把 fetch 移出 hook

最后抽出来的是 usePaymentMethods 里的 fetch 和转换。hook 是 React 的概念，所以留在 view 一侧。加上 error handling 和 retry，hook 很快就会膨胀；换到别的 view library，hook 就用不了。而普通函数在哪里都能用。

const fetchPaymentMethods = async () => {
  const response = await fetch(`${API}/payment-methods?countryCode=AU`);
  return convertPaymentMethods(await response.json());
};
 
export const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<PaymentMethod[]>([]);
  useEffect(() => {
    fetchPaymentMethods().then(setPaymentMethods);
  }, []);
  return { paymentMethods };
};

作者写道，这个函数的作用类似 Anti-Corruption Layer 或 Gateway。意思是即使服务器响应的结构变了，要改的地方也只限于这一个函数。不过这两个名字并不是一回事。Fowler 的 Gateway 是把对外部系统的访问封装到一处的对象；Anti-Corruption Layer 则出自 Eric Evans 的 DDD，是一道边界，负责翻译语义体系不同的外部模型，防止它污染自己的模型。这个例子里的服务器响应只有 { name } 一个字段，几乎没有需要翻译的语义差异，所以笔者认为 Gateway 是更准确的名字。当服务器是其他团队拥有的遗留系统、连支付方式的含义本身都不同时，同一个位置才会成为 Anti-Corruption Layer。

最终结构是这样的。render 在 component 里，state 在 hook 里，规则在 domain object 里，网络请求在函数里。

作者列出了这样拆分带来的五个好处。更容易找到缺陷所在的位置。代码更容易复用和组合。更容易阅读。增加功能时整体不会动摇。还有，domain logic 不知道 view，所以可以只替换 view layer。对最后一点，作者自己也附加了一个前提：在大多数项目中这种情况非常罕见。另外值得一并记住的是，这五点都没有测量数据。

原文的主线到此为止。但真正把这段代码跑起来，会冒出文章里看不到的东西。

运行示例后看到的东西

笔者拉下作者的示例仓库（16 个提交，最后一个提交 de186c5），跑了 tsc --noEmit 和 7 个测试。两者都通过了，原文中缺少定义的 helper 也在仓库的 src/utils.ts 里。但仔细看了结构之后，发现有三件事是在照搬之前需要知道的。

每次 render 都新建的 Strategy

支付 component 通过 prop 接收 Strategy，没有传的话就用 new 创建默认值。而 useRoundUp 把这个 Strategy 放进了 useMemo 的 dependency 里。

export const Payment = ({
  amount,
  strategy = new PaymentStrategy("$", roundUpToNearestInteger),
}: { amount: number; strategy?: PaymentStrategy }) => {
  const { total, tip } = useRoundUp(amount, strategy); // 안에서 [agreeToDonate, amount, strategy]
  // ...
};

JavaScript 的 default parameter 在每次调用时都会求值。而 useMemo 用 Object.is 比较 dependency。两者一碰上，每次 render 都会生成新实例，memo 每次都重新计算。笔者在 React 18 下把同样的结构 render 了四次，使用默认值时计算跑了 4 次，传入同一个实例时只跑了 1 次。仓库里的 App.tsx 写的是 <Payment amount={19.9} />，没有传 Strategy，所以应用的执行路径恰好走的就是默认值这一侧。

这个例子的计算只是几次加法，没有什么开销。问题在于结构。由谁在哪里创建并传入 Strategy，文章和仓库里都没有定下来，只有测试创建了日本和丹麦的实例。换作笔者，会把实例放成 module 级常量，再按国家代码取出来传进去。

const strategies = {
  AU: new CountryPayment("$", (n) => Math.floor(n + 1)),
  JP: new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100),
} as const;
 
<Payment amount={amount} strategy={strategies[countryCode]} />

仓库里的 fetch 没有 dependency 数组

原文代码的 useEffect 里有 []，但仓库中的 usePaymentMethods 从第一个提交到最后一个提交都没有 dependency 数组。没有数组的 effect 每次 render 都会重新执行。响应回来后用新数组更新 state，这又触发 render，effect 再次 fetch。由于 convertPaymentMethods 每次都返回新数组，这个循环停不下来。

把 fetch 换成立即响应的 mock，在 Jest 里统计 300ms 内的调用次数，测了四次，分别是 152、225、231、233 次。加上 [] 就是 1 次。仓库的测试只检查文案有没有出现在页面上，所以抓不到这种反复调用，全部通过。照着原文敲代码的读者不会遇到这个问题，只有直接拿仓库来用时才会踩到。

把国家代码作为 prop 传入时出现的 race

原文代码的 fetch effect 也没有 cleanup。React 官方文档的 Synchronizing with Effects 指出，在 effect 里 fetch 时，晚到的旧响应可能覆盖最新的响应，所以要用 ignore 标志丢弃旧响应。原文只在 mount 时 fetch 一次，所以目前没有问题。但一旦把 URL 里的 countryCode=AU 改成通过 prop 传入，就有了 dependency，race 也随之出现。笔者在移植这套结构时，会从一开始就这样写。

useEffect(() => {
  let ignore = false;
  fetchPaymentMethods(countryCode).then((methods) => {
    if (!ignore) setPaymentMethods(methods);
  });
  return () => { ignore = true; };
}, [countryCode]);

再补充一点，原文的取整是 Math.floor(amount + 1)，所以金额已经是整数时还会再加 1。20 美元的订单会变成 21 美元。原文只举了 19.80 美元和 3312 日元的例子，看不出这是不是有意为之。如果要搬到实际服务中，首先得确定它和 Math.ceil 有什么不同。

这种结构什么时候用

作者自己也说，拆分不是固定规则。小而内聚的 component 放在一个文件里反而更容易理解其行为，需要警惕的是文件大到无法理解。他明确表示，Todo 应用或只有一个表单的应用全部放进 component 里也没关系，而示例是为了展示更多模式才故意做得复杂。其他资料也给出了同一方向的前提。

Fowler 在同一篇 layering 文章中说，这种划分只适用于相对较小的单元。把 view、model、data 作为顶层文件夹，在小系统里没问题，但一旦其中某一个变得太大，就应该按领域划分顶层，再在其内部分层。如果把前面看到的 components/、hooks/、models/ 文件夹原样搬成大型应用的顶层结构，就会变成 Fowler 叫人避免的样子。

Dan Abramov 也有类似的经历。他在 2015 年提出把 component 分成 presentational 和 container component，到了 2019 年又在文章开头加了一段更新，说现在不再推荐这样拆分。理由是 Hooks 不需要任意的划分就能做到同样的事；他还补充说，见过太多在没有必要的情况下被教条式强制推行的例子。原文的 hook 抽取更接近这段更新所说的方式。不单独设一个叫 container 的 component，由调用 hook 的 Payment 兼任这个角色。

关于 fetch，React 官方文档又往前走了一步。You Might Not Need an Effect 一方面说把 fetch logic 抽到 custom hook 里，日后更容易迁移到更好的策略；另一方面首推的是 framework 内置的数据获取，或 TanStack Query 这样的 client cache。像原文最后一步那样把 fetch 抽成普通函数，就可以把这个函数直接传给 TanStack Query 的 queryFn，前一节的 race 和反复调用都交给 library 处理。笔者认为，这是原文只用一句话带过、却最实用的收益。key 和函数如何组合，另在 queryKey 一文中讨论过。

总结一下笔者的判断。原文的顺序（hook、pure component、domain object、Strategy、network client）值得照着走，因为每个阶段的不便都会成为进入下一阶段的理由。但并不是非走到底不可，看清自己眼下遇到的不便属于哪个阶段，在那里停下就好。与 render 无关的代码多，就做到 hook；同样的判断四处散落，就做到 domain object；一处变更要改好几个文件，就做到 Strategy。另外，如果要用 Strategy，先定好创建实例的位置；如果要把 fetch 放在 effect 里，先写好 cleanup 和 dependency。原文省略的这两点，正是实际移植时最先出问题的地方。

没有标准答案，但希望读到这篇文章的各位也能想一想，自己的代码眼下正遭遇的是第几个阶段的不便。

最先映入眼帘的用途是浏览器自动化。Browserbase 提交了一个把 Jev 接进 Stagehand 的 act() 的 PR。结构是把页面的无障碍树作为 state 发过去，再以选项的形式问「下一步该点击哪个元素」。40 个任务里 act() 的中位数从 1.97 秒降到 0.46 秒，147 次操作中回退到 LLM 的只有 4 次。Playwright 脚本只要一个 selector 变了就会坏掉的那个位置，被一次只返回一个概率的调用填上了。写这篇文章的时候，这个 PR 还没有合并。

那个 PR 划的线，就是这篇文章的问题。它把接受 Jev 答案的标准放在概率 0.7，过不了就交给 LLM。能不能相信那个模型返回的概率，在代码里划一条线。

光看别人的基准测试没法判断，所以笔者想用自己的数据来验证。这个博客里有一道拦截音译外来词的闸门。规则是不写 피커 而写 picker，但正则只能抓住有把握的那一半，像 멀티스레드（멀티=multi + 스레드=thread）或 콜 스택（call stack）这种嵌在复合词里或者在韩语里早已定型的词，由笔者每次手工判断。答案只有「还原」和「保留」两个，懂的人一秒就能判断，而且要在构建脚本里、没有人复核的情况下决定通过还是失败。它和 Stagehand 的 selector 判断是同一种形状。

于是顺序就这样定了：Jev 返回什么，那个概率来自什么样的训练，把笔者的闸门交给它会得到什么数字，以及这些数字能用在哪里。

不生成文本的模型

公开日期是 2026 年 9 月 15 日。公司不把它叫作 LLM，而是归进 System One Model 这个新类别。本文称之为决策模型。创始人 Diogo Almeida 曾在 OpenAI 以第四作者的身份参与过InstructGPT 论文。他待过打造了 ChatGPT 直系祖先那套方法的团队，如今站在指出这套方法局限的一边。

Jev 不生成句子。预先给定答案的形状，它就从中挑选，并一并返回概率。问题类型只有三种。

endpoint 也只有一个。向 POST /v1/systemone 发送 state（要评估的内容）、model、questions（问题映射）就会拿到答案。针对同一个 state 的多个问题可以装进一次请求，而且问题变多，响应时间也几乎不增加。

为什么快，可以用token 的原理一文中梳理过的 prefill 与 decode 的不对称来解释。LLM 慢的原因在于输出要一个 token 一个 token 地顺序挤出来，而 Jev 没有 decode 这个阶段。它并行读一次输入，直接把概率读出来。所以完全没有输出 token 的费用，只有输入按每百万 token $0.042 计费。

有一位叫 Archer Hume 的开发者调用 API 约一万次，从外部还原了它的行为，写成了一篇分析。输入 360 token 时中位数 57.5ms，29,835 token 时 218ms，塞进 1,500 个问题时是 610ms。其中最直接的证据，是选项有 200 个的响应与只有 2 个的响应以同样的速度返回这一观察。意思是写答案本身不花时间。

没人看的判断

速度和价格很显眼，但 Almeida 在公开发布文章里抛出的问题在另一边。模型在对话上已经超人好几年了，那自动化都去哪儿了。

他的回答是，这两类工作的种类不同。聊天机器人、copilot 和编码 agent，目标是让人在旁边看着觉得满意。在服务器上安静运行、没人看的判断则不是这样。如果把前者叫 assistant、后者叫 automation，那么到目前为止出现的模型全都是为前者造的。

笔者在梳理harness 设计时也做过类似的区分。agent 系统里有无数没人看的判断。这个请求要不要转交给人。这条命令可不可以执行。现在这些全都在问昂贵的 LLM。笔者的正则闸门盖不住的剩下那一半，也是这样的判断。

RLHF 留下的位置

那为什么需要新的训练方法呢。让现有的模型只答是/否不行吗。

线索在校准里。准确率是能答对百分之几，校准则是知不知道自己能答对百分之几，衡量这种偏离的指标是 ECE（expected calibration error）。它把每个概率区间里说出口的概率与实际命中率的差值按样本比例加权平均，0 为完美。可是，有案例显示，经过优化人类偏好的 RLHF（reinforcement learning from human feedback）之后，这个刻度偏了。在 GPT-4 技术报告的 Figure 8 中，预训练模型的 ECE 是 0.007，经过 post-training 的模型则是 0.074，差了十倍以上。报告没有写出原因，笔者也没有找到能确定原因的一手证据。定义以及原因目前弄清到了什么程度，另外整理在LLM 的校准与过度自信中。

不过光靠 ECE 一个是不够的。 对所有输入都打 0.6 的常数预测器，只要实际命中率是 60%，ECE 也是 0。概率只是诚实、却不随案例分开，就没有划线的地方。所以除校准之外还要一起看概率是否真的分得开，后文要用的“在误差预算内可自动处理的比例”就是把这两者捆成一个数字的指标。

从软件的角度看，重要的是这一部分。概率既诚实又分得开，就能划线。于是有了超过 0.95 就自动处理、低于这个值就交给人的结构。

TypeSafe 说自己瞄准这个位置开出了第三条路。优化人类偏好的 RLHF，优化机器可判分的正确答案的 RLVR（reinforcement learning with verifiable rewards），以及声称优化校准后决策的 RLCD。

只是以 RLCD 名义公开出来的只有三行输出契约。截至写这篇文章的 2026 年 9 月 23 日，TypeSafe 的文档和发布文章里都没有论文或技术报告。另有一篇用同样缩写的 ICLR 2024 论文，那边是 reinforcement learning from contrastive distillation，是不同的方法。检索时注意别混在一起。

confidence 的真面目

那么 Jev 返回的数字诚实吗。回答之前先要看一件事。它返回的数字不止一个。

Choice 和 Score 的响应里同时装着 probabilities 和 confidence。前者是覆盖全部选项的概率分布，后者是 0 到 1 之间的一个数字。在代码里设阈值时，手先伸过去的是 confidence。

这个值不是模型造出来的。TypeSafe 组织公开的 system-one-adapter-python 里，_utils/confidence_metrics.py 总共 32 行，Choice 的部分是这样。

def choice_confidence(probs: list[float]) -> float:
    """Scale peak choice probability from uniform to certainty."""
    if len(probs) == 1:
        return 1.0
 
    normalized_probs = _normalize(probs)
    uniform_probability = 1.0 / len(normalized_probs)
    return (max(normalized_probs) - uniform_probability) / (1.0 - uniform_probability)

没有模型调用，也没有学出来的参数。进去的是一个 probabilities 向量，出来的是一个实数。写成式子就是 c = (p_max − 1/K) / (1 − 1/K)，选项为三个、最大概率为 0.8 时得到 0.7。

这个仓库不是生产环境的 Jev 服务器，而是用 LLM 模仿同一套 API 的替代实现。所以只凭它还不能断言。不过还有两个指向同一个式子的证据。TypeSafe 官方文档的 confidence 页面把这个值写成 "a statistic computed from the probability distribution"，演示代码里则放了一条标注为三选项近似式的 (3 × largest probability − 1) / 2。K 为 3 时与上式相同。另外主张审计账本记录了在真实 API 上，只给两个都错的选项时，响应中胜者为 0.52，confidence 返回的是 0.04。K 为 2 时 (0.52 − 0.5) / (1 − 0.5) = 0.04。与式子吻合。

在同一个仓库里，Score 用的干脆是另一个式子。把到众数水平的平均绝对距离除以均匀分布下的同一个量，然后用 1 减去它。文档没有公开 Score 的式子。也就是说，confidence 这一个名字底下有两套算式，类型不同时同一个数字含义也不同。Noul 没有 confidence 也是同样的理由。没有可折叠的分布。

文档也没有藏着这一点。它甚至写明，想用别的计算方式的话会把整个 probabilities 给你，你自己处理。这是写在文档里的内容，问题在于不读就用的那一方。

不过公开发布文章的对比表把两者并在一起写。上面写着 "Calibrated: higher confidence means higher accuracy"。读的人会理解为 confidence 是经过校准的值，而校准主张实际挂着的那一侧是 probabilities。

这个区分在数字上拉开多大，有测量可看。一位叫 scienthoon 的开发者公开的独立校准测量，单独测了把 confidence 读作“答对的概率”时的 ECE。OpenBookQA 上是 0.035，HellaSwag 上是 0.078，合成集合上是 0.18。同一批集合的原始概率分别是 0.024、0.029、0.107。三个集合里 confidence 一侧都更差。

为什么会变差，答案在式子里。K 固定时 c 是 p_max 的单调递增变换，顺序被保留。判别力原样不变，只要把阈值换算过去就行。坏掉的不是信息，是刻度。 K 随问题变化时，就多出一个问题。拉伸的倍率也跟着变。同样是 p_max 0.8，两个选项时变成 0.6，五个选项时变成 0.75。在选项数混杂的工作负载里用单一阈值的那一刻，这就成了问题。

随分布变化的校准

那么 probabilities 那一侧可以信吗。

实际调用 Jev 测过的记录是公开的。Jared Palmer 做的开源复现实现 Kev 的仓库里有 runs/jev-* directory，usage.json 以 "model": "typesafe-ai/jev" 记录着这是经由 Vercel AI Gateway 的真实调用。把六个 jev-* directory 的 usage.json 加起来，2026 年 9 月 18 日和 20 日两天共调用了 5,364 次，输入是 2,418,260 token。下面七个集合中的 scienthoon 是把那位开发者的结果文件转换后导入的，不在这个合计里。

价格确实只按输入计费这一点，可以在别处得到确认。钓鱼基准的作者看了 TypeSafe dashboard 记了下来。两次运行的 456 万 token 中，输入 366 万、输出 90 万，而账单是 $0.15，这个值与只按输入计算的结果吻合。

从同一个 directory 的 report.json 里取出七个评估集合的指标，整理出来是这样。下面的确信度不是 confidence 字段，而是 probabilities 的最大值。过度自信是 평균 확신도 − 정확도（平均确信度减准确率），共 5,743 条。删去判断依据的“无法判断”项，用的是将其排除在准确率评分之外的 clean 块的值。

从中能读出两点。

第一，ECE 变动了将近十倍。 从 0.011 到 0.105。同一个评分器，同一个模型。“已校准”不是模型的性质，而是模型与分布之间的关系。分布一变校准就垮掉，这件事本身早已是已知的结果。这里新的地方在于，在把校准当作训练目标的模型上也出现了同样的形状。

ECE 最大的那个集合的 0.105，比前面看到的 post-RLHF GPT-4 的 0.074 还要大。不过不能把这两个读成排名。任务不同，而且 ECE 是一个会随着区间分成几份、样本挤在哪个区间而变动的估计量，把来自不同评分器的数字放在一起，比较并不成立。

第二，测得的 ECE 几乎全部由过度自信一项解释。 两列之差在七个集合上全都落在 0.002 到 0.011 之间。ECE 是各区间差距的加权平均，不可能小于整体的过度自信，而这个差几乎为 0，意味着各区间偏离的符号都朝一个方向倾斜。不是各区间互相交错抵消的噪声。

为什么会这样，竖着读就看得见。平均确信度除去 semif 之外，六个都挤在 0.851 到 0.906 之间。在同一段区间里，准确率却从 0.753 摆到 0.857，宽度是前者的两倍。确信度即使分布变了也几乎不动，动的只有准确率。剩下的差值就直接是 ECE。

这个性质在实务里怎么显现，另一个基准给出了答案。在 2,000 封钓鱼邮件上以 Claude Haiku 4.5 作对照组的测量中，Jev 的准确率是 62.6%，Haiku 是 81.3%。不过更显眼的是 ECE。仓库报告的 ECE 是 Jev 0.154、Haiku 0.097，而主张审计账本把 Jev 的 P(phishing) 值在 0 到 1 上按 10 个区间重新测算，得到 0.170。无论按哪种读法，把校准当作训练目标的模型，在校准上都输给了用 RLHF 造出来的 LLM。 同一位作者只用一条链接主机列表规则就拿到了 91.6%。

把同一个指标放到多个集合上看，幅度就更清楚。误差预算 5% 下可自动处理的比例，在 scienthoon 集合是 0.486，transfer-v9 是 0.695，semif 是 1.000。Kev 的评分器注明这个值是在样本内选取阈值得到的最大值，并不是部署后的误差保证。不能把其中任何一个当作模型的规格来引用。

音译判别闸门

读别人的基准和在自己的数据上测，是两回事。所以笔者把开头那道闸门实际交给它过了一遍。

笔者还没有 Jev 的 API key。于是改成在本地跑了前面提到的 Kev-9B。 它是在 Qwen3.5-9B-Base 上加了 rank-16 LoRA 和 pointer head 的复现实现，采用 Apache-2.0。下面的数字不是 Jev 的数字。Kev 的训练数据是英语决策任务，在同一位作者的测量里，Kev-9B 即使在英语任务上也不如 Jev。误差预算 5% 的自动化比例是 0.45 到 0.57，而 Jev 是 0.70；MMLU-Pro 是 0.52 对 0.84。而且 TypeSafe 文档也就 Jev 说明了英语是主要训练语言，CJK 并不对等。

评估集合取自本仓库的 18 篇韩语文章。标签的正确答案标准是本仓库一贯把那个词写成哪种形式。也就是说，它不是韩语技术文档社区的共识，而是这个博客的惯例；在两者分歧的词上，模型可能按社区标准是对的，按这个标准却是错的。

• 闸门集合 102 句：是闸门已经认识的词。把正文里写成英文的 calendar、picker、adapter 之类的词改回韩文音译的反事实句子为阳性 23 句，write-post.md 明确列为例外的 리렌더링（re-rendering）或 콜 스택（call stack）实际出现的句子为阴性 79 句。在这里，现行的正则闸门按定义能答对 100%。
• 保留集合 60 句：是闸门一次都没见过的词。 也就是机器学习里说的 held-out 集合。 把正文里只写英文的 loader、mutation、prefill 改成音译的为阳性 30 句，正文里只写韩文的 리듀서（reducer）、스냅샷（snapshot）、런타임（runtime）为阴性 30 句。在这里，正则一个阳性都抓不到。

阳性是笔者造出来的反事实句子、阴性是真实句子，这个不对称先说明在前。而且有效样本不是句子数，而是词数。 标签是按词确定的，所以出现同一个词的那些句子并不是独立观测。闸门集合是 24 种，保留集合是 13 种。

下表只统计了问“这个词是否该还原成英文”的那一个 noul 问题。同一次请求里装了四个问题，但其余三个是否定式、Choice 变体，以及没能把标签立好的复合词判定，所以没有混进来。5% 预算自动化比例是指从确信度高的一侧往下切，使切点以上区间的误差不超过 5% 的最大比例。

多数类基线是不读句子、只押多数那一侧标签时的得分。模型在它之下。

最后一行就是这次实验的答案。在保留集合上，无论把阈值定得多高，能在 5% 误差内自动处理的决策一件都没有。

看预测分布，就知道发生了什么。模型对全部 162 句都答了“该还原”。 37 种词全部如此。阳性全对，阴性全错。所以保留集合的 0.500 不是实力，而是因为集合本身平衡才出来的数字。

与此同时平均确信度是 0.876。在闸门集合上确信度超过 0.9 的占 49%，而那个区间的实际命中是 0.240。

结构性恒等式也没有成立。把“是否该还原”和“是否该保持原样”的概率相加，在闸门集合上平均得到 1.655，102 句全部偏离 1 超过 0.1。

设计上就是如此。两个问题是彼此读不到对方的独立评估，TypeSafe 自己也在 jaggedness 页面上放了 refund 0.72 与 not_refund 0.47 相加得到 1.19 的例子。

实务上卡住的地方在这里。不能把按 Noul 调好的阈值搬到 Choice 上。 同一个判断而结论相左的句子占 14% 到 17%。

如果是问什么都答是的模型，这个结果就毫无意义。笔者先确认了这一点。

它读韩语，会说“不是”，并且把 0.02 和 0.98 分开。 这不是全局性的迎合偏差。能借此排除的也就到这里为止。闸门问题的措辞本身很差的可能性仍然留着。

把规则放进 state 的结果

那么，把判别所需的知识直接给它会不会不一样呢。TypeSafe 文档推荐的领域适配方式就是这个。不碰权重，把参考资料装进 state 发过去。

笔者把 write-post.md 里已经写好的规则段落一起放进 state，重新跑了一遍。输入从每句 100 token 增加到了 450 token。闸门集合是泄漏。 因为那份参考资料把闸门词和例外词逐个点名列了出来。所以那一侧是用来看“它到底读不读参考资料”的对照组，真正的考试是保留集合。

延迟是在 M2 Max 上跑的本地推理，和前面看到的 Jev 的 API 延迟不在同一个轴上。这里要看的不是绝对值，而是放进参考资料之后的 2.4 倍。

在平衡的保留集合上，按句子的准确率从 0.500 到 0.500，完全没动。 按词来看反而从 7/13 降到了 5/13。

闸门集合从 0.225 到 0.676 并不是实力提升。之前它对 102 句全都说“还原”，给了参考资料之后只对 12 句这样回答。阴性从 0/79 升到了 68/79，但阳性从 23/23 崩到了 1/23。那个集合里阴性以 79 比 23 占多数，所以“大体上保持原样”这个常数自动就能拿到更高的分。它学到的不是区分，而是改变了倾斜。

这并不意味着模型不读句子。同一个词的同一批句子，给了参考资料之后，预测在句子之间散开了。로더（loader）的标准差从 0.096 增加到 0.217，뮤테이션（mutation）从 0.042 增加到 0.236。读是读了，只是分不出来。

而且这个结果也动摇了上一节的解读。如果仅凭一段 state 文本就能把输出整个翻过来，那么第一次运行时的“全都还原”，也可能不是模型的极限，而是问题措辞的不足。本文没能排除这个可能性。

有一点明显变好了。“还原”和“保持原样”的概率之和在保留集合上从 1.508 靠近到了 0.963，大幅偏离 1 的句子从 59 句减到了 18 句。但准确率没有动。 两个问题的概率彼此对得上，和那些概率本身是对的，是两回事。

决策模型的位置

看到这里很容易倾向于得出这类模型整体没用的结论，但把公开的基准并排放在一起看，并非如此。

只有 rerank 那一行是检索排序质量指标，与其他行的准确率不在同一个轴上。

在分布内，正则或调好的分类器要么赢要么打平。 这和笔者的闸门集合上正则以 1.000 对 0.225 获胜是同一个位置。只要能收集到标签，训练一个小模型更便宜、更快、也更准。那是很早以前就在做的事。

差距是在分布是新的、又没有标签的时候拉开的。 分布外的垃圾邮件上是 98.6% 对 73.0%。调好的分类器在自己没见过的形状面前垮掉，而这一侧撑住了。决策模型的位置，是无法收集数据、打上标签再训练的判断。每次情况都是新的所以收不到标签，判断却要以秒为单位做出的地方。

笔者的音译判别为什么失败，也能用这个框架解释。那个判断需要的不是一般性的推理，而是韩语技术文档里哪种说法已经定型这种特定领域的知识；对一个用英语决策任务训练出来的 9B 复现实现来说，那不是分布外，而是根本不存在的知识。把规则写成文字给它也不管用的原因就在这里。

在 TechCrunch 的报道里，做 Pi harness 的 Earendil 的 CTO Armin Ronacher 这样说。

At the end of the day, it delegates the hallucination problem a little bit to the user.

不是消除了幻觉，而是把判断交给了开发者。TypeSafe 文档也写着，校准是对一批预测才成立的性质，并不保证单个答案是对的；公开发布文章里幻觉率 0% 那根柱子下方的 Nuance 条目写着 "Our number is not empirical"。形式有保证，内容没有。

jevable 上的 194 个项目

在笔者的数据上失败了，于是去看别人把它用在了哪里。jevable.com 是一位叫 Nikunj 的开发者把 X 上出现的 Jev 项目逐个审核后汇集起来的独立策展站。截至 2026 年 9 月 23 日共 194 个，登记日期集中在 9 月 16 日到 20 日之间。其中 152 个是在 9 月 18 日一天之内进来的。那是公开三天之后。

不按类别，而按“问什么”重新分组，就得到三种形状。下面的数字都是发帖人自己写在帖子里的值。

第一，分类与路由。 给 1,500 封邮件分类，给税务文件分类，19 秒花 $0.12 给 1,891 条竞品广告分类，对一个 PR diff 做 14 项 typed check，从 Android 通知里判别广告，2.9 秒给 26 张建筑图纸分类。和开头的音译闸门是同一种形状。正如前一节的表所说，这是标签每天都在累积的位置，时间一长，用自己的标签训练出来的小分类器会赢或者打平。Jev 的优势在于还没有标签的第一天。

第二，行动选择循环。 接在 Browser Use 上，7 秒花 $0.0039 完成机票搜索的 browser agent；用语音操作 Mac 的 computer use；每当 Mario 死掉就把 VM fork 成四路、挑活下来那一路继续的游戏；每条消息都要为 3D 角色的嘴、眉毛、视线等十个部位做决定的表情引擎。每一步的 action space 都在变，所以收不到标签，而判断要压到秒以下。这正是分布外垃圾邮件上差距被拉开的那个位置。Games 以 39 个成为最大类别，笔者认为原因也在这里。游戏是错了也能回退的行动选择循环。

第三，把概率直接展示给用户的 UI。 不给答案只给判定的 Ask Jev，用概率挑选下一个问题的分支表单 JevForm，用技术深度、戏剧性等六个滑块重新排列 Hacker News 首页的 Upweight。阈值不写进代码，而是由人来读概率，所以本文追究的校准要求在这里最低。

有一点很显眼。194 条说明文里写了成本的有 30 条，写了速度的有 53 条，而写了准确率或基准线的只有 7 条。说明文只收录原帖的开头部分，所以这是下限，但方向是明确的。快和便宜第一天就能知道，对不对却要测了才知道，而测的人很少。那 7 条里有一个是 jevcal。它说大家都在凭感觉挑阈值，于是做成一个工具：放进自己的数据和目标准确率，就返回阈值和可自动处理的比例。这正是把下一节要推荐的步骤原样做成了工具。

画线的步骤

本文的结论是这个。不要把模型返回的概率当作规格来读，而要在自己的数据上亲手测量，再去划线。

测量的步骤是这样。收集一百来条带标签的数据，做一张按概率区间划分的实际命中率表，然后把阈值从上往下降，看切点以上区间的错误率。定好误差预算之后，守得住这个预算的最大覆盖率就是可自动化的比例。笔者的实验里确信度 0.9 以上区间的实际命中是 0.240，这一点用 102 句就显露出来了。

刻度偏了大多是可以修的。 过度自信均匀铺在所有区间上时，一个温度参数就能把大部分对齐。Kev 也是这样把 ECE 从 0.106 降到 0.042 的。问题在于要调那个温度就需要该分布的标签，而生产环境里缺的恰恰是这个。何况温度改变不了概率的顺序，所以可自动化的比例并不会跟着上去。因此比起刻度，顺序更重要；比起 ECE，误差预算覆盖率是更实用的指标。

如果把文档示例里用的 0.9 原样写进代码，这道闸门会悄悄改错 38 处。因为不报错，所以是难以察觉的失败。TypeSafe 文档也在那段示例的正下方写了要用自己的数据试一试。写进代码的，通常不是下面那句话，而是上面那个数字。

就算没有 key，至少测量这一步今天就能做。Kev 以 Apache-2.0 公开着，在笔记本上就能跑。

希望各位数一数，现在运营的服务里只向大模型问是/否的调用有多少个。在把那些调用搬到决策模型之前，建议先测一测搬过去之后该把线划在哪里。笔者守住了这个顺序，才能定下不去动那道闸门。拿到 Jev 的 key 之后打算把同一批集合再跑一遍，那时如果结论变了，也会写下来。

笔者喜欢声明式的代码。打开 overlay、关闭它、在其中做异步处理，这一连串行为笔者认为应该由 overlay 自己管理。调用方持有 isOpen 并来回切换的做法，会把处理状态的代码和渲染该状态的组件放到两个不同的地方。

然而笔者在公司负责的页面，模态框恰恰相反。是否打开被放在全局 store 里，调用方打开，调用方关闭。连关闭模态框的代码和接收结果的回调,都是调用方直接写的。所以笔者花了很长时间琢磨如何把它挪向声明式的方向，最后干脆重写了一遍。

做这项工作时笔者看了 overlay-kit。它和笔者想要的接口很接近。本文记录 overlay-kit 的声明式接口，以及笔者如何设计公司内部的模态框系统。

曾经用状态持有的模态框

笔者在关于状态管理的文章里，把模态框的开关标志当作最简单的局部状态的例子。笔者写道，那是只在一个组件内部使用、外部既无需也无权知道的状态。这个看法现在依然成立。只是一旦模态框有了几十种、彼此层叠出现、还必须把结果值返回给调用方，这个状态就不会再留在组件内部了。

笔者接手的代码把打开的模态框列表放在全局 store 里。由于是公司代码，下面的例子只保留结构、替换了标识符。

const [openPopup, closePopup] = useModalStore(
  useShallow((state) => [state.openPopup, state.closePopup]),
);
 
const handleAddNote = useCallback(() => {
  openPopup(PopupType.ADD_NOTE, {
    itemId,
    onClose: () => closePopup(PopupType.ADD_NOTE),
    onSubmit: (note) => {
      closePopup(PopupType.ADD_NOTE);
      saveNote(note);
    },
  });
}, [closePopup, openPopup, itemId]);

这段代码让笔者别扭的地方有三处。

第一，打开用的函数必须从 hook 里取出来。 openPopup 和 closePopup 是要从 store 中选取的值，因此只能在组件内部拿到。这意味着打开模态框的代码走不出组件。想在用不了 hook 的地方打开模态框，比如拦截 API 响应的位置或路由守卫，就只能把那个函数当作参数一路传下去。

第二，结果通过回调返回。 笔记是否保存了、用户是否直接关掉了，要通过 onSubmit 和 onClose 两条分支来接收。打开模态框之后要做的事都得写进回调里。如果需要接连打开两个模态框，回调里就会再套一层回调。

第三，关闭的责任在调用方。 closePopup(PopupType.ADD_NOTE) 是调用方来调的。模态框并不关闭自己，而是打开它的那一方记着它是哪一种模态框，然后去关。所以同一个常量会在一个函数里出现三次。

这三点的共同之处在于，打开一个模态框，调用方要写三种代码：打开的代码、接收结果的回调，以及关闭的代码。

如果说决定显示什么才是调用方的职责，那么这里调用方连之后的事情也一并扛下了。尤其是 closePopup(PopupType.ADD_NOTE) 用字符串常量指名要关闭的对象。写成别的模态框的常量也照样能通过类型检查，因为它们属于同一个枚举，结果关掉的是别的模态框。

等待结果的接口

那么这三点中可以减掉哪一个呢。笔者得到的答案是，把打开模态框变成一次函数调用，并让这个函数返回一个携带结束结果的 Promise。

const result = await openModalAsync('ADD_NOTE', { itemId });
if (result.reason !== 'confirmed') return;
 
await saveNote(result.value);

变化有三点。打开用的函数从 hook 变成模块函数，因此可以在组件外调用。结果从回调参数变成返回值，因此后续处理留在了调用函数自身的流程里。而关闭这件事交给了模态框组件自己。

由于返回类型是 Promise<ModalResult<V>>，模态框的结束被收拢成了一个值。

Promise 只会结束一次。对已经结束的 Promise 再次 resolve 不会发生任何事，所以结束的原因必须全部塞进这一个值里。于是笔者把 reason 分成了五种：用户确认了、用户明确取消了、没有值就关闭了、被同类型的新模态框替换了，或者因整体清理被强制结束了。若只用一个布尔值，"取消"和"整个页面被清理掉"就成了同一个值，而在需要善后的流程里必须区分这两者。

反过来，如果不结束它，调用方就会永远等下去。回调不调用也不会发生什么，但 await 会一直不返回。因此每当新增一条把模态框从画面上移除的路径，笔者都得确认那条路径是否也结束了 Promise。替换和强制结束各自拥有一个 reason，正是出于这个原因。

overlay-kit 的调用处

toss 的 overlay-kit，调用处长这样。

const confirmed = await overlay.openAsync<boolean>(({ isOpen, close }) => (
  <ConfirmDialog
    open={isOpen}
    onConfirm={() => close(true)}
    onCancel={() => close(false)}
  />
));

笔者认为是好接口的地方有三处。

打开的是什么，就写在调用处。 笔者做的那一版传的是 'ADD_NOTE' 这样的字符串 key。这个 key 对应哪个组件，由 registry 文件知道。那是一个只装着一个对象的文件，把字符串 key 和加载该模态框的 import() 函数配成一对。

export const modalImporters = {
  ADD_NOTE: () => import('.../add-note-modal'),
  CONFIRM: () => import('.../confirm-modal'),
  // 모달 종류만큼 이어진다
} as const;

overlay-kit 把 JSX 直接写在那里。读代码的人不必跳到那个文件，就知道会弹出什么。

结果的类型在调用处确定。 openAsync<boolean> 的类型参数既是 close 的参数类型，也是 await 的结果类型。不需要为每个模态框单独声明结果类型再登记到表里。

关闭和移除是分开的。 controller 接收的 props 有四个：overlayId、isOpen、close、unmount。close 把 isOpen 设为 false，组件原样保留。真正移除它的是 unmount。官方文档关于打开和关闭 overlay 的说明是这样解释的。

之所以会有这样的差别，是因为使用 close 时，为了展示 overlay 关闭的动画，会把它继续保留在内存中。

笔者做的那一版没有这个区分。一关闭就立刻从列表里移除。这也就意味着笔者把关闭动画交给了组件库，并且只处理了能这样做的页面。

从 overlay.open 到渲染

接口合意之后，接下来好奇的就是内部。一个模块函数要在 React 树里画出组件，中间必须有什么东西把两边连起来。

事件与 reducer

overlay.open 不改变状态。它只发出一个事件。

// packages/src/event.ts
const open = (controller: OverlayControllerComponent, options?: OpenOverlayOptions) => {
  const overlayId = options?.overlayId ?? randomId();
  const componentKey = randomId();
  const dispatchOpenEvent = createEvent('open');
 
  dispatchOpenEvent({ controller, overlayId, componentKey });
  return overlayId;
};

接收方是 OverlayProvider。Provider 持有一个 useReducer，订阅事件并把 ADD 送进 reducer。这里要留意的是 isOpen 是以 false 进入的。

// packages/src/context/provider/index.tsx
const [overlayState, overlayDispatch] = useReducer(overlayReducer, {
  current: null,
  overlayOrderList: [],
  overlayData: {},
});
 
const open: OverlayEvent['open'] = useCallback(({ controller, overlayId, componentKey }) => {
  overlayDispatch({
    type: 'ADD',
    overlay: { id: overlayId, componentKey, isOpen: false, isMounted: false, controller },
  });
}, []);

然后在 controller 挂载后的下一帧送入 OPEN，把 isOpen 变成 true。

// packages/src/context/provider/content-overlay-controller.tsx
useEffect(() => {
  requestAnimationFrame(() => {
    overlayDispatch({ type: 'OPEN', overlayId });
  });
}, [overlayDispatch, overlayId]);

这里有一处和笔者预想的不一样。

状态并不在 React 之外。 因为是用模块函数打开的 API，笔者以为 store 也会在模块层级，实际上却是 Provider 内部的 useReducer。在 React 之外的只有事件总线，而它并不持有状态。overlay 被渲染为 Provider 的 children 旁边的兄弟节点。它不使用 createPortal，也不 import react-dom。

还有一处值得注意。从调用处看是 overlay.open() 一行，而其内部是一套顺序固定的流程：发出事件、把 ADD 送进 reducer、等一帧、再送入 OPEN。声明式的接口并没有消灭命令式的代码，而是把它挪到了边界的另一侧。

打开的一侧与关闭的一侧

前面看到的 requestAnimationFrame，和上一节看到的 close 与 unmount 的分离，乍看是两回事。实际上它们是堵住同一个约束两端的两个装置。

这个约束就是：CSS 过渡只有在起始状态和结束状态都被真正渲染出来时才会执行。MDN 的 CSS 过渡文档针对刚添加到 DOM 的元素给出了这样的警告。

This is treated as if the initial state had never occurred and the element was always in its final state.

失败在这里表现为两种形态。打开时因为没有起始状态而不执行，关闭时因为结束状态还没画出来元素就消失了而不执行。

关闭的一侧之所以归使用者负责，原因就在最后一行。打开的一侧，库知道"一帧就够"这个常量。关闭的一侧，库无从知道动画是 200 毫秒还是 400 毫秒。

以 unmount 交出的关闭

关闭的一侧能够成立，依据在 reducer 里。CLOSE 只翻转 overlayData 中的 isOpen，不碰 overlayOrderList。Provider 遍历那个列表来渲染，因此只要还留在列表里，组件就活着。只有 REMOVE 把它从列表中移除，才会真正卸载。

不过 rAF 并非总是必要。 react-transition-group 默认不会在首次挂载时执行 enter 过渡。即使 in 已经是 true 也会跳过，必须开启 appear。overlay-kit 的 rAF 会在挂载之后把 isOpen 从 false 改为 true，正好覆盖了这种情况。

用 Promise 包起来的二十行

openAsync 并不是另一套实现，而是包住 open 的一层薄封装。

// packages/src/event.ts
const openAsync = async <T>(controller: OverlayAsyncControllerComponent<T>, options?: OpenOverlayOptions) => {
  return new Promise<T>((_resolve, _reject) => {
    open((overlayProps, ...deprecatedLegacyContext) => {
      const close = (param: T) => {
        _resolve(param);
        overlayProps.close();
      };
      const reject = (reason?: unknown) => {
        _reject(reason);
        overlayProps.close();
      };
      const props: OverlayAsyncControllerProps<T> = { ...overlayProps, close, reject };
      return controller(props, ...deprecatedLegacyContext);
    }, options);
  });
};

它所做的全部事情，就是把传给 controller 的 close 换掉。原本的 close 不接收参数，这里则接收参数，用它 resolve Promise，然后再调用原来的 close。结果类型之所以在调用处确定，原因也在这里。T 既是 close 的参数类型，也是 Promise 的类型。

不过这个结构有一个漏洞。resolve 只在 close 被调用时发生。因此如果只用 unmount 移除 overlay，Promise 就会永远停留在 pending。这一点记录在 issue #169 里，笔者认为需要解决，但该 issue 目前仍然是打开状态。

resolve 发生在 close 这一点还有另一层含义。那是关闭开始的时刻，而不是关闭动画结束的时刻。如果流程是拿到确认后调用 API 就没问题，但如果是拿到确认后打开下一个模态框，那么前一个还在消失的过程中，后一个就已经升起来了。

设计绕了一圈的地方

为了探究设计的过程，笔者顺着提交记录看了一遍，发现这个结构并非一开始就是如此。1.0 用的是和现在相同的事件加 reducer 的组合。1.2.0 把状态挪到模块层级的外部 store，改用 useSyncExternalStore 读取，而 1.8.0 又退回了 reducer。

退回的理由写在 issue #148 里。

useSyncExternalStore resolves tearing issues, but it doesn't work well with suspense.

在 overlay 内部取数据导致 suspend 时，React 会警告说组件在响应同步输入的过程中 suspend 了。挪到外部 store 的本意是让人不用 hook 也能读到 overlay 的状态，而当时的 PR 正文里写明了这个目标并没有按预期达成。最终目标是靠 hook 解决的，只有存储方式回到了原处。

笔者从这段记录里得到的不是结论，而是一条判断标准。把状态放到 React 之外，调用位置会变自由，代价是留出了与 React 调度错位的余地。overlay-kit 只把调用位置放到了外面，状态留在了里面。

用同一个 id 再次打开时

读 reducer 的时候有一处卡住了笔者。ADD 的最前面有这样一个分支。

// packages/src/context/reducer.ts
case 'ADD': {
  if (state.overlayData[action.overlay.id] != null && state.overlayData[action.overlay.id].isOpen === false) {
    const overlay = state.overlayData[action.overlay.id];
    if (overlay == null || overlay.isOpen) {
      return state;
    }
    return {
      ...state,
      current: action.overlay.id,
      overlayData: { ...state.overlayData, [action.overlay.id]: { ...overlay, isOpen: true } },
    };
  }
  // ...

指定 overlayId 打开一个 overlay，close 之后再用同一个 id 打开，就会走进这个分支。但返回值原样沿用了既有的 overlay 对象。

新传进来的 action.overlay 的 controller 哪里都没有被用到。

只靠阅读还不能确信，于是笔者把库的仓库拉下来，自己加了测试。准备两个渲染不同内容的组件，用同一个 id 依次打开。

const ControllerA = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">AAA</div> : null);
const ControllerB = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">BBB</div> : null);
 
overlay.open(ControllerA, { overlayId: 'id-close' });
overlay.close('id-close');
overlay.open(ControllerB, { overlayId: 'id-close' });

结果如下。在 overlay-kit 1.9.0 时点的 main 分支上用 vitest 执行。

第三行是文档作为功能来说明的行为，所以和预期一致。问题在第一行。

被忽略的新 JSX

笔者在这里又确认了一件事。同一个 reducer 的后半部分有这样一段注释。

/**
 * @description Brings the overlay to the front when reopened after closing without unmounting.
 */
overlayOrderList: [...state.overlayOrderList.filter((item) => item !== action.overlay.id), action.overlay.id],

意思是关闭之后再次打开会把 overlay 带到最前面。可是因为前面的分支会先 return，这一行在那种情况下根本不会执行。笔者把两个 overlay 叠着打开，对压在下面的那个执行 close 再重新打开，DOM 顺序并没有变化。

与注释不符的实际行为

不过笔者没有确认这在画面上是否会立刻表现为问题。测试只看到 DOM 顺序为止，而大多数对话框库都使用自己的 z-index 或 portal，所以 DOM 顺序并不等同于视觉顺序。

笔者做的那一版把同样的情况作为选项暴露出来。再次打开同一种模态框时，由调用方选择是保留既有的还是用新的 props 替换。选择替换的话，既有的 Promise 会以 replaced 结束。前面把结果类型分成五种的原因之一就是这个。

两种设计的差异在这里显现出来。 笔者的做法把模态框当作数据。字符串 key 和 props 都在 store 里，所以之后可以替换、可以更新。overlay-kit 把模态框当作函数。controller 是一个闭包，一旦存下来，就没有办法从外部改变它的内容。

在调用处写 JSX 的代价

那么，在调用处写 JSX 的方式是不是总比字符串 key 的方式更好呢。笔者认为并非如此。要付出的代价有三个。

代码分割从默认值里掉了出去。 调用处写 JSX，意味着调用处 import 了那个组件。如果模态框是一个沉重的编辑页面，而按下那个按钮的用户只是少数，那份重量就会进到列表页面的 bundle 里。

React.lazy 在 controller 内部是可以工作的。笔者用和前面测试相同的方式量了一下：open 之前模块没有被加载，打开时 Suspense 的 fallback 先出现，然后主体才渲染出来。

const Heavy = React.lazy(() => import('./HeavyModal'));
 
overlay.open(({ isOpen, close }) => isOpen ? (
  <Suspense fallback={<Spinner />}><Heavy onClose={close} /></Suspense>
) : null);

所以差别不在能不能，而在默认值是什么。

笔者做的那一版，registry 文件里的值全都是 import() 函数，因此代码分割在结构上是被强制的。overlay-kit 则需要在每个调用处手写。

调用 unmount 的位置要由使用者决定。 只调用 close 就收手的话，overlay 的信息会留在内存里。官方文档也警告了这一点，并针对每个设计系统分别说明该把 unmount 挂在哪里。MUI 和 Mantine 有过渡结束的回调，挂在那里即可，而对于没有这类回调的库，文档建议按动画时长设置一个定时器。指引文档要按库分开写，这件事本身就是这个决定的成本。

overlay 在 Provider 所在的位置渲染。 因为不使用 portal，同一份代码也能在 React Native 上运行，这是优点。反过来说，在 OverlayProvider 之下提供的 context，在 overlay 内部是看不到的。打开依赖路由或表单 context 的模态框时，需要先确认这一点。

声明式这个词的范围

写到这里，有一件事让笔者在意。笔者是以"声明式"来称呼这个接口开篇的，可 overlay.openAsync(...) 怎么看都是一次函数调用。

先从定义说起。React 官方文档是这样划分两者的。

In React, you don't directly manipulate the UI--meaning you don't enable, disable, show, or hide components directly. Instead, you declare what you want to show, and React figures out how to update the UI.

同一份文档举的比喻更鲜明。命令式是给开车的人一个路口一个路口地报路，声明式则是坐上出租车只说目的地。

声明式的接口并不是消灭命令式的流程，而是把它挪到边界的另一侧，并给那条边界起个名字。 前面看到的 overlay-kit 内部正是如此。调用处只有一行，而内部跑着发出事件、两次 dispatch 的流程。

那么来看各个项目把这个词用在哪里。overlay-kit 的文档把以往的方式称为命令式。它所指的是用 useState 持有开关标志、在事件处理器里翻转那个值的代码。相反，它称为声明式的，是把 overlay 当作行为而非状态来处理的那一侧。toss 技术博客的关于声明式代码的文章把这个词定义得更宽：声明式的代码就是抽象层级更高的代码，而把显示 overlay 这一行为抽象出来的 hook 就是一个例子。

于是笔者决定把这个词收窄成这样。调用方不写关闭的代码。 什么时候关、关闭过程中留下什么，由 overlay 一侧决定；调用方只写显示什么，以及期望拿回什么结果。

按这个标准来看，用 useState 持有 isOpen 的代码，和把打开的列表放在全局 store、由调用方来关闭的代码，站在同一边。只是存放位置不同，关闭的语句由调用方来写这一点是一样的。

结语

笔者在公司代码里改掉的，归根结底并不是存放位置。而是关闭的代码由谁来写。

即便在使用全局 store 的时期，状态也已经在组件之外了，但打开和关闭的语句依然留在调用处。换成一行 await 之后，那些语句才进到模态框内部。

overlay-kit 抵达了同一个位置之后又往前走了一步：把显示什么也写在调用处。笔者认为那个接口读起来很好。而在写这篇文章的过程中，笔者也弄明白了这一步的代价是什么。

那是把模态框当作函数还是当作数据的差别。 在调用处写 JSX，controller 就成了闭包，而闭包一旦被存下来，其内容就无法从外部改变。用同一个 id 再次打开时新的 JSX 被忽略，正是从这个结构里来的。用字符串 key 来处理，模态框就变成了装在 store 里的值，可以替换、可以更新、可以代码分割，但调用方只会知道一个名字。

笔者认为，在挑选库的时候，"喜欢这个接口"的感觉是个相当可靠的信号。只是那种感觉究竟指向什么，至少该用语言表述一次。不表述出来，就分不清自己喜欢的是接口本身，还是使用这个库的人们的口碑。也想建议读到这里的各位，针对现在正在用的库做一次这样的梳理。

笔者在验证 TypeSafe AI 公开的决策模型 Jev 的说法时，必须先把这个概念理清楚。Jev 不返回句子，而是为每个选项返回概率，并把校准作为训练目标。要检验这个说法，得先知道校准是什么，以及它在现有模型中为什么会偏。

准确率与校准

首先必须区分准确率和校准。准确率是能答对百分之几，校准是知不知道自己能答对百分之几。把说过降水概率 70% 的那些天汇总起来，如果实际十次里下了七次雨，那这个预报就是校准良好的。它不代表准确率高。它代表预报知道自己的极限。只有 60% 正确率的模型，只要自己说 60%，校准就是满分。

刻度偏离的方向有两个。模型说出的概率高于实际命中率，叫作 overconfidence（过度自信）；低于实际命中率，叫作 underconfidence。把说出的概率放在横轴，把该概率区间的实际命中率放在纵轴，两者在哪里分开就一目了然。这样画出的图叫作 reliability diagram。

曲线贴着对角线，说明模型说多少就答对多少。越往对角线下方垂，相对于它说出的概率，答对得就越少。

衡量这种偏离的指标是 ECE（expected calibration error）。按照 Guo et al. 2017 的定义，它把每个概率区间里“说出口的概率”与“实际命中率”的差值，按该区间的样本比例加权平均，0 为完美。下面的代码把这个公式写了出来。它比较一个 10 道题答对 6 道的模型，在每次都说 0.6 和每次都说 0.95 时的情况。

// Guo et al. 2017 의 식 (3). 구간은 등간격 10개(논문 실험은 15개), 경계는 왼쪽 닫힘
function ece(preds, M = 10) {
  const bins = Array.from({ length: M }, () => ({ n: 0, hit: 0, conf: 0 }))
  for (const { p, correct } of preds) {
    const b = bins[Math.min(M - 1, Math.floor(p * M))]
    b.n++
    b.hit += correct ? 1 : 0
    b.conf += p
  }
  return bins.reduce(
    (sum, b) => (b.n ? sum + (b.n / preds.length) * Math.abs(b.hit / b.n - b.conf / b.n) : sum),
    0,
  )
}
 
// 10문제 중 6문제를 맞힌다
const answers = Array.from({ length: 10 }, (_, i) => ({ correct: i < 6 }))
console.log(ece(answers.map((a) => ({ ...a, p: 0.6 }))).toFixed(3)) // 매번 0.6 이라고 말할 때
console.log(ece(answers.map((a) => ({ ...a, p: 0.95 }))).toFixed(3)) // 매번 0.95 라고 말할 때

这是 2026-10-08 用 Node v24.16.0 运行的结果。

0.000
0.350

两种情况的准确率都是 0.6。只是说出的概率变了，ECE 就从 0 升到 0.35。不过公式里取了绝对值，所以 ECE 只衡量偏离的大小，不知道方向。每次都说 0.25、同样答对 6 道题的模型，ECE 也恰好是 0.35。究竟是 overconfidence 还是 underconfidence，要看 reliability diagram，或者平均确信度减去准确率的值才知道。

RLHF 的目标函数

那么，用人的反馈打磨过的模型，为什么这个刻度会偏呢。首先要看 RLHF（reinforcement learning from human feedback）在优化什么。用人的偏好比较来建立奖励模型这一骨架出自 Christiano et al. 2017，把它搬到语言模型上的早期工作是 Ziegler et al. 2019，InstructGPT 又把它用于指令跟随。这时被推高的值，是模仿人类偏好的奖励模型的分数。语言模型方面的工作会在奖励上加 KL penalty，让模型不要离开始强化学习之前的模型太远，InstructGPT 还混入了预训练数据的梯度（PPO-ptx），但推高的对象仍然是那个分数。

对聊天机器人来说，人的偏好是对的目标。问题在于这种偏好偏向回避流露不确定性的语气。Zhou et al. 2024 在四个公开偏好数据集上表明，标注者较少选择含有 "I'm not sure, maybe" 这类弱化表达的回答。差异很小，但显著。不过，他们并没有更多地选择含有强调确信的表达的回答。Leng et al. 2025 表明，奖励模型不管回答的实际质量如何，都会给写出高确信度分数的回答更高的分数。两者都不是关于 token 概率，而是关于文字中的确信表达（verbalized confidence）的结果。推出替代 RLHF 的训练方法的 TypeSafe，也在自家的入门文档中写道，RLHF 可能会奖励听起来很有把握的幻觉（confident-sounding hallucinations）。这是推销替代方案的一方的立场。

GPT-4 的校准曲线

在 token 概率上也观察到了同一方向的偏离。GPT-4 技术报告正文的 Figure 8 把预训练模型和 post-training 模型的 reliability diagram 并排放在一起，图注是这样写的。

Right: Calibration plot of the post-trained GPT-4 model on the same subset of MMLU. The post-training hurts calibration significantly.

横轴是模型给 MMLU 选择题的 A、B、C、D 每个选项分配的概率（logprob），纵轴是该区间的实际命中率。按 Figure 8 上标出的数字，预训练模型的 ECE 是 0.007，经过 PPO（RLHF 中朝着提高奖励模型分数的方向更新模型时使用的强化学习算法）的模型是 0.074。恶化了十倍以上。

在 Figure 8 右侧（PPO）的面板中，0.4 以上区间的柱子在对角线下方，但 0.1 到 0.3 之间的区间反而在对角线上方。0.1 到 0.9 之间的柱子平平地挤在实际命中率约 0.3 到 0.5，所以模型说出的概率升高了，命中率却几乎跟不上。0.074 里也混进了这些 underconfidence 的区间。而且正如 Guo et al. 指出的，reliability diagram 不显示每个区间有多少样本，所以不能认为柱子离对角线的距离和该区间对 ECE 贡献的大小成比例。

这块面板和上面的概念图有两点不同。首先，它不像概念图里的曲线那样只往对角线下方垂，而是穿过对角线一次。其次，它把四个选项的概率全都放进了区间，所以也和上面代码那样只用所选答案一个概率来衡量的定义不同。所以笔者不把 0.074 和上面代码的 0.35 放在同一把尺子上比较。

那么为什么会变差。报告正文只写了预训练模型校准得很好、post-training 之后校准下降，没有说原因。线索在 Anthropic 的 Kadavath et al. 2022 里。他们用自家语言模型训练出的 RLHF 策略，表面上看校准非常差。论文说这并不意外，因为 RL fine-tuning 往往会把预测往获得最多奖励的行为方向收拢。这不是论文的主题，而是顺带做的一个简短实验。然而，对所有评估都使用同一个温度 T=2.5 之后，三项评估中的校准问题大体上都解决了。温度是用来除 logit 的值，大于 1 时它保持答案的顺序不变，只把概率分布摊平。笔者把一个值就大体解决了问题这一结果，理解为偏离并不集中在某些区间，而是整个分布都往一边收窄了。论文也附上了一句保留：更强的 RL 训练可能会以这种方式无法修复的形式破坏校准。

这是 Anthropic 模型上的结果，所以不能直接搬来当作 Figure 8 的原因。前一节的研究处理的也是文字中的确信表达。笔者没能找到把“人回避不确定的语气”这一结果和 token 概率的偏离直接连起来的一手证据。

代码拿到的概率

Figure 8 里的概率是 token 的对数概率。要拿到同一类值，按照 OpenAI API 规范，在 Chat Completions 请求里把 logprobs 设为 true，再用 top_logprobs 在 0 到 20 之间决定每个 token 位置返回多少个候选。让模型在回答的同时用数字说出确信度，这样拿到的值是用文字说出的确信，和 token 概率是不同的值。

研究这两种值的论文比较的是不同的组合。Tian et al. 2023 报告说，在 ChatGPT、GPT-4、Claude 这样的 RLHF 模型内部，用文字说出的确信通常比条件概率校准得更好，在三个基准上常常把 ECE 相对降低约 50%。不过在这项比较中，权重未公开的模型的条件概率不是 API 的 token 概率，而是把同一个问题采样 10 次、按得出该答案的比例估计的值。前面提到的 Leng et al. 则报告说，与 RLHF 之前的模型相比，RLHF 模型在用文字说出的确信上更 overconfident。两个结果可以同时成立。而且 0.074 是 2023 年 GPT-4 post-training 模型在 MMLU 子集上得出的值，不能原样套用到你现在通过 API 调用的模型上。

总结

总结一下，校准不是能答对百分之几的问题，而是知不知道自己能答对百分之几的问题，ECE 是衡量这种偏离大小的数字。方向要看 reliability diagram，或者平均确信度减去准确率的值才知道。RLHF 推高模仿人类偏好的奖励模型的分数。Kadavath et al. 认为，这种优化往往会把预测往获得更多奖励的方向收窄。有研究表明，人较少选择流露不确定性的回答，而奖励模型不论质量如何，都会给写出高确信度分数的回答更高的分数。在 GPT-4 上，post-training 之后 ECE 从 0.007 变成了 0.074，但 OpenAI 并没有写出原因。代码拿到的概率是 token 概率还是文字中说出的确信，校准结果也会不同，所以不管是哪一种，都要在自己的数据上重新测一遍。

把校准作为训练目标的决策模型 Jev 的概率是否真的诚实，将在决策模型，Jev 与 Kev中讨论。

也希望读到这里的各位，在把模型返回的概率作为阈值写进代码之前，至少测一次：这个模型是以什么为目标训练的，在自己的数据上刻度准不准。

做开发时，我花在弄清楚该做什么上的时间，和写代码的时间一样多。与产品经理来回确认需求，与设计师对齐界面，向懂领域的人询问某个术语究竟指什么。而这个过程一旦错位，代价远大于把代码写错的代价，这一点我已经经历过好几次。

最近我读了 James Samuel 写的工程领导者的日常工作。作者把领导者的工作分成六项，最先讨论的就是信息收集。理由是所有的决策、方向和行动，都依赖于对当下正在发生什么的准确理解。

我确实希望将来能担任领导角色，但读到这一段之后浮现的想法有些不同。如果领导者最先处理的工作是信息收集，那么对一线执行者而言，与之对应的就是需求的梳理。我现在处理需求的方式，日后就会成为我处理组织信息的方式。

这篇文章并不想谈领导力。它谈的是我作为一线执行者与其他职能沟通时，究竟做错了什么，又能把什么当作工具。先说结论：我逐渐认为这不只是态度问题。有一个可以替代的说法叫 ubiquitous language，我们来看看它是什么。

同一个词，不同的含义

Martin Fowler 在Bounded Context一文中举了电力公司的例子。我遇到的错位，相当一部分正是这种形态。

在这里，“meter”这个词在组织的不同部分含义有微妙差别：它指的是电网与某个地点的连接，还是电网与某位客户的连接，抑或是物理电表本身？

here the word 'meter' meant subtly different things to different parts of the organization: was it the connection between the grid and a location, the grid and a customer, the physical meter itself

同一个“meter”，在组织的不同部门里指的是微妙不同的东西。Fowler 还补充说，这种混乱并非那个案例的偶然。他说自己反复见到 Customer、Product 这类多义词引发同样的混乱。

这并不是因为与会者不擅长开会。只要组织内部存在不同的语境，同一个词分化就是自然的事；放任不管，最终连代码也会跟着分化。

这个话题的技术背景，我在领域模型里讨论过一次。那时谈的是如何在代码中表达模型。而本文要谈的是那个模型形成之前，人与人之间对话的阶段。

有两种含义的词

那么，这种事为什么会结构性地反复出现呢？有两条解释路径。

一条来自组织结构。Mel Conway 于 1968 年发表在 Datamation 上的论文How Do Committees Invent?指出，组织无法灵活改变自身沟通结构的程度有多深，它就会把自己的形象刻印到所产出的一切设计物上。通常被引用为康威定律的那一句话，其实是作者日后自己整理出的表述，而我觉得 1968 年原文中的这段描述更为直接。

我从这句话里读出的实务含义，是“刻印”这个说法。因为它意味着术语的分化不会止于对话，而是原封不动地留在产出物里。前面的“meter”就是如此。如果各方对“meter”的范围理解不同却各自动手去做，这个差异不会留在会议纪要里，而会留在表名、API 响应字段和界面文案里。而从那一刻起，修改的成本就与再谈一次的成本不可同日而语了。

一线执行者能做的和不能做的，在这里分开。改变组织的沟通结构超出了执行者的能力范围。但让术语的边界变得可见，是当下就能做的事。也就是写清楚本文档中某个词的含义范围，若与其他团队使用的词不同，就明确指出不同。后面要看的工具，全都是让这件事变容易的装置。

另一条则更为根本。从认知科学的角度看，协作本来就只能建立在共享的背景之上。Herbert Clark 与 Susan Brennan 于 1991 年撰写的Grounding in Communication以钢琴二重奏开篇。两位演奏者若不预设大量的共享信息，也就是 common ground，甚至无法开始对齐内容。这里的 common ground 指的是相互知识、相互信念与相互假设。作者还明确指出，一切集体行动都建立在 common ground 及其累积之上。

把这两条并排看过之后，我得到的视角是这样的。术语出现偏差不是事故，而是默认状态。对齐的状态反而是需要付出维护成本的例外。那么由谁、以什么方式支付这份成本，就成了实务上的问题。

积极监视

Evans 在 2003 年出版的 Domain-Driven Design 中提出了 ubiquitous language，也就是共享语言这一模式。它常被简化为“让 developer 和领域专家使用相同的术语”，但读原书会发现处方要具体得多。他要求团队把模型作为语言的骨架，并约定在团队内的一切沟通和代码中坚持使用这套语言。而紧随其后的那句话，对我而言最为重要。

领域专家会对那些别扭或不足以传达领域理解的术语与结构提出异议，而 developer 则留意那些会让设计栽跟头的歧义或不一致。

Domain experts object to terms or structures that are awkward or inadequate to convey domain understanding, while developers watch for ambiguity or inconsistency that will trip up design.

领域专家对不足以传达领域理解的别扭术语与结构提出异议，而 developer 则监视那些会推倒设计的歧义或不一致。

读到这句话后，我修正了对自身角色的理解。在此之前，我在需求会议上把自己视为接收者。我以为产品那边定下来之后，准确接收并实现就是我的工作。可 Evans 界定的 developer 职责并不是接收。而是发现歧义并把它交还回去。这不是消极配合，而是积极监视。

（顺带一提，Fowler 在自己的文章中把这句话写成了“Domain experts should object ... developers should watch”。原书里并没有情态动词。差别虽小，但原书读起来更为断然。那语气不是说这样做比较好，而是说这样做就是这个模式的定义。）

那么歧义该怎么发现呢？Evans 对此也给了答案：在对话中反复使用，术语理解上的差异就会显现。我是这样读这句话的。歧义不是靠精读文档找出来的。无论把需求文档读得多仔细，“meter”这个词具有多种含义的事实都不会浮现。只有把这个词放到实际案例上反复使用，它才会分化。像“其他人把 meter 理解成什么意思？”这样的问题冒出来的瞬间，就是那个分岔点。

最小协作努力原理

我们可能知道这个方法，却仍然无法实践。那么，为什么不反复去问呢？

让我们再回到 Clark 与 Brennan 的论文。作者把“将说出口的内容变成 common ground 的一部分”这一过程命名为 grounding。并针对人们在这个过程中的行为提出了一条原理：最小协作努力原理（the principle of least collaborative effort）。这条原理源自一个观察，即人不喜欢比必要程度更卖力地工作。

关键的段落在这里。

根据最小协作努力原理，人们应当以所需的最少共同努力去完成 grounding。但什么事情耗费努力，会随沟通媒介发生剧烈变化。

By the principle of least collaborative effort, people should try to ground with as little combined effort as needed. But what takes effort changes dramatically with the communication medium.

耗费努力的地方会随媒介发生剧烈变化。在某种媒介中可用的确认手段，在另一种媒介中可能根本不可行，即便可行成本也高得多。作者尤其指出，在对方无法即时接收的媒介中，指望他人来纠正误解的成本会变得非常高，于是说话的人就会设法回避。

这里有一点要事先说明。这篇论文写于 1991 年，作者比较的媒介是面对面对话、电话、书信和电话答录机之类。它并不涉及 Slack 或 Notion。grounding 成本随媒介变化这个框架是作者的，而把它套用到今天的异步工作频道上，是我的解读。

这样套用之后，就能解释我为什么没有反复发问了。在以文本接收需求文档、又以文本确认的环境里，每遇到一处含糊就发一条确认消息，成本很高。你不知道答复什么时候来，还担心问了好几次会显得像是没听懂。于是人自然而然就滑向了自己的解读。

这里需要区分两股力量。一股是媒介抬高了确认成本，这是 Clark 与 Brennan 说的。另一股是担心问多了显得无能，这并非他们的原理所预测的，而属于后文心理安全感那一侧的话题。准确地说，最小协作努力原理预测的是会挑一种更便宜的确认方式，而不是不再确认。收起确认转向猜测，不是原理在起作用，而是 grounding 的失败。而那个解读错了的事实，要等到实现做完之后才会显露。

达到足够的水平

那么每一处含糊都得去问吗？这不现实，我也没见过这么做的人。对于这个问题，论文同样给出了标准，就是 grounding criterion。它指的是双方彼此相信，听者已经在足以支撑当前目的的水平上理解了说话者的意思。作者在此之前还补了一句：完美的理解本来就不可能。

这个标准让我觉得实用的原因，是它把目标调低了。不需要完美地理解需求。只要在足以支撑眼下要做的事的程度上彼此相信就够了。作者还说，目的一旦改变，标准也必须随之改变。

这一点在实务中会成为调节确认力度的依据。在还在探索方向的场合，抓着“这里的 meter 是什么意思？”不放，对话就推进不下去。那个阶段需要的是关于要做什么、为什么做的共识，而不是边界值的确定。反过来，在进入实现之前，这个问题就必须提出来。此时双方必须能够相信彼此对“meter”的范围想的是同一件事，否则代码就会堆在错误的前提之上。

所以，即便遇到同样的含糊，我也会根据当下处于哪个阶段而区别对待。探索阶段就记在清单上先往前走，临近实现时再打开那份清单逐条关闭。推迟确认和放弃确认是两回事。

在这个环节，有一个很适合搭配使用的工具。Matthew Skelton 与 Manuel Pais 的 Team Topologies 把团队之间的互动分为三种模式：在约定的期间内共同发现新事物的 collaboration，一方提供、一方消费的 X-as-a-Service，以及一方帮助并辅导另一方的 facilitation。

它原本讲的是组织设计，但我觉得把它缩小到单场会议来用很实用。如果双方对当下这场对话属于哪种模式的认知不一致，会议就会错位。产品经理认为这是传达既定结论的场合，而 developer 认为这是共同发现的场合，那么 developer 的提问听起来就不像协作，而像抬杠。反过来也有。如果 developer 是来接收已确定的规格，而产品经理还在探索阶段，developer 就会因为拿不到规格而着急。

所以我最近会在会议开头先确认这一点：“这件事还是开放的，还是我们在确认已经定下来的内容？”这一个问题，就能改变之后整场对话的性质。这和把 grounding criterion 按目的做调整是同一回事。

分辨率对不上，对话就会空转

即便对齐了模式，仍有问题残留。我经常遇到的另一种错位，是双方在用不同的分辨率说话。

产品经理用文字给出的需求，大多太过抽象。像“让用户能方便地查看预约记录”这样的句子，看不出有几个界面，也看不出从哪里跳到哪里。反过来，设计师给的稿子又太过具体。连按钮颜色和留白都定好了，反倒难以讨论“这个流程对不对”。

Basecamp 的 Ryan Singer 所写的 Shape Up 精准地点出了这个问题：一上来就从线框图或具体的视觉布局入手，就会被不必要的细节困住，无法按需要的广度去探索。因此Shape Up 提出的方案是介于两者之间的表达。它被称为 breadboarding，概念借自电气工程。面包板是一种具备实机全部元件与接线、却没有工业设计的原型。所以要画的东西也正好三样：可以跳转到的位置（places）、用户可以操作的东西（affordances），以及展示该操作把用户带往何处的连接线（connection lines）。

我看好这个技法的原因，是它是 developer 做得出来的产出物。不必请产品经理写得更详细，也不必等设计师出稿，就可以当场把自己理解的流程画出来，反问一句“我是这么理解的，对吗”。这可以说是执行 Evans 所说的监视（把歧义交还回去）的具体方法。而从上一节的视角看，这是一个降低 grounding 成本的装置。一张图，抵得上用文字来回确认好几轮。

不过这个分辨率比想象中难以维持。画着流程，自然而然就会滑到“这里的按钮放右下角是不是更好”之类的讨论上。我自己也这样过几次。一旦这样滑下去，当场正在讨论的问题，也就是这个流程对不对，就悄悄消失了。流程尚未确定却在敲定按钮位置，等到之后流程一变，那些讨论就会被整块丢掉。

所以在这个阶段，我会刻意维持一张画得不好的图。如果只有方框、箭头和名称，对方也就不会想去挑细节，只会针对流程做出反应。图的完成度低，在这个工具里反而是一项功能。（要按住想画得漂亮的心思，比想象中难）

抽象层级这个概念本身可以成为协作工具，这一点与我在抽象化里谈过的内容相通。那时说的是代码的抽象层级，而对话里也有同样的东西。

把规则、示例和问题分开

对齐分辨率的另一种方法，是把讨论本身结构化。

来看看 Cucumber 项目负责人 Matt Wynne 在 2015 年介绍的Example Mapping。他把许多团队觉得需求讨论困难的原因，诊断为缺乏结构导致耗时又无聊。于是团队既不会定期做，也不会一致地做。我正是如此。需求会议一旦拖长，下次就想快点结束，而草草结束，含糊之处就原样留了下来。

Example Mapping 用四种颜色的卡片来划分讨论。黄色是当下讨论的 story，蓝色是规则或验收标准，绿色是说明该规则的具体示例，而红色是不知道答案的问题。

其中，我认为红色卡片才是核心。其余三种是整理技法，而红色卡片是把“不知道”变成会议正式产出物的装置。说出自己不知道，不再是拖慢会议的行为，而成了会议本该产出的结果。

这为什么重要，只要想想反面情形就很清楚。在没有红色卡片的会议上遇到含糊之处，选项只有两个：现在纠缠下去把会议拉长，或者先跳过之后自己一个人去解读。正如上一节所见，人大多会选后者。可只要多了一张卡片，就出现了第三个选项。记下来往前走，同时不让它消失。会议继续推进，而含糊之处并未被抹去，仍留在清单上。

绿色卡片也起着类似的作用。只写规则时大家都会点头，可一旦有人要写出说明该规则的具体示例，解读就会分开。这可以说是把 Evans 所说的“在对话中反复使用就会显现差异”搬进了会议形式。如果要求每条规则配三个示例，其中总有一个会冒出“咦？这种情况怎么算？”。（以我的经验，那个问题没有出现的会议，不是大家都理解了的会议，而是各自理解得不一样的会议）

类似思路下，BDD 圈子里长期使用的 Three Amigos 也是如此。它主张业务、开发与测试这三种视角各自抛出不同的问题，而Agile Alliance 术语表把这些问题整理为：想解决什么问题，要如何构建解决该问题的方案，以及这个怎么样、可能会发生什么。第三个问题始终不出现的会议会变成什么样，大概不必特意说明。

建立确认未知事项的流程

可是，我们为什么难以打出红色卡片呢？说到这里，就绕不开心理安全感的话题。

Amy Edmondson 于 1999 年发表在 Administrative Science Quarterly 上的论文，是正式确立团队心理安全感这一概念的研究。（论文本身把 1965 年 Schein 与 Bennis 的研究列为源头）它把团队心理安全感定义为一种共享信念，即团队是一个可以承担人际风险的安全场所。说自己不知道、提出反对意见、承认失误，都属于此列。论文调查了一家制造业公司的 51 个团队，结果显示心理安全感与学习行为相关，而这种学习行为在心理安全感与团队绩效之间起中介作用。

不过，这篇论文里让我觉得最实用的句子并不是定义，而是紧随其后的那一句。

多数情况下，这种信念往往是隐性的：被视为理所当然，个人和整个团队都不会对它给予直接关注。

For the most part, this belief tends to be tacit—taken for granted and not given direct attention either by individuals or by the team as a whole.

也就是说，这种信念大多是隐性的，个人和团队都不会对它给予直接关注。

从这里开始是我的推测。论文说到的是这种信念是隐性的，至于“所以做个表格就好”这样的处方，论文里并没有。不过我见过好几次，隐性的东西不会因为宣告而改变。说一句“我们团队是可以问自己不懂的事情的团队”，往往改变不了什么。所以我认为上一节的红色卡片很重要。把“不知道”变成表格里的一个格子，填写它就从勇气变成了流程。

当然，反驳是成立的。在不安全的团队里，红色卡片的格子恐怕就是空着。这个指摘没错，我也无意主张这个工具能创造出安全感。只是，格子存在的话，至少空着这件事会变得可见。这就有了一个可以发问的位置：是因为没人有疑问才空着，还是因为难以开口才空着。

同样的想法也已经进入了实际的文档格式。看看 DDD 社区制作的Bounded Context Canvas，它是一个用于设计并记录单个上下文的协作工具，格子的构成很有意思。名称与目的、战略分类、领域角色、入站与出站沟通，然后是 Ubiquitous Language、业务决策、Assumptions、验证指标，以及 Open Questions。

写共享语言的格子、写假设的格子、写开放问题的格子各自独立。画布的说明写道，书写目的这个行为本身就会迫使模糊的想法被清晰地表达出来，并把整个团队放到同一页上。

我认为这个思路是面对沟通问题最现实的路径。与其试图改变人的态度，不如为那些难以说出口的事情做一个格子。好的结构不是要求人做得好，而是让人容易做好。

这为什么不是偏好问题

读到这里，可能会有这样的反应：说得挺好，可归根结底不就是“好好沟通”吗？那不是性格问题吗？

我也曾这样想过一阵子。但这部分是有数据的。

DORA 在讨论组织文化时，引用了社会学家 Ron Westrum 的分类：权力导向的 pathological、规则导向的 bureaucratic，以及绩效导向的 generative。而DORA 的官方文档是这样总结自身研究结果的。

高信任并重视信息流动的组织文化，能够预测软件交付绩效。

organizational culture that is high-trust and emphasizes information flow is predictive of software delivery performance

高信任且重视信息流动的组织文化能够预测软件交付绩效。这说的不是沟通顺畅的团队心情好，而是它是一个与绩效同向变动的变量。

不过，这里的“预测”不能读作因果。DORA 的数据来自同一批受访者同时回答文化与绩效的问卷，是组织层面的相关性。对组织满意的人两边都给出宽松评分的可能性依然存在，而且从组织层面的关系，也无法直接推出个人该如何行动的处方。所以凭这份材料能说的仅止于此：信息流动并不只存在于偏好的领域，它处在一个与绩效同向变动的位置上。

同一份文档还整理了 Westrum 所说的好信息的三个性质：能回答接收者需要的问题、时机恰当，以及以接收者能有效使用的方式呈现。值得留意的是，三者的标准都落在接收者身上。共享得多，并不等于信息流动得好。

Google 的 Project Aristotle 也是常被引用的资料。根据reWork 上公开的内容，他们调查了 180 个团队，对数百个变量跑了 35 个以上的统计模型，提出影响团队效能的五个因素：心理安全感、可靠性、结构与清晰度、意义，以及影响力。而结论是，比起团队里有谁，这个团队如何协作更为重要。

不过有一点我想说明。官方页面写明这五个因素是按重要性排序的，并把心理安全感放在最前面。但引用这项研究的文章中常见的“压倒性第一”这类关于量级的表述，那个页面上并没有。存在顺序，和压倒其余，是两回事。所以本文不主张量级。若要论述心理安全感的重要性，依托上一节 Edmondson 的原论文才是准确的做法。

再回到领导者的话题

回到开头引用的那篇文章。

James Samuel 在最先讨论信息收集时说，一线执行者时期的方法会失效。作为个人贡献者时，你握有自己工作的全貌，可一旦背负起对人的责任，就无法再沿用过去的方法。因此他把过滤噪声、将信息综合成一幅连贯的现实图景的能力列为必需能力，因为没有哪个管理者能处理一切。

我觉得这与前面看到的 Westrum 关于好信息的三个性质是同一回事。重点不在于收集得多，而在于把它变成可用的形态。而这与我现在处理需求时所做的事并无二致。从需求文档的句子中挑出含糊之处，用 breadboard 重画一遍来确认，把不知道的事情留作红色卡片，这正是过滤噪声、构建连贯图景的练习。

作者关于决策留下的话也让我印象深刻：等待确定性本身也是一种决策，并且伴随着成本。等到需求完全明确为止，同样如此。所以，比起完美的理解，“足以支撑当前目的”这一 grounding criterion 才是实用的标准。

结语

总结一下。

与其他职能的沟通失败，大多不只是态度问题。只要组织内部存在不同的语境，同一个词分化就是默认状态，而对齐的状态反而是需要付出成本去维持的例外。支付这份成本的方式就是共享语言，而在其中，developer 的职责不是把需求听写下来，而是监视歧义并把它交还回去。

可是交还回去是要花力气的，而人总想把这份力气降到最低。所以我决定不依赖意志，而是使用三样东西：先确认这场对话属于哪种模式；用介于文字与设计稿之间的分辨率把流程画出来并交还回去；以及在会议的表格里预留一个写下未知的格子。这三样都不要求人改正态度，而是让正确的做法更容易做到。

我还不是领导者，写在这篇文章里的东西也没有在那个位置上验证过。团队规模或组织文化不同，总会有行不通的地方。不过有一点，我现在似乎可以确信。日后处理信息的方式不是重新学来的，而是当下处理需求的习惯原样长大的形态。所以我最近尽量不再像从前那样，羞于在会议上问一句“那是什么意思”。

如果读到这里的你，能想起最近某场会议上自己点了头、其实并不确定的某个词，那么我建议你下次把那个词再用一次。反复使用，它就会显现。

在整理上一篇关于token 节省方法的文章时，有一个问题始终萦绕在我脑海中。我认为，重心正在从逐个雕琢 prompt，转向去除无关信息并筛选所需内容的技术（context engineering）。文章写完后，下一个问题自然浮现：那么，context 之后是什么？

讨论“未来方向”需要谨慎。未来可能有无数种选择，因此本文只专注于梳理从已经公开的一手资料中能够读出的重心转移。其中难免包含一些推论，也希望读者能从不同角度看待本文。

从 prompt 到 context

先厘清术语。曾有一段时间，业界的核心话题是 prompt engineering。问题在于如何写好发给模型的一次性指令，也就是如何设计清晰的指示、恰当的示例和输出格式。

后来，工作的单位变大了。随着运行数十个轮次的 agent 日益普及，重要的不再是一次 prompt，而是如何组织模型在每个轮次看到的完整 context（system prompt + 工具定义 + 对话记录 + 搜索结果 + 记忆）。这就是 context engineering。Anthropic 在 2025 年 9 月的“Effective context engineering for AI agents”一文中梳理了这一框架；同年 Chroma 研究团队（Hong et al.）发表的 context rot 研究又提供了定量依据。他们测试了 GPT-4.1、Claude 4、Gemini 2.5、Qwen3 等 18 个模型，发现即使只是原样抄写单词这样的简单任务，输入越长，性能也会出现不均匀的下降。模型会同等处理第 100 个 token 和第 10,000 个 token 这一常见假设，在现实中并不成立。结论不是“context 越长越好”，而是“信息如何摆放，与其中包含什么同样重要”。这进一步推动了从填满 context 向筛选 context 的转变，也让这个术语迅速普及。

这里需要指出一个常见误解。prompt engineering 并没有被 context engineering 取代。写好 prompt 依然是基础，而 context engineering 更接近建立在其上的上位概念。（关注点从写好代码转向设计好系统，并不意味着 coding 不再必要。）所以更准确的表述不是“换轨”，而是“在包含原有概念的同时扩大了范围”。

那么再问一次：这种扩展止步于 context 了吗？看起来并没有。

Anthropic 工程博客

我认为，判断方向最诚实的方法，是按时间顺序阅读那些真正推动该领域发展的组织正在写什么。沿着 Anthropic 工程博客中“Effective context engineering”（2025 年 9 月）之后的文章看下去，仅从标题就能勾勒出重心下一步移向何处。

• 2025 年 10 月，用 Agent Skills 武装 agent
• 2025 年 11 月，Code execution with MCP：更高效的 agent
• 2025 年 11 月，Effective harnesses for long-running agents
• 2026 年 1 月，Demystifying evals for AI agents
• 2026 年 1 月，设计 AI-resistant 技术评估
• 2026 年 2 月，量化 agentic coding 评估中的基础设施噪声
• 2026 年 3 月，Harness design for long-running application development
• 2026 年 4 月，Scaling Managed Agents：分离大脑与双手
• 2026 年 5 月，如何在所有产品中 contain Claude

退一步看这份列表，关键词聚成三条线：harness、eval 和 containment。我将其理解为：讨论正在从如何恰当地填充、清理 context，再向外迈出一步，转向设计、测量和控制整个 agent 系统。（当然，这里有一个局限：这只是一家公司的侧重点。不过考虑到该公司在 coding agent 生态中的分量，也很难把它仅仅视为单一 vendor 的兴趣。）

下面逐一展开。

harness

harness 这个词可能有些陌生。直译是马具，即套在马身上、把力量引向预期方向的装置。在 AI agent 中，harness 指的是在 model 外部包围 model、驱动其工作的完整骨架。包括允许它以什么顺序使用哪些 tool、一次失败后如何恢复、授予多大权限，以及 loop 何时停止。

如果 context engineering 解决的是“给 model 看什么”，那么 harness 设计解决的是“让 model 在其中如何行动”。它位于更外一层。若把 model 比作聪明的新员工，context 是交给新人的工作材料，harness 则更像其工作环境和操作规程。同一个人在混乱的环境中表现会不稳定，而在设计良好的流程上，凭同样能力也能走得更远。

这一点的重要性，在Anthropic 工程团队亲身遭遇的失败中体现得很清楚。他们把顶级编程模型 Opus 4.5 放在 Claude Agent SDK 上，只给出“做一个 claude.ai 复刻版”之类的高层指令，并运行多个会话；模型本身虽然聪明，却没能产出生产级应用。失败反复呈现两种形态。一种是试图一次做完所有事情，实作中途耗尽 context，让下一个会话接手半成品功能。另一种是后来加入的会话看到“已经做得差不多了”，便丢下尚未完成的工作直接宣布结束。（可以想象一项漫长工作由多人轮班接续，但每个接班者都完全没有前一人的记忆。）

解决办法不是让模型更聪明，而是改变骨架。第一个会话获得用于搭建环境的专用 prompt（initializer agent），把 200 多项功能规格展开到 feature_list.json，并创建启动开发服务器的 init.sh 和进度日志（claude-progress.txt）。此后的每个会话（coding agent）每次只处理一个功能，以 git commit 和进度记录留下整洁状态，然后结束。下一个会话先读取进度文件和 git log，弄清“上一班做到哪里”，再继续工作。同一个模型放到这套骨架上，结果就变了。决定成败的不是模型，而是 harness。（有趣的是，Anthropic 的这些做法并不新鲜。功能清单、小步 commit、进度记录、每次都执行的 smoke test，正是资深开发者每天在做的事。所谓适合 agent 的良好骨架，归根结底就是把良好的工程习惯嵌入环境。）

这条脉络与 token 节省讨论的交点也很明确。上一篇文章谈到的 subagent 隔离、tool 定义瘦身和 model routing，单独看是不同的节省技巧；合在一起看，归根结底都是如何设计一个 harness的组成部分。决定哪类工作送往哪个 model lane、只开启哪些 tool、把 verbose 的探索隔离到哪里，这整个过程就是 harness 设计。节省更像是设计的副产品。

不过，harness 设计有一个微妙的陷阱：骨架设计得越好，model 进步后就越可能过时。 harness 本质上是一组关于“model 无法独自完成什么”的假设；model 一旦能够自行完成，这些假设就成了冗余。Anthropic 提到的案例正是如此。Sonnet 4.5 在接近 context 上限时有匆忙收尾的习惯（context anxiety），因此团队在骨架中加入了 context reset 机制。可同一套骨架换成 Opus 4.5 后，这种习惯已经消失，精心加入的 reset 反而成了累赘。model 每聪明一步，骨架的一部分就可能这样到期。

于是出现了更进一步的思路：与其精心打造某个特定骨架，不如设计即使骨架变化也保持稳定的接口。Anthropic 的 Managed Agents 正朝这个方向发展，而其思想源头竟是操作系统。OS 能维持数十年，是因为它把硬件虚拟化为进程、文件等抽象，提前造出了能容纳尚不存在的程序的容器。一行 read()，无论面对 1970 年代的磁盘还是今天的 SSD，都以相同方式工作。用同样思路把 agent 分为三部分：负责判断的大脑（Claude 与 harness）、实际动手的双手（code execution sandbox 与工具），以及以 append 方式记录一切的会话日志。三者分离后，即便容器崩溃，大脑也能将其当成 tool call error 处理；即便 harness 崩溃，也能从会话日志的最后位置恢复。副作用是成本与延迟也降低了。只在真正需要时启动容器后，time to first token（TTFT）据称在中位数上下降约 60%，p95 下降超过 90%。（这里再次与 token 节省文章相接。上一篇建议为 prompt caching 把静态部分放在前面；“如何安排 context 才能提高 cache hit 率”，正是大脑旁边的 harness 所负责的工作。）

eval

第二条线是我个人最感兴趣的。2026 年初的文章仿佛事先约好一样，全都聚向评估（eval）。

想想原因就很自然。context 是否组织得当，harness 是否设计得好，cost 是否真的节省了，要用什么来确认？ agent 越是自主处理漫长而复杂的工作，人就越难逐项用肉眼确认“它到底运行得好不好”。信任的依据最终会转向测量。因此，“如何设计 agent 评估”“如何消除评估本身的噪声”“如何处理 model 察觉评估后改变行为的 eval awareness”等主题走到了前台。

agent 评估之所以棘手，是因为它与一次性问答性质不同。agent 会跨多个 turn 调用 tool、改变 state，一次错误会向后传播并累积。而且即使输入相同，每次运行的结果也会波动。Anthropic用两个指标描述这种非确定性。pass@k 是 k 次尝试中至少成功一次的概率，因此尝试越多越高。pass^k 是 k 次全部成功的概率，因此尝试越多越低。只需偶尔生成一次正确代码时，pass@1 很重要；每次都必须稳定运行的客服 agent，则以 pass^k 为核心。（若 per-trial 成功率为 75%，连续成功三次的概率是 0.75³，约 42%。“通常能用”和“每次都能用”的差距就是这么大。）

那么一次尝试由什么评分？同一篇文章把 grader 分为三类。code-based（test 是否通过、static analysis、tool call 验证）快速、便宜且客观，却不擅长存在多个正确答案的开放任务。model-based（LLM-as-judge、按 rubric 评分）能捕捉细微质量，但具有非确定性，必须定期与人工评分校准。human-based 最准确，却缓慢而昂贵。实际工作中会混合三者，尽可能以确定性评分打底，再用 model 评分辅助。还要区分另一组概念。capability eval 问“这个 agent 能做到什么”，所以会从低分起步，给出可以攀登的坡度；regression eval 问“过去能做到的现在还能不能”，因此必须维持接近 100%，分数下降就是某处损坏的信号。

这里有一个常被忽略的陷阱：分数低，问题可能不在 agent，而在评估。 Anthropic 报告称，Opus 4.5 最初在 CORE-Bench 上得到 42%；调查后发现，原因包括僵硬的评分方式——期待“96.124991…”，却把“96.12”判错——以及含糊的题目规格和无法复现的随机任务。修复 bug 并用放宽约束的 scaffold 重跑后，分数跃升至 95%。因此他们强调一项原则：不要照单全收分数，要亲自阅读 transcript（运行记录）。 如果 frontier model 尝试 100 次仍是 0%，通常不是 model 无能，而是题目坏了。

随着测量进步，基准线本身也快速移动，这一点同样有趣。在代表性的 coding agent benchmark SWE-bench Verified（给出真实 GitHub issue，并按 test 是否通过评分）中，frontier model 的分数在 1 年内就从 30% 多升到 80% 以上。到了这里，简单题已全部解决，分数触及天花板（saturation），于是产生悖论：能力的大幅提升只能显示为很小的分差。据说有一家 code review startup 起初只看一次性评估，对新 model 不以为然；改用衡量更长、更复杂任务的 agent 型评估后，才真正看见进步。因此，eval 不是做一次就结束的东西，而是需要不断换成更难版本的活资产。（Anthropic 将其比作安全工程中的“Swiss cheese model”。一片有孔的奶酪无法挡住失败，但把自动评估、production monitoring 和人工 transcript review 层层叠加，穿过一层的失败就会被下一层捕获。）

containment

第三条线的性质略有不同。它关注的不是 cost 或 performance，而是安全与控制。

agent 掌握越多 tool、行动越自主，一次错误的影响范围（blast radius）也越大。对于能删除 file、向外部发送 request、代为执行特权操作的 agent，“做得有多好”与“出错时在哪里止损”同样重要。2026 年 5 月，Anthropic 关于全产品 containment 的文章被放到突出位置，也可从这一背景理解。文章把 agent 风险分为三类：user 出于恶意或疏忽要求有害操作的 user misuse；model 在无人指示时自行行动的 model misbehavior；以及通过 tool、file、network 从外部进入的 external attack。一个有趣的观点是，model 变聪明并不只会降低风险。能力较弱的 model 会误读情境、犯明显错误；能力更强的 model 错误较少，却更善于找到意料之外的路径，绕过无人明确写下的约束。

他们强调的核心是“每次都由人监督”这一方式的局限。Claude Code 早期通过在每次写入、执行、network access 前请求 user 批准来保障安全，但 telemetry 显示，user 直接同意了约 93% 的请求。批准窗口越多，人对每一个就越不注意，形成 approval fatigue。依赖人的 click 的概率性防御最终仍会留洞。因此重心从“监控 agent 正在做什么”移向“首先限制 agent 能做什么”。防御分三层叠加：sandbox、VM、egress control 等构成的环境层，system prompt、classifier 等构成的 model 层，以及 MCP、plugin、搜索结果等构成的外部内容层。核心原则是首先建立能以确定方式阻断行为的环境层。这并非因为 model 层防御很弱。事实上，在测试 prompt injection 的 Gray Swan benchmark 上，单次攻击成功率约为 0.1%，处于顶尖水平。但适应性地尝试 100 次后，成功率会升至 5～6%；概率性防御本质上不可能达到 100% 命中率。所以还要设置最终会撞上的硬边界。（引入 OS 级 sandbox 后，批准窗口减少了 84%。安全机制反而降低了摩擦。）

这似乎与 token 节省相距很远，实则同根。两者都在问：“给 agent 什么，又给到什么程度？” Anthropic 用两个案例很好地说明了这种联系。其一，内部 red team 通过 phishing 让员工用恶意 prompt 运行 Claude Code。悄悄夹入的指令让它读取 ~/.aws/credentials 并向外 POST，25 次中成功了 24 次。由于指令由用户亲自输入，模型分类器看不出可疑之处。阻止攻击的不是聪明的模型，而是最初就把凭据放在 sandbox 外的环境边界与 egress control。另一案例更微妙。egress allowlist 正常放行了 api.anthropic.com，但攻击者植入的文件使用攻击者自己的 API key 调用 Anthropic 的文件上传 API，让数据流向攻击者账户。sandbox 完美工作，数据却依然泄漏。教训是，allowlist 不能只看作“目的地过滤器”，而应看作“允许使用该域名所有功能的权限”。（Anthropic 反复强调这一原则：经过验证的 hypervisor、syscall filter 和 container runtime 都安然无恙，真正出问题的是他们自己在其上构建的组件。）移除不用的 MCP 工具也是同一个道理：既节省成本，又减少 attack surface。保持轻量的设计不仅更便宜、更准确，也更安全。

总结

把三条线压缩成一句话：关注的单位正在逐层向外扩展，从 prompt（一次指令）到 context（每个 turn 展示什么），再到整个 agent 系统（如何运行、如何测量、如何限制）。harness 对应“如何运行”，eval 对应“如何知道运行得好不好”，containment 对应“运行出错时如何阻止”。

再次强调，这三条线是作者从已经公开的资料中推断出的重心转移，不是“2026 年下半年它们将成为标准”之类的预言。有些趋势会继续扩大，有些会被吸收到别的名称之下。但可以确定的是，prompt 和 context 都不会消失，而会作为更大框架的一部分留下。这个领域一直不是用新词抹掉旧词，而是在其上再加一层；未来也很可能如此。

我们从 cost 谈起，一路来到这里。上一篇建议读者拿出 token 账本，这篇则更进一步：不妨同时审视，节省的 cost 用什么确认（eval），这种节省在哪种骨架上可以重复（harness），以及该骨架安全到什么程度（containment）。归根结底，最持久的也许不是某一种节省技巧，而是测量并控制自己系统的习惯。

本文是对 2026 年 6 月所写复盘的重写。最初那篇文章打出的“七种选择器共用一套 API，比竞品库的一个日历还小”，重新核实后发现一半是错的，另一半算不上差异点。所以这次按照开发原因、与现有方案的区别、技术定义的顺序重新整理。

先说结论：Kalyx 的区别不在组件数量，而在 值模型。基准版本是 @kalyx/react 1.4.7 与 @kalyx/core 1.4.8（MIT，仅支持 React 19），引用的代码基于 GitHub 仓库 2026-09-16 的 main（0bb302e）。

我想以声明式的方式使用日期选择器

开发它的原因有两个。一是想用更声明式、更简单的方式使用复杂难用的日期库，二是想学习这类库在内部是如何构建的。“难用”这个说法太笼统，所以我用各个库的类型定义重新确认了一遍，我当初卡住的地方在最新版本里是否依然存在。

用 prop 开启模式的 API

react-datepicker 用 showTimeSelect 开启时间选择，用 showMonthYearPicker 开启月份选择，用 showYearPicker 开启年份选择，用 selectsRange 开启范围选择。同一个组件会随着 prop 组合变成不同的东西。代价体现在类型上。在 9.1.0 的类型定义中，根据 selectsRange 的值，onChange 的签名会分叉。

// react-datepicker/dist/index.d.ts (발췌)
    selectsRange?: true;
    selectsMultiple?: false | undefined;
    formatMultipleDates?: never;
    onChange?: (date: [Date | null, Date | null], event?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void;

这是一个写得很好的 union，但模式越多，分支就成倍增加，使用方只能看着 prop 名称去推想当前是哪种组合。（这和我在抽象一文中讨论的“捆绑错误的抽象会增加耦合”是同一种形态）我希望“输入框、弹出层和日历”能直接从 JSX 结构本身读出来。

值类型与时区泄漏的地方

react-datepicker 和 react-day-picker 传递的是原生 Date。两者确实都有接收 IANA 时区的 timeZone prop。react-datepicker 需要可选 peer 依赖 date-fns-tz，react-day-picker 的那个则是实验性功能，但无论哪一边，值的类型依然是 Date。Date 会按运行环境的本地时区解释，所以在首尔，new Date(2026, 3, 15) 经 toISOString() 得到的是 2026-04-14T15:00:00.000Z。选的是 4 月 15 日，服务器看到的却是 14 日。react-datepicker 的 "Date Selected is One Day Off" issue 于 2017 年 9 月打开，2025 年 12 月才关闭。

另一端的 Ark UI 和 React Aria 使用 @internationalized/date 的 CalendarDate、ZonedDateTime 对象。语义很精确，但在表单状态和服务器响应全是字符串的应用里，每个边界都会冒出转换代码。

时区支持有时还和日期库的选择绑定在一起。查看 MUI X Date Pickers 9.13.0 的适配器代码，dayjs、Luxon、Moment 适配器是 isTimezoneCompatible = true，date-fns 系列则是 false。使用 date-fns 的应用若想用 timezone prop，就得再引入一个日期库。

模式分散在 prop 组合里，值分散在解释依赖运行环境的 Date 里，时区支持分散在日期库的选择里。很难用一个声明写清意图。

在构建中学习

日期选择器看起来很小，却包含了日历计算、区域设置、时区与夏令时（DST）、键盘导航和 SSR。所以我定下的目标是：在使用方，只看 JSX 就能读懂在构建什么；在实现方，把范围收窄到能说清值在哪里被转换。

那么，真的没有已经解决这些需求的库吗？

与现有方案有什么不同

先说答案：有。我一开始认定没有既是 headless 又具备多种选择器的库，但重新调查后发现这个前提是错的。

各方案选择的值模型

以下内容是 2026-09-16 安装 npm 最新版本后，通过类型定义和官方文档确认的。体积一列是用下文介绍的同一方法测得的。

react-day-picker 在官方指南中明确写道 "DayPicker does not include a built-in time picker"。MUI 的体积包含 @mui/material 和 emotion，所以如果本来就是 MUI 应用，增量要小得多。

headless 的完整方案早已存在

表中重要的是 Ark UI 和 React Aria 两行。Ark UI 通过 DatePicker.Root 这类 dot notation 组合 API，提供单选、多选、范围选择以及按月、按年选择。React Aria 是 Adobe 以无障碍为核心的实现。所以 Kalyx 的位置比我最初想的要窄。

headless 的完整方案早已存在。不过 Ark UI 和 React Aria 以 @internationalized/date 对象传递值，时间输入采用分段字段。Kalyx 把值固定为可以直接放进 JSON 的 UTC 时刻字符串，并把从列表中选择的 TimePicker 以及月、年、周选择器放进了同一套组合 API。

不过，“值是字符串所以好”是个站不住的主张。CalendarDate 调用一次 toString() 也能变成字符串。差异不在格式，而在于 这个字符串始终是真实的瞬间（时刻），不会与日历格子（坐标）混用的契约，以及守护这个契约的测试。

用同一方法重新测量包体积

README 徽章上的包体积并不是能和其他库比较的量。徽章上约 19.5KB 的数字，是 @kalyx/react 的 dist 中的一个文件，而这个文件把 @kalyx/core、@kalyx/adapter-date-fns、@floating-ui/react 留作外部 import。我把这个数字和别人包含依赖的数字摆在了一起。

所以我按“消费方应用加一行 import 时，包会增大多少”把所有库重新测了一遍。

echo "import { DatePicker } from '@kalyx/react'; export default DatePicker;" > entry.jsx
npx esbuild entry.jsx --bundle --minify --format=esm --platform=browser \
  --external:react --external:react-dom --external:react/jsx-runtime | gzip -6 | wc -c

测量使用 esbuild 0.28.2，时间为 2026-09-16，KB 是字节数除以 1024 的值。react-datepicker 排除了 CSS。React Aria Components 测了两次：一次是组装单个 DatePicker 所需的 12 个 export（DatePicker、DateInput、Calendar、Popover、Dialog 等），一次是加入范围和时间的 14 个 export（含 DateRangePicker、RangeCalendar、TimeField）。

在相同条件下，成立的说法只有一个。一个 DatePicker（18.9KB）与 DayPicker（20.0KB）体积相当，七种全部（25.6KB）则比它大。（即便如此，DayPicker 只有日历，而 Kalyx DatePicker 还包含输入框和弹出层）体积对 import 组合和 gzip 级别很敏感，按数量级来读更合适，体积也不是选择 Kalyx 的核心理由。

从技术上定义 Kalyx

Kalyx 是一个 headless React 日期选择器：它把所有输入输出固定为 UTC 时刻字符串，把日历坐标与时刻之间的转换只放在两个函数里，并针对运行时知道的所有时区用属性测试检查这一往返。

使用方的 API 如下。value 和 onChange 是 string | null，displayTimezone 决定用哪个时区的日历来显示。

<DatePicker value={iso} onChange={setIso} displayTimezone="America/New_York">
  <DatePicker.Input />
  <DatePicker.Popover>
    <DatePicker.Calendar />
  </DatePicker.Popover>
</DatePicker>

值是时刻，日历格子是坐标

Kalyx 内部流动着格式相同的两种 ISO 字符串。坐标 是日历网格中的一格，写作 YYYY-MM-DDT00:00:00.000Z，却没有时区概念。网格计算只在 UTC 中进行，因此与运行环境无关。时刻 是通过 onChange 输出的值，是 displayTimezone 中当天零点对应的真实瞬间。同样是 1 月 15 日，在纽约是 2026-01-15T05:00:00.000Z，在首尔是 2026-01-14T15:00:00.000Z。

连接二者的函数只有 @kalyx/core 中的两个：把坐标转为时刻的 civilMidnightFromUtcDay，以及反方向的 calendarDayFromInstant。后者读取“这个时刻在该时区是几号”，再重新写成 UTC 零点坐标。

// packages/core/src/utils/timezone.ts:187-190
export function calendarDayFromInstant(iso: ISODateString, timeZone: string): ISODateString {
  const p = partsInTimezone(new Date(iso), timeZone);
  return new Date(Date.UTC(p.year, p.month - 1, p.day)).toISOString();
}

规则在于方向。选中格子并提交值时，坐标转为时刻；根据存储值决定显示哪个月和焦点位置时，时刻转为坐标。DatePicker Root 的 selectDate 先转换，再用转换后的时刻检查约束，通过后提交。

// packages/react/src/components/DatePicker/Root.tsx:182-194
const normalized =
  coordinate && displayTimezone
    ? civilMidnightFromUtcDay(coordinate, displayTimezone)
    : coordinate;
 
if (normalized && isDateDisabled(normalized, disabledRules, adapter, displayTimezone)) {
  return;
}
 
if (!isControlled) {
  setUncontrolledValue(normalized);
}
onChange?.(normalized);

调用点不止这一处。搜索 packages/react/src 会发现，这两个函数分散在 DatePicker、RangePicker、DateTimePicker 的 Root 和 Calendar、Presets、键盘移动工具函数以及六个 headless hook 中。即便如此，所有提交日期格子或决定视图的路径都会经过二者之一。提交时间由 setTimeInTimezone 负责，它在内部也用同一个内部函数 resolveCivilDateTime 转换。

这个契约由基于属性的测试（property-based test）守护。对任意坐标 c 和时区 z，都必须满足 calendarDayFromInstant(civilMidnightFromUtcDay(c, z), z) === c。

// packages/core/src/__tests__/timezone.property.test.ts:86-94
it('round-trips every UTC calendar coordinate through civil midnight', () => {
  fc.assert(
    fc.property(utcCalendarCoordinate(), zone(), (coordinate, timeZone) => {
      const instant = civilMidnightFromUtcDay(coordinate, timeZone);
      expect(calendarDayFromInstant(instant, timeZone)).toBe(coordinate);
    }),
    RUNS,
  );
});

fast-check 随机生成 2020 年到 2045 年之间的日期，与 +5:45 的 Kathmandu、+14 的 Kiritimati、-11 的 Niue 等 14 个代表性时区组合，运行 300 次。紧接着的测试对 Intl.supportedValuesOf('timeZone') 返回的所有时区，逐个时区各检查 12 次同样的往返。在我本地的 Node 24.16 上，这个列表有 418 个时区。1.4.8 又加入了一个全量测试，在每次夏令时切换处把边界时间的转换结果与 Temporal 实现对照。

那么，库能不能自动把用户传入的 "2026-01-15T00:00:00.000Z" 规范化为时刻？这条路走不通，因为仅凭字符串无法判断它是坐标还是时刻。对已经是时刻的首尔值 2026-01-14T15:00:00.000Z 再套一次 civilMidnightFromUtcDay，就会得到 2026-01-13T15:00:00.000Z，在首尔这样偏移为正的时区，每次渲染日期都会再往前挪一天。（纽约的值再套一次也不变）换成无论应用多少次结果都相同的 startOfDayInTimezone，虽然不会挪动，却做不了把坐标转为时刻这个本职工作。

所以我放弃了规范化，用文档固定契约。使用方必须原样传回选择器输出的值。坦白说，这是转嫁给使用方的成本，而且 ISODateString 是 string 的别名，编译器也拦不住。

只用 Intl 解决夏令时

要把坐标转为时刻，需要知道“该时区当天的 00:00”在 UTC 中是什么时候，但偏移量只有知道时刻才能求出。更麻烦的是，在夏令时切换日，当地时间可能不存在（spring forward），也可能出现两次（fall back）。

Kalyx 不借助 date-fns-tz 这样的库来解决这个问题。它用 Intl.DateTimeFormat(...).formatToParts 询问“这个 UTC 瞬间在该时区是几点”，以此测出偏移量，并在请求时间的前一天和后一天两个点读取偏移量。

// packages/core/src/utils/timezone.ts:251-254, 259
const candidate = (probeEpoch: number) =>
  civilEpoch - getTimezoneOffsetMinutes(new Date(probeEpoch).toISOString(), timeZone) * 60_000;
const epochBefore = candidate(civilEpoch - 86_400_000);
const epochAfter = candidate(civilEpoch + 86_400_000);
 
if (epochBefore === epochAfter) return new Date(epochBefore).toISOString();

civilEpoch 是把目标当地时间当作 UTC 读出的值。偏移量在 ±14 小时以内，所以前一天和后一天会分别给出附近切换之前和之后的偏移量。两者相同说明附近没有切换，两次 formatToParts 就结束；网格的 42 个格子各调用一次，所以这条快速路径决定了开销。（前提是 48 小时内最多一次切换，这在 2020 至 2045 年的所有时区都成立）

两者不同时，会在该时区重新读取两个候选，看哪个与请求时间一致（timezone.ts:261-279）。fall back 的重叠中两者都一致，于是选用切换前偏移量得出的较早一个；spring forward 的空隙中两者都不一致，于是同样选这一侧，把时间按空隙长度往后推。实际运行的结果如下。

“空隙往后推，歧义取较早”与 MDN 的 Temporal.ZonedDateTime 文档所说明的 disambiguation 默认值 "compatible" 相同。1.4.7 的 London 一行为什么出错，后面再讲。

适配器边界是 21 个字符串方法

既然时区由 core 计算，那 date-fns 或 dayjs 负责什么？日期运算和解析。这条边界 DateAdapter 有 21 个方法，日期参数和返回值全都是 ISO 字符串。

// packages/core/src/types.ts:71-102 (발췌)
export interface DateAdapter {
  parse(value: string, format?: string): string;
  format(iso: string, formatStr: string, timezone?: string): string;
  addDays(iso: string, n: number): string;
  isSameDay(a: string, b: string, timezone?: string): boolean;
  startOfDay(iso: string, timezone?: string): string;
  today(timezone?: string): string;
  // addMonths, isBefore, startOfMonth, getYear 등 15개
}

接收时区的方法有 format、isSameDay、startOfDay、today 四个，而这四个也把计算交给 core。date-fns 适配器的 format 在有 timezone 时，会直接调用 core 的 formatInTimezone（packages/adapter-date-fns/src/index.ts:112-115）。因此无论使用哪个适配器，时区的答案都出自同一段代码，三个适配器（date-fns、dayjs、luxon）各自运行 @kalyx/core/test-helpers 的 runAdapterConformanceTests，确认给出相同的答案。

两个入口也在这条边界上分开。默认入口 @kalyx/react 在模块加载时调用 setDefaultAdapter(DateFnsAdapter)，所以安装后即可使用（packages/react/src/index.ts:9-11）。@kalyx/react/headless 没有这个调用，打包也是分开的，date-fns 的代码不会混进来。

这种边界形态是有代价的。2026 年 6 月，我放弃了 Temporal 适配器。Temporal 的价值在于像 PlainDate、ZonedDateTime 这样 由类型携带语义，可一旦边界是字符串，这层语义就无法通过。包一层也只会被压平成字符串，我判断这在正确性上没有收益。回头看，上一节“坐标和时刻是同一个 string”的问题，恰恰就是 Temporal 用 PlainDate 和 Instant 在类型层面解决的问题。字符串边界让替换适配器变得容易，代价是堵住了用类型解决问题的路。

七种选择器是三个上下文的组合

Kalyx 的选择器有 DatePicker、RangePicker、TimePicker、DateTimePicker、MonthPicker、YearPicker、WeekPicker 七种。比数量更重要的是，这七种并不是独立实现。上下文只有 DatePickerContext、RangePickerContext、TimePickerContext 三个。

MonthPicker 的 Root 只是把显示格式默认值改为 yyyy-MM，再把 selectionGranularity="month" 传给 DatePicker 的 Root 实现（MonthPicker/Root.tsx:11-20）。DatePicker 的 selectDate 在 granularity 为 month 时，把坐标折叠到当月 1 日，之后照样走前面看到的转换和约束检查。DateTimePicker 则叠加提供两个上下文。

// packages/react/src/components/DateTimePicker/Root.tsx:401-402
<DatePickerContext.Provider value={dateContext}>
  <TimePickerContext.Provider value={timeContext}>{children}</TimePickerContext.Provider>

所以 DateTimePicker.Calendar 和 DatePicker.Calendar 是同一个组件，它并不知道自己处在哪个选择器里。一处修改会作用到所有使用该组件的选择器，一处缺陷也会波及全部。前面图表中单个 DatePicker 占全部体积 74% 的原因，也正是这层共享基础。

守住契约的代价

1.0 之后的三个月，我更多用来确认这个契约而不是做新功能，结果出现了三次靠示例测试会被放过的缺陷。第一个由属性测试发现，第二个由代码交叉审查发现，第三个由本文的核查发现。

Sydney 10 月 1 日的一小时

第一个是“把 startOfDayInTimezone 的结果放到该时区读取，得到 00:00:00”这一属性在 Australia/Sydney 被打破。当时的实现只测一次偏移量。Sydney 在 2034 年 10 月 1 日 02:00 从 +10 切换到 +11，当天 00:00 仍是 +10，所以正确答案是 2034-09-30T14:00:00.000Z。然而“把 10 月 1 日 00:00 当作 UTC 读取的那个点”已经在切换之后，返回的是 +11，结果变成了前一天 23:00。这个反例也作为回归测试保留了下来（timezone.property.test.ts:276）。

只在首尔通过的测试

第二个出自 2026 年 8 月 3 日的交叉审查。决定日历中哪一格显示为选中的代码做了两次转换。格子本来就是坐标，却把格子和存储值都转换成了该时区的日期。选择“1 月 15 日”的结果如下。

在正偏移时区，两次偏移相互抵消，碰巧是对的，而已有测试只覆盖了首尔。同一次检查还发现了反方向的违规。决定显示哪个月时，直接对时刻套用了 startOfMonth，于是在首尔把 1 月 1 日作为值传入，打开的却是 12 月的日历。

机制不同，违反的规则却是同一条：每个方向只用指定的函数转换一次。

这次事故让 core 的往返属性测试从“几个代表性时区”扩展到“运行时知道的全部时区”。（React 一侧的组件测试仍在使用 America/New_York 这类代表性时区）只在符号翻转处暴露的缺陷，靠抽样是抓不到的。

London 的 01:30 被解析成较晚的一个

第三个是在把本文的 DST 表格扩展到其他时区时发现的。1.4.7 从“把请求时间当作 UTC 读取的那个点”开始测偏移量，而在切换后偏移量为 0 或以上的时区，那个点已经在切换之后，于是收敛到较晚的偏移量。用 temporal-polyfill 对 418 个时区 2020 至 2045 年的全部切换逐一对照，3,395 次重叠切换中有 1,908 次选了较晚的一个，涉及 84 个时区。（3,394 次空隙切换全部正确，偏移为负的纽约只是碰巧正确）

在 #226 中我改成读取前一天和后一天，作为 @kalyx/core 1.4.8 发布，并把同样的对照保留为 timezone.dst-oracle.test.ts。（temporal-polyfill 只在测试中使用）之前错写成 'earlier' 的源码注释也改成了 'compatible'。这一次，样本同样集中在一种符号上。

花在正确性上的 3KB

这些修复需要代码。Kalyx 为默认入口的包设置了 CI 上限，超出的 PR 会在必需检查中失败。这个上限从 12KB 起步，每加一个功能就上调 1KB，而在 2026 年 8 月全面修正时区和约束的正确性时，我把它从 17KB 一次性提到了 20KB。

体积是 README 徽章上展示的卖点。在负偏移时区每次差一天的日期选择器，不管大小都没法用。

如果必须在小和对之间选一个，那就选对的。现在的上限很紧。根据仓库 2026-09-11 的包字节分布文档，用 Node 默认 gzip 测量 dist/index.cjs 的结果是 20,259B，上限是 20,480B，余量只有 221B。（这是把依赖留在外部的自身文件大小，与前面图表测的是不同的量）下一个功能得先回收字节才能加进来。

与最初设想不同的结论

我想要的是以声明式的方式使用复杂的日期库。做完之后才发现，声明式的组合 API 和 headless 的完整方案早已存在。剩下的差异藏在更里面。把值固定为一个时刻，把坐标与时刻之间的转换收窄到两个函数，并用测试在所有时区守住这个往返。 基于 Intl 的夏令时处理、字符串适配器边界、由三个上下文组成的七种选择器，都是这一决定的结果。

从学习这个目标来看，我学到最多的是如何主张“正确”。最初文章的包体积对比测的是不同的量，在首尔通过的测试在纽约是错的。如果不把测了什么、用什么样本确认一并写下来，数字很容易沦为炫耀。

局限也很明确。维护者只有我一个人，仅支持 React 19，@kalyx/react 在 2026 年 9 月 5 日至 11 日的 npm 下载量是 200 次，其中 156 次集中在 1.4.7 发布当天。坐标与时刻无法用类型区分的问题只靠文档挡着，作为样式接入点的 classNames 和 data-* 属性是否作为公开 API 来保证，我也还没决定。可访问性方面，日历有 grid、输入框有 combobox、时间列表有 listbox 角色，支持方向键、Home/End、PageUp/PageDown 导航，CI 会运行 8 个测试文件中的 jest-axe 检查，但还没有依据说它和 React Aria 一样经过充分验证。

所以，如果本来就是 MUI 应用，先看 MUI X；如果分段输入和经过验证的无障碍是首要需求，先看 React Aria；如果只需要一个日历，先看 react-day-picker，这样更合适。如果你在值以 JSON 往来的表单中遇到过日期差一天的问题，那时再来看看 Kalyx 我会很高兴；如果你知道更好的解法，也欢迎通过 GitHub Issue 告诉我。

pnpm add @kalyx/react

在文档站的 Playground 中，可以亲手试用七种选择器，并修改 locale 和 timezone 设置。

过去，我关注的是结果和过程，而不是性能与成本。AI 产出的内容漏洞不少，必须逐一验证；为了尽快拿到结果，包括我在内的很多人一旦 Token 不够，就会付费或升级到更高档的订阅。我也不例外。（其实最初几个月里，我甚至没有留意 Token 究竟花了多少钱。）

但过了一段时间，我渐渐对 Token 用量警觉起来。个人感到月费负担沉重，企业则开始认真考虑人力和运营成本。我在MCP 与 function calling中整理了把智能体连接到外部系统的协议，在代码智能的四个层级中整理了代码检索工具和 GitHub Trending，在上下文文件中整理了智能体读取的规则文件。可以说，之前的文章更关注有哪些工具、该如何用好它们。我依然认同这个方向，不过随着时间推移，人们最终最想知道的恐怕还是成本。

关于 Token 究竟是什么、如何通过 BPE 生成，以及 prompt caching 降低单价时 Transformer 内部发生了什么，我已在 Token 的工作原理中单独整理。本文以此为基础，先看费用如何计算、低效从何而来，再归纳经过验证的节省模式。主要模式都附上了笔者用多种策略执行同一任务、亲自测得的 Token 用量。

Token 成本是怎样产生的？

先用最简明的方式看看 Token 成本从何而来，又按什么规则计费。

我们发送的所有文本——系统提示词、工具定义、对话记录、用户消息——都会成为输入 Token，模型生成的回复则是输出 Token。对模型来说，每次调用都是从未见过的新输入。无论是昨天的对话还是一分钟前的调用，新调用都会把相同内容作为输入重新完整发送。（这个简单事实正是 Token 成本的核心：模型没有记忆，是我们每次都把内容重新告诉它。）

这里还有一个变量。重复调用时，如果每次都重新传输静态部分，成本实在太高，因此主流 LLM 提供商引入了 prompt caching。静态输入先保存到缓存中一次，后续调用只对从缓存读取的 Token 按低得多的价格计费。（Token 如何由 BPE 生成，以及缓存如何复用 Transformer 的 KV cache 来降低单价，已在“Token 的工作原理”中说明；这里关注这些原理怎样转化为费用。）

输入 Token、输出 Token 与缓存 Token

来看 Anthropic SDK 在响应的 usage 对象中返回的四个字段。

• input_tokens 已发送输入中除缓存读取之外的部分
• output_tokens 模型生成的响应
• cache_creation_input_tokens 本次调用首次写入缓存的 Token
• cache_read_input_tokens 从已有缓存中再次读取的 Token

这四个字段分别乘以不同单价。输出 Token 最贵，从缓存读取的 Token 最便宜。根据 Anthropic 官方文档，缓存读取价格是基础输入价格的 0.1 倍，也就是整整 10%。缓存写入按 5 分钟 TTL（Time To Live，缓存有效期）计为 1.25 倍，按 1 小时 TTL 计为 2 倍。也就是说，第一次稍微多付一些，从第二次开始便宜 90%。

不过缓存还有一些不太为人所知的限制。可缓存的最小 Token 数因模型而异，同一系列的不同版本也不一样。根据 Anthropic 官方文档，Sonnet 4.6 和 Opus 4.8 是 1,024 Token，Opus 4.7 是 2,048 Token，Haiku 4.5 与旧版 Opus 4.5/4.6 则是 4,096 Token。更短的提示词即使设置了 cache_control，也不会提示错误，只是不会被缓存。每个请求最多可设置 4 个 cache_control 断点，缓存按 tools → system → messages 的层级顺序读取。因此，前方哪怕只改了一项工具定义，后面的全部缓存也会失效。

缓存之所以能让单价降低 90%，源于在多次调用之间复用 Transformer 的 KV cache；内部原理已在“Token 的工作原理”中详述。从成本角度只需记住一点：缓存命中只有在前缀完全相同时才会发生。因此必须把静态部分放在前面，把每次变化的动态部分放在后面，才能避免缓存失效。提示词前部哪怕只多了一个时间戳字符，也会使后续缓存全部失效。

此时很自然会想到一个问题：“多轮对话每轮输入都不同，缓存岂不是几乎每次都会失效？”答案是否定的。对话输入并不是每轮重写的一整块内容，而是保留前面累积的内容，只在末尾追加新发言（append）的结构。系统提示词、工具定义以及此前各轮的问答一旦确定就保持不变，只有本轮的新问题会加到最后。因此，从开头比较本轮和上一轮输入时，首次出现差异的位置总是末尾的新问题。整体输入每次都不同，但从前缀看，前面绝大部分仍然一致，缓存便能保留。（真正导致每轮缓存失效的，是把动态值塞到提示词前部的错误设计。Claude Code、opencode 等工具都固定前部、只在后面追加，用户也无需专门调整缓存设置。输入中的错别字或拼写差异不影响缓存，道理相同：变化总发生在缓存覆盖范围之外的最末端。）

AI 对比

把截至 2026 年 6 月 Anthropic、OpenAI、Google 的官方价格放进同一张表，趋势便一目了然。（单位为每百万 Token 的美元价格，主要选取编程工作流中常用的模型。）

三家提供商的输出价格都是输入的 5～6 倍。也就是说，输出越长，即使答案相同，费用也会陡增。同一档位内，不同模型的价格也可能相差 3～6 倍。只看简单计算就能得出降低 Token 成本的三条主线：缩短输出；答案相同时选更便宜的模型；把静态输入放进缓存。（再算一步会更有意思：假设每次调用都复用 1 万 Token 的静态上下文，共调用 100 次，按 GPT-5.5 基础价格需 $5，而从缓存读取只需 $0.50。缓存实际节省 $4.5，且第一次写缓存几乎没有附加成本，所以第二次调用起就开始获益。）

缓存机制的差异

即使节省比例相近，各提供商的内部结构也并不相同。了解差异为何出现，会更容易制定策略。

三家的设计理念清晰可见。Anthropic要求用户明确指定缓存范围，第一次调用收取少量溢价（1.25 倍），之后则大幅降价。前缀的位置容易控制，缓存读取率也更可预测。OpenAI恰好相反，一切自动处理。超过 1,024 Token 就自动缓存且没有附加费用，但用户几乎无法干预缓存行为。Google同时提供两种方式，用户显式控制缓存时另收存储费。短小而频繁的缓存适合隐式方式，需要保存一小时以上的大型上下文则适合显式缓存加存储费的模式。

工具定义与分词器

此外，还有两个影响出乎意料地大的变量。

第一是工具定义。在连接多个 MCP 服务器的环境中，每次调用都会把所有工具名称与参数模式定义一同作为输入发送（后文会直接测量这会膨胀多少）。即使工具不变，只换模型也会影响费用，这一点值得注意。Anthropic 官方价格文档显示，工具系统提示词的长度本身就因模型而异。Sonnet 4.6 与 Haiku 4.5 在 tool_choice: auto 下约为 497 Token，Opus 4.7 在同一位置使用 675 Token，Opus 4.8 又降到 290 Token。在 model routing 前先确认“当前模型会把工具定义展开多长”，常常能发现数量级不小的差异。

第二是分词器（把人类文本切分为模型可处理 Token 单位的工具）自身的效率。正如“Token 的工作原理”所述，同一文本经过不同分词器，Token 数也会不同。OpenAI 的 o200k_base 与 cl100k_base 相比，能显著减少非英语文本的 Token；Anthropic 则明确说明，从 Opus 4.7 起换用新分词器后，同一文本最多可能多用 35% 的 Token。只按单价选模型，可能又从分词器效率差异中漏掉成本。诚实的模型比较，应看单价×预计 Token 数的乘积。

实际比较时，韩语上的差异尤其明显。我用 OpenAI 的两种分词器处理同样的句子，英语技术句在新旧版本中的 Token 数相同，但韩语使用旧版（cl100k_base）时比新版（o200k_base）多出 31～43%。尤其值得注意的是一段韩语：167 个字符在旧版中变成 169 Token，出现了Token 数比字符数还多的结果，相当于一个韩文字平均消耗超过一个 Token。

原因是旧版会把韩语按字节细细拆开，而新版能把“개발”“입니다”等常见片段整体合并为一个 Token。即使单价相同，以韩语为主的任务仅凭分词器效率差异，也可能让账单相差 1.5 倍以上。

看到这里，一个问题自然浮现：“那么，我们究竟在哪里制造了低效？”

浪费 Token 的常见模式

即使自认为很会使用 AI，Token 低效流失的情况仍然很常见。把我自己和身边开发者的习惯归纳起来，大致有以下几类。

过多的 MCP 服务器与工具定义

前面虽已提到，这里仍想再次强调。MCP 服务器（Linear、GitHub、Notion、Figma、Slack、Sentry）一旦接入，往往就很少移除。未使用的工具模式定义会在每次调用时膨胀为输入 Token。Claude Code 默认启用的 MCP Tool Search 正是为了解决这个问题：会话开始时只加载工具名称和服务器描述，直到真正调用某个工具时才加载完整模式定义。

我直接测量了这种差异。以工作中的 Claude Code 会话里 27 个 MCP 工具（serena 10 个、claude.ai OAuth 四组共 8 个、figma 2 个、agentmemory 7 个）为对象，使用同一条用户消息在两种配置下调用。一边完全没有安装 MCP，另一边已挂载了全部 27 个，但模型无法调用；两边的工具调用次数都设为 0。

问题相同、模型相同、回复含义也相同，输入 Token 却从 41 → 10,335（+10,294）（Opus 4.7）暴增。换算为单次费用，就是从 $0.0048 → $0.0563，约 12 倍。输入膨胀 250 倍，预填充负担也随之增加，响应时间多出 +783ms。比金额本身更直观的是：即使用户这一轮一次 MCP 工具都没有调用，这笔费用仍会在每次调用时产生。上一段的 Tool Search 防住的正是这笔成本。（完成这次测量后，我一直在清理平时不用的 MCP 服务器。）

上下文累积与 Lost in the Middle

原封不动地延续长对话，不仅会增加每次调用的输入 Token，还会降低模型本身的正确率。Stanford 的 Liu 团队在“Lost in the Middle”论文中定量展示了一条 U 形曲线：关键信息位于上下文开头或末尾时最容易被找到，埋在中间时性能明显下降。于是出现最糟糕的组合——花更多 Token，得到更差的答案。Transformer 的自注意力计算量随 Token 数平方增长；上下文越长，每个 Token 能分到的绝对注意力越稀薄。再加上训练数据的重要信息往往集中在首尾，中间便最先变弱。

再深入一点，模型处理 Token“位置”的方式本身，就包含两种会让中间内容被淹没的习性。听起来复杂，用比喻解释却很简单。

第一，模型会更加留意附近的 Token。如今大多数公开模型采用的位置表示方式 RoPE（Rotary Position Embedding，旋转位置嵌入）被设计为：两个 Token 距离越远，彼此联系越弱（距离越远，信号越淡的 decay effect），因此远处 Token 自然更少受到关注。

第二，模型会把过多注意力无意义地流向第一个 Token。模型受到一种约束：每时每刻都必须把自己的注意力以 100% 的总量分配完毕（softmax 强制注意力总和为 1）。即使当前没有特别需要关注的地方，剩余注意力也必须丢到某处，而那个位置通常是句首的第一个 Token。第一个 Token 吸收多余注意力的现象称为 attention sink，即“注意力排水口”。（MIT 的 Xiao 团队在 StreamingLLM 论文中首次对其进行定量分析。它并非因为第一个 Token 包含重要信息，更像是把剩余注意力排出去所产生的副作用。）

两种习性叠加后，注意力会集中在两端（邻近的近期 Token＋第一个 Token），真正埋在中间的信息反而最弱。重要的是，这不是某个特定模型的缺陷。LLaMA、Mistral、Qwen 等多数公开模型采用 RoPE 系列，Claude、GPT 等闭源模型也被认为使用类似方法，因此 lost-in-the-middle 更像是现代 Transformer 共有的偏差。

近来，这种现象被称为 context rot。Chroma 研究团队让包括 GPT-4.1、Claude 4、Gemini 2.5、Qwen3 在内的 18 个前沿模型完成同一项 NIAH（needle in a haystack，大海捞针）任务。分析定量显示，当输入从 10k 增至 100k 以上时，正确率会因模型不同而降至 20～50%。18 个模型都随着长度增加而性能下降，下降最慢的是 Claude 系列。Anthropic 也将其解释为 Transformer 的 n² 注意力机制导致“注意力预算”被每个 Token 消耗的问题。保持上下文轻量，既是在省钱，也是在守住正确率。

无节制地调用 subagent

因为 subagent 好用就把所有任务都交出去，同样是个陷阱。subagent 在独立于父级的上下文中启动，因此要从头装载系统提示词和工具定义，产生固定成本。把短 shell 命令、简单 git 查询之类的小任务交给 subagent，启动成本可能超过整理主上下文所省下的费用。Anthropic 公布的 multi-agent research system 报告显示，与普通对话相比，单个智能体约使用 4 倍 Token，multi-agent system 约使用 15 倍。只有正确率提升足以抵偿这 4～15 倍的额外费用时，委派才有意义。

同样的陷阱也适用于 MCP 工具挂载。每启用一个工具，其模式定义都会在每一轮进入系统提示词，即使模型当轮不用，也照样计费。“说不定会用，干脆全开”直觉上似乎安全，实测却并非如此。

我针对 facebook/react v19 的 reconciler 源码，把相同问题分成以下三种配置，测量正确率与费用。

• 不使用工具
• 只使用一个工具（CodeGraph、Serena、ripgrep、bare grep）
• 同时挂载四个工具

结果清楚显示了三个特点。（这里的召回率指正确答案被完整找出的程度。）

• 不使用工具的平均召回率只有 0.31，证明工具本身确实有价值。
• 只使用 Serena（LSP）的召回率为 1.00，费用 $0.38，是所有单工具策略中效率最高的。
• 挂载全部四个工具时，召回率反而降至 0.89，费用升至 $0.47。尤其在多跳问题中，全挂载配置的分数与单独使用 CodeGraph（0.78 / 0.88）精确到小数点后两位都相同。模型偏向四个工具中的一个，也完整继承了它的弱点。

subagent 与工具挂载遵循同一条原则：只有额外成本能换来足够的正确率提升，才有意义。准确选择一个适合任务领域的工具，比“也许会用”而全部开启更便宜，也更准确。

那么，经过验证的节省方法究竟是什么？真的存在可行的办法吗？

经过验证的 Token 节省方法

每种节省模式针对不同的成本维度：有的减少输入，有的降低相同输入的单价，有的把相同任务交给更便宜的模型。下面逐一来看。

Prompt caching

这是见效最快的方法。正如前文所述，缓存读取只需基础输入价格的 0.1 倍。第一次调用支付少量写入溢价（1.25 倍）后，从第二次起，相同静态部分便能以十分之一的价格重复使用。

从节省角度还要再强调一点：无论采用哪种方式，真正适合缓存的都是每次调用几乎不变的部分（工具定义、代码片段、RAG 上下文）。只要不把静态块与动态内容（本轮问题、刚得到的工具结果）混在一起，效果就不会打折。直接使用 API 时，把静态块集中放在前面、动态部分放到后面，便能实现大部分节省；使用 Claude Code、opencode 等成熟工具时，排列工作会由工具自动完成。

用 Batch API 汇总异步任务

如果调用不必立即完成，Batch API 是直接降低单价最简单的工具。Anthropic、OpenAI、Google 都对输入和输出 Token 提供同样的 50% 折扣，代价是结果会在最长 24 小时内返回。Anthropic 的实测中，大多数批次会在一小时内完成，但 SLA 本身仍是 24 小时。调用内容完全不变，单价直接减半，采用成本几乎为零。

这 50% 最有意思之处在于，它会与其他节省机制相乘叠加。Anthropic 官方文档明确说明，缓存与批处理折扣会相乘（stack）。静态输入价格可降为标准价格×0.5（批处理）×0.1（缓存读取）＝0.05 倍，也就是标准价格的 5%。关键在于两项折扣不是相加，而是相乘。

我直接计算了差异。假设有 100 个任务，每个任务包含 1 万 Token 的静态上下文、500 Token 的动态输入和 1,000 Token 的输出，然后按 Opus 4.8 的价格比较四种策略。

只用缓存可节省 57%，只用批处理可节省 50%，两者结合则可节省 79%。原因是折扣并非简单相加，而是在静态输入部分相乘。（输出 Token 不属于缓存对象，只享受批处理的 50% 折扣，所以输出占比越高，整体节省幅度就越低于 79%；静态输入占比越高，相乘效果越明显。）夜间建立代码库索引、发布前文章评估、数据提取、定期报告等场景，并不需要人守在屏幕前等待，其范围比想象中更广。

但并非所有任务都能延后异步处理。在编程智能体主会话或交互式聊天界面中，用户需要根据回答决定下一步行动，响应时间本身就是价值，Batch 并不适合。仅仅把任务分为“必须马上看到结果”和“下次上班前收到即可”两类，就可能让账单减半。

用 Subagent 隔离高输出量任务

直接引用 Claude Code 官方文档的表述，subagent“在自己隔离的上下文窗口中运行，中间工具调用及其结果留在 subagent 内，只有最终消息返回父级”。也就是说，把高输出量任务整体委派出去，父级上下文中只会留下整洁的摘要。Anthropic 的 context engineering 文章指出，即便 subagent 在探索中使用数万 Token，通常也只会向父级返回一份压缩到 1,000～2,000 Token 的摘要。保持父级上下文轻量的效果非常明确。

高输出量任务是指为了得到一行答案，在过程中吐出大量 Token 的任务，例如运行测试、搜索文档、分析日志等。

不过有一点需要澄清：subagent 并不等于总成本下降。Anthropic 自己的报告称，智能体使用的 Token 约为普通对话的 4 倍，multi-agent system 则约为 15 倍。subagent 是把大量输出从昂贵的长期上下文中移走，从而守住正确率和父级成本的机制，并非无条件削减总 Token 开支的魔法。因此，应遵循前文的原则：只有“整理主上下文所省费用高于启动成本”时才委派；短任务由父级直接完成更便宜。

还需要考虑适用领域。Anthropic 的 multi-agent research system 报告称，在内部评估中，Opus 4（负责人）＋Sonnet 4（多个 subagent）的组合相较单个 Opus 4 智能体性能提高了 90.2%。但这种提升并非在所有领域都一样。同一篇文章明确指出，“需要智能体共享同一上下文，或智能体之间依赖关系很多的领域不适合多智能体”，并把编程工作列为典型例子。研究任务可以沿独立方向并行探索，代码则运行在依赖图上，一个函数的变化会影响其他函数。（如果你正在把多智能体用于编程，不妨重新确认工作流是否真的接近并行探索。单个智能体加一个隔离的探索 subagent，或许是编程领域更安全的默认方案。）

compact 与 progressive disclosure

Claude Code 的 /compact 会把截至当前的整段对话压缩成摘要，再以新上下文重新开始。按 Anthropic 官方说明，压缩并非简单截断，而是按语义总结：保留正在进行的任务背景与近期变更，丢弃重复工具输出等不太需要再次引用的内容。/clear 会清空一切，而 /compact 会留下摘要；当上下文窗口接近占满 95% 时，auto-compact 会自动执行相同操作。在适当节点整理过长会话，就能切断输入 Token 的累积。

再深入一点，/compact 只是用户显式调用的最后阶段，在它之前还有四级自动上下文压缩流程。根据分析 Claude Code 内部机制的外部研究《Dive into Claude Code》，每次调用前，query.ts 都会依次检查以下五个阶段。

• Budget Reduction 会截掉单个工具输出超过大小上限的部分。
• Snip 会按时间轴截去较旧的历史记录。
• Microcompact 在保留缓存感知能力的同时进行细粒度压缩。
• Context Collapse 在 read-time 重新投影超长历史记录，以降低维度。
• Auto-Compact 在达到 95% 时作为最后手段，按语义执行压缩。

越靠上越轻量、越便宜，越靠下越重但效果也越强。五级结构的设计依据是：单一压缩策略无法解决所有上下文压力。用户显式调用 /compact，近似于提前触发自动流程的最后一级。

相似思路也体现在 Claude Code 的 Skills 结构中。/compact 是事后缩减已累积的上下文，而 /skills 的三级加载则从一开始就避免累积。

根据 Anthropic 文档，技能分三阶段加载。会话开始时，上下文中只有名称和一行说明（约 100 Token）；正文（SKILL.md，少于 5,000 Token）直到技能被触发才加载；打包脚本或资源通过 bash 执行时，只把输出返回上下文，代码本身不会进入。因此，即使安装几十个技能，初始上下文也几乎不会增加。

model routing：答案相同，就交给更便宜的模型

Opus 4.8 与 Haiku 4.5 的输入价格相差 5 倍。如果连简单搜索、探索、短摘要都一律交给最大的模型，成本损失会很大。按照任务难度沿 Haiku → Sonnet → Opus 逐级路由，只在真正需要重度推理的阶段调用 Opus，正在成为标准模式。LMSYS 的 RouteLLM 研究展示了一种路由器：在保持 GPT-4 质量 95% 的同时，把强模型调用比例降至 14%（需要注意，这项基准针对一般推理，并非编程专项）。

工具版图也在迅速稳定。商业网关有 OpenRouter、Martian、NotDiamond，开源自托管阵营则有 LMSYS 的 RouteLLM，以及 LiteLLM、Bifrost 等成本可视化层。在 Anthropic 生态中，Agent SDK 的模型选择参数、Claude Code subagent 的 model 字段（Explore 默认使用 Haiku）、/model 斜杠命令，都是为路由准备的机制。不过需要指出，直接调用 API 时，并不会根据输入难度自动选择模型。Anthropic、OpenAI、Google API 默认都会严格使用用户指定的模型名；自动路由只在产品层（Cursor 的 Auto、ChatGPT 的自动模式、OpenRouter 的 openrouter/auto）作为可选项存在。想通过路由降低费用，无论接入网关还是部署分类器，都要自行构建。

但也不能盲目接入外部自动路由器。OpenRouter Auto Router 这类每次调用都动态换模型的路由器，与前文的 prompt caching 正面冲突。Anthropic 的 ephemeral cache 只有在模型相同、前缀相同时才能命中；每次调用改变模型键，缓存键就会错位。缓存读取原本能降低九成单价，这个效果会完全丢失。用路由省下近一半，又因缓存未命中全部吐回去的情况并不少见。OpenRouter 意识到了这一点，才会推荐基于 session_id 的粘性选项。

因此，业界最终形成的方案反而很简单：不要每次调用都动态分类，而应按任务类型静态分支。前文 subagent 的 model 字段就是这种模式。Explore subagent 始终走 Haiku 的代码探索通道，代码审查 subagent 始终走 Opus 的审查通道。每条通道内重复相同模型、系统提示词和工具定义，各模型便能分别积累并命中自己的缓存。所以“路由正在成为标准”更接近这样的含义：标准并非每次运行分类器的动态路由，而是“协调者＋执行者”形式、按任务类型划分的静态分支。路由与缓存能在同一设计中不矛盾地共存，原因就在这里。

Cursor Composer 2.5

这是一种稍有不同的节省方法：使用 Cursor 这样的智能体。Cursor 于 2026 年 5 月 18 日发布的自研模型 Composer 2.5以 Moonshot AI 的开源检查点 Kimi K2.5 为基础，针对编程任务进行了微调。Cursor 团队称，在自有基准中，它以大约十分之一的价格实现了可与 Claude Opus 4.7 相当的编程性能。公开基础价格为输入 $0.50、输出 $2.50；与 Opus 4.8 的输入 $5.00、输出 $25.00 相比，正好低一个数量级。

专用模型的基准数值由 Cursor 自己测量，因此与其照单全收绝对值，不如把它看作一种趋势：“面向编程训练的小模型，可以在与通用前沿模型相同的任务上达到相近的实用性能，同时把成本降低一个数量级。”这是 2026 年最明显的节省趋势之一。

真正有趣的不只是单价，而是与 IDE 共同设计时，输入 Token 本身也会减少。Composer、Cascade 等模型经过训练，可以高效消化 IDE 发送的代码库上下文（当前文件、相邻文件、已建立索引的符号）。同一任务中，通用模型往往要求“再给我看看相关文件”，反复执行 grep、read，输入 Token 随之膨胀；专用模型可减少这部分开销。单价降低一个数量级，再叠加 Token 数略减，实际节省会超过单纯的价格差。

把上下文移到上下文之外

2026 年最值得关注的趋势，是只在“需要的时候，放入需要的内容”。Anthropic 称之为 just in time（JIT）上下文。它不把全部资料预先塞进上下文，而是只保留文件路径、查询等轻量引用，真正需要时再通过工具取回。Claude Code 不会把整个代码库建立索引后全部装载，而是通过 glob、grep 随用随读，正是这一模式。

Anthropic 随 Sonnet 4.5 一同发布的 memory tool 与 context editing，也源于相同理念。这里要特别说明：memory tool 的“记忆”与常见理解不同。它既不是会话内累积的对话记录（存在于上下文窗口中，会话结束便消失），也不是 CLAUDE.md 这类由人预先编写、启动时自动加载的配置文件。memory tool 是由模型直接读写文件的工具。

深入来看，两种工具的设计接口出乎意料地简单。memory tool 让 Claude 对用户基础设施中的专用记忆目录执行创建、读取、更新、删除文件四类操作。模型不是把内容“写到某段文本里”，而是像使用普通文件系统一样管理记忆。保存位置放在用户基础设施中是关键：Claude 得以在上下文窗口外持久保留记忆，而数据如何存储和保管仍由用户控制。会话记忆在上下文内会消失，这类记忆却留在外部并延续到下一会话。context editing 从相反方向完成同一件事：接近 Token 上限时，自动清除陈旧且不再引用的工具调用结果，保留对话脉络，让智能体能运行更久。

Anthropic 自己的评估显示，两者结合后相较基线性能提升 39%，单用 context editing 提升 29%；在 100 轮网页搜索评估中，Token 消耗减少 84%。（应考虑这是供应商自有基准，但方向十分明确：上下文设计的重点正从填满转向腾空。）这一趋势与 Claude Code 的 /compact 五级流程一脉相承。区别在于，/compact 在上下文内部做减法，memory tool 则在上下文外设置独立存储。两者并不冲突，而是互相补充。

结语

梳理到这里，节省 Token 最终可归结为三条轴线：同一件事，发送更少；同一份输入，用更低价格发送；同一个答案，交给更便宜的模型。Prompt caching、Batch API、subagent 隔离、/compact、memory tool 与 context editing、model routing、专用模型等模式，区别只在于它们攻击三条轴线中的哪一条。若用一句话概括 2026 年的趋势，那就是上下文的重心正从“填入内容的技术”转向“腾空并筛选内容的技术”，也就是 context engineering。正如 context rot 所示，轻量上下文不仅省钱，也有利于正确率。

当然，不存在唯一答案。不同团队的工作模式不同，同一个人写文章和写代码时，成本结构也不同。但有一点可以确定：生态变化越快，“昨天有效的节省模式今天仍然有效”这个假设就越危险。持续追踪新模型、新工具和新价格表，并在自己的任务上用小型 POC 验证，或许才是最不起眼却最持久的节省方法。也建议读者试着翻开自己的 Token 账本看一看。（如果想了解这些策略为何有效，可以到“Token 的工作原理”中继续阅读 BPE 与 KV cache。）

最后还剩下一个问题：当我们已经学会腾空和筛选上下文，下一步会走向哪里？沿着公开资料看，重心正向上下文再外移一层，扩展到如何运行智能体整体系统（harness 设计）、如何衡量它是否运行良好（eval），以及出错时如何限制它（containment）。有趣的是，本文一直强调的“亲自用 POC 测量”，一旦扩展到系统层面，就恰好成为 eval。关于接下来的方向，我准备在 上下文之后中另行详述。

过去，我主要关注如何用好 AI 工具、哪些工具正在流行，以及它们为什么会流行。但在整理 Token 节省方法时，我重新意识到一件事：要讲清怎样降低成本，终究得先说明“Token 是什么、费用又是怎样计算的”，可我此前从未认真补上这块基础。（写着写着，光是 Token 工作原理就已经足够单独成篇了。）

因此，本文是进入节省技巧前的基础篇。我们将依次梳理：如果 Token 既不是单词也不是字符，它到底是什么（BPE）；它以什么形式进入模型（embedding）；为什么输出比输入更贵（prefill/decode）；prompt caching 降低单价的原因来自 Transformer（神经网络架构）的哪个环节（KV cache）；以及上下文越长为什么越贵（注意力的平方成本）。如果更关心实践方法，可以读完本文后继续阅读 Token 节省方法。

Token 既不是单词，也不是字符

先从最基本的事实说起：Token 既不是单词，也不是字符。 它是模型把训练数据中频繁出现的字符序列压缩后建立的一种词表单位。

人类凭直觉询问“这句话有几个词”的方式，与模型切分文本的方式并不相同。模型会把经常共同出现的字符组合归为一个单位，并在文本输入时按照这套词表将其切分。因此，同样是一个单词，有的只对应一个 Token，有的却会被拆成多个 Token。

构建这套词表的算法，就是几乎所有现代 LLM 都共同依赖的 BPE。

BPE 算法

BPE（Byte Pair Encoding，字节对编码）会反复将最常共同出现的相邻符号对合并为一个新符号，从而逐步扩充词表。

有趣的是，它最初并非为自然语言处理而生。Philip Gage 在 1994 年首次将 BPE 作为一种数据压缩技术提出：用数据中未使用的一个字节替换出现频率最高的字节对，并把替换规则单独存入一张表。

后来，爱丁堡大学 Sennrich 团队把它引入了神经机器翻译的词表问题。在 2015 年公开、并于 ACL 2016 发表的论文《Neural Machine Translation of Rare Words with Subword Units》中，他们用 BPE 解决了固定词表无法处理生僻词和陌生词的局限。其思路是：与其完整记住单词，不如用更小的子词片段组合来表示，这样即使词表中没有某个单词，也能用已有片段编码出来。

它的工作流程出乎意料地简单。

1. 一开始，每个字符都是一个 Token。
2. 在语料库中找出最常相邻出现的 Token 对。
3. 把这对 Token 合并成一个新 Token，并在整个语料库中用新 Token 替换它们。
4. 重复第 2～3 步，直到词表达到目标大小。

因此，起初每个字符都是一个 Token；随后，“th”“the”“tion”等频繁出现的组合会逐渐合并成单个 Token。换句话说，越常见的模式，越容易形成更大的块。

GPT 系列在此基础上更进一步，采用字节级 BPE。它先把文本转换为 UTF-8 字节流，再应用 BPE。这样既能让基础词表从 256 项（字节的种类数）开始，又能在没有未知 Token 的情况下编码任何可由 UTF-8 表示的文本。无论是表情符号、汉字还是特殊符号，至少在字节层面都一定能够表示。

相同文本，不同 Token 数

由于这种结构，同一段文本在不同 tokenizer（把人类书写的文本切成模型可处理 Token 的工具）中可能得到截然不同的 Token 数。词表的训练方式不同，同一句话就可能被切得更细，也可能组成更大的块。

OpenAI 随 GPT-4o 一起发布的资料清楚展示了这种差异。GPT-4o 系列的新 tokenizer o200k_base，比 GPT-4 系列的 cl100k_base 能用更少 Token 表示同一文本。英语的效率只提高约 1.1 倍，但越到非英语语言，差距越明显。在官方公布的短例句中，中文和日文的 Token 数约减少 1.4 倍，韩文约 1.7 倍，印地语最多约 2.9 倍。（从韩语用户的角度看，tokenizer 代际差异比英语用户感受到的更明显，这一点很有意思。）

从更广的范围看，语言本身也存在差异。Yennie Jun 使用 cl100k_base 比较多种语言后发现，表达相同含义时，英语几乎总是需要最少的 Token，而采用独立文字体系的语言往往会被切成更多 Token。印地语和孟加拉语可能需要英语的 5 倍，缅甸语甚至超过 10 倍。韩语和中文也比英语使用更多 Token，但没有那些语言那么极端。

这带来一个重要的实践结论。Anthropic 从 Opus 4.7 起引入新 tokenizer，并在官方定价文档中明确指出：“相同文本相较旧模型，最多可能按多 35% 的 Token 计费。”即使每 Token 单价不变，Token 数增加也会让账单同比增加。 因此，诚实地比较模型不能只看单价，还必须看“单价 × 预期 Token 数”。

不过，这些被切分的 Token 进入模型时，并不是以字符或单词原样进入。那么，Token 究竟以什么形态作为模型输入？

Token 如何进入模型

神经网络不能直接处理文本。模型最终能够计算的只有数字，更准确地说，是向量（由多个数字组成的数组）。所以 Token 在进入模型前，要经过若干步骤转换为数值。

按顺序来看，流程如下。

1. 文本 → Token：BPE tokenizer 将文本切分为 Token 片段。
2. Token → Token ID：每个 Token 都会映射到一个整数 ID，指向它在词表中的位置。例如，如果 " the" 是词表中的第 1,234 个 Token，它的 ID 就是 1234。
3. Token ID → embedding 向量：用这个 ID 取出 embedding 矩阵中对应的一行。embedding 矩阵是一张尺寸为 vocabulary size × model dimension (d_model) 的巨大表，每个 Token ID 对应其中一行，也就是一个向量。可以把这个向量理解为承载 Token“含义”的一组坐标。
4. 加入位置信息：自注意力本身并不知道 Token 的顺序。也就是说，它会把“我喜欢你”和“你我喜欢”看成相同内容。因此，需要向每个 Token 向量注入位置信息，让模型知道排列顺序。

仅靠文字会显得抽象，因此这里放了一个可以亲手操作这四个步骤的交互工具。改变输入句子或点击某个 Token，就能沿着它从 ID 变成 embedding 向量、再加入位置信息成为最终输入向量的路径查看。（展示时减少了维度数量，但实际 GPT-4 的向量有 12,288 维，可以带着这个概念观察。）

这里的模型维度（d_model）是表示一个 Token 的向量长度。最初的 Transformer 论文中，这个值是 512；如今的 LLM 则大得多。（仅 Llama 2 的 7B 模型就有 4,096 维。）模型维度越大，越能丰富地表达 Token 含义的细微差别，但计算量和内存占用也会随之增加。

注入位置信息的方式也随着技术演进而变化。最初的 Transformer 直接把用正弦和余弦函数构造的位置向量加到 embedding 上；如今公开 LLM 事实上普遍采用 RoPE（Rotary Position Embedding，旋转位置 embedding），通过旋转 Query/Key 向量，在注意力计算阶段注入相对位置。（方式虽不同，目的都是“让 Transformer 获得顺序感”。）

简而言之，完整流程是：文本 → Token → Token ID → embedding 向量（+ 位置信息）→ Transformer 输入。账单上的“Token 数”，就是这个流程第二步的数量，也就是文本被切成了多少个 Token。

至此，我们已经知道 Token 如何生成，又以什么形式进入模型。那么模型处理这些 Token 时，输入和输出成本为何相差如此悬殊？重复发送相同输入的成本又如何降低？

为什么输入便宜、输出昂贵

接触过 Token 的人多半都疑惑过：定价表上，输出 Token 往往比输入 Token 贵好几倍。 Anthropic 的所有模型中，输出单价都恰好是输入单价的 5 倍。（Opus 输入 $5／输出 $25，Haiku 输入 $1／输出 $5。）明明是同一个 Token，为什么进入与输出时价格不同？

答案在于，模型处理输入和输出 Token 的方式完全不同。LLM 推理分为两个阶段。

• prefill（输入处理）：把提示词中的全部 Token 一次性并行处理。无论是 1,000 个还是 10,000 个 Token，GPU 都会一并扫描，计算每个 Token 的 K/V（Key/Value）。虽然总计算量很大，但并行处理让每 Token 的效率很高。
• decode（输出生成）：响应 Token 一次一个、按顺序生成。每生成一个 Token，就把它追加到输入中，再生成下一个，直到响应结束。

这种不对称造成了成本差异。Databricks 的推理性能分析指出，prefill 是受计算能力限制的阶段，而 decode 是受内存带宽限制的阶段。decode 每生成一个 Token，都必须从 GPU 内存重新读取整个模型的权重，可一次却只得到一个 Token。GPU 庞大的计算能力大部分都处于闲置状态。（借用 Databricks 的说法，就是花钱开着 GPU，却没能利用可用的计算能力。）

也就是说，输入 Token 能在并行 prefill 中一次高效处理，输出 Token 却必须逐个低效地挤出来。 需求、利润等商业因素当然也可能影响定价，但至少从技术上看，decode 阶段的这种低效构成了底层原因。因此，“缩短输出”不只是一条普通的省钱技巧，而是在直接削减最昂贵的阶段。

那么，有没有办法让低效的 decode 稍微高效一些？KV cache 正是在这里登场。

缓存降低单价的原理

prompt caching 会先把静态输入存入缓存，让后续调用以低得多的价格再次读取。按照 Anthropic 官方文档，缓存读取的价格是基础输入单价的 0.1 倍，也就是 10%。缓存写入在 5 分钟 TTL（Time To Live，缓存有效期）下为 1.25 倍，在 1 小时 TTL 下为 2 倍。也就是第一次调用多付一点，从第二次起节省 90%。

但为什么价格能下降 90%？为什么“前缀必须完全一致”的条件如此严格？只要看一眼 Transformer 内部，两者的答案就会清晰起来。

KV cache

模型处理输入 Token 时，会为每个 Token 创建对应的 Query/Key/Value（Q/K/V）向量。自注意力用 Query 与 Key 的点积计算注意力分数，再用这些分数对 Value 做加权和得到输出。可以把它理解为决定一个 Token 应该“参考”其他 Token 多少的计算。

前面提到的 decode 阶段正是在这里遇到问题。每生成一个新 Token，都需要前面所有 Token 的 K/V；如果每次都从头计算，同样的 K/V 就会无休止地重复计算。

KV cache 正是为了消除这种重复而引入。它会存储计算过的 K/V；生成新 Token 时，不再重新计算前面 Token 的 K/V，而是从缓存读取并复用。这样，在一个序列中多生成一个 Token 的成本，就从每一步都重算整个序列的 O(n²)，降为只需读取缓存的 O(n)。（严格说来，这是每一步的成本；核心思想很简单：“已经算过的就不要再算。”）decode 之所以受内存限制，也因为每一步都要从内存重新读取这份 KV cache。

跨调用复用

如果说 KV cache 最初是为了加速单次响应内部的 decode，那么 prompt caching 的想法就是把这套内存结构不只用于一次调用内部，而是在调用与调用之间继续复用。

静态前缀（系统提示词、工具定义、代码片段等每次基本相同的开头部分）的 K/V，会在 5 分钟或 1 小时 TTL 内留在 GPU 内存中。下一次调用若从相同前缀开始，模型就会完全跳过这部分 K/V 计算，直接从缓存读取。准确地说，并不是输入 Token 单价凭空变低，而是计算这些 Token 所需的 GPU 工作本身消失了。 90% 的降价，是把节省的计算反映到价格上的结果。

理解这一机制后，也就能自然明白“前缀必须完全一致”为何如此严格。缓存命中通过比较前缀的累计哈希来判断；而自注意力具有因果性，只要前面的一个 Token 改变，后面所有 Token 的 K/V 都会改变。哪怕只在提示词最前面加入一行时间戳，它每次调用时变化，都会让前缀哈希不同，使后续整段缓存失效。

Anthropic 的缓存按 tools → system → messages 的层级顺序读取。因此，前部哪怕只改动一个工具定义，后面的全部缓存也会失效。结论很简单：静态内容放前面，每次变化的动态内容放后面，缓存才能存活。

缓存还有一些不太为人熟知的限制。可缓存的最少 Token 数会因模型而异，同一系列的不同版本也可能不同。短于这一阈值的提示词即使开启缓存，也会悄无声息地不被保存。（这些最少 Token 数和不同服务商的缓存策略直接关系到成本设计，因此我在 Token 节省方法一文中结合定价表作了详细说明。）

上下文窗口为什么形成 Token 上限

最后，谈 Token 绕不开的概念是上下文窗口：模型一次最多能够接收多少 Token。理解这项限制为何存在，也就能看清“上下文越长越贵”这句常见警告背后的原因。

关键在自注意力的计算结构。注意力会让每个 Token 各自参考所有其他 Token 一次。若有 n 个 Token，Token 对的数量就是 n × n，也就是说，自注意力的计算量与内存需求会随序列长度 n 的平方增长。 Token 数翻倍，注意力成本就变为 4 倍。（需要说明的是，并非整个模型都是 O(n²)，而是注意力阶段如此。）

Hugging Face 的估算清楚展示了这种平方增长有多陡。在未经优化的标准注意力中，仅保存注意力分数矩阵，输入为 1,000 个 Token 时约需 50MB；16,000 个 Token 时约需 19GB；100,000 个 Token 时则接近 1TB。

此外，前面提到的 KV cache 也会按 Token 数量占用内存。上下文越长，必须保存的 K/V 就越多，并呈线性累积。因此，上下文窗口上限本质上是模型面对“再长下去，内存和计算就无法承受”这一物理限制所划出的边界。

所以，原样保留一段很长的对话，不只是增加输入 Token 数这么简单。注意力成本按平方增长，而且 Token 数越接近上限，模型准确处理信息的能力也会下降。（这种准确率下降与 Token 节省方法一文所谈的上下文退化直接相关；保持上下文精简之所以同时有利于成本和答案质量，原因就在这里。）

总结

梳理到这里，Token 的工作原理可以浓缩为几个简单事实：Token 是 BPE 把高频模式合并后形成的词表单位，它经过 Token ID 映射，变为 embedding 向量后进入模型。输入可以通过并行 prefill 一次处理，而输出必须逐个 Token 挤出，因此更加昂贵；KV cache 则通过复用 K/V 来缓解这种低效。缓存能降低单价并不是魔法，而是 Transformer 不必重新计算已经算过的 K/V；前缀必须完全一致这一严格条件，也直接源自这种结构。最后，上下文越长越贵，是因为注意力成本按 Token 数的平方增长。

掌握这层基础后，成本问题就清楚得多。为什么输出贵、怎样安排提示词才不会破坏缓存、为什么应当保持上下文精简、在答案相同时为什么应该换用更便宜的模型——这些节省策略都建立在上述原理之上。如果你是为了理解工作机制读到这里，不妨继续阅读 Token 节省方法，看看这些原理如何真正降低费用。

本文写给这样的开发者：一个项目里同时堆着 CLAUDE.md、AGENTS.md、SKILL.md 和 .cursor/rules，却搞不清它们各自何时被读取、该写些什么。读完之后，你会了解这些文件的区别、智能体读取它们的方式，以及基于 ETH Zurich 研究的判断标准：只写智能体无法推断的信息。

作为一名前端开发者，我在日常工作中经常使用 Claude。渐渐地，项目根目录里多出了 CLAUDE.md，旁边还有别人创建的 AGENTS.md，某个角落仍留着 .cursorrules，我也曾照着某篇文章建起 .claude/skills/ 文件夹。（回过神来，记录着相似内容的文件已经有五个左右了。）

没有持久记忆的智能体

AI 编程智能体存在一个根本局限：它没有持久记忆。每个 session 都从空白状态开始，昨天约定的 convention，或一小时前介绍过的文件夹结构，到了下一次对话就无法记住。上下文文件是解决这个问题最简单的装置：只要在项目中放置一个每次 session 开始时都会自动读取的文件，就不必反复说明同一件事。

问题在于，各种工具围绕同一种思路分别创建了自己的文件。Claude Code 读取 CLAUDE.md，Cursor 读取 .cursorrules（现已 deprecated，官方建议改用 .cursor/rules），GitHub Copilot 读取 .github/copilot-instructions.md，OpenAI Codex 则读取 AGENTS.md。当一个团队同时使用多种工具时，同样的内容就得复制到四个地方。

CLAUDE.md

CLAUDE.md 是 Claude Code 在 session 开始时自动读取的文件。根据 Anthropic 官方文档（code.claude.com/docs/en/memory），Claude Code 会在以下三个层级查找 CLAUDE.md。

• 用户记忆（~/.claude/CLAUDE.md）：适用于本机所有项目的全局默认值
• 项目记忆（项目根目录下的 CLAUDE.md）：提交到 git，由整个团队共享
• 本地记忆（子目录中的 CLAUDE.md）：仅在该目录内工作时额外加载

三个层级同时存在时，Claude 会全部读取并串联（concatenate）。它并非按优先级只选一个，而是像 CSS cascade 一样，将更具体的内容继续叠加上去。（这是合并，不是覆盖。）因此，如果把同一主题的规则分散到多个层级，就可能产生冲突。（Anthropic 官方文档明确指出，指令冲突时的行为不受保证。）

这里有一点经常被忽略：Claude 会从当前工作目录一路向上走到仓库根目录，并读取沿途遇到的所有 CLAUDE.md。所以在 monorepo 的 packages/ui/ 中工作时，根目录的 CLAUDE.md 与 packages/ui/CLAUDE.md 都会被加载。（这很强大，但也意味着上下文可能在不知不觉间膨胀。）

AGENTS.md

AGENTS.md 是为解决上述各工具专属文件泛滥而创建的标准。2025 年 12 月，OpenAI 将这一标准捐赠给 Linux Foundation 旗下的 Agentic AI Foundation（AAIF）。据 Linux Foundation 的公告，AAIF 由 Anthropic、Block、OpenAI 共同创立，创始项目有三个：Anthropic 的 MCP（把智能体连接到外部系统的协议）、Block 的 goose，以及 OpenAI 的 AGENTS.md。官方网站（agents.md）明确表示，已有超过 6 万个开源仓库采用该文件。

看看支持工具的名单，这一点就更清楚了。OpenAI Codex、Google Jules、VS Code、GitHub Copilot、Cursor、JetBrains Junie、Aider、Devin、Zed、Factory、Warp、goose、opencode、Amp、RooCode、Gemini CLI、Kilo Code、Phoenix、Semgrep、Ona、Windsurf、Augment Code 等众多工具都提供支持。GitHub Copilot 从 2025 年 8 月起原生支持 AGENTS.md。有趣的是，Claude Code 对 AGENTS.md 的原生支持目前仍处于 active feature request 状态。Claude Code 依然将 CLAUDE.md 视为主要文件。

它虽被称为标准，但人们可能仍会怀疑是否真的有人采用。最有力的证据就是 dogfooding，也就是亲自使用自己制定的标准。

• Vercel/Next.js 的 canary 分支根目录中有一个 AGENTS.md。它实际上是指向 CLAUDE.md 的符号链接，其中包含 monorepo 结构、通过 pnpm --filter=next dev 进行 1～2 秒级迭代、Turbopack 与 Webpack 双端测试指南、pr-status 脚本，以及环境变量和 secret 的处理规则。create-next-app 后来改为在新项目中同时生成 AGENTS.md 和 CLAUDE.md，也是同一趋势的体现。
• OpenAI/codex 仓库本身也维护着自己的 AGENTS.md。

一种标准策略正在逐渐成形：将 AGENTS.md 作为单一信息源（single source of truth），尽可能精简 CLAUDE.md，只保留一行对 AGENTS.md 的引用，以及 Claude Code 专用指令。这样既消除了重复，又因为 Claude Code 会读取两个文件而不会丢失任何信息。

SKILL.md

SKILL.md 与前两个文件性质不同。CLAUDE.md 和 AGENTS.md 是始终存在于上下文中的持久指令，而 Skill 是只在需要时调用的按需能力。

Skill 以文件夹为单位组织。文件夹中包含一个 SKILL.md、该 Skill 会执行的脚本，以及额外的 Markdown 文档。只有当前任务与 Skill 的 description 匹配时，Claude 才会加载该文件夹。这称为 progressive disclosure（渐进式披露）。这一概念由 Jakob Nielsen 于 1995 年在 UX 领域确立：把高级或较少使用的功能放到辅助界面，让用户一次只专注于一项任务，从而降低认知负荷和错误。在 Claude Skills 的语境中，它指“只在需要时才把 Skill 正文载入上下文”的机制。这样可以大幅节省上下文窗口成本。

SKILL.md 的 frontmatter 中有几个独有字段。

• description：说明何种情况下需要该 Skill，是模型判断是否调用它的触发条件
• allowed-tools：限制 Skill 内可使用的工具（例如 "Read, Glob, Grep, Bash(python:*)"）
• disable-model-invocation: true：禁止模型调用，只允许用户通过斜杠命令触发。用于部署、提交等带有副作用的操作
• user-invocable: false：不在用户的斜杠菜单中显示，仅由 Claude 自主调用，适合作为背景知识

Claude Skills 于 2025 年 10 月 16 日在 Claude.ai、Claude Code、API 与 Agent SDK 中同时推出。随后在 2025 年 12 月 18 日，Anthropic 又将 Skills 规范本身发布为开放标准（agentskills.io）。Simon Willison 甚至评价道：“Skills are awesome, maybe a bigger deal than MCP。”原因在于，它的形式比 MCP 简洁得多，同时借助 progressive disclosure 解决了上下文窗口成本问题。

这里与 Skills 相比较的 MCP（Model Context Protocol），是把智能体与 Slack、GitHub、DB 等外部系统连接起来、使其能够调用这些系统的标准协议。如果说上下文文件关乎该告诉智能体什么，MCP 关乎的就是该让智能体能做什么。MCP 与 function calling 有何不同，另外整理在MCP 与 function calling中。

帮助智能体降低查找相关代码成本的工具（Repomix、Aider、CodeGraph、Serena），因理解代码的深度不同，所降低的成本也不同。相关比较另外整理在代码智能的四个层级中。

其他工具使用的文件

Cursor 的 .cursorrules 从 0.43 版本起已 deprecated。目前官方建议在 .cursor/rules/ 目录中放置多个 .mdc 文件。每个 .mdc 文件都带有 YAML frontmatter。

• description：供智能体判断该规则是否相关
• globs：当匹配的文件进入对话时自动附加（auto-attach）
• alwaysApply：设为 true 时无条件加入每次对话（此时忽略 globs）

GitHub Copilot 也朝着类似方向演进。仓库全局指令放在 .github/copilot-instructions.md 中；需要按路径限定作用域的指令，则放进 .github/instructions/*.instructions.md 文件，并通过 frontmatter 的 applyTo: 键指定 glob。（Copilot code review 从 2025 年 9 月起正式支持 path-scoped instructions。）

Cursor、Copilot 以外的工具也都在向相似模式靠拢。汇总如下。

尤其值得注意的是 Aider 的 CONVENTIONS.md。官方文档明确指出，由于每次请求都会将该文件完整加入上下文，因此应“保持在 200 行以内”。（可以说，Aider 很早就意识到这一限制，并明确提醒了用户。）

MEMORY.md

除了上述文件，还有一种模式正越来越常见：MEMORY.md。它不是官方标准，而是社区自发形成的 convention，用于记录随时间累积的决策与失误。

## 2026-04-10
Pages Router에서 App Router로 이전. 신규 라우트는 App Router 컨벤션 사용.
 
## 2026-04-22
Prisma 쿼리 결과에 optional chaining 쓰지 말 것 — null은 if-check로 명시적 처리.
(이전에 옵셔널 체이닝으로 null을 흘려보내 프로덕션 이슈 발생.)

如果说 CLAUDE.md 或 AGENTS.md 记录的是当前规则，那么 MEMORY.md 记录的就是这些规则为何形成的历史。（两者是互补关系，而非替代关系。）

智能体如何读取这些文件

到目前为止，我们梳理了有哪些文件。但还有一个经常被遗漏的问题：智能体究竟把这些文件读到哪里，又是怎样读取的？ 理解这一机制，就更容易明白后文 ETH Zurich 的研究结果——上下文文件中的指令并不会被可靠遵循——为何会出现。

首先要明确一个事实：CLAUDE.md 不是 system prompt，而是以 user message 的形式注入。 Anthropic 官方文档明确写道：

CLAUDE.md 的内容会在 system prompt 之后以 user message 的形式传递，而不是作为 system prompt 的一部分。Claude 会读取并尝试遵循它，但不保证严格执行。

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance.

也就是说，它不是强制规则，而是“参考上下文”。如果确实要强制某种行为，官方指南也建议使用 PreToolUse hook 等额外机制。

加载顺序按 broad → specific 逐层叠加。具体来说，是 managed policy（组织级设置）→ 用户全局文件（~/.claude/CLAUDE.md）→ 项目文件（./CLAUDE.md）→ 本地文件（./CLAUDE.local.md）。在同一目录中，先读 CLAUDE.md，再读 CLAUDE.local.md。利用距离最近的指令最后读取这一点，可以借助 LLM 的 recency bias，让更具体的规则产生更强影响。

这里很有意思的是 @import 语法。在 CLAUDE.md 正文的任意位置写入 @path/to/file，对应文件就会在原地展开并一同加载。最大递归深度为 4 hops，相对路径以写有 import 语句的文件为基准解析。因此，官方建议用 @AGENTS.md 建立 bridge。让 CLAUDE.md 几乎保持为空，只写一行 @AGENTS.md，Claude Code 就能自然读取 AGENTS.md。（在 CLAUDE.md 尚未原生支持 AGENTS.md 的现状下，这是最简洁的变通方案。）

token 方面也值得一提。CLAUDE.md 本身没有明确的 token 上限，因此只要存在就会完整加载。不过官方建议每个文件不超过 200 行。超过 200 行后，会“consume more context and may reduce adherence”。有趣的是，在 Claude 4.x 中，仅仅启用 tool use，就会自动通过 special system prompt 增加 346 个 token（以 tool_choice: auto 为准）。上下文就在这些不易察觉的地方不断流失。

Cursor 则采用另一种方式。.cursor/rules/*.mdc 中的规则有四种工作模式。

• Always Apply：无条件加入每次 chat；忽略 globs/description
• Apply Intelligently（Agent Requested）：智能体读取 description，判断相关性后自行调用规则
• Apply to Specific Files（Auto Attached）：与 glob 模式匹配的文件进入上下文时激活
• Apply Manually：用户通过 @rule-name 明确调用

其他工具又有所不同。OpenAI Codex 会从 git 仓库根目录朝 cwd 方向遍历，收集所有 AGENTS.md，并在用户 prompt 之前紧邻的位置注入。GitHub Copilot 则将 .github/copilot-instructions.md 放在上下文窗口的中等优先级：“位于 edit context 与 explicit references 之后，但在 loosely related open files 之前。”即使使用同一个 AGENTS.md 文件，各工具的加载时机、优先级与合并规则仍不相同，因此不能保证三个工具以完全相同的方式理解该文件。

但这里还剩下一个根本问题：为什么模型只遵循上下文中的一部分指令？ 单纯用“指令太长”来解释并不充分。这种现象背后是 LLM 的结构性局限。

幻觉与上下文遗忘

如果你见过 AI 智能体混淆对话语境，或忘掉前面明明说过的内容，那么这正是幻觉（Hallucination）的一种形式。通常提到幻觉，人们首先想到的是“捏造不存在的事实”，但学术上会将其分为三类。Yue Zhang 等研究者在 2023 年的综述《Siren's Song in the AI Ocean》中将它们归为：输入冲突型（生成内容与用户明确提供的内容不一致）、上下文冲突型（与自己先前生成的内容矛盾）、事实冲突型（与世界知识不符）。忽略上下文文件指令属于第一类，而不是第三类。模型在处理输入时，把其中一部分信息当成了“不存在”。

更根本的问题在于，这种幻觉原则上无法彻底消除。新加坡国立大学的研究团队利用学习理论对此作出了数学证明：任何 LLM 都无法学习所有可计算函数，因此只要把它当作通用问题求解器，就必然会在某处产生幻觉。

位置效应也很重要。Stanford 的研究团队通过实验证明，当相关信息位于上下文窗口的开头或结尾时，模型最容易引用；而当信息埋在中间时，性能会显著下降。这与上下文文件直接相关。按照加载顺序，CLAUDE.md 会被插入某个中间位置；随着对话变长，其中的指令也会越来越深地被推向上下文的“中部”。这也对应了前文提到的 recency bias 的另一面：在 primacy-recency 效应中，中间区域最为薄弱。

把这些现象放在一起，就会得到一幅完整图景。上下文文件不过是在 LLM 第一个 user turn 之前，从 system prompt 外部额外插入的文本。它不是强制模型作出某种决策的机制，而只是丢进上下文窗口的另一块 token。文件越长、对话越长，其中的指令就越容易被推向“中间”，引用率也随之下降。ETH Zurich 的结果可以说是对这一结构性局限的量化验证。

ETH Zurich 的研究

很多人可能会想：“那就尽可能多地往这些文件里写内容吧？”近期一项研究正面反驳了这种直觉，也就是前文不断提到的 ETH Zurich 研究。

ETH Zurich 研究团队于 2026 年 2 月发表论文《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》。研究者在由 138 个真实 Python 软件工程任务构成的 benchmark（AGENTBENCH）以及 SWE-bench Lite 上，测试了 Claude Code（Sonnet-4.5）、Codex（GPT-5.2 / GPT-5.1 mini）、Qwen Code 共四种智能体，结果出人意料。

• 由 LLM 自动生成的上下文文件在 SWE-bench Lite 上反而使任务成功率降低约 0.5%，在 AGENTBENCH 上降低约 2%
• 即使是人工编写的文件，平均也只带来约 4% 的小幅改善
• 添加上下文文件后，每个 instance 的推理成本增加了 20% 以上
• 对更强的模型（GPT-5.2）而言，上下文文件效果更加有限（模型越强，parametric knowledge 越充足，额外上下文就越可能成为噪声）

不过有一个例外：明确指定非标准工具时。例如在上下文中指定 Python 包管理器 uv 后，智能体使用 uv 的频率从每个 instance 0.01 次上升到 1.6 次，约为原来的 160 倍。

Aider 的“200 行建议”是实用层面的提醒——文件每次都会进入上下文，所以要保持简短；而 ETH Zurich 的研究则量化证明了“冗长上下文文件会在统计意义上降低性能”。我认为这项研究有以下实践启示。

• 自动生成的巨型上下文文件可能弊大于利。如果把编码规范、架构、workflow 全塞进 300 行的 CLAUDE.md，智能体会遵循其中一部分、忽略其余部分。这种不一致甚至可能比没有上下文更糟。
• 真正必须写下的是“无法推断的信息”。非标准工具、项目专属 convention、过去的失败案例都属于这一类。一般性的编码最佳实践，模型本来就知道。
• 将 AGENTS.md 作为单一来源，CLAUDE.md 只保留简短的工具专用指令，把细致的 workflow 拆分为 Skill。

总结

上下文文件因工具而异，名称、存放位置和被读取的时机都不一样。仅本文提到的就有 CLAUDE.md、AGENTS.md、SKILL.md、Cursor rules、copilot-instructions.md 和 MEMORY.md，哪个工具支持哪个文件也在不断变化。只记住文件清单，很快就会过时。

所以，我想做的不是推荐某种特定的文件格式，而是培养一种看清文件如何被智能体读取的眼光。理解 CLAUDE.md 为何以 user message 注入、不同工具为何以不同方式读取同一个 AGENTS.md、指令为何会在上下文中间变弱之后，新的上下文文件格式出现时，就能快速看懂：“它何时被加载，作用有多强。”

最终留下的，是 ETH Zurich 研究带来的一个直觉：模型本来就知道很多东西。 把所有内容都塞进上下文文件，并不会让智能体更认真地遵循。更好的做法是，只保留模型很可能不知道的信息——项目专属 convention、非标准工具、过去的错误——删除其余内容。把上下文文件写长，与把它写好，是两回事。

我也建议读者不要急着把 CLAUDE.md 扩展到几百行，不妨先深入了解一下，自己当前使用的工具会在何时、放在哪个位置、以多大的力度读取这个文件。无论文件格式如何变化，这种理解都会成为不易动摇的基础。

本文写给这样的开发者：看到智能体在大型代码库中反复 grep 和读取文件、不断消耗 token，正在犹豫该接入 Repomix、CodeGraph、Serena 中的哪一种。这些工具按对代码理解的深度，分为 context packing、tree-sitter repo map、知识图谱、LSP 四个层级，每个层级降低检索成本的位置各不相同。知识图谱附上开发方的基准测试，其余三个层级附上在这个博客仓库上测得的结果。

自从看到 codegraph 登上 GitHub Trending 并跟着安装之后，笔者每次看到新工具，都会好奇它究竟靠什么原理节省 token。本文出现的工具，很多也是笔者在 GitHub Trending 上第一次看到的；笔者平时按 weekly 浏览，并筛选 TypeScript 和 Python。

代码智能工具

智能体在修改代码之前，会先去找相关代码在哪里。用 grep 查找、读取文件、筛选、再 grep，如此循环。在后文要看的 CodeGraph 基准测试中，不用该工具作答的一方，回答一个问题最多用了 43 次 tool call。代码智能工具就是为了降低这种检索成本而出现的各种尝试。

不过，“成本”指的并不是一样东西。模型处理的 token、tool call 的次数，以及工作结束后仍留在 context window 里的 token，三者各自变化。本文逐个层级来看它减少的是这三者中的哪一个。

笔者按照工具对代码理解的深度，把这些尝试分为以下四个层级（tier）。业界并没有既定的分类，这一划分是笔者自己整理的。本文的实测数值，都是 2026-10-08 在本仓库的提交 36e5cfa 上得到的，token 用 tiktoken 的 o200k_base 计数。它与 Claude 的 tokenizer 数值不同，因此用于比较，而不是当作绝对值。

上下文打包

最简单的方案是：“把所有内容都塞进一个 context window。”既不建图，也不做索引，只是把整个仓库序列化为一大块文本，再整体交给模型。

代表性工具是 Repomix。它的默认输出格式是 XML，README 附上了 Anthropic 关于 XML 标签的文档链接。它同时提供 CLI、Web、浏览器扩展与 MCP server。

GitIngest 的优势是无需安装即可使用。把 GitHub URL 中的 github.com 换成 gitingest.com，整个仓库就变成一个文本页面。Rust CLI code2prompt（由 Mufeed VH 开发）可以用模板改变输出格式。

rtk（rtk-ai/rtk）的方向略有不同。上述工具是一次打包整个仓库，而 rtk 压缩的是智能体所执行 CLI 命令的输出。它是用 Rust 编写的单一 binary，注册在 Claude Code、Cursor、Copilot、Gemini CLI、Codex 等多种智能体的 hook 中，当智能体调用 git status 时，会改为执行 rtk git status。它对 100 多种命令应用 filtering、grouping、truncation、deduplication。rtk 的 hook 只以 Bash 的 tool call 为对象。Claude Code 的 Read、Grep、Glob 会直接绕过。

减少的幅度需要小心解读。rtk README 写着能把 Bash 输出最多减少 90%，随即补充说这并不等于账单减少 90%。从模型的角度看，命令输出只是输入 token 的一部分，而输入 token 又只是账单的一部分，所以每经过一步都会被稀释。官方网站 主打的数字是：在 rtk 改写执行的命令上平均减少 56%。如果说前面的工具减少的是输入的文本，rtk 减少的则是作为 tool call 结果返回的文本。

这一层级的局限是：大型仓库会触及 token 上限。仅打包这个博客 src/ 中的 109 个文件，就有 94,596 tokens。这个量还能放进窗口，但如果是有数千个文件的仓库，很快就会触及上限。Repomix 用 --compress 来应对这个问题。根据 README，它用 Tree-sitter 保留函数与类的签名，丢弃实现主体。

# repomix 1.18.1, 이 리포 커밋 36e5cfa, 2026-10-08
npx -y repomix@1.18.1 src -o out.xml              # Total Tokens: 94,596 tokens
npx -y repomix@1.18.1 src --compress -o out.xml   # Total Tokens: 30,320 tokens

减少了 68%。注释会原样保留，因此 JSDoc 较长的 visit-counter.ts 只从 1,642 降到约 1,220 tokens，仅减少 26%。压缩结果中保留了 import 语句和签名，但函数体内的调用会消失。哪个文件引入了什么，从文本中看得出来，但无法询问谁调用谁。因此，这一层级与下一层级的边界，与其说在于是否看得到语法，不如说在于能否就关系发问。

tree-sitter 仓库地图

下一个层级利用 tree-sitter 分析代码结构，但不会另外启动 index server。

这一层级的工具所使用的 tree-sitter，构建的是用树形结构表示源代码结构的 CST（Concrete Syntax Tree）。tree-sitter 官方文档 也写着它构建的是 concrete syntax tree。这是一棵连括号和标点都保留为节点的树，下面这些工具处理的也正是这棵树。

tree-sitter 是一个开源 parser generator 与增量（incremental）解析库。GitHub 的 code navigation 使用了 tree-sitter。由于它只重新解析被编辑的部分，在编辑器中改一行也不会重新解析整个文件，而只修补发生变化的那部分树。这个优势属于编辑不断发生的编辑器。下文的 Aider 则按文件修改时间做缓存，不会重新解析没有变化的文件。

在终端中使用的 AI 结对编程工具 Aider 是这种方法的代表。Aider 用 tree-sitter 从每个文件中提取函数、类、方法的定义与引用。然后构建以文件为节点的图。当文件 A 引用了文件 B 中定义的标识符时，就会产生一条从 A 指向 B 的边。

为了在这张图中挑出重要的文件，Aider 使用 PageRank。PageRank 是一种算法，节点收到的链接越多、越重，得分就越高。Aider 用的是它的变体 personalized PageRank，会让分数向指定节点倾斜。然后按 token 预算，从排名靠前的文件开始放入定义与签名。

预算里放进什么，会随当前对话而变化。在 Aider 的 repomap.py 中，边的权重是引用次数的平方根乘以倍数。对话中出现的标识符乘 10，8 个字符以上的 camelCase、snake_case 或 kebab-case 标识符也乘 10。以 _ 开头的标识符和在超过 5 个文件中被定义的标识符各乘 0.1，从当前加入聊天的文件出发的边乘 50。加入聊天的文件、对话中提到的文件，以及路径或文件名与对话中标识符相同的文件，还会得到 PageRank 的 personalization 分数。

预算也不是固定值。Aider 文档 写的 --map-tokens 默认值是 1k，但 代码 会把模型输入上限的 1/8 截取到 1,024 到 4,096 之间。而且聊天中没有文件时，会放大到 --map-multiplier-no-files（默认 2）倍。笔者用本仓库的 src/ 验证了这一点。实际运行的 0.86.1 与上面链接的提交，排序代码相同。输出的 map 连同 Aider 附加的三行提示文字一起，用 o200k_base 计数。

# aider-chat 0.86.1, 리포 루트에서 시작한다, 2026-10-08
mkdir /tmp/aidermap && cp -R src /tmp/aidermap/ && cd /tmp/aidermap && git init -q && git add -A && git commit -qm init
# 키는 더미 값이다. --show-repo-map 은 map 만 출력하고 LLM 을 부르지 않는다
export OPENAI_API_KEY=dummy
aider_map() { uvx --python 3.12 --from aider-chat==0.86.1 aider --no-check-update --analytics-disable --no-gitignore --model gpt-4o "$@"; }
aider_map --show-repo-map                                              # Repo-map: using 4096 tokens
aider_map --map-tokens 1024 --show-repo-map                            # Repo-map: using 1024 tokens
aider_map --map-tokens 1024 --show-repo-map src/lib/filter-posts.ts    # 이 파일을 채팅에 올린 상태

gpt-4o 的输入上限是 128k，所以 1/8 被截到 4,096；聊天为空，map 就在其两倍以内输出。把一个文件加入聊天后，map 缩到预算以内，原来 27 个文件中只留下 10 个，PostList.tsx 和 SearchModal.tsx 则是新加入的。repo map 不是仓库的固定摘要，而是按那一刻的对话裁出的摘录。

同一层级里还有一个值得一提的工具：ast-grep（ast-grep/ast-grep）。它是基于 tree-sitter 的结构化搜索与 rewrite CLI，匹配的是语法树节点而不是文本。例如，console.log($A) 这个模式会抓住所有以单个参数调用 console.log 的地方，不管换行和空白长什么样。它抓住的是相同的语法结构。它不知道 $A 的类型，也不知道 console 这个名字从哪里来。另外还有 ast-grep-mcp server，可以让智能体用结构化搜索代替文本 grep。

知识图谱

第三个层级更进一步：预先解析整个代码库，构建知识图谱并保存到磁盘，智能体再向保存好的图谱发出查询。最受关注的例子是名为 CodeGraph 的工具。

CodeGraph README 描述的结构很简单。用 tree-sitter 解析代码，提取 symbol、边与文件信息，并把它们保存到本地 SQLite 数据库中。名称搜索通过 SQLite 的 FTS5 索引完成。智能体通过 MCP 向这张图发问。README 描述的步骤中没有出现 LLM。因此笔者认为，这种提取是确定性的（deterministic），也就是同样的代码总会得到同样的结果。

如果由 LLM 摘要代码来构建图谱，即便是相同的代码，结果也可能不同，还可能混入幻觉。反之，直接解析语法树，就只会按语言文法规定的规则提取 symbol 关系，这类解释没有插足的余地。

这里出现的 FTS5（SQLite Full-Text Search 5）是 SQLite 以虚拟表形式提供的全文搜索扩展。根据 SQLite 文档，它自 3.9.0（2015-10-14）起被纳入 amalgamation，可用 CREATE VIRTUAL TABLE ... USING fts5(...) 建表，再用 MATCH 运算符查询。无需另外启动 Elasticsearch 之类的搜索引擎，用一个 SQLite 文件就能持有全文索引。

不过，确定性不等于没有遗漏。同一份 README 把依赖约定和反射的框架的路由识别率记为从 Django 的 74.1% 到 ASP.NET 的 83.9%，并称之为静态分析的上限（honest static-analysis ceiling）。相同的代码会得到相同的结果，但这个结果里可能缺了一些边。

基准测试是 CodeGraph 自己测的。同一份 README 中 2026-08-05 的重新测量，以 headless 方式运行 Claude Opus 4.8，向 7 个开源仓库各提一个架构问题。启用 CodeGraph MCP 的一方，平均成本降低 44%，处理的 token 减少 62%，tool call 减少 88%。这次重新测量在双方都禁止通过 Bash 调用 codegraph CLI。在没有这一限制的测量环境中，不用该工具的一方在 28 次运行中有 26 次找到并用上了 CLI，README 也说明此前公布的数字是在没有这一限制的情况下得出的。

节省幅度并没有跟随仓库规模。在不用该工具的一方用了 28～43 次 tool call 的问题上，成本降低了 57～78%；而在 7 次就结束的 Gin 上，几乎持平。约 11k 个文件的 VS Code 是 71%，约 640 个文件的 Excalidraw 是 78%。README 用问题所需的探索量来解释这一点。每个仓库只有一个问题，所以笔者只读出方向。

README 也记录了方向相反的数字。处理的 token 减少了，但在多轮会话结束时，仍留在 context window 中的 retrieval 结果，在 7 个仓库整体上 CodeGraph 一方多出约 80%。各仓库之间差距很大，仅 VS Code 一个仓库就是 67k 对 18k tokens，约 3.7 倍。原因是它一次返回密集的原文，而这些原文会原样留在窗口里。CodeGraph 以窗口中留存更多为代价，减少了 tool call 和处理的 token。

Cursor 走了另一条路，后来又改变了方向。2026 年 1 月 Cursor 博客 介绍的索引不是语法图，而是基于向量嵌入的语义搜索。它在本地把文件切成 chunk，用 Merkle tree 哈希与服务器同步，并把 chunk 转成嵌入，用于语义搜索。2026 年 7 月，Cursor 的 Community Support Engineer 在论坛上回答：“Semantic/embeddings indexing is being turned down in favor of grep-based retrieval”。同一帖子里，另一位员工写道，随着模型越来越会用 grep，以前的语义搜索路径已不再有实质帮助。现在的 Cursor 文档 写着：Instant Grep 在本机构建并查询索引，不为搜索保存代码库的嵌入。

LSP

最后一个层级直接依赖语言服务器。如果说 tree-sitter 知道“symbol 存在”，那么 LSP 知道“这个 symbol 是什么”。

LSP（Language Server Protocol）是一种基于 JSON-RPC 的开放协议，用来标准化编辑器与语言分析工具（代码补全、跳转到定义、查找引用、重构等）之间的通信。2016 年，Microsoft、Red Hat、Codenvy 宣布了合作。核心思路是：“不要为每个编辑器重新实现语言分析器，而是每种语言放一个服务器，让所有编辑器都去问它。”rust-analyzer 和 Python 的 pyright 是 LSP 服务器，而 TypeScript 使用的是 typescript-language-server，它用 LSP 包装了使用自有协议的 tsserver。

Serena（oraios/serena）是属于这一层级的 MCP server。截至 2026-10-08 有 30,093 stars，仓库创建于 2025 年 3 月。Serena 的核心思路可以用一句话概括：以 symbol 为单位给智能体看代码。 主要工具有 find_symbol、find_referencing_symbols、get_symbols_overview 等。后端可以二选一：默认是实现了 LSP 的语言服务器（免费/开源），另一个选项是利用 JetBrains IDE 代码分析的付费插件（提供免费试用）。

在本仓库里测一下，就能看出差异从哪里来。笔者用两种方式查找了过滤非公开文章的 isHiddenPost（src/lib/filter-posts.ts:12）的使用位置。文本这一侧是 grep。

# 커밋 36e5cfa, 2026-10-08. 이 글도 같은 이름을 담고 있어 content/ 는 뺐다
git grep -n isHiddenPost -- ':!content'   # 16줄, 파일 9개
git grep -n -C1 isHiddenPost -- ':!content'   # 같은 16곳을 앞뒤 1줄과 함께

LSP 这一侧调用的是 Serena 的 find_referencing_symbols。LSP 的查找引用不是按名称，而是按位置（文件、行、列）来问，所以这个工具也要同时接收作为 symbol 名称的 name_path 和定义所在文件的 relative_path。这里没有把 Serena 作为 MCP 服务器启动，而是在同一个提交上从 Python 直接调用了这个工具。

# serena 3b99f8b, 커밋 36e5cfa, 2026-10-08. 리포 루트에서 실행한다
# uvx --python 3.12 --from git+https://github.com/oraios/serena@3b99f8b024dafd58c962ea6e74f37c8a730ef532 python refs.py
from serena.agent import SerenaAgent
from serena.config.serena_config import SerenaConfig
from serena.tools.symbol_tools import FindReferencingSymbolsTool
agent = SerenaAgent(project=".", serena_config=SerenaConfig().with_headless_mode_overrides())
agent.execute_task(lambda: None)  # 언어 서버가 뜰 때까지 기다린다
tool = agent.get_tool(FindReferencingSymbolsTool)
print(agent.execute_task(lambda: tool.apply(name_path="isHiddenPost", relative_path="src/lib/filter-posts.ts")))

输出是一行 JSON。只摘出第一项是这样的。行号从 0 开始计。

{"src/lib/filter-posts.ts": {"Function": [{"name_path": "filterPublishedPosts", "body_location": {"start_line": 22, "end_line": 24}, "content_around_reference": "...  22:export function filterPublishedPosts(posts: Post[]): Post[] {\n  >  23:  return posts.filter(post => !isHiddenPost(post))\n...  24:}"}]}, ...

Serena 返回了 10 处引用。它不包括定义所在的 filter-posts.ts:12，对三个文件中的 import 行，则把该文件本身作为 symbol（File）返回。grep 抓到的 11 处代码位置，等于这 10 处再加上定义那一行。这个名字在仓库中只有一个，所以 grep 既没有漏掉也没有多抓代码位置。grep 多抓的 5 处，是文档中解释这个函数的句子：根目录的 CLAUDE.md，.claude/commands/ 下的 audit.md 和 write-post.md，以及 docs/research/snapshot-20260816/ 中留下的 CLAUDE.md 和 write-post.md 副本。

Serena 会给每个引用附上前后各 1 行再返回。因此 grep 分两种方式运行：只返回行号的 git grep -n，和连前后各 1 行一起返回的 git grep -n -C1，再用 o200k_base 统计三种输出的全部 token。

与连前后 1 行一起返回的 grep 相比，Serena 少 683 tokens。差距来自它不返回 5 处文档。不过 Serena 会给每个引用附上 JSON 形式的 symbol 名称和位置信息，所以只看代码一侧，它反而多 159 tokens。与只返回行号的 git grep -n 的 703 tokens 相比，Serena 的 892 tokens 更多。在这个仓库里，LSP 层级节省的不是搜索结果，而是看到 grep 结果后再去读周边行或文件的下一步。

在这下一步中，如果智能体把 grep 命中的 9 个文件整个读一遍，要读的量是 47,034 tokens，其中 4 个代码文件 3,716，5 个文档 43,318。这是上限。在实际会话中，CLAUDE.md 很可能已经在 context 中，不会再读一次。如果是 isLocale 这样常见的名字，连代码位置的结果都可能出现分歧。

总结

总之，四个层级按对代码理解的深度区分，减少的成本也各不相同。context packing 把代码作为文本交出去，即使加上 --compress 也只保留到语法，减少的是输入的 token。tree-sitter repo map 知道 symbol 存在，用预算给输入的 token 设上限，至于用什么填满这个上限，则由那一刻的对话决定。知识图谱预先保存关系，减少 tool call 和处理的 token，但按厂商自己的测量，留在窗口里的量反而增加了。LSP 连 symbol 是什么都知道，在这个仓库里，它不返回文档中的同名内容，但给每个结果都附上了元数据。节省之处不在搜索结果，而在其后的阅读。

所以，笔者在挑选工具时，比起层级有多深，会先看现在出问题的是哪一种成本。窗口小而会话长，就看留存的量；往返慢，就看 tool call 次数；如果仓库里文档和代码共用同样的名字，就看看到 grep 结果后还要多读多少文件。笔者把 Cursor 拿掉基于嵌入的语义搜索、改用本地文本索引（Instant Grep）这件事，也读作“昂贵的索引不一定总胜过模型自身的检索能力”的信号。

如果这些工具降低的是智能体查找代码的成本，那么智能体从一开始就该知道的项目规则要写在哪个文件、写多少，就是另一个问题了。这部分内容在上下文文件中讨论。

本文写给这样的开发者：在 Claude Code 或 Cursor 中接入了 MCP server，却很难说清它与 LLM API 的 function calling 在哪里分道扬镳。先说答案：MCP 并不取代 function calling。host 应用把从 MCP server 拿到的工具列表转换成 function calling 的 tools 参数传入，再把模型选中的调用转交回 MCP server。读完之后，你会知道 MCP 在此之上增加的四点差异分别来自协议的哪个部分，哪些差异在 2026-07-28 修订版之后依然存在，以及这种结构会打开怎样的攻击面。

笔者作为前端开发者，日常都会使用 Claude，但每次新增一个 MCP server 时，对于这些工具究竟如何进入模型的视野，总是有些模糊。

MCP（Model Context Protocol）

MCP（Model Context Protocol）解决的是“该让智能体能做什么”的问题。

展开来说，AI 智能体若要向 Slack 发送消息，就必须能调用 Slack API；要创建 GitHub issue，就必须能调用 GitHub API；要查询 Postgres，就必须能处理 DB 连接。MCP 就是把所有这些外部系统集成统一到一个标准协议之下。（意思是 client 与 server 按同一套规格连接。）

MCP 是 Anthropic 于 2024 年 11 月 25 日首次发布的开放标准。到 2025 年 12 月 9 日，Anthropic 将 MCP 捐赠给 Linux Foundation 旗下的 Agentic AI Foundation（AAIF）。AAIF 由 Anthropic、Block、OpenAI 共同创立。

MCP 是建立在 JSON-RPC 之上的协议。JSON-RPC 2.0 是一种以 JSON 作为 wire format 的 stateless 轻量级 RPC（Remote Procedure Call）协议。它与传输层无关，可以运行在 HTTP、TCP 或标准输入输出之上。本文以 2025-11-25 修订版为准，在这一版中，MCP 是为每个连接建立 session 的 stateful 协议。之后的修订版改了什么，等看完调用流程再讨论。

六种 primitive

2025-11-25 规范的概览列出了 server 提供的三项功能和 client 提供的三项功能。本文把这六项称为 primitive。这里的 primitive 与 JavaScript 的原始类型（如 string、number）无关，指的是协议所定义的基本交互类型。

Server 侧 primitive

• Tool（model-controlled）：模型自行判断是否调用并执行的操作，可能产生副作用（side effect）
• Resource（application-controlled）：由 URI 标识的数据。规范中只有读取内容的 resources/read，没有写入方法。如何把这些 resource 放入 context，由 host application 决定
• Prompt（user-controlled）：由用户通过斜杠命令等方式明确触发的可复用模板

Client 侧 primitive

• Sampling：让 server 反向请求 client 的 LLM 生成 completion，从而在 client 与 server 之间建立双向结构。它的用途是让 server 在执行工具时需要生成文本，可以不用自己的 API key，借用 client 所用的模型。在 2026-07-28 修订版中，它成为计划移除的 deprecated 状态
• Roots：client 向 server 说明“可操作范围到这里为止”的 workspace 边界信息
• Elicitation：server 在执行工具的过程中，以结构化形式向用户请求补充输入

这种区分之所以重要，是因为由谁决定调用或提供各不相同。Tool 由模型判断并执行，因此存在误调用风险；Prompt 由用户明确选择。Resource 默认由应用选择，但规范也允许依据启发式规则或模型的选择自动纳入的实现。client 侧的三种方向正好相反：由 server 发出请求，是否响应由 client 决定。

两种传输方式

标准传输方式有两种，规范也允许其他自定义传输（MAY）。一种是 stdio：将 MCP server 作为本地子进程运行，通过标准输入输出通信，适合文件系统、git 等在本地工作的工具。另一种是 Streamable HTTP：在 HTTP POST 和 GET 上叠加 SSE（Server-Sent Events）streaming，形成近似双向的通信方式。SSE 是 server 在 HTTP 连接上向 client 单向推送数据的方式。它适合远程 server、OAuth 认证、多 client 连接、云端部署等跨网络场景。

LLM 调用 MCP 工具的流程

了解 primitive 与传输方式后，接下来看看 LLM 实际如何发现并调用 MCP 工具。

在 2025-11-25 修订版中，连接开始时会按以下顺序进行 handshake。截至 2026-10-08，TypeScript SDK 的 1.32.1 和 v2 系列的 2.3.1 在默认配置下也按这个顺序运行。

• Client → Server：发送 initialize 请求（传递支持的协议版本和 client capabilities）
• Server → Client：返回 initialize 响应（server capabilities + 可选的 instructions 字段）
• Client → Server：发送 notifications/initialized 通知
• Client → Server：发送 tools/list 请求 → 获取可用工具列表
• （之后）LLM 决定调用工具 → client 发送 tools/call → 接收结果

initialize 响应中的 instructions 字段，是 server 用文字说明工具该如何使用的位置。下面演示输出中的 instructions 一行就是这个值。

那么，tool 定义本身又是如何进入 LLM 视野的？MCP 的 tool 定义采用如下 JSON Schema 形式。

{
  "name": "get_weather",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  }
}

host 会把通过 tools/list 获取的列表转换成 Anthropic Messages API 的 tools 参数，或 OpenAI function calling 的 tools 参数，再随 LLM API 请求一同发送。以 Anthropic 为例，传入 tool 参数后，系统会自动添加 special system prompt，使模型理解工具调用方式。它的长度因模型而异。在 2026-10-08 查看的文档表格中，以 tool_choice: auto 为准，现行模型为 286～675 个 token。

当 LLM 判断应该调用工具时，响应中会包含 tool_use block（{"type": "tool_use", "name": ..., "input": ...}），并以 stop_reason 为 tool_use 结束。host 收到后，会向实际的 MCP server 发送 tools/call，再把返回结果装进下一条 user message 的 tool_result block 中发回 LLM。这个循环会持续进行，直到 stop_reason 从 tool_use 变成其他值（如 end_turn、max_tokens）。 我们通常所说的“智能体在工作”，实际上很接近这种调用、结果、调用的循环的连续运行。

画成图的话，模型与 MCP server 之间没有连线。模型只看到通过 tools 收到的定义，MCP server 接收的是 host 的请求，而不是模型的请求。连接两个协议的是中间的 host。

为了看看这个转换实际有多短，笔者把它跑了一遍。2026-10-08 使用 Node v24.16.0、@modelcontextprotocol/sdk 1.32.1、zod 4.6.5 运行。传输用的不是 stdio，而是在同一进程内连接 server 与 client 的 InMemoryTransport，也没有调用 LLM。tool_use block 是按照 Anthropic 文档中的形状手工构造的。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { z } from "zod";
 
// MCP 서버: 도구 하나와 instructions 를 둔다
const server = new McpServer(
  { name: "weather", version: "1.0.0" },
  { instructions: "Use get_weather for current conditions only." }
);
server.registerTool(
  "get_weather",
  { description: "Get current weather information for a location", inputSchema: { location: z.string() } },
  async ({ location }) => ({ content: [{ type: "text", text: `${location}: 15C, partly cloudy` }] })
);
 
// 호스트: 같은 프로세스 안에서 서버와 잇고, 클라이언트가 보내는 메서드 이름을 찍는다
const [clientT, serverT] = InMemoryTransport.createLinkedPair();
const send = clientT.send.bind(clientT);
clientT.send = (m) => { console.log("C->S", m.method, m.params?.protocolVersion ?? ""); return send(m); };
await server.connect(serverT);
const client = new Client({ name: "demo-host", version: "1.0.0" });
await client.connect(clientT);
console.log("instructions:", client.getInstructions());
 
// 1. tools/list 결과를 LLM API 의 tools 파라미터 모양으로 바꾼다
const { tools } = await client.listTools();
const anthropicTools = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.inputSchema }));
const openaiTools = tools.map((t) => ({ type: "function", name: t.name, description: t.description, parameters: t.inputSchema }));
console.log("anthropic:", JSON.stringify(anthropicTools[0]));
console.log("openai:", JSON.stringify(openaiTools[0]));
 
// 2. 모델이 이런 tool_use 블록을 돌려줬다고 가정한다. input 이 그대로 tools/call 의 arguments 가 된다
const toolUse = { type: "tool_use", id: "toolu_demo", name: "get_weather", input: { location: "Seoul" } };
const result = await client.callTool({ name: toolUse.name, arguments: toolUse.input });
console.log("tool_result:", JSON.stringify({ type: "tool_result", tool_use_id: toolUse.id, content: result.content }));
await client.close();

node post-demo.mjs 的输出如下。

C->S initialize 2025-11-25
C->S notifications/initialized 
instructions: Use get_weather for current conditions only.
C->S tools/list 
anthropic: {"name":"get_weather","description":"Get current weather information for a location","input_schema":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
openai: {"type":"function","name":"get_weather","description":"Get current weather information for a location","parameters":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
C->S tools/call 
tool_result: {"type":"tool_result","tool_use_id":"toolu_demo","content":[{"type":"text","text":"Seoul: 15C, partly cloudy"}]}

工具定义的转换只不过是改字段名。MCP 的 inputSchema 在 Anthropic 中变成 input_schema，在 OpenAI 中变成 parameters。从输出中还能看到 SDK 会在 schema 里加上 $schema。反方向同样简短。Anthropic 的 tool_use.input 是对象，所以直接成为 tools/call 的 arguments。结果一侧也一样，text block 形状相同，可以直接传过去；但图片或错误结果的形状不同，由 Anthropic SDK 的 MCP helper 另行转换。上面 OpenAI 一侧的形状是 Responses API 的格式。OpenAI 返回的调用中的 arguments 是 JSON 字符串，因此在转交之前需要先经过一次 JSON.parse。上面的代码只构造了 Anthropic 形状的 tool_use 块，所以这个 parse 步骤不会出现在输出中。

MCP 增加的四点

那么，MCP 给 function calling 增加了什么？以 2025-11-25 修订版为准，有四点。

• 动态发现：构建时并不知道工具列表，而是在运行时通过 tools/list 获取。server 可以通过 notifications/tools/list_changed 通知连接期间列表发生了变化
• Stateful session：用 initialize 建立连接，请求在其中往来。没有用于结束的 JSON-RPC 消息，关闭传输即告结束
• Tool 以外的 primitive：通过 capability negotiation 暴露 Resource、Prompt、Sampling、Roots、Elicitation。capability negotiation 是在 initialize 中双方互相告知所支持功能的阶段
• 双向性：server 可以通过 Sampling 反向请求 client 的 LLM 生成 completion（2026-07-28 修订版中已 deprecated）

2026-07-28 修订版之后

截至 2026-10-08，官方网站作为 latest 打开的是 2026-07-28 修订版，这份列表在其中变了一半。首先，由 initialize 与 notifications/initialized 构成的 handshake 以及协议层面的 session 消失了。取而代之的是，每个请求都在 _meta 中携带协议版本和 client capabilities。这个字段是 MCP 预留的位置，用于在消息本身的参数之外附加元数据。server 必须（MUST）实现 server/discover。这个 RPC 返回 server 支持的协议版本、capabilities 和 server 信息，client 可以在其他请求之前调用它，预先确认支持的版本和 capabilities。

原先由 server 先发出的请求，被一种名为 Multi Round-Trip Requests（MRTR）的模式取代。server 不再单独发出请求，而是返回一个表示还需要额外输入的中间结果（input_required），client 补上这些输入后重新发送原来的请求。

Sampling 和 Roots 与 Logging 一起被标为 deprecated。它们仍留在规范中并且可以工作，但新的实现不应采用，规范建议不要用 Sampling，而是直接对接 LLM provider 的 API。

不过，SDK 的默认行为仍是旧方式。TypeScript SDK 1.32.1 的最新版本常量是 2025-11-25，因此并不知道 2026-07-28 修订版；2.3.1 支持这一修订版，但版本协商的默认值是 legacy。上面输出的第一行 initialize 2025-11-25 就是其结果。

这样一来，四点中留下的是动态发现和 Tool 以外的 primitive（Resource、Prompt、Elicitation）。动态发现的形态也略有变化：列表变更通知只发给 opt-in 了 subscriptions/listen 流的 client。归根结底，MCP 与 function calling 分道扬镳之处，与其说在 session 或双向性，不如说在于在运行时交换工具列表与 context 的约定。

当 API 成为 MCP client

这份约定中有多少能到达模型，Anthropic 的 MCP connector（beta）给出了答案。这是 Messages API 直接连接远程 MCP server 的功能，而文档的 Limitations 写道，在 MCP 规范的功能中 "only tool calls are currently supported"，并写道 "Local STDIO servers cannot be connected directly"。同一份文档还说明，如果需要本地 server 或 MCP 的 prompt、resource，就用 MCP SDK 自行管理连接，同时使用 Anthropic SDK 的转换 helper。

也就是说，在 function calling 层消费 MCP 时，只剩下 Tool。Resource 和 Prompt 要有 host 把它们带到界面或 context 中才有意义。OpenAI 也在 function calling 指南中介绍了把 MCP server 的功能当作 built-in tool 使用的方式。OpenAI 的 MCP servers 指南只说明了如何列出和调用工具，没有写明是否支持 Resource 或 Prompt。

动态发现打开的攻击面

工具的 description 和工具调用的结果，会经由 host 进入模型的 context。所以无论 server 在那里写了什么，模型都会读到。两种代表性攻击都源于这一点。

• Tool Poisoning Attack（TPA）：Invariant Labs 于 2025 年 4 月命名并公开 PoC 的攻击。若把恶意指令隐藏在 MCP server 的工具 description 中，模型会读到这段用户看不见的文本，并可能在用户不知情的情况下照做。

• Rug Pull：Invariant Labs 在同一篇文章中描述的攻击，即在用户批准之后，server 修改工具定义。就像 Simon Willison 引用的 Elena Cross 的例子：第 1 天批准了一个看起来安全的工具，到第 7 天它已经被改成把 API key 发给攻击者；这是因为工具定义不是在安装时，而是在运行时从 server 获取。tool 规范建议（SHOULD）提供显示哪些工具暴露给模型的 UI，但并不要求对变化后的定义重新批准，因此重新批准由 host 负责。

总结

总而言之，MCP 并不是要取代 function calling，而是建立在它之上的标准。模型调用工具的方式仍然是 tools 参数和 tool_use 循环，两个协议之间由 host 负责翻译。在 2025-11-25 修订版中，MCP 增加的是动态发现、stateful session、Tool 以外的 primitive，以及从 server 发往 client 的调用。在 2026-07-28 修订版中 session 消失、Sampling 被标为 deprecated 之后，留下的是在运行时交换工具列表与 context 的约定。正因为有这份约定，污染工具定义或悄悄修改它们的攻击也从同一个地方产生。再接入一个 MCP server 时，建议不仅确认这个 server 能做什么，也确认定义变化时 host 是否会提醒你。

如果说 MCP 关乎该让智能体能做什么，那么该告诉它什么，就是 CLAUDE.md、AGENTS.md 这类上下文文件的问题。这些文件如何被智能体读取、其中的指令能被遵守到什么程度，在上下文文件中讨论。

如今，AI 工具（Claude、ChatGPT、Cursor、Gemini、Copilot）已经深度融入我们的工作。开发速度呈指数级提升，但坦率地说，我感觉服务的完成度并没有同步跟上。功能越多，随之增加的 bug 也越多，我们也越来越常听到“我不知道为什么会变成这样”。

开发越快，我们就越少逐行细看代码。正因如此，我认为我们更需要具备一种能够为 AI 指明正确方向的基本功。只有能发现 AI 生成代码中的问题，并重新引导它朝预期方向前进，才能守住交付质量。这些基本功可以包括从领域视角开发、抽象、TDD（Test-Driven Development，测试驱动开发）、善用库，以及建立性能优势等很多方面。

不过，每当我问前端同事以及其他 IT 岗位的同事“前端开发中最棘手的工作是什么？”时，听到最多的答案始终如一：“管理状态流。”

本文将梳理为什么状态流管理如此棘手，以及要想做好这件事，需要培养怎样的判断力与感觉。

什么是状态（State）

在正式展开之前，先从最基础的问题说起。我们所说的“状态”究竟是什么？

学习前端开发时，我常读 hoseung.me 的文章。其中将状态定义为“所有可能影响 UI 的数据”。点赞数、购物车列表、模态框是否打开、输入值、当前登录用户的信息、当前选中的标签页、搜索结果、是否正在加载——这些全都是状态。

React 官方文档给出了更形式化的定义。页面标题就是 “State: A Component's Memory”，展开来说，大致是指“组件在多次渲染之间保留（retain）数据，并在数据更新时触发 React 重新渲染的机制”。也就是说，这类数据不会随时间消失，会因某个事件而更新，并在更新时让 UI 重新绘制。还有一点需要指出：状态按组件实例彼此隔离。 即使页面上存在十个相同组件，它们也各自拥有独立状态。这个事实与后文“状态应该放在哪里”的讨论直接相关。

两种定义指向的是同一件事：“会影响渲染，并随时间变化的值”就是状态。不变的常量（constant）不是状态。构建时就固定下来的原始设计 token 不是状态，但由用户切换的深色模式是状态。（严格来说，值本身会根据深色/浅色主题这一状态完成 resolve，因此更准确的理解是，“主题选择”才是状态，token 则是映照该状态的镜子。）

这里还有一点需要明确：并非所有状态都存在于组件中。 有些状态存在 Cookie 中，有些存在 localStorage、sessionStorage 或 IndexedDB 中，还有些存在 URL 中。把服务端数据带到客户端并加以缓存，也会形成一种状态。浏览器自身维护的滚动位置和历史记录栈，在它们会决定应用行为时，也需要被当作状态处理。

为什么如此棘手

先简单想一想，处理状态为什么困难。创建需要的状态，把它传到需要的地方，再妥善处理更新与初始化，不就可以了吗？

把这个问题留在脑中，然后打开你正在开发的服务中的任意一个页面。

这个页面有多少个组件？即使是简单页面，也可能由少则几十、多则几百个组件组成一棵树。每个组件可能持有自己的状态，可能与兄弟组件共享状态，也可能从父组件接收状态。状态还会在页面之间迁移：有些状态刷新后必须保留，有些状态则应在关闭标签页时消失。

状态真正难以管理的原因就在这里：我们无法一眼看清大量状态分别在哪里声明、如何更新，又在何时消亡。 职责相似的组件越多，给状态命名以及追踪修改状态的代码就越困难。

于是，一张看不见的蛛网形成了。A 组件中的某次点击使 B 的数据失效，B 的失效又让 C 的 UI 关闭，C 关闭时表单输入随之消失。如果这种连锁关系没有在代码的任何地方明确表达，那么调试 bug 时，我们就只能在脑中重新画出这张蛛网。

那么，该如何整理这张蛛网？在我看来，第一步是意识到：“状态有不同的种类。”

并非所有状态都是同一种状态

Kent C. Dodds 将状态分为 Server Cache（服务端保存信息，客户端为便于快速访问而持有的副本）与 UI State（只存在于 UI 中，用于控制界面行为）。我们经常在把两者混为一谈时犯错。

TanStack Query 官方文档将 TanStack Query 定义为 Server State 库，用于管理服务端与客户端之间的异步工作；Redux、MobX、Zustand 等工具则被定义为 Client State 库。（它们虽然能够存储异步数据，但这样做效率不高。）

关键点很明确：Server State 与 Client State 是不同的问题。 Server State 是异步的，可能被其他用户修改，并会随时间变得 stale。Client State 是同步的、受我们控制，并会在刷新后消失。（准确地说，页面 unload 时，JavaScript 运行时会重新启动，heap 内存中的组件树及其状态会一并被回收。 因此再次 mount 时，会从 useState 的初始值重新开始。）如果试图用同一种工具管理两者，就必须亲手实现缓存失效、后台刷新、乐观更新等模式。

在此基础上，我会更进一步，把前端状态分为七个类别。需要提前说明的是，这七类并不能沿单一维度整齐划分。存储位置、来源、生命周期和职责彼此交织，因此一个状态可能同时属于多个类别。请不要把它看作一张完美的分类表，而应把它理解为决定如何管理状态时需要提出的一组问题。

• 局部状态（Local State）：只在一个组件或较小子树中使用的状态
• 全局状态（Global State）：需要由整个应用共享的状态
• 服务端状态（Server State）：以服务器为 Single Source of Truth、客户端副本仅作为缓存的状态
• 表单状态（Form State）：用户输入期间暂时存在的状态
• URL 状态（URL State）：位于地址栏中、可分享且刷新后仍保留的状态
• 外部状态（External State）：位于 React 外部的状态，如 Cookie、localStorage、sessionStorage 和 IndexedDB
• 状态守卫（State Guard）：根据状态组合阻止、允许或校验访问与操作的逻辑，而不是状态本身

除此之外，还有适合用状态机精细建模的工作流状态，以及基于 WebSocket 或 CRDT 的实时协作状态。

下面逐一说明为什么它们需要不同的工具，以及应以怎样的判断力来对待它们。

局部状态（Local State）

这是最简单的一类状态。它只在一个组件内使用，外部既不需要知道，也无权知道。例如模态框是否打开、切换按钮的 on/off、悬停状态、正在输入的搜索词。

function SearchBox() {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

这些大家应该已经很熟悉了。但局部状态真正棘手的地方，是“这个状态应该放在哪里”这一位置决策。

Kent C. Dodds 的 State Colocation一文指出：人们习惯于把状态“提升（lift up）”，却不擅长在代码发生变化后，重新把状态“就近放置（colocate）”。

当兄弟组件需要共享同一状态时，提升状态是我们很自然的做法。既然两个兄弟组件要读取同一份数据，就把状态提升到共同父组件，再通过 props 向下传递。

问题出在兄弟组件不再需要该状态时。我们通常不会把状态重新下移到子组件中。结果，父组件积累了大量实际上与自身无关的状态，每次父组件重新渲染时，整棵子树也会随之重新渲染。

因此，处理局部状态的第一条判断准则是：为了让代码更快、更简单，应让状态尽可能靠近使用它的代码。 如果某个状态只被一个组件的某个子组件使用，父组件就没有理由持有它。把它移到该子组件内部，父组件也会因此变得更轻。

全局状态（Global State）

全局状态是需要在应用任意位置访问的状态。登录信息、主题、语言、通知（toast）等都可能属于这一类。

局部状态与全局状态的区别，并不只是“存在于哪里”。二者对引用方式的承诺不同。局部状态向代码承诺的是“只在这个组件内部有意义”；全局状态则向整个代码库发布一项承诺：“应用中的任何位置，都可以用这个名字引用这个值。” 这项承诺成本高昂，正是全局状态的本质。

创建一个全局状态，实际上就是为整个应用增加一项隐式依赖。

服务端状态（Server State）

把 API 返回的数据塞进 Client State，亲自用 boolean 管理加载与错误，做着做着便会产生疑问：“为什么每次都在写同样的样板代码？”

TanStack 的主要维护者 Tanner Linsley 曾表示：“Client State 是同步且可预测的。Server State 是异步的，会被多个组件共享，必须谨慎处理缓存、后台刷新与错误状态。” 也就是说，Server State 与 Client State 本质上是不同的物种，不应使用同一种工具处理。

Server State 的棘手之处，不在于工具，而在于数据的本质。

客户端看到的数据属于服务端。客户端持有的只是某一时刻的快照。随着时间推移，这份数据会产生 staleness。它还是异步的，可能失败，并拥有 pending、error、success 等状态。

最重要的本质是：响应无法保证按照请求发出的顺序返回。 假设用户在搜索框中快速输入“react”。r → re → rea → reac → react 的请求会依次发出，但如果“react”的响应先到，随后“rea”的响应才到，页面最终显示的就会是“rea”的结果。要避免这类问题，每次都得手动编写 AbortController 或请求 ID 追踪逻辑，因此必须关注这种并发风险（race conditions）。

表单状态（Form State）

表单是一类微妙的状态。用户输入期间，它会剧烈变化；一旦提交，通常就会消失。它不会与其他地方共享，也（大多）没有需要保存的去处。

问题在于，这种“剧烈变化”代价不菲。如果每次按键都触发 React 重新渲染，那么在大型表单中，输入延迟会明显到可以被用户察觉。而且表单不只是“持有值”。校验、dirty check、提交状态、错误信息、多步骤流程等多种状态，会同时在一个表单内部运转。

像三步支付流程这样的多步骤表单，通常会被期待“即使中途刷新，进度状态也能保留”。如果只用 useState 保存表单值，刷新后所有内容都会丢失。更自然的做法是保存在 sessionStorage（标签页级临时存储）或 URL（可分享的步骤）中。也就是说，表单状态会根据生命周期要求，与外部状态或 URL 状态结合。

URL 状态（URL State）

假设我们正在搜索页面中按分类、排序方式和页码进行筛选。如果用 useState 保存这些状态，会同时出现三个问题。

• 刷新后，所有筛选条件都会重置
• 即使把 URL 分享给朋友，对方看到的仍是没有应用筛选条件的页面
• 点击后退，也无法回到之前的筛选条件

解决这些问题时，把状态放进 URL 是很自然的选择。 URL 本身就是一种无需额外成本的持久存储，天然支持刷新、分享和历史记录。

/products?category=shoes&sort=price-desc&page=2

这一行 URL 中已经包含了“鞋类商品按价格降序排列后的第 2 页”这一完整状态，无需再用 useState 单独保存。

那么，什么时候适合用 URL 管理状态？URL 是公开接口。 密码、认证 token、用户不愿让他人看到的临时备忘等信息，都不应放入 URL。此外，如果把变化过于频繁的值（每次输入都会变化的搜索词）直接写进 URL，历史记录栈就会被垃圾填满。这种情况下，应在 debounce 后再同步，仅在合适时使用 push，而对不应新增历史记录的更新使用 replace。

URL 中的值始终是字符串。数字、boolean、数组、对象都必须经过序列化与反序列化。并且 URL 必须遵循百分号编码（percent-encoding）规则，&、=、韩文、空格等字符都需要特殊处理。如果每次都手写这些逻辑，很快就会成为 bug 的温床。

const params = new URLSearchParams(location.search);
const page = Number(params.get("page") ?? "1");
params.set("page", String(page + 1));
navigate(`?${params.toString()}`);
 
const [page, setPage] = useQueryState("page", parseAsInteger.withDefault(1));

nuqs 之类的库通过解析器（parser）概念解决了这两个问题。parseAsInteger、parseAsBoolean、parseAsJson 等解析器统一负责序列化、反序列化与类型。它支持 Next.js（App/Pages Router）、React Router v6/v7、TanStack Router、Remix 等大多数环境。

那么，可以把任意多的状态都塞进 URL 吗？除了序列化和类型问题之外，还有最后一个约束需要注意。RFC 7230 并未规定精确上限，但建议“服务器至少应支持 8,000 个 octet（在网络或数据通信中，用于明确指代由 8 Bit 组成的 1 Byte 的单位）”。不同浏览器的限制也各不相同。现代浏览器大多允许 8KB 到数万字符，但搜索引擎、社交媒体的 OG/分享处理，以及部分网关，可能在接近 2KB 时就截断内容。因此，不要无限制地往 URL 中塞数据。只保留可分享的核心筛选条件，其余内容交给 sessionStorage 或服务端存储会更安全。

外部状态（External State）

React 只知道自身内部的状态，但我们的应用也在不断与 React 之外的世界交互。存在于那个世界中的状态，不受 React 生命周期约束，会独立存续，也会发生变化。这里所说的外部状态包括 Cookie、localStorage、sessionStorage、IndexedDB。

应该如何选择存储方式？我通常从生命周期、容量、同步性、安全性四个维度思考。

对于认证 token，OWASP 的建议首选 HttpOnly + Secure Cookie。localStorage 可由 JavaScript 访问，因此一旦暴露于 XSS，token 就会被直接窃取。部分安全指南建议采用混合模式：access token 放在内存中，refresh token 放在 HttpOnly Cookie 中。需要持久保存、不敏感且不经常变化的数据，可以放在 localStorage；应随标签页关闭而消失的数据，则可以使用 sessionStorage。离线缓存、大体量数据和文件通常使用 IndexedDB。

Cookie 与 Web Storage（local/session）只能存储字符串。因此，要存入对象就必须经过 JSON.stringify/JSON.parse。但 JSON 存在局限。

JSON.stringify({ when: new Date() });
// → { "when": "2026-05-19T..." } — Date becomes a string
 
JSON.stringify({ map: new Map([["a", 1]]) });
// → { "map": {} } — Map is lost entirely
 
JSON.stringify({ value: undefined });
// → "{}" — the undefined field is omitted

Date 在 JSON 往返转换后会变成字符串，Map、Set 和 undefined 则可能丢失数据。默认情况下，BigInt 会让 JSON.stringify 抛出 TypeError，导致序列化直接失败。把对象存入外部存储时，必须始终留意哪些类型可能消失、改变或导致序列化失败，必要时应提供序列化适配器。

外部状态真正的难点是：React 无法自动检测它的变化。 即使向 localStorage 写入值，React 组件也不会重新渲染。解决这一问题通常有三种模式。

• 用自定义 hook（useLocalStorage）再封装一层，把外部状态同步为 React state。 这种方式轻量，但如果自行实现，就必须处理多标签页、SSR、tearing 等各种边界情况。
• 使用 React 18 引入的 useSyncExternalStore hook，“与 React 外部状态同步”。 借此可以确保并发渲染中不会发生 tearing。 它是连接 localStorage、浏览器 API 与外部 store 的标准工具。
• Zustand 的 persist middleware、Jotai 的 atomWithStorage 等状态库，把外部存储集成作为一等能力提供，因此也可以直接使用已有的库。

这里再补充一条判断准则：一旦把外部状态带入 React，同步责任就落到了我们身上。 如果另一个标签页更新了它呢？如果服务端修改了 Cookie 呢？如果用户通过浏览器开发者工具直接修改 localStorage 呢？这些情况往往会成为最严重的 bug 温床。

状态守卫（State Guard）

最后一类稍有不同。它不是状态本身，而是根据状态组合来阻止、允许或校验某个流程的逻辑。

最常见的例子是认证守卫（Auth Guard）。

function ProtectedRoute({ children }) {
  const { isAuthenticated, isLoading } = useAuth();
 
  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return children;
}

这里，isAuthenticated 状态控制了路由流程，这就是守卫逻辑。守卫有很多种，包括认证守卫（是否已认证）、权限守卫（特定角色、权限）、流程守卫（进入分支）、校验守卫（启用步骤）等。

守卫逻辑很容易堆积在一个地方。常见的情况是，一个组件里同时写满了“未登录就去登录页、无权限就去 403、购物车为空就去商品页、用户被封禁就显示封禁提示”。守卫越臃肿，就越难调试究竟是哪个条件在哪里阻断了流程。

好的守卫只检查一件事。 组合则通过 Composition 完成。

<AuthGuard>
  <RoleGuard role="admin">
    <FlowGuard require={["cartHasItems"]}>
      <CheckoutPage />
    </FlowGuard>
  </RoleGuard>
</AuthGuard>

每个守卫只作出一个决定，组合关系由树形结构负责。添加新守卫时，无需修改现有守卫。

处理守卫时，比“是否拦截”更需要仔细考虑的是：拦截后把用户送到哪里，以及后续如何处理。 只会拦截、没有 fallback 的守卫，最终只会留下白屏或无限 spinner。

最常见的 bug 是：“在守卫的异步检查完成前，受保护内容会短暂闪现。” 认证 token 校验、权限查询大多是异步操作，在此期间，isAuthenticated 会有一小段时间处于 undefined 或 false。如果不显式处理加载状态，受保护页面就可能在这个间隙暴露，或用户可能被错误重定向到登录页。

// Ignores loading and handles only missing data => incorrect
if (!user) return <Navigate to="/login" />;
 
// Treat loading as a first-class state (early return) => correct
if (isLoading) return <Spinner />;
if (!user) return <Navigate to="/login" replace />;
return children;

编写权限守卫时，常见的模型有两种。

• RBAC（Role-Based Access Control）：按角色授予权限，例如“admin 可以查看所有用户信息”。它简单、快速，但随着角色不断细分，角色数量会爆炸式增长
• ABAC（Attribute-Based Access Control）：根据属性组合决定权限，例如“用户是该帖作者、与作者属于同一团队，或用户是 admin”。它表达能力强，但实现和调试更困难

如 TanStack Router 的 RBAC 指南所示，推荐在路由层的 beforeLoad 中设置守卫。关键在于：权限检查不应散落在代码各处，而应能表达为数据（角色/权限列表）。这样一来，权限策略调整只需变更数据。

总结

总结一下。状态管理之所以困难，不是因为库难用，而是因为我们经常忘记：状态有不同种类，也容易忽略不同种类需要不同的工具与思考方式。

局部状态应尽量就近放置；面对全局状态，要再确认一次它是否真的需要全局；Server State 应作为缓存处理；表单应与领域分离；URL 应更积极地使用；外部存储需要明确意识到自身责任；守卫则应拆薄后进行组合。这就是处理七类状态的基本功。

而凌驾于这些具体做法之上的判断力，最终可以浓缩为四个问题。

• 这份数据的 Single Source of Truth 在哪里？
• 这是可以计算得到的值，还是确实必须存储的值？
• 这些状态的组合中，是否存在不可能的组合？
• 这个状态真的应该位于这里吗？

每次开发新页面、审查 PR、接收 AI 生成的代码时，都把这些问题问上一遍。我相信，这是培养判断力与感觉最可靠的方式。

正如开头所说，AI 会长久地留在我们身边。我们逐行查看代码的时间会越来越少。但越是如此，能够回答“这个状态应该放在哪里？”这类小问题的能力就越有价值。让 AI“在这里再加一个 useState”很容易；但那一行代码会在应用的蛛网上增添一根怎样的丝线，只有阅读代码的人凭借自己的判断力才能看清。

不存在唯一正确答案。但至少，“不知道状态是什么就创建状态”与“意识到状态的种类和位置后再创建状态”之间，有着明确的区别。希望读者下次写下一行 useState 之前，也能暂时停一下，问问自己：“它属于哪一类状态？”

本文写给这样的前端开发者：税额计算、申报状态判断这类业务规则散落在组件、Hook 和 utils 里，每改一条规则都要四处寻找并修改好几个文件。读完之后，你会知道如何把这些规则移到不依赖 React 的纯函数中，以及判断这种拆分应在何处停止的标准。

文中的例子全部使用综合所得税的计算，这是笔者一直关注的领域。

前端的领域逻辑应该放在哪里？

回答之前，先统一一个术语。本文所说的领域模型，是把业务概念和作用于其上的规则放在一起的东西。它不同于像 API 响应类型那样、只定义数据以什么形状传递的数据模型。组件一旦直接依赖响应结构，后端 schema 每次变化都会让整个前端跟着动摇，原因也正是这个区别。领域、领域模型、领域对象、领域对象模型这四个术语有什么不同，另外整理在领域术语中。

热衷于软件设计的 Khalil Stemmler 起初主张“业务逻辑不属于前端”，后来又调整了立场，表示“后端在架构层面所做的几乎一切，前端也能做，而且应该做。”

我也认同这一观点。当然，前端不应成为业务逻辑的唯一事实来源（Single Source of Truth），那是后端的职责。但前端确实存在前端独有的领域逻辑。

设想这样一种情况：“需要根据用户输入的信息，实时展示预计退税额。”如果这类计算逻辑只存在于后端，用户每修改一个收入金额的字符，就要调用一次 API。用户界面会在网络往返期间停顿；如果用户输入很快，还会产生爆炸式增长的无用请求。即使加入防抖，数百毫秒的延迟也足以破坏“实时预览”的体验。最终，需要即时反馈的计算只能由前端自行完成，于是也就出现了只能在前端执行的逻辑。

领域逻辑混入组件的情况

以综合所得税预览页面为例。用户输入收入信息后，页面会实时展示预计税额。下面是一段常见的代码，其中领域逻辑和用户界面逻辑混在了一起。

function TaxPreviewPage() {
  const [총수입, set총수입] = useState(0);
  const [경비율, set경비율] = useState(0.641); 
  const [인적공제대상인원, set인적공제대상인원] = useState(1); 
 
  const 종합소득금액 = 총수입 - 총수입 * 경비율;
 
  const 소득공제합계 = 인적공제대상인원 * 1_500_000;
  const 과세표준 = Math.max(0, 종합소득금액 - 소득공제합계);
 
  let calculatedTax = 0;
  if (과세표준 <= 14_000_000) {
    calculatedTax = 과세표준 * 0.06;
  } else if (과세표준 <= 50_000_000) {
    calculatedTax = 과세표준 * 0.15 - 1_260_000;
  } else if (과세표준 <= 88_000_000) {
    calculatedTax = 과세표준 * 0.24 - 5_760_000;
  } else if (과세표준 <= 150_000_000) {
    calculatedTax = 과세표준 * 0.35 - 15_440_000;
  } else {
    calculatedTax = 과세표준 * 0.38 - 19_940_000;
  }
 
  const 기납부세액 = 총수입 * 0.033;
  const refundOrPayment = 기납부세액 - calculatedTax;
 
  return <div>...</div>;
}

看出这段代码的问题了吗？“每人 150 万韩元的人身扣除”“8 级累进税率”“3.3% 预扣税”等由税法规定的业务规则被直接写死在 React 组件中。税法每年都会修订，如果这些规则散落在各个组件里，修订时就必须四处寻找需要修改的位置。如果质量保证团队还有端到端测试场景需要维护，测试成本也不会低。

最终，视图逻辑与业务逻辑变得难以区分，代码也会被大量条件语句和自定义钩子缠成一团。

分离领域逻辑

借用 Alex Bespoyasov 的 Clean Architecture 方法中的一项核心原则：把领域逻辑分离为不依赖框架的纯函数。

领域是区分一个应用与另一个应用的核心。可以把领域理解为，即使从 React 迁移到 Angular，也不会发生变化的部分。

The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular.

来重构上面的税额计算示例。

首先定义领域类型和规则，将相关信息聚合起来。

export interface Income {
  grossAmount: number;
  expenseRate: number;
}
 
export interface Deductions {
  personalCount: number;
  pensionPaid: number;
  additionalDeductions: number;
}
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
const TAX_BRACKETS = [
  { limit: 14_000_000, rate: 0.06, progressiveDeduction: 0 },
  /** ...구간들... **/
] as const;

然后，将领域逻辑分离为纯函数。

把前面计算收入、扣除、计税依据、税额、退税额等逻辑分离到 computeFullTax 函数中，再把每个阶段拆成更小的纯函数。结果类型可以通过 ReturnType<typeof computeFullTax> 推断，无需单独声明接口。

之后，组件只需“使用”领域逻辑。

import { computeFullTax } from "../domain/tax";
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({
    grossAmount: 0,
    expenseRate: 0.641,
  });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1,
    pensionPaid: 0,
    additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

发生了哪些变化？

• 8 级累进税率表（TAX_BRACKETS）集中在一处，税法修订时只需修改 domain/tax.ts
• 计算流水线聚合在 computeFullTax 这一个函数中，整体流程一目了然。（为了让示例保持简单，这里将它合并成了一个函数；在实际项目中，更适合按收入计算、扣除计算、税额计算等目的进一步细分。）
• 组件只专注于“如何展示”。即使税率变化，也无需修改组件
• 即使从 React 迁移到其他框架，domain/tax.ts 也无需变化

分离领域逻辑后，测试会变得出奇简单。在税务领域，计算是否准确直接关系到用户的钱，所以这一点尤其重要。

包含税务计算逻辑的纯函数不需要 React Testing Library，也不需要 render 或 screen.getByText。传入输入、检查输出即可。“1,400 万韩元及以下适用 6% 税率”“计税依据为 0 韩元时税额也为 0 韩元”“自由职业者收入 3,000 万韩元时的退税额”等用例，都可以用一行 it 来表达。领域单元测试会自然地帮助确定组件的拆分边界，测试代码本身也能充当文档。

贫血领域模型（Anemic Domain Model）

上一节分离了计算逻辑。但领域逻辑除了计算，还包括状态转换规则和权限判断。例如：“现在可以修改这份申报单吗？”“可以提交吗？”“可以切换申请方式吗？”在分离这些规则时，很容易落入一个陷阱，也就是 Martin Fowler 命名的贫血领域模型（Anemic Domain Model）。

贫血领域模型是指：类型虽然用领域语言定义得很好，但作用于类型之上的规则却散落到了领域之外。以报税申报（Filing）领域为例，类型本身很整洁。

// types/filing.ts
export interface TaxFiling {
  id: string;
  status: "draft" | "submitted" | "reviewing" | "completed" | "amended";
  taxYear: number;
  filingType: "regular" | "late" | "amendment";
  determinedTax: number;
}

但针对这个类型的判断和转换规则，却写死在其他地方。

// utils/filingHelpers.ts
export function canAmendFiling(filing: TaxFiling) {
  return filing.status === "completed" && filing.filingType !== "amendment";
}
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 같은 도메인 규칙을 컴포넌트 안에 다시 작성한다
  const canEdit = filing.status === "draft" || filing.status === "reviewing";
  // ...
}
 
// hooks/useSubmitFiling.ts
export function handleSubmitFiling(filing: TaxFiling) {
  if (filing.status !== "draft") return;
  // ...
}

同一条领域规则分别以不同形式存在于工具函数、组件和钩子这三个地方。此时，如果收到“申请条件将发生变化”的需求，就必须四处寻找要修改的位置；任何一个被遗漏的地方，都会在网站的某处作出错误判断。Fowler 批评这类代码，称其“与只披了一层面向对象外衣的过程式代码别无二致”。

解决办法与上一节处理计算逻辑的方法相同：把规则放在类型旁边。

export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus =
  | "draft"
  | "submitted"
  | "reviewing"
  | "completed"
  | "amended";
 
export type FilingType = "regular" | "late" | "amendment";
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === "draft";
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === "draft" && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === "completed" && filing.filingType !== "amendment";
}

现在，申报相关规则都在 domain/filing.ts 中统一管理。任何组件只需调用 canAmend(filing)；规则发生变化时，也只需修改这一个文件。关键在于，应该把类型及其上的规则视为一个整体。如果只把类型放进领域文件夹，却把规则抽到工具函数中，这种局部分离即使外表整洁，仍然处于贫血状态。

API 响应与领域模型之间的转换层

在实际工作中，还要考虑另一件事：后端 API 的响应结构不一定总与前端领域模型一致。如果是与国家机关对接的税务服务，就更是如此。韩国国税厅 Hometax 的对接数据充斥着缩写和代码值，几乎不可能以与前端领域模型相同的形式返回。

此时就需要转换层（Mapper）。不要让 API 响应类型原封不动地一路流入组件，而应先将其整理成领域类型，再交给组件使用。一个纯函数就足够了。

import type { Income } from "../domain/tax";
 
interface HometaxIncomeResponse {
  총수입금액: number;
  경비율: number;
  소득유형코드: string;
  // ... 나머지 약어 필드들
}
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    총수입_금액: response.총수입금액,
    경비_비율: response.경비율,
  };
}

这样一来，就能在一个地方把 API 响应中的 총수입금액、경비율 等缩写，以及基于代码值的分类，转换为适合前端领域的形式。像收入类型代码这样需要展开为枚举的值，可以在转换器中放一张小型查找表。即使 Hometax API 的字段名发生变化，也只需修改一个转换器。

工具函数与领域逻辑

分离领域逻辑时，必然会遇到一个问题：“这不就是工具函数吗？”

来看下面两个函数。

function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find((bracket) => taxableBase <= bracket.limit);
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrency 是把数字转换成字符串的纯表现层逻辑（Presentation）。加上“韩元”单位和千位分隔符并不是业务规则，而是如何把内容展示给用户的问题。相反，calculateTax 包含“应用 8 级累进税率”这一基于税法的业务规则。即使没有用户界面，这条领域规则也必须同样适用。

我在实际工作中使用的判断标准是：

如果这段逻辑消失，受损的是业务，还是只有页面？

如果业务受损，它就是领域逻辑；如果只有页面受损，它就是表现层逻辑。仅凭这个问题，就能划清大多数边界。

但现实并没有这么清晰。最棘手的是，有些逻辑看起来像领域逻辑，其实却是表现层逻辑。

来看下面的代码。因为它以 FilingStatus 这一领域概念作为参数，所以被归类为领域逻辑。但它真的是领域逻辑吗？

// domain/filing.ts
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: "gray",
    submitted: "blue",
    reviewing: "yellow",
    completed: "green",
    amended: "purple",
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: "작성 중",
    submitted: "제출 완료",
    reviewing: "검토 중",
    completed: "신고 완료",
    amended: "경정청구",
  };
  return labels[status];
}

getStatusBadgeColor 和 getStatusDisplayText 虽然使用了 FilingStatus 这一领域概念，但它们做的事情是页面呈现。徽章颜色变化并不会对业务造成任何影响。把这类函数放进 domain/filing.ts，会让领域模块越来越臃肿，真正的领域逻辑和表现层逻辑也会混在一起。

分离领域模型与 ViewModel

有一种实用的方法可以解决这个问题：在同一个领域文件夹中，把 ViewModel 分离到单独的文件里。与 .ui.ts 相比，采用 .viewModel.ts 这一命名能自然地与 MVVM 模式中的 ViewModel 概念衔接，因为“把领域数据转换成适合页面呈现的形式”这一职责能够直接从名称中体现出来。

domains/
└── filing/
    ├── filing.ts              # 순수 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

把前面看到的 getStatusBadgeColor、getStatusDisplayText 原样移到 filing.viewModel.ts。此外，像 getFilingTypeLabel(type: FilingType): string 这样把申报类型转换成韩文标签的逻辑，也集中放在这里。filing.ts 只负责业务规则，filing.viewModel.ts 只负责页面呈现。

关键在于依赖方向。filing.viewModel.ts 会导入 filing.ts，但 filing.ts 绝不能导入 filing.viewModel.ts。领域不了解表现层，而表现层了解领域。可以把它看作 Robert C. Martin 所说的依赖规则（Dependency Rule）的缩小版。

我认为共同变化的文件应该放在同一目录，因此把它们放在了同一个文件夹。给 FilingStatus 类型添加新值（例如 'rejected'）时，filing.ts 和 filing.viewModel.ts 都需要修改。由于位于同一个文件夹，修改范围一目了然。

边界与内聚

与分离领域逻辑同样重要的是：边界应该画在哪里。下面整理几种我在实际工作中经常遇到的边界判断问题。

前端处理的数据大致来自四种来源。

• 服务端数据：通过 API 响应获得的数据
• 派生数据：由服务端数据计算得到的数据
• 用户界面状态：用于控制页面的状态，以及用户交互
• 用户输入：正在表单中输入的数据

如果把这四类数据混进同一个类型，领域模型就会受到污染。

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

这个类型把领域概念、用户界面状态和临时数据都塞进了同一个篮子。每次 activeStep 变化，就等于更新了一次申报领域。（表单步骤变化并不是业务事件。）

改进方法是按照边界拆分类型。领域模型只包含 id、status、determinedTax 等业务概念；用户界面状态（FilingFormViewState）只包含 isExpanded、activeStep 等页面控制信息；表单状态（DeductionEditForm）只保存正在输入的临时数据。

这样一来，每种类型都只有一个变化原因。领域类型只在税法变化时修改，用户界面状态只在页面设计变化时修改，表单状态只在输入体验变化时修改。

把共同变化的内容放在一起

Eric Evans 的 DDD 中有一个聚合（Aggregate）概念，指的是“把一组相关对象作为一个单元来处理”。前端无需照搬这一概念，但其中的核心原则值得借鉴：把共同变化的数据和规则放在一起。

以税务服务为例，Income（收入）和 ExpenseRate（费用率）总是共同变化。收入类型变化时，适用的费用率也会变化，综合所得金额的计算也会受到影响。因此，应把这些内容聚合到同一个文件 domain/tax.ts 中。

相反，TaxFiling（申报单）可以独立于税额计算而变化。即使申报单的状态转换规则发生变化，税率计算逻辑也不会受到影响。因此，把它分离到 domain/filing.ts 才是合适的做法。

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

类与函数式风格

读到这里，可能会产生一个根本问题：前面的示例都是 interface + 纯函数的组合，如果用类来表达领域，内聚不是会更自然吗？

确实如此。使用类来表达领域，会把数据与行为封装在同一个对象中，因此内聚性能够直接体现在代码结构里。

class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === "draft";
  }
 
  canAmend(): boolean {
    return this.status === "completed" && this.filingType !== "amendment";
  }
 
  canSubmit(): boolean {
    return this.status === "draft" && this.determinedTax >= 0;
  }
}
 
const filing = new TaxFilingModel(
  "F-001",
  "completed",
  2025,
  "regular",
  547200,
);
 
filing.canAmend();

使用类时，行为归属于数据，而且调用处的主语非常明确。filing.canAmend() 读起来像自然语言一样直观，主语（filing）和动词（canAmend）清楚地结合在一起。就像写下 jihoon.eat('감자탕')，马上就能读出“Jihoon 吃脊骨土豆汤”。

而函数式风格是这样的。

canAmend(filing);
eat("jihoon", "감자탕");

在函数式风格中，数据存在于函数之外。上面第一段代码接收 filing 数据作为参数并执行某种行为；eat 函数则接收 jihoon 和 감자탕 两项数据作为参数来执行行为。

这样一来，主语和动词的结合会变得松散。只有打开文件或查看类型签名，才能知道 canAmend 函数与 TaxFiling 有关。如果同一文件中混杂着 canAmend(filing)、canEdit(filing)、calculateTax(taxableBase) 等函数，就可能很难一眼看出每个函数分别属于哪个领域。

那么，应该使用类吗？

坦率地说，答案是“视情况而定”。但根据我的经验，在 React + TypeScript 环境中，类并非万能，这背后有一些现实原因。

与 React 状态管理之间的摩擦

React 的状态管理与普通对象（Plain Object）配合得最自然。useState 和 useReducer 在技术上可以保存任何值，Redux DevTools 本身也不会移除类实例的原型。但如果 Redux/Zustand 持久化中间件以 JSON 保存并恢复状态，类实例就会在 JSON.stringify → JSON.parse 循环中丢失方法和原型，退化为普通对象。从 React Server Component 向 Client Component 传递 props 的边界则有另一种限制：它只接受受支持的可序列化（serializable）值，因此任意类实例从一开始就无法通过该边界。

来看下面的代码。

const [filing, setFiling] = useState(
  new TaxFilingModel("F-001", "draft", 2025, "regular", 0),
);

仅仅更新 React 状态并不会让 filing 失去 TaxFilingModel 实例的身份。但如果 Redux/Zustand 持久化以 JSON 保存并恢复它，恢复后的值可能变成没有方法的普通对象，此时无意间调用 filing.canAmend() 就可能触发运行时错误。从 React Server Component 传递到 Client Component 时，失败会更早发生，因为类实例不是受支持的可序列化 props 值。

难以保证不可变性

React 基于引用相等性（referential equality）检测状态变化。如果类实例的方法执行 this.items.push(...) 之类的内部修改，引用保持不变，React 就不会触发重新渲染。因此，最终只能让 addDeduction(item) 像 return new DeductionList([...this.items, item]) 一样，每次都返回一个新实例。这样一来，类的优势——“封装后的状态变更”——也就失去了意义，代码与函数式更新并没有太大区别。

在函数式风格中获得内聚的策略

那么，在函数式风格中，如何改善 eat('jihoon', '감자탕') 这种内聚松散的问题？下面介绍三种我认为有效的方法。

通过模块命名空间实现内聚

这是最直观的方法。把文件（模块）本身按领域组织，并在导入时使用命名空间。直接使用前面定义的 domain/filing.ts 即可。