feat(desktop): 模型图片输入能力本地声明与运行期对账

[zyjisdog]

这次改了什么

摘要

让用户能在设置 → 模型 → 高级设置里，为任意一个模型声明上游目录没说清、但实际成立的模型能力，声明只落在本机 model-catalog-overrides.json，不写回 Server、不改连接配置。

背景是一条真实的用户困境：目录（Server 正本 → 客户端目录）里某些模型的能力位是错的或缺失的。典型实报——space-bunny-free 被声明为「不支持思考」且六档思考档全为 null，而厂商模型卡明确它是强制推理模型（reasoning_effort: none 无效，档位 max/xhigh/high/medium/low）。目录这么写，Pi 客户端就没有任何 thinking 通道可用，模型的推理文本只能随 content 通道返回、被 Cindy 当作普通 assistant 正文渲染，用户看到的是「思考被写进正文」，而不是可折叠的思考块。

这个 PR 把 override 写入面从「只有读」补成「可声明」，并在两条能力上真正落地：图片输入能力（多模态）与思考档位。

变更类型

• feat 新功能
• fix 缺陷修复
• refactor / perf 重构或性能优化
• docs / test / chore 文档、测试或工程维护
• 其他：

范围

• 关联 Issue / 需求：模型能力目录错报 / 缺失时，用户缺少自行声明的入口
• 本 PR 包含：
  • override 写入面（此前 upstream 上只有 readModelCatalogOverrides）：新增 store 写入函数、IPC handler、preload 桥、抽屉 UI 控件区；非法组合在 IPC 边界就拒，不让 sanitize 事后把整条判无效、用户看着「保存了但没生效」
  • 多模态（图片输入）能力声明：supportsImageInput 三态（跟随 / 显式支持 / 显式不支持）；运行期对账按声明决定是否拒收图片
  • 思考档位声明：efforts + defaultEffort，三态 + 逐档勾选；Pi 侧无档位时记 warn 而非静默照发
  • 顺带修正高级抽屉两处上下文显示问题（非新增上下文能力，是既有能力的显示与时序修正）：
    「上游最大上下文」不再拿 200K 展示兜底冒充上游窗口（按 contextWindowMax → 已验证 contextWindow → 未声明 三级来源，第 3 条必须排除「自定义模型缺元数据时的 200K 兜底」——那个常量会让用户以为容量只有 200K，而运行期窗口其实取模型级上下文上限）；上下文上限提交在途时不再闪回旧值（ctxCommitting 收口）
• 明确不包含：
  • 上下文窗口上限的 override 能力本身不在本 PR 新增范围：它在 upstream/main 已存在，本 PR 未改动其写入逻辑；本 PR 只是让写入面成为可复用的通用通道，使「思考档位」能以同一套机制落地。需要区分的是：本 PR 仍然包含上文那条上下文显示与提交时序的修正（既有能力的修 bug，不是新增能力）
  • 不改 Server 正本（上游元数据修正应由 Server 侧 PR 处理）
  • 不开通用 patch 写入口（会让任意目录字段可从 renderer 改写，超出当前需求）
• 用户可见变化：设置 → 模型 → 高级设置新增「图片输入能力」与「思考」两行声明控件；多档勾选、跟随供应商、失败提示带可执行指引；另修正高级抽屉「上游最大上下文」的取值来源与上下文上限提交在途的闪回
• 是否存在 breaking change：无

UI 变化

• 引用的设计规范：docs/design-rules/DESIGN.md §4 Component Stylings（Buttons）：声明控件沿用同抽屉既有 dropdown 触发按钮的形态——同一控件内「状态图标 + 文案 + Chevron」的组合、rounded-full 胶囊外形、hover 走 --surface-hover，颜色全部走语义 token，Light/Dark 两套都不写死；disabled 状态沿用同抽屉协议控件既有约定（禁用但不改 opacity），未新增视觉语言。docs/design-rules/DESIGN.md §11 Voice & Content：文案沿用既有 override 控件的「跟随供应商 / 已声明」措辞与 §11.1「动宾结构、结果点名对象」的要求，失败提示按 §11.1「错误 = 发生了什么 + 下一步」给出可执行原因（errorReason 透出），五语言经 i18n key 落地。docs/design-rules/DESIGN.md §14.2 Focus Management：多选下拉勾选时 preventDefault 阻止 Radix 自动关闭，便于连续勾多档，键盘路径沿用 Radix 既有行为，未改 Tab 遍历。

怎么验证的

自动验证

pnpm --filter desktop run typecheck
结果：通过（0 error）

pnpm test:unit:related
结果：EXIT=0，8 个工作区全 PASS（含 desktop 全量 unit）

