@deepseek-harness-tui/dsh-tui 0.12.0 → 0.14.0

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/launchpadParams.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 落地页参数行的**三段式宽度分配**（2026-10）。
+ *
+ * 参数行是输入框下那一行四段值：`模型 · 思考深度 · agent preset 显示名 ·
+ * 权限 preset 名`。改造前是「逐段累加、第一个超预算的段直接 break」，于是
+ * **从尾部整段消失**（权限 → preset → 思考深度 → 模型）——preset 显示名一长
+ * （名册的 `config.name`，长度不可控），最先走的恰好是那一屏唯一的安全读数
+ * （`danger-full-access` = 不审批 + 全盘写）。
+ *
+ * 现在的三档（自顶向下，第一个成立者胜出）：
+ *
+ *   ① FIT       —— 四段按原样装得下 → **原样返回**（常规场景逐字节不变）；
+ *   ② TRUNCATED —— 装不下 → 挑**可缩减量最大**（`宽度 - 下限`）的段做**尾部
+ *                   截断**（`truncateToWidth(text, max - 1) + '…'`），一次减掉
+ *                   当前超宽量；减到各自的 `PARAM_SEGMENT_MIN_WIDTH` 或装下为止。
+ *                   **权限段不被截断**、宽度 ≤ 下限的段不可减（`Max` 这类短段
+ *                   因此永不被砍）——所以这一档**四段都在**，被压缩的是最长的
+ *                   非权限段；
+ *   ③ FALLBACK  —— 非权限段全压到下限仍装不下（**完整权限名放不进预算**时——
+ *                   终端 ≥76 列后，再宽也不改变结果；更窄的终端或更长的权限名
+ *                   都会更早触发）→ **逐字节复刻改造前的尾部省段**：用**原始宽度**
+ *                   按显示顺序累加、首个超预算即 break（权限段最先被省；用户裁决
+ *                   这一档"与今天逐字节一致"，决策当时的措辞是"极窄屏"——
+ *                   准确条件即上面这条）。
+ *
+ * 纯函数：不改入参、不读环境、同样输入恒同样输出——`verify-launchpad.tsx`
+ * 的 Q 组表驱动回归钉死三档与边界（含"撤实现必红"留证）。
+ *
+ * **改动本契约时必须同时更新的地方**：本模块顶部的两个常量与三条注释、
+ * `Launchpad.tsx` 的接入点、`scripts/verify-launchpad.tsx` 的 Q 组、
+ * `docs/interaction{,.en}.md` 与 `docs/user-guide{,.en}.md`（+ `guide/**` 副本）。
+ */
+/**
+ * 段之间的分隔符——**与组件渲染的那串是同一个**（两侧各两格）。导出它是为了让
+ * `Launchpad.tsx` 画分隔符时直接用它、别再造一份字面量：这里的宽度记账与那边
+ * 画出来的字符必须是同一个决定，否则改一处就悄悄错位。
+ */
+export declare const PARAM_SEPARATOR = "  \u00B7  ";
+/**
+ * 每段被压缩后的**显示宽度下限**（含 `…`）：12 格 ≈ 11 个可见字符，仍能读出
+ * 段首词（`Standard (G…`、`deepseek-fl…`）；再小就只剩两三个字符，阅读价值不
+ * 足以继续挤压别的段——那时让位给兜底档更诚实。量级参照同族常量
+ * `LAUNCHPAD_CONTINUE_TITLE_MAX = 16`（`launchpadActions.ts`）。
+ */
+export declare const PARAM_SEGMENT_MIN_WIDTH = 12;
+/**
+ * **永不被截断**的段：权限 preset 名是启动第一屏唯一的安全读数（危险权限 =
+ * 不审批 + 全盘写），半截的权限名和没有权限名一样不可靠。它是"截断阶段"的
+ * 豁免；兜底档仍按改造前的顺序整段省（用户裁决，见模块头注释③）。
+ */
+export declare const PARAM_UNTRUNCABLE_SEGMENT = "permission";
+/**
+ * 参数行的一段（与 `Launchpad.tsx` 的 `paramParts` 同形）。
+ * `S` 是段的字面量联合（`LaunchpadParamSegment`），泛型原样透传、不丢字面量类型
+ * ——Chat 侧按 `segment` 分派选择器。
+ */
+export interface ParamPart<S extends string = string> {
+    /** 段的身份（焦点环、选择器分派都用它）。 */
+    readonly segment: S;
+    /** 当前显示值（拟合前的原值）。 */
+    readonly value: string;
+    /** 模型段带主题色（其余 dim）；原样透传给组件。 */
+    readonly colored?: boolean;
+}
+/**
+ * 参数行降级的**档位**（T-FIX-05 / REVIEW F-09）：三档契约的机器可读载体。
+ *
+ * 以前"这一次落在哪一档"只活在模块头注释与回归的推断里，文档一旦漂移（F-02 就是
+ * 漂了的那一处）没有任何机制能发现；现在它是 `FittedParamPart.tier`，可以直接断言
+ * ——断它比断 `truncated` 或数组长度更贴近契约本身（"哪一档"是契约，"某段是否被截"
+ * 只是档内的结果）。
+ */
+export type ParamFitTier = 'fit' | 'truncated' | 'fallback';
+/** 拟合后的一段：显示值 + 是否被截断 + 完整名（tooltip 用）+ 档位。 */
+export interface FittedParamPart<S extends string = string> {
+    /** 段的身份（原样透传）。 */
+    readonly segment: S;
+    /** 最终显示值；被截断时以 `…` 结尾，其余与 `fullValue` 逐字节相同。 */
+    readonly value: string;
+    /** 模型段带主题色（原样透传）。 */
+    readonly colored?: boolean;
+    /** 完整名（截断前的原值）——hover tooltip 显示它。 */
+    readonly fullValue: string;
+    /** 本段是否被尾部截断（`value !== fullValue` 的等价标志）。 */
+    readonly truncated: boolean;
+    /**
+     * 本行落在哪一档：`fit` 原样 / `truncated` 尾部截断 / `fallback` 尾部省段。
+     * **同一行的各段恒相同**（档位是"行"的决定，不是"段"的）。
+     */
+    readonly tier: ParamFitTier;
+}
+/**
+ * 参数行的宽度分配（落地页唯一的入口；组件不要再自己写累加循环）。
+ *
+ * @param parts - 按**显示顺序**给出的段（模型 · 思考深度 · preset · 权限）。
+ * @param budget - 这一行的显示宽度预算（`max(24, min(columns - 4, 72)) - 2`）。
+ * @returns 拟合后的段（新数组；FIT 档与入参逐字节等值，TRUNCATED 档四段都在）。
+ *   每段的 `tier` 标明本行落在哪一档（见 `ParamFitTier`）——同一行的各段恒相同。
+ */
+export declare function fitParamParts<S extends string>(parts: readonly ParamPart<S>[], budget: number): readonly FittedParamPart<S>[];
+//# sourceMappingURL=launchpadParams.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"launchpadParams.d.ts","sourceRoot":"","sources":["../../../src/components/launchpadParams.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe,eAAU,CAAA;AAItC;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,eAAe,CAAA;AAErD;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAClD,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,qBAAqB;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,WAAW,GAAG,UAAU,CAAA;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACxD,kBAAkB;IAClB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,qBAAqB;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAC5B;AAuGD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC5C,KAAK,EAAE,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE,EAC9B,MAAM,EAAE,MAAM,GACb,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,CAS/B"}

