@buyi1net/pi-toolkit 0.0.1

package/index.ts

@@ -0,0 +1,99 @@
+// pi-toolkit 入口：装配模块，注册 /pi-toolkit 控制菜单。
+// 菜单用 pi 原生 SettingsList + getSettingsListTheme()（与原生 /settings 同组件同主题）。
+
+import {
+  getAgentDir,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { languageLabelKey } from "./i18n.ts";
+import { groupItemId } from "./menu/items.ts";
+import { createMenuTheme } from "./menu/theme.ts";
+import { applyMenuChange, ToolkitMenu } from "./menu/toolkit-menu.ts";
+import { ENABLED_FIELD } from "./module.ts";
+import { BUILT_IN_MODULES } from "./modules/index.ts";
+import { createToolkit, type Toolkit } from "./toolkit.ts";
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export default async function piToolkit(pi: ExtensionAPI): Promise<void> {
+  const toolkit = await createToolkit({
+    pi,
+    agentDir: getAgentDir(),
+    modules: BUILT_IN_MODULES,
+  });
+
+  registerControlCommand(pi, toolkit);
+  reportProblems(pi, toolkit);
+}
+
+function reportProblems(pi: ExtensionAPI, toolkit: Toolkit): void {
+  if (toolkit.problems.length === 0) return;
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    const t = toolkit.getTranslator();
+    for (const problem of toolkit.problems) {
+      const label = t(problem.kind === "config" ? "problem.config" : "problem.module");
+      ctx.ui.notify(
+        t("problem.summary", { label, source: problem.source, detail: problem.detail }),
+        "warning",
+      );
+    }
+  });
+}
+
+function registerControlCommand(pi: ExtensionAPI, toolkit: Toolkit): void {
+  pi.registerCommand("pi-toolkit", {
+    // 命令说明在注册时定稿（命令表不支持随语言重建），取装载时的配置语言。
+    description: toolkit.getTranslator()("command.description"),
+    handler: async (_args: string, ctx: ExtensionCommandContext): Promise<void> => {
+      const t = () => toolkit.getTranslator();
+      if (!ctx.hasUI) {
+        ctx.ui.notify(t()("notify.nonInteractive"), "warning");
+        return;
+      }
+
+      let menu: ToolkitMenu | undefined;
+
+      const handleChange = async (id: string, value: string): Promise<void> => {
+        try {
+          const result = await applyMenuChange(toolkit, id, value);
+          if (result.kind === "ignored") return;
+
+          if (result.kind === "language") {
+            const name = t()(languageLabelKey(result.language));
+            ctx.ui.notify(t()("notify.languageChanged", { language: name }), "info");
+            // 语言变了要重建菜单，否则列表里的文案还是旧语言
+            menu?.refresh(groupItemId("general"));
+            return;
+          }
+
+          if (result.field === ENABLED_FIELD) {
+            const definition = toolkit.getModuleDefinition(result.moduleId);
+            const name = definition ? t()(definition.labelKey) : result.moduleId;
+            ctx.ui.notify(t()("notify.moduleTogglePending", { module: name }), "warning");
+          }
+        } catch (error) {
+          ctx.ui.notify(t()("notify.saveFailed", { reason: describeError(error) }), "error");
+        }
+      };
+
+      await ctx.ui.custom((tui, theme, _keybindings, done) => {
+        menu = new ToolkitMenu({
+          toolkit,
+          theme: createMenuTheme(theme),
+          context: ctx,
+          agentDir: getAgentDir(),
+          requestRender: () => tui.requestRender(),
+          onChange: (id, value) => {
+            void handleChange(id, value);
+          },
+          onClose: () => done(undefined),
+        });
+        return menu;
+      });
+    },
+  });
+}

package/menu/items.ts

