@buyi1net/pi-toolkit 0.0.1

package/menu/toolkit-menu.ts

@@ -0,0 +1,139 @@
+// 顶层菜单组件与菜单改动落盘。
+// 顶层用 SettingsList 内嵌在 Container 里（上下边框），分组页与取值选择器见 panels.ts。
+
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container } from "@earendil-works/pi-tui";
+import type { LanguageSetting } from "../i18n.ts";
+import type { ModuleConfigScalar } from "../module.ts";
+import type { Toolkit } from "../toolkit.ts";
+import {
+  buildTopLevelItems,
+  fieldValueFromLabel,
+  ID_LANGUAGE,
+  languageFromLabel,
+  type MenuBuildContext,
+  type MenuState,
+} from "./items.ts";
+import { I18nSettingsList } from "./settings-list.ts";
+import type { MenuTheme } from "./theme.ts";
+
+const TOP_LEVEL_MAX_VISIBLE = 8;
+
+export function readMenuState(toolkit: Toolkit): MenuState {
+  return {
+    config: toolkit.getConfig(),
+    modules: toolkit.modules,
+    problems: toolkit.problems,
+    services: toolkit.services,
+    language: toolkit.getLanguage(),
+    resolvedLanguage: toolkit.getResolvedLanguage(),
+  };
+}
+
+export interface ToolkitMenuOptions {
+  readonly toolkit: Toolkit;
+  readonly theme: MenuTheme;
+  /** 打开菜单时的扩展上下文（模块自绘子菜单用） */
+  readonly context: ExtensionContext;
+  /** pi 的配置目录（传给模块菜单，供模块自写盘） */
+  readonly agentDir: string;
+  /** 异步动作结束后请宿主重绘 */
+  readonly requestRender: () => void;
+  /** 菜单里每次取值变化都先到这里（id + 显示文案） */
+  readonly onChange: (id: string, value: string) => void;
+  /** 顶层 Esc：关闭菜单 */
+  readonly onClose: () => void;
+}
+
+export class ToolkitMenu extends Container {
+  private readonly options: ToolkitMenuOptions;
+  private readonly build: MenuBuildContext;
+  private list: I18nSettingsList | undefined;
+
+  constructor(options: ToolkitMenuOptions) {
+    super();
+    this.options = options;
+    this.build = {
+      // 译者始终读当前语言，重建时 label 自然换成新语言
+      t: options.toolkit.getTranslator(),
+      theme: options.theme,
+      context: options.context,
+      agentDir: options.agentDir,
+      getState: () => readMenuState(options.toolkit),
+      getModuleConfig: (moduleId) => options.toolkit.getModuleConfig(moduleId),
+      onChange: options.onChange,
+      requestRender: () => options.requestRender(),
+      refresh: (selectId) => this.rebuild(selectId),
+    };
+    this.rebuild();
+  }
+
+  /** 语言切换后重建整棵菜单，让全部文案立刻生效 */
+  refresh(selectId?: string): void {
+    this.rebuild(selectId);
+  }
+
+  handleInput(data: string): void {
+    this.list?.handleInput(data);
+  }
+
+  private rebuild(selectId?: string): void {
+    this.clear();
+    const items = buildTopLevelItems(this.build);
+    this.addChild(new DynamicBorder(this.options.theme.border));
+    const list = new I18nSettingsList({
+      items,
+      maxVisible: Math.min(Math.max(items.length, 1), TOP_LEVEL_MAX_VISIBLE),
+      theme: this.options.theme.settings,
+      t: this.build.t,
+      onChange: this.options.onChange,
+      onCancel: () => this.options.onClose(),
+      enableSearch: true,
+    });
+    this.list = list;
+    this.addChild(list);
+    this.addChild(new DynamicBorder(this.options.theme.border));
+    if (selectId) list.selectItem(selectId);
+  }
+}
+
+export type MenuChangeResult =
+  | { readonly kind: "language"; readonly language: LanguageSetting }
+  | {
+      readonly kind: "module-field";
+      readonly moduleId: string;
+      readonly field: string;
+      readonly value: ModuleConfigScalar;
+    }
+  | { readonly kind: "ignored" };
+
+/**
+ * 把菜单行 id 与显示文案翻回配置改动并持久化。
+ * 显示文案 → 规范化取值的映射见 items.ts（同一份 i18n 选项表）。
+ */
+export async function applyMenuChange(
+  toolkit: Toolkit,
+  id: string,
+  displayValue: string,
+): Promise<MenuChangeResult> {
+  const t = toolkit.getTranslator();
+
+  if (id === ID_LANGUAGE) {
+    const language = languageFromLabel(t, displayValue);
+    if (!language) return { kind: "ignored" };
+    return { kind: "language", language: await toolkit.setLanguage(language) };
+  }
+
+  const separator = id.indexOf(".");
+  if (separator <= 0) return { kind: "ignored" };
+  const moduleId = id.slice(0, separator);
+  const field = id.slice(separator + 1);
+  const definition = toolkit.getModuleDefinition(moduleId);
+  const schemaField = definition?.configSchema[field];
+  if (!definition || !schemaField) return { kind: "ignored" };
+
+  const value = fieldValueFromLabel(t, schemaField, displayValue);
+  if (value === undefined) return { kind: "ignored" };
+  return { kind: "module-field", moduleId, field, value: await toolkit.setModuleField(moduleId, field, value) };
+}

