dsh-config-manager 0.1.63 → 0.1.65

package/lib/ui/runs-view.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 运行中心（Run Center）纯渲染模型：把宿主 /runs 的 RunState 列表变成「一张卡片 + 一次决策」。
+ *
+ * 为什么单独一层：卡片要区分「在跑 / 在等人 / 已结束」，决策框要算「已应用多少 / 剩下多少」
+ * 并给出默认选项 —— 这些判据都必须可单测（UI 分层铁律：逻辑在 src/ui，React 壳只装配）。
+ *
+ * 三条设计约束（读码得出，不是偏好）：
+ *  1. **可终止 ≠ 所有 run**：只有导入引擎实现了「计划项边界协作式取消」（/runs/cancel）；
+ *     其余 run 类型（同步/恢复/备份/自动同步）没有安全点，UI 必须如实禁用而不是给个假按钮。
+ *  2. **待决策态优先于一切**：pendingDecision 非空时 run 并没有卡住，它在等人 —— 卡片必须显性提示，
+ *     否则用户会以为任务死了（这正是「终止需弹窗」的功能入口）。
+ *  3. **默认选项跟随既有偏好**：用户此前勾过「失败不回滚」（rollbackOnError=false）时，决策框默认落在
+ *     「保留已应用项」；没勾过则默认「回滚」。不推翻用户已有的心智，也不替他做更危险的选择。
+ */
+import type { RunKind, RunState } from '../core/run-registry.ts';
+import type { ImportLogCounts } from './import-log.ts';
+/** 终止决策（与宿主 /runs/cancel/decision 的取值一一对应）。 */
+export type CancelDecision = 'rollback' | 'keep';
+/** 一张运行卡片的纯数据模型（文案一律给 key，由壳层翻译）。 */
+export interface RunCardModel {
+    runId: string;
+    kind: RunKind;
+    /** 卡片标题 key（`runs.kind.<kind>`）。 */
+    kindLabelKey: string;
+    status: 'running' | 'done' | 'failed';
+    /** 状态徽章 key（`runs.status.<status>`；待决策时另由 awaitingDecision 覆盖显示）。 */
+    statusLabelKey: string;
+    /** 已到安全点、等用户选「回滚 / 保留」。 */
+    awaitingDecision: boolean;
+    /** 可手动终止（只有导入支持计划项边界协作式取消；已请求过就不再显示按钮）。 */
+    canCancel: boolean;
+    /**
+     * 已请求终止、正等当前计划项结束（null = 未请求）。
+     * `stuck` = 等待超过阈值 → 界面必须从「请稍候」升级为「给出路」。
+     */
+    cancelWait: {
+        minutes: number;
+        stuck: boolean;
+    } | null;
+    /** 可「跳过当前插件」（仅导入的插件安装阶段有意义）。 */
+    canSkip: boolean;
+    /** 进度（item/itemTotal 优先；导出用 section 计数）。 */
+    progress: {
+        labelKey: string;
+        section: string | null;
+        item: number | null;
+        itemTotal: number | null;
+        detail: string | null;
+        percent: number | null;
+    };
+    /** 日志聚合计数（无日志时为 null）。 */
+    counts: ImportLogCounts | null;
+    /** 需要用户关注的项数（警告 + 失败）。 */
+    problems: number;
+    /** 最近日志行（已截断；供折叠查看，不含敏感内容：宿主侧落账前已 redact）。 */
+    logTail: string[];
+    updatedAt: number;
+    /**
+     * 「最近一次更新」的相对时间（复用 overview.time.* 字典）。
+     * 为什么需要：没有它，「进行中」和「三小时前就结束的僵尸卡片」在界面上长得一模一样，
+     * 用户只能得出「一直在加载」的结论（真机报告）。
+     */
+    time: {
+        key: string;
+        params?: {
+            n: string;
+        };
+    };
+}
+/** 日志尾部保留行数（卡片里只给「最近发生了什么」，完整日志在所属页面）。 */
+export declare const RUN_CARD_LOG_TAIL = 8;
+/**
+ * 终止请求等多久算「可能卡住」（2 分钟）。
+ * 为什么要有阈值：协作式取消只能等到**项边界**，而插件安装可以跑几十分钟。
+ * 2 分钟内大概率是在装插件（正常），超过就该把出路摆到用户面前（跳过当前项 / 重启），
+ * 否则用户只能一遍遍点「终止…」——而那个按钮此刻已经没有任何作用了。
+ */
+export declare const CANCEL_STUCK_AFTER_MS: number;
+/**
+ * 相对时间（纯函数，now 显式传入 → 可单测）：刚刚 / N 分钟前 / N 小时前 / N 天前。
+ * 键复用 config-manager 字典里既有的 overview.time.*（同字典，不新造文案）。
+ */
+export declare function relativeTimeLabel(updatedAt: number, now: number): {
+    key: string;
+    params?: {
+        n: string;
+    };
+};
+/** RunState[] → 卡片模型（按 updatedAt 倒序；终态与进行中同列，由 status 区分）。 */
+export declare function runCards(runs: readonly RunState[], opts?: {
+    logTail?: number;
+    now?: number;
+}): RunCardModel[];
+/** 状态栏 / 抽屉徽章用的计数。 */
+export declare function runSummary(runs: readonly RunState[]): {
+    running: number;
+    awaiting: number;
+    total: number;
+};
+/** 终止决策框模型。 */
+export interface CancelDialogModel {
+    runId: string;
+    kindLabelKey: string;
+    /** 已经应用的计划项数（引擎回传的 executed 长度不可得，故用进度计数近似并如实标注）。 */
+    appliedCount: number | null;
+    /** 计划项总数（null = 宿主未上报）。 */
+    totalCount: number | null;
+    /** 未执行项数（total - applied；无法计算时 null）。 */
+    pendingCount: number | null;
+    defaultDecision: CancelDecision;
+    options: {
+        id: CancelDecision;
+        labelKey: string;
+        descKey: string;
+    }[];
+}
+/**
+ * 终止决策框模型。默认选项跟随用户既有的 rollbackOnError 偏好：
+ * 勾过「失败不回滚」→ 默认保留（与他的心智一致）；否则默认回滚（安全侧）。
+ */
+export declare function cancelDialogModel(run: Pick<RunState, 'runId' | 'kind' | 'item' | 'itemTotal'>, opts: {
+    defaultRollbackOnError: boolean;
+}): CancelDialogModel;
+/** 「已应用/未执行」的用户可读摘要参数（null → 壳层显示「未知」而不是编个数字）。 */
+export declare function cancelCostParams(model: CancelDialogModel): {
+    applied: string;
+    pending: string;
+};

