@armadra/agent 0.6.2 → 0.6.3

package/dist/modes/interactive/run-indicator.js

@@ -9,6 +9,10 @@
  *   助手在流式输出 → 末块是思考 `思考中`，否则 `回复中 · ↓≈1.2k`（本条输出的估算 token，4 字符 ≈ 1）
  *   其余（等首个 token）→ `思考中`
  * 运行或压缩时 Loader 才挂进槽位；附加项 `Esc 中断`。
+ * [W7-A] 有该显示的子 Agent 任务时再带可丢弃的 `↓ Agent 栏`（窄屏先丢它）；任务随时出现 / 结束，
+ * 每帧对一次，变了才换动词。
+ * [W7-C] 有阻塞中的前台任务时可丢弃项前面加 `Ctrl+B 转后台`；有停靠的审批时 `↓ Agent 栏` 换成
+ * `↓ 处理审批`。顺序 `Esc 中断 · Ctrl+B 转后台 · ↓ Agent 栏`，窄屏从后往前丢。
  *
  * 排队消息：缩进 2 列（挂在当前回合下），`↳ 插话 / 之后  文本` 整体 muted、标签 dim；超过 3 条首行
  * `… 另 N 条`；末行 `Alt+↑ 取回 · Esc 回填并中断`。
@@ -48,8 +52,32 @@ export class RunIndicator {
     approval = false;
     retry;
     stream;
+    /** [W7-A] 有该显示的子 Agent 任务（interactive-mode 在 AgentUi 建好后接上）。 */
+    agents = () => false;
+    /** [W7-C] 有阻塞中的前台任务（Ctrl+B 可转后台）。 */
+    background = () => false;
+    /** [W7-C] 有停靠在 Agent 栏的审批。 */
+    docked = () => false;
+    hintKey = "";
     constructor(deps) {
         this.deps = deps;
+        deps.loader.onFrame(() => {
+            if (this.busy && !this.approval && this.optionalHints().join("\n") !== this.hintKey)
+                this.applyVerb();
+        });
+    }
+    /** 可丢弃的按键提示（按丢弃的逆序排列）。 */
+    optionalHints() {
+        const down = this.deps.theme.glyphs.arrowDown;
+        const key = this.deps.backgroundKey;
+        const out = [];
+        if (key !== undefined && this.background())
+            out.push(msg().agents.background.runHint(key));
+        if (this.docked())
+            out.push(msg().agents.approval.runHint(down));
+        else if (this.agents())
+            out.push(msg().agents.bar.runHint(down));
+        return out;
     }
     get busy() {
         return this.running || this.compacting;
@@ -133,17 +161,21 @@ export class RunIndicator {
         const m = msg().interactive.view.run;
         const esc = [m.esc];
         if (this.approval) {
+            this.hintKey = "";
             loader.setVerb(m.awaitingApproval);
             return;
         }
+        const hints = this.optionalHints();
+        this.hintKey = hints.join("\n");
+        const optional = hints.length > 0 ? { optional: hints } : {};
         const running = tools.running();
         const top = running.filter((view) => !running.some((p) => p.children.includes(view)));
         if (top.length === 1) {
-            loader.setVerb(m.runningTool(top[0].toolName), esc);
+            loader.setVerb(m.runningTool(top[0].toolName), esc, optional);
             return;
         }
         if (top.length > 1) {
-            loader.setVerb(m.runningTools(top.length), esc);
+            loader.setVerb(m.runningTools(top.length), esc, optional);
             return;
         }
         if (this.retry !== undefined) {
@@ -154,15 +186,15 @@ export class RunIndicator {
             return;
         }
         if (this.compacting) {
-            loader.setVerb(m.compacting, esc);
+            loader.setVerb(m.compacting, esc, optional);
             return;
         }
         const stream = this.stream;
         if (stream !== undefined && !stream.thinking && stream.tokens > 0) {
-            loader.setVerb(m.replying, [`↓≈${formatTokens(stream.tokens)}`, ...esc]);
+            loader.setVerb(m.replying, [`↓≈${formatTokens(stream.tokens)}`, ...esc], optional);
             return;
         }
-        loader.setVerb(m.thinking, esc);
+        loader.setVerb(m.thinking, esc, optional);
     }
 }
 /** 排队消息（插话 / 之后），挂在 Loader 之上。 */

package/dist/modes/interactive/session-events.js

@@ -9,8 +9,12 @@ export function createSessionEventHandler(deps) {
     const { view, tools, status, area, agentUi, indicator, session, setQueue, notice, render } = deps;
     const images = new ImageBudgetNotices((text) => notice("info", text));
     return (event) => {
-        if (area.onEvent(event) || agentUi().onEvent(event))
+        if (area.onEvent(event) || agentUi().onEvent(event)) {
+            // [W7-A] 子任务出现 / 结束：运行提示行的「↓ Agent 栏」跟着变
+            if (event.type === "subagent_start" || event.type === "subagent_end")
+                indicator.sync();
             return render();
+        }
         images.onEvent(event);
         switch (event.type) {
             case "agent_settled":

package/dist/modes/interactive/startup-header.d.ts

@@ -1,32 +1,43 @@
 /**
  * 交互模式启动头（终端界面视觉设计 v1 §3.1）。
  *
- * - `normal`：宽度 ≥ 56 且非 `ui.compact` 时画框（宽 `min(width, 64)`，左对齐）——标题 `✻ ama x.y.z`、
- *   键值行（模型 / 目录 / 模式 / 已加载 / 宿主 / 警告）、按键提示；否则去框去键列，每项一行。
- * - `header`：一行 `✻ ama x.y.z · 模型 · 模式 · /help`，无框。`silent` 不输出（调用方不加本组件）。
- * - 着色：`✻` accent、标题粗体；键列 dim；模型 accent；已信任 success / 未信任 warning；Bypass 模式 warning；
- *   按键提示 dim。路径过长时从左截断（`…/armadra-agent`）。宽度变化时按新宽重算是否去框。
+ * - `normal`：无框。宽度 ≥ 72 时「AMA」字符画（startup-logo.ts）在左、信息列在右；48–71 列字符画在上、
+ *   空一行、信息列在下；< 48 列退回两行简洁头（不画字符画）。`ui.logo: "off"` 或 `ui.compact` 时只画信息列，
+ *   首行 `✻ ama x.y.z`。
+ * - 信息列：标题（版本）、模型 · 思考、目录 · 信任（来源）、模式 · 预设 · codemode、已加载 / 宿主 / 警告
+ *   （有才画）、按键提示。
+ * - `header`：一行 `✻ ama x.y.z · 模型 · 模式 · /help`。`silent` 不输出（调用方不加本组件）。
+ * - 着色：字符画按列 accent → user → tool 渐变；`✻` accent、标题粗体；模型 accent；已信任 success / 未信任
+ *   warning；Bypass 模式 warning；按键提示与分隔点 dim。路径过长时从左截断（`…/armadra-agent`）。
+ * - 启动动画通过 `setSweep` 改字符画的扫描位置（undefined = 定格），信息列不变。
  */
 import type { StartupInfo } from "../../cli/startup-screen.js";
 import { type Component, type Theme } from "../../tui.js";
-/** 画框的最小宽度；更窄时去框去键列。 */
-export declare const HEADER_BOX_MIN_WIDTH = 56;
-/** 设计稿写 60；常见的「供应商/模型@渠道 · 思考 级别」要 62 列左右才不截断，取 64。 */
-export declare const HEADER_BOX_MAX_WIDTH = 64;
+import { type SweepTarget } from "./startup-logo.js";
+/** 字符画与信息列并排的最小宽度。 */
+export declare const HEADER_SIDE_MIN_WIDTH = 72;
+/** 画字符画的最小宽度；更窄时两行简洁头。 */
+export declare const HEADER_LOGO_MIN_WIDTH = 48;
 export interface StartupHeaderOptions {
     theme: Theme;
     level: "normal" | "header";
-    /** `ui.compact`：normal 也不画框。 */
-    compact?: boolean;
+    /** `ui.compact`：不画字符画。 */
+    compact?: boolean | undefined;
+    /** `ui.logo`，缺省 auto；off 不画字符画。 */
+    logo?: "auto" | "off" | undefined;
 }
 /** 从左截断到 `width` 列（保留末尾，前面加省略号）。 */
 export declare function truncateLeft(text: string, width: number, ellipsis?: string): string;
-export declare class StartupHeader implements Component {
+export declare class StartupHeader implements Component, SweepTarget {
     private readonly info;
     private readonly options;
     private cache;
+    private sweep;
     constructor(info: StartupInfo, options: StartupHeaderOptions);
     private get theme();
+    /** 这个宽度下是否画字符画（动画只在画了时播放）。 */
+    hasLogo(width: number): boolean;
+    setSweep(sweep: number | undefined): void;
     private title;
     private modeText;
     private trustText;
@@ -34,7 +45,11 @@ export declare class StartupHeader implements Component {
     private codemodeText;
     render(width: number): string[];
     private headerLine;
-    private plainLines;
-    private boxLines;
+    /** < 48 列：两行（版本 · 模型 · 思考 / 模式 · 目录 · 信任），有警告再加一行。 */
+    private narrowLines;
+    /** 信息列：首行 `title`，其后模型、目录、模式、可选行、按键提示；每行截到 `width`。 */
+    private infoLines;
+    /** 字符画 + 信息列：够宽并排（顶端对齐），否则上下叠放。 */
+    private logoLines;
     invalidate(): void;
 }

package/dist/modes/interactive/startup-header.js

@@ -1,19 +1,26 @@
 /**
  * 交互模式启动头（终端界面视觉设计 v1 §3.1）。
  *
- * - `normal`：宽度 ≥ 56 且非 `ui.compact` 时画框（宽 `min(width, 64)`，左对齐）——标题 `✻ ama x.y.z`、
- *   键值行（模型 / 目录 / 模式 / 已加载 / 宿主 / 警告）、按键提示；否则去框去键列，每项一行。
- * - `header`：一行 `✻ ama x.y.z · 模型 · 模式 · /help`，无框。`silent` 不输出（调用方不加本组件）。
- * - 着色：`✻` accent、标题粗体；键列 dim；模型 accent；已信任 success / 未信任 warning；Bypass 模式 warning；
- *   按键提示 dim。路径过长时从左截断（`…/armadra-agent`）。宽度变化时按新宽重算是否去框。
+ * - `normal`：无框。宽度 ≥ 72 时「AMA」字符画（startup-logo.ts）在左、信息列在右；48–71 列字符画在上、
+ *   空一行、信息列在下；< 48 列退回两行简洁头（不画字符画）。`ui.logo: "off"` 或 `ui.compact` 时只画信息列，
+ *   首行 `✻ ama x.y.z`。
+ * - 信息列：标题（版本）、模型 · 思考、目录 · 信任（来源）、模式 · 预设 · codemode、已加载 / 宿主 / 警告
+ *   （有才画）、按键提示。
+ * - `header`：一行 `✻ ama x.y.z · 模型 · 模式 · /help`。`silent` 不输出（调用方不加本组件）。
+ * - 着色：字符画按列 accent → user → tool 渐变；`✻` accent、标题粗体；模型 accent；已信任 success / 未信任
+ *   warning；Bypass 模式 warning；按键提示与分隔点 dim。路径过长时从左截断（`…/armadra-agent`）。
+ * - 启动动画通过 `setSweep` 改字符画的扫描位置（undefined = 定格），信息列不变。
  */
 import { msg } from "../../i18n/index.js";
 import { permissionModeLabel } from "../../permissions/modes.js";
-import { Box, KeyValue, padToWidth, truncateToWidth, visibleWidth, } from "../../tui.js";
-/** 画框的最小宽度；更窄时去框去键列。 */
-export const HEADER_BOX_MIN_WIDTH = 56;
-/** 设计稿写 60；常见的「供应商/模型@渠道 · 思考 级别」要 62 列左右才不截断，取 64。 */
-export const HEADER_BOX_MAX_WIDTH = 64;
+import { truncateToWidth, visibleWidth } from "../../tui.js";
+import { logoRows, logoWidth, paintLogo } from "./startup-logo.js";
+/** 字符画与信息列并排的最小宽度。 */
+export const HEADER_SIDE_MIN_WIDTH = 72;
+/** 画字符画的最小宽度；更窄时两行简洁头。 */
+export const HEADER_LOGO_MIN_WIDTH = 48;
+/** 字符画与信息列之间的空列。 */
+const GAP = 3;
 /** 从左截断到 `width` 列（保留末尾，前面加省略号）。 */
 export function truncateLeft(text, width, ellipsis = "…") {
     if (visibleWidth(text) <= width)
@@ -33,6 +40,13 @@ export function truncateLeft(text, width, ellipsis = "…") {
     }
     return ellipsis + out;
 }
+/** 按 ` · ` 分段的提示放不下时从末尾整段去掉（至少留第一段，再不够由调用方截断）。 */
+function fitSegments(text, width) {
+    const parts = text.split(" · ");
+    while (parts.length > 1 && visibleWidth(parts.join(" · ")) > width)
+        parts.pop();
+    return parts.join(" · ");
+}
 /** 去掉模型引用里的渠道（`@messages`）。 */
 function withoutChannel(model) {
     const at = model.indexOf("@");
@@ -42,6 +56,7 @@ export class StartupHeader {
     info;
     options;
     cache = null;
+    sweep;
     constructor(info, options) {
         this.info = info;
         this.options = options;
@@ -49,6 +64,19 @@ export class StartupHeader {
     get theme() {
         return this.options.theme;
     }
+    /** 这个宽度下是否画字符画（动画只在画了时播放）。 */
+    hasLogo(width) {
+        return (this.options.level === "normal" &&
+            this.options.logo !== "off" &&
+            this.options.compact !== true &&
+            width >= HEADER_LOGO_MIN_WIDTH);
+    }
+    setSweep(sweep) {
+        if (sweep === this.sweep)
+            return;
+        this.sweep = sweep;
+        this.cache = null;
+    }
     title() {
         const t = this.theme;
         return `${t.fg("accent", t.glyphs.thinking)} ${t.bold(`ama ${this.info.version}`)}`;
@@ -82,11 +110,15 @@ export class StartupHeader {
     render(width) {
         if (this.cache?.width === width)
             return this.cache.lines;
-        const lines = this.options.level === "header"
-            ? [this.headerLine(width)]
-            : this.options.compact === true || width < HEADER_BOX_MIN_WIDTH
-                ? this.plainLines(width)
-                : this.boxLines(width);
+        let lines;
+        if (this.options.level === "header")
+            lines = [this.headerLine(width)];
+        else if (width < HEADER_LOGO_MIN_WIDTH)
+            lines = this.narrowLines(width);
+        else if (!this.hasLogo(width))
+            lines = this.infoLines(width, this.title());
+        else
+            lines = this.logoLines(width);
         this.cache = { width, lines };
         return lines;
     }
@@ -101,66 +133,68 @@ export class StartupHeader {
         ];
         return truncateToWidth(parts.join(sep), width);
     }
-    plainLines(width) {
+    /** < 48 列：两行（版本 · 模型 · 思考 / 模式 · 目录 · 信任），有警告再加一行。 */
+    narrowLines(width) {
         const t = this.theme;
         const sep = t.fg("dim", " · ");
-        const ellipsis = t.glyphs.ellipsis;
         const { info } = this;
-        const lines = [this.title()];
-        lines.push(t.fg("accent", withoutChannel(info.model)) + sep + info.thinking);
+        const lines = [
+            [this.title(), t.fg("accent", withoutChannel(info.model)), info.thinking].join(sep),
+        ];
+        const mode = this.modeText();
         const trust = this.trustText(false);
-        const room = Math.max(4, width - visibleWidth(trust) - 3);
-        lines.push(truncateLeft(info.cwd, room, ellipsis) + sep + trust);
-        const mode = [this.modeText(), info.preset, this.codemodeText()].filter((p) => p !== undefined);
-        lines.push(mode.join(sep));
-        const loaded = this.loadedText();
-        if (loaded !== undefined)
-            lines.push(loaded);
-        const m = msg().interactive.startup.header;
-        if (info.host !== undefined)
-            lines.push(m.host(info.host));
-        if (info.warnings > 0)
-            lines.push(t.fg("warning", m.warnings(info.warnings)));
-        lines.push(t.fg("dim", m.hintCompact));
+        const room = Math.max(4, width - visibleWidth(mode) - visibleWidth(trust) - 6);
+        lines.push([mode, truncateLeft(info.cwd, room, t.glyphs.ellipsis), trust].join(sep));
+        if (info.warnings > 0) {
+            lines.push(t.fg("warning", msg().interactive.startup.header.warnings(info.warnings)));
+        }
         return lines.map((line) => truncateToWidth(line, width));
     }
-    boxLines(width) {
+    /** 信息列：首行 `title`，其后模型、目录、模式、可选行、按键提示；每行截到 `width`。 */
+    infoLines(width, title) {
         const t = this.theme;
         const sep = t.fg("dim", " · ");
         const { info } = this;
         const m = msg().interactive.startup.header;
-        const boxWidth = Math.min(width, HEADER_BOX_MAX_WIDTH);
-        // 键列至少 6 列（「已加载」的宽度），没有这一行时也对齐；英文键更宽时按最宽的键
-        const keyWidth = Math.max(6, ...[m.keyModel, m.keyDir, m.keyMode, m.keyLoaded, m.keyHost, m.keyWarnings].map((k) => visibleWidth(k)));
-        /** 框内文本宽：边框 2 + 内边距 2；键列 + 间隔 1。 */
-        const valueWidth = boxWidth - 4 - keyWidth - 1;
         const trust = this.trustText(true);
-        const cwdRoom = Math.max(4, valueWidth - visibleWidth(trust) - 3);
-        const rows = [
-            { key: m.keyModel, value: t.fg("accent", info.model) + sep + m.thinking(info.thinking) },
-            { key: m.keyDir, value: truncateLeft(info.cwd, cwdRoom, t.glyphs.ellipsis) + sep + trust },
-            {
-                key: m.keyMode,
-                value: [this.modeText(), m.preset(info.preset), this.codemodeText()]
-                    .filter((p) => p !== undefined)
-                    .join(sep),
-            },
+        const cwdRoom = Math.max(4, width - visibleWidth(trust) - 3);
+        const lines = [
+            title,
+            t.fg("accent", info.model) + sep + m.thinking(info.thinking),
+            truncateLeft(info.cwd, cwdRoom, t.glyphs.ellipsis) + sep + trust,
+            [this.modeText(), m.preset(info.preset), this.codemodeText()]
+                .filter((p) => p !== undefined)
+                .join(sep),
         ];
         const loaded = this.loadedText();
         if (loaded !== undefined)
-            rows.push({ key: m.keyLoaded, value: loaded });
+            lines.push(loaded);
         if (info.host !== undefined)
-            rows.push({ key: m.keyHost, value: info.host });
-        if (info.warnings > 0) {
-            rows.push({ key: m.keyWarnings, value: t.fg("warning", m.warningsValue(info.warnings)) });
+            lines.push(m.host(info.host));
+        if (info.warnings > 0)
+            lines.push(t.fg("warning", m.warnings(info.warnings)));
+        lines.push(t.fg("dim", fitSegments(m.hint, width)));
+        return lines.map((line) => truncateToWidth(line, width));
+    }
+    /** 字符画 + 信息列：够宽并排（顶端对齐），否则上下叠放。 */
+    logoLines(width) {
+        const t = this.theme;
+        const logo = paintLogo(t, this.sweep);
+        const logoCols = logoWidth(logoRows(t));
+        const title = `${t.bold("ama")} ${t.fg("dim", this.info.version)}`;
+        if (width < HEADER_SIDE_MIN_WIDTH) {
+            return [...logo, "", ...this.infoLines(width, title)];
+        }
+        const info = this.infoLines(width - logoCols - GAP, title);
+        const rows = Math.max(logo.length, info.length);
+        const blank = " ".repeat(logoCols);
+        const gap = " ".repeat(GAP);
+        const lines = [];
+        for (let i = 0; i < rows; i++) {
+            const right = info[i];
+            lines.push(right === undefined ? (logo[i] ?? "") : (logo[i] ?? blank) + gap + right);
         }
-        const padded = rows.map((row) => ({ ...row, key: padToWidth(row.key, keyWidth) }));
-        const kv = new KeyValue(padded, { theme: t, gap: 1, maxKeyRatio: 1 });
-        const body = {
-            render: (inner) => [this.title(), "", ...kv.render(inner), "", t.fg("dim", m.hint)],
-            invalidate: () => kv.invalidate(),
-        };
-        return new Box(body, { theme: t }).render(boxWidth);
+        return lines;
     }
     invalidate() {
         this.cache = null;

package/dist/modes/interactive/startup-logo.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 启动头的「AMA」字符画与启动动画（终端界面视觉设计 v1 §3.1.1）。
+ *
+ * - 字形：缺省 5 行实心块字（`█▀▄`，宽 25）；ASCII 回退（`ui.ascii` / `AMA_ASCII=1`）用 figlet 风格的
+ *   `_ / \ |`（同为 5 行、宽 25）。
+ * - 着色：按列三段渐变 accent → user → tool（主题已有颜色，深浅主题 / 16 色都有对应值）；无色主题原样输出。
+ * - 动画（点亮扫描）：未扫到的列 dim，扫描头 3 列 text 粗体高亮，扫过的列定格为渐变色；每帧前进 1 列，
+ *   约 30 帧 × 32 ms ≈ 1 s，结束停在定格帧。动画只重画启动头所在行（差分渲染器原地改写），所以只在
+ *   整屏内容装得下视口时播放；任何时候 `finish()` 立即定格。
+ */
+import type { Theme, TUI } from "../../tui.js";
+/** 缺省字形（实心块字）。 */
+export declare const LOGO_BLOCK: readonly string[];
+/** 纯 ASCII 字形（只用 `_ / \ |`）。 */
+export declare const LOGO_ASCII: readonly string[];
+/** 扫描头的宽度（列）。 */
+export declare const SWEEP_BAND = 3;
+/** 帧间隔（ms）；帧数 = 字形宽 + 扫描头宽，总时长约 1 s（上限 1.2 s）。 */
+export declare const FRAME_MS = 32;
+export declare function logoRows(theme: Theme): readonly string[];
+/** 字形的列宽（逐字符都是 1 列）。 */
+export declare function logoWidth(rows: readonly string[]): number;
+/** 动画总帧数（不含定格帧）。 */
+export declare function sweepFrames(theme: Theme): number;
+/** 画字形：同样式的连续列合成一段，空格不着色；返回的每行都补足到字形宽。 */
+export declare function paintLogo(theme: Theme, sweep?: number): string[];
+/** 动画画到的目标（启动头）。 */
+export interface SweepTarget {
+    setSweep(sweep: number | undefined): void;
+}
+export interface LogoAnimationOptions {
+    frames: number;
+    intervalMs?: number;
+    /** 每帧之后请求重绘。 */
+    render(): void;
+    /** 每帧之前检查：返回 false（内容已超出视口等）立即定格。 */
+    canContinue?(): boolean;
+    /** 定格之后（走完或提前结束）调用一次。 */
+    onDone?(): void;
+}
+/** 一次性的点亮扫描：`start()` 从第 0 帧开始，走完或 `finish()` 后定格，不会再动。 */
+export declare class LogoAnimation {
+    private readonly target;
+    private readonly options;
+    private frame;
+    private timer;
+    private done;
+    constructor(target: SweepTarget, options: LogoAnimationOptions);
+    get running(): boolean;
+    start(): void;
+    private step;
+    /** 立即定格（按键、退出、走完）；重复调用无副作用。 */
+    finish(): void;
+}
+/** 是否播放启动动画的输入（interactive-mode 汇总）。 */
+export interface AnimationGate {
+    /** `ui.animation`。 */
+    animation: boolean | undefined;
+    /** 启动头确实画了 logo（normal 档、`ui.logo` 非 off、非 compact、宽度够）。 */
+    hasLogo: boolean;
+    colors: number;
+    io: {
+        stdoutIsTTY: boolean;
+    };
+    /** 嵌入宿主（profile.host）。 */
+    host: boolean;
+    /** 启动即提交的提示（`ama "..."`）；非空不播放。 */
+    prompt: string | undefined;
+    env: NodeJS.ProcessEnv;
+    rows: number;
+}
+/** 终端低于这个行数不播放（启动头 + 输入框 + 状态栏放不下时差分渲染会把动画帧滚进回滚区）。 */
+export declare const MIN_ANIMATION_ROWS = 16;
+export declare function shouldAnimate(gate: AnimationGate): boolean;
+/** 能播放动画的启动头。 */
+export interface AnimatedHeader extends SweepTarget {
+    hasLogo(width: number): boolean;
+}
+/**
+ * 界面启动后调用：条件满足就播放点亮扫描并返回动画（退出时 `finish()`），否则返回 undefined、启动头
+ * 直接是定格帧。按任意键立即定格——监听器不吞键，按键照常进输入框。
+ */
+export declare function playStartupAnimation(tui: TUI, header: AnimatedHeader | undefined, theme: Theme, conditions: Omit<AnimationGate, "hasLogo" | "colors" | "rows">): LogoAnimation | undefined;

package/dist/modes/interactive/startup-logo.js

@@ -0,0 +1,183 @@
+/**
+ * 启动头的「AMA」字符画与启动动画（终端界面视觉设计 v1 §3.1.1）。
+ *
+ * - 字形：缺省 5 行实心块字（`█▀▄`，宽 25）；ASCII 回退（`ui.ascii` / `AMA_ASCII=1`）用 figlet 风格的
+ *   `_ / \ |`（同为 5 行、宽 25）。
+ * - 着色：按列三段渐变 accent → user → tool（主题已有颜色，深浅主题 / 16 色都有对应值）；无色主题原样输出。
+ * - 动画（点亮扫描）：未扫到的列 dim，扫描头 3 列 text 粗体高亮，扫过的列定格为渐变色；每帧前进 1 列，
+ *   约 30 帧 × 32 ms ≈ 1 s，结束停在定格帧。动画只重画启动头所在行（差分渲染器原地改写），所以只在
+ *   整屏内容装得下视口时播放；任何时候 `finish()` 立即定格。
+ */
+/** 缺省字形（实心块字）。 */
+export const LOGO_BLOCK = [
+    " ▄███▄  ██▄   ▄██  ▄███▄",
+    "██▀ ▀██ ███▄ ▄███ ██▀ ▀██",
+    "███████ ██ ▀█▀ ██ ███████",
+    "██   ██ ██     ██ ██   ██",
+    "▀▀   ▀▀ ▀▀     ▀▀ ▀▀   ▀▀",
+];
+/** 纯 ASCII 字形（只用 `_ / \ |`）。 */
+export const LOGO_ASCII = [
+    "    _    __  __    _",
+    "   / \\  |  \\/  |  / \\",
+    "  / _ \\ | |\\/| | / _ \\",
+    " / ___ \\| |  | |/ ___ \\",
+    "/_/   \\_\\_|  |_/_/   \\_\\",
+];
+/** 扫描头的宽度（列）。 */
+export const SWEEP_BAND = 3;
+/** 帧间隔（ms）；帧数 = 字形宽 + 扫描头宽，总时长约 1 s（上限 1.2 s）。 */
+export const FRAME_MS = 32;
+const GRADIENT = ["accent", "user", "tool"];
+/** 每个字母起始列（渐变按字母分段，不把一个字母劈成两色）。 */
+const LETTER_STARTS = { block: [0, 8, 18], ascii: [0, 8, 16] };
+export function logoRows(theme) {
+    return theme.glyphs.ascii ? LOGO_ASCII : LOGO_BLOCK;
+}
+function letterColor(col, ascii) {
+    const starts = LETTER_STARTS[ascii ? "ascii" : "block"];
+    let index = 0;
+    for (let i = 0; i < starts.length; i++)
+        if (col >= starts[i])
+            index = i;
+    return GRADIENT[index];
+}
+/** 字形的列宽（逐字符都是 1 列）。 */
+export function logoWidth(rows) {
+    return Math.max(...rows.map((row) => [...row].length));
+}
+/** 动画总帧数（不含定格帧）。 */
+export function sweepFrames(theme) {
+    return logoWidth(logoRows(theme)) + SWEEP_BAND;
+}
+/** 第 `col` 列的样式；`sweep` 为扫描头所在列，undefined 为定格。 */
+function styleAt(col, ascii, sweep) {
+    const settled = { color: letterColor(col, ascii), bold: true };
+    if (sweep === undefined || col <= sweep - SWEEP_BAND)
+        return settled;
+    if (col <= sweep)
+        return { color: "text", bold: true };
+    return { color: "dim", bold: false };
+}
+/** 画字形：同样式的连续列合成一段，空格不着色；返回的每行都补足到字形宽。 */
+export function paintLogo(theme, sweep) {
+    const rows = logoRows(theme);
+    const width = logoWidth(rows);
+    return rows.map((row) => {
+        const chars = [...row.padEnd(width)];
+        let out = "";
+        let run = "";
+        let runStyle;
+        const flush = () => {
+            if (run === "")
+                return;
+            if (runStyle === undefined)
+                out += run;
+            else {
+                const colored = theme.fg(runStyle.color, run);
+                out += runStyle.bold ? theme.bold(colored) : colored;
+            }
+            run = "";
+        };
+        chars.forEach((ch, col) => {
+            const style = ch === " " ? undefined : styleAt(col, theme.glyphs.ascii, sweep);
+            if (style?.color !== runStyle?.color || style?.bold !== runStyle?.bold) {
+                flush();
+                runStyle = style;
+            }
+            run += ch;
+        });
+        flush();
+        return out;
+    });
+}
+/** 一次性的点亮扫描：`start()` 从第 0 帧开始，走完或 `finish()` 后定格，不会再动。 */
+export class LogoAnimation {
+    target;
+    options;
+    frame = 0;
+    timer;
+    done = false;
+    constructor(target, options) {
+        this.target = target;
+        this.options = options;
+    }
+    get running() {
+        return !this.done && this.timer !== undefined;
+    }
+    start() {
+        if (this.done || this.timer !== undefined)
+            return;
+        this.step();
+    }
+    step() {
+        this.timer = undefined;
+        if (this.frame >= this.options.frames || this.options.canContinue?.() === false) {
+            this.finish();
+            return;
+        }
+        this.target.setSweep(this.frame++);
+        this.options.render();
+        this.timer = setTimeout(() => this.step(), this.options.intervalMs ?? FRAME_MS);
+        this.timer.unref?.();
+    }
+    /** 立即定格（按键、退出、走完）；重复调用无副作用。 */
+    finish() {
+        if (this.done)
+            return;
+        this.done = true;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.target.setSweep(undefined);
+        this.options.render();
+        this.options.onDone?.();
+    }
+}
+/** 终端低于这个行数不播放（启动头 + 输入框 + 状态栏放不下时差分渲染会把动画帧滚进回滚区）。 */
+export const MIN_ANIMATION_ROWS = 16;
+export function shouldAnimate(gate) {
+    const ci = gate.env["CI"];
+    return (gate.animation !== false &&
+        gate.hasLogo &&
+        gate.colors > 0 &&
+        gate.io.stdoutIsTTY &&
+        !gate.host &&
+        (gate.prompt ?? "").trim() === "" &&
+        (ci === undefined || ci === "" || ci === "0" || ci === "false") &&
+        gate.rows >= MIN_ANIMATION_ROWS);
+}
+/**
+ * 界面启动后调用：条件满足就播放点亮扫描并返回动画（退出时 `finish()`），否则返回 undefined、启动头
+ * 直接是定格帧。按任意键立即定格——监听器不吞键，按键照常进输入框。
+ */
+export function playStartupAnimation(tui, header, theme, conditions) {
+    const term = tui.terminal;
+    const columns = term.columns;
+    if (header === undefined)
+        return undefined;
+    const gate = {
+        ...conditions,
+        hasLogo: header.hasLogo(term.columns),
+        colors: theme.caps.colors,
+        rows: term.rows,
+    };
+    // 整屏内容装得下视口，动画帧才只在原地改写、不进回滚区
+    const fits = () => tui.render(term.columns).length <= term.rows;
+    if (!shouldAnimate(gate) || !fits())
+        return undefined;
+    let offInput = () => undefined;
+    const animation = new LogoAnimation(header, {
+        frames: sweepFrames(theme),
+        render: () => tui.requestRender(),
+        // 改了尺寸（差分渲染要整屏重画）也立即定格
+        canContinue: () => term.columns === columns && fits(),
+        onDone: () => offInput(),
+    });
+    offInput = tui.addInputListener(() => {
+        animation.finish();
+        return false;
+    });
+    animation.start();
+    return animation;
+}