package/lib/types/components/launchpadParams.js

@@ -0,0 +1,171 @@
+import { stringWidth } from '../ink/stringWidth.js';
+import { truncateToWidth } from '../ink/truncateToWidth.js';
+/**
+ * 落地页参数行的**三段式宽度分配**（2026-10）。
+ *
+ * 参数行是输入框下那一行四段值：`模型 · 思考深度 · agent preset 显示名 ·
+ * 权限 preset 名`。改造前是「逐段累加、第一个超预算的段直接 break」，于是
+ * **从尾部整段消失**（权限 → preset → 思考深度 → 模型）——preset 显示名一长
+ * （名册的 `config.name`，长度不可控），最先走的恰好是那一屏唯一的安全读数
+ * （`danger-full-access` = 不审批 + 全盘写）。
+ *
+ * 现在的三档（自顶向下，第一个成立者胜出）：
+ *
+ *   ① FIT       —— 四段按原样装得下 → **原样返回**（常规场景逐字节不变）；
+ *   ② TRUNCATED —— 装不下 → 挑**可缩减量最大**（`宽度 - 下限`）的段做**尾部
+ *                   截断**（`truncateToWidth(text, max - 1) + '…'`），一次减掉
+ *                   当前超宽量；减到各自的 `PARAM_SEGMENT_MIN_WIDTH` 或装下为止。
+ *                   **权限段不被截断**、宽度 ≤ 下限的段不可减（`Max` 这类短段
+ *                   因此永不被砍）——所以这一档**四段都在**，被压缩的是最长的
+ *                   非权限段；
+ *   ③ FALLBACK  —— 非权限段全压到下限仍装不下（**完整权限名放不进预算**时——
+ *                   终端 ≥76 列后，再宽也不改变结果；更窄的终端或更长的权限名
+ *                   都会更早触发）→ **逐字节复刻改造前的尾部省段**：用**原始宽度**
+ *                   按显示顺序累加、首个超预算即 break（权限段最先被省；用户裁决
+ *                   这一档"与今天逐字节一致"，决策当时的措辞是"极窄屏"——
+ *                   准确条件即上面这条）。
+ *
+ * 纯函数：不改入参、不读环境、同样输入恒同样输出——`verify-launchpad.tsx`
+ * 的 Q 组表驱动回归钉死三档与边界（含"撤实现必红"留证）。
+ *
+ * **改动本契约时必须同时更新的地方**：本模块顶部的两个常量与三条注释、
+ * `Launchpad.tsx` 的接入点、`scripts/verify-launchpad.tsx` 的 Q 组、
+ * `docs/interaction{,.en}.md` 与 `docs/user-guide{,.en}.md`（+ `guide/**` 副本）。
+ */
+/**
+ * 段之间的分隔符——**与组件渲染的那串是同一个**（两侧各两格）。导出它是为了让
+ * `Launchpad.tsx` 画分隔符时直接用它、别再造一份字面量：这里的宽度记账与那边
+ * 画出来的字符必须是同一个决定，否则改一处就悄悄错位。
+ */
+export const PARAM_SEPARATOR = '  ·  ';
+/** 分隔符占据的显示格数（`·` 是 U+00B7，按窄字符算 1 格）。 */
+const PARAM_SEPARATOR_WIDTH = stringWidth(PARAM_SEPARATOR);
+/**
+ * 每段被压缩后的**显示宽度下限**（含 `…`）：12 格 ≈ 11 个可见字符，仍能读出
+ * 段首词（`Standard (G…`、`deepseek-fl…`）；再小就只剩两三个字符，阅读价值不
+ * 足以继续挤压别的段——那时让位给兜底档更诚实。量级参照同族常量
+ * `LAUNCHPAD_CONTINUE_TITLE_MAX = 16`（`launchpadActions.ts`）。
+ */
+export const PARAM_SEGMENT_MIN_WIDTH = 12;
+/**
+ * **永不被截断**的段：权限 preset 名是启动第一屏唯一的安全读数（危险权限 =
+ * 不审批 + 全盘写），半截的权限名和没有权限名一样不可靠。它是"截断阶段"的
+ * 豁免；兜底档仍按改造前的顺序整段省（用户裁决，见模块头注释③）。
+ */
+export const PARAM_UNTRUNCABLE_SEGMENT = 'permission';
+/** 一行参数行的显示宽度：各段宽之和 + 分隔符 ×（段数 - 1）。 */
+function lineWidth(parts) {
+    let sum = 0;
+    for (const [index, part] of parts.entries()) {
+        if (index > 0)
+            sum += PARAM_SEPARATOR_WIDTH;
+        sum += stringWidth(part.value);
+    }
+    return sum;
+}
+/**
+ * 一段的"原样"输出（FIT 档与兜底档都用它：`fullValue` = 原值、未截断）。
+ * `tier` 由调用方给出——它描述的是**整行**落在哪一档，不是这一段的局部状态。
+ */
+function fitWhole(part, tier) {
+    return { ...part, fullValue: part.value, truncated: false, tier };
+}
+/**
+ * 一段的**可缩减量**：权限段恒 0（不被截断），宽度 ≤ 下限的段也是 0（减不动，
+ * 例如 `Max`）——"可缩减量最大者先减"只在 > 0 的段里选。
+ */
+function reducibleOf(segment, width) {
+    if (segment === PARAM_UNTRUNCABLE_SEGMENT)
+        return 0;
+    return Math.max(0, width - PARAM_SEGMENT_MIN_WIDTH);
+}
+/**
+ * 挑**可缩减量最大**的段（D2 的缩减优先序；并列时取显示顺序在前的，保证同输入
+ * 恒同输出）。
+ *
+ * @param targets - 各段的**当前**目标宽度（被压过的段已经变小）。
+ * @returns 段下标；全都减不动（权限段 / 宽度 ≤ 下限的短段）时返回 `-1`。
+ */
+function pickMostReducible(parts, targets) {
+    let pick = -1;
+    let best = 0;
+    for (const [index, width] of targets.entries()) {
+        const reducible = reducibleOf(parts[index].segment, width);
+        if (reducible > best) {
+            pick = index;
+            best = reducible;
+        }
+    }
+    return pick;
+}
+/**
+ * 第二档：逐步尾部截断。每轮挑可缩减量最大的段，把它压到
+ * `max(下限, 当前宽度 - 剩余超宽)`。
+ *
+ * @param total - 四段的**原始**总宽（`fitParamParts` 已算过，避免重复记账）。
+ * @returns 装得下的四段；压到各段下限仍超预算时返回 `undefined`（交给兜底档）。
+ */
+function fitByTruncating(parts, budget, total) {
+    const original = parts.map(part => stringWidth(part.value));
+    /** 各段**当前**的目标宽度（未被压过的保持原始宽度）。 */
+    const targets = [...original];
+    let overflow = total - budget;
+    while (overflow > 0) {
+        const pick = pickMostReducible(parts, targets);
+        // 全是权限段 / 宽度 ≤ 下限的段：这一档减不动了。
+        if (pick < 0)
+            return undefined;
+        const target = Math.max(PARAM_SEGMENT_MIN_WIDTH, targets[pick] - overflow);
+        overflow -= targets[pick] - target;
+        targets[pick] = target;
+    }
+    const fitted = parts.map((part, index) => {
+        if (targets[index] >= original[index])
+            return fitWhole(part, 'truncated');
+        // 尾部截断：留一格给 `…`（码位安全，CJK 不会切半个字形）。
+        return { ...part, value: truncateToWidth(part.value, targets[index] - 1) + '…', fullValue: part.value, truncated: true, tier: 'truncated' };
+    });
+    // 宽度记账用**截断后的真实文本**再算一次（宽字符可能让实际值比目标更窄），
+    // 只有真的 ≤ 预算才认这一档——本函数的输出恒满足"总宽 ≤ budget"。
+    return lineWidth(fitted) <= budget ? fitted : undefined;
+}
+/**
+ * 第三档（兜底）：**逐字节复刻改造前的尾部省段**——用**原始宽度**按显示顺序
+ * 累加、首个超预算即 break。故意不改写、不"顺手保权限"：用户裁决这一档的形态与
+ * 今天一致（决策当时的措辞是"极窄屏"；准确条件是**完整权限名放不进预算**——
+ * 终端 ≥76 列后，再宽也不改变结果；更窄的终端或更长的权限名都会更早触发。
+ * v2 才考虑兜底保权限），回归（Q5/Q7）拿独立的同形循环做期望。
+ */
+function dropFromTail(parts, budget) {
+    const fitted = [];
+    let used = 0;
+    for (const part of parts) {
+        const width = stringWidth(part.value);
+        const next = fitted.length === 0 ? width : used + PARAM_SEPARATOR_WIDTH + width;
+        if (next > budget)
+            break;
+        fitted.push(fitWhole(part, 'fallback'));
+        used = next;
+    }
+    return fitted;
+}
+/**
+ * 参数行的宽度分配（落地页唯一的入口；组件不要再自己写累加循环）。
+ *
+ * @param parts - 按**显示顺序**给出的段（模型 · 思考深度 · preset · 权限）。
+ * @param budget - 这一行的显示宽度预算（`max(24, min(columns - 4, 72)) - 2`）。
+ * @returns 拟合后的段（新数组；FIT 档与入参逐字节等值，TRUNCATED 档四段都在）。
+ *   每段的 `tier` 标明本行落在哪一档（见 `ParamFitTier`）——同一行的各段恒相同。
+ */
+export function fitParamParts(parts, budget) {
+    const total = lineWidth(parts);
+    // ① 装得下：原样（普通宽度下与改造前逐字节一致）。
+    if (total <= budget)
+        return parts.map(part => fitWhole(part, 'fit'));
+    // ② 截断：四段都在，权限段一字不减。
+    const truncated = fitByTruncating(parts, budget, total);
+    if (truncated !== undefined)
+        return truncated;
+    // ③ 兜底：今天的尾部省段。
+    return dropFromTail(parts, budget);
+}

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

