[Windows/Linux] TypeScript build error: missing 'thinking.budget' and compat fields in catalog.ts

[hoofungson]

环境

• 操作系统：Windows 11 / Linux
• Node.js：v24.20.0
• pnpm：最新版

问题描述

执行 pnpm run build 时，TypeScript 编译报错：
packages/llm/llm-pi-ai/src/catalog.ts:143:7 - error TS2741:
Property '"thinking.budget"' is missing in type ...

packages/llm/llm-pi-ai/src/catalog.ts:242:12 - error TS1360:
Property 'thinkingTokenBudgetField' is missing ...

packages/llm/llm-pi-ai/src/catalog.ts:267:12 - error TS1360:
Property 'allowedFallbackModels' is missing ...

原因分析

问题源于 pnpm-lock.yaml 被重新生成时，拉取到了更新版本的 AI SDK 依赖。新版类型定义要求必须包含上述三个字段，而当前代码中缺失了这些字段。

复现步骤

1. 克隆项目
2. 删除 pnpm-lock.yaml
3. 执行 pnpm install
4. 执行 pnpm run build

修复建议

在 packages/llm/llm-pi-ai/src/catalog.ts 中补充以下三个字段：

1. 第 143 行附近：添加 'thinking.budget': true
2. 第 242 行附近：添加 thinkingTokenBudgetField: 'offer'
3. 第 267 行附近：添加 allowedFallbackModels: 'offer'

[argszero]

你的诊断方向需要修正——这三个 TS 错误不是「catalog.ts 缺字段」要补, 而是 deliberate 的 drift gate 在报警, 报错位置 catalog.ts:143/242/267 恰恰是设计上要「在新版本 AI SDK 引入新字段时故意编译失败、逼维护者分类」的地方。

这三个报错到底是什么

packages/llm/llm-pi-ai/src/catalog.ts 有三处 satisfies Record<keyof X, ...> 的编译期漂移门（drift gate）:

• :143 CHAT_TEMPLATE_VAR_GATE: Record<PiAiChatTemplateVar, true> —— 枚举 pi-ai 所有 chat-template 占位符。
• :242 OpenAICompletionsCompat gate —— as const satisfies Record<keyof OpenAICompletionsCompat, CompatDisposition>。
• :267 AnthropicMessagesCompat gate —— 同构。

PiAiChatTemplateVar / OpenAICompletionsCompat / AnthropicMessagesCompat 这些类型来自 @earendil-works/pi-ai（catalog.ts:15-16/18/26-30 导入）。当你的 pnpm install（重新生成 lockfile）拉到更新的 pi-ai 后, pi-ai 给这些类型新增了成员:

• OpenAICompletionsCompat 新增 thinkingTokenBudgetField
• AnthropicMessagesCompat 新增 allowedFallbackModels
• ChatTemplateKwargValue 的 $var 判别新增了 thinking.budget

于是 satisfies Record<keyof X, CompatDisposition> 就抛 TS2741/TS1360（"Property X is missing"）——这是门在说「pi-ai 多了新字段, 你得在门里显式分类 (offer/withhold)」, 不是「你的代码缺这几个字段, 补上」。

为什么不是补字段

如果是「补字段」, 你会误把 thinkingTokenBudgetField 当 catalog.ts 自己的属性加进去——但它属于 pi-ai 的 compat 类型, 不该出现在 dsh 的 catalog 结构里。正确做法是在门里对新字段给 offer/withhold 分类。看既有先例（catalog.ts 已分类的字段）:

:223  maxTokensField: 'offer',
:228  thinkingFormat: 'offer',

这些也是 pi-ai 的 compat 字段, dsh 用 satisfies 门确保 pi-ai 每加一个, dsh 都显式决定「暴露还是不暴露」。thinkingTokenBudgetField/allowedFallbackModels 同理。

正确的修法（参考）

在新 pi-ai 下, 给三个门各补一个「分类」键即可（具体值取决于 dsh 想不想 profile 暴露这些能力）:

@@ packages/llm/llm-pi-ai/src/catalog.ts @@
 const CHAT_TEMPLATE_VAR_GATE: Record<PiAiChatTemplateVar, true> = {
   'thinking.enabled': true,
   'thinking.effort': true,
+  'thinking.budget': true,   // 若 dsh 允许 profile 配置 thinking budget; 否则删这行但需另想办法
 }
 // OpenAICompletionsCompat gate:
   maxTokensField: 'offer',
   thinkingFormat: 'offer',
