Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(web): 视觉探测没得出结论时,原因留在视觉开关下面,不再只活六秒

lmliheng28477dec88c4
diff --git a/changelog/unreleased/2026-11-04-model-vision-refusal.md b/changelog/unreleased/2026-11-04-model-vision-refusal.md
new file mode 100644
index 00000000..e84d36bf
--- /dev/null
+++ b/changelog/unreleased/2026-11-04-model-vision-refusal.md
@@ -0,0 +1,72 @@
+# A vision probe that decided nothing says so under the vision switch, not in a six-second toast
+
+- **Date:** 2026-11-04
+- **Type:** fix
+- **Scope:** `web`
+- **Breaking:** no
+
+[中文](2026-11-04-model-vision-refusal.zh.md)
+
+The model config dialog's "detect" control beside the vision switch spends the user's own credential
+on one tiny image request. Its answer has three shapes: the model took the image (vision on), it
+refused it (vision off), or nothing usable came back (the switch stays as the reader left it). The
+first two moved the switch in front of the reader, and that movement is the whole account of the
+press. The third wrote nothing at all — so the reason was the only trace of the press, and it used to
+arrive as a notification: it sat over the dialog, dismissed itself after six seconds, and left a form
+that looked untouched. The three things it names (the API key, the base URL, the model id) are all in
+that same dialog, which is exactly what the reader is about to change.
+
+That sentence is now drawn in the dialog, directly under the vision switch's row (`role="alert"`,
+danger colour, two lines at most with the whole text on hover), and it stays until the form is edited
+or the next press starts. The two decided answers keep their toast: the switch they moved already
+says what was learned.
+
+One wrong subject goes with it: both failures used to borrow protocol detection's sentence ("could not
+detect the protocol, check the API key and the base URL") though the press was about images. They now
+open with "vision probe failed:" and relay the route's own truncated upstream text, which is the part
+that actually diagnoses the failure and used to be hidden behind the generic line. A request that never
+reached the route (a 500 from the server, an expired login, a dropped connection) reads the localized
+sentence for its error code instead — the rule the other two probes in this dialog and every other
+refusal slot in the app follow (7.19). A form with no model id never asks the route, but the press
+still has to explain itself, so the same line says to fill the id in.
+
+## Details
+
+- `packages/web/src/features/models/vision-refusal.ts` (new, 54 lines): `visionProbeRefusal(press)`
+ turns one press into that line, `null` for either decided answer. Three shapes: no model id (the
+ route must not be asked), the route answered (took it / refused it / learned nothing), and the
+ request itself failed. A press that learned nothing relays `message` (the upstream text the route
+ truncated) and falls back to the generic text when there is none — an empty line under the control
+ would say less than the toast it replaced. A failed request goes through `refusalText` (7.19's
+ app-wide rule).
+- `packages/web/src/features/models/models-page.tsx`: one `visionRefusal` state — cleared at the start
+ of every press and on every edit (the sentence describes the form it was sent), set when there is no
+ id to probe or when nothing was learned. The line is drawn below the switch row and above the
+ standing "read through the vision proxy model" hint, i.e. adjacent to the control that was pressed.
+ `detectVisionFromButton`'s three failure paths write that line instead of raising a toast; the two
+ decided answers keep theirs.
+- `packages/web/src/lib/strings{,-en}.ts`: one new string, `detectVisionFailed(detail)` ("视觉检测失败:…"
+ / "Vision probe failed: …") — the borrowed `detectFailedBody` is about the protocol and cannot be
+ reused; `detectVisionNeedsId` and the error-code table supply the rest.
+
+## Tests
+
+- `packages/web/test/vision-refusal.test.ts` (new, 9 cases): accepted leaves nothing / refused leaves
+ nothing / learned-nothing relays the upstream text as-is / no detail falls back to the generic text /
+ the protocol sentence is no longer used / a failed request reads its code's sentence (raw English
+ never reaches the screen) / an error the client raised itself keeps its own words and nothing at all
+ falls back to the generic text / no model id says what is missing / the active language.
+- `packages/web/e2e/models-vision-refusal.spec.mjs` (new, two cases on a real server): the probe route
+ is stubbed at `page.route` — it bills a real provider. Case ①: a `failed` answer carrying upstream
+ text draws that line under the switch, the notification region holds nothing to dismiss, the probe
+ carried the form's provider / model id / base URL, nothing was written, and seven seconds later the
+ line is still there; editing a character drops it. Case ②: a request that failed on the way out — a
+ coded 500 — reads `视觉检测失败:服务器内部错误,请稍后重试。` rather than advice about the protocol, while
+ the probe carried the unsaved `sk-probe`; once let through, the same button retries, the line goes,
+ the "accepts images, vision turned on" toast appears, the switch is on, and the probe ran twice.
+
+## Compatibility
+
+No interface change, no new dependency, no Project config change. Two dictionaries gain one string
+each; the mis-subject sentence ("could not detect the protocol…") stays where it belongs, in protocol
+detection.
diff --git a/changelog/unreleased/2026-11-04-model-vision-refusal.zh.md b/changelog/unreleased/2026-11-04-model-vision-refusal.zh.md
new file mode 100644
index 00000000..7efb2d05
--- /dev/null
+++ b/changelog/unreleased/2026-11-04-model-vision-refusal.zh.md
@@ -0,0 +1,56 @@
+# 模型库的视觉探测没得出结论时,原因留在视觉开关下面,不再只活六秒
+
+- **日期:** 2026-11-04
+- **类型:** fix
+- **范围:** `web`
+- **破坏性:** 否
+
+[English](2026-11-04-model-vision-refusal.md)
+
+模型库配置弹窗里,视觉开关旁边那颗「检测」会花用户自己的额度发一次极小的图片请求。它的答复只有三种:
+接受(视觉打开)、明确拒绝(视觉关闭)、什么也没学到(开关原样不动)。前两种在读者眼前把开关挪了位置,
+那一下就是这次按键的全部交代;第三种什么都没写,于是**理由就是这次按键留下的唯一痕迹** —— 而它过去只落进
+一条通知:通知浮在弹窗上、六秒后自己消失,屏上留下一张与按键前完全一样的表单,没有任何东西说明这颗按钮
+被按过。它点名的三个东西(API Key、base URL、模型 id)全在同一个弹窗里,读者改它们时正需要看着那句话。
+
+那两句话现在画在弹窗里、就在视觉开关那一行的下面(`role="alert"`、危险色、最多两行、整句挂悬停提示),
+一直留到表单被编辑或下一次按键开始。两种「有结论」的答复仍走通知:开关已经动过,读者看得见。
+
+顺带修掉一处**说错了标的**的诊断:这两条失败的句子此前借的是协议探测那句「无法检测接口协议,请检查
+API Key 与 base URL」—— 读者按的是关于图片的按钮,答的却是协议;现在它们各自以「视觉检测失败:」开头,
+并带出服务端转来的那句截断的上游原文(过去被那条通用句盖住,正好是最能定位问题的那一句)。请求本身根本
+没发出去时(服务端 500、登录过期、连接断了),画的是错误码自己的本地化句子 —— 与这个弹窗里另外两颗探测
+按钮、以及全应用其余拒绝位同一条规则(7.19)。表单里还没有模型 id 时,路线不会被问,但那一下仍然要交代,
+于是同一行里说「请先填写模型 id」。
+
+## 明细
+
+- `packages/web/src/features/models/vision-refusal.ts`(新,54 行):`visionProbeRefusal(press)` 把一次按键
+ 变成那句话,两种有结论的答复给 `null`。三种形状:表单没有模型 id(路线不该被问)、路线答复了(接受 /
+ 拒绝 / 没学到)、请求本身失败。前两种有结论的答复不留句子 —— 开关与它们各自的通知已经说完了;
+ 没学到的那次带出 `message`(路线截断过的上游原文),缺了就退回通用文本(空白的一行比它取代的通知说得更少);
+ 请求失败走 `refusalText`(7.19 的全应用口径)。
+- `packages/web/src/features/models/models-page.tsx`:一个 `visionRefusal` 状态 —— 每次按键开始时清掉、
+ `set()` 里清掉(表单任何一次编辑都让那句话描述的表单不在屏上了)、没有模型 id 或没得出结果时写上。
+ 句子画在视觉开关那一行下面、视觉关闭时那行常驻说明的上面(贴着被按的控件,常驻说明不是这次按键的答复)。
+ `detectVisionFromButton` 的三条失败路从 `toastError` 改成写这一行;两种有结论的答复仍是原来的通知。
+- `packages/web/src/lib/strings{,-en}.ts`:新增一条 `detectVisionFailed(detail)`(「视觉检测失败:{detail}」/
+ `Vision probe failed: {detail}`)—— 原来借的 `detectFailedBody` 讲的是协议,不能复用;其余复用
+ `detectVisionNeedsId` 与错误码表里的句子。
+
+## 测试
+
+- `packages/web/test/vision-refusal.test.ts`(新,9 条):接受不留句子 / 拒绝不留句子 / 没学到时原样带出
+ 上游那句 / 路线没给理由时退回通用文本 / 不再讲协议探测那句 / 请求本身失败按错误码取句子(英文原文不上屏)/
+ 客户端自己抛的错保留自己的话、什么都没有时退回通用文本 / 没有模型 id 时说缺什么 / 跟随当前语言。
+- `packages/web/e2e/models-vision-refusal.spec.mjs`(新,两条真服务端用例):探测路线在 `page.route` 上打桩
+ (它真的会计费)。用例①:答复 `failed` 加一句上游原文 → 视觉开关下面出现那句话、通知区 0 个可点条目、
+ 探测带走的是表单里的 provider / model id / base URL、什么都没写,**七秒后句子仍在**,改一个字符即清掉。
+ 用例②:请求本身失败(500 加错误码)→ 画的是 `视觉检测失败:服务器内部错误,请稍后重试。`(不再叫读者
+ 去看协议),探测带走的是未保存的 `sk-probe`;放行后同一颗按钮重试 —— 句子消失、`该模型接受图片输入,
+ 已开启视觉` 那条通知出现、开关被打开、探测发了两次。
+
+## 兼容
+
+没有接口变化,没有新依赖,没有 Project 配置变化。文案只在中文与英文两个词典各加一条;此前那句错标的
+「无法检测接口协议…」仍在协议探测那一处使用(它对那里是对的)。
diff --git a/packages/web/e2e/models-vision-refusal.spec.mjs b/packages/web/e2e/models-vision-refusal.spec.mjs
new file mode 100644
index 00000000..b7dfba17
--- /dev/null
+++ b/packages/web/e2e/models-vision-refusal.spec.mjs
@@ -0,0 +1,202 @@
+/**
+ * Regression: the model config dialog's vision probe says why it decided nothing — in the dialog,
+ * under the switch it was asked about — instead of leaving the form exactly as it was with the
+ * reason in a notification that dismissed itself after six seconds.
+ *
+ * The probe spends the user's credential on one tiny image request. Two of its outcomes move the
+ * switch (accepted → on, refused → off) and that movement is the whole account of the press. The
+ * third learned nothing and leaves the switch alone, so the sentence is the only thing that says
+ * the button was pressed — and the fields it is about (the key, the base URL, the model id) are all
+ * in the same dialog. As a notification it was gone six seconds later.
+ *
+ * A second wrong it fixes: those two sentences used to be protocol detection's ("could not detect
+ * the protocol, check the API key and the base URL") although the press was about images.
+ *
+ * The probe route is stubbed rather than travelled — it bills a real provider — because what this
+ * spec is about is what the page does with the answer.
+ */
+import { test, expect } from "@playwright/test";
+import { provisionAndLogin } from "./auth.mjs";
+
+const BASE = process.env.BASE_URL;
+const P = "password123";
+
+/** The group and model the tests work with; unique enough to appear nowhere else. */
+const GROUP = "probevision";
+const MODEL = "probe-vision";
+const NAME = "Probe Vision";
+const BASE_URL = "http://127.0.0.1:9/v1";
+
+/** The row the model is, as this file seeds it: a hand-added model of a user-defined group. */
+const ROW = {
+ provider: GROUP,
+ modelId: MODEL,
+ displayName: NAME,
+ contextWindow: 32000,
+ clientType: "openai-chat",
+ baseUrl: BASE_URL,
+ maxTokens: 4096,
+};
+
+/** The table entry a `ModelInfo` came from: every field the response reports, sent back as-is. */
+function toEntry(m) {
+ const entry = { provider: m.provider, modelId: m.modelId };
+ for (const key of [
+ "displayName",
+ "contextWindow",
+ "clientType",
+ "vision",
+ "maxTokens",
+ "fastMode",
+ "pricing",
+ ]) {
+ if (m[key] !== undefined) entry[key] = m[key];
+ }
+ if (m.credential?.baseUrl !== undefined) entry.baseUrl = m.credential.baseUrl;
+ return entry;
+}
+
+/**
+ * Provision the user and seed their Project with the model, through the table PUT so nothing here
+ * depends on the built-in catalog. Idempotent: a rerun on the same data root rewrites the row the
+ * tests expect rather than trusting it.
+ */
+async function projectWithModel(page, user) {
+ await provisionAndLogin(page.request, user, P);
+ const { projects } = await (await page.request.get(`${BASE}/api/projects`)).json();
+ const projectId = projects[0].projectId;
+ const read = async () =>
+ (await page.request.get(`${BASE}/api/projects/${projectId}/models`)).json();
+
+ const table = await read();
+ const current = table.models.find((m) => m.provider === GROUP && m.modelId === MODEL);
+ if (!current || (current.displayName ?? "") !== NAME) {
+ const put = await page.request.put(`${BASE}/api/projects/${projectId}/models`, {
+ data: {
+ defaultModel: table.defaultModel,
+ models: [...table.models.filter((m) => m.provider !== GROUP).map(toEntry), ROW],
+ },
+ });
+ expect(put.ok(), "seed the model through the table PUT").toBeTruthy();
+ }
+ expect(
+ (await read()).models.find((m) => m.provider === GROUP && m.modelId === MODEL),
+ "the Project holds the model",
+ ).toBeTruthy();
+}
+
+/**
+ * Open the model's config dialog. The list is filtered rather than scrolled: a user-defined group
+ * sits far below the built-in ones, and a search force-opens every group it leaves visible.
+ */
+async function openModelDialog(page) {
+ await page.goto("/models");
+ await page.locator('input[placeholder*="搜索"]').first().fill(NAME);
+ const card = page.getByText(NAME, { exact: true }).first();
+ await expect(card).toBeVisible();
+ await card.click();
+ const dialog = page.getByRole("dialog");
+ await expect(dialog).toBeVisible();
+ await expect(page.getByRole("button", { name: "删除模型" })).toBeVisible();
+ return dialog;
+}
+
+/** The probe trigger beside the vision switch — "检测", not the base URL's "检测协议". */
+function detectButton(dialog) {
+ return dialog.getByRole("button", { name: "检测", exact: true });
+}
+
+/** The line the dialog draws under the vision switch. */
+function line(dialog) {
+ return dialog.getByRole("alert");
+}
+
+/** The notification area's dismissible entries: what a failed probe used to be. */
+function toasts(page) {
+ return page.getByRole("region", { name: "通知" }).getByRole("button");
+}
+
+test("a probe that learned nothing leaves its reason under the vision switch", async ({ page }) => {
+ await projectWithModel(page, "r192test");
+
+ const dialog = await openModelDialog(page);
+ const posts = [];
+ await page.route("**/api/projects/*/models/detect-vision", async (route) => {
+ if (route.request().method() !== "POST") return route.fallback();
+ posts.push(route.request().postDataJSON());
+ // What the route sends when the provider answered nothing usable: the truncated upstream text.
+ await route.fulfill({
+ status: 200,
+ contentType: "application/json",
+ body: JSON.stringify({ outcome: "failed", message: "401 Unauthorized: invalid api key" }),
+ });
+ });
+
+ await detectButton(dialog).click();
+
+ // One sentence, in the dialog, naming what was probed plus the provider's own words.
+ await expect(line(dialog)).toHaveText("视觉检测失败:401 Unauthorized: invalid api key");
+ await expect(toasts(page)).toHaveCount(0);
+ expect(posts).toHaveLength(1);
+ // The probe asked about the form as it stands, and wrote nothing back into it.
+ expect(posts[0]).toMatchObject({ provider: GROUP, modelId: MODEL, baseUrl: BASE_URL });
+
+ // And the reason is still on screen after the toast that used to carry it would have gone.
+ await page.waitForTimeout(7000);
+ await expect(line(dialog)).toHaveText("视觉检测失败:401 Unauthorized: invalid api key");
+
+ // An edit retires it: the sentence described the endpoint that was probed, and that endpoint is
+ // no longer the one in the field.
+ await dialog.getByLabel("自定义 base URL").fill("http://127.0.0.1:9/v2");
+ await expect(line(dialog)).toHaveCount(0);
+});
+
+test("a request that failed on the way out reads in the app's words, and the retry clears it", async ({
+ page,
+}) => {
+ await projectWithModel(page, "r192retry");
+
+ const dialog = await openModelDialog(page);
+ const posts = [];
+ let refuse = true;
+ await page.route("**/api/projects/*/models/detect-vision", async (route) => {
+ if (route.request().method() !== "POST") return route.fallback();
+ posts.push(route.request().postDataJSON());
+ if (!refuse) {
+ await route.fulfill({
+ status: 200,
+ contentType: "application/json",
+ body: JSON.stringify({ outcome: "supported" }),
+ });
+ return;
+ }
+ await route.fulfill({
+ status: 500,
+ contentType: "application/json",
+ body: JSON.stringify({ error: { code: "internal", message: "RAW ENGLISH MESSAGE" } }),
+ });
+ });
+
+ // A key typed but not yet saved: the probe asks about it, which is why its refusal belongs on the
+ // form rather than in a notification.
+ await dialog.getByLabel("API key").fill("sk-probe");
+
+ await detectButton(dialog).click();
+ // The code's own sentence, not the server's English, and not protocol detection's advice.
+ await expect(line(dialog)).toHaveText("视觉检测失败:服务器内部错误,请稍后重试。");
+ await expect(toasts(page)).toHaveCount(0);
+ expect(posts).toHaveLength(1);
+ // What was probed is the draft, not the stored row.
+ expect(posts[0]).toMatchObject({ baseUrl: BASE_URL, apiKey: "sk-probe" });
+
+ // The button is the retry, and a verdict leaves no line behind: vision is switched on and the
+ // outcome travels in the toast the dialog has always used for it.
+ refuse = false;
+ await detectButton(dialog).click();
+ await expect(line(dialog)).toHaveCount(0);
+ await expect(page.getByRole("region", { name: "通知" })).toContainText(
+ "该模型接受图片输入,已开启视觉",
+ );
+ await expect(dialog.getByRole("switch", { name: "支持视觉" })).toBeChecked();
+ expect(posts).toHaveLength(2);
+});
diff --git a/packages/web/src/features/models/models-page.tsx b/packages/web/src/features/models/models-page.tsx
index 6410d3c6..4e98707c 100644
--- a/packages/web/src/features/models/models-page.tsx
+++ b/packages/web/src/features/models/models-page.tsx
@@ -171,6 +171,7 @@ import { modelTestRefusal } from "./model-test-refusal";
import type { ModelTestAnswer } from "./model-test-refusal";
import { detectProtocolRefusal } from "./detect-refusal";
import type { DetectPress } from "./detect-refusal";
+import { visionProbeRefusal } from "./vision-refusal";
/**
* The authorization flows a group's Connect dialog can run, keyed by the flow named in that
@@ -2735,6 +2736,13 @@ function ModelDialog({
const detectInFlight = useRef<Promise<DetectOutcome | null> | null>(null);
/** Vision probe in progress (its own control, so its own busy state). */
const [visionDetecting, setVisionDetecting] = useState(false);
+ /**
+ * The sentence the last vision probe that decided nothing left under the vision switch
+ * (vision-refusal.ts). It lives on the dialog for the same reason the other two probes' lines do:
+ * it names the key, the URL and the id this form holds, and a toast would be gone before the
+ * reader had read it against them. Cleared by every edit and at the start of the next press.
+ */
+ const [visionRefusal, setVisionRefusal] = useState<string | null>(null);
/** Single-flight guard for the vision probe: it bills the user, so never twice at once. */
const visionInFlight = useRef<Promise<void> | null>(null);
const isNew = row === null;
@@ -2772,9 +2780,11 @@ function ModelDialog({
setForm((prev) => ({ ...prev, ...patch }));
// A refused probe described the values it was sent: any edit makes that sentence describe a
// form that is no longer on screen, so it goes with the field it named. Same for the detection
- // line below — a detection reads the URL, the key and the id, so every one of them retires it.
+ // and vision lines below — both read the URL, the key and the id, so every one of them retires
+ // it.
setTestRefusal(null);
setDetectRefusal(null);
+ setVisionRefusal(null);
// Clear the error marker for whichever field was changed (keys match RowState field names).
setFieldErrors((prev) => {
const next = { ...prev };
@@ -2960,22 +2970,29 @@ function ModelDialog({
};
/**
- * Vision probe. Mirrors protocol detection — always clickable, single-flight, toast-only
- * — with one deliberate difference: it is a REAL completion on the user's credential
+ * Vision probe. Mirrors protocol detection — always clickable, single-flight — with one
+ * deliberate difference: it is a REAL completion on the user's credential
* (an image request cannot be shaped to cost nothing the way the protocol probes are), so
* it only ever runs from this button, never implicitly and never on save.
*
* Three outcomes, because "the probe failed" and "the model says no" are different facts:
* a hit switches vision ON, a definitive image rejection switches it OFF, and a probe
- * that learned nothing leaves the switch exactly as the user had it.
+ * that learned nothing leaves the switch exactly as the user had it — and, unlike the other
+ * two, has to say why on the form itself (vision-refusal.ts): the sentence names what was
+ * probed, and nothing here writes anything the reader could read the answer off instead.
*/
const detectVisionFromButton = async () => {
if (visionInFlight.current) return;
const modelId = form.modelId.trim();
if (!modelId) {
- toastError(S.models.detectVisionNeedsId);
+ // Nothing is asked of the route without an id, but the press still happened: the line says
+ // why, next to the control, instead of only in a toast that is gone by the time the reader
+ // has scrolled to the id it names.
+ setVisionRefusal(visionProbeRefusal({ kind: "unprobeable" }));
return;
}
+ // This run describes the form as it stands now; the previous line described the one it replaced.
+ setVisionRefusal(null);
setVisionDetecting(true);
const run = (async () => {
try {
@@ -2994,10 +3011,12 @@ function ModelDialog({
set({ vision: false });
toastInfo(S.models.detectVisionNo);
} else {
- toastError(S.models.detectFailedBody);
+ // Learned nothing: the switch stays as the reader left it, and the line carries the
+ // provider's own sentence back to the form.
+ setVisionRefusal(visionProbeRefusal({ kind: "answer", result: res }));
}
- } catch {
- toastError(S.models.detectFailedBody);
+ } catch (e) {
+ setVisionRefusal(visionProbeRefusal({ kind: "failed", error: e }));
} finally {
setVisionDetecting(false);
}
@@ -3872,11 +3891,13 @@ function ModelDialog({
<div className={toggleCellClass}>
{/* Detect sits inline after the switch — the protocol control's idiom, but next
to the setting it fills in rather than at a field's top-right, since this row
- has no field to hang off. Always clickable, single-flight, toast-only, like
- protocol detection; it just costs a real (tiny) completion, so it never runs
- on its own. `flex-wrap` is what lets the switch and the trigger share a
- half-width cell: when they do not both fit, the trigger drops onto its own
- line inside the cell instead of widening the grid column. */}
+ has no field to hang off. Always clickable and single-flight, like protocol
+ detection; it just costs a real (tiny) completion, so it never runs on its own.
+ Its two verdicts announce themselves through the switch they moved, while a
+ press that decided nothing leaves the line drawn below (visionRefusal).
+ `flex-wrap` is what lets the switch and the trigger share a half-width cell:
+ when they do not both fit, the trigger drops onto its own line inside the cell
+ instead of widening the grid column. */}
<div className="flex flex-wrap items-center gap-x-3 gap-y-1">
<label
className={`inline-flex items-center gap-2 ${canEdit ? "cursor-pointer" : "cursor-not-allowed"}`}
@@ -3905,6 +3926,21 @@ function ModelDialog({
</Button>
)}
</div>
+ {visionRefusal !== null && (
+ // Under the switch row the button sits in, inside this half-width cell:
+ // `line-clamp-2` keeps a long upstream sentence from heightening the form, and the
+ // whole text is on hover, the way every other refusal slot carries its longer form.
+ // Drawn above the off-state hint so it stays adjacent to the control that was
+ // pressed; the hint is a standing explanation, not the answer to this press.
+ <p
+ role="alert"
+ data-tooltip={visionRefusal}
+ data-tooltip-content="text"
+ className={`mt-1 line-clamp-2 break-words text-xs ${toneInk.danger}`}
+ >
+ {visionRefusal}
+ </p>
+ )}
{!form.vision && (
<p className="mt-1 text-xs text-gray-400 dark:text-gray-500">
{S.models.visionOffProxyHint}
diff --git a/packages/web/src/features/models/vision-refusal.ts b/packages/web/src/features/models/vision-refusal.ts
new file mode 100644
index 00000000..21c48c92
--- /dev/null
+++ b/packages/web/src/features/models/vision-refusal.ts
@@ -0,0 +1,54 @@
+/**
+ * The model config dialog's vision probe ("检测" beside the vision switch): the sentence a press
+ * that decided nothing leaves under that control, and why that sentence is a line in the dialog
+ * rather than a toast.
+ *
+ * The probe spends the user's own credential on one tiny image request and writes nothing unless it
+ * learns something: a hit switches vision on, a definitive refusal switches it off, and a press that
+ * got no usable answer leaves the switch exactly as it was. So the last of those is a sentence the
+ * reader has to keep while they look at the same form they are about to fix — the key, the base URL
+ * and the model id are all a glance away — and as a notification it sat over the dialog and
+ * dismissed itself after six seconds, leaving no trace that the button had been pressed.
+ *
+ * Two of these three sentences used to be a single one borrowed from protocol detection ("could not
+ * detect the protocol, check the API key and the base URL"), which names the wrong subject at the
+ * wrong place: the reader pressed a control about images, and the answer talks about a protocol.
+ *
+ * The two answers keep their toast (`detectVisionOk` / `detectVisionNo`): each moved the switch in
+ * front of the reader, which is the whole account of the press, and a rejection is a verdict rather
+ * than a refusal. A missing model id is not a probe at all — the route must not be asked without
+ * one — yet it is still a press that has to say why nothing happened, next to the button.
+ */
+import type { ModelVisionDetectResponse } from "@adelie/server/api";
+import { S } from "../../lib/strings";
+import { refusalText } from "../../lib/api-error";
+
+/** What one press of the vision probe came back with. */
+export type VisionPress =
+ /** The form has no model id, so there is nothing to probe (the button still has to say so). */
+ | { readonly kind: "unprobeable" }
+ /** The route answered: it either took the image, refused it, or learned nothing. */
+ | { readonly kind: "answer"; readonly result: ModelVisionDetectResponse }
+ /** The request itself failed on the way out (server error, login gone, connection dropped). */
+ | { readonly kind: "failed"; readonly error?: unknown };
+
+/**
+ * The line the dialog draws under the vision control, or `null` when the press needs none.
+ *
+ * Both verdicts leave nothing behind here: the switch they moved already says what was learned, and
+ * they carry their own toast. A press that decided nothing reads the provider's own sentence (the
+ * route truncates it) under a phrase naming what was probed, because "vision detection failed" and
+ * "the endpoint never answered" have to be told apart by the reader fixing the form. Nothing at all
+ * falls back to the generic text — an empty line under the control would say less than the toast it
+ * replaced. A request that never reached the route reads its code's sentence (`refusalText`, 7.19's
+ * rule), so a 500 is not relayed as advice about the model id this form already has.
+ */
+export function visionProbeRefusal(press: VisionPress): string | null {
+ if (press.kind === "unprobeable") return S.models.detectVisionNeedsId;
+ if (press.kind === "answer") {
+ const { outcome, message } = press.result;
+ if (outcome === "supported" || outcome === "unsupported") return null;
+ return S.models.detectVisionFailed(message ?? S.common.unknownError);
+ }
+ return S.models.detectVisionFailed(refusalText(press.error));
+}
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index e0789c1a..1923ddb1 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -2189,6 +2189,8 @@ export const en: Strings = {
detectVisionNeedsId: "Fill in the model id first, then detect.",
detectVisionOk: "This model accepts images; vision turned on",
detectVisionNo: "This model does not accept images; vision left off",
+ /** The vision probe learned nothing: name what was probed, then relay the route's own sentence. */
+ detectVisionFailed: (detail: string): string => `Vision probe failed: ${detail}`,
visionOffProxyHint: "Images are read via the vision proxy model",
fastMode: "Fast mode",
fastModeHint:
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 121a06b3..cb68d9b9 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -2234,6 +2234,8 @@ export const zh = {
detectVisionNeedsId: "请先填写模型 id,再进行检测。",
detectVisionOk: "该模型接受图片输入,已开启视觉",
detectVisionNo: "该模型不接受图片输入,视觉保持关闭",
+ /** 视觉探测一次没得出结论时,画在视觉开关下面的那一行;先讲清探的是视觉,再带出服务端给的句子(协议探测那句不适用)。 */
+ detectVisionFailed: (detail: string): string => `视觉检测失败:${detail}`,
/** Shown only while the vision switch is OFF: images are then read via the configured vision proxy model (read_file hands them to it). */
visionOffProxyHint: "使用视觉代理模型读图",
/** Switch label for the per-model fast mode (the provider's premium faster serving tier); the switch is only rendered for models whose AgentHub client can carry the parameter. */
diff --git a/packages/web/test/vision-refusal.test.ts b/packages/web/test/vision-refusal.test.ts
new file mode 100644
index 00000000..0a786a53
--- /dev/null
+++ b/packages/web/test/vision-refusal.test.ts
@@ -0,0 +1,89 @@
+/**
+ * The model config dialog's vision-probe line (src/features/models/vision-refusal.ts): which
+ * presses leave a sentence under the vision control, and whose words that sentence uses.
+ *
+ * The probe spends the user's own credential and, when it learns nothing, writes nothing — so this
+ * line is the only thing that accounts for the press once the six-second toast is gone. Two of the
+ * three outcomes are verdicts the switch itself reports, and the rule that matters most is the
+ * first: neither of them leaves a line behind.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { ApiError } from "../src/api/client";
+import { en as EN } from "../src/lib/strings-en";
+import { S, setActiveStrings, zh as ZH } from "../src/lib/strings";
+import { visionProbeRefusal } from "../src/features/models/vision-refusal";
+
+afterEach(() => {
+ setActiveStrings(ZH);
+});
+
+describe("visionProbeRefusal", () => {
+ it("leaves no line when the model took the image", () => {
+ // Vision was switched on in front of the reader, and that is the whole account of the press.
+ expect(visionProbeRefusal({ kind: "answer", result: { outcome: "supported" } })).toBeNull();
+ });
+
+ it("leaves no line when the model refused the image", () => {
+ // A verdict, not a refusal: the switch went off, which says what was learned.
+ expect(visionProbeRefusal({ kind: "answer", result: { outcome: "unsupported" } })).toBeNull();
+ });
+
+ it("relays the provider's sentence when the probe learned nothing", () => {
+ // The switch must stay where the reader left it, so the reason has to be on the form; the
+ // route's own truncated text is what makes a wrong key or endpoint diagnosable.
+ expect(
+ visionProbeRefusal({
+ kind: "answer",
+ result: { outcome: "failed", message: "401 Unauthorized: invalid api key" },
+ }),
+ ).toBe(S.models.detectVisionFailed("401 Unauthorized: invalid api key"));
+ });
+
+ it("does not fall back to an empty line when the route names no reason", () => {
+ // An empty line under the control would say less than the toast it replaced.
+ expect(visionProbeRefusal({ kind: "answer", result: { outcome: "failed" } })).toBe(
+ S.models.detectVisionFailed(S.common.unknownError),
+ );
+ });
+
+ it("does not talk about protocol detection", () => {
+ // The press was about images; the sentence that names the protocol is the other button's.
+ const line = visionProbeRefusal({ kind: "answer", result: { outcome: "failed" } });
+ expect(line).not.toBe(S.models.detectFailedBody);
+ });
+
+ it("reads a failed request through its code, so the advice is not misleading", () => {
+ // The endpoint was never probed: relaying a provider sentence would claim an answer that never
+ // came, so a 500 reads as a 500.
+ const line = visionProbeRefusal({
+ kind: "failed",
+ error: new ApiError(500, "internal", "RAW ENGLISH SERVER MESSAGE"),
+ });
+ expect(line).toBe(S.models.detectVisionFailed(S.errors.byCode["internal"] as string));
+ expect(line).not.toContain("RAW ENGLISH SERVER MESSAGE");
+ });
+
+ it("keeps the message of an error the client itself raised", () => {
+ // `refusalText`'s rule: only an ApiError goes through the code table; anything else with
+ // something to say is shown as it is, and nothing at all falls back to the generic text.
+ expect(visionProbeRefusal({ kind: "failed", error: new Error("network down") })).toBe(
+ S.models.detectVisionFailed("network down"),
+ );
+ expect(visionProbeRefusal({ kind: "failed", error: undefined })).toBe(
+ S.models.detectVisionFailed(S.common.unknownError),
+ );
+ });
+
+ it("says what is missing when the form has no model id yet", () => {
+ // No id means the route is never asked; the press still has to explain itself.
+ expect(visionProbeRefusal({ kind: "unprobeable" })).toBe(S.models.detectVisionNeedsId);
+ });
+
+ it("follows the active language", () => {
+ setActiveStrings(EN);
+ expect(visionProbeRefusal({ kind: "unprobeable" })).toBe(EN.models.detectVisionNeedsId);
+ expect(visionProbeRefusal({ kind: "answer", result: { outcome: "failed" } })).toBe(
+ EN.models.detectVisionFailed(EN.common.unknownError),
+ );
+ });
+});