@@ -1,5 +1,34 @@
 import React from 'react';
 import type { TerminalImageSource } from '../ink/terminal-image.js';
+/**
+ * The maid portrait (鲸鱼娘) for `dsh-tui.whaleGirl` and the star modal —
+ * the author-designed 464×464 pixel art shipped at `assets/whale-girl/`,
+ * rendered FIRST as a real raster through the terminal image protocols
+ * (Kitty graphics / Sixel): full fidelity, anti-aliased curves, the whole
+ * palette. The chain degrades per surface when images cannot show — the
+ * header falls back to the character-art maid (`WhaleGirl.tsx`, the
+ * author's placeholder), the star modal to the animated pixel whale — so
+ * the setting never leaves the header worse than the whale it replaces.
+ */
+/** 一套立绘资产：`assets/` 下的目录 + `normal`/`happy` 两张变体。 */
+export interface PortraitAssets {
+    readonly dir: string;
+    readonly normal: string;
+    readonly happy: string;
+}
+/** 鲸鱼娘（DeepSeek 品牌，settings `dsh-tui.whaleGirl`）。 */
+export declare const MAID_ASSETS: PortraitAssets;
+/** Claude 娘（claude 品牌，见 `branding.ts`）：取自 cc-bridge 的开发期占位
+ * 素材（1024×1024 透明底×2）。授权注记：那边的 assets/README 标注授权未
+ * 确认——本仓库自用没问题，再分发前需确认或替换。 */
+export declare const CLAUDE_GIRL_ASSETS: PortraitAssets;
+/** 恶魔精灵（codex 品牌，见 `branding.ts`）：用户提供的淡紫像素立绘 ×2
+ * （628×628 透明底，Lanczos 自 1254² 重采样）——常态 = 淡紫恶魔精灵头像，
+ * 点击后切「按下红色按钮的紫月龙裔少女」几秒（与鲸鱼娘/claude 娘同一套
+ * reactMaid 交互）。 */
+export declare const CODEX_GIRL_ASSETS: PortraitAssets;
+/** 品牌档 → 立绘资产集（LogoV2 的立绘槽选这一份；deepseek 走鲸鱼娘）。 */
+export declare function portraitAssetsOf(brand: 'deepseek' | 'claude' | 'codex'): PortraitAssets;
 /** 一台机器上的两张立绘都解好、并补齐到**同一像素画布**上——几何完全一致，
  *  换图时宿主是「擦旧 + 画新」一次写入，不会留残影。 */
 export interface MaidPortraits {
@@ -7,18 +36,21 @@ export interface MaidPortraits {
     readonly happy: TerminalImageSource;
 }
 /**
- * 解码两张立绘一次（进程内缓存；失败缓存成 `undefined`，坏安装不会每次
- * 渲染都重试）。两张都裁掉透明边后**居中补到同一张透明画布**（取两者
- * 较大的宽高）——所以它们的像素尺寸与单元格盒完全一致。
+ * 解码一套立绘的两张变体（每套缓存一次）。两张都裁掉透明边后**居中补到
+ * 同一张透明画布**（取两者较大的宽高）——所以它们的像素尺寸与单元格盒
+ * 完全一致。资产候选同时覆盖两种目录深度：`lib/types/components`（发布
+ * 形态）比 `src/components`（仓库形态）深一层。
+ * @param assets - 资产集（默认鲸鱼娘；claude 品牌传 `CLAUDE_GIRL_ASSETS`）。
  * @returns 两张 RGBA 源；任一张缺失/解码失败时整体 `undefined`。
  */
-export declare function loadMaidPortraits(): Promise<MaidPortraits | undefined>;
+export declare function loadMaidPortraits(assets?: PortraitAssets): Promise<MaidPortraits | undefined>;
 /**
  * 两张立绘，终端图像能力确认后解码（一次把两张都备好，点击换图不等待）。
  * @param enabled - `useTerminalImages()` 的结果；为假时根本不解码。
+ * @param assets - 资产集（默认鲸鱼娘；claude 品牌传 `CLAUDE_GIRL_ASSETS`）。
  * @returns 两张 RGBA 源；未就绪/不可用时为 `undefined`。
  */
-export declare function useMaidPortraits(enabled: boolean): MaidPortraits | undefined;
+export declare function useMaidPortraits(enabled: boolean, assets?: PortraitAssets): MaidPortraits | undefined;
 /**
  * The portrait's center column inside the whale's 40-column slot: the
  * aspect-fit image spans columns 5..34 (center 19.5). The welcome tagline

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

@@ -1 +1 @@
-{"version":3,"file":"maidPortrait.d.ts","sourceRoot":"","sources":["../../../src/components/maidPortrait.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAuBnE;iCACiC;AACjC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CACpC;AASD;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CA+BtE;AAsDD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAW5E;AAKD;;;;GAIG;AACH,eAAO,MAAM,eAAe,OAAO,CAAA;AAEnC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,UAAU,EACV,OAAO,EACP,YAAY,GACb,EAAE;IACD,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAA;IACrC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,SAAS,CAAA;CAChD,GAAG,KAAK,CAAC,SAAS,CAuBlB"}
+{"version":3,"file":"maidPortrait.d.ts","sourceRoot":"","sources":["../../../src/components/maidPortrait.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAInE;;;;;;;;;GASG;AAEH,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,qDAAqD;AACrD,eAAO,MAAM,WAAW,EAAE,cAIzB,CAAA;AAED;;8BAE8B;AAC9B,eAAO,MAAM,kBAAkB,EAAE,cAIhC,CAAA;AAED;;;oBAGoB;AACpB,eAAO,MAAM,iBAAiB,EAAE,cAI/B,CAAA;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,cAAc,CAEvF;AAED;iCACiC;AACjC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CACpC;AAWD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,cAA4B,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAmC1G;AAsDD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,cAA4B,GAAG,aAAa,GAAG,SAAS,CAWlH;AAKD;;;;GAIG;AACH,eAAO,MAAM,eAAe,OAAO,CAAA;AAEnC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,UAAU,EACV,OAAO,EACP,YAAY,GACb,EAAE;IACD,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAA;IACrC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,SAAS,CAAA;CAChD,GAAG,KAAK,CAAC,SAAS,CAuBlB"}