@buyi1net/pi-toolkit 0.0.1

package/modules/eyes/pi-model-backend.ts

@@ -0,0 +1,245 @@
+// Pi 视觉模型发现、通用调用与显式能力测试。
+// 所有调用都经 Pi 原生 modelRegistry.complete()，本模块不读取凭证、不自行构造 HTTP 请求。
+// 模型对象类型从 ModelRegistry 的方法签名推导，避免直接 import pi-ai（本包只声明 pi 宿主 peer）。
+
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+
+/** pi 的模型对象（Model<Api>），由注册表签名推导 */
+export type PiVisionModel = NonNullable<ReturnType<ModelRegistry["find"]>>;
+
+export interface PiVisionModelSelection {
+  provider: string;
+  modelId: string;
+}
+
+export interface PiVisionImage {
+  data: string;
+  mediaType: string;
+}
+
+export interface PiVisionModelCandidate extends PiVisionModelSelection {
+  name: string;
+  api: string;
+  available: boolean;
+  auth: {
+    configured: boolean;
+    source?: string;
+    label?: string;
+  };
+}
+
+export interface PiVisionCallOptions {
+  signal?: AbortSignal;
+  maxTokens?: number;
+  systemPrompt?: string;
+}
+
+export interface AutomaticPiVisionModelOptions {
+  currentModel?: PiVisionModelSelection;
+  allowedModels?: readonly PiVisionModelSelection[] | null;
+  excludedModels?: ReadonlySet<string>;
+}
+
+export interface PiVisionProbeResult {
+  passed: boolean;
+  matched: number;
+  total: number;
+  answers: string[];
+  text: string;
+}
+
+export type PiVisionModelRegistry = Pick<
+  ModelRegistry,
+  "getAll" | "getAvailable" | "find" | "getProviderAuthStatus" | "complete"
+>;
+
+export function piVisionModelKey(provider: string, modelId: string): string {
+  return `${provider}\0${modelId}`;
+}
+
+/** 列出全部声明支持图片的模型，并分别保留认证与当前可用状态。 */
+export function discoverPiVisionModels(registry: PiVisionModelRegistry): PiVisionModelCandidate[] {
+  const available = new Set(registry.getAvailable().map((model) => piVisionModelKey(model.provider, model.id)));
+  return registry.getAll()
+    .filter((model) => model.input.includes("image"))
+    .map((model) => {
+      const auth = registry.getProviderAuthStatus(model.provider);
+      return {
+        provider: model.provider,
+        modelId: model.id,
+        name: model.name,
+        api: model.api,
+        available: available.has(piVisionModelKey(model.provider, model.id)),
+        auth: {
+          configured: auth.configured,
+          ...(auth.source ? { source: auth.source } : {}),
+          ...(auth.label ? { label: auth.label } : {}),
+        },
+      };
+    });
+}
+
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/** 从 Pi 当前可用的图片模型中按稳定规则选择一个，不发起模型调用。 */
+export function selectAutomaticPiVisionModel(
+  registry: PiVisionModelRegistry,
+  options: AutomaticPiVisionModelOptions = {},
+): PiVisionModelSelection | undefined {
+  const allowed = options.allowedModels === null || options.allowedModels === undefined
+    ? undefined
+    : new Set(options.allowedModels.map((model) => piVisionModelKey(model.provider, model.modelId)));
+  const seen = new Set<string>();
+  const candidates = registry.getAvailable()
+    .filter((model) => model.input.includes("image"))
+    .filter((model) => {
+      const key = piVisionModelKey(model.provider, model.id);
+      if (seen.has(key) || options.excludedModels?.has(key) || (allowed && !allowed.has(key))) return false;
+      seen.add(key);
+      return true;
+    })
+    .map((model) => ({ provider: model.provider, modelId: model.id }));
+
+  const currentKey = options.currentModel
+    ? piVisionModelKey(options.currentModel.provider, options.currentModel.modelId)
+    : undefined;
+  candidates.sort((left, right) => {
+    const leftKey = piVisionModelKey(left.provider, left.modelId);
+    const rightKey = piVisionModelKey(right.provider, right.modelId);
+    if (currentKey) {
+      if (leftKey === currentKey && rightKey !== currentKey) return -1;
+      if (rightKey === currentKey && leftKey !== currentKey) return 1;
+      const leftSameProvider = left.provider === options.currentModel!.provider;
+      const rightSameProvider = right.provider === options.currentModel!.provider;
+      if (leftSameProvider !== rightSameProvider) return leftSameProvider ? -1 : 1;
+    }
+    return compareText(`${left.provider}/${left.modelId}`, `${right.provider}/${right.modelId}`);
+  });
+  return candidates[0];
+}
+
+/** 只按 provider 与 modelId 联合键查找，不用显示名或模糊匹配。 */
+export function resolvePiVisionModel(
+  registry: PiVisionModelRegistry,
+  selection: PiVisionModelSelection,
+): PiVisionModel | undefined {
+  const model = registry.find(selection.provider, selection.modelId);
+  return model?.input.includes("image") ? model : undefined;
+}
+
+function abortError(message: string): Error {
+  const error = new Error(message);
+  error.name = "AbortError";
+  return error;
+}
+
+/** 经 Pi 原生 provider 调度发送图片，不读取凭证，也不自行构造 HTTP 请求。 */
+export async function callPiVisionModel(
+  registry: PiVisionModelRegistry,
+  selection: PiVisionModelSelection,
+  prompt: string,
+  images: PiVisionImage[],
+  options: PiVisionCallOptions = {},
+): Promise<string> {
+  options.signal?.throwIfAborted();
+  const model = resolvePiVisionModel(registry, selection);
+  if (!model) {
+    throw new Error(`Pi 视觉模型不可用：${selection.provider}/${selection.modelId}`);
+  }
+  if (images.length === 0) throw new Error("调用 Pi 视觉模型时至少需要一张图片");
+  const maxTokens = Math.min(options.maxTokens ?? model.maxTokens, model.maxTokens);
+
+  const result = await registry.complete(
+    model,
+    {
+      ...(options.systemPrompt ? { systemPrompt: options.systemPrompt } : {}),
+      messages: [{
+        role: "user",
+        timestamp: Date.now(),
+        content: [
+          ...images.map((image) => ({ type: "image" as const, data: image.data, mimeType: image.mediaType })),
+          { type: "text" as const, text: prompt },
+        ],
+      }],
+    },
+    {
+      ...(options.signal ? { signal: options.signal } : {}),
+      maxTokens,
+    },
+  );
+
+  if (result.stopReason === "aborted") {
+    throw abortError(result.errorMessage || "Pi 视觉模型请求已取消");
+  }
+  if (result.stopReason === "error") {
+    throw new Error(result.errorMessage || `Pi 视觉模型请求失败：${selection.provider}/${selection.modelId}`);
+  }
+  if (result.errorMessage) throw new Error(result.errorMessage);
+
+  const text = result.content
+    .filter((block): block is Extract<typeof block, { type: "text" }> => block.type === "text")
+    .map((block) => block.text)
+    .join("\n")
+    .trim();
+  if (!text) throw new Error(`Pi 视觉模型未返回文本：${selection.provider}/${selection.modelId}`);
+  return text;
+}
+
+function normalizeProbeValue(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function parseProbeAnswers(text: string): string[] {
+  const trimmed = text.trim();
+  const start = trimmed.indexOf("[");
+  const end = trimmed.lastIndexOf("]");
+  if (start < 0 || end <= start) return [];
+  try {
+    const parsed = JSON.parse(trimmed.slice(start, end + 1));
+    return Array.isArray(parsed) && parsed.every((value) => typeof value === "string")
+      ? parsed.map(normalizeProbeValue)
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+export function evaluatePiVisionProbe(text: string, expected: readonly string[]): PiVisionProbeResult {
+  const normalizedExpected = expected.map(normalizeProbeValue);
+  const answers = parseProbeAnswers(text);
+  const matched = normalizedExpected.reduce(
+    (count, value, index) => count + (answers[index] === value ? 1 : 0),
+    0,
+  );
+  const total = normalizedExpected.length;
+  const threshold = total === 0 ? 1 : Math.ceil(total * 5 / 6);
+  return { passed: total > 0 && matched >= threshold, matched, total, answers, text };
+}
+
+export function buildPiVisionProbePrompt(expected: readonly string[]): string {
+  if (expected.length === 0) throw new Error("Pi 视觉模型测试至少需要一个预期值");
+  // 排序后再放进提示，避免候选标签的排列意外泄露测试图答案。
+  const labels = [...new Set(expected.map(normalizeProbeValue))].sort();
+  return (
+    `The image contains ${expected.length} colored cells. Read them from left to right, then top to bottom. ` +
+    `Use only these labels: ${labels.join(", ")}. Return only one JSON array with ${expected.length} strings.`
+  );
+}
+
+/** 仅在调用方明确触发时，使用调用方提供的测试图验证模型是否真正能看图。 */
+export async function testPiVisionModel(
+  registry: PiVisionModelRegistry,
+  selection: PiVisionModelSelection,
+  image: PiVisionImage,
+  expected: readonly string[],
+  options: PiVisionCallOptions = {},
+): Promise<PiVisionProbeResult> {
+  const prompt = buildPiVisionProbePrompt(expected);
+  const text = await callPiVisionModel(registry, selection, prompt, [image], {
+    ...options,
+    maxTokens: options.maxTokens ?? 128,
+  });
+  return evaluatePiVisionProbe(text, expected);
+}

package/modules/eyes/resilience.ts

@@ -0,0 +1,161 @@
+// 视觉后端失败分类与熔断。
+// 思路移植自 dsh-vision-router/lib/vision-resilience.js(MIT),按 pi 扩展环境精简:
+// 保留"分类 → 决定换后端还是熔断 → 本轮全失败短路"三层,去掉凭证指纹与多会话 scope。
+
+export type FailureKind =
+  | "AUTH"
+  | "RATE_LIMIT"
+  | "TIMEOUT"
+  | "SERVER"
+  | "INVALID_REQUEST"
+  | "NETWORK"
+  | "QUOTA"
+  | "OTHER";
+
+export interface BackendFailure {
+  kind: FailureKind;
+  retryAfterMs?: number;
+}
+
+// 分类正则沿用 dsh 调教过的集合与顺序:先确定性失败,后环境性失败
+const AUTH_PATTERNS = [/\b401\b/, /\b403\b/, /unauthorized/i, /invalid api[ -]?key/i, /forbidden/i, /authentication/i];
+const RATE_LIMIT_PATTERNS = [/\b429\b/, /rate.?limit/i, /too many requests/i];
+const TIMEOUT_PATTERNS = [/abort/i, /timeout/i, /etimedout/i, /timed ?out/i, /deadline exceeded/i];
+const SERVER_PATTERNS = [/\b500\b/, /\b502\b/, /\b503\b/, /\b504\b/, /bad gateway/i, /service unavailable/i];
+const INVALID_REQUEST_PATTERNS = [/\b400\b/, /\b404\b/, /\b413\b/, /\b422\b/, /invalid request/i, /does not support image/i, /invalid model/i, /no such model/i, /model not exist/i, /request body/i];
+const NETWORK_PATTERNS = [/econn/i, /enotfound/i, /network/i, /fetch failed/i, /socket/i, /connection reset/i, /dns/i];
+const QUOTA_PATTERNS = [/\b402\b/, /insufficient/i, /balance/i, /credits/i];
+
+const KIND_BY_PATTERN: Array<[FailureKind, RegExp[]]> = [
+  ["AUTH", AUTH_PATTERNS],
+  ["RATE_LIMIT", RATE_LIMIT_PATTERNS],
+  ["TIMEOUT", TIMEOUT_PATTERNS],
+  ["SERVER", SERVER_PATTERNS],
+  ["INVALID_REQUEST", INVALID_REQUEST_PATTERNS],
+  ["NETWORK", NETWORK_PATTERNS],
+  ["QUOTA", QUOTA_PATTERNS],
+];
+
+/** HTTP 状态码优先于报错文本分类。 */
+export function kindForStatus(status: number | undefined): FailureKind | undefined {
+  if (status === 401 || status === 403) return "AUTH";
+  if (status === 429) return "RATE_LIMIT";
+  if (status === 402) return "QUOTA";
+  if (status === 400 || status === 404 || status === 413 || status === 422) return "INVALID_REQUEST";
+  if (status !== undefined && status >= 500 && status <= 599) return "SERVER";
+  return undefined;
+}
+
+export function classifyFailure(error: { status?: number; message: string; retryAfterMs?: number }): BackendFailure {
+  let kind = kindForStatus(error.status);
+  if (kind === undefined) {
+    kind =
+      KIND_BY_PATTERN.find(([, patterns]) => patterns.some((p) => p.test(error.message)))?.[0] ?? "OTHER";
+  }
+  return { kind, retryAfterMs: error.retryAfterMs };
+}
+
+/** per-backend 熔断器:认证类熔断 10 分钟,限频按 Retry-After 冷却。 */
+const AUTH_TRIP_MS = 10 * 60 * 1000;
+const DEFAULT_RATE_COOLDOWN_MS = 60 * 1000;
+
+export class VisionCircuit {
+  private backends = new Map<string, { authUntil?: number; cooldownUntil?: number }>();
+
+  inspect(id: string, _turn: number, now = Date.now()): { blocked: boolean; reason?: string } {
+    const hit = this.backends.get(id);
+    if (!hit) return { blocked: false };
+    if (hit.cooldownUntil !== undefined && hit.cooldownUntil > now) {
+      return { blocked: true, reason: "rate-limit cooldown" };
+    }
+    if (hit.authUntil !== undefined && hit.authUntil > now) {
+      return { blocked: true, reason: "auth failure cooldown" };
+    }
+    return { blocked: false };
+  }
+
+  record(id: string, failure: BackendFailure, _turn: number, now = Date.now()): void {
+    const hit = this.backends.get(id) ?? {};
+    this.backends.set(id, hit);
+    if (failure.kind === "AUTH" || failure.kind === "QUOTA") {
+      hit.authUntil = now + AUTH_TRIP_MS;
+      return;
+    }
+    if (failure.kind === "RATE_LIMIT") {
+      const cooldown = failure.retryAfterMs ?? DEFAULT_RATE_COOLDOWN_MS;
+      hit.cooldownUntil = Math.max(hit.cooldownUntil ?? 0, now + cooldown);
+      return;
+    }
+    // INVALID_REQUEST / TIMEOUT / SERVER / NETWORK / OTHER 不熔断：
+    // 调用方可能修正图片、参数或请求体后再次使用同一后端。
+  }
+
+  clear(id: string): void {
+    this.backends.delete(id);
+  }
+}
+
+/** 本轮失败记忆:全部后端都失败后,后续调用不再碰网络。 */
+export class TurnMemory {
+  private turn = 0;
+  private failedAll = false;
+  private attempted: string[] = [];
+
+  newTurn(turn: number): void {
+    this.turn = turn;
+    this.failedAll = false;
+    this.attempted = [];
+  }
+
+  get currentTurn(): number {
+    return this.turn;
+  }
+
+  get allFailed(): boolean {
+    return this.failedAll;
+  }
+
+  recordAttempt(entry: string): void {
+    this.attempted.push(entry);
+  }
+
+  get attempts(): string[] {
+    return [...this.attempted];
+  }
+
+  markAllFailed(): void {
+    this.failedAll = true;
+  }
+}
+
+export const DO_NOT_RETRY_ADVICE =
+  "Vision backends are unavailable for this turn (auth failure, rate limit, timeout or outage). " +
+  "Do NOT call backend-dependent vision tools again this turn with only a reworded question — rephrasing cannot fix an " +
+  "auth, rate-limit or infrastructure failure. Answer from the information you already have and " +
+  "continue the text task; local-only tools such as crop, colors, pixel diff, foreground extraction, trace, " +
+  "HTML screenshot and Tesseract OCR may still work. Tell the user the remote vision backend is temporarily unavailable.";
+
+const CORRECT_REQUEST_ADVICE =
+  "The backend rejected this request as invalid or too large. Correct the image path, format, count, size, " +
+  "or tool parameters before retrying; do not retry the identical request.";
+
+const CODE_FOR_ONLY_KIND: Partial<Record<FailureKind, string>> = {
+  AUTH: "VISION_AUTH_FAILED",
+  RATE_LIMIT: "VISION_RATE_LIMITED",
+  TIMEOUT: "VISION_TIMEOUT",
+};
+
+/** 组结构化失败 JSON:工具描述里的 FAILURE SEMANTICS 承诺的就是这个形状。 */
+export function buildFailureJson(kinds: FailureKind[], attempted: string[]): string {
+  const set = new Set(kinds);
+  const correctable = set.has("INVALID_REQUEST");
+  const code =
+    set.size === 1 ? CODE_FOR_ONLY_KIND[[...set][0]] ?? "VISION_BACKEND_UNAVAILABLE" : "VISION_BACKEND_UNAVAILABLE";
+  return JSON.stringify({
+    ok: false,
+    code,
+    retryable: correctable,
+    reason: correctable ? CORRECT_REQUEST_ADVICE : DO_NOT_RETRY_ADVICE,
+    attemptedBackends: attempted,
+  });
+}

package/modules/eyes/vision-bridge.ts

@@ -0,0 +1,232 @@
+// 视觉桥：收集消息里的图片、保存最近一张截图、调用辅助视觉模型并把结构化视觉笔记注入上下文。
+// 文案（注入告警、询问失败说明）全部走 pi-toolkit 三语键表；纯文本模型才走注入，原生多模态模型旁路。
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Translator } from "../../i18n.ts";
+import { VisionChain, type VisionAnswer } from "./chain.ts";
+import { imageHash, noteKey, VisionNoteCache } from "./vision-cache.ts";
+import { contextBlock, formatNote, isStructuredVisionResponse, neutralizeVisionDelimiters, notePrompt } from "./vision-prompt.ts";
+import {
+  describeVisionImageError,
+  isSharpMissingError,
+  prepareVisionImages,
+} from "./vision-preprocess.ts";
+import type { VisionImage, VisionMessages, VisionNote, VisionResource } from "./vision-types.ts";
+
+const CONTEXT_START = "<vision-context>";
+const CONTEXT_END = "</vision-context>";
+const TASK_DEADLINE_MS = 120_000;
+const PER_CALL_MS = 120_000;
+
+function contentText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((block: any) => block?.type === "text").map((block: any) => block.text || "").join("\n");
+}
+
+function isTextOnlyModel(model: any): boolean {
+  return Array.isArray(model?.input) && !model.input.includes("image");
+}
+
+function modelQuestion(messages: VisionMessages): string {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if ((messages[index] as any)?.role !== "user") continue;
+    const text = contentText((messages[index] as any)?.content)
+      .replace(/<vision-context>[\s\S]*?<\/vision-context>/g, "")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (text) return text.slice(0, 2000);
+  }
+  return "Describe the image accurately and report only visible evidence.";
+}
+
+function collectImages(messages: VisionMessages): VisionResource[] {
+  const resources: VisionResource[] = [];
+  messages.forEach((message: any, messageIndex) => {
+    if (contentText(message?.content).includes(CONTEXT_START)) return;
+    if (!Array.isArray(message?.content)) return;
+    message.content.forEach((block: any) => {
+      if (block?.type !== "image") return;
+      const image: VisionImage = {
+        data: block.data || block.source?.data,
+        mediaType: block.mimeType || block.mediaType || block.source?.mediaType || "image/png",
+      };
+      if (typeof image.data !== "string" || !image.data) return;
+      resources.push({ messageIndex, image, hash: imageHash(image) });
+    });
+  });
+  return resources;
+}
+
+function removeImages(content: unknown): unknown {
+  if (!Array.isArray(content)) return content;
+  return content.filter((block: any) => block?.type !== "image");
+}
+
+function addText(content: unknown, text: string): unknown {
+  if (typeof content === "string") return `${text}${content}`;
+  if (Array.isArray(content)) return [{ type: "text", text }, ...content];
+  return [{ type: "text", text }];
+}
+
+function lastUserMessageIndex(messages: VisionMessages): number {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if ((messages[index] as any)?.role === "user") return index;
+  }
+  return -1;
+}
+
+function failureMessages(messages: VisionMessages, failure: string): VisionMessages {
+  const index = lastUserMessageIndex(messages);
+  return messages.map((message: any, messageIndex) => {
+    const content = removeImages(message.content);
+    return messageIndex === index
+      ? { ...message, content: addText(content, `${CONTEXT_START}\n${neutralizeVisionDelimiters(failure)}\n${CONTEXT_END}\n\n`) }
+      : Array.isArray(message.content) && content !== message.content
+        ? { ...message, content }
+        : message;
+  });
+}
+
+export class VisionBridge {
+  private readonly cache = new VisionNoteCache();
+  private readonly chain: VisionChain;
+  private readonly t: Translator;
+  private readonly latestImages = new Map<string, VisionImage>();
+  private latestSessionKey?: string;
+
+  constructor(chain: VisionChain, t: Translator) {
+    this.chain = chain;
+    this.t = t;
+  }
+
+  private sessionKey(ctx: ExtensionContext): string {
+    return ctx.sessionManager.getSessionFile() || `cwd:${ctx.cwd || "unknown"}`;
+  }
+
+  private rememberLatest(ctx: ExtensionContext, image: VisionImage): void {
+    const key = this.sessionKey(ctx);
+    if (this.latestSessionKey && this.latestSessionKey !== key) this.latestImages.clear();
+    this.latestSessionKey = key;
+    this.latestImages.set(key, image);
+  }
+
+  /** sharp 缺失属于可操作的安装问题，单独给用户弹提示（其余预处理失败只注入上下文） */
+  private reportPreprocessFailure(error: unknown, ctx: ExtensionContext): void {
+    if (!ctx.hasUI || !isSharpMissingError(error)) return;
+    ctx.ui.notify(describeVisionImageError(error, this.t), "error");
+  }
+
+  private async analyze(image: VisionImage, question: string, ctx: ExtensionContext, deadlineAt: number): Promise<VisionNote | undefined> {
+    const currentModel = ctx.model ? { provider: ctx.model.provider, modelId: ctx.model.id } : undefined;
+    const target = this.chain.selectTarget(ctx.modelRegistry, currentModel);
+    const cacheModel = target
+      ? { provider: target.provider, id: target.modelId }
+      : currentModel ? { provider: currentModel.provider, id: currentModel.modelId } : undefined;
+    const key = noteKey(imageHash(image), question, cacheModel);
+    const cached = this.cache.get(key);
+    if (cached) return cached;
+
+    const answer = await this.chain.ask(ctx.modelRegistry, [image], notePrompt(question), {
+      signal: ctx.signal,
+      deadlineAt,
+      currentModel,
+      perCallMs: PER_CALL_MS,
+    });
+    if (!answer.ok) return undefined;
+
+    let responseText = answer.text;
+    let correctionBackend = answer.backend;
+    if (!isStructuredVisionResponse(responseText)) {
+      const correction = await this.chain.ask(
+        ctx.modelRegistry,
+        [image],
+        `${notePrompt(question)}\n上一次输出格式无效。现在只返回完整 JSON，不要添加 Markdown 或解释。`,
+        { signal: ctx.signal, deadlineAt, currentModel, perCallMs: PER_CALL_MS },
+      );
+      if (!correction.ok || !isStructuredVisionResponse(correction.text)) return undefined;
+      responseText = correction.text;
+      correctionBackend = correction.backend;
+    }
+
+    const note: VisionNote = {
+      key,
+      note: formatNote(responseText, question),
+      imageHash: imageHash(image),
+      question,
+      model: correctionBackend,
+      updatedAt: Date.now(),
+    };
+    await this.cache.set(ctx, note);
+    return note;
+  }
+
+  /** 让主模型针对最近一张截图自由追问辅助视觉模型。 */
+  async queryLatest(question: string, ctx: ExtensionContext): Promise<VisionAnswer> {
+    const normalizedQuestion = question.trim();
+    if (!normalizedQuestion) return { ok: false, json: this.t("module.eyes.queryEmpty") };
+    await this.cache.load(ctx);
+    const image = this.latestImages.get(this.sessionKey(ctx));
+    if (!image) return { ok: false, json: this.t("module.eyes.queryNoImage") };
+    let preparedImage: VisionImage;
+    try {
+      [preparedImage] = await prepareVisionImages([image]);
+    } catch (error) {
+      this.reportPreprocessFailure(error, ctx);
+      return {
+        ok: false,
+        json: this.t("module.eyes.injectPreprocessFailed", { reason: describeVisionImageError(error, this.t) }),
+      };
+    }
+    const note = await this.analyze(preparedImage, normalizedQuestion, ctx, Date.now() + TASK_DEADLINE_MS);
+    return note
+      ? { ok: true, text: note.note, backend: note.model }
+      : { ok: false, json: this.t("module.eyes.queryFailed") };
+  }
+
+  async prepare(messages: VisionMessages, ctx: ExtensionContext): Promise<VisionMessages> {
+    const resources = collectImages(messages);
+    if (!resources.length) return messages;
+    if (!isTextOnlyModel(ctx.model)) {
+      this.rememberLatest(ctx, resources[resources.length - 1].image);
+      return messages;
+    }
+    await this.cache.load(ctx);
+
+    const question = modelQuestion(messages);
+    let preparedImages: VisionImage[];
+    try {
+      preparedImages = await prepareVisionImages(resources.map((resource) => resource.image));
+    } catch (error) {
+      this.reportPreprocessFailure(error, ctx);
+      return failureMessages(messages, describeVisionImageError(error, this.t));
+    }
+
+    this.rememberLatest(ctx, preparedImages[preparedImages.length - 1]);
+    const deadlineAt = Date.now() + TASK_DEADLINE_MS;
+    const notes: VisionNote[] = [];
+    for (let resourceIndex = 0; resourceIndex < resources.length; resourceIndex += 1) {
+      const note = await this.analyze(preparedImages[resourceIndex], question, ctx, deadlineAt);
+      if (!note) return failureMessages(messages, this.t("module.eyes.injectUnavailable"));
+      notes.push(note);
+    }
+
+    const byMessage = new Map<number, VisionNote[]>();
+    resources.forEach((resource, index) => {
+      const list = byMessage.get(resource.messageIndex) || [];
+      list.push(notes[index]);
+      byMessage.set(resource.messageIndex, list);
+    });
+    return messages.map((message: any, index) => {
+      const localNotes = byMessage.get(index);
+      return localNotes?.length
+        ? { ...message, content: addText(removeImages(message.content), contextBlock(localNotes)) }
+        : message;
+    });
+  }
+}
+
+/** context 注入钩子：只有模块启用时才会被注册（装配器负责按 enabled 跳过） */
+export function registerVisionContext(pi: ExtensionAPI, bridge: VisionBridge): void {
+  pi.on("context", async (event, ctx) => ({ messages: await bridge.prepare(event.messages, ctx) }));
+}