@deepseek-harness-tui/dsh-tui 0.11.2 → 0.13.0

package/lib/types/components/design-system/Divider.js

@@ -5,7 +5,7 @@ import Text from './ThemedText.js';
 import measureElement from '../../ink/measure-element.js';
 import { stringWidth } from '../../ink/stringWidth.js';
 import { useTerminalSize } from '../../ink/hooks/use-terminal-size.js';
-import { usePageInset } from '../PageMargin.js';
+import { useSurfaceEdges } from '../SurfaceEdges.js';
 // Upper bound on distinct measurements applied per terminal-width
 // generation. Converging layouts apply one or two; a non-converging
 // context (content-sized Box, or a sibling negotiating space the same
@@ -35,13 +35,18 @@ const MAX_APPLIED_MEASUREMENTS = 8;
  */
 export function Divider({ width, color, char = '─', padding = 0, title, bleed = false, }) {
     const { columns } = useTerminalSize();
-    const inset = usePageInset();
-    // Full-bleed: the rule spans the terminal columns, shifted left by the
-    // page inset via a negative margin (the box reaches into the margin
-    // area; the parent does not clip). `columns` here is the CONTENT width
-    // (PageMargin narrows TerminalSizeContext), so +2·inset.x = terminal.
-    const bleedX = bleed ? inset.x : 0;
-    const bleedWidth = columns + 2 * bleedX;
+    const edges = useSurfaceEdges();
+    // Full-bleed: the rule spans the SURFACE width, shifted left by the
+    // allowed bleed via a negative margin (the box reaches into the margin
+    // area; the parent does not clip). `columns` here is the SURFACE
+    // content width (PageMargin narrows TerminalSizeContext, the side panel
+    // narrows it again per column), and SurfaceEdges says how far past each
+    // side chrome may run: under PageMargin alone that's {x, x} (the whole
+    // terminal); in the split chat column it's {x, 0} — the rule stops at
+    // the divider instead of painting into the panel.
+    const bleedLeft = bleed ? edges.left : 0;
+    const bleedRight = bleed ? edges.right : 0;
+    const bleedWidth = columns + bleedLeft + bleedRight;
     const [measuredWidth, setMeasuredWidth] = useState(null);
     const boxRef = useRef(null);
     // Measurement feedback guard: the rule width rendered from
@@ -108,7 +113,7 @@ export function Divider({ width, color, char = '─', padding = 0, title, bleed
         text = char.repeat(lineWidth);
     }
     return (_jsx(Box, { ref: boxRef, ...(bleed
-            ? { width: bleedWidth, marginLeft: -bleedX }
+            ? { width: bleedWidth, marginLeft: -bleedLeft }
             : width !== undefined
                 ? { width }
                 : {}), children: _jsx(Text, { dimColor: !color, color: color, wrap: "truncate-end", children: text }) }));

package/lib/types/components/launchpadActions.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 落地页的一个动作入口（第四版：状态驱动的"下一步建议"）。
+ *
+ * 动作仍然全部走**既有命令名**（第七版表：continue / home / settings /
+ * jobs / update / star / help）——这一屏不新增行为，它只是把"当前状态下
+ * 最可能的下一步"摆到台面上。知道了名字，键盘用户直接敲；鼠标用户点一下，
+ * 两条路落到同一个 `runCommand`。
+ */
+export interface LaunchpadAction {
+    /** 稳定的行标识（焦点、`key` 都用它）。 */
+    readonly id: string;
+    /** i18n key：那一行的短标签。 */
+    readonly labelKey: string;
+    /** i18n 插值参数（目前只有 Continue 带会话标题）。 */
+    readonly values?: Readonly<Record<string, string>>;
+    /** 点击/回车时交给 `Chat.runCommand` 的命令名（不含斜杠）。 */
+    readonly command: string;
+}
+/**
+ * resolveLaunchpadActions 的输入——一次启动的状态快照。
+ *
+ * 第七版：每个字段都来自**既有**数据源（不造假）：
+ *   - `lastSessionTitle`：会话名册（`channel.agentViewRows`，含持久化会话）
+ *     里最近一条**可继续**会话的标题；没有就没有 Continue（不放假动作）；
+ *   - `jobsRunning`：`channel.backgroundJobs` 里有 running/stopping 的任务；
+ *   - `updateAvailable`：`checkForTuiUpdate()`（src/update.ts，与 /update
+ *     同一条判定）在启动页挂起时异步探得的新版本；
+ *   - `starDue`：`usageStats`（~/.dsh-tui/usage.json）有**未报过的**已达档
+ *     里程碑（首档 24h）且本进程尚未 star 成功——口径与开屏求 star 弹窗
+ *     完全一致（pendingStarMilestone + starred）。
+ */
+export interface LaunchpadActionState {
+    /** 最近一条可继续会话的标题；没有（或为空）视为"无历史"，整格不画。 */
+    readonly lastSessionTitle?: string | undefined;
+    /** 有后台任务在跑（条件位①）。 */
+    readonly jobsRunning: boolean;
+    /** 检测到可用更新（条件位②）。 */
+    readonly updateAvailable: boolean;
+    /** 用量到档且从未 star（条件位③）。 */
+    readonly starDue: boolean;
+}
+/** Continue 标题的截断上限（显示宽度，含截断省略号）。 */
+export declare const LAUNCHPAD_CONTINUE_TITLE_MAX = 16;
+/**
+ * 截断会话标题：按显示宽度（CJK 双宽）从头部取，超宽补 `…`。
+ * 纯函数、无副作用，表驱动回归直接钉它的边界。
+ */
+export declare function truncateContinueTitle(title: string, max?: number): string;
+/**
+ * 落地页第七版的核心纯函数：按状态快照决定入口行放什么。
+ *
+ * 版面（用户拍板的四格；第一格条件性缺席）：
+ *
+ *   1. `继续「<标题>」` —— 有可继续会话才画（无历史不放假动作）；
+ *      快捷键 Alt+R（keymap 的 `continue` 动作，见 utils/keymap.ts）。
+ *   2. `会话与工作区` —— 历史会话 + 工作区合并入口；命令用既有 `home`。
+ *   3. `设置` —— /settings。
+ *   4. 条件位，**按优先级取第一个成立者**（同时成立时高优先级胜出，
+ *      回归按这张优先级表驱动）：
+ *        ① jobsRunning → `后台任务`（/jobs）
+ *        ② updateAvailable → `有新版本`（/update，走既有更新路径）
+ *        ③ starDue → `投喂一颗 Star`（/star）
+ *        ④ 都不成立 → `帮助`（/help）兜底。
+ *
+ * 第六版的 doctor 入口已删（第七版）：它的输出属于转录区，天然把人带进
+ * 对话页，不适合留在"Esc 必须回启动页"的这一屏；首启/配置问题专属按钮
+ * 也随之退役——首启由引导向导（盖在落地页之上）承担，provider 配置经
+ * 向导或 /settings 可达。输出恒 ≤4 条。
+ *
+ * 纯函数：不改入参、不读环境、同样输入恒同样输出——表驱动回归钉死每个状态。
+ */
+export declare function resolveLaunchpadActions(state: LaunchpadActionState): readonly LaunchpadAction[];
+//# sourceMappingURL=launchpadActions.d.ts.map

package/lib/types/components/launchpadActions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launchpadActions.d.ts","sourceRoot":"","sources":["../../../src/components/launchpadActions.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,wBAAwB;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9C,qBAAqB;IACrB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,qBAAqB;IACrB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,qCAAqC;AACrC,eAAO,MAAM,4BAA4B,KAAK,CAAA;AAE9C;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAA+B,GAAG,MAAM,CAY/F;AAkDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,oBAAoB,GAAG,SAAS,eAAe,EAAE,CAkB/F"}

package/lib/types/components/launchpadActions.js

@@ -0,0 +1,111 @@
+import { stringWidth } from '../ink/stringWidth.js';
+/** Continue 标题的截断上限（显示宽度，含截断省略号）。 */
+export const LAUNCHPAD_CONTINUE_TITLE_MAX = 16;
+/**
+ * 截断会话标题：按显示宽度（CJK 双宽）从头部取，超宽补 `…`。
+ * 纯函数、无副作用，表驱动回归直接钉它的边界。
+ */
+export function truncateContinueTitle(title, max = LAUNCHPAD_CONTINUE_TITLE_MAX) {
+    const clean = title.replace(/[\r\n]+/gu, ' ').trim();
+    if (stringWidth(clean) <= max)
+        return clean;
+    let width = 0;
+    let out = '';
+    for (const ch of Array.from(clean)) {
+        const w = stringWidth(ch);
+        if (width + w > max - 1)
+            break;
+        out += ch;
+        width += w;
+    }
+    return out + '…';
+}
+/** Continue（不带标题时的短标签）。 */
+const CONTINUE = {
+    id: 'continue',
+    labelKey: 'launchpad-action-continue',
+    command: 'continue',
+};
+/**
+ * 会话与工作区（第七版合并入口）：历史会话与工作区本来就是同一个界面
+ * （`/home` 的会话名册 = 工作区首页，见 Chat 的 resume/home/agentview 合一
+ * 注释），两个按钮进同一个页面——用户实测后要求合并只留一个。命令用
+ * 既有的 `home` 那条。
+ */
+const SESSIONS_WORKSPACE = {
+    id: 'sessions-workspace',
+    labelKey: 'launchpad-action-sessions-workspace',
+    command: 'home',
+};
+/** Settings（用户拍板的第三格）。 */
+const SETTINGS = {
+    id: 'settings',
+    labelKey: 'launchpad-action-settings',
+    command: 'settings',
+};
+/** 条件位①：有后台任务在跑。 */
+const JOBS = {
+    id: 'jobs',
+    labelKey: 'launchpad-action-jobs',
+    command: 'jobs',
+};
+/** 条件位②：检测到可用更新。 */
+const UPDATE = {
+    id: 'update',
+    labelKey: 'launchpad-action-update',
+    command: 'update',
+};
+/** 条件位③：用量到档且从未 star。 */
+const STAR = {
+    id: 'star',
+    labelKey: 'launchpad-action-star',
+    command: 'star',
+};
+/** Help（? 快捷键与命令）——条件位的兜底。 */
+const HELP = {
+    id: 'help',
+    labelKey: 'launchpad-action-help',
+    command: 'help',
+};
+/**
+ * 落地页第七版的核心纯函数：按状态快照决定入口行放什么。
+ *
+ * 版面（用户拍板的四格；第一格条件性缺席）：
+ *
+ *   1. `继续「<标题>」` —— 有可继续会话才画（无历史不放假动作）；
+ *      快捷键 Alt+R（keymap 的 `continue` 动作，见 utils/keymap.ts）。
+ *   2. `会话与工作区` —— 历史会话 + 工作区合并入口；命令用既有 `home`。
+ *   3. `设置` —— /settings。
+ *   4. 条件位，**按优先级取第一个成立者**（同时成立时高优先级胜出，
+ *      回归按这张优先级表驱动）：
+ *        ① jobsRunning → `后台任务`（/jobs）
+ *        ② updateAvailable → `有新版本`（/update，走既有更新路径）
+ *        ③ starDue → `投喂一颗 Star`（/star）
+ *        ④ 都不成立 → `帮助`（/help）兜底。
+ *
+ * 第六版的 doctor 入口已删（第七版）：它的输出属于转录区，天然把人带进
+ * 对话页，不适合留在"Esc 必须回启动页"的这一屏；首启/配置问题专属按钮
+ * 也随之退役——首启由引导向导（盖在落地页之上）承担，provider 配置经
+ * 向导或 /settings 可达。输出恒 ≤4 条。
+ *
+ * 纯函数：不改入参、不读环境、同样输入恒同样输出——表驱动回归钉死每个状态。
+ */
+export function resolveLaunchpadActions(state) {
+    const conditional = state.jobsRunning
+        ? JOBS
+        : state.updateAvailable
+            ? UPDATE
+            : state.starDue
+                ? STAR
+                : HELP;
+    const title = truncateContinueTitle(state.lastSessionTitle ?? '');
+    if (title !== '') {
+        return [
+            { ...CONTINUE, labelKey: 'launchpad-action-continue-titled', values: { title } },
+            SESSIONS_WORKSPACE,
+            SETTINGS,
+            conditional,
+        ];
+    }
+    return [SESSIONS_WORKSPACE, SETTINGS, conditional];
+}

package/lib/types/components/launchpadLayout.d.ts

@@ -0,0 +1,62 @@
+import type { SplashFont } from './splashFonts.js';
+/** 输入框卡片占的行数：边框 2 + 输入 1（第三版：参数行移出框外）。 */
+export declare const CARD_ROWS = 3;
+/** 框下参数行的行数（模型/思考深度/模式/权限全空时整行不画）。 */
+export declare const PARAM_ROWS = 1;
+/** 该尺寸下渲染哪一档。 */
+export type LaunchpadStage = 'full' | 'no-tip' | 'no-hints' | 'no-art' | 'input-only';
+/** 一屏落地页在该尺寸下要渲染哪些部件。 */
+export interface LaunchpadLayout {
+    /** 整块撤的顺序档位。 */
+    readonly stage: LaunchpadStage;
+    /** 渲染像素鲸鱼 / 女仆娘立绘（宽轴决定；窄了不画，免得被裁）。 */
+    readonly showWhale: boolean;
+    /** 渲染 DEEPSEEK / HARNESS 块体大字。 */
+    readonly showBigTitle: boolean;
+    /** 大字放不下、立绘也放不下：退化成一行纯文字标题。 */
+    readonly showPlainTitle: boolean;
+    /** 头部整块是否渲染。 */
+    readonly showHero: boolean;
+    /** 键帽按钮行（框下成组行的第二行，右对齐）。 */
+    readonly showHints: boolean;
+    /** 居中 Tips 行（成组行的第三行）。 */
+    readonly showTip: boolean;
+    /**
+     * 参数行与入口行之间的呼吸留白行数（0 或 1）：默认 1；矮屏阶梯里排在
+     * Tips 之后、键帽行之前被撤掉。参数行缺席时恒 0（没有可隔开的两行）。
+     */
+    readonly hintsGapRows: number;
+    /**
+     * 词标与输入框之间的呼吸留白行数（1 或 2，第六版默认 2——刻意的呼吸感，
+     * 不是遗漏）：矮屏阶梯里先于 Tips 行被撤回紧档 1。
+     */
+    readonly heroGapRows: number;
+    /**
+     * 入口行与 Tips 行之间的呼吸留白行数（1 或 2，第六版默认 2）：矮屏阶梯
+     * 里先于 Tips 行被撤回紧档 1（Tips 行本身更晚才整行撤掉）。
+     */
+    readonly tipGapRows: number;
+    /** 双角铭牌行（永远画：它是这一屏的底边锚点）。 */
+    readonly showCorners: boolean;
+    /** 输入框卡片占的行数（边框 2 + 输入 1，恒 3）。 */
+    readonly cardRows: number;
+    /** 头部本体占的行数（不含 LogoV2 根盒的 marginTop）。 */
+    readonly heroRows: number;
+    /** 内容总行数——测试用来钉死这一档真的放得下。 */
+    readonly totalRows: number;
+}
+/**
+ * @param columns - 内容区列数。
+ * @param rows - 内容区行数。
+ * @param options - whale / whaleGirl 对应设置项；font 是当天那款字体（字身宽度
+ *   不同，宽轴阈值也跟着不同）；params 是框下有没有参数行（模型/思考深度/模式/
+ *   权限全拿不到时为 false，成组行矮一行）。
+ * @returns 该尺寸下要渲染的部件。
+ */
+export declare function resolveLaunchpadLayout(columns: number, rows: number, options: {
+    whale: boolean;
+    whaleGirl?: boolean;
+    font: SplashFont;
+    params?: boolean;
+}): LaunchpadLayout;
+//# sourceMappingURL=launchpadLayout.d.ts.map

package/lib/types/components/launchpadLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launchpadLayout.d.ts","sourceRoot":"","sources":["../../../src/components/launchpadLayout.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AA0ClD,0CAA0C;AAC1C,eAAO,MAAM,SAAS,IAAI,CAAA;AAC1B,sCAAsC;AACtC,eAAO,MAAM,UAAU,IAAI,CAAA;AAwC3B,iBAAiB;AACjB,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,YAAY,CAAA;AAErF,yBAAyB;AACzB,MAAM,WAAW,eAAe;IAC9B,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,gBAAgB;IAChB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACnF,eAAe,CAwFjB"}

package/lib/types/components/launchpadLayout.js

@@ -0,0 +1,176 @@
+import { bigTextWidth } from './bigfont.js';
+import { WHALE_BOX_WIDTH } from './splashLayout.js';
+/**
+ * 落地页的降级阶梯——两个轴一起解：
+ *
+ * **宽轴**：上下排布之后立绘与词标各自独立判断（谁都别挤谁）——词标放不下就
+ * 退化成一行纯文字标题，立绘放不下（窄于盒宽）就不画。
+ * **高轴**是本模块的：落地页是整屏、放不下就没了，所以按行数再排一次顺序
+ * **整块撤**，顺序从最可省到最不可省：
+ *
+ *   ① full       —— 头部 + 输入框 + 紧贴框下的成组三行（参数/键帽/Tips）+ 双角铭牌
+ *   ② full-撤呼吸 —— 第六版两处呼吸留白（词标↔输入框、入口行↔Tips，各 2 行）
+ *                   先撤回紧档 1 行，参数行留白随后也撤——**留白是刻意的
+ *                   呼吸感，不是遗漏**；所有留白永远排在 Tips/入口行之前撤
+ *   ③ no-tip     —— 撤 Tips 行（最可省的一句闲话）
+ *   ④ no-hints   —— 撤键帽按钮行（鼠标的礼貌；命令名本身还在 `/` 里）
+ *   ⑤ no-art     —— 撤立绘（13 行，最占地方的那块），只留词标
+ *   ⑥ input-only —— 只留词标 + 输入框 + 双角铭牌（最矮的终端也要能敲进去第一句）
+ *
+ * 双角铭牌（工作路径:分支 / 版本号）钉在最底一行，是这一屏唯一不随阶梯消失的
+ * 装饰——它把整块界面扎在终端底边上。
+ *
+ * 版面契约（2026-10 第三版）：
+ * - 头部走 LogoV2 的 chrome=minimal + arrangement=column：立绘在上、
+ *   DEEPSEEK/HARNESS 大字在下，两块各自水平居中；版号/模型/工作目录/提示一律不进
+ *   头部（它们各自有更低频的位置：参数进框下成组行，目录与版本进底角）。
+ * - 输入框（圆角边框）里**只有输入那一行**；参数行移到框外、紧贴框下方，
+ *   左对齐输入框。整组（头部 + 输入框 + 参数/键帽/Tips 三行）垂直居中，
+ *   不钉屏幕底、中间不留大空档。
+ * - 键帽按钮行整行右对齐（与输入框右缘对齐）；Tips 行居中、`● Tips：` 前缀。
+ *
+ * 所有列数按**内容区**算（PageMargin 已经把 TerminalSizeContext 收窄）；行数
+ * 同理。落地页不自己减页边距。
+ */
+/** 鲸鱼/女仆娘立绘（含盒）的行数。 */
+const WHALE_ART_ROWS = 13;
+/** 块体大字的行数：上排 5 + 空 1 + 下排 5。 */
+const BIG_TITLE_ROWS = 11;
+/** 只留文字的档位：一行纯标题。 */
+const PLAIN_TITLE_ROWS = 1;
+/** 输入框卡片占的行数：边框 2 + 输入 1（第三版：参数行移出框外）。 */
+export const CARD_ROWS = 3;
+/** 框下参数行的行数（模型/思考深度/模式/权限全空时整行不画）。 */
+export const PARAM_ROWS = 1;
+/**
+ * 头部与卡片之间的呼吸留白（第六版，2026-10 用户原话「DeepSeekHarness 和
+ * 输入框中间空一行」）：默认 2 行。**这是刻意的版面呼吸感，不是遗漏**——
+ * 别在重构时把它当成 bug 修掉。矮屏阶梯里它排在参数行留白之后、Tips 行
+ * 之前被撤（撤到紧档 1 行），绝不让呼吸把输入框挤掉。
+ */
+const HERO_TO_CARD_GAP = 2;
+/** 矮屏撤呼吸后的紧档（第五版的老间距：词标与输入框隔 1 行）。 */
+const HERO_TO_CARD_GAP_TIGHT = 1;
+/** LogoV2 根盒自带的 marginTop——真实占一行，阶梯预算必须算进去，否则恰好卡
+ *  阈值时卡片会被挤掉最后一行（夹具实证）。 */
+const HERO_TOP_MARGIN = 1;
+/**
+ * 参数行与入口行之间的呼吸留白（第五版，2026-10 用户实测「跟输入框太紧了，
+ * 留一两行空」）：默认 1 行。**这行留白是刻意的版面呼吸感，不是遗漏**——
+ * 别在重构时把它当成 bug 修掉。只在参数行画出来时才存在（参数全空时入口行
+ * 直接紧贴框底，原契约不变）。矮屏阶梯里它的取舍顺序排在 Tips 之后、
+ * 键帽行之前：先撤留白、再撤键帽行，绝不让这行呼吸把输入框挤掉。
+ */
+const PARAM_HINTS_GAP_ROWS = 1;
+/** 键帽按钮行：参数行之下、隔一行呼吸留白（矮屏可撤，见 PARAM_HINTS_GAP_ROWS）。 */
+const HINTS_ROWS = 1;
+/**
+ * Tips 行：自身 1 行 + 上方呼吸留白（第六版，用户原话「继续等按钮和 tips
+ * 中间空一行」→ 入口行与 Tips 之间默认 2 行空行）。**这行留白同样是刻意的
+ * 呼吸感，不是遗漏**；矮屏阶梯里先撤它（回到 1 行）再撤 Tips 行本身。
+ */
+const TIP_BLOCK_ROWS = 3;
+/** 矮屏撤呼吸后的紧档（自身 1 + 留白 1）。 */
+const TIP_BLOCK_ROWS_TIGHT = 2;
+/**
+ * 双角铭牌：自身 2 行 + 上方 1 行留白。自身 2 行是第七版**版本号竖排**带来
+ * 的——右下角两行（`dsh-tui v…` 在上、`dsh-core v…` 在下），左下目录铭牌仍
+ * 1 行、与第一行顶对齐。内核版本读不到时右侧只画 1 行（预算按 2 行上限算，
+ * 矮屏阶梯的取舍顺序不变：先撤装饰、绝不让输入框被挤掉）。
+ */
+const CORNERS_BLOCK_ROWS = 3;
+/**
+ * @param columns - 内容区列数。
+ * @param rows - 内容区行数。
+ * @param options - whale / whaleGirl 对应设置项；font 是当天那款字体（字身宽度
+ *   不同，宽轴阈值也跟着不同）；params 是框下有没有参数行（模型/思考深度/模式/
+ *   权限全拿不到时为 false，成组行矮一行）。
+ * @returns 该尺寸下要渲染的部件。
+ */
+export function resolveLaunchpadLayout(columns, rows, options) {
+    const { font } = options;
+    // 与 resolveSplashLayout 同一套阈值：末尾那一格字距也算进去，否则恰好卡阈值
+    // 时 Ink 会把最后一个字形换成省略号。
+    const titleWidth = bigTextWidth(font, font.tagline.top, font.tagline.topKerning) + font.tagline.topKerning;
+    const showBigTitle = columns >= titleWidth;
+    const artBox = WHALE_BOX_WIDTH;
+    const wantsArt = options.whale || options.whaleGirl === true;
+    // 上下排布：立绘只看自己放不放得下，不再和词标抢同一行的宽度。
+    const showWhale = wantsArt && columns >= artBox;
+    const showPlainTitle = !showBigTitle && !showWhale;
+    const showHero = showWhale || showBigTitle || showPlainTitle;
+    // 上下排布时头部 = 立绘 + 间隔 1 + 大字；退化档位取各自实际行数。
+    const artRows = showWhale ? WHALE_ART_ROWS : 0;
+    const titleRows = showBigTitle ? BIG_TITLE_ROWS : PLAIN_TITLE_ROWS;
+    const heroRows = showHero ? (artRows > 0 ? artRows + 1 + titleRows : titleRows) : 0;
+    // 头部整块（含根盒 marginTop）实际占的行数：阶梯与 totalRows 都按它算。
+    const heroBlockRows = showHero ? heroRows + HERO_TOP_MARGIN : 0;
+    // 第六版行数预算：输入框（恒 3）+ 框下成组行（参数 1 + 呼吸留白 0/1 +
+    // 键帽 1 + Tips 3）+ 双角铭牌 2。撤的顺序「从最可省到最不可省」：
+    // 新增的两处呼吸（词标↔输入框、入口行↔Tips）→ 参数行呼吸留白 → Tips 行
+    // 本身 → 键帽行 → 立绘（**所有留白永远排在 Tips/入口行之前撤**，
+    // 绝不让呼吸把输入框挤掉）。
+    const paramRows = options.params === true ? PARAM_ROWS : 0;
+    const gapRows = paramRows > 0 ? PARAM_HINTS_GAP_ROWS : 0;
+    const cardRows = CARD_ROWS;
+    const withArt = artRows > 0 ? artRows + 1 : 0;
+    const core = heroBlockRows + cardRows + paramRows + CORNERS_BLOCK_ROWS;
+    // 每一档的总行数。顺序即从最全的往下掉：先试最全的，放不下就往下掉。
+    // full 带 4 个变体（呼吸×参数留白的紧/松组合）、no-tip 带 3 个：
+    // 呼吸在（默认 2/2）→ 撤呼吸（紧档 1/1）→ 撤参数留白，全部都矮于撤 Tips。
+    const stages = [
+        { stage: 'full', breath: true, gap: true, rows: core + HERO_TO_CARD_GAP + gapRows + HINTS_ROWS + TIP_BLOCK_ROWS },
+        { stage: 'full', breath: false, gap: true, rows: core + HERO_TO_CARD_GAP_TIGHT + gapRows + HINTS_ROWS + TIP_BLOCK_ROWS_TIGHT },
+        { stage: 'full', breath: true, gap: false, rows: core + HERO_TO_CARD_GAP + HINTS_ROWS + TIP_BLOCK_ROWS },
+        { stage: 'full', breath: false, gap: false, rows: core + HERO_TO_CARD_GAP_TIGHT + HINTS_ROWS + TIP_BLOCK_ROWS_TIGHT },
+        { stage: 'no-tip', breath: false, gap: true, rows: core + HERO_TO_CARD_GAP_TIGHT + gapRows + HINTS_ROWS },
+        { stage: 'no-tip', breath: true, gap: false, rows: core + HERO_TO_CARD_GAP + HINTS_ROWS },
+        { stage: 'no-tip', breath: false, gap: false, rows: core + HERO_TO_CARD_GAP_TIGHT + HINTS_ROWS },
+        { stage: 'no-hints', breath: false, gap: false, rows: core + HERO_TO_CARD_GAP_TIGHT },
+        { stage: 'no-art', breath: false, gap: false, rows: core + HERO_TO_CARD_GAP_TIGHT - withArt },
+        { stage: 'input-only', breath: false, gap: false, rows: core + HERO_TO_CARD_GAP_TIGHT - withArt },
+    ];
+    // 默认落到最省的那一档：终端矮到连它都放不下时，宁可溢出也不把输入框藏起来
+    // ——这一屏存在的理由就是能敲进去第一句。
+    let stage = 'input-only';
+    let keepGap = false;
+    let keepBreath = false;
+    for (const candidate of stages) {
+        if (candidate.rows <= rows) {
+            stage = candidate.stage;
+            keepGap = candidate.gap;
+            keepBreath = candidate.breath;
+            break;
+        }
+    }
+    const dropArt = (stage === 'no-art' || stage === 'input-only') && withArt > 0;
+    const heroRowsFinal = dropArt ? titleRows : heroRows;
+    const heroBlockFinal = showHero ? heroRowsFinal + HERO_TOP_MARGIN : 0;
+    const showHints = stage === 'full' || stage === 'no-tip';
+    const showTip = stage === 'full';
+    // 留白只画在「参数行 ↔ 入口行」之间：两行都在且这一档保住了留白才算数。
+    const hintsGapRows = showHints && keepGap ? gapRows : 0;
+    // 两处呼吸（词标↔输入框、入口行↔Tips）：默认 2 行，矮屏先撤回紧档 1 行。
+    const heroGapRows = keepBreath ? HERO_TO_CARD_GAP : HERO_TO_CARD_GAP_TIGHT;
+    const tipGapRows = keepBreath ? TIP_BLOCK_ROWS - 1 : TIP_BLOCK_ROWS_TIGHT - 1;
+    const total = (showTip ? 1 + tipGapRows : 0) + hintsGapRows + (showHints ? HINTS_ROWS : 0) + heroBlockFinal
+        + heroGapRows + cardRows + paramRows + CORNERS_BLOCK_ROWS;
+    return {
+        stage,
+        // dropArt 只撤立绘——`heroRowsFinal`/`totalRows` 都按「撤立绘、留大字」算，
+        // 这里跟着把大字也杀掉会让字段自相矛盾（测试代理实测抓到）。
+        showWhale: showWhale && !dropArt,
+        showBigTitle,
+        showPlainTitle: showBigTitle ? false : showPlainTitle || dropArt,
+        showHero,
+        showHints,
+        showTip,
+        hintsGapRows,
+        heroGapRows,
+        tipGapRows,
+        showCorners: true,
+        cardRows,
+        heroRows: heroRowsFinal,
+        totalRows: total,
+    };
+}

package/lib/types/components/messages/AssistantThinkingMessage.js

@@ -8,7 +8,7 @@ import { formatDuration } from '../../terminal-utils/format.js';
 import { THINKING_SPINNER_FRAMES, THINKING_SPINNER_INTERVAL_MS, THINKING_SETTLED_MARKER, } from '../../terminal-utils/figures.js';
 import { BRAND, ICE } from '../shimmer.js';
 import { interpolateColor } from '../Spinner/spinnerUtils.js';
-import { isMinimalMode } from '../../minimalMode.js';
+import { isMinimalUiMode } from '../../minimalUiMode.js';
 import { primaryComboString } from '../../utils/keymap.js';
 /** Preview body rows — a FIXED row count (kimicode-style constant-height
  *  ticker). Ink's truncate slices the whole string across newlines as one
@@ -48,10 +48,10 @@ export function AssistantThinkingMessage({ thinking, textFull, marginTopOnTurn,
         : '';
     // Kimi Code style blue pulse: the streaming glyph breathes along the
     // header's brand→ice ladder, one sine period per ~7 frames (≈0.56s) —
-    // lively without strobing. Minimal mode drops the color (plain glyph);
+    // lively without strobing. The minimal UI drops the color (plain glyph);
     // settled always keeps the plain dim anchor.
     const label = `${t('thinking-label')}${duration}${streaming ? '…' : ` ${t('hint-expand-ctrl-o', { key: primaryComboString('transcript') })}`}`;
-    const minimal = isMinimalMode();
+    const minimalUi = isMinimalUiMode();
     const pulse = (Math.sin(frame * 0.9) + 1) / 2;
     const pulseColor = interpolateColor(BRAND, ICE, pulse);
     const frameText = THINKING_SPINNER_FRAMES[frame % THINKING_SPINNER_FRAMES.length];
@@ -61,7 +61,7 @@ export function AssistantThinkingMessage({ thinking, textFull, marginTopOnTurn,
     const hoverProps = onClick !== undefined
         ? { onMouseEnter: () => setHovered(true), onMouseLeave: () => setHovered(false) }
         : {};
-    const header = streaming ? (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: minimal ? frameText : chalk.rgb(pulseColor.r, pulseColor.g, pulseColor.b).bold(frameText) }), _jsx(Text, { dimColor: !hovered, color: hovered ? 'text' : undefined, italic: true, children: ` ${label}` })] })) : (_jsx(Text, { italic: true, dimColor: !hovered, color: hovered ? 'text' : undefined, children: `${minimal ? '*' : THINKING_SETTLED_MARKER} ${label}` }));
+    const header = streaming ? (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { children: minimalUi ? frameText : chalk.rgb(pulseColor.r, pulseColor.g, pulseColor.b).bold(frameText) }), _jsx(Text, { dimColor: !hovered, color: hovered ? 'text' : undefined, italic: true, children: ` ${label}` })] })) : (_jsx(Text, { italic: true, dimColor: !hovered, color: hovered ? 'text' : undefined, children: `${minimalUi ? '*' : THINKING_SETTLED_MARKER} ${label}` }));
     if (preview) {
         // Live ticker: the model's last few reasoning lines, dimmed, one Text
         // per row so each truncates to the width independently, padded to a

package/lib/types/components/onboardingModel.d.ts

@@ -0,0 +1,83 @@
+import type { LlmModelInfo, LlmProviderInfo } from '../adapter/ports/channel-view.js';
+import type { BalanceResult } from '../adapter/ports/channel-catalog.js';
+/** 引导的四个配置域，按"先解决拦路的事、再解决好不好看、最后解决怎么用"排。 */
+export declare const ONBOARDING_STEPS: readonly ["apikey", "look", "model", "keys"];
+export type OnboardingStep = (typeof ONBOARDING_STEPS)[number];
+/**
+ * 步骤条需要的**最小**尺寸：四步的标题横排（`❯ API Key 与连通性 · ...`）
+ * 在 76 列下会被截成残句，在 8 行下会把内容挤没——那时整条不画，进度改由
+ * 头部那行"第 N / 4 步"承担（信息不丢，只是换了个地方）。
+ */
+export declare const STEP_BAR_MIN_COLUMNS = 76;
+export declare const STEP_BAR_MIN_ROWS = 10;
+/** 第四步（招式卡）里的一张卡。 */
+export interface TutorialCard {
+    /** 稳定 id（"试过没有"记在它上面）。 */
+    readonly id: string;
+    readonly titleKey: string;
+    readonly descKey: string;
+    /**
+     * 可试的命令名（不含斜杠）；`undefined` = 只能读的键位卡。
+     *
+     * 键位卡故意不给"试一下"：`Esc` / `Ctrl+C` 只有在真回合里才有意义，在引导
+     * 里按下去要么没反应、要么把引导关掉——那是在骗人。命令卡则真的能开：
+     * 交给 Chat 的 `runCommand`，与手敲 `/help` 走同一条路。
+     */
+    readonly command?: string;
+    /** 键位卡的按键动作 id（`utils/keymap` 的 `ShortcutActionId`）。 */
+    readonly action?: 'cancel';
+    /** 纯字面量的键（`/` / `?` 这类不是可重绑动作的）。 */
+    readonly literal?: string;
+}
+/**
+ * 招式卡表：四张能**直接试用**的命令卡 + 两张只能读的键位卡。
+ * 顺序 = 使用频率，不按重要性；第一张是用户最先会需要的。
+ */
+export declare const TUTORIAL_CARDS: readonly TutorialCard[];
+/**
+ * 某一步的标题 key。
+ * @param step - 步骤 id。
+ * @returns 该步标题的 i18n key。
+ */
+export declare function stepTitleKey(step: OnboardingStep): string;
+/**
+ * 某一步的说明 key。
+ * @param step - 步骤 id。
+ * @returns 该步说明的 i18n key。
+ */
+export declare function stepDescKey(step: OnboardingStep): string;
+/** provider 分组（首现顺序，名字用注册表的，取不到就退回 route key）。 */
+export declare function modelGroupsOf(models: readonly LlmModelInfo[], providers: readonly LlmProviderInfo[]): readonly {
+    provider: string;
+    label: string;
+    count: number;
+}[];
+/**
+ * 余额显示串：取第一条，币种码直接用接口给的（不猜符号）。
+ *
+ * @param result - `channel.balanceInfo()` 的返回值。
+ * @returns `"CNY 110.00"` 这类串；没有可用条目时 `null`。
+ */
+export declare function formatBalance(result: BalanceResult): string | null;
+/**
+ * 连通性失败分类 → 可执行的下一步。
+ *
+ * 分类口径与 `BalanceResult.reason` 一一对应，因为"检查网络"这种话对
+ * `unauthorized` 的用户毫无用处——五种原因要指向五个不同的动作，这正是
+ * `BalanceResult` 分了五类的原因。
+ *
+ * @param reason - `BalanceResult.reason`。
+ * @param status - 非 2xx 时的状态码。
+ * @returns 给用户看的排查方向。
+ */
+export declare function connFailText(reason: string, status?: number): string;
+/**
+ * 凭证来源的显示文案。`CredentialStatus.source` 是 adapter 自己的口径
+ * （`'env'` / `'config'` / 其他），这里只做展示映射，认不出的值一律走
+ * "未知"而不是把原始串丢到界面上——那个串属于 adapter 内部词汇。
+ *
+ * @param source - `CredentialStatus.source`。
+ * @returns 一句中文/英文来源说明。
+ */
+export declare function credentialSourceText(source: string | undefined): string;
+//# sourceMappingURL=onboardingModel.d.ts.map

package/lib/types/components/onboardingModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboardingModel.d.ts","sourceRoot":"","sources":["../../../src/components/onboardingModel.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAA;AAExE,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,8CAA+C,CAAA;AAC5E,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE9D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAA;AACtC,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC,qBAAqB;AACrB,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAA;IAI1B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAOjD,CAAA;AAkBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAExD;AAED,kDAAkD;AAClD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,SAAS,EAAE,SAAS,eAAe,EAAE,GACpC,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAe/D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAKlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CASpE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIvE"}