package/module.ts

@@ -0,0 +1,156 @@
+// 模块契约：每个源插件迁入 pi-toolkit 后实现为一个 ModuleDefinition。
+// 装配器只负责按 enabled 开关决定是否调用 register；模块自己决定注册哪些命令/工具/钩子。
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SettingItem } from "@earendil-works/pi-tui";
+import type { MessageKey, Translator } from "./i18n.ts";
+import type { MenuTheme } from "./menu/theme.ts";
+import type { ServiceRegistry } from "./services.ts";
+
+/** 配置节里的标量取值；schema 字段（菜单控件）只接受标量 */
+export type ModuleConfigScalar = string | number | boolean | null;
+/**
+ * 配置节里能存的值：标量、数组与嵌套对象。
+ * 嵌套结构不属于 schema 字段（菜单不渲染），模块在自己的配置解析里读取校验，
+ * 例如视觉模块的 `backend.route.allowedModels` / `fixedModel`。
+ */
+export type ModuleConfigValue =
+  | ModuleConfigScalar
+  | ModuleConfigValue[]
+  | { [key: string]: ModuleConfigValue };
+export type ModuleConfigRecord = Record<string, ModuleConfigValue>;
+
+/**
+ * 一个配置字段。
+ * - default 为 boolean：开/关字段
+ * - default 为 string 且带 values：枚举字段（配置里存 values 中的规范化代码）
+ * - 枚举值的显示文案从 valueLabelKeys 取；某个值没配键时直接显示该值原文
+ *
+ * 数值/自由文本字段等后续工单需要时再扩展控件类型，本工单不预置无用分支。
+ */
+export interface ConfigField {
+  default: ModuleConfigScalar;
+  values?: readonly string[];
+  labelKey: MessageKey;
+  descriptionKey?: MessageKey;
+  /** 枚举值 → 显示文案键，必须覆盖 values 里的每一项 */
+  valueLabelKeys?: Readonly<Record<string, MessageKey>>;
+}
+
+export type ModuleConfigSchema = Record<string, ConfigField>;
+
+/** 菜单分组：顶层菜单的两组 */
+export type ModuleGroup = "general" | "subagents";
+export const MODULE_GROUPS: readonly ModuleGroup[] = ["general", "subagents"];
+
+/** 模块总开关字段名；每个模块的 schema 必须声明它 */
+export const ENABLED_FIELD = "enabled";
+
+export function enabledField(labelKey: MessageKey, descriptionKey?: MessageKey): ConfigField {
+  return { default: true, labelKey, descriptionKey };
+}
+
+export function isBooleanField(field: ConfigField): boolean {
+  return typeof field.default === "boolean";
+}
+
+/** 把外部输入（菜单回传的显示文案、配置文件里的值）规范化成 schema 接受的值；不接受则返回 undefined */
+export function normalizeConfigValue(field: ConfigField, value: unknown): ModuleConfigScalar | undefined {
+  if (typeof field.default === "boolean") {
+    if (typeof value === "boolean") return value;
+    if (value === "true") return true;
+    if (value === "false") return false;
+    return undefined;
+  }
+  if (typeof field.default === "number") {
+    if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+  }
+  if (typeof value !== "string") return undefined;
+  if (field.values && !field.values.includes(value)) return undefined;
+  return value;
+}
+
+export interface ModuleContext {
+  readonly moduleId: string;
+  /** 收到 pi API 后自行注册命令、工具与钩子 */
+  readonly pi: ExtensionAPI;
+  readonly services: ServiceRegistry;
+  readonly t: Translator;
+  /** 实时读取本模块配置（已合并 schema 默认值） */
+  getConfig(): ModuleConfigRecord;
+  /**
+   * 重新从磁盘读取整份配置文件并刷新状态中枢的内存副本。
+   * 模块用自己的配置层写到盘上（如视觉路由）之后，靠它让 getConfig 跟上磁盘。
+   */
+  reloadConfig(): Promise<void>;
+  /**
+   * 写入并持久化单个配置字段，返回规范化后的值。
+   * 只接受 schema 声明的字段；模块私有的结构化配置（非 schema 键）由模块自己的配置层写入。
+   */
+  setConfig(key: string, value: ModuleConfigScalar): Promise<ModuleConfigScalar>;
+}
+
+export interface ModuleMenuContext {
+  readonly t: Translator;
+  readonly services: ServiceRegistry;
+  getConfig(): ModuleConfigRecord;
+  /** 打开菜单时的扩展上下文：需要与宿主交互的菜单项（如视觉探测）从这里取 modelRegistry / model / signal */
+  readonly context: ExtensionContext;
+  /** pi 的配置目录（<agentDir>/pi-toolkit.json 就在它下面）：模块自写盘时用 */
+  readonly agentDir: string;
+  /** 子菜单自绘面板上色用的主题 */
+  readonly theme: MenuTheme;
+  /** 异步动作结束后请宿主重绘（pi 的 TUI 是按需渲染） */
+  requestRender(): void;
+}
+
+export interface ModuleDefinition {
+  /** 模块 id：同时是配置节名与菜单项 id 前缀 */
+  readonly id: string;
+  readonly labelKey: MessageKey;
+  readonly descriptionKey: MessageKey;
+  readonly group: ModuleGroup;
+  /** 配置 schema，必须包含 enabled 字段 */
+  readonly configSchema: ModuleConfigSchema;
+  /** 仅在模块启用时调用 */
+  readonly register: (context: ModuleContext) => void;
+  /** 可选：schema 自动生成的行之外，本模块专属的菜单行；同样只在模块启用时渲染 */
+  readonly menuItems?: (context: ModuleMenuContext) => readonly SettingItem[];
+}
+
+const MODULE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+
+/** 装配期校验：schema 写错就当场抛出，不拖到菜单渲染时才炸 */
+export function assertModuleDefinition(definition: ModuleDefinition): void {
+  if (!MODULE_ID_PATTERN.test(definition.id)) {
+    throw new Error(`模块 id 不合法：${JSON.stringify(definition.id)}`);
+  }
+  if (!MODULE_GROUPS.includes(definition.group)) {
+    throw new Error(`模块 ${definition.id} 的菜单分组不合法：${String(definition.group)}`);
+  }
+  const enabled = definition.configSchema[ENABLED_FIELD];
+  if (!enabled || !isBooleanField(enabled)) {
+    throw new Error(`模块 ${definition.id} 的 schema 必须包含 enabled 开/关字段`);
+  }
+  for (const [key, field] of Object.entries(definition.configSchema)) {
+    if (isBooleanField(field)) continue;
+    if (!field.values || field.values.length === 0) {
+      throw new Error(`模块 ${definition.id} 的字段 ${key} 需要 values 才能生成菜单控件`);
+    }
+    if (field.values.length !== new Set(field.values).size) {
+      throw new Error(`模块 ${definition.id} 的字段 ${key} 含重复 values`);
+    }
+    if (field.valueLabelKeys) {
+      for (const value of field.values) {
+        if (!field.valueLabelKeys[value]) {
+          throw new Error(`模块 ${definition.id} 的字段 ${key} 缺少取值 ${value} 的显示文案键`);
+        }
+      }
+    }
+  }
+}

