dsh-config-manager 0.1.0

package/src/security/zip-security.ts

@@ -0,0 +1,180 @@
+/**
+ * ZIP 解压安全（规范 §19 / 设计 §9 / core utils/zip.ts 的强化层）。
+ *
+ * 分工（避免与 core 重复）：
+ * - core `utils/zip.ts` 已实现：条目名 isPathSafe、条目数/压缩体积/解压体积/单条/压缩比限额、
+ *   CRC32 与尺寸校验、ZipArchive.readEntry 预算、safeExtract 基础解压。
+ * - 本模块在其上强化 core 未覆盖的攻击面：
+ *   1. **symlink 条目拒绝**：解析中央目录 external attrs 的 Unix mode（S_IFLNK 0xA000）→ 拒绝；
+ *   2. **重复条目名拒绝**：同名条目（含目录/文件互撞）→ 拒绝（防读取歧义攻击）；
+ *   3. **安全解压强化**：解压后逐条 lstat 复查「必须是普通文件」，任何异常 → 中止并**完整清理**目标目录；
+ *   4. **可执行文件告警**：扩展名黑名单 → warnings（本插件从不执行 ZIP 内文件）。
+ *
+ * 与 core 注入点对齐：`parseZipHardened` / `createHardenedZipParser` 满足
+ * `ImporterOptions.parseZipOverride` 签名 `(buf, limits?) => ZipArchive`。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isPathSafe, isSameOrChild } from '../utils/paths.ts';
+import {
+  DEFAULT_ZIP_SAFETY_LIMITS,
+  ZipArchive,
+  ZipSafetyError,
+  type ZipEntryMeta,
+  type ZipSafetyLimits,
+} from '../utils/zip.ts';
+
+export { isPathSafe } from '../utils/paths.ts';
+
+/* ---------------- 常量 ---------------- */
+
+const EOCD_SIG = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+const CENTRAL_SIG = 0x02014b50;
+/** Unix 文件类型掩码（external attrs 高 16 位） */
+const S_IFMT = 0xf000;
+/** 符号链接 */
+const S_IFLNK = 0xa000;
+
+/** 可执行文件扩展名黑名单（§19.6：只警告，本插件不执行任何脚本） */
+export const EXECUTABLE_EXTENSIONS = new Set([
+  '.exe', '.bat', '.cmd', '.sh', '.ps1', '.dll', '.so', '.dylib', '.bin', '.jar',
+]);
+
+/** 条目名是否疑似可执行文件（按扩展名） */
+export function isExecutableName(name: string): boolean {
+  const ext = name.slice(name.lastIndexOf('.')).toLowerCase();
+  return EXECUTABLE_EXTENSIONS.has(ext);
+}
+
+/* ---------------- 强化解析（parseZipOverride 注入点） ---------------- */
+
+/**
+ * 强化版 ZIP 解析：在 core 全部安全校验（条目名/条目数/压缩体积）之上，
+ * 增加 symlink 拒绝与重复条目名拒绝。返回 core `ZipArchive`（解压校验完全复用）。
+ */
+export function parseZipHardened(buf: Uint8Array, limits: ZipSafetyLimits = {}): ZipArchive {
+  const merged: Required<ZipSafetyLimits> = { ...DEFAULT_ZIP_SAFETY_LIMITS, ...limits };
+  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+  if (b.length < 22) throw new ZipSafetyError('不是合法的 ZIP 文件（体积过小）');
+
+  const eocdIdx = b.lastIndexOf(EOCD_SIG);
+  if (eocdIdx < 0 || eocdIdx + 22 > b.length) {
+    throw new ZipSafetyError('不是合法的 ZIP 文件（缺少中央目录结束记录）');
+  }
+  const totalEntries = b.readUInt16LE(eocdIdx + 10);
+  const cdSize = b.readUInt32LE(eocdIdx + 12);
+  const cdOffset = b.readUInt32LE(eocdIdx + 16);
+  if (cdOffset + cdSize > b.length) throw new ZipSafetyError('中央目录越界（ZIP 损坏）');
+  if (totalEntries > merged.maxEntries) {
+    throw new ZipSafetyError(`ZIP 条目数 ${totalEntries} 超过上限 ${merged.maxEntries}`);
+  }
+
+  const metas: ZipEntryMeta[] = [];
+  const seenNames = new Set<string>();
+  let pos = cdOffset;
+  let compressedTotal = 0;
+  for (let i = 0; i < totalEntries; i++) {
+    if (pos + 46 > cdOffset + cdSize) throw new ZipSafetyError('中央目录条目越界（ZIP 损坏）');
+    if (b.readUInt32LE(pos) !== CENTRAL_SIG) throw new ZipSafetyError('中央目录签名损坏');
+
+    const method = b.readUInt16LE(pos + 10);
+    const crc = b.readUInt32LE(pos + 16);
+    const compSize = b.readUInt32LE(pos + 20);
+    const uncompSize = b.readUInt32LE(pos + 24);
+    const nameLen = b.readUInt16LE(pos + 28);
+    const extraLen = b.readUInt16LE(pos + 30);
+    const commentLen = b.readUInt16LE(pos + 32);
+    const externalAttrs = b.readUInt32LE(pos + 38);
+    const localOffset = b.readUInt32LE(pos + 42);
+    const name = b.subarray(pos + 46, pos + 46 + nameLen).toString('utf8');
+
+    // —— 强化检查 ——
+    if (!isPathSafe(name)) throw new ZipSafetyError(`ZIP 条目名不安全: ${name}`);
+    if (seenNames.has(name)) throw new ZipSafetyError(`ZIP 条目名重复: ${name}`);
+    seenNames.add(name);
+    const mode = (externalAttrs >>> 16) & S_IFMT;
+    if (mode === S_IFLNK) {
+      throw new ZipSafetyError(`ZIP 含符号链接条目，已拒绝: ${name}`);
+    }
+    if (localOffset + 30 > b.length) {
+      throw new ZipSafetyError(`条目 "${name}" 本地文件头越界`);
+    }
+
+    compressedTotal += compSize;
+    if (compressedTotal > merged.maxCompressedBytes) {
+      throw new ZipSafetyError('ZIP 压缩数据总量超过上限');
+    }
+    metas.push({
+      name,
+      method,
+      compressedSize: compSize,
+      uncompressedSize: uncompSize,
+      crc32: crc,
+      isDirectory: name.endsWith('/'),
+      localOffset,
+    });
+    pos += 46 + nameLen + extraLen + commentLen;
+  }
+  return new ZipArchive(b, metas, merged);
+}
+
+/** 工厂：带默认限额的强化解析器（对齐 ImporterOptions.parseZipOverride 签名） */
+export function createHardenedZipParser(defaultLimits?: ZipSafetyLimits) {
+  return (buf: Uint8Array, limits?: ZipSafetyLimits): ZipArchive =>
+    parseZipHardened(buf, { ...defaultLimits, ...limits });
+}
+
+/* ---------------- 强化安全解压（m5 导入文件类分区用） ---------------- */
+
+export interface SafeExtractResult {
+  /** 已解压条目的 ZIP 相对路径（正斜杠） */
+  files: string[];
+  /** 非阻塞告警（可执行文件条目等） */
+  warnings: string[];
+}
+
+/**
+ * 安全解压到受控目录（对齐 core safeExtract 语义 + 强化）：
+ *  - 条目名/限额/symlink/重复名检查（parseZipHardened）；
+ *  - 逐条 CRC32/尺寸/预算校验（ZipArchive.readEntry）；
+ *  - 解压后 lstat 复查「全部产物必须是普通文件」（防符号链接/非常规写入）；
+ *  - 任何异常 → 中止并**完整清理** destDir 后抛出（不残留部分落盘）。
+ */
+export async function safeExtractHardened(
+  zipPath: string,
+  destDir: string,
+  limits: ZipSafetyLimits = {},
+): Promise<SafeExtractResult> {
+  const data = await fs.readFile(zipPath);
+  const archive = parseZipHardened(data, limits);
+  const extracted: string[] = [];
+  const warnings: string[] = [];
+
+  try {
+    for (const meta of archive.entries()) {
+      if (meta.isDirectory) continue;
+      const target = path.join(destDir, ...meta.name.split('/'));
+      if (!isSameOrChild(target, destDir)) {
+        throw new ZipSafetyError(`解压目标越界: ${meta.name}`);
+      }
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, archive.readEntry(meta.name));
+      extracted.push(meta.name);
+      if (isExecutableName(meta.name)) {
+        warnings.push(`条目 "${meta.name}" 是潜在可执行文件，本插件不会执行它`);
+      }
+    }
+    // 解压后复查：全部产物必须是普通文件（防 symlink 逃逸 / 非常规写入）
+    for (const rel of extracted) {
+      const p = path.join(destDir, ...rel.split('/'));
+      const st = await fs.lstat(p);
+      if (!st.isFile()) {
+        throw new ZipSafetyError(`解压产物不是普通文件: ${rel}`);
+      }
+    }
+    return { files: extracted, warnings };
+  } catch (err) {
+    await fs.rm(destDir, { recursive: true, force: true });
+    throw err;
+  }
+}

