@ia-ccun/code-agent-cli 0.0.51-beta.13 → 0.0.51-beta.15

package/config/agent/extensions/aicode-advisor.ts

@@ -0,0 +1,707 @@
+/**
+ * aicode-advisor extension
+ *
+ * @author  xujianjiang
+ * 让工作模型在采取行动之前，向更强的审查模型征求第二意见
+ *
+ * Registers the `advisor` tool, `/advisor` command, and lifecycle
+ * hooks that implement the advisor-strategy pattern.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Api, Model, StopReason, Usage } from "@earendil-works/pi-ai";
+import { completeSimple, getSupportedThinkingLevels, type Message, type ThinkingLevel } from "@earendil-works/pi-ai";
+import {
+  type AgentToolResult,
+  type AgentToolUpdateCallback,
+  buildSessionContext,
+  convertToLlm,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+import type { SelectItem } from "@earendil-works/pi-tui";
+import { DynamicBorder, type Theme } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  SelectList,
+  Spacer,
+  Text,
+} from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+// ============== 常量 ==============
+const ADVISOR_TOOL_NAME = "advisor";
+const TOOL_LABEL = "Advisor";
+const CHECKMARK = " ✓";
+const NO_ADVISOR_VALUE = "__no_advisor__";
+const OFF_VALUE = "__off__";
+const BASE_EFFORT_LEVELS: ThinkingLevel[] = ["minimal", "low", "medium", "high"];
+const XHIGH_EFFORT_LEVEL: ThinkingLevel = "xhigh";
+const EFFORT_ORDINAL: readonly ThinkingLevel[] = ["minimal", "low", "medium", "high", "xhigh"];
+const DEFAULT_EFFORT: ThinkingLevel = "high";
+const RECOMMENDED_EFFORT_SUFFIX = "  (recommended)";
+
+// 消息
+const MSG_ADVISOR_DISABLED = "Advisor disabled";
+const MSG_REQUIRES_INTERACTIVE = "/advisor requires interactive mode";
+const MSG_ADVISOR_NUDGE = "Please advise on the executor's situation above.";
+const MSG_PERSIST_FAILED = "Failed to save advisor selection";
+const ERR_NO_MODEL = "No advisor model is configured. Use /advisor to enable one.";
+const ERR_CALL_ABORTED = "Advisor call was cancelled.";
+const ERR_EMPTY_RESPONSE = "Advisor returned no text content.";
+const ERR_NO_MODEL_SELECTED = "no advisor model selected";
+const ERR_EMPTY_RESPONSE_DETAIL = "empty response";
+const ERR_ABORTED_DETAIL = "aborted";
+const ERR_UNKNOWN = "unknown error";
+
+// 系统提示词
+const ADVISOR_SYSTEM_PROMPT = [
+  "You are a senior reviewer providing guidance to a working agent.",
+  "The working agent will share their full conversation context with you.",
+  "Your role is to provide strategic guidance, identify blind spots, suggest better approaches, or warn about risks.",
+  "Be concise but thorough. Focus on high-level strategy and critical issues.",
+  "Do not attempt to do the work yourself — provide guidance the working agent can act on.",
+].join(" ");
+
+// ============== 配置持久化 ==============
+interface AdvisorConfig {
+  modelKey?: string;
+  effort?: ThinkingLevel;
+  disabledForModels?: Array<string | { model: string; minEffort?: ThinkingLevel }>;
+}
+
+function getConfigPath(): string {
+  const configDir = join(process.env.HOME || process.env.USERPROFILE || "~", ".aicode-cli", "agent", "aicode-advisor");
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  }
+  return join(configDir, "advisor.json");
+}
+
+function loadAdvisorConfig(): AdvisorConfig {
+  const configPath = getConfigPath();
+  try {
+    if (existsSync(configPath)) {
+      const content = readFileSync(configPath, "utf-8");
+      const config: AdvisorConfig = JSON.parse(content);
+      return config;
+    }
+  } catch {
+    // Ignore read errors
+  }
+  return {};
+}
+
+function saveAdvisorConfig(key: string | undefined, effort: ThinkingLevel | undefined): boolean {
+  const configPath = getConfigPath();
+  const existing = loadAdvisorConfig();
+  const config: AdvisorConfig = { ...existing };
+  
+  if (key) config.modelKey = key;
+  else delete config.modelKey;
+  
+  if (effort) config.effort = effort;
+  else delete config.effort;
+  
+  try {
+    writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseModelKey(key: string): { provider: string; modelId: string } | undefined {
+  const idx = key.indexOf(":");
+  if (idx < 1) return undefined;
+  return { provider: key.slice(0, idx), modelId: key.slice(idx + 1) };
+}
+
+// ============== 运行时状态 ==============
+let selectedAdvisor: Model<Api> | undefined;
+let selectedAdvisorEffort: ThinkingLevel | undefined;
+let disabledForModelsCache: Array<string | { model: string; minEffort?: ThinkingLevel }> = [];
+
+function getAdvisorModel(): Model<Api> | undefined {
+  return selectedAdvisor;
+}
+
+function setAdvisorModel(model: Model<Api> | undefined): void {
+  selectedAdvisor = model;
+}
+
+function getAdvisorEffort(): ThinkingLevel | undefined {
+  return selectedAdvisorEffort;
+}
+
+function setAdvisorEffort(effort: ThinkingLevel | undefined): void {
+  selectedAdvisorEffort = effort;
+}
+
+function setDisabledForModels(models: Array<string | { model: string; minEffort?: ThinkingLevel }>): void {
+  disabledForModelsCache = models;
+}
+
+// ============== 工具清单序列化 ==============
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => (v === undefined ? "null" : stableStringify(v))).join(",")}]`;
+  }
+  const obj = value as Record<string, unknown>;
+  const entries: string[] = [];
+  for (const k of Object.keys(obj).sort()) {
+    const v = obj[k];
+    if (v === undefined) continue;
+    entries.push(`${JSON.stringify(k)}:${stableStringify(v)}`);
+  }
+  return `{${entries.join(",")}}`;
+}
+
+function buildInventoryBlock(tools: ToolInfo[]): string {
+  return tools
+    .map((t) => `### ${t.name}\n${t.description}\n\nParameters: ${stableStringify(t.parameters)}`)
+    .join("\n\n---\n\n");
+}
+
+function stripInflightAdvisorCall(messages: Message[]): Message[] {
+  if (messages.length === 0) return messages;
+  const last = messages[messages.length - 1];
+  if (last.role !== "assistant") return messages;
+  const filtered = last.content.filter((c) => !(c.type === "toolCall" && c.name === ADVISOR_TOOL_NAME));
+  if (filtered.length === last.content.length) return messages;
+  if (filtered.length === 0) return messages.slice(0, -1);
+  return [...messages.slice(0, -1), { ...last, content: filtered }];
+}
+
+function ensureUserTailForAdvisor(messages: Message[]): Message[] {
+  if (messages.length === 0) return messages;
+  const last = messages[messages.length - 1];
+  if (last.role !== "assistant") return messages;
+  const nudge: Message = {
+    role: "user",
+    content: [{ type: "text", text: MSG_ADVISOR_NUDGE }],
+    timestamp: Date.now(),
+  };
+  return [...messages, nudge];
+}
+
+function getInventoryMessage(tools: ToolInfo[]): Message | undefined {
+  if (tools.length === 0) return undefined;
+  const sorted = [...tools].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const text = `## Available Executor Tools\n\n${buildInventoryBlock(sorted)}`;
+  return {
+    role: "user",
+    content: [{ type: "text", text }],
+    timestamp: Date.now(),
+  };
+}
+
+// ============== 会话恢复 ==============
+function restoreAdvisorState(ctx: ExtensionContext, pi: ExtensionAPI): void {
+  const config = loadAdvisorConfig();
+  setDisabledForModels(config.disabledForModels || []);
+
+  if (!config.modelKey) return;
+
+  const parsed = parseModelKey(config.modelKey);
+  if (!parsed) return;
+
+  const model = ctx.modelRegistry.find(parsed.provider, parsed.modelId);
+  if (!model) {
+    if (ctx.hasUI) {
+      ctx.ui.notify(`Previously configured advisor model ${config.modelKey} is no longer available`, "warning");
+    }
+    return;
+  }
+
+  setAdvisorModel(model);
+  if (config.effort) {
+    setAdvisorEffort(config.effort);
+  }
+
+  if (isExecutorBlocked(ctx, pi.getThinkingLevel())) {
+    if (ctx.hasUI) {
+      ctx.ui.notify(`Advisor restored: ${model.provider}:${model.id} (inactive for current executor)`, "info");
+    }
+    return;
+  }
+
+  const active = pi.getActiveTools();
+  if (!active.includes(ADVISOR_TOOL_NAME)) {
+    pi.setActiveTools([...active, ADVISOR_TOOL_NAME]);
+  }
+
+  if (ctx.hasUI) {
+    ctx.ui.notify(`Advisor restored: ${model.provider}:${model.id}${config.effort ? `, ${config.effort}` : ""}`, "info");
+  }
+}
+
+// ============== Advisor 工具执行 ==============
+interface AdvisorDetails {
+  advisorModel?: string;
+  effort?: ThinkingLevel;
+  usage?: Usage;
+  stopReason?: StopReason;
+  errorMessage?: string;
+}
+
+function buildErrorResult(
+  advisorLabel: string | undefined,
+  userText: string,
+  errorMessage: string,
+): AgentToolResult<AdvisorDetails> {
+  const effort = getAdvisorEffort();
+  return {
+    content: [{ type: "text", text: userText }],
+    details: advisorLabel ? { advisorModel: advisorLabel, effort, errorMessage } : { effort, errorMessage },
+  };
+}
+
+async function executeAdvisor(
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<AdvisorDetails> | undefined,
+): Promise<AgentToolResult<AdvisorDetails>> {
+  const advisor = getAdvisorModel();
+  if (!advisor) {
+    return buildErrorResult(undefined, ERR_NO_MODEL, ERR_NO_MODEL_SELECTED);
+  }
+  const advisorLabel = `${advisor.provider}:${advisor.id}`;
+  const effort = getAdvisorEffort();
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(advisor);
+  if (!auth.ok) {
+    return buildErrorResult(advisorLabel, `Advisor (${advisorLabel}) is misconfigured: ${auth.error}`, auth.error);
+  }
+  if (!auth.apiKey) {
+    return buildErrorResult(advisorLabel, `Advisor (${advisorLabel}) has no API key available.`, `no API key for ${advisor.provider}`);
+  }
+
+  const { messages: sessionMessages } = buildSessionContext(
+    ctx.sessionManager.getEntries(),
+    ctx.sessionManager.getLeafId(),
+  );
+  const branchMessages = ensureUserTailForAdvisor(stripInflightAdvisorCall(convertToLlm(sessionMessages)));
+  const inventoryMessage = getInventoryMessage(pi.getAllTools());
+  const messages: Message[] = inventoryMessage ? [inventoryMessage, ...branchMessages] : branchMessages;
+
+  onUpdate?.({
+    content: [{ type: "text", text: `Consulting advisor (${advisorLabel}${effort ? `, ${effort}` : ""})…` }],
+    details: { advisorModel: advisorLabel, effort },
+  });
+
+  try {
+    const response = await completeSimple(
+      advisor,
+      { systemPrompt: ADVISOR_SYSTEM_PROMPT, messages, tools: [] },
+      { apiKey: auth.apiKey, headers: auth.headers, signal, reasoning: effort },
+    );
+
+    if (response.stopReason === "aborted") {
+      return {
+        content: [{ type: "text", text: ERR_CALL_ABORTED }],
+        details: {
+          advisorModel: advisorLabel,
+          effort,
+          usage: response.usage,
+          stopReason: response.stopReason,
+          errorMessage: response.errorMessage ?? ERR_ABORTED_DETAIL,
+        },
+      };
+    }
+
+    if (response.stopReason === "error") {
+      return {
+        content: [{ type: "text", text: `Advisor call failed: ${response.errorMessage}` }],
+        details: {
+          advisorModel: advisorLabel,
+          effort,
+          usage: response.usage,
+          stopReason: response.stopReason,
+          errorMessage: response.errorMessage,
+        },
+      };
+    }
+
+    const advisorText = response.content
+      .filter((c): c is { type: "text"; text: string } => c.type === "text")
+      .map((c) => c.text)
+      .join("\n")
+      .trim();
+
+    if (!advisorText) {
+      return {
+        content: [{ type: "text", text: ERR_EMPTY_RESPONSE }],
+        details: {
+          advisorModel: advisorLabel,
+          effort,
+          usage: response.usage,
+          stopReason: response.stopReason,
+          errorMessage: ERR_EMPTY_RESPONSE_DETAIL,
+        },
+      };
+    }
+
+    return {
+      content: [{ type: "text", text: advisorText }],
+      details: {
+        advisorModel: advisorLabel,
+        effort,
+        usage: response.usage,
+        stopReason: response.stopReason,
+      },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return buildErrorResult(advisorLabel, `Advisor call threw: ${message}`, message);
+  }
+}
+
+// ============== 工具注册 ==============
+const AdvisorParams = Type.Object({});
+
+const ADVISOR_DESCRIPTION =
+  "Escalate to a stronger reviewer model for guidance. When you need " +
+  "stronger judgment — a complex decision, an ambiguous failure, a problem " +
+  "you're circling without progress — escalate to the advisor model for " +
+  "guidance, then resume. Takes NO parameters — when you call advisor(), " +
+  "your entire conversation history is automatically forwarded. The advisor " +
+  "sees the task, every tool call you've made, every result you've seen.";
+
+const DEFAULT_PROMPT_SNIPPET =
+  "Escalate to a stronger reviewer model for guidance when stuck, before substantive work, or before declaring done";
+
+const DEFAULT_PROMPT_GUIDELINES: string[] = [
+  "Call `advisor` BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption.",
+  "Also call `advisor` when you believe the task is complete. BEFORE this call, make your deliverable durable.",
+  "Also call `advisor` when stuck — errors recurring, approach not converging, results that don't fit.",
+  "On tasks longer than a few steps, call `advisor` at least once before committing to an approach and once before declaring done.",
+  "Give the advisor's advice serious weight. Adapt if empirical evidence contradicts it.",
+  "If advisor points another direction than your data, reconcile with another `advisor` call before switching.",
+];
+
+function registerAdvisorTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: ADVISOR_TOOL_NAME,
+    label: TOOL_LABEL,
+    description: ADVISOR_DESCRIPTION,
+    promptSnippet: DEFAULT_PROMPT_SNIPPET,
+    promptGuidelines: DEFAULT_PROMPT_GUIDELINES,
+    parameters: AdvisorParams,
+    async execute(_toolCallId, _params, signal, onUpdate, ctx) {
+      return executeAdvisor(ctx, pi, signal, onUpdate);
+    },
+  });
+}
+
+// ============== before_agent_start 处理器 ==============
+function registerAdvisorBeforeAgentStart(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", async (_event, ctx) => {
+    const advisor = getAdvisorModel();
+    if (!advisor) {
+      const active = pi.getActiveTools();
+      if (active.includes(ADVISOR_TOOL_NAME)) {
+        pi.setActiveTools(active.filter((n) => n !== ADVISOR_TOOL_NAME));
+      }
+      return;
+    }
+    const blocked = isExecutorBlocked(ctx, pi.getThinkingLevel());
+    const active = pi.getActiveTools();
+    const hasTool = active.includes(ADVISOR_TOOL_NAME);
+    if (blocked && hasTool) {
+      pi.setActiveTools(active.filter((n) => n !== ADVISOR_TOOL_NAME));
+    } else if (!blocked && !hasTool) {
+      pi.setActiveTools([...active, ADVISOR_TOOL_NAME]);
+    }
+  });
+}
+
+// ============== model_select 处理器 ==============
+function modelKey(m: { provider: string; id: string }): string {
+  return `${m.provider}:${m.id}`;
+}
+
+function isModelBlocked(model: Model<Api> | undefined, thinkingLevel?: string): boolean {
+  if (!model) return false;
+  const key = modelKey(model);
+  for (const entry of disabledForModelsCache) {
+    if (typeof entry === "string") {
+      if (entry === key) return true;
+    } else {
+      if (entry.model !== key) continue;
+      if (entry.minEffort === undefined) return true;
+      const thresholdOrdinal = EFFORT_ORDINAL.indexOf(entry.minEffort);
+      const executorOrdinal = EFFORT_ORDINAL.indexOf(thinkingLevel as ThinkingLevel);
+      if (executorOrdinal >= thresholdOrdinal) return true;
+    }
+  }
+  return false;
+}
+
+function isExecutorBlocked(ctx: ExtensionContext, thinkingLevel?: string): boolean {
+  return isModelBlocked(ctx?.model, thinkingLevel);
+}
+
+function registerModelSelectHandler(pi: ExtensionAPI): void {
+  pi.on("model_select", async (event, ctx) => {
+    if (event.source === "restore") return;
+
+    const advisor = getAdvisorModel();
+    if (!advisor) return;
+
+    const blocked = isModelBlocked(event.model, pi.getThinkingLevel());
+    const active = pi.getActiveTools();
+    const hasTool = active.includes(ADVISOR_TOOL_NAME);
+
+    if (blocked && hasTool) {
+      pi.setActiveTools(active.filter((n) => n !== ADVISOR_TOOL_NAME));
+      if (ctx.hasUI) {
+        ctx.ui.notify(`Advisor disabled for ${modelKey(event.model)}`, "info");
+      }
+    } else if (!blocked && !hasTool) {
+      pi.setActiveTools([...active, ADVISOR_TOOL_NAME]);
+      if (ctx.hasUI) {
+        ctx.ui.notify(`Advisor restored: ${modelKey(advisor)}`, "info");
+      }
+    }
+  });
+}
+
+// ============== /advisor 命令 UI (使用原版 SelectList 实现) ==============
+const MAX_VISIBLE_ROWS = 10;
+const NAV_HINT = "↑↓ navigate • enter select • esc cancel";
+
+const ADVISOR_HEADER_TITLE = "Advisor Tool";
+const ADVISOR_HEADER_PROSE_1 =
+  "当工作模型遇到复杂决策、难以判断的失败、或反复尝试却无法推进的困境时，" +
+  "可以向更强的审查模型征求第二意见。审查模型在云端运行，会额外消耗 Token。";
+const ADVISOR_HEADER_PROSE_2 =
+  "最佳实践：主模型选用速度型，审查模型选用能力型 —— 既能获得顶级模型的判断力，" +
+  "又能控制 Token 成本。";
+
+const ADVISOR_HELP_TITLE = "💡 使用场景";
+const ADVISOR_HELP_EXAMPLES = [
+  "  • 复杂决策前：「这个架构方案有没有潜在风险？」",
+  "  • 遇到模糊错误：「为什么测试一直失败？我是不是漏了什么？」",
+  "  • 反复尝试无果：「我已经试了 3 种方法都不行，请帮我分析」",
+  "  • 完成任务前：「我准备提交了，请帮我检查有没有遗漏」",
+  "  • 长任务关键节点：「我打算这么做，请确认方向是否正确」",
+];
+
+const EFFORT_HEADER_TITLE = "Reasoning Level";
+const EFFORT_HEADER_PROSE =
+  "推理能力级别越高，判断越深入，但 Token 消耗也越多。";
+
+function selectListTheme(theme: Theme) {
+  return {
+    selectedPrefix: (t: string) => theme.bg("selectedBg", theme.fg("accent", t)),
+    selectedText: (t: string) => theme.bg("selectedBg", theme.bold(t)),
+    description: (t: string) => theme.fg("muted", t),
+    scrollInfo: (t: string) => theme.fg("dim", t),
+    noMatch: (t: string) => theme.fg("warning", t),
+  };
+}
+
+function buildSelectPanel(theme: Theme, title: string, proseLines: string[], selectList: SelectList, helpLines?: string[]): Container {
+  const container = new Container();
+  const border = () => new DynamicBorder((s: string) => theme.fg("accent", s));
+
+  container.addChild(border());
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+  container.addChild(new Spacer(1));
+  for (const line of proseLines) {
+    container.addChild(new Text(line, 1, 0));
+    container.addChild(new Spacer(1));
+  }
+  
+  // 添加帮助信息（如果有）
+  if (helpLines && helpLines.length > 0) {
+    container.addChild(new Text(theme.fg("accent", theme.bold(helpLines[0])), 1, 0));
+    container.addChild(new Spacer(1));
+    for (let i = 1; i < helpLines.length; i++) {
+      container.addChild(new Text(helpLines[i], 1, 0));
+    }
+    container.addChild(new Spacer(1));
+  }
+  
+  container.addChild(selectList);
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(theme.fg("dim", NAV_HINT), 1, 0));
+  container.addChild(new Spacer(1));
+  container.addChild(border());
+  return container;
+}
+
+function showAdvisorPicker(
+  ctx: ExtensionContext,
+  items: SelectItem[],
+): Promise<string | null> {
+  return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+    const selectList = new SelectList(items, Math.min(items.length, MAX_VISIBLE_ROWS), selectListTheme(theme));
+    selectList.onSelect = (item) => done(item.value);
+    selectList.onCancel = () => done(null);
+
+    const container = buildSelectPanel(
+      theme,
+      ADVISOR_HEADER_TITLE,
+      [ADVISOR_HEADER_PROSE_1, ADVISOR_HEADER_PROSE_2],
+      selectList,
+      [ADVISOR_HELP_TITLE, ...ADVISOR_HELP_EXAMPLES],
+    );
+
+    return {
+      render: (w: number) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        selectList.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+}
+
+function showEffortPicker(
+  ctx: ExtensionContext,
+  items: SelectItem[],
+  currentEffort?: ThinkingLevel,
+  defaultEffort?: ThinkingLevel,
+): Promise<string | null> {
+  return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+    const selectList = new SelectList(items, Math.min(items.length, MAX_VISIBLE_ROWS), selectListTheme(theme));
+    const preferredIdx = currentEffort ? items.findIndex((item) => item.value === currentEffort) : -1;
+    selectList.setSelectedIndex(
+      preferredIdx >= 0 ? preferredIdx : items.findIndex((item) => item.value === defaultEffort),
+    );
+    selectList.onSelect = (item) => done(item.value);
+    selectList.onCancel = () => done(null);
+
+    const container = buildSelectPanel(theme, EFFORT_HEADER_TITLE, [EFFORT_HEADER_PROSE], selectList);
+
+    return {
+      render: (w: number) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        selectList.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+}
+
+// ============== /advisor 命令注册 ==============
+function registerAdvisorCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("advisor", {
+    description: "Configure the advisor model for the advisor-strategy pattern",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify(MSG_REQUIRES_INTERACTIVE, "error");
+        return;
+      }
+
+      const availableModels = ctx.modelRegistry.getAvailable();
+      const current = getAdvisorModel();
+      const currentKey = current ? modelKey(current) : undefined;
+
+      const items: SelectItem[] = availableModels.map((m) => {
+        const key = modelKey(m);
+        const check = key === currentKey ? CHECKMARK : "";
+        return { value: key, label: `${m.name}  (${m.provider})${check}` };
+      });
+      items.push({
+        value: NO_ADVISOR_VALUE,
+        label: currentKey === undefined ? `No advisor${CHECKMARK}` : "No advisor",
+      });
+
+      const choice = await showAdvisorPicker(ctx, items);
+      if (!choice) {
+        return;
+      }
+
+      const activeTools = pi.getActiveTools();
+      const activeHas = activeTools.includes(ADVISOR_TOOL_NAME);
+
+      if (choice === NO_ADVISOR_VALUE) {
+        if (!saveAdvisorConfig(undefined, undefined)) {
+          ctx.ui.notify(MSG_PERSIST_FAILED, "error");
+          return;
+        }
+        setAdvisorModel(undefined);
+        setAdvisorEffort(undefined);
+        if (activeHas) {
+          pi.setActiveTools(activeTools.filter((n) => n !== ADVISOR_TOOL_NAME));
+        }
+        ctx.ui.notify(MSG_ADVISOR_DISABLED, "info");
+        return;
+      }
+
+      const picked = availableModels.find((m) => modelKey(m) === choice);
+      if (!picked) {
+        ctx.ui.notify(`Advisor selection not found: ${choice}`, "error");
+        return;
+      }
+
+      // Effort picker for reasoning-capable models
+      let effortChoice: ThinkingLevel | undefined;
+      if (picked.reasoning) {
+        const levels = getSupportedThinkingLevels(picked).includes("xhigh")
+          ? [...BASE_EFFORT_LEVELS, XHIGH_EFFORT_LEVEL]
+          : BASE_EFFORT_LEVELS;
+
+        const effortItems: SelectItem[] = [
+          { value: OFF_VALUE, label: "off" },
+          ...levels.map((level) => ({
+            value: level,
+            label: level === DEFAULT_EFFORT ? `${level}${RECOMMENDED_EFFORT_SUFFIX}` : level,
+          })),
+        ];
+
+        const effortResult = await showEffortPicker(ctx, effortItems, getAdvisorEffort(), DEFAULT_EFFORT);
+        if (!effortResult) {
+          return;
+        }
+        effortChoice = effortResult === OFF_VALUE ? undefined : (effortResult as ThinkingLevel);
+      }
+
+      if (!saveAdvisorConfig(modelKey(picked), effortChoice)) {
+        ctx.ui.notify(MSG_PERSIST_FAILED, "error");
+        return;
+      }
+      setAdvisorEffort(effortChoice);
+      setAdvisorModel(picked);
+
+      const activeToolsNow = pi.getActiveTools();
+      const activeHasNow = activeToolsNow.includes(ADVISOR_TOOL_NAME);
+      const blocked = isExecutorBlocked(ctx, pi.getThinkingLevel());
+      
+      if (!activeHasNow && !blocked) {
+        pi.setActiveTools([...activeToolsNow, ADVISOR_TOOL_NAME]);
+      }
+      
+      if (blocked) {
+        ctx.ui.notify(`Advisor: ${modelKey(picked)}${effortChoice ? `, ${effortChoice}` : ""} (inactive for current executor)`, "info");
+      } else {
+        ctx.ui.notify(`Advisor: ${modelKey(picked)}${effortChoice ? `, ${effortChoice}` : ""}`, "info");
+      }
+    },
+  });
+}
+
+// ============== 导出 ==============
+export default function (pi: ExtensionAPI) {
+  registerAdvisorTool(pi);
+  registerAdvisorCommand(pi);
+  registerAdvisorBeforeAgentStart(pi);
+  registerModelSelectHandler(pi);
+
+  pi.on("session_start", async (_event, ctx) => {
+    restoreAdvisorState(ctx, pi);
+  });
+}