+  thinkingTokenBudgetField: 'withhold',   // 或 'offer', 视 profile 是否暴露
 // AnthropicMessagesCompat gate:
   // ...
+  allowedFallbackModels: 'withhold',

⚠️ 注意分类语义: CHAT_TEMPLATE_VAR_GATE 是 Record<PiAiChatTemplateVar, true>（true 表示「允许 profile 用这个占位符」），不是 CompatDisposition。thinking.budget 若你不想让 profile 用, 把这个占位符从 pi-ai 的 template 路径屏蔽掉, 得看 PiAiChatTemplateVar 是怎么产生的——这处门是 Record<X, true>, 意味着每枚举一个 pi-ai 占位符都必须显式列出。如果你用的 pi-ai 版本并不严格要求所有占位符都出现在门里, 那 0.84.2 不会报这个错——你报错说明拉到的 pi-ai 比 0.84.2 新。

真正的根因（重要）

CATALOG 的兼容门设计初衷: pi-ai 每加一个新 compat 字段/模板占位符, dsh 的 build 就该 fail, 逼维护者决定 offer/withhold。你 relock 拉到新 pi-ai, 触发了这个刻意设计。所以:

1. 不是 bug, 是设计上的「漂移哨兵」。
2. 修法不是补字段, 是在三个门里分类新成员。
3. 若你用的是 ^0.84.2（catalog.ts package.json:44）, 现在 lockfile 是 0.84.2——你重建 lock 会解析到 ^0.84.2 范围内最新的一个（可能是 0.84.3+ 或 0.85.x）, 它才加了这些字段。锁回到 0.84.2 也能避开, 但这会掩盖漂移, 不建议——正确做法是让维护者分类。

建议

• 这本质是「pi-ai 上游加了新能力, dsh 的 drift gate 需要一次分类」, 由 dsh-llm-pi-ai 维护者处理。
• 你可以先确认拉到的 pi-ai 版本（pnpm why @earendil-works/pi-ai 或 node_modules 里的 version）——如果确实 ≥0.84.3, 报错是预期哨兵行为。
• 如果我只是看错线号、或你的 pi-ai 里根本没有这些字段, 请贴 catalog.ts 当前 3 个门附近的实际内容, 我再精确对齐——但以 satisfies Record<keyof X, CompatDisposition> 的语义, TS2741/TS1360 的「is missing」几乎必然是门在报「新成员未分类」。

关联家族: 这与我在别处跟踪的 pi-ai 兼容性系列同源（dsh-llm-pi-ai 的 supportsDeveloperRole / openRouterRouting 等 compat 分类门, 以及 pi-ai 版本演进导致的 drift push）。这类门是「类型层安全网」, 不是缺陷。

[Saidoua]

This one is worth re-checking before it gets patched: the three fields are missing because step 2 of your repro deletes pnpm-lock.yaml.

pnpm-lock.yaml is the pin. With it committed, pnpm install && pnpm run build succeeds — the build and typecheck run clean on master here, so catalog.ts matches the AI SDK version the repository actually depends on. Deleting the lockfile resolves every range to whatever is newest at that moment, which is how you got type definitions the code was never written against. That is also why the failure looks version-independent: it follows the deletion, not the platform, which is likely why it reproduced on both Windows and Linux.

So the fix is to keep the lockfile rather than to add the fields:

git checkout pnpm-lock.yaml   # if it is already gone
pnpm install --frozen-lockfile
pnpm run build

--frozen-lockfile is worth using deliberately: it fails loudly if the lockfile and the manifests disagree, instead of silently resolving newer versions.

Adding 'thinking.budget', thinkingTokenBudgetField, and allowedFallbackModels would compile against the newer SDK but would then be wrong for the locked one, so it trades a build error you can undo for a mismatch that ships. Moving to that SDK version is a real change — a dependency bump with its own review of what those fields mean — rather than three additions to satisfy a compiler.

If you deleted the lockfile deliberately because you need a newer SDK for some other reason, say so and the ask becomes "please update the AI SDK dependency", which is a fair request and a different thread.

---

中文

