@buyi1net/pi-toolkit 0.0.1

package/modules/eyes/menu.ts

@@ -0,0 +1,828 @@
+// 视觉配置子菜单：常规组里的 `视觉配置` 行打开这一页（原生 SettingsList 形态）。
+// 页面四行：
+//   视觉模型   —— SelectList 选 auto / off / 具体模型；改模型前先跑真实图片探测，通过才写盘
+//   刷新模型目录 —— 重读 Pi 的模型目录（不联网），成功后候选列表与目录版本号都刷新
+//   运行自检   —— 对当前生效路由发一张探测图（原向导 T 键的等价物），结果进诊断缓存
+//   路由状态   —— 只读展示当前路由
+//
+// 原 setup.ts 里必须保留的业务流程都落在下面这些可单测的函数上：
+//   discoverCandidates / routePatchFor / saveRouteSelection / runVisionSelfCheck / refreshVisionCatalogue
+// Esc 取消长任务靠 startCancellable 的 AbortController；探测常量在 vision-probe.ts。
+
+import {
+  type ExtensionContext,
+  type ModelRegistry,
+} from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Key,
+  matchesKey,
+  SelectList,
+  type SelectItem,
+  type SettingItem,
+  Text,
+} from "@earendil-works/pi-tui";
+import type { Translator } from "../../i18n.ts";
+import { I18nSettingsList } from "../../menu/settings-list.ts";
+import type { MenuTheme } from "../../menu/theme.ts";
+import type { ModuleMenuContext } from "../../module.ts";
+import { describeEyesRoute, saveEyesRoute, type EyesRouteConfig } from "./config.ts";
+import { selectAutomaticPiVisionModel, testPiVisionModel } from "./pi-model-backend.ts";
+import { VISION_PROBE_EXPECTED, VISION_PROBE_IMAGE } from "./vision-probe.ts";
+
+/** 分组页里的入口行 id */
+export const EYES_MENU_ITEM_ID = "eyes.settings";
+
+const ROW_MODEL = "eyes.settings.model";
+const ROW_REFRESH = "eyes.settings.refresh";
+const ROW_CHECK = "eyes.settings.check";
+const ROW_ROUTE = "eyes.settings.route";
+
+const VALUE_AUTO = "auto";
+const VALUE_OFF = "off";
+/** 模型取值编码：provider + NUL + modelId；provider / modelId 里不会出现 NUL */
+const MODEL_VALUE_SEPARATOR = "\u0000";
+
+/** 菜单需要的模型注册表能力（取 ModelRegistry 的子集，方便 headless 自测塞 stub） */
+export type VisionMenuRegistry = Pick<
+  ModelRegistry,
+  | "getAll"
+  | "getAvailable"
+  | "find"
+  | "getProviderAuthStatus"
+  | "complete"
+  | "hasConfiguredAuth"
+  | "refresh"
+>;
+
+export interface VisionSelection {
+  readonly provider: string;
+  readonly modelId: string;
+}
+
+export interface VisionCandidate extends VisionSelection {
+  /** 该供应商已配置认证；仅用于排序与候选描述 */
+  readonly authenticated: boolean;
+}
+
+export interface VisionDiagnostic {
+  readonly key: string;
+  readonly passed: boolean;
+  readonly elapsedMs: number;
+  readonly detail: string;
+}
+
+/** 菜单运行态：路由镜像、目录版本号与诊断缓存都由模块持有，跨菜单开关保留 */
+export interface EyesMenuRuntime {
+  /** 写盘目标（全局节）当前路由；会话启动与每次保存后刷新 */
+  globalRoute(): EyesRouteConfig;
+  /** 保存后重载配置并刷新视觉链，返回刷新后的全局路由 */
+  reapply(context: ExtensionContext): Promise<EyesRouteConfig>;
+  catalogueGeneration(): number;
+  bumpCatalogueGeneration(): void;
+  diagnostic(): VisionDiagnostic | undefined;
+  setDiagnostic(diagnostic: VisionDiagnostic): void;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function singleLine(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/** config.ts 的只读路由文案吃整份视觉配置（EyesConfig），这里把路由包回去 */
+function describeRoute(route: EyesRouteConfig, t: Translator): string {
+  return describeEyesRoute({ route }, t);
+}
+
+// ─────────────────────────────────────────────────────────────
+// 纯逻辑：候选发现、取值编码、写盘补丁、诊断缓存键
+// ─────────────────────────────────────────────────────────────
+
+export function candidateKey(candidate: VisionSelection): string {
+  return `${candidate.provider}${MODEL_VALUE_SEPARATOR}${candidate.modelId}`;
+}
+
+export function isModelValue(value: string): boolean {
+  return value.includes(MODEL_VALUE_SEPARATOR);
+}
+
+export function parseModelValue(value: string): VisionSelection | undefined {
+  const index = value.indexOf(MODEL_VALUE_SEPARATOR);
+  if (index <= 0) return undefined;
+  const provider = value.slice(0, index);
+  const modelId = value.slice(index + 1);
+  return provider && modelId ? { provider, modelId } : undefined;
+}
+
+/** 候选 = 模型目录里声明支持 image 且当前可用的模型；已认证的排前面，其余按 provider/model 排序 */
+export function discoverCandidates(registry: VisionMenuRegistry): VisionCandidate[] {
+  const candidates: VisionCandidate[] = [];
+  const seen = new Set<string>();
+  for (const model of registry.getAvailable()) {
+    if (!model.input.includes("image")) continue;
+    const selection: VisionSelection = { provider: model.provider, modelId: model.id };
+    const key = candidateKey(selection);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    candidates.push({ ...selection, authenticated: registry.hasConfiguredAuth(model) });
+  }
+  candidates.sort((left, right) => {
+    if (left.authenticated !== right.authenticated) return left.authenticated ? -1 : 1;
+    return candidateKey(left).localeCompare(candidateKey(right));
+  });
+  return candidates;
+}
+
+export function candidateKeys(candidates: readonly VisionCandidate[]): string {
+  return candidates.map((candidate) => candidateKey(candidate)).join("|");
+}
+
+/** 保存前重扫目录用的比较：只比 provider/model 联合键，与 pi-eyes 原判定一致 */
+export function sameCandidates(
+  left: readonly VisionCandidate[],
+  right: readonly VisionCandidate[],
+): boolean {
+  return candidateKeys(left) === candidateKeys(right);
+}
+
+export function routeSelectionValue(route: EyesRouteConfig): string {
+  if (route.allowedModels !== null && route.allowedModels.length === 0) return VALUE_OFF;
+  if (route.mode === "fixed" && route.fixedModel) {
+    return `${route.fixedModel.provider}${MODEL_VALUE_SEPARATOR}${route.fixedModel.model}`;
+  }
+  return VALUE_AUTO;
+}
+
+/** 选择器取值 → 路由补丁。auto 写 null 白名单，off 写空白名单，固定模型写 fixedModel */
+export function routePatchFor(value: string): Partial<EyesRouteConfig> | undefined {
+  if (value === VALUE_AUTO) return { mode: "automatic", allowedModels: null };
+  if (value === VALUE_OFF) return { mode: "automatic", allowedModels: [] };
+  const selection = parseModelValue(value);
+  return selection
+    ? {
+        mode: "fixed",
+        allowedModels: null,
+        fixedModel: { provider: selection.provider, model: selection.modelId },
+      }
+    : undefined;
+}
+
+/** 菜单行显示的当前视觉模型（不带 fixed 前缀，区别于只读路由行） */
+export function modelValueLabel(route: EyesRouteConfig, t: Translator): string {
+  if (route.allowedModels !== null && route.allowedModels.length === 0) {
+    return t("module.eyes.model.off");
+  }
+  if (route.mode === "fixed" && route.fixedModel) {
+    return `${route.fixedModel.provider}/${route.fixedModel.model}`;
+  }
+  return t("module.eyes.model.auto");
+}
+
+/** 当前路由实际会调用的模型；off 返回 undefined，auto 走 Pi 的自动选择规则 */
+export function resolveRouteCandidate(
+  route: EyesRouteConfig,
+  registry: VisionMenuRegistry,
+  currentModel?: { provider: string; id: string },
+): VisionSelection | undefined {
+  if (route.allowedModels !== null && route.allowedModels.length === 0) return undefined;
+  if (route.mode === "fixed" && route.fixedModel) {
+    return { provider: route.fixedModel.provider, modelId: route.fixedModel.model };
+  }
+  const allowed = route.allowedModels?.map((model) => ({ provider: model.provider, modelId: model.model })) ?? null;
+  const selection = selectAutomaticPiVisionModel(registry, {
+    allowedModels: allowed,
+    ...(currentModel ? { currentModel: { provider: currentModel.provider, modelId: currentModel.id } } : {}),
+  });
+  return selection ? { provider: selection.provider, modelId: selection.modelId } : undefined;
+}
+
+/** 诊断缓存键：目录版本 + 当前选择 + 候选清单 + 会话当前模型（与 pi-eyes 原键一致） */
+export function diagnosticCacheKey(options: {
+  readonly generation: number;
+  readonly route: EyesRouteConfig;
+  readonly candidates: readonly VisionCandidate[];
+  readonly currentModel?: { provider: string; id: string };
+}): string {
+  return [
+    options.generation,
+    routeSelectionValue(options.route),
+    candidateKeys(options.candidates),
+    options.currentModel
+      ? `${options.currentModel.provider}${MODEL_VALUE_SEPARATOR}${options.currentModel.id}`
+      : "no-current-model",
+  ].join("\n");
+}
+
+export interface ProbeOutcome {
+  readonly passed: boolean;
+  readonly matched: number;
+  readonly total: number;
+  readonly text: string;
+}
+
+/** 真实图片探测：发 6 格彩色格子图，6 格过 5 格判通过 */
+export async function probeVisionModel(
+  registry: VisionMenuRegistry,
+  selection: VisionSelection,
+  signal?: AbortSignal,
+): Promise<ProbeOutcome> {
+  const result = await testPiVisionModel(registry, selection, VISION_PROBE_IMAGE, VISION_PROBE_EXPECTED, {
+    ...(signal ? { signal } : {}),
+  });
+  return { passed: result.passed, matched: result.matched, total: result.total, text: result.text };
+}
+
+export interface SaveRouteResult {
+  readonly kind: "saved" | "modelsChanged" | "failed";
+  readonly route?: EyesRouteConfig;
+  readonly reason?: string;
+}
+
+/** 保存路由：先重扫目录，候选变了就中止；写盘走 02 的 saveEyesRoute，再让模块重载并刷新视觉链 */
+export async function saveRouteSelection(options: {
+  readonly value: string;
+  readonly openedWith: readonly VisionCandidate[];
+  readonly registry: VisionMenuRegistry;
+  readonly runtime: EyesMenuRuntime;
+  readonly context: ExtensionContext;
+  readonly agentDir?: string;
+}): Promise<SaveRouteResult> {
+  const patch = routePatchFor(options.value);
+  if (!patch) return { kind: "failed", reason: `unknown selection: ${options.value}` };
+
+  const latest = discoverCandidates(options.registry);
+  if (!sameCandidates(options.openedWith, latest)) return { kind: "modelsChanged" };
+
+  try {
+    await saveEyesRoute(patch, options.agentDir === undefined ? {} : { agentDir: options.agentDir });
+    const route = await options.runtime.reapply(options.context);
+    return { kind: "saved", route };
+  } catch (error) {
+    return { kind: "failed", reason: describeError(error) };
+  }
+}
+
+export interface SelfCheckResult {
+  readonly kind: "passed" | "failed" | "noRoute" | "noModel" | "cancelled";
+  readonly text: string;
+  readonly cached: boolean;
+}
+
+/** 运行自检：对当前生效路由发探测图，命中诊断缓存时直接回放，不重复请求 */
+export async function runVisionSelfCheck(options: {
+  readonly t: Translator;
+  readonly registry: VisionMenuRegistry;
+  readonly runtime: EyesMenuRuntime;
+  readonly context: ExtensionContext;
+  readonly route: EyesRouteConfig;
+  readonly candidates: readonly VisionCandidate[];
+  readonly signal?: AbortSignal;
+}): Promise<SelfCheckResult> {
+  const { t, registry, runtime } = options;
+  if (options.route.allowedModels !== null && options.route.allowedModels.length === 0) {
+    return { kind: "noRoute", text: t("module.eyes.check.noRoute"), cached: false };
+  }
+
+  const currentModel = options.context.model
+    ? { provider: options.context.model.provider, id: options.context.model.id }
+    : undefined;
+  const key = diagnosticCacheKey({
+    generation: runtime.catalogueGeneration(),
+    route: options.route,
+    candidates: options.candidates,
+    ...(currentModel ? { currentModel } : {}),
+  });
+
+  const cached = runtime.diagnostic();
+  if (cached?.key === key) {
+    return cached.passed
+      ? { kind: "passed", text: t("module.eyes.check.passed", { elapsed: cached.elapsedMs }), cached: true }
+      : { kind: "failed", text: t("module.eyes.check.failed", { reason: cached.detail }), cached: true };
+  }
+
+  const selection = resolveRouteCandidate(options.route, registry, currentModel);
+  if (!selection) {
+    runtime.setDiagnostic({ key, passed: false, elapsedMs: 0, detail: "" });
+    return { kind: "noModel", text: t("module.eyes.check.noModel"), cached: false };
+  }
+
+  const startedAt = Date.now();
+  try {
+    const probe = await probeVisionModel(registry, selection, options.signal);
+    if (options.signal?.aborted) {
+      return { kind: "cancelled", text: t("module.eyes.cancelled"), cached: false };
+    }
+    const elapsedMs = Date.now() - startedAt;
+    const detail = singleLine(probe.text || (probe.passed ? "OK" : "unknown error"));
+    runtime.setDiagnostic({ key, passed: probe.passed, elapsedMs, detail });
+    return probe.passed
+      ? { kind: "passed", text: t("module.eyes.check.passed", { elapsed: elapsedMs }), cached: false }
+      : { kind: "failed", text: t("module.eyes.check.failed", { reason: detail }), cached: false };
+  } catch (error) {
+    if (options.signal?.aborted) {
+      return { kind: "cancelled", text: t("module.eyes.cancelled"), cached: false };
+    }
+    const elapsedMs = Date.now() - startedAt;
+    const detail = singleLine(describeError(error));
+    runtime.setDiagnostic({ key, passed: false, elapsedMs, detail });
+    return { kind: "failed", text: t("module.eyes.check.failed", { reason: detail }), cached: false };
+  }
+}
+
+export interface RefreshResult {
+  readonly kind: "ok" | "cancelled" | "failed";
+  readonly reason?: string;
+}
+
+/** 重读 Pi 的模型目录（不联网）；provider 报错时把细节带出来 */
+export async function refreshVisionCatalogue(
+  registry: VisionMenuRegistry,
+  signal?: AbortSignal,
+): Promise<RefreshResult> {
+  try {
+    const result = await registry.refresh({ allowNetwork: false, ...(signal ? { signal } : {}) });
+    if (result.aborted || signal?.aborted) return { kind: "cancelled" };
+    if (result.errors.size > 0) {
+      const detail = [...result.errors.entries()]
+        .map(([provider, error]) => `${provider}: ${error.message}`)
+        .join("; ");
+      return { kind: "failed", reason: detail };
+    }
+    return { kind: "ok" };
+  } catch (error) {
+    if (signal?.aborted) return { kind: "cancelled" };
+    return { kind: "failed", reason: describeError(error) };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// UI：取消控制器 + 状态面板 + 模型选择器 + 主面板
+// ─────────────────────────────────────────────────────────────
+
+type StatusColor = "dim" | "warning" | "success" | "error";
+type StatusSetter = (text: string, color: StatusColor, running?: boolean) => void;
+
+interface Cancellable {
+  readonly signal: AbortSignal;
+  abort(reason?: unknown): void;
+  dispose(): void;
+}
+
+/** 自己的 AbortController，并把会话的 ctx.signal 一起接进来；Esc / 卸载时都从这里断路 */
+function startCancellable(parent: AbortSignal | undefined): Cancellable {
+  const controller = new AbortController();
+  const forward = (): void => controller.abort(parent?.reason);
+  if (parent?.aborted) forward();
+  else parent?.addEventListener("abort", forward, { once: true });
+  return {
+    signal: controller.signal,
+    abort: (reason) => controller.abort(reason),
+    dispose: () => parent?.removeEventListener("abort", forward),
+  };
+}
+
+interface PanelEnv {
+  readonly t: Translator;
+  readonly theme: MenuTheme;
+  readonly context: ExtensionContext;
+  /** pi 配置目录：写盘目标 */
+  readonly agentDir: string;
+  readonly runtime: EyesMenuRuntime;
+  readonly requestRender: () => void;
+}
+
+export interface EyesStatusPanelOptions extends PanelEnv {
+  readonly title: string;
+  readonly hint: string;
+  readonly onClose: () => void;
+  readonly onResult?: (text: string) => void;
+  readonly run: (signal: AbortSignal, setStatus: StatusSetter) => Promise<void>;
+}
+
+/** 一次异步动作的展示面板：运行中显示进度，结束后显示结果，Esc 取消或返回 */
+export class EyesStatusPanel extends Container {
+  private readonly options: EyesStatusPanelOptions;
+  private readonly controller: Cancellable;
+  private readonly body: Text;
+  private token = 0;
+  private running = true;
+
+  constructor(options: EyesStatusPanelOptions) {
+    super();
+    this.options = options;
+    this.controller = startCancellable(options.context.signal);
+    this.addChild(new Text(options.theme.title(options.title), 1, 0));
+    this.body = new Text(options.theme.fg("warning", `  ${options.t("module.eyes.running")}`), 1, 0);
+    this.addChild(this.body);
+    this.addChild(new Text(options.theme.hint(options.hint), 1, 0));
+    void this.start();
+  }
+
+  handleInput(data: string): void {
+    if (!matchesKey(data, Key.escape)) return;
+    if (this.running) {
+      this.cancel();
+      return;
+    }
+    this.options.onClose();
+  }
+
+  dispose(): void {
+    this.token += 1;
+    this.controller.dispose();
+    this.controller.abort(new DOMException("Disposed", "AbortError"));
+  }
+
+  private async start(): Promise<void> {
+    const token = ++this.token;
+    const setStatus: StatusSetter = (text, color, running = false) => {
+      if (token !== this.token) return;
+      this.running = running;
+      this.body.setText(this.options.theme.fg(color, `  ${text}`));
+      if (!running) this.options.onResult?.(text);
+      this.options.requestRender();
+    };
+    try {
+      await this.options.run(this.controller.signal, setStatus);
+    } catch (error) {
+      setStatus(singleLine(describeError(error)), "error");
+    } finally {
+      if (token === this.token) {
+        this.running = false;
+        this.controller.dispose();
+        this.options.requestRender();
+      }
+    }
+  }
+
+  private cancel(): void {
+    this.token += 1;
+    this.running = false;
+    this.controller.abort(new DOMException("Cancelled", "AbortError"));
+    this.body.setText(this.options.theme.fg("dim", `  ${this.options.t("module.eyes.cancelled")}`));
+    this.options.requestRender();
+  }
+}
+
+export interface VisionModelPickerOptions extends PanelEnv {
+  readonly selection: EyesRouteConfig;
+  readonly candidates: readonly VisionCandidate[];
+  readonly onSaved: () => void;
+  readonly onDone: (value?: string) => void;
+}
+
+/** 视觉模型选择器：SelectList 形态；选具体模型先探测，auto / off 直接写盘 */
+export class VisionModelPicker extends Container {
+  private readonly options: VisionModelPickerOptions;
+  private readonly initialValue: string;
+  private readonly list: SelectList;
+  private readonly controller: Cancellable;
+  private token = 0;
+  /** picking：选择列表；busy：探测/保存中（Esc 取消）；settled：结果显示中（Esc 返回） */
+  private phase: "picking" | "busy" | "settled" = "picking";
+
+  constructor(options: VisionModelPickerOptions) {
+    super();
+    this.options = options;
+    this.initialValue = routeSelectionValue(options.selection);
+    this.controller = startCancellable(options.context.signal);
+
+    this.addChild(new Text(options.theme.title(options.t("module.eyes.model.label")), 1, 0));
+    const items = this.buildItems();
+    const currentIndex = items.findIndex((item) => item.value === this.initialValue);
+    this.list = new SelectList(items, Math.min(items.length, 10), options.theme.select);
+    if (currentIndex > 0) this.list.setSelectedIndex(currentIndex);
+    this.list.onSelect = (item) => {
+      void this.choose(item.value);
+    };
+    this.list.onCancel = () => this.options.onDone();
+    this.addChild(this.list);
+    if (options.candidates.length === 0) {
+      this.addChild(new Text(options.theme.fg("warning", `  ${options.t("module.eyes.model.empty")}`), 1, 0));
+    }
+    this.addChild(new Text(options.theme.hint(options.t("hint.chooseOptions")), 1, 0));
+  }
+
+  handleInput(data: string): void {
+    if (this.phase === "picking") {
+      this.list.handleInput(data);
+      return;
+    }
+    if (!matchesKey(data, Key.escape)) return;
+    if (this.phase === "busy") {
+      this.token += 1;
+      this.controller.abort(new DOMException("Cancelled", "AbortError"));
+      this.showStatus(this.options.t("module.eyes.cancelled"), "dim", "settled");
+      return;
+    }
+    this.options.onDone();
+  }
+
+  dispose(): void {
+    this.token += 1;
+    this.controller.dispose();
+    this.controller.abort(new DOMException("Disposed", "AbortError"));
+  }
+
+  private buildItems(): SelectItem[] {
+    const t = this.options.t;
+    const items: SelectItem[] = [
+      {
+        value: VALUE_AUTO,
+        label: t("module.eyes.model.auto"),
+        description: t("module.eyes.model.autoDescription"),
+      },
+      {
+        value: VALUE_OFF,
+        label: t("module.eyes.model.off"),
+        description: t("module.eyes.model.offDescription"),
+      },
+    ];
+    const unavailable = isModelValue(this.initialValue)
+      && !this.options.candidates.some((candidate) => candidateKey(candidate) === this.initialValue);
+    if (unavailable) {
+      const selection = parseModelValue(this.initialValue);
+      if (selection) {
+        items.push({
+          value: this.initialValue,
+          label: `${selection.provider}/${selection.modelId}`,
+          description: t("module.eyes.model.unavailable"),
+        });
+      }
+    }
+    for (const candidate of this.options.candidates) {
+      items.push({
+        value: candidateKey(candidate),
+        label: `${candidate.provider}/${candidate.modelId}`,
+        description: candidate.authenticated
+          ? t("module.eyes.model.authenticated")
+          : t("module.eyes.model.noAuthRequired"),
+      });
+    }
+    return items;
+  }
+
+  private async choose(value: string): Promise<void> {
+    if (value === this.initialValue) {
+      this.options.onDone();
+      return;
+    }
+    const token = ++this.token;
+    const t = this.options.t;
+
+    if (isModelValue(value)) {
+      const selection = parseModelValue(value);
+      if (!selection) return;
+      const model = `${selection.provider}/${selection.modelId}`;
+      this.showStatus(t("module.eyes.probe.running", { model }), "warning", "busy");
+      let probe: ProbeOutcome;
+      try {
+        probe = await probeVisionModel(this.options.context.modelRegistry, selection, this.controller.signal);
+      } catch (error) {
+        if (this.token !== token) return;
+        if (this.controller.signal.aborted) {
+          this.showStatus(t("module.eyes.cancelled"), "dim", "settled");
+          return;
+        }
+        this.showStatus(`${t("module.eyes.probe.failed", {
+          model,
+          matched: 0,
+          total: VISION_PROBE_EXPECTED.length,
+          reason: singleLine(describeError(error)),
+        })} ${t("module.eyes.probe.unchanged")}`, "error", "settled");
+        return;
+      }
+      if (this.token !== token) return;
+      if (this.controller.signal.aborted) {
+        this.showStatus(t("module.eyes.cancelled"), "dim", "settled");
+        return;
+      }
+      if (!probe.passed) {
+        this.showStatus(`${t("module.eyes.probe.failed", {
+          model,
+          matched: probe.matched,
+          total: probe.total,
+          reason: singleLine(probe.text),
+        })} ${t("module.eyes.probe.unchanged")}`, "error", "settled");
+        return;
+      }
+      this.showStatus(t("module.eyes.probe.passed", {
+        model,
+        matched: probe.matched,
+        total: probe.total,
+        response: singleLine(probe.text),
+      }), "success", "busy");
+    }
+
+    await this.save(value, token);
+  }
+
+  private async save(value: string, token: number): Promise<void> {
+    const t = this.options.t;
+    this.showStatus(t("module.eyes.save.running"), "warning", "busy");
+    const result = await saveRouteSelection({
+      value,
+      openedWith: this.options.candidates,
+      registry: this.options.context.modelRegistry,
+      runtime: this.options.runtime,
+      context: this.options.context,
+      agentDir: this.options.agentDir,
+    });
+    if (this.token !== token) return;
+    if (result.kind === "modelsChanged") {
+      this.showStatus(t("module.eyes.save.modelsChanged"), "error", "settled");
+      return;
+    }
+    if (result.kind === "failed" || !result.route) {
+      this.showStatus(`${t("module.eyes.save.failed", {
+        reason: result.reason ?? "",
+      })} ${t("module.eyes.probe.unchanged")}`, "error", "settled");
+      return;
+    }
+    this.options.onSaved();
+    this.options.onDone(modelValueLabel(result.route, t));
+  }
+
+  private showStatus(text: string, color: StatusColor, phase: "busy" | "settled"): void {
+    this.phase = phase;
+    this.clear();
+    this.addChild(new Text(this.options.theme.title(this.options.t("module.eyes.model.label")), 1, 0));
+    this.addChild(new Text(this.options.theme.fg(color, `  ${text}`), 1, 0));
+    this.addChild(new Text(
+      this.options.theme.hint(this.options.t(phase === "busy" ? "hint.cancel" : "hint.back")),
+      1,
+      0,
+    ));
+    this.options.requestRender();
+  }
+}
+
+export interface EyesVisionPanelOptions extends PanelEnv {
+  readonly onDone: (value: string) => void;
+}
+
+/** 视觉配置页：四行 SettingsList，子菜单各自负责自己的异步动作 */
+export class EyesVisionPanel extends Container {
+  private readonly options: EyesVisionPanelOptions;
+  private list: I18nSettingsList | undefined;
+  private candidates: VisionCandidate[];
+  private checkValue: string | undefined;
+
+  constructor(options: EyesVisionPanelOptions) {
+    super();
+    this.options = options;
+    this.candidates = discoverCandidates(options.context.modelRegistry);
+    this.addChild(new Text(options.theme.title(options.t("module.eyes.menu.label")), 1, 0));
+    this.list = new I18nSettingsList({
+      items: this.buildItems(),
+      maxVisible: 8,
+      theme: options.theme.settings,
+      t: options.t,
+      onChange: (id) => {
+        if (id === ROW_MODEL) this.refreshRows();
+      },
+      onCancel: () => this.close(),
+    });
+    this.addChild(this.list);
+  }
+
+  handleInput(data: string): void {
+    this.list?.handleInput(data);
+  }
+
+  private close(): void {
+    this.options.onDone(describeRoute(this.options.runtime.globalRoute(), this.options.t));
+  }
+
+  private refreshRows(): void {
+    const route = this.options.runtime.globalRoute();
+    this.list?.updateValue(ROW_MODEL, modelValueLabel(route, this.options.t));
+    this.list?.updateValue(ROW_ROUTE, describeRoute(route, this.options.t));
+    this.list?.updateValue(ROW_REFRESH, this.refreshValue());
+    if (this.checkValue) this.list?.updateValue(ROW_CHECK, this.checkValue);
+    this.options.requestRender();
+  }
+
+  private refreshValue(): string {
+    return this.options.t("module.eyes.refresh.value", { count: this.candidates.length });
+  }
+
+  private buildItems(): SettingItem[] {
+    const t = this.options.t;
+    const route = this.options.runtime.globalRoute();
+    return [
+      {
+        id: ROW_MODEL,
+        label: t("module.eyes.model.label"),
+        description: t("module.eyes.model.description"),
+        currentValue: modelValueLabel(route, t),
+        submenu: (_currentValue, done) =>
+          new VisionModelPicker({
+            ...this.options,
+            selection: this.options.runtime.globalRoute(),
+            candidates: this.candidates,
+            onSaved: () => this.refreshRows(),
+            onDone: done,
+          }),
+      },
+      {
+        id: ROW_REFRESH,
+        label: t("module.eyes.refresh.label"),
+        description: t("module.eyes.refresh.description"),
+        currentValue: this.refreshValue(),
+        submenu: (_currentValue, done) =>
+          new EyesStatusPanel({
+            ...this.options,
+            title: t("module.eyes.refresh.label"),
+            hint: t("hint.back"),
+            onClose: () => done(),
+            run: async (signal, setStatus) => {
+              setStatus(t("module.eyes.refresh.running"), "warning", true);
+              const result = await refreshVisionCatalogue(this.options.context.modelRegistry, signal);
+              if (signal.aborted) {
+                setStatus(t("module.eyes.cancelled"), "dim");
+                return;
+              }
+              if (result.kind === "ok") {
+                this.options.runtime.bumpCatalogueGeneration();
+                this.candidates = discoverCandidates(this.options.context.modelRegistry);
+                setStatus(t("module.eyes.refresh.complete"), "success");
+                this.refreshRows();
+                return;
+              }
+              if (result.kind === "cancelled") {
+                setStatus(t("module.eyes.cancelled"), "dim");
+                return;
+              }
+              setStatus(t("module.eyes.refresh.failed", { reason: result.reason ?? "" }), "error");
+            },
+          }),
+      },
+      {
+        id: ROW_CHECK,
+        label: t("module.eyes.check.label"),
+        description: t("module.eyes.check.description"),
+        currentValue: this.checkValue ?? t("module.eyes.check.value"),
+        submenu: (_currentValue, done) =>
+          new EyesStatusPanel({
+            ...this.options,
+            title: t("module.eyes.check.label"),
+            hint: t("hint.back"),
+            onClose: () => done(),
+            onResult: (text) => {
+              this.checkValue = text;
+              this.list?.updateValue(ROW_CHECK, text);
+            },
+            run: async (signal, setStatus) => {
+              setStatus(t("module.eyes.check.running"), "warning", true);
+              const result = await runVisionSelfCheck({
+                t,
+                registry: this.options.context.modelRegistry,
+                runtime: this.options.runtime,
+                context: this.options.context,
+                route: this.options.runtime.globalRoute(),
+                candidates: this.candidates,
+                signal,
+              });
+              setStatus(result.text, result.kind === "passed" ? "success" : result.kind === "cancelled" ? "dim" : "error");
+            },
+          }),
+      },
+      {
+        id: ROW_ROUTE,
+        label: t("module.eyes.route.label"),
+        description: t("module.eyes.route.description"),
+        currentValue: describeRoute(route, t),
+      },
+    ];
+  }
+}
+
+/** 模块的菜单行：一行入口，进去是四行视觉配置页 */
+export function buildEyesMenuItems(
+  context: ModuleMenuContext,
+  runtime: EyesMenuRuntime,
+): readonly SettingItem[] {
+  const t = context.t;
+  return [
+    {
+      id: EYES_MENU_ITEM_ID,
+      label: t("module.eyes.menu.label"),
+      description: t("module.eyes.menu.description"),
+      currentValue: describeRoute(runtime.globalRoute(), t),
+      submenu: (_currentValue, done) =>
+        new EyesVisionPanel({
+          t,
+          theme: context.theme,
+          context: context.context,
+          agentDir: context.agentDir,
+          runtime,
+          requestRender: () => context.requestRender(),
+          onDone: (value) => done(value),
+        }),
+    },
+  ];
+}