package/src/ui/conflict-view.test.ts

@@ -0,0 +1,62 @@
+/**
+ * conflict-view 测试（m6-ui，规范 §11）：
+ * Keep Current / Use Imported / Review 决策收集与 core 决策表转换。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ConflictCollector } from './conflict-view.ts';
+import { makePlan, makePlanItem } from './test-helpers.ts';
+
+function conflictPlan() {
+  return makePlan({
+    items: [
+      makePlanItem({ id: 'settings:a', kind: 'Conflict', description: '设置 a 与目标不同', detail: 'current={x:1} imported={x:2}' }),
+      makePlanItem({ id: 'settings:b', kind: 'Conflict', description: '设置 b 与目标不同' }),
+      makePlanItem({ id: 'plugin:c', kind: 'Conflict', adapter: 'plugins', description: '插件 c 版本不同' }),
+      makePlanItem({ id: 'prompt:d', kind: 'Create', adapter: 'prompts', description: '创建提示 d' }),
+    ],
+  });
+}
+
+test('conflict-view: 只收集 Conflict 项', () => {
+  const c = new ConflictCollector(conflictPlan());
+  assert.equal(c.conflicts.length, 3);
+  assert.equal(c.hasUnresolved, true);
+});
+
+test('conflict-view: resolve 设置决策；未知 id 忽略', () => {
+  const c = new ConflictCollector(conflictPlan());
+  assert.equal(c.resolve('settings:a', 'useImported'), true);
+  assert.equal(c.resolve('nope', 'review'), false);
+  assert.equal(c.decisionOf('settings:a'), 'useImported');
+});
+
+test('conflict-view: unresolved 只含未决/ review 项', () => {
+  const c = new ConflictCollector(conflictPlan());
+  c.resolve('settings:a', 'keepCurrent');
+  c.resolve('plugin:c', 'review');
+  const unresolved = c.unresolved();
+  assert.deepEqual(unresolved.map((i) => i.id), ['settings:b', 'plugin:c']);
+  assert.equal(c.hasUnresolved, true);
+  c.resolve('settings:b', 'useImported');
+  c.resolve('plugin:c', 'useImported');
+  assert.equal(c.hasUnresolved, false);
+});
+
+test('conflict-view: toResolutions 输出 core 决策表', () => {
+  const c = new ConflictCollector(conflictPlan());
+  c.resolve('settings:a', 'keepCurrent');
+  c.resolve('settings:b', 'useImported');
+  const resolutions = c.toResolutions();
+  assert.deepEqual(resolutions, { 'settings:a': 'keepCurrent', 'settings:b': 'useImported' });
+});
+
+test('conflict-view: viewItems 提供视图数据（React 绑定）', () => {
+  const c = new ConflictCollector(conflictPlan());
+  c.resolve('settings:a', 'useImported');
+  const views = c.viewItems();
+  assert.equal(views.length, 3);
+  const first = views.find((v) => v.item.id === 'settings:a')!;
+  assert.equal(first.resolution, 'useImported');
+  assert.ok(first.currentSummary !== undefined);
+});

package/src/ui/conflict-view.ts

@@ -0,0 +1,65 @@
+/**
+ * 冲突决策收集（规范 §11，m6-ui）。
+ *
+ * 输入：ImportPlan.items 中的 Conflict 项（目标存在且不同）。
+ * 输出：逐项决策 Keep Current / Use Imported / Review，转为 core ImportDecisions.resolutions。
+ *
+ * 纯逻辑：只收集用户选择，不触碰 core；未决（review/未选）项在预览时如实展示。
+ */
+import type { ImportPlan, ItemResolution, PlanItem } from '../core/types.ts';
+import type { ConflictViewItem } from './types.ts';
+
+export class ConflictCollector {
+  private readonly plan: ImportPlan;
+  private readonly decisions = new Map<string, ItemResolution>();
+
+  constructor(plan: ImportPlan) {
+    this.plan = plan;
+  }
+
+  /** 需要用户决策的冲突项（kind === 'Conflict'） */
+  get conflicts(): PlanItem[] {
+    return this.plan.items.filter((i) => i.kind === 'Conflict');
+  }
+
+  /** 设置某项决策；未出现在冲突列表中的 id 忽略并返回 false */
+  resolve(itemId: string, resolution: ItemResolution): boolean {
+    if (!this.conflicts.some((i) => i.id === itemId)) return false;
+    this.decisions.set(itemId, resolution);
+    return true;
+  }
+
+  /** 单项当前决策（未决策返回 null） */
+  decisionOf(itemId: string): ItemResolution | null {
+    return this.decisions.get(itemId) ?? null;
+  }
+
+  /** 仍未解决（review 或未决策）的冲突项 */
+  unresolved(): PlanItem[] {
+    return this.conflicts.filter((i) => {
+      const d = this.decisions.get(i.id);
+      return d === undefined || d === 'review';
+    });
+  }
+
+  get hasUnresolved(): boolean {
+    return this.unresolved().length > 0;
+  }
+
+  /** 转 core 决策表（供 createImportPlan / executeImportPlan 使用） */
+  toResolutions(): Record<string, ItemResolution> {
+    const out: Record<string, ItemResolution> = {};
+    for (const [id, res] of this.decisions) out[id] = res;
+    return out;
+  }
+
+  /** 构造视图项列表（React 绑定用）：含当前/导入摘要占位 */
+  viewItems(): ConflictViewItem[] {
+    return this.conflicts.map((item) => ({
+      item,
+      currentSummary: item.detail?.split('\n')[0],
+      importedSummary: undefined,
+      resolution: this.decisionOf(item.id),
+    }));
+  }
+}