package/modules/eyes/chain.ts

@@ -0,0 +1,173 @@
+// 共享视觉链：Pi 视觉模型选择、熔断与 deadline。
+// 视觉模块持有一个实例，context 注入与 vision_query 的模型调用都经它提问。
+
+import {
+  callPiVisionModel,
+  piVisionModelKey,
+  selectAutomaticPiVisionModel,
+  type PiVisionModelRegistry,
+  type PiVisionModelSelection,
+} from "./pi-model-backend.ts";
+import { VisionCircuit, TurnMemory, classifyFailure, buildFailureJson, type FailureKind } from "./resilience.ts";
+import type { VisionImage } from "./vision-types.ts";
+
+export interface VisionAnswerOk {
+  ok: true;
+  text: string;
+  backend: string;
+}
+
+export interface VisionAnswerFail {
+  ok: false;
+  json: string;
+}
+
+export type VisionAnswer = VisionAnswerOk | VisionAnswerFail;
+
+export interface VisionRoutingConfig {
+  route: {
+    mode: "automatic" | "fixed";
+    allowedModels: PiVisionModelSelection[] | null;
+    fixedModel?: PiVisionModelSelection;
+  };
+}
+
+const DEFAULT_ROUTING: VisionRoutingConfig = {
+  route: { mode: "automatic", allowedModels: null },
+};
+
+export class VisionChain {
+  readonly circuit = new VisionCircuit();
+  readonly turnMemory = new TurnMemory();
+  private turnCount = 0;
+  private routing: VisionRoutingConfig = DEFAULT_ROUTING;
+  private stickyAutomaticModel?: PiVisionModelSelection;
+  private readonly failedAutomaticModels = new Set<string>();
+
+  setRouting(config: VisionRoutingConfig): void {
+    if (config.route.mode === "fixed" && !config.route.fixedModel) {
+      throw new Error("fixed 路由必须指定 fixedModel");
+    }
+    this.routing = {
+      route: {
+        mode: config.route.mode,
+        allowedModels: config.route.allowedModels?.map((model) => ({ ...model })) ?? null,
+        ...(config.route.fixedModel ? { fixedModel: { ...config.route.fixedModel } } : {}),
+      },
+    };
+    this.stickyAutomaticModel = undefined;
+    this.failedAutomaticModels.clear();
+  }
+
+  /** 一次 agent run 记一轮:清上一轮的失败短路与无效请求熔断。 */
+  beginTurn(): void {
+    this.turnCount += 1;
+    this.turnMemory.newTurn(this.turnCount);
+  }
+
+  selectTarget(
+    registry: PiVisionModelRegistry,
+    currentModel?: PiVisionModelSelection,
+  ): PiVisionModelSelection | undefined {
+    return this.selectPiTarget(registry, currentModel);
+  }
+
+  private selectPiTarget(
+    registry: PiVisionModelRegistry,
+    currentModel?: PiVisionModelSelection,
+  ): PiVisionModelSelection | undefined {
+    if (this.routing.route.mode === "fixed") return this.routing.route.fixedModel;
+
+    if (this.stickyAutomaticModel) {
+      const availableSticky = selectAutomaticPiVisionModel(registry, {
+        allowedModels: [this.stickyAutomaticModel],
+        excludedModels: this.failedAutomaticModels,
+      });
+      if (availableSticky) return availableSticky;
+      this.stickyAutomaticModel = undefined;
+    }
+    const selected = selectAutomaticPiVisionModel(registry, {
+      currentModel,
+      allowedModels: this.routing.route.allowedModels,
+      excludedModels: this.failedAutomaticModels,
+    });
+    this.stickyAutomaticModel = selected;
+    return selected;
+  }
+
+  /**
+   * 向视觉链提一次问。deadlineAt 是整个工具任务(可能含多次 ask)的共享截止,
+   * 单后端再叠加 per-call 上限;本轮已全失败时直接短路。
+   */
+  async ask(
+    registry: PiVisionModelRegistry,
+    images: VisionImage[],
+    prompt: string,
+    options: {
+      signal?: AbortSignal;
+      deadlineAt: number;
+      perCallMs?: number;
+      currentModel?: PiVisionModelSelection;
+    },
+  ): Promise<VisionAnswer> {
+    options.signal?.throwIfAborted();
+    if (this.turnMemory.allFailed) {
+      return { ok: false, json: buildFailureJson(["OTHER"], this.turnMemory.attempts) };
+    }
+
+    const piSelection = this.selectPiTarget(registry, options.currentModel);
+    if (!piSelection) {
+      const attempted = ["pi: no available vision model"];
+      this.turnMemory.recordAttempt(attempted[0]);
+      this.turnMemory.markAllFailed();
+      return { ok: false, json: buildFailureJson(["OTHER"], attempted) };
+    }
+
+    const targetId = `${piSelection.provider}/${piSelection.modelId}`;
+    const attempted: string[] = [];
+    const failureKinds: FailureKind[] = [];
+    const remaining = options.deadlineAt - Date.now();
+    if (remaining <= 0) {
+      failureKinds.push("TIMEOUT");
+      attempted.push(`${targetId}: skipped (task deadline exhausted)`);
+    } else {
+      const gate = this.circuit.inspect(targetId, this.turnCount);
+      if (gate.blocked) {
+        attempted.push(`${targetId}: skipped (circuit open: ${gate.reason})`);
+      } else {
+        options.signal?.throwIfAborted();
+        const perCall = Math.min(options.perCallMs ?? 60_000, remaining);
+        const callSignal = options.signal
+          ? AbortSignal.any([options.signal, AbortSignal.timeout(perCall)])
+          : AbortSignal.timeout(perCall);
+        try {
+          const text = await callPiVisionModel(registry, piSelection, prompt, images, {
+            signal: callSignal,
+            maxTokens: 4096,
+          });
+          this.circuit.clear(targetId);
+          return { ok: true, text, backend: targetId };
+        } catch (error) {
+          if (options.signal?.aborted) options.signal.throwIfAborted();
+          const failure = classifyFailure({
+            message: error instanceof Error ? error.message : String(error),
+          });
+          this.circuit.record(targetId, failure, this.turnCount);
+          if (this.routing.route.mode === "automatic" && failure.kind !== "INVALID_REQUEST") {
+            this.failedAutomaticModels.add(piVisionModelKey(piSelection.provider, piSelection.modelId));
+            this.stickyAutomaticModel = undefined;
+          }
+          this.turnMemory.recordAttempt(`${targetId}: ${failure.kind}`);
+          attempted.push(`${targetId}: ${failure.kind}`);
+          failureKinds.push(failure.kind);
+        }
+      }
+    }
+    // 自动模式每个请求只试一个 Pi 模型；该候选失败后，下次调用可换下一个。
+    const automaticCanTryAnotherModel =
+      this.routing.route.mode === "automatic" && piSelection !== undefined;
+    // 400/413/422 往往是本次参数或负载问题，允许调用方修正后重试。
+    if (!failureKinds.includes("INVALID_REQUEST") && !automaticCanTryAnotherModel) this.turnMemory.markAllFailed();
+    return { ok: false, json: buildFailureJson(failureKinds.length > 0 ? failureKinds : ["OTHER"], attempted) };
+  }
+}