这一条在动手打补丁之前值得重新核对：那三个字段之所以"缺失"，是因为复现步骤的第 2 步删除了 pnpm-lock.yaml。

pnpm-lock.yaml 就是版本锁定本身。在它被提交的状态下，pnpm install && pnpm run build 是成功的——本仓库 master 上的 build 与 typecheck 均干净通过，说明 catalog.ts 与仓库实际依赖的 AI SDK 版本是匹配的。删除锁文件会让每个范围都解析到当时的最新版本，于是就得到了代码从未针对其编写的类型定义。这也解释了为何该故障看起来与版本无关：它跟随的是删除动作，而非平台，这多半正是它在 Windows 与 Linux 上都能复现的原因。

因此修复方式是保留锁文件，而不是补上字段：

git checkout pnpm-lock.yaml   # 如果它已被删除
pnpm install --frozen-lockfile
pnpm run build

--frozen-lockfile 值得刻意使用：当锁文件与清单不一致时它会明确失败，而不是静默解析出更新的版本。

补上 'thinking.budget'、thinkingTokenBudgetField 与 allowedFallbackModels 固然能针对新版 SDK 通过编译，但对被锁定的那个版本而言就是错的——这等于把一个可撤销的构建错误，换成了一个会被发布出去的不匹配。迁移到该 SDK 版本是一项真实的变更：一次依赖升级，并需要单独评审这些字段的含义，而不是为满足编译器而新增三行。

如果您是出于其他原因、有意删除锁文件以使用更新的 SDK，请说明——那么诉求就变成"请升级 AI SDK 依赖"，这是一个合理的请求，也是另一个议题。

[argszero]

@Saidoua 你的指正是对的, 我接受——锁文件是关键。我上一轮的「给门补分类」是在**没先问「到底想不想升级 SDK」**的前提下给的, 那确实是把「可撤销的构建错误」换成了「会发布出去的不匹配」, 这不该是首选。让我把两个层面分开:

我上一轮哪对、哪需要修正

对的部分（我们一致）: 这三个 TS 报错不是「catalog.ts 缺字段」要补——字段来自代码未针对其编写的 pi-ai 类型定义; 报错位 catalog.ts:143/242/267 确实是 satisfies Record<keyof X, ...> 的编译期漂移门, 它刻意在「type definitions 与代码不同步」时 fail。

需要修正的部分（你点得对）: 我该在确定要升级到新 pi-ai 之后才推荐「在门里分类」——那只适用于「决定 move to newer SDK」的场景。若只是「想 build 过」, 正确做法是保留锁文件, 而不是去动 gate。

所以正确的决策树

1. 不想升级 SDK（只是想 build/typecheck 过）→ 保留 pnpm-lock.yaml + pnpm install --frozen-lockfile。这是你的主方案, 正确且最小。
2. 确实想升级 SDK（比如要某个新能力/新字段）→ 这才是一次真正的依赖升级, 需要: ① pnpm update @earendil-works/pi-ai（或改 package.json range）; ② 评审新字段含义（thinkingTokenBudgetField/allowedFallbackModels/thinking.budget 在 pi-ai 里什么语义）; ③ 然后在三个 drift gate 里给新成员分类（offer/withhold, 按 dsh 要不要暴露该能力）。这才是「在门里加分类」的正确时机。
3. 只为了消除构建错误的「折中」（一边想升级一边偷懒）→ 不要用, 那是你正确指出的「可撤销错误换发布不匹配」。

一个补充：漂移门 vs 锁文件是两件独立的事

即使保留锁文件, 这些 drift gate 依然是有意的——它们保护的是「当 maintainer 主动升级 pi-ai 时, 类型不同步会 fail loud, 逼它分类」; 不是给「第三方删锁文件」预备的。所以:

• 对 OP: git checkout pnpm-lock.yaml + --frozen-lockfile 即可恢复 build（若 OP 没有有意升级, 这是终局）。
• 对 maintainer: 若任何 PR 想升 pi-ai, 那个 PR 应同时在三个 gate 里补分类 + 评审新字段。这是我上一轮 diff 的正确适用范围, 收窄到「升级 PR」而非「普通 build 报错」。

感谢你的澄清——这个「lockfile 是 pin」的提醒让讨论更准确。会建议 OP 先跑你的方案; 若他确认需要更强能力, 再开「升级 pi-ai」的独立议题。