pnpm check:dco
结果：8 commits signed off

新增/更新测试：
- model-catalog-override-store.test.ts（图片输入声明面，12 例）
- modelCatalogThinkingOverride.test.ts（思考档位声明面，7 例：三态、只动自己字段、
  perAgent 残留遮蔽清理、按 agent 合成 base+perAgent、多引擎分叉检出、非法组合拒收）
- providerHandlers.test.ts（写入 / 读回 / 拒写 / 边界校验，共 200 例）
- ModelAdvancedDrawer.test.tsx（抽屉声明控件，共 55 例）
- useModelCatalogImageInput.test.ts（hook 并发与回读纪律）
- pi-provider-routing.test.ts（运行期对账，Pi 侧）

手工验证

• 图片能力（设置 → 模型 → 高级设置 → 能力区）：目录未声明图片能力时，声明「支持」→ 该模型在 Pi 侧可发图；声明「不支持」→ Pi 客户端拒收图片（请求不出网），ErrorBanner 给出可执行指引。已覆盖自动化测试。
• 思考档位：对 space-bunny-free 这类目录声明「零档位」但实际会推理的模型，声明其真实档位（max/xhigh/high/medium/low）→ 该模型在 Pi 侧能开真正的 thinking 通道，推理回到可折叠思考块，不再混进正文。
• 平台：Windows（desktop main + renderer）；Pi 运行期对账在真实 Pi + fake gateway 下覆盖。

未执行的验证

• 未在真实 Pi 子进程 + 真实 space-bunny 网关上做端到端实拍（需真实账号额度与解锁环境）。目录错报的判定依据是厂商公开模型卡与 Pi 运行时 models.json 的实测（reasoning: false + 六档全 null）。

风险

风险分类

• 无已知风险
• SQLite / migration
• system prompt
• 协议兼容
• 权限 / 安全 / 用户数据
• 存量插件兼容（批准状态 / 指纹 / manifest 校验 / 安装布局 / 包格式）
• 原生层 / fingerprint / OTA
• 跨平台差异
• 其他：override 是本机最高优先级写入，若不加门会让运行期能力偏离服务端 / 管理员下发的配置

影响与回滚

• 权限 / 安全（本 PR 的关键门）：override 是本机最高优先级，不加这道门就能让运行期能力偏离管理员下发的企业配置。因此写入面对两类来源拒写：

  • xd（Cindy AI Gateway，能力由服务端目录控制）→ INVALID_PARAMS
  • 组织托管供应商（能力由管理员下发）→ PERMISSION_DENIED，与价格 override 同一位置、同一错误码

  抽屉控件也一并 disabled（按钮禁用挡不住受信 renderer 直调，IPC 侧拒写是真正的那道门）。

• 多引擎 id 双写：桥接投影两端 id 不同（如 openai 行 codex 用 gpt-5.6-sol、pi 用 chatgpt/gpt-5.6-sol），override 按 provider:model 精确匹配。只写主展示引擎的 id，运行期真正消费该能力的 Pi 读不到、UI 却显示「已声明」。因此写入面一次写该行全部引擎 id；各引擎键分叉时读回报 diverged，UI 允许「重选当前项」写回一致。

• 恢复继承：用户把「显式不支持」改回「跟随供应商」后 override 被删、声明读回 undefined，与「目录自己标了 text-only」在读回看来相同。为此运行期新增「活动目录最终结论」钩子（readModelCatalogImageCapability），以最终 input 判定「该恢复支持」；拿不到结论则保持现状不翻转（不猜）。

• 影响范围：仅模型能力元数据（图片输入 / 思考档位）的本机声明；不改会话数据、不改凭证、不改连接配置。

• 回滚 / 降级方式：删除 model-catalog-overrides.json 中对应条目即回到「跟随目录」；整文件删除回到「无覆盖」。本 PR 全部逻辑在客户端，回滚无服务端残留。

提交前检查

• 已 review 完整 diff
• 每个 commit 都带 DCO 签名（git commit -s，见 DCO）
• UI 改动已在「UI 变化」注明引用的设计规范章节
• 未提交凭证、令牌或授权文件
• 已核对受影响的文档（设计台账 design-inventory 已重跑生成器并保持最新）
• 已确认测试结果或说明未执行原因

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds local model capability overrides for image input and thinking tiers.

当前 PR 未发现仍需阻止合并的新问题，看来可以安全合并。

Summary

本 PR 为桌面端增加模型图片输入与思考档位的本地声明能力，并让活动 Pi 会话在运行期重新对账目录能力；同时修正高级设置中的上下文容量展示和提交状态时序。