package/lib/ui/runs-view.js

@@ -0,0 +1,123 @@
+import { buildImportLogModel } from './import-log.js';
+import { isSkippablePluginInstall } from './import-wizard.js';
+/** 日志尾部保留行数（卡片里只给「最近发生了什么」，完整日志在所属页面）。 */
+export const RUN_CARD_LOG_TAIL = 8;
+/**
+ * 终止请求等多久算「可能卡住」（2 分钟）。
+ * 为什么要有阈值：协作式取消只能等到**项边界**，而插件安装可以跑几十分钟。
+ * 2 分钟内大概率是在装插件（正常），超过就该把出路摆到用户面前（跳过当前项 / 重启），
+ * 否则用户只能一遍遍点「终止…」——而那个按钮此刻已经没有任何作用了。
+ */
+export const CANCEL_STUCK_AFTER_MS = 2 * 60 * 1000;
+/**
+ * 相对时间（纯函数，now 显式传入 → 可单测）：刚刚 / N 分钟前 / N 小时前 / N 天前。
+ * 键复用 config-manager 字典里既有的 overview.time.*（同字典，不新造文案）。
+ */
+export function relativeTimeLabel(updatedAt, now) {
+    const diffMs = Math.max(0, now - updatedAt);
+    const minutes = Math.floor(diffMs / 60_000);
+    if (minutes < 1)
+        return { key: 'overview.time.now' };
+    if (minutes < 60)
+        return { key: 'overview.time.min', params: { n: String(minutes) } };
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return { key: 'overview.time.hour', params: { n: String(hours) } };
+    return { key: 'overview.time.day', params: { n: String(Math.floor(hours / 24)) } };
+}
+function percentOf(item, itemTotal) {
+    if (item === null || itemTotal === null || itemTotal <= 0)
+        return null;
+    return Math.min(100, Math.max(0, Math.round((item / itemTotal) * 100)));
+}
+/** RunState[] → 卡片模型（按 updatedAt 倒序；终态与进行中同列，由 status 区分）。 */
+export function runCards(runs, opts = {}) {
+    const tail = opts.logTail ?? RUN_CARD_LOG_TAIL;
+    const now = opts.now ?? Date.now();
+    return [...runs]
+        .sort((a, b) => b.updatedAt - a.updatedAt)
+        .map((run) => {
+        const log = run.log ?? [];
+        const model = log.length > 0 ? buildImportLogModel(log) : null;
+        const running = run.status === 'running';
+        const awaitingDecision = running && run.pendingDecision === 'cancel';
+        // 终止请求已到达、但还没走到安全点：把「等了多久」算出来给界面用（见 CANCEL_STUCK_AFTER_MS）
+        const requestedAt = typeof run.cancelRequestedAt === 'number' ? run.cancelRequestedAt : null;
+        const waitedMs = requestedAt === null ? 0 : Math.max(0, now - requestedAt);
+        const cancelWait = requestedAt !== null && running && !awaitingDecision
+            ? { minutes: Math.floor(waitedMs / 60_000), stuck: waitedMs >= CANCEL_STUCK_AFTER_MS }
+            : null;
+        return {
+            runId: run.runId,
+            kind: run.kind,
+            kindLabelKey: `runs.kind.${run.kind}`,
+            status: run.status,
+            statusLabelKey: `runs.status.${run.status}`,
+            awaitingDecision,
+            // 只有导入实现了协作式取消；其余类型给禁用态（不给假按钮）。
+            // 已请求过终止就不再给按钮：再点也不会有新效果（run 级信号是幂等的），
+            // 留着一个亮着的主按钮只会让用户以为「多点几次就能好」。
+            canCancel: running && run.kind === 'import' && !awaitingDecision && cancelWait === null,
+            cancelWait,
+            // 「跳过当前插件」复用向导的**同一判据**（isSkippablePluginInstall：detail 带 plugin: 前缀），
+            // 绝不在这里另写一份「是不是插件安装项」的判断 —— 两份判据漂移会让两个页面对同一个 run
+            // 给出不同的可操作性。skipRequested 由运行中心自己的在途状态抑制（见 RunsCenter）。
+            canSkip: running && run.kind === 'import' && run.pendingDecision !== 'cancel'
+                && isSkippablePluginInstall(run.detail ?? undefined, running, false),
+            progress: {
+                labelKey: `runs.progress.${running ? 'running' : run.status === 'done' ? 'done' : 'failed'}`,
+                section: run.section,
+                item: run.item,
+                itemTotal: run.itemTotal,
+                detail: run.detail,
+                percent: percentOf(run.item, run.itemTotal),
+            },
+            counts: model === null ? null : model.counts,
+            problems: model === null ? 0 : model.problems,
+            logTail: log.slice(-Math.max(0, tail)),
+            updatedAt: run.updatedAt,
+            time: relativeTimeLabel(run.updatedAt, now),
+        };
+    });
+}
+/** 状态栏 / 抽屉徽章用的计数。 */
+export function runSummary(runs) {
+    let running = 0;
+    let awaiting = 0;
+    for (const run of runs) {
+        if (run.status !== 'running')
+            continue;
+        running += 1;
+        if (run.pendingDecision === 'cancel')
+            awaiting += 1;
+    }
+    return { running, awaiting, total: runs.length };
+}
+/**
+ * 终止决策框模型。默认选项跟随用户既有的 rollbackOnError 偏好：
+ * 勾过「失败不回滚」→ 默认保留（与他的心智一致）；否则默认回滚（安全侧）。
+ */
+export function cancelDialogModel(run, opts) {
+    const applied = run.item;
+    const total = run.itemTotal;
+    return {
+        runId: run.runId,
+        kindLabelKey: `runs.kind.${run.kind}`,
+        appliedCount: applied,
+        totalCount: total,
+        pendingCount: applied !== null && total !== null ? Math.max(0, total - applied) : null,
+        defaultDecision: opts.defaultRollbackOnError ? 'rollback' : 'keep',
+        options: [
+            { id: 'rollback', labelKey: 'runs.cancel.rollback', descKey: 'runs.cancel.rollbackDesc' },
+            { id: 'keep', labelKey: 'runs.cancel.keep', descKey: 'runs.cancel.keepDesc' },
+        ],
+    };
+}
+/** 「已应用/未执行」的用户可读摘要参数（null → 壳层显示「未知」而不是编个数字）。 */
+export function cancelCostParams(model) {
+    return {
+        applied: model.appliedCount === null ? '' : String(model.appliedCount),
+        pending: model.pendingCount === null ? '' : String(model.pendingCount),
+    };
+}
+//# sourceMappingURL=runs-view.js.map