package/src/ui/errors.test.ts

@@ -0,0 +1,44 @@
+/**
+ * errors 测试（m6-ui，规范 §23）：可操作错误 Reason/Suggested action，Secret 脱敏。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { formatActionableError, toActionableError } from './errors.ts';
+
+test('errors: SETTINGS_CONFLICT 映射为可操作建议', () => {
+  const e = toActionableError(new Error('SETTINGS_CONFLICT: llm-deepseek revision 12 != 14'));
+  assert.equal(e.title, '配置已被并发修改');
+  assert.ok(e.suggestedAction !== undefined);
+  assert.equal(e.retryable, true);
+});
+
+test('errors: 完整性失败不可重试', () => {
+  const e = toActionableError(new Error('备份完整性校验失败: "config/settings.json"'));
+  assert.equal(e.title, '备份完整性校验失败');
+  assert.equal(e.retryable, false);
+});
+
+test('errors: 未知错误回退通用文案（仍给 Reason）', () => {
+  const e = toActionableError(new Error('boom'));
+  assert.equal(e.title, '操作失败');
+  assert.equal(e.reason, 'boom');
+});
+
+test('errors: Secret 值绝不进入输出（脱敏）', () => {
+  const e = toActionableError(new Error('写入失败: apiKey=sk-abcdef1234567890'));
+  assert.ok(!e.reason.includes('sk-abcdef1234567890'));
+  assert.ok(e.reason.includes('REDACTED'));
+});
+
+test('errors: 带 item 的错误也脱敏', () => {
+  const e = toActionableError(new Error('fail'), { item: 'apiKey=sk-zzz999' });
+  assert.ok(!e.item!.includes('sk-zzz999'));
+});
+
+test('errors: formatActionableError 输出 Reason + Suggested action', () => {
+  const e = toActionableError(new Error('ENOENT: no such file'), { item: 'x.zip' });
+  const text = formatActionableError(e);
+  assert.ok(text.includes('Reason:'));
+  assert.ok(text.includes('Suggested action:'));
+  assert.ok(text.includes('Item:'));
+});

package/src/ui/errors.ts

@@ -0,0 +1,95 @@
+/**
+ * 可操作错误模型（规范 §23，m6-ui）。
+ *
+ * 绝不只有 "Something went wrong."：
+ *  - 解析错误 → Reason + Suggested action（可操作）；
+ *  - 输出前强制脱敏（redact），Secret 永不进入 UI/日志。
+ */
+import { redact } from '../security/redaction.ts';
+
+/** 可操作错误（UI 渲染为 Reason / Suggested action 两段） */
+export interface ActionableError {
+  title: string;
+  reason: string;
+  suggestedAction?: string;
+  /** 相关项（如 MCP 服务器名 / 插件包名）；可空 */
+  item?: string;
+  /** 是否可重试（true 显示重试按钮） */
+  retryable: boolean;
+}
+
+/** 常见错误 → 建议动作 的规则表（按错误消息子串匹配） */
+interface ErrorRule {
+  match: (msg: string) => boolean;
+  title: string;
+  suggestedAction: string;
+  retryable: boolean;
+}
+
+const ERROR_RULES: readonly ErrorRule[] = [
+  {
+    match: (m) => /SETTINGS_CONFLICT|revision.*conflict/i.test(m),
+    title: '配置已被并发修改',
+    suggestedAction: '目标 DSH 的该配置在导入期间被其他进程修改，为避免覆盖请重新导出或手动核对后再试。',
+    retryable: true,
+  },
+  {
+    match: (m) => /ImportNotConfirmed|未确认/i.test(m),
+    title: '导入未确认',
+    suggestedAction: '请在预览页确认导入内容后重试。',
+    retryable: true,
+  },
+  {
+    match: (m) => /backup integrity|完整性校验失败|checksum/i.test(m),
+    title: '备份完整性校验失败',
+    suggestedAction: '备份文件可能已损坏或被篡改，请重新导出备份后再试。',
+    retryable: false,
+  },
+  {
+    match: (m) => /schema.*(不支持|超出)|无法导入|Unsupported/i.test(m),
+    title: '备份格式版本不受支持',
+    suggestedAction: '请升级 DSH Config Manager 或使用相同版本的备份文件。',
+    retryable: false,
+  },
+  {
+    match: (m) => /ENOENT|not found|无法读取|不存在/i.test(m),
+    title: '文件或路径不存在',
+    suggestedAction: '请检查文件路径是否正确、文件是否已被移动或删除。',
+    retryable: true,
+  },
+  {
+    match: (m) => /EACCES|permission|权限/i.test(m),
+    title: '权限不足',
+    suggestedAction: '请检查目标目录的读写权限后重试。',
+    retryable: true,
+  },
+  {
+    match: (m) => /install.*(plugin|插件)|needsRestart|重启/i.test(m),
+    title: '插件安装需要重启生效',
+    suggestedAction: '导入已完成，插件将在重启 DSH 后生效；请在 DSH Desktop 中重启服务。',
+    retryable: false,
+  },
+];
+
+/** 将任意错误转换为可操作错误（消息已脱敏，不泄漏 Secret） */
+export function toActionableError(err: unknown, opts?: { item?: string; fallbackTitle?: string }): ActionableError {
+  const raw = err instanceof Error ? err.message : String(err ?? '未知错误');
+  const message = redact(raw);
+  const rule = ERROR_RULES.find((r) => r.match(message));
+  return {
+    title: rule?.title ?? opts?.fallbackTitle ?? '操作失败',
+    reason: message,
+    suggestedAction: rule?.suggestedAction,
+    item: opts?.item !== undefined ? redact(opts.item) : undefined,
+    retryable: rule?.retryable ?? true,
+  };
+}
+
+/** 格式化为用户可读的多行文本（Reason / Suggested action） */
+export function formatActionableError(e: ActionableError): string {
+  const lines = [e.title];
+  lines.push(`Reason: ${e.reason}`);
+  if (e.suggestedAction) lines.push(`Suggested action: ${e.suggestedAction}`);
+  if (e.item) lines.push(`Item: ${e.item}`);
+  return lines.join('\n');
+}

