跳转至

[ISSUE-0182] 余额是厂商特例,不是通用能力

Tony 的诉求

直接把 key 获取入口加上去……如果没充值(能检测余额吗?)让用户进去充…… 能获取到 key 的余额吗?要是能获取是不是可以显示在上边? 如果按照上边这样,是不是就不用专门写文档了?

🔴 对抗梳理否掉了其中两条

否掉①:内置截图比外部文档更难维护

用户以为内置图可以免掉写文档,恰恰相反:

外部链接 内置截图
平台改版后 对方自己更新,用户立刻看到新的 得发一个新版本才能更新
过期了谁发现 有人会反馈内容不对 没人会反馈 —— 图打得开、看着也像那么回事,只是按钮位置早变了

「图片能打开但已经过期」是那种不会有人来报的错。 用户照着旧图找不到按钮,只会默默放弃。 ⇒ 不内置图,直接给链接 —— 厂商自己的页面永远是最新的。

否掉②:厂商行「骑缝加点啥」

加什么都是重复:Key 入口已经在 API Key 那行。 空白也在传达「这里没有需要你操心的事」,骑缝不占位置不是放东西的理由。

查证过的事实(2026-09-20)

厂商 创建 Key 充值 余额接口
DeepSeek ✅ platform.deepseek.com/api_keys ✅ /top_up ✅ GET /user/balance
智谱 GLM ✅ 控制台 apikeys ❌ 没查证到 ❌ 公开文档里没有

⇒ 余额是厂商特例。 能力由 vendors.ts 声明(balancePath), 不在 UI 里硬判厂商 —— 哪天 GLM 出了,补一行配置即可。

🔴 GLM 的充值页和余额接口留空,不猜:给一个猜的路径,用户点进去 404, 比没有链接更糟。这条已写成判据,防止以后有人「顺手补上」。

三条设计决定

① 结论来自厂商,不自己算

DeepSeek 返回 is_available(它自己对「够不够调用」的判断)。 不用 total_balance > 0 去推 —— 看着等价,其实不是: 赠送额度可能已过期、可能有欠费、可能按月结算。 别人已经给了结论,就不要自己再推一个,推错的那次会把能用的账号标成「余额不足」。

② 只在测试成功之后查

不在输入框里边打字边查 —— 那会把每一次按键变成一次网络请求, 而且会把半截的 Key 发出去。测试成功意味着 Key 已被证明有效。

⚠️ 换 Key / 换地址后旧余额立刻作废:它是上一把 Key 的结论。

③ 不支持的厂商什么都不显示,也不写「暂不支持」

在 A 家见过余额、换到 B 家看到「暂不支持」,用户会问「是不是我配错了」; 而它压根不出现时,没人会去找一个从没见过的东西。

空 Key 时「去创建」要显眼(Tony 拍板选 B)

对第一次用的人,他手上根本没有 Key —— 这时把唯一能让他往下走的那一步 做成挂在字段右边的小链接,等于把它藏起来了。 ⇒ 空 Key 时是一个明确的行;填了之后立刻缩回成小链接 —— 那时他已经不需要它,常驻的显眼引导会变成每次打开都要跳过的噪音。

🔄 两道既有的闸当场抓住了我

  1. ai-ui-tokens:我写了 fontSize: 14,而三档是 11/13/15。抓得对,已改。
  2. ai-no-secrets:vendors.ts 出现 apiKey —— 命中的是 keyUrl: '…/api_keys' 这个 URL 路径,是误报。 但它的立意(厂商表随扩展分发,不许内置密钥)完全正确。 ⇒ 收窄锚点而不是放宽立意:改判「字段声明形态」(后面跟 : 或 =)。 ⚠️ 收窄之后做了反向验证:塞 apiKey: / api_key: / secretKey: 三种形态, 全部照样被抓 —— 证明这是收窄不是放水。

关于那条待办

「写地图版 Key 文档」这条降级不撤:链接 + 余额解决了 90% 的情况, 但「拿到 Key 之后填到哪里」仍然没有指引 —— 而那正是 ZCode 那篇唯一对不上的地方。 正式版发布时写一段短的就够,不必是完整教程。


v0.15.17:三个问题,第一个是我写的低级错误

Tony:「我这设置里明明有 key 为什么还让我填写?而且还挤变形了!!!」

🔴 ① 明明有 Key 却让重填 —— 判可用性没读功能配置

aiAvailability(accounts) 我没传第二个参数(功能自己的 accountId/modelId)。 于是走进「没选模型」分支 —— 而他有 2 个启用模型, 正好落进「有歧义、要求显式选」,被判成不可用。

他的功能明明已经选了 deepseek-flash,只是我没去读。

⇒ 判可用性和真正跑(runFeature)必须读同一份配置, 否则「界面说不能用」和「其实能跑」各说各话 —— 那比直接报错更难查。

已写成判据:两边都得按 features 里的 id 取 accountId/modelId。

② 新增与编辑长得不一样

上一版按「Key 填没填」给了两种形态:空态一个绿色大 Alert、有值时两个小链接。 我当时的理由是「空态最需要显眼」—— 但用户看到的是同一个对话框在两种情况下长得不一样,而它们做的是同一件事。

🔴 不该因为一个字段的值而换皮。

⇒ 统一成一种:「创建 ↗ / 充值 ↗」挂在 label 骑缝处 (那条线上本来就是空的,放进去零成本;单独占一行则是 「每次打开都要跳过的一行」,而拿 Key 是一次性动作)。 空态的引导改由 placeholder 承担 —— 不占行、不变形。

⚠️ 那个 Alert 在窄对话框里文字换行、按钮被挤,整块变形(Tony:「还挤变形了」)—— 这也是「显眼」做过头的代价。

③ 顺带查出的过期文案

设置页底部写着「到『新建任务 → 类别 / 关键词 → AI 推演』就能用了」, 而这两个名字在 v0.15.15 就已经改成「搜什么店」「帮我想搜哪些」。

🔴 这类错不会被任何判据抓到:它是一句转述别处界面的话, 而被转述的那处改名时,没人会想起这里还有一份。 ⇒ 已补判据盯住这句指路。同批还订正了推演对话框自己的标题与说明。

关于「示意图呢?」

仍然不做,理由没变(见本文上半部分):内置截图比外部文档更难维护, 而且过期了没人会反馈。现在的链接是直达 DeepSeek 控制台,那页永远是最新的。