package/lib/ui/select-model.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 自定义下拉（Select）的纯交互模型 —— src/client/common/Select.tsx 只做装配。
+ *
+ * 为什么需要它：原生 <select> 的外观由浏览器渲染（无法跟随 `--dsw-*` token，
+ * 深色主题下是白底系统控件、与工作台其余控件格格不入），故改为 div/button 自绘。
+ * 自绘换来的是**无障碍与键盘语义要自己扛**（ARIA combobox + listbox 模式），
+ * 所以可测的那部分（高亮项推导 / 上下移动 / 首尾跳转）全部落在这里，node 可测。
+ *
+ * 分层铁律：本文件零依赖（不 import react / 浏览器 API），client 与 node 单测都能用。
+ */
+/** 下拉选项（value 一律字符串：调用点的数字枚举在边界处 String/Number 转换）。 */
+export interface SelectOption {
+    /** 回传给 onChange 的值（唯一键） */
+    value: string;
+    /** 展示文本（已本地化；不在本层做 i18n） */
+    label: string;
+    /** 禁用项：键盘移动跳过、不可提交（灰显） */
+    disabled?: boolean;
+}
+/** 选中值对应的选项；值不在清单里（如远端快照已被清理）→ undefined。 */
+export declare function selectedOption(options: SelectOption[], value: string): SelectOption | undefined;
+/**
+ * 触发器上的显示文本。
+ *
+ * 值不在清单里时**不显示空**：先用 fallback（调用点给的占位文案），
+ * 仍为空则显示原值本身 —— 显示「一个不存在的 id」也比显示空白强
+ * （用户至少能看出当前选中的是什么；空白会被读成「没选中」）。
+ */
+export declare function selectDisplayLabel(options: SelectOption[], value: string, fallback?: string): string;
+/**
+ * 打开菜单时的初始高亮项：
+ * 选中项优先（它是用户下次最可能改动的锚点）；选中项不存在或已禁用 → 第一个可用项。
+ * 全部禁用 / 空清单 → -1（表示没有高亮项）。
+ */
+export declare function initialActiveIndex(options: SelectOption[], value: string): number;
+/** 第一个可用项下标；没有 → -1。 */
+export declare function firstEnabledIndex(options: SelectOption[]): number;
+/** 最后一个可用项下标；没有 → -1。 */
+export declare function lastEnabledIndex(options: SelectOption[]): number;
+/**
+ * 从 from 出发按 delta（±1）移动高亮项。
+ *
+ * 三条语义（与原生 <select> 的键盘行为对齐）：
+ *   ① 禁用项跳过，不停留；
+ *   ② 到达末尾**环绕**（原生 select 也环绕），环绕一整圈回到原位；
+ *   ③ 当前无高亮（from < 0）时：delta > 0 → 第一个可用项，delta < 0 → 最后一个可用项。
+ * 全部项禁用 / 空清单 → -1。
+ */
+export declare function stepActiveIndex(options: SelectOption[], from: number, delta: number): number;
+/** Home/End：跳到第一个/最后一个可用项。 */
+export declare function edgeActiveIndex(options: SelectOption[], edge: 'first' | 'last'): number;