package/src/ui/export-flow.test.ts

@@ -0,0 +1,75 @@
+/**
+ * export-flow 测试（m6-ui）：Quick 推荐项 / Custom 分组目录 / 校验 / 执行进度与端口调用。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ExportFlow } from './export-flow.ts';
+import { MockExportPort, makeExportReport } from './test-helpers.ts';
+
+test('export-flow: Quick 推荐项 = defaultIncluded 且非 deviceSpecific', () => {
+  const flow = new ExportFlow({ port: new MockExportPort() });
+  const sel = flow.quickSelection();
+  assert.ok(sel.includes('settings'));
+  assert.ok(sel.includes('plugins'));
+  assert.ok(sel.includes('mcp'));
+  assert.ok(sel.includes('providers'));
+  assert.ok(!sel.includes('sessions'), 'sessions 默认关闭');
+  assert.ok(!sel.includes('pluginFiles'), 'pluginFiles 默认关闭');
+  assert.ok(!sel.includes('credentialsStatus'), 'deviceSpecific 不进 Quick');
+});
+
+test('export-flow: Custom 分组目录按 §1 分组且 automation 有说明', () => {
+  const flow = new ExportFlow({ port: new MockExportPort() });
+  const groups = flow.groupedCatalog();
+  const ids = groups.map((g) => g.group);
+  assert.ok(ids.includes('general'));
+  assert.ok(ids.includes('ai'));
+  assert.ok(ids.includes('extensions'));
+  assert.ok(ids.includes('optional'));
+  const automation = groups.find((g) => g.group === 'automation');
+  assert.ok(automation, 'automation 组存在（说明 DSH 无对应配置）');
+  assert.ok(automation!.note !== undefined);
+  const optional = groups.find((g) => g.group === 'optional')!;
+  assert.ok(optional.categories.some((c) => c.id === 'sessions'), '可选分区在 optional 组');
+});
+
+test('export-flow: validateSelection 对 deviceSpecific 分区给出警告', () => {
+  const flow = new ExportFlow({ port: new MockExportPort() });
+  const { valid, warnings } = flow.validateSelection(['settings', 'sessions']);
+  assert.equal(valid, true);
+  assert.ok(warnings.some((w) => w.includes('Sessions')));
+  const bad = flow.validateSelection(['nope'] as never);
+  assert.ok(bad.warnings.some((w) => w.includes('未知分区')));
+});
+
+test('export-flow: run 调 port 并携带 only 选择与进度事件', async () => {
+  const port = new MockExportPort();
+  const events: string[] = [];
+  const flow = new ExportFlow({ port, onProgress: (e) => events.push(e.stage) });
+  const out = await flow.run('custom', ['settings', 'plugins']);
+
+  assert.equal(port.calls.length, 1);
+  assert.deepEqual(port.calls[0]!.only, ['settings', 'plugins']);
+  assert.equal(port.calls[0]!.includeSecrets, false);
+  assert.equal(out.text.includes('Backup Created'), true);
+  assert.equal(out.text.includes('✓ settings'), true);
+  assert.equal(out.text.includes('8 plugins'), true);
+  assert.equal(events[events.length - 1], 'done');
+  // 进度覆盖导出阶段序列
+  assert.ok(events.includes('analyzing'));
+  assert.ok(events.includes('creating-archive'));
+});
+
+test('export-flow: Quick 模式 only 使用推荐项', async () => {
+  const port = new MockExportPort();
+  const flow = new ExportFlow({ port });
+  await flow.run('quick', []);
+  assert.deepEqual(port.calls[0]!.only, flow.quickSelection());
+});
+
+test('export-flow: 报告包含 Excluded 与 Security 信息', async () => {
+  const report = makeExportReport({ excluded: ['sessions'] });
+  const out = await new ExportFlow({ port: new MockExportPort(report) }).run('quick', []);
+  assert.equal(out.report.excluded.includes('sessions'), true);
+  assert.equal(out.report.security.secretsExcluded, true);
+});

package/src/ui/export-flow.ts

@@ -0,0 +1,128 @@
+/**
+ * Export 控制器（规范 §1 / §21，m6-ui）。
+ *
+ * 职责：
+ *  - Quick Export：推荐项 = defaultIncluded 且非 deviceSpecific 的分区（设计 §11.1）；
+ *  - Custom Export：按 §1 分组目录逐项勾选（含默认关闭的可选分区 pluginFiles/sessions）；
+ *  - 进度事件：调用 core 前后按 §29 阶段文案发出（UI 不冻结）；
+ *  - 结果：返回 ExportReport 并渲染 §21 文本报告。
+ *
+ * 依赖注入：ExportPort 由宿主在挂载时接入真实 Exporter（core/exporter.ts），
+ * 测试注入内存 mock —— 本层零依赖 core 实现。
+ */
+import type { Manifest, SectionId } from '../schema/types.ts';
+import type { ExportOptions, ExportReport } from '../core/types.ts';
+import {
+  EXPORT_GROUPS, type ExportCategory, type ExportGroup,
+  type ProgressListener, isQuickRecommended,
+} from './types.ts';
+import { EXPORT_STAGES, ProgressTracker } from './progress.ts';
+import { renderExportReport } from './report.ts';
+
+/** UI → core 的导出端口（宿主注入 Exporter.export；测试注入 mock） */
+export interface ExportPort {
+  export(options: ExportOptions): Promise<{ zipPath: string; manifest: Manifest; report: ExportReport }>;
+}
+
+export interface ExportFlowOptions {
+  port: ExportPort;
+  /** 分类目录（缺省用内置目录，与 adapters 的 displayName/defaultIncluded/portability 对齐） */
+  categories?: ExportCategory[];
+  onProgress?: ProgressListener;
+}
+
+export interface ExportRunResult {
+  zipPath: string;
+  manifest: Manifest;
+  report: ExportReport;
+  /** §21 渲染文本（report.ts） */
+  text: string;
+}
+
+/** 内置分类目录（与 src/adapters/* 的 displayName/defaultIncluded/portability 对齐，研究报告 §2.2） */
+export const DEFAULT_CATEGORIES: readonly ExportCategory[] = [
+  { id: 'settings', label: 'Settings', description: 'DSH 全局设置（namespace 分区，redacted）', defaultIncluded: true, portability: 'portable', group: 'general' },
+  { id: 'providers', label: 'Providers & Models', description: 'LLM Provider / Model / 默认模型 / BaseURL', defaultIncluded: true, portability: 'portable', group: 'ai' },
+  { id: 'plugins', label: 'Plugins', description: '已安装插件清单与启用状态（不含二进制）', defaultIncluded: true, portability: 'portable', group: 'extensions' },
+  { id: 'pluginFiles', label: 'Plugin Files', description: '插件自有配置文件（dsh-ssh.json 等，白名单）', defaultIncluded: false, portability: 'deviceSpecific', group: 'extensions' },
+  { id: 'mcp', label: 'MCP Servers', description: 'MCP 服务器组合配置（需重启生效）', defaultIncluded: true, portability: 'platformSpecific', group: 'mcp' },
+  { id: 'prompts', label: 'Prompts', description: 'System Prompt / Plan Mode 提示', defaultIncluded: true, portability: 'portable', group: 'customization' },
+  { id: 'skills', label: 'Skills', description: '用户技能文件（~/.dsh/skills）', defaultIncluded: true, portability: 'portable', group: 'customization' },
+  { id: 'agentPresets', label: 'Agent Presets', description: 'Agent 预设（~/.dsh/.agent-presets）', defaultIncluded: true, portability: 'portable', group: 'customization' },
+  { id: 'workspaces', label: 'Workspaces', description: '工作区记录（含绝对路径，需路径映射）', defaultIncluded: true, portability: 'platformSpecific', group: 'workspace' },
+  { id: 'ui', label: 'UI Preferences', description: 'UI 类 settings namespace（localStorage 项仅说明）', defaultIncluded: true, portability: 'portable', group: 'ui' },
+  { id: 'credentialsStatus', label: 'Credentials Status', description: '凭据状态（configured 标记，永不导出值）', defaultIncluded: true, portability: 'deviceSpecific', group: 'optional', sensitive: true },
+  { id: 'sessions', label: 'Sessions', description: '历史会话（默认关闭，含敏感内容）', defaultIncluded: false, portability: 'deviceSpecific', group: 'optional' },
+] as const;
+
+export class ExportFlow {
+  readonly categories: readonly ExportCategory[];
+  private readonly port: ExportPort;
+  private readonly onProgress: ProgressListener | undefined;
+
+  constructor(opts: ExportFlowOptions) {
+    this.port = opts.port;
+    this.categories = opts.categories ?? DEFAULT_CATEGORIES;
+    this.onProgress = opts.onProgress;
+  }
+
+  /** Quick Export 推荐分区（defaultIncluded 且非 deviceSpecific） */
+  quickSelection(): SectionId[] {
+    return this.categories.filter(isQuickRecommended).map((c) => c.id);
+  }
+
+  /** 按 §1 分组返回分类目录（Custom Export 树） */
+  groupedCatalog(): { group: ExportGroup; label: string; note?: string; categories: ExportCategory[] }[] {
+    return EXPORT_GROUPS.map((g) => ({
+      group: g.id,
+      label: g.label,
+      note: g.note,
+      categories: this.categories.filter((c) => c.group === g.id),
+    }));
+  }
+
+  /** 校验 Custom 勾选：未知分区 = invalid；deviceSpecific 分区给提示警告（仍可继续） */
+  validateSelection(selection: readonly SectionId[]): { valid: boolean; warnings: string[] } {
+    const warnings: string[] = [];
+    let valid = true;
+    const known = new Set(this.categories.map((c) => c.id));
+    for (const id of selection) {
+      if (!known.has(id)) {
+        warnings.push(`未知分区：${id}`);
+        valid = false;
+      }
+    }
+    for (const c of this.categories) {
+      if (selection.includes(c.id) && c.portability === 'deviceSpecific') {
+        warnings.push(`${c.label} 为设备相关数据（${c.portability}），跨设备导入时可能不适用`);
+      }
+    }
+    return { valid, warnings };
+  }
+
+  /** 执行导出：发进度事件 → 调 core → 渲染 §21 报告 */
+  async run(
+    mode: 'quick' | 'custom',
+    selection: readonly SectionId[],
+    opts: { includeSecrets?: boolean } = {},
+  ): Promise<ExportRunResult> {
+    const tracker = new ProgressTracker(EXPORT_STAGES, this.onProgress);
+    const only = mode === 'quick' ? this.quickSelection() : [...selection];
+    if (mode === 'quick' && opts.includeSecrets === undefined) opts = { ...opts, includeSecrets: false };
+
+    tracker.emit('analyzing');
+    tracker.emit('exporting-settings');
+    tracker.emit('scanning-secrets');
+    tracker.emit('exporting-plugins');
+    tracker.emit('creating-archive');
+    tracker.emit('calculating-checksums');
+
+    const result = await this.port.export({
+      includeSecrets: opts.includeSecrets ?? false,
+      only,
+    });
+
+    tracker.emit('done');
+    return { ...result, text: renderExportReport(result.report) };
+  }
+}