[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 时是一个明确的行;填了之后立刻缩回成小链接 —— 那时他已经不需要它,常驻的显眼引导会变成每次打开都要跳过的噪音。
🔄 两道既有的闸当场抓住了我¶
ai-ui-tokens:我写了fontSize: 14,而三档是 11/13/15。抓得对,已改。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 控制台,那页永远是最新的。