package/lib/ui/select-model.js

@@ -0,0 +1,84 @@
+/**
+ * 自定义下拉（Select）的纯交互模型 —— src/client/common/Select.tsx 只做装配。
+ *
+ * 为什么需要它：原生 <select> 的外观由浏览器渲染（无法跟随 `--dsw-*` token，
+ * 深色主题下是白底系统控件、与工作台其余控件格格不入），故改为 div/button 自绘。
+ * 自绘换来的是**无障碍与键盘语义要自己扛**（ARIA combobox + listbox 模式），
+ * 所以可测的那部分（高亮项推导 / 上下移动 / 首尾跳转）全部落在这里，node 可测。
+ *
+ * 分层铁律：本文件零依赖（不 import react / 浏览器 API），client 与 node 单测都能用。
+ */
+/** 选中值对应的选项；值不在清单里（如远端快照已被清理）→ undefined。 */
+export function selectedOption(options, value) {
+    for (const option of options) {
+        if (option.value === value)
+            return option;
+    }
+    return undefined;
+}
+/**
+ * 触发器上的显示文本。
+ *
+ * 值不在清单里时**不显示空**：先用 fallback（调用点给的占位文案），
+ * 仍为空则显示原值本身 —— 显示「一个不存在的 id」也比显示空白强
+ * （用户至少能看出当前选中的是什么；空白会被读成「没选中」）。
+ */
+export function selectDisplayLabel(options, value, fallback = '') {
+    const hit = selectedOption(options, value);
+    if (hit !== undefined)
+        return hit.label;
+    return fallback !== '' ? fallback : value;
+}
+/**
+ * 打开菜单时的初始高亮项：
+ * 选中项优先（它是用户下次最可能改动的锚点）；选中项不存在或已禁用 → 第一个可用项。
+ * 全部禁用 / 空清单 → -1（表示没有高亮项）。
+ */
+export function initialActiveIndex(options, value) {
+    const selected = options.findIndex((option) => option.value === value);
+    if (selected >= 0 && options[selected]?.disabled !== true)
+        return selected;
+    return firstEnabledIndex(options);
+}
+/** 第一个可用项下标；没有 → -1。 */
+export function firstEnabledIndex(options) {
+    return options.findIndex((option) => option.disabled !== true);
+}
+/** 最后一个可用项下标；没有 → -1。 */
+export function lastEnabledIndex(options) {
+    for (let i = options.length - 1; i >= 0; i--) {
+        if (options[i]?.disabled !== true)
+            return i;
+    }
+    return -1;
+}
+/**
+ * 从 from 出发按 delta（±1）移动高亮项。
+ *
+ * 三条语义（与原生 <select> 的键盘行为对齐）：
+ *   ① 禁用项跳过，不停留；
+ *   ② 到达末尾**环绕**（原生 select 也环绕），环绕一整圈回到原位；
+ *   ③ 当前无高亮（from < 0）时：delta > 0 → 第一个可用项，delta < 0 → 最后一个可用项。
+ * 全部项禁用 / 空清单 → -1。
+ */
+export function stepActiveIndex(options, from, delta) {
+    const total = options.length;
+    if (total === 0)
+        return -1;
+    if (firstEnabledIndex(options) < 0)
+        return -1;
+    if (from < 0)
+        return delta >= 0 ? firstEnabledIndex(options) : lastEnabledIndex(options);
+    let index = from;
+    for (let hop = 0; hop < total; hop++) {
+        index = (index + delta + total) % total;
+        if (options[index]?.disabled !== true)
+            return index;
+    }
+    return from;
+}
+/** Home/End：跳到第一个/最后一个可用项。 */
+export function edgeActiveIndex(options, edge) {
+    return edge === 'first' ? firstEnabledIndex(options) : lastEnabledIndex(options);
+}
+//# sourceMappingURL=select-model.js.map