@@ -0,0 +1,264 @@
+// 菜单行构造：顶层两组 + 分组页内容（语言、占位行、模块行）。
+// 设计约定：SettingsList 一行只接受一个字符串，所以取值选择器回传"显示文案"，
+// 这里用同一份 i18n 选项表把文案映射回规范化取值（见 fieldValueFromLabel / languageFromLabel），
+// 因此语言切换后菜单重建即刷新全部显示，无需额外的显示态。
+
+import type { SettingItem } from "@earendil-works/pi-tui";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ToolkitConfig } from "../config.ts";
+import {
+  languageLabelKey,
+  LANGUAGE_SETTINGS,
+  type LanguageSetting,
+  type MessageKey,
+  type ResolvedLanguage,
+  type Translator,
+} from "../i18n.ts";
+import {
+  isBooleanField,
+  MODULE_GROUPS,
+  normalizeConfigValue,
+  type ConfigField,
+  type ModuleConfigScalar,
+  type ModuleConfigRecord,
+  type ModuleDefinition,
+  type ModuleGroup,
+} from "../module.ts";
+import type { ActiveModule } from "../assembler.ts";
+import { moduleFieldId } from "../assembler.ts";
+import type { ToolkitProblem } from "../toolkit.ts";
+import type { ServiceRegistry } from "../services.ts";
+import { ChoicePicker, SettingsPanel } from "./panels.ts";
+import type { MenuTheme } from "./theme.ts";
+
+/** 语言行的 id */
+export const ID_LANGUAGE = "language";
+
+const GROUP_ID_PREFIX = "group.";
+
+export function groupItemId(group: ModuleGroup): string {
+  return `${GROUP_ID_PREFIX}${group}`;
+}
+
+export interface MenuState {
+  readonly config: ToolkitConfig;
+  readonly modules: readonly ActiveModule[];
+  readonly problems: readonly ToolkitProblem[];
+  readonly services: ServiceRegistry;
+  readonly language: LanguageSetting;
+  readonly resolvedLanguage: ResolvedLanguage;
+}
+
+export interface MenuBuildContext {
+  readonly t: Translator;
+  readonly theme: MenuTheme;
+  /** 打开菜单时的扩展上下文；模块自绘子菜单需要与宿主交互时用它 */
+  readonly context: ExtensionContext;
+  /** pi 的配置目录：模块自写盘时用 */
+  readonly agentDir: string;
+  getState(): MenuState;
+  getModuleConfig(moduleId: string): ModuleConfigRecord;
+  /** 顶层统一改动入口（id 与显示文案） */
+  onChange(id: string, value: string): void;
+  /** 异步动作结束后请宿主重绘 */
+  requestRender(): void;
+  /** 重建整棵菜单：语言切换后用它刷新全部文案 */
+  refresh(selectId?: string): void;
+}
+
+/** 一个取值的规范化代码与本地化文案 */
+export interface FieldOption {
+  readonly code: string;
+  readonly label: string;
+}
+
+function enumValueLabel(t: Translator, field: ConfigField, value: string): string {
+  const key = field.valueLabelKeys?.[value];
+  return key ? t(key) : value;
+}
+
+/** 字段的可选值：boolean 为 开/关，枚举取 schema 声明的 values */
+export function fieldOptions(t: Translator, field: ConfigField): FieldOption[] {
+  if (isBooleanField(field)) {
+    return [
+      { code: "true", label: t("common.on") },
+      { code: "false", label: t("common.off") },
+    ];
+  }
+  return (field.values ?? []).map((value) => ({ code: value, label: enumValueLabel(t, field, value) }));
+}
+
+function fieldCode(current: ModuleConfigScalar | undefined): string | undefined {
+  return current === undefined ? undefined : String(current);
+}
+
+/** 当前值在菜单里显示的本地化文案 */
+export function fieldDisplayValue(
+  t: Translator,
+  field: ConfigField,
+  current: ModuleConfigScalar | undefined,
+): string {
+  const code = fieldCode(current);
+  const option = fieldOptions(t, field).find((candidate) => candidate.code === code);
+  return option?.label ?? code ?? "";
+}
+
+/** 选择器回传的显示文案 → 规范化取值；匹配不上返回 undefined */
+export function fieldValueFromLabel(
+  t: Translator,
+  field: ConfigField,
+  label: string,
+): ModuleConfigScalar | undefined {
+  const option = fieldOptions(t, field).find((candidate) => candidate.label === label);
+  return option ? normalizeConfigValue(field, option.code) : undefined;
+}
+
+/** 语言选择项：四个设置加各自本地化文案 */
+export function languageOptions(t: Translator): { setting: LanguageSetting; label: string }[] {
+  return LANGUAGE_SETTINGS.map((setting) => ({ setting, label: t(languageLabelKey(setting)) }));
+}
+
+export function languageFromLabel(t: Translator, label: string): LanguageSetting | undefined {
+  return languageOptions(t).find((option) => option.label === label)?.setting;
+}
+
+export function buildTopLevelItems(build: MenuBuildContext): SettingItem[] {
+  const state = build.getState();
+  const items: SettingItem[] = [];
+  for (const problem of state.problems) {
+    items.push(problemItem(build, problem));
+  }
+  for (const group of MODULE_GROUPS) {
+    items.push(groupItem(build, group));
+  }
+  return items;
+}
+
+export function buildGroupItems(build: MenuBuildContext, group: ModuleGroup): SettingItem[] {
+  const items: SettingItem[] = [];
+  if (group === "general") {
+    items.push(languageItem(build));
+  }
+  for (const active of build.getState().modules) {
+    if (active.definition.group !== group) continue;
+    items.push(...moduleItems(build, active.definition));
+  }
+  return items;
+}
+
+function groupLabelKeys(group: ModuleGroup): { label: MessageKey; description: MessageKey } {
+  return group === "general"
+    ? { label: "group.general", description: "group.general.description" }
+    : { label: "group.subagents", description: "group.subagents.description" };
+}
+
+function groupItem(build: MenuBuildContext, group: ModuleGroup): SettingItem {
+  const keys = groupLabelKeys(group);
+  return {
+    id: groupItemId(group),
+    label: build.t(keys.label),
+    description: build.t(keys.description),
+    currentValue: build.t("group.itemCount", { count: buildGroupItems(build, group).length }),
+    submenu: (_currentValue, done) =>
+      new SettingsPanel({
+        title: build.t(keys.label),
+        items: buildGroupItems(build, group),
+        theme: build.theme,
+        t: build.t,
+        onChange: build.onChange,
+        onClose: () => done(),
+      }),
+  };
+}
+
+function problemItem(build: MenuBuildContext, problem: ToolkitProblem): SettingItem {
+  return {
+    id: `problem.${problem.kind}.${problem.source}`,
+    label: build.t(problem.kind === "config" ? "problem.config" : "problem.module"),
+    description: problem.detail,
+    currentValue: problem.source,
+  };
+}
+
+function languageItem(build: MenuBuildContext): SettingItem {
+  const state = build.getState();
+  const description =
+    state.language === "auto"
+      ? build.t("language.autoResolved", {
+          language: build.t(languageLabelKey(state.resolvedLanguage)),
+        })
+      : build.t("language.description");
+  return {
+    id: ID_LANGUAGE,
+    label: build.t("language.label"),
+    description,
+    currentValue: build.t(languageLabelKey(state.language)),
+    submenu: (_currentValue, done) =>
+      new ChoicePicker({
+        title: build.t("language.label"),
+        options: languageOptions(build.t).map((option) => ({
+          value: option.setting,
+          label: option.label,
+          ...(option.setting === state.language ? { description: build.t("common.current") } : {}),
+        })),
+        theme: build.theme,
+        t: build.t,
+        onSelect: (_value, label) => done(label),
+        onCancel: () => done(),
+      }),
+  };
+}
+
+function moduleItems(build: MenuBuildContext, definition: ModuleDefinition): SettingItem[] {
+  const config = build.getModuleConfig(definition.id);
+  const items: SettingItem[] = [];
+  for (const [key, field] of Object.entries(definition.configSchema)) {
+    // schema 字段是标量；这里再规范化一次，把类型收成标量（取值非法时回落到默认值）
+    const current = normalizeConfigValue(field, config[key]) ?? field.default;
+    items.push(fieldItem(build, definition, key, field, current));
+  }
+  if (definition.menuItems) {
+    items.push(
+      ...definition.menuItems({
+        t: build.t,
+        services: build.getState().services,
+        getConfig: () => build.getModuleConfig(definition.id),
+        context: build.context,
+        agentDir: build.agentDir,
+        theme: build.theme,
+        requestRender: () => build.requestRender(),
+      }),
+    );
+  }
+  return items;
+}
+
+function fieldItem(
+  build: MenuBuildContext,
+  definition: ModuleDefinition,
+  key: string,
+  field: ConfigField,
+  current: ModuleConfigScalar | undefined,
+): SettingItem {
+  const label = build.t(field.labelKey);
+  const currentCode = fieldCode(current);
+  return {
+    id: moduleFieldId(definition.id, key),
+    label,
+    ...(field.descriptionKey === undefined ? {} : { description: build.t(field.descriptionKey) }),
+    currentValue: fieldDisplayValue(build.t, field, current),
+    submenu: (_currentValue, done) =>
+      new ChoicePicker({
+        title: label,
+        options: fieldOptions(build.t, field).map((option) => ({
+          value: option.code,
+          label: option.label,
+          ...(option.code === currentCode ? { description: build.t("common.current") } : {}),
+        })),
+        theme: build.theme,
+        t: build.t,
+        onSelect: (_value, displayLabel) => done(displayLabel),
+        onCancel: () => done(),
+      }),
+  };
+}