• 新增受限的本地 override 存储、IPC、preload 与 renderer hooks。
• 设置抽屉提供图片输入三态和思考档位多选声明，并处理多引擎模型 ID 分叉。
• Pi 在切模、同路由同步及图片发送前刷新能力快照，避免宿主与子进程状态分叉。
• 写入边界拒绝 XD 网关和组织托管供应商，并保留 owner 隔离与目录成员校验。
• 本轮未发现需要新增评论的问题。

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  UI["高级设置能力控件"] --> Hook["图片 / 思考 Hook"]
  Hook --> IPC["Preload 与受信 IPC"]
  IPC --> Guard["目标、权限、Owner 与目录成员校验"]
  Guard --> Store["model-catalog-overrides.json"]
  Store --> Catalog["刷新活动模型目录"]
  Catalog --> Pi["Pi 会话能力对账"]
  Pi --> Runtime["models.json / 活动思考档位快照"]

Loading

_{Reviews (15) · Last reviewed commit: "Merge remote-tracking branch 'upstream/m..."}

[zyjisdog]

@greptileai review

[zyjisdog]

第二轮独立对抗审核（对上一批修复本身）

审核对象：44c6a3fbe（第一轮 review 的修复批次）。结论：修完 P0 再合，已全部处理并推送 c98098750。

P0（已修）

路由重放会对 spawn-only 路由发 set_model，失败即终止整个任务。 本文件自己写明「spawn 能靠 custom model id 跑在 Pi 自带目录没有的路由上，重复 set_model 反而 fail-closed」（switchModel 开头同路由 no-op 不变量），而上一批的路由重放是无条件 set_model + 失败 terminate —— 用户在 SuperGrok 这类路由上改一次「图片输入能力」，下一次同步点就会把正在跑的任务杀掉。修法：switch_session 后先 get_state 读回，读回已等于当前路由就不发 set_model（这正是 spawn 路由这一类）；读回确实不同才重放。重放被拒/读回不匹配仍 fail-closed 终止（子进程确实跑在错路由上，静默发错模型比终止更糟）。

P1（已修）

1. 回合延后期间把图片放行给旧清单的子进程：延后只对齐宿主快照，而准入门读的就是这份快照 → 立即放行；子进程 models.json 还是旧值。改为 pending 且本次需要该能力时抛可重试的 PI_IMAGE_CAPABILITY_REFRESH_FAILED（不再假装已生效）。
2. currentSpec === undefined（启动后才新增的模型行）假装对账成功：写盘是空操作，却照样置 pending + 触发重载，而快照始终没变。改为显式跳过 + warn。
3. 新错误码不会在对话里本地化：ErrorBanner 只特判了 PI_IMAGE_INPUT_UNSUPPORTED，新码走兜底显示中文原文。已补同型分支（isPiImageCapabilityRefreshFailedError）并加「两码互不误判」测试。

P2（已修 / 已知）

• 已修：hook 写在途跳过回读改为只对同一 target 生效（否则写 A 行后立刻打开 B 行，B 卡在 loading 且点击无效）；store 的 loss guard 改用独立错误类型 → IPC 映射 PRECONDITION_FAILED 并把「先修正该文件」的指引带给用户。
• 已知并接受：读路径「取第一个非空」对存量单键条目（只写了一个引擎 id）仍可能 UI 显示已声明而运行期拒收。该状态只可能由本未合分支的旧写法产生，外发数据不存在；多引擎写入已保证新写入不再产生该状态。
• 测试缺口：回合运行中的延后分支缺少自动化用例 —— 该测试文件的 harness 没有事件注入通道（ctx.isStreaming 由 translator 事件驱动，rpc-client 被整体 mock），补测需要扩 harness。已用 P1-1 的分支守卫（pending + supportsNow → 抛错）覆盖逻辑，但未做端到端断言。

验证

pnpm test:unit:related EXIT=0（desktop/maker-core 全 PASS）；maker-core 与 desktop typecheck 0 错；check:i18n-glossary ✅；check:design-inventory ✅。新增测试 7 条：spawn-only 路由不重放/不终止、重放被拒终止、非 no-op 切模落在目标模型、两码互不误判、跨 target 回读不被吞、loss guard 错误类型与 IPC 码。

[zyjisdog]

已并入 upstream/main（45 commits，含 #4854「未知图片能力默认按支持处理」），51ee475ed，冲突已解、PR 恢复 MERGEABLE。

冲突点的处置（packages/maker-core/src/agents/pi/index.ts，双方改的是同一段 assertImageInputSupported）：

