@ia-ccun/code-agent-cli 0.0.52 → 0.0.53-beta.2

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

@@ -9,10 +9,14 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import type { Api, Model, StopReason, Usage } from "@earendil-works/pi-ai";
-import { completeSimple, getSupportedThinkingLevels, type Message, type ThinkingLevel } from "@earendil-works/pi-ai";
+import {
+  completeSimple,
+  getSupportedThinkingLevels,
+  type Message,
+  type ThinkingLevel,
+} from "@earendil-works/pi-ai/compat";
 import {
   type AgentToolResult,
   type AgentToolUpdateCallback,
@@ -24,12 +28,7 @@ import {
 } 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 { Container, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 // ============== 常量 ==============
@@ -38,9 +37,20 @@ 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 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 EFFORT_ORDINAL: readonly ThinkingLevel[] = [
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+];
 const DEFAULT_EFFORT: ThinkingLevel = "high";
 const RECOMMENDED_EFFORT_SUFFIX = "  (recommended)";
 
@@ -49,15 +59,13 @@ 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_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.",
@@ -70,11 +78,18 @@ const ADVISOR_SYSTEM_PROMPT = [
 interface AdvisorConfig {
   modelKey?: string;
   effort?: ThinkingLevel;
-  disabledForModels?: Array<string | { model: string; minEffort?: 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");
+  const configDir = join(
+    process.env.HOME || process.env.USERPROFILE || "~",
+    ".aicode-cli",
+    "agent",
+    "aicode-advisor",
+  );
   if (!existsSync(configDir)) {
     mkdirSync(configDir, { recursive: true, mode: 0o700 });
   }
@@ -95,17 +110,20 @@ function loadAdvisorConfig(): AdvisorConfig {
   return {};
 }
 
-function saveAdvisorConfig(key: string | undefined, effort: ThinkingLevel | undefined): boolean {
+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;
@@ -114,7 +132,9 @@ function saveAdvisorConfig(key: string | undefined, effort: ThinkingLevel | unde
   }
 }
 
-function parseModelKey(key: string): { provider: string; modelId: string } | undefined {
+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) };
@@ -123,7 +143,9 @@ function parseModelKey(key: string): { provider: string; modelId: string } | und
 // ============== 运行时状态 ==============
 let selectedAdvisor: Model<Api> | undefined;
 let selectedAdvisorEffort: ThinkingLevel | undefined;
-let disabledForModelsCache: Array<string | { model: string; minEffort?: ThinkingLevel }> = [];
+let disabledForModelsCache: Array<
+  string | { model: string; minEffort?: ThinkingLevel }
+> = [];
 
 function getAdvisorModel(): Model<Api> | undefined {
   return selectedAdvisor;
@@ -141,11 +163,26 @@ function setAdvisorEffort(effort: ThinkingLevel | undefined): void {
   selectedAdvisorEffort = effort;
 }
 
-function setDisabledForModels(models: Array<string | { model: string; minEffort?: ThinkingLevel }>): void {
+function setDisabledForModels(
+  models: Array<string | { model: string; minEffort?: ThinkingLevel }>,
+): void {
   disabledForModelsCache = models;
 }
 
 // ============== 工具清单序列化 ==============
+/**
+ * stableStringify - 稳定序列化对象（键排序）
+ *
+ * 用于序列化工具参数，确保参数对象的键顺序一致，便于对比和展示。
+ *
+ * 功能说明：
+ * - 处理 null 和非对象类型：直接 JSON.stringify
+ * - 处理数组：递归序列化每个元素，undefined 替换为 "null"
+ * - 处理对象：键排序后序列化，跳过 undefined 值
+ *
+ * @param value - 要序列化的值
+ * @returns 稳定的 JSON 字符串（键排序）
+ */
 function stableStringify(value: unknown): string {
   if (value === null || typeof value !== "object") {
     return JSON.stringify(value);
@@ -165,7 +202,10 @@ function stableStringify(value: unknown): string {
 
 function buildInventoryBlock(tools: ToolInfo[]): string {
   return tools
-    .map((t) => `### ${t.name}\n${t.description}\n\nParameters: ${stableStringify(t.parameters)}`)
+    .map(
+      (t) =>
+        `### ${t.name}\n${t.description}\n\nParameters: ${stableStringify(t.parameters)}`,
+    )
     .join("\n\n---\n\n");
 }
 
@@ -173,7 +213,9 @@ 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));
+  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 }];
@@ -193,7 +235,9 @@ function ensureUserTailForAdvisor(messages: Message[]): Message[] {
 
 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 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",
@@ -215,7 +259,10 @@ function restoreAdvisorState(ctx: ExtensionContext, pi: ExtensionAPI): void {
   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");
+      ctx.ui.notify(
+        `Previously configured advisor model ${config.modelKey} is no longer available`,
+        "warning",
+      );
     }
     return;
   }
@@ -227,7 +274,10 @@ function restoreAdvisorState(ctx: ExtensionContext, pi: ExtensionAPI): void {
 
   if (isExecutorBlocked(ctx, pi.getThinkingLevel())) {
     if (ctx.hasUI) {
-      ctx.ui.notify(`Advisor restored: ${model.provider}:${model.id} (inactive for current executor)`, "info");
+      ctx.ui.notify(
+        `Advisor restored: ${model.provider}:${model.id} (inactive for current executor)`,
+        "info",
+      );
     }
     return;
   }
@@ -238,7 +288,10 @@ function restoreAdvisorState(ctx: ExtensionContext, pi: ExtensionAPI): void {
   }
 
   if (ctx.hasUI) {
-    ctx.ui.notify(`Advisor restored: ${model.provider}:${model.id}${config.effort ? `, ${config.effort}` : ""}`, "info");
+    ctx.ui.notify(
+      `Advisor restored: ${model.provider}:${model.id}${config.effort ? `, ${config.effort}` : ""}`,
+      "info",
+    );
   }
 }
 
@@ -259,7 +312,9 @@ function buildErrorResult(
   const effort = getAdvisorEffort();
   return {
     content: [{ type: "text", text: userText }],
-    details: advisorLabel ? { advisorModel: advisorLabel, effort, errorMessage } : { effort, errorMessage },
+    details: advisorLabel
+      ? { advisorModel: advisorLabel, effort, errorMessage }
+      : { effort, errorMessage },
   };
 }
 
@@ -278,22 +333,39 @@ async function executeAdvisor(
 
   const auth = await ctx.modelRegistry.getApiKeyAndHeaders(advisor);
   if (!auth.ok) {
-    return buildErrorResult(advisorLabel, `Advisor (${advisorLabel}) is misconfigured: ${auth.error}`, auth.error);
+    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}`);
+    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 branchMessages = ensureUserTailForAdvisor(
+    stripInflightAdvisorCall(convertToLlm(sessionMessages)),
+  );
   const inventoryMessage = getInventoryMessage(pi.getAllTools());
-  const messages: Message[] = inventoryMessage ? [inventoryMessage, ...branchMessages] : branchMessages;
+  const messages: Message[] = inventoryMessage
+    ? [inventoryMessage, ...branchMessages]
+    : branchMessages;
 
   onUpdate?.({
-    content: [{ type: "text", text: `Consulting advisor (${advisorLabel}${effort ? `, ${effort}` : ""})…` }],
+    content: [
+      {
+        type: "text",
+        text: `Consulting advisor (${advisorLabel}${effort ? `, ${effort}` : ""})…`,
+      },
+    ],
     details: { advisorModel: advisorLabel, effort },
   });
 
@@ -319,7 +391,12 @@ async function executeAdvisor(
 
     if (response.stopReason === "error") {
       return {
-        content: [{ type: "text", text: `Advisor call failed: ${response.errorMessage}` }],
+        content: [
+          {
+            type: "text",
+            text: `Advisor call failed: ${response.errorMessage}`,
+          },
+        ],
         details: {
           advisorModel: advisorLabel,
           effort,
@@ -331,8 +408,11 @@ async function executeAdvisor(
     }
 
     const advisorText = response.content
-      .filter((c): c is { type: "text"; text: string } => c.type === "text")
-      .map((c) => c.text)
+      .filter(
+        (c: { type: string }): c is { type: "text"; text: string } =>
+          c.type === "text",
+      )
+      .map((c: { type: "text"; text: string }) => c.text)
       .join("\n")
       .trim();
 
@@ -360,7 +440,11 @@ async function executeAdvisor(
     };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    return buildErrorResult(advisorLabel, `Advisor call threw: ${message}`, message);
+    return buildErrorResult(
+      advisorLabel,
+      `Advisor call threw: ${message}`,
+      message,
+    );
   }
 }
 
@@ -428,7 +512,10 @@ function modelKey(m: { provider: string; id: string }): string {
   return `${m.provider}:${m.id}`;
 }
 
-function isModelBlocked(model: Model<Api> | undefined, thinkingLevel?: string): boolean {
+function isModelBlocked(
+  model: Model<Api> | undefined,
+  thinkingLevel?: string,
+): boolean {
   if (!model) return false;
   const key = modelKey(model);
   for (const entry of disabledForModelsCache) {
@@ -438,14 +525,19 @@ function isModelBlocked(model: Model<Api> | undefined, thinkingLevel?: string):
       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);
+      const executorOrdinal = EFFORT_ORDINAL.indexOf(
+        thinkingLevel as ThinkingLevel,
+      );
       if (executorOrdinal >= thresholdOrdinal) return true;
     }
   }
   return false;
 }
 
-function isExecutorBlocked(ctx: ExtensionContext, thinkingLevel?: string): boolean {
+function isExecutorBlocked(
+  ctx: ExtensionContext,
+  thinkingLevel?: string,
+): boolean {
   return isModelBlocked(ctx?.model, thinkingLevel);
 }
 
@@ -501,7 +593,8 @@ const EFFORT_HEADER_PROSE =
 
 function selectListTheme(theme: Theme) {
   return {
-    selectedPrefix: (t: string) => theme.bg("selectedBg", theme.fg("accent", t)),
+    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),
@@ -509,7 +602,13 @@ function selectListTheme(theme: Theme) {
   };
 }
 
-function buildSelectPanel(theme: Theme, title: string, proseLines: string[], selectList: SelectList, helpLines?: string[]): Container {
+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));
 
@@ -521,17 +620,19 @@ function buildSelectPanel(theme: Theme, title: string, proseLines: string[], sel
     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 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));
@@ -545,7 +646,11 @@ function showAdvisorPicker(
   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));
+    const selectList = new SelectList(
+      items,
+      Math.min(items.length, MAX_VISIBLE_ROWS),
+      selectListTheme(theme),
+    );
     selectList.onSelect = (item) => done(item.value);
     selectList.onCancel = () => done(null);
 
@@ -575,15 +680,28 @@ function showEffortPicker(
   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;
+    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),
+      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);
+    const container = buildSelectPanel(
+      theme,
+      EFFORT_HEADER_TITLE,
+      [EFFORT_HEADER_PROSE],
+      selectList,
+    );
 
     return {
       render: (w: number) => container.render(w),
@@ -617,7 +735,8 @@ function registerAdvisorCommand(pi: ExtensionAPI): void {
       });
       items.push({
         value: NO_ADVISOR_VALUE,
-        label: currentKey === undefined ? `No advisor${CHECKMARK}` : "No advisor",
+        label:
+          currentKey === undefined ? `No advisor${CHECKMARK}` : "No advisor",
       });
 
       const choice = await showAdvisorPicker(ctx, items);
@@ -659,15 +778,26 @@ function registerAdvisorCommand(pi: ExtensionAPI): void {
           { value: OFF_VALUE, label: "off" },
           ...levels.map((level) => ({
             value: level,
-            label: level === DEFAULT_EFFORT ? `${level}${RECOMMENDED_EFFORT_SUFFIX}` : level,
+            label:
+              level === DEFAULT_EFFORT
+                ? `${level}${RECOMMENDED_EFFORT_SUFFIX}`
+                : level,
           })),
         ];
 
-        const effortResult = await showEffortPicker(ctx, effortItems, getAdvisorEffort(), DEFAULT_EFFORT);
+        const effortResult = await showEffortPicker(
+          ctx,
+          effortItems,
+          getAdvisorEffort(),
+          DEFAULT_EFFORT,
+        );
         if (!effortResult) {
           return;
         }
-        effortChoice = effortResult === OFF_VALUE ? undefined : (effortResult as ThinkingLevel);
+        effortChoice =
+          effortResult === OFF_VALUE
+            ? undefined
+            : (effortResult as ThinkingLevel);
       }
 
       if (!saveAdvisorConfig(modelKey(picked), effortChoice)) {
@@ -680,15 +810,21 @@ function registerAdvisorCommand(pi: ExtensionAPI): void {
       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");
+        ctx.ui.notify(
+          `Advisor: ${modelKey(picked)}${effortChoice ? `, ${effortChoice}` : ""} (inactive for current executor)`,
+          "info",
+        );
       } else {
-        ctx.ui.notify(`Advisor: ${modelKey(picked)}${effortChoice ? `, ${effortChoice}` : ""}`, "info");
+        ctx.ui.notify(
+          `Advisor: ${modelKey(picked)}${effortChoice ? `, ${effortChoice}` : ""}`,
+          "info",
+        );
       }
     },
   });

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

@@ -0,0 +1,101 @@
+/**
+ * @author: xujianjiang
+ * aicode-banner extension
+ *
+ * 在 `session_start` 触发时打印启动 banner (含快捷命令、常用提示词、技能).
+ * 替代原 cli.js 启动时同步 `console.log(generateBanner(...))`:
+ *   1) 避开 RPC 模式 stdout 污染 (banner 现在走 TUI notify, 不写 stdout)
+ *   2) chdir 到 homedir 之后才触发, 配合 cli.js 入口的防御性 chdir
+ *   3) 只在首次 startup 时打印; resume/new/fork 不重复
+ *
+ * ponytail: 用 ctx.ui.notify 走 TUI 通知路径, 不直写 console.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const COLOR_THEMES = [
+	{ name: "deep-cyan", hex: "#2e7d8c" },
+	{ name: "dark-cyan", hex: "#399aad" },
+	{ name: "cyan", hex: "#49bccf" },
+	{ name: "light-cyan", hex: "#5ec9db" },
+	{ name: "bright-cyan", hex: "#73d6e8" },
+	{ name: "pale-cyan", hex: "#8ae3f0" },
+	{ name: "faint-cyan", hex: "#a0f0f8" },
+];
+
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+	const h = hex.replace("#", "");
+	return {
+		r: parseInt(h.slice(0, 2), 16),
+		g: parseInt(h.slice(2, 4), 16),
+		b: parseInt(h.slice(4, 6), 16),
+	};
+}
+
+function getRotatedColorTheme(): string {
+	const day = new Date().getDay();
+	return COLOR_THEMES[day % COLOR_THEMES.length].hex;
+}
+
+// 最小可用 banner: 走 ctx.ui.notify() 渲染, 不依赖 dist/banner.js
+// 保留 cli.js 旧 banner 的核心信息密度, 但走 TUI 而非 stdout
+function buildBanner(themeColor: string, version: string): string {
+	const theme =
+		themeColor === "random" || themeColor === "rotate"
+			? getRotatedColorTheme()
+			: themeColor;
+	const rgb = hexToRgb(theme);
+	const color = (text: string) =>
+		`\x1b[38;2;${rgb.r};${rgb.g};${rgb.b}m${text}\x1b[0m`;
+	const dim = (text: string) => `\x1b[2m${text}\x1b[0m`;
+	const bold = (text: string) => `\x1b[1m${text}\x1b[0m`;
+
+	// cwd 用 try/catch 防御 ENOENT (虽然 cli.js 已 chdir 到 homedir, 多一道防御)
+	let cwd: string;
+	try {
+		cwd = process
+			.cwd()
+			.replace(process.env.HOME || process.env.USERPROFILE || "", "~");
+	} catch {
+		cwd = "~";
+	}
+
+	return [
+		`${color(bold("AICODE CLI"))} ${dim(`v${version}`)}`,
+		`${dim("Dir:")} ${dim(cwd)}`,
+		"",
+		dim(
+			"- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -",
+		),
+		dim(
+			"     直接用自然语言描述需求即可  • 复杂任务先用 /plan 生成计划  • @文件路径 指定文件",
+		),
+		dim(
+			"- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -",
+		),
+		"",
+		bold("  常用命令"),
+		`  ${color("/model")} 切换模型       ${color("/settings")} 设置         ${color("/compact")} 压缩上下文`,
+		`  ${color("/new")} 新会话         ${color("/reload")} 重载配置       ${color("/resume")} 恢复会话`,
+		`  ${color("/plan")} 计划模式(只读)  ${color("/bugs")} 已知bug修复    ${color("/goal")} 目标导向`,
+		"",
+		bold("  提示词与技能"),
+		`  ${color("/workflow")} 六阶段工作流  ${color("/code-review")} 代码审查   ${color("/commit")} Git提交`,
+		`  ${color("/brainstorming")} 头脑风暴  ${color("/skill-creator")} 创建技能`,
+	].join("\n");
+}
+
+export default function (pi: ExtensionAPI) {
+	const version = process.env.AICODE_CLI_VERSION || "";
+	// 主题色从 env 读 (cli.js 启动时已注入 AICODE_BANNER_THEME), 缺省用基准色
+	const themeColor = process.env.AICODE_BANNER_THEME || "#49bccf";
+
+	pi.on("session_start", (event, ctx) => {
+		// 只在 startup (新会话) 时打印, 不在 resume/new/fork 重复刷屏
+		if (event.reason !== "startup") return;
+		// 没有 TUI (纯 RPC/JSON 模式) 不打印 — 不污染 JSON 输出
+		if (!ctx.hasUI) return;
+
+		ctx.ui.notify(buildBanner(themeColor, version), "info");
+	});
+}