package/menu/panels.ts

@@ -0,0 +1,91 @@
+// 菜单里的两种面板组件，都是 Container 子类内嵌 pi 原生列表组件（原生 WarningSettingsSubmenu 同款写法）：
+// - SettingsPanel：设置面板，内嵌 SettingsList，用于分组页（常规 / 子代理）
+// - ChoicePicker：取值选择器，内嵌 SelectList，用于语言与各配置字段的取值选择
+// 两者只加一行标题：子菜单渲染在顶层 Container 的边框之内（与原生 /settings 的子菜单一致，不再套第二层边框）。
+// Esc 都交给上层回传 done() 返回上级。
+
+import {
+  Container,
+  type SelectItem,
+  SelectList,
+  type SettingItem,
+  Text,
+} from "@earendil-works/pi-tui";
+import type { Translator } from "../i18n.ts";
+import { I18nSettingsList } from "./settings-list.ts";
+import type { MenuTheme } from "./theme.ts";
+
+const MAX_VISIBLE = 10;
+
+export interface SettingsPanelOptions {
+  readonly title: string;
+  readonly items: readonly SettingItem[];
+  readonly theme: MenuTheme;
+  readonly t: Translator;
+  readonly onChange: (id: string, value: string) => void;
+  /** Esc：返回上级菜单 */
+  readonly onClose: () => void;
+  readonly enableSearch?: boolean;
+}
+
+export class SettingsPanel extends Container {
+  private readonly list: I18nSettingsList;
+
+  constructor(options: SettingsPanelOptions) {
+    super();
+    this.addChild(new Text(options.theme.title(options.title), 1, 0));
+    this.list = new I18nSettingsList({
+      items: options.items,
+      maxVisible: MAX_VISIBLE,
+      theme: options.theme.settings,
+      t: options.t,
+      onChange: options.onChange,
+      onCancel: options.onClose,
+      ...(options.enableSearch === undefined ? {} : { enableSearch: options.enableSearch }),
+    });
+    this.addChild(this.list);
+  }
+
+  handleInput(data: string): void {
+    this.list.handleInput(data);
+  }
+}
+
+export interface ChoiceOption {
+  readonly value: string;
+  readonly label: string;
+  readonly description?: string;
+}
+
+export interface ChoicePickerOptions {
+  readonly title: string;
+  readonly options: readonly ChoiceOption[];
+  readonly theme: MenuTheme;
+  readonly t: Translator;
+  /** 回传规范化取值与显示文案；由调用方决定如何回填父项 */
+  readonly onSelect: (value: string, label: string) => void;
+  readonly onCancel: () => void;
+}
+
+export class ChoicePicker extends Container {
+  private readonly list: SelectList;
+
+  constructor(options: ChoicePickerOptions) {
+    super();
+    this.addChild(new Text(options.theme.title(options.title), 1, 0));
+    const items: SelectItem[] = options.options.map((option) => ({
+      value: option.value,
+      label: option.label,
+      ...(option.description === undefined ? {} : { description: option.description }),
+    }));
+    this.list = new SelectList(items, Math.min(items.length, MAX_VISIBLE), options.theme.select);
+    this.list.onSelect = (item) => options.onSelect(item.value, item.label);
+    this.list.onCancel = () => options.onCancel();
+    this.addChild(this.list);
+    this.addChild(new Text(options.theme.hint(options.t("hint.chooseOptions")), 1, 0));
+  }
+
+  handleInput(data: string): void {
+    this.list.handleInput(data);
+  }
+}