• 采用 upstream fix(pi): 未声明图片能力时默认允许图片输入 #4854 的语义：目录未声明 input 时按支持图片算（(nativeModel.input ?? ["text","image"]).includes("image")），不再一律拒收 —— 与全仓其它判定口径一致。
• 我的双向对账（先 refresh 再判、runExclusivePiRpc 补链、延后期间 pending 拒收）整段保留。
• 关键点：对账的「快照基线」口径必须跟着改 —— 否则对一个没写 input 的模型声明 false 时，基线（旧写法 false）与目标值相同会被判成「无变化」，声明永远落不下去。现在基线同样用 ?? ["text","image"]（hadImage），并加了注释说明两边必须同口径。

验证：pnpm test:unit:related EXIT=0；maker-core / desktop typecheck 0 错；pi-provider-routing 98 条全过（我的 7 条 + upstream #4854 的 3 条）；check:i18n-glossary ✅；check:design-inventory ✅（surface 数从 50 → 51，upstream 新增）。

[zyjisdog]

@greptileai review

[zyjisdog]

@greptileai review

[zyjisdog]

CI 红的两条根因（已定位，一条已修，一条在 upstream/main 上）

① 已修：design-inventory 台账落后（我的分支落后 upstream）

c864c6204：并入 upstream/main 后，upstream 新增的设置面板文件（#4813 Cindy Make 等）让 desktop.settings 的裸圆角计数 717 → 718，scripts/__tests__/design-inventory.test.mjs 的「CLI --check 在当前台账上通过」因此在 Windows/Linux 两个分片都红。按门禁要求重算台账（只改这一个统计单元格，人工区保留）。

顺带说明这条为什么只在 CI 出现、本地是绿的：CI 跑的是 PR 与当前 upstream/main 的合并结果，而本地 worktree 还停在我上一次合并的基点（6210df89d）。upstream 在这之后又走了 8 个提交。

② 未修（不是本 PR 引入）：cindyMakeInlineEntry.test.ts 在 upstream/main 上就是红的

src/renderer/__tests__/cindyMakeInlineEntry.test.ts > Cindy Make composer presentation
  > keeps question, plan and permission prompts ahead of the first-execution input lock
AssertionError: expected -1 to be greater than 222686

这是 source-contract 断言：测试在 CCAgentSessionView.tsx 里找字面量 ") : cindyMakeRecoveryId && session ? ("，而 #4813 把该处改成了先起一层 ) : (、再由 topSlot={cindyMakeRecoveryId && session ? ( 承载，字面量已不存在（indexOf 返回 -1）。

证据（都在 upstream/main 上验证，与本分支无关）：

• git show upstream/main:.../CCAgentSessionView.tsx | grep 只命中 topSlot={cindyMakeRecoveryId && session ? (，没有 ) : 前缀那一版；
• git show upstream/main:.../cindyMakeInlineEntry.test.ts 仍然断言带前缀的字面量；
• upstream/main 自己的 client-ci 在 7edd27be4 上也因同一条测试在 Linux/Windows 两个分片失败（run 35732083639）。

本 PR 没有触碰任何 cindyMake* 文件（git diff --name-only upstream/main...HEAD | grep -i cindyMake 为空）。

另外两条观察（非本 PR 问题）

• packages/anthropic-compat-proxy/src/oversized-attachments.test.ts 在 Windows 分片偶发失败，单跑 18/18 通过 —— 高负载下的时序假失败。
• 本地 pnpm test:unit:related 偶发 cindySubagentRunner.test.ts 同类假失败，单跑必过。

②需要 upstream 侧修（改一行断言字面量）或由维护者决定是否接受这条红；本 PR 侧不再夹带无关改动。

[MagicLizi]

这条 PR 需要维护者确认后才能继续自动审查和合并。

当前拦截是产品 / UI：设置高级抽屉新增「图片输入」三态声明（跟随供应商 / 支持 / 不支持），图片失败文案也变了。架构面上新增两条本机 IPC，并在切模、发图时按目录声明热重载 Pi 会话。design-inventory.md 只把生成计数从 717 改成 718，不改变规则含义。

请维护者在 PR 上 Approve；需要作者修改时请 Request Changes。讨论：#4889

[zyjisdog]

@greptileai review

[zyjisdog]

@greptileai review

[zyjisdog]

@greptileai review

acda94ee4 已处置本轮 5 条意见（显式「不支持思考」三态可存 / 默认档不再被猜成排序第一档 / 多引擎读回只认 Pi 侧且按内容比 / 声明后切模即对齐活会话档位快照 / ultra 补入候选），逐条回复并已 resolve，麻烦对新 head 再审一轮，辛苦！

[zyjisdog]

@greptileai review

[zyjisdog]

@greptileai review

[zyjisdog]

@greptileai review