package/lib/ui/selection-model.d.ts

@@ -32,6 +32,30 @@ export interface SelectionUnit {
      * 与既有分区（skills / pluginFiles / …）的表现完全一致。纯展示层，不参与勾选契约。
      */
     group?: string;
+    /**
+     * 本单元拥有的会话 id（工作区单元专用；issue #45）。
+     *
+     * 用途：勾选联动 —— 勾了会话就自动勾上它所属的工作区，取消工作区就取消它的会话。
+     * 取值 = 工作区记录 sessionIds **原样**（DSH 一律写 `session-<uuid>`）；与会话单元 id 的末段（目录名，
+     * 可能是 `session-<uuid>` 也可能是裸 `<uuid>`）用 `sessionIdKey()` 归一化后配对 —— 两种形态直接做
+     * 字符串比较会失配（真机实测 546/570 会话因此联不上工作区）。
+     */
+    sessionIds?: string[];
+    /**
+     * 本单元 **path 的 cwd 目录键**（工作区单元专用；issue #45 勾选联动的第二判据）。
+     *
+     * 为什么需要它：DSH 注册表 `sessionIds` 覆盖率很低（真机实测一次可选择的 570 条会话里只有 23 条在
+     * 里面），而 DSH 自己按「会话 cwd 的目录键 == 工作区 path 的目录键」会话显示在工作区下。勾选联动若
+     * 只认 sessionIds，就会出现「界面明明把对话挂在某工作区下、勾它却不联动」。
+     */
+    projectKey?: string;
+    /**
+     * 父对话的会话裸键（**只有子代理会话才有值**；宿主在 /export-preview 里按 DSH 的会话存储关系下发）。
+     *
+     * 用途：「父 ↔ 子代理会话」勾选联动（勾父自动勾上它的子代理会话、勾子自动带上父）。没有这个字段
+     * 时联动整段失效 —— 界面勾了什么与包里装了什么就会不一致（真机事故：勾 2 条、包里 41 条）。
+     */
+    parentSessionId?: string;
 }
 /** 一个分区及其可勾选单元；units 为空 = 本分区不可细分（UI 只给整体开关）。 */
 export interface SelectionSection {
@@ -85,7 +109,7 @@ export declare function visibleUnits(units: readonly SelectionUnit[], showAll: b
  * 纯函数（node 可测）：只改显示文本，不改数据；完整值由调用方放进 `title`。
  * 与 CSS `text-overflow: ellipsis` 叠加使用（CSS 兜底实际容器宽度）。
  */
-export declare function middleEllipsis(text: string, max?: number): string;
+export declare function tailWeightedEllipsis(text: string, max?: number): string;
 /** 缺省：全选（excluded 为空 = 没有任何例外）。 */
 export declare function defaultSelection(sections: SectionId[]): Selection;
 /** 把 /export-preview 的分区响应映射为选择模型的分区（宿主类型 → UI 模型，显式转换一次）。 */
@@ -110,11 +134,27 @@ export interface UnitGroup {
  *  - 无分组的单元单独成一组，排在**最前**（它们通常是该分区的公共条目）。
  */
 export declare function groupUnits(units: readonly SelectionUnit[]): UnitGroup[];
+/**
+ * 分组内已勾选单元数。
+ *
+ * **必须先看所属分区**（与 sectionPickState / selectedUnitCount 同一口径）：稀疏表示下
+ * 「不在 excluded 里」只说明「没有显式排除」，分区整体没勾时同样成立 —— 只看 excluded 会渲染出
+ * 「分区 已选 0/13、13 个子项却全部打勾」的自相矛盾（用户实测：点「全不选」后子项仍然勾着）。
+ */
+export declare function groupSelectedCount(sel: Selection, group: UnitGroup, section: SectionId): number;
 /** 二级分组三态（与分区三态同一套口径；分组只是分区内的视图）。 */
-export declare function groupPickState(sel: Selection, group: UnitGroup): SectionPickState;
+export declare function groupPickState(sel: Selection, group: UnitGroup, section: SectionId): SectionPickState;
 /** 分组级勾选：整组一起选/取消（并保证其所属分区处于勾选状态）。 */
 export declare function toggleUnitGroup(sel: Selection, node: SelectionSection, group: UnitGroup, checked: boolean): Selection;
 export declare function isUnitSelected(sel: Selection, unitId: string): boolean;
+/**
+ * 单元勾选态（**渲染层唯一口径**）。
+ *
+ * 与 `isUnitSelected` 的差别：后者是稀疏表示下的「未显式排除」，分区整体没勾时它依然为 true，
+ * 直接拿它渲染勾选框会出现「分区计数 0/13 + 13 个子项全打勾」的自相矛盾（用户实测：
+ * 点「全不选」后分区标题变成未勾选，子项却还是勾的）。渲染必须先看分区，再看排除集。
+ */
+export declare function unitChecked(sel: Selection, section: SectionId, unitId: string): boolean;
 /** 分区三态：不可细分分区退回整体开关。 */
 export declare function sectionPickState(sel: Selection, node: SelectionSection): SectionPickState;
 /** 已勾选条目数（不可细分分区用宿主的 count 兜底）。 */
@@ -155,6 +195,71 @@ export interface ExportRequestPlan {
  */
 export declare function buildExportRequest(sel: Selection, nodes: SelectionSection[]): ExportRequestPlan;
 /** 搜索过滤：按分区名/单元名/副标题匹配；命中的分区保留其全部单元（便于继续勾选同分区其它项）。 */
+/** 会话单元 id（sessions:<projectKey>/<sessionId>）→ sessionId；非会话单元 → undefined。 */
+/**
+ * 会话单元 id（`sessions:<项目键>/<目录名>`）→ **cwd 目录键**（项目键）；非会话单元 / 形状不符 → undefined。
+ *
+ * 用途：勾选联动的第二判据 —— 与工作区单元的 `projectKey` 比较，口径与 DSH「把会话显示在工作区下」一致。
+ */
+/**
+ * 工作区单元的 cwd 目录键：宿主直出的 `projectKey` 优先，缺省时用 `detail`（= 工作区绝对路径）现算。
+ *
+ * 为什么要有兜底：`projectKey` 是后加的宿主字段，**旧宿主**（未重启的 DSH 进程）不会回传它，而工作区单元的
+ * `detail` 一直就是绝对路径。只在 detail 形如绝对路径时才现算 —— 计划项的 detail 是描述文案
+ * （如 `current={...} imported={...}`），绝不会被误当成路径。
+ */
+export declare function workspaceProjectKeyOf(unit: {
+    projectKey?: string;
+    detail?: string;
+}): string | undefined;
+export declare function sessionProjectKeyOfUnit(unitId: string): string | undefined;
+export declare function sessionIdOfUnit(unitId: string): string | undefined;
+/** 本次勾选动作（哪个单元、点完后是勾还是取消）—— 父/子两条规则必须按动作方向定夺。 */
+export interface SessionParentChange {
+    unitId: string;
+    checked: boolean;
+}
+/**
+ * 父对话 ↔ 子代理会话联动。三件事，全部由**用户勾选的父对话**这一侧驱动：
+ *  - **勾父** → 连带勾上它的子代理会话（传递：子会话自己还有子会话也一起带）；
+ *  - **勾子** → 连带勾上它的父对话（父链向上传递）—— 与导出的「向上补父对话」同口径，
+ *    否则界面勾了子、包里却多出父，勾选与包内容不一致；
+ *  - **取消父** → 连带取消它的子代理会话；**取消子** → 只取消这一条（父对话留着）。
+ *
+ * 为什么必须按动作方向（而不是无脑闭包）：两条规则会互相抵消 —— 取消父之后若还跑
+ * 「已勾选的子 ⇒ 勾上父」，父立刻被勾回来（与工作区联动完全同一个坑，见 focus 的注释）。
+ *
+ * @param change 本次点击的单元与状态；缺省（分区/分组/全选等批量动作、清单到货后补跑）
+ *   只做**正向闭包**：已勾选的父把子补齐、已勾选的子把父补齐，绝不取消任何东西。
+ */
+export declare function applySessionParentCoupling(sel: Selection, nodes: SelectionSection[], change?: SessionParentChange): Selection;
+/**
+ * 会话 ↔ 工作区联动（issue #45）：① 勾了会话 → 自动勾上「拥有它的工作区」；② 取消工作区 → 它的会话也取消。
+ *
+ * 为什么写在选择模型层：导出页与导入向导共用同一个 ContentPicker，规则写一次两端行为一致
+ * （「同样的勾选框不一样的行为」是本仓库明确要消灭的状态）。只按 sessionIds 匹配、不翻译路径：
+ * 跨机时工作区路径与会话 cwd 都是源机形态，按路径匹配不可靠。无 sessionIds 的单元一律不参与联动（不猜）。
+ */
+/**
+ * 本次勾选动作的方向：① 只勾会话 → 带上其工作区；② 只动工作区 → 撤销未勾工作区的会话；both = 两条都跑。
+ *
+ * 为什么必须有方向：两条规则在「会话勾着、它的工作区却被取消」这种状态下会互相抵消（谁后跑谁翻盘）。
+ * 用动作方向定夺，行为才是确定的：取消工作区一定连带取消它的会话，勾上会话一定带上它的工作区。
+ */
+export type SessionWorkspaceCouplingFocus = 'sessions' | 'workspaces' | 'both';
+/**
+ * 会话↔工作区联动需要的**伙伴分区**（导出页的清单是逐分区惰性拉的）。
+ *
+ * 联动的唯一数据源是**工作区单元上的 `sessionIds`**：勾了会话但工作区清单还没读出来 → 没有 sessionIds 可读 →
+ * 联动**静默失效**（用户真机复验：取消工作区后再勾一个对话，对应工作区不会回来）。所以只要勾了会话，就
+ * 必须把工作区清单一起读出来；工作区记录是纯元数据（每条几十字节），这点代价可以忽略。
+ *
+ * 反向刻意不加（勾着工作区、会话清单没读）：那种状态下会话单元根本不在选择器里，没有需要联动的会话。
+ */
+export declare function couplingInventorySections(sections: readonly SectionId[]): SectionId[];
+/** 两份选择是否等价（按集合；用于「清单到货后补一次联动」避免无谓写库 / 自激渲染）。 */
+export declare function sameSelection(a: Selection, b: Selection): boolean;
+export declare function applySessionWorkspaceCoupling(sel: Selection, nodes: SelectionSection[], focus?: SessionWorkspaceCouplingFocus): Selection;
 export declare function filterSections(nodes: SelectionSection[], query: string): SelectionSection[];
 /**
  * 高风险分区（严格分层信任的默认：须用户显式勾选）。
@@ -190,6 +295,17 @@ export declare function defaultSelectionFromPlan(plan: ImportPlan, opts?: {
 export declare function isPlanItemExcluded(item: PlanItem, selection: Selection): boolean;
 /** 被用户排除的计划项（供报告如实展示「N 项未导入」）。 */
 export declare function excludedPlanItems(plan: ImportPlan, selection: Selection): PlanItem[];
+/**
+ * 本次导入**确实会写盘**的分区集合。
+ *
+ * 用途：路径映射阶段的过滤依据 —— PathIssue 只说明「这条路径来自哪个分区」，
+ * 还需要「这个分区这次会不会写」才能判断该不该问用户（工作区全为 Skip 或整个分区被取消时，
+ * 为它填映射是纯粹的无效劳动）。
+ *
+ * 入参必须是**已裁剪**的子计划（buildSelectedPlan 的产物）：本函数只按 kind 判定，
+ * 不再重复做选择语义，避免出现第二套「哪些项会被导入」的判定。
+ */
+export declare function planWriteSections(plan: ImportPlan): Set<SectionId>;
 /**
  * 选择是否**留下了**计划中的任何一项（UI-05「全不选」守卫）。
  *