package/menu/settings-list.ts

@@ -0,0 +1,84 @@
+// SettingsList 的薄包装：组件内部自带几行英文提示（"Enter/Space to change · Esc to cancel"、
+// "Type to search"、"No matching settings" 等），无法通过构造参数改写。这里在渲染出口按行
+// 替换成 i18n 文案，保证三语切换后菜单里没有残留英文；无法识别时原样放行，不猜不改。
+
+import {
+  type Component,
+  type SettingItem,
+  SettingsList,
+  type SettingsListTheme,
+  type TuiMouseEvent,
+  type TuiMouseEventResult,
+  truncateToWidth,
+} from "@earendil-works/pi-tui";
+import type { MessageKey, Translator } from "../i18n.ts";
+
+/** 组件内置提示行 → i18n 键；顺序即匹配顺序，先匹配更长的搜索提示 */
+const BUILT_IN_HINTS: readonly { readonly match: string; readonly key: MessageKey }[] = [
+  { match: "Type to search", key: "hint.search" },
+  { match: "Enter/Space to change", key: "hint.change" },
+  { match: "No matching settings", key: "hint.noMatch" },
+  { match: "No settings available", key: "hint.noSettings" },
+];
+
+export interface I18nSettingsListOptions {
+  readonly items: readonly SettingItem[];
+  readonly maxVisible: number;
+  readonly theme: SettingsListTheme;
+  readonly t: Translator;
+  readonly onChange: (id: string, value: string) => void;
+  readonly onCancel: () => void;
+  readonly enableSearch?: boolean;
+}
+
+export class I18nSettingsList implements Component {
+  private readonly list: SettingsList;
+  private readonly t: Translator;
+  private readonly theme: SettingsListTheme;
+
+  constructor(options: I18nSettingsListOptions) {
+    this.t = options.t;
+    this.theme = options.theme;
+    this.list = new SettingsList(
+      [...options.items],
+      options.maxVisible,
+      options.theme,
+      options.onChange,
+      options.onCancel,
+      options.enableSearch === undefined ? {} : { enableSearch: options.enableSearch },
+    );
+  }
+
+  updateValue(id: string, newValue: string): void {
+    this.list.updateValue(id, newValue);
+  }
+
+  selectItem(id: string): void {
+    this.list.selectItem(id);
+  }
+
+  invalidate(): void {
+    this.list.invalidate();
+  }
+
+  handleInput(data: string): void {
+    this.list.handleInput(data);
+  }
+
+  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+    return this.list.handleMouse(event);
+  }
+
+  render(width: number): string[] {
+    return this.list.render(width).map((line) => this.translateLine(line, width));
+  }
+
+  private translateLine(line: string, width: number): string {
+    for (const hint of BUILT_IN_HINTS) {
+      if (line.includes(hint.match)) {
+        return truncateToWidth(this.theme.hint(this.t(hint.key)), width);
+      }
+    }
+    return line;
+  }
+}

package/menu/theme.ts

@@ -0,0 +1,31 @@
+// 菜单主题：SettingsList / SelectList 用 pi 原生 get*Theme()，与原生 /settings 同色；
+// 标题与边框用 ctx.ui.custom 回调里的主题实例显式上色（jiti 加载下不要依赖组件内部默认主题）。
+
+import {
+  getSelectListTheme,
+  getSettingsListTheme,
+  type Theme,
+  type ThemeColor,
+} from "@earendil-works/pi-coding-agent";
+import type { SelectListTheme, SettingsListTheme } from "@earendil-works/pi-tui";
+
+export interface MenuTheme {
+  readonly settings: SettingsListTheme;
+  readonly select: SelectListTheme;
+  readonly title: (text: string) => string;
+  readonly border: (text: string) => string;
+  readonly hint: (text: string) => string;
+  /** 模块自绘面板用：状态行按语义上色（success / error / warning / dim） */
+  readonly fg: (color: ThemeColor, text: string) => string;
+}
+
+export function createMenuTheme(theme: Theme): MenuTheme {
+  return {
+    settings: getSettingsListTheme(),
+    select: getSelectListTheme(),
+    title: (text) => theme.bold(theme.fg("accent", text)),
+    border: (text) => theme.fg("border", text),
+    hint: (text) => theme.fg("dim", text),
+    fg: (color, text) => theme.fg(color, text),
+  };
+}