dsh-config-manager 0.1.0

package/src/ui/report.test.ts

@@ -0,0 +1,93 @@
+/**
+ * report 测试（m6-ui）：§21 导出报告 / §22 导入报告 / §17 回滚报告 / 动作按钮。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  formatBytes, importSectionStats, renderExportReport, renderImportReport,
+  renderRollbackReport, sectionFromItemId, suggestedActions,
+} from './report.ts';
+import { makeExportReport, makeImportResult, makeRollbackReport } from './test-helpers.ts';
+
+test('report: sectionFromItemId 前缀推断', () => {
+  assert.equal(sectionFromItemId('settings:general'), 'settings');
+  assert.equal(sectionFromItemId('ui:theme'), 'ui');
+  assert.equal(sectionFromItemId('provider:pi-ai'), 'providers');
+  assert.equal(sectionFromItemId('plugin:x'), 'plugins');
+  assert.equal(sectionFromItemId('patch:line-1'), 'plugins');
+  assert.equal(sectionFromItemId('mcp:filesystem'), 'mcp');
+  assert.equal(sectionFromItemId('prompt:p1'), 'prompts');
+  assert.equal(sectionFromItemId('workspace:ws-1'), 'workspaces');
+  assert.equal(sectionFromItemId('secret:K1'), 'credentialsStatus');
+  assert.equal(sectionFromItemId('skills:my.md'), 'skills');
+  assert.equal(sectionFromItemId('sessions:s1'), 'sessions');
+  assert.equal(sectionFromItemId('unknown'), 'other');
+});
+
+test('report: 导出报告含 Included/Excluded/Security/File', () => {
+  const text = renderExportReport(makeExportReport());
+  assert.ok(text.includes('Backup Created'));
+  assert.ok(text.includes('✓ settings'));
+  assert.ok(text.includes('8 plugins'));
+  assert.ok(text.includes('○ sessions'));
+  assert.ok(text.includes('API Keys excluded: yes'));
+  assert.ok(text.includes('File: dsh-config-2026-08-14.zip'));
+  assert.ok(text.includes('2 sensitive field(s) redacted'));
+});
+
+test('report: 导入报告分节统计', () => {
+  const result = makeImportResult();
+  const stats = importSectionStats(result.executed);
+  const settings = stats.find((s) => s.section === 'settings')!;
+  assert.equal(settings.ok, 2);
+  const plugins = stats.find((s) => s.section === 'plugins')!;
+  assert.equal(plugins.ok, 1);
+  assert.equal(plugins.skipped, 1);
+  const secrets = stats.find((s) => s.section === 'credentialsStatus')!;
+  assert.equal(secrets.skipped, 1);
+});
+
+test('report: 导入报告渲染含分节/重启/缺失 secret', () => {
+  const text = renderImportReport(makeImportResult());
+  assert.ok(text.includes('Import Complete'));
+  assert.ok(text.includes('settings: ✓ 2 imported'));
+  assert.ok(text.includes('Secrets: ⚠ 1 credentials need to be entered'));
+  assert.ok(text.includes('Restart required'));
+});
+
+test('report: 失败导入渲染 Import Failed + 回滚报告', () => {
+  const result = makeImportResult({
+    ok: false,
+    executed: [
+      { itemId: 'settings:a', status: 'ok' },
+      { itemId: 'mcp:m', status: 'failed', message: 'npx not found' },
+    ],
+    rollback: makeRollbackReport(),
+  });
+  const text = renderImportReport(result);
+  assert.ok(text.includes('Import Failed'));
+  assert.ok(text.includes('Rollback partially completed.'));
+  assert.ok(text.includes('manual recovery'));
+  assert.ok(text.includes('npx not found'));
+});
+
+test('report: 回滚报告 full / partial', () => {
+  assert.ok(renderRollbackReport({ full: true, restored: [], failed: [] }).includes('完整恢复'));
+  const partial = renderRollbackReport(makeRollbackReport());
+  assert.ok(partial.includes('Rollback partially completed.'));
+  assert.ok(partial.includes('请手动安装'));
+});
+
+test('report: suggestedActions 顺序（fixIssues → viewDetails → done）', () => {
+  assert.deepEqual(suggestedActions(makeImportResult()), ['viewDetails', 'done']);
+  const failed = makeImportResult({
+    executed: [{ itemId: 'mcp:m', status: 'failed' }],
+  });
+  assert.deepEqual(suggestedActions(failed), ['fixIssues', 'viewDetails', 'done']);
+});
+
+test('report: formatBytes', () => {
+  assert.equal(formatBytes(512), '512 B');
+  assert.equal(formatBytes(20480), '20.0 KB');
+  assert.equal(formatBytes(2 * 1024 * 1024), '2.0 MB');
+});

package/src/ui/report.ts

@@ -0,0 +1,140 @@
+/**
+ * 报告渲染（规范 §21 导出报告 / §22 导入报告 / §17 回滚报告，m6-ui）。
+ *
+ * 纯文本渲染：输出用户可读的多行文本（未来 React 客户端可直接替换为组件渲染）。
+ * 导入报告按分区统计：从 ExecutedItem.itemId 前缀推断所属分区（与 adapters 的 id 规则一致）。
+ */
+import type { SectionId } from '../schema/types.ts';
+import type {
+  ExecutedItem, ExportReport, ImportResult, RollbackReport,
+} from '../core/types.ts';
+import type { ImportResultAction, ImportSectionStat } from './types.ts';
+
+/* ---------------- §21 导出报告 ---------------- */
+
+export function renderExportReport(report: ExportReport): string {
+  const lines: string[] = ['Backup Created', ''];
+  lines.push('Included:');
+  for (const { section, counts } of report.included) {
+    const detail = Object.entries(counts)
+      .map(([k, v]) => `${v} ${k}`)
+      .join(', ');
+    lines.push(`  ✓ ${section}${detail !== '' ? ` (${detail})` : ''}`);
+  }
+  lines.push('');
+  if (report.excluded.length > 0) {
+    lines.push('Excluded:');
+    for (const s of report.excluded) lines.push(`  ○ ${s}`);
+    lines.push('');
+  }
+  lines.push('Security:');
+  lines.push(`  ✓ API Keys excluded: ${report.security.secretsExcluded ? 'yes' : 'no'}`);
+  lines.push(`  ✓ Contains secrets: ${report.security.containsSecrets ? 'yes (encrypted)' : 'no'}`);
+  lines.push(`  ✓ Encrypted: ${report.security.encrypted ? 'yes' : 'no'}`);
+  if (report.security.redactedHits > 0) lines.push(`  ⚠ ${report.security.redactedHits} sensitive field(s) redacted`);
+  lines.push('');
+  lines.push(`File: ${report.file.name} (${formatBytes(report.file.sizeBytes)})`);
+  for (const w of report.warnings) lines.push(`  ⚠ ${w}`);
+  return lines.join('\n');
+}
+
+/* ---------------- §22 导入报告 ---------------- */
+
+/** 从 itemId 前缀推断所属分区（与 adapters id 规则对齐；未知归 'other'） */
+export function sectionFromItemId(itemId: string): SectionId | 'other' {
+  if (itemId.startsWith('settings:')) return 'settings';
+  if (itemId.startsWith('ui:')) return 'ui';
+  if (itemId.startsWith('provider:')) return 'providers';
+  if (itemId.startsWith('plugin:') || itemId.startsWith('patch:')) return 'plugins';
+  if (itemId.startsWith('mcp:')) return 'mcp';
+  if (itemId.startsWith('prompt:')) return 'prompts';
+  if (itemId.startsWith('workspace:')) return 'workspaces';
+  if (itemId.startsWith('secret:')) return 'credentialsStatus';
+  if (itemId.startsWith('skills:')) return 'skills';
+  if (itemId.startsWith('agentPresets:')) return 'agentPresets';
+  if (itemId.startsWith('pluginFiles:')) return 'pluginFiles';
+  if (itemId.startsWith('sessions:')) return 'sessions';
+  return 'other';
+}
+
+/** 按分区聚合执行结果（统计 + 明细） */
+export function importSectionStats(executed: readonly ExecutedItem[]): ImportSectionStat[] {
+  const bySection = new Map<string, ImportSectionStat>();
+  for (const e of executed) {
+    const section = sectionFromItemId(e.itemId);
+    let stat = bySection.get(section);
+    if (!stat) {
+      stat = { section: section as SectionId, ok: 0, skipped: 0, failed: 0, items: [] };
+      bySection.set(section, stat);
+    }
+    if (e.status === 'ok') stat.ok += 1;
+    else if (e.status === 'skipped') stat.skipped += 1;
+    else stat.failed += 1;
+    stat.items.push(e);
+  }
+  return [...bySection.values()];
+}
+
+/** 导入报告渲染（含回滚状态；§22 动作按钮由 suggestedActions 给出） */
+export function renderImportReport(result: ImportResult): string {
+  const lines: string[] = [result.ok ? 'Import Complete' : 'Import Failed', ''];
+  const stats = importSectionStats(result.executed);
+  for (const s of stats) {
+    const parts: string[] = [];
+    if (s.ok > 0) parts.push(`✓ ${s.ok} imported/restored`);
+    if (s.skipped > 0) parts.push(`- ${s.skipped} skipped`);
+    if (s.failed > 0) parts.push(`✗ ${s.failed} failed`);
+    lines.push(`${s.section}: ${parts.join(' ') || 'no changes'}`);
+    // 失败项给出可操作原因（§23）
+    for (const it of s.items) {
+      if (it.status === 'failed') {
+        lines.push(`  Reason: ${it.message ?? '未知原因'}`);
+      }
+    }
+  }
+  if (result.missingSecrets.length > 0) {
+    lines.push(`Secrets: ⚠ ${result.missingSecrets.length} credentials need to be entered`);
+  }
+  if (result.needsRestart) {
+    lines.push('Restart required: 插件/MCP 变更将在重启 DSH 后生效');
+  }
+  for (const w of result.warnings) lines.push(`⚠ ${w}`);
+  if (result.rollback) {
+    lines.push('');
+    lines.push(renderRollbackReport(result.rollback));
+  }
+  return lines.join('\n');
+}
+
+/** 结果页动作按钮（§22：Fix Issues / View Details / Done） */
+export function suggestedActions(result: ImportResult): ImportResultAction[] {
+  const actions: ImportResultAction[] = [];
+  if (result.executed.some((e) => e.status === 'failed')) actions.push('fixIssues');
+  if (result.executed.length > 0 || result.warnings.length > 0) actions.push('viewDetails');
+  actions.push('done');
+  return actions;
+}
+
+/* ---------------- §17 回滚报告 ---------------- */
+
+/** 回滚报告渲染（full / partial + 人工恢复清单） */
+export function renderRollbackReport(rr: RollbackReport): string {
+  if (rr.full) {
+    return 'Rollback: 已完整恢复导入前的配置。';
+  }
+  const lines = ['Rollback partially completed.'];
+  lines.push('These items may require manual recovery:');
+  for (const f of rr.failed) {
+    lines.push(`  - ${f.item}: ${f.reason}${f.manualHint ? ` (${f.manualHint})` : ''}`);
+  }
+  if (rr.restored.length > 0) lines.push(`Restored: ${rr.restored.length} item(s)`);
+  return lines.join('\n');
+}
+
+/* ---------------- 工具 ---------------- */
+
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/ui/test-helpers.ts

@@ -0,0 +1,177 @@
+/**
+ * UI 层测试辅助（m6-ui）：mock core 调用与样本数据。
+ * 仅供 src/ui/*.test.ts 使用，不参与生产构建语义。
+ */
+import type { Manifest } from '../schema/types.ts';
+import type {
+  ExportReport, ImportAnalysis, ImportDecisions, ImportPlan, ImportResult,
+  PlanItem, RollbackReport,
+} from '../core/types.ts';
+import type { ExportPort } from './export-flow.ts';
+import type { ImportPort } from './types.ts';
+
+/** 样本 manifest（UI 测试不关心真实字段，仅类型占位） */
+export function makeManifest(): Manifest {
+  return {
+    schemaVersion: 1,
+    exporter: { name: 'dsh-config-manager-test', version: '0.0.0' },
+    source: { dshVersion: '0.1.0-rc.6', platform: 'win32', arch: 'x64' },
+    exportedAt: '2026-08-14T12:00:00.000Z',
+    sections: {
+      settings: true, ui: false, providers: false, plugins: false, mcp: false, prompts: false,
+      skills: false, agentPresets: false, workspaces: false, pluginFiles: false,
+      credentialsStatus: false, secrets: false, sessions: false,
+    },
+    security: { containsSecrets: false, encrypted: false, encryption: null },
+  };
+}
+
+export function makeExportReport(overrides: Partial<ExportReport> = {}): ExportReport {
+  return {
+    included: [
+      { section: 'settings', counts: { namespaces: 3 } },
+      { section: 'plugins', counts: { plugins: 8 } },
+    ],
+    excluded: ['sessions', 'pluginFiles'],
+    security: { secretsExcluded: true, containsSecrets: false, encrypted: false, redactedHits: 2 },
+    file: { name: 'dsh-config-2026-08-14.zip', sizeBytes: 20480 },
+    warnings: [],
+    ...overrides,
+  };
+}
+
+/** 内存 ExportPort mock：记录调用参数，返回固定结果 */
+export class MockExportPort implements ExportPort {
+  calls: { includeSecrets: boolean; only?: string[] }[] = [];
+  result: { zipPath: string; manifest: Manifest; report: ExportReport };
+  constructor(report: ExportReport = makeExportReport()) {
+    this.result = {
+      zipPath: report.file.name,
+      manifest: makeManifest(),
+      report,
+    };
+  }
+  async export(opts: { includeSecrets: boolean; only?: string[] }): Promise<{ zipPath: string; manifest: Manifest; report: ExportReport }> {
+    this.calls.push({ includeSecrets: opts.includeSecrets, only: opts.only });
+    return this.result;
+  }
+}
+
+/* ---------------- Import mock ---------------- */
+
+export function makeAnalysis(overrides: Partial<ImportAnalysis> = {}): ImportAnalysis {
+  return {
+    valid: true,
+    errors: [],
+    warnings: [],
+    compatibility: 'good',
+    sectionsInZip: ['settings', 'plugins', 'mcp', 'prompts'],
+    pluginSummary: { installed: 6, toInstall: 2 },
+    pathIssues: [],
+    secretCount: 3,
+    dependencyIssues: [],
+    ...overrides,
+  };
+}
+
+export function makePlanItem(overrides: Partial<PlanItem> = {}): PlanItem {
+  return {
+    id: 'settings:general',
+    kind: 'Create',
+    adapter: 'settings',
+    description: '创建设置 general',
+    severity: 'info',
+    ...overrides,
+  };
+}
+
+export function makePlan(overrides: Partial<ImportPlan> = {}): ImportPlan {
+  return {
+    items: [
+      makePlanItem({ id: 'settings:a', kind: 'Update', description: '更新设置 a' }),
+      makePlanItem({ id: 'settings:b', kind: 'Create', description: '创建设置 b' }),
+      makePlanItem({ id: 'plugin:x', kind: 'Install', adapter: 'plugins', description: '安装插件 x' }),
+      makePlanItem({ id: 'plugin:y', kind: 'Skip', adapter: 'plugins', description: '插件 y 已一致' }),
+      makePlanItem({ id: 'prompt:p', kind: 'Create', adapter: 'prompts', description: '创建提示 p' }),
+      makePlanItem({ id: 'mcp:m', kind: 'Create', adapter: 'mcp', description: '创建 MCP m' }),
+      makePlanItem({ id: 'secret:K1', kind: 'MissingSecret', adapter: 'credentialsStatus', description: '凭据 K1 需要补录' }),
+    ],
+    globalStrategy: 'merge',
+    pathMappings: [],
+    missingSecrets: [{ ref: 'K1', required: true }],
+    needsRestart: true,
+    estimatedActions: {
+      settings: 2, ui: 0, providers: 0, plugins: 1, mcp: 1, prompts: 1,
+      skills: 0, agentPresets: 0, workspaces: 0, pluginFiles: 0,
+      credentialsStatus: 0, secrets: 0, sessions: 0,
+    },
+    ...overrides,
+  };
+}
+
+export function makeRollbackReport(overrides: Partial<RollbackReport> = {}): RollbackReport {
+  return {
+    full: false,
+    restored: ['settings:a'],
+    failed: [{ item: 'plugin:x', reason: '安装失败', manualHint: '请手动安装' }],
+    ...overrides,
+  };
+}
+
+export function makeImportResult(overrides: Partial<ImportResult> = {}): ImportResult {
+  return {
+    ok: true,
+    executed: [
+      { itemId: 'settings:a', status: 'ok' },
+      { itemId: 'settings:b', status: 'ok' },
+      { itemId: 'plugin:x', status: 'ok', message: '需要重启生效' },
+      { itemId: 'plugin:y', status: 'skipped' },
+      { itemId: 'prompt:p', status: 'ok' },
+      { itemId: 'mcp:m', status: 'ok' },
+      { itemId: 'secret:K1', status: 'skipped', message: '凭据未提供' },
+    ],
+    needsRestart: true,
+    missingSecrets: ['K1'],
+    warnings: [],
+    rollback: null,
+    snapshotId: 'snap-1',
+    ...overrides,
+  };
+}
+
+/** 内存 ImportPort mock：可编排各阶段返回与调用记录 */
+export class MockImportPort implements ImportPort {
+  analysis: ImportAnalysis;
+  plan: ImportPlan;
+  result: ImportResult;
+  analyzeCalls = 0;
+  planCalls: ImportDecisions[] = [];
+  executeCalls: { confirm: boolean; secretInputs?: Record<string, string>; rollbackOnError: boolean }[] = [];
+
+  constructor(opts: {
+    analysis?: ImportAnalysis;
+    plan?: ImportPlan;
+    result?: ImportResult;
+  } = {}) {
+    this.analysis = opts.analysis ?? makeAnalysis();
+    this.plan = opts.plan ?? makePlan();
+    this.result = opts.result ?? makeImportResult();
+  }
+
+  async analyzeImport(): Promise<ImportAnalysis> {
+    this.analyzeCalls += 1;
+    return this.analysis;
+  }
+  async createImportPlan(_zip: string, decisions: ImportDecisions): Promise<ImportPlan> {
+    this.planCalls.push(decisions);
+    return this.plan;
+  }
+  async executeImportPlan(
+    _zip: string,
+    _plan: ImportPlan,
+    opts: { confirm: boolean; secretInputs?: Record<string, string>; rollbackOnError: boolean },
+  ): Promise<ImportResult> {
+    this.executeCalls.push(opts);
+    return this.result;
+  }
+}

package/src/ui/types.ts

@@ -0,0 +1,193 @@
+/**
+ * UI 层共享类型（m6-ui，框架无关）。
+ *
+ * 设计原则（对齐 Docs/design/architecture.md §12.2 与规范 §28/§29）：
+ *  - 本模块为纯 TypeScript 逻辑层，不引入 React / 打包器 / 任何运行时依赖；
+ *  - 未来 React 客户端（src/client/）直接消费本层的控制器输出（渲染文本 / 状态快照）；
+ *  - UI 层不直接 import core 的类实现，只依赖 core/types.ts 的纯类型 + 注入的「端口」
+ *    （ExportPort / ImportPort，宿主在 settings.section 挂载时把真实 Exporter/Importer 接入）。
+ */
+import type { SectionId } from '../schema/types.ts';
+import type {
+  CompatibilityScore, ImportAnalysis, ImportDecisions, ImportPlan, ImportResult,
+  ItemResolution, PathIssue, PlanItem, Portability, RollbackReport,
+} from '../core/types.ts';
+
+/* ---------------- 导出（规范 §1 / §21） ---------------- */
+
+export type ExportMode = 'quick' | 'custom';
+
+/** Custom Export 分组（规范 §1 分类；automation 组在 DSH 中无对应分区，UI 标注说明） */
+export type ExportGroup =
+  | 'general' | 'ai' | 'extensions' | 'mcp' | 'customization'
+  | 'automation' | 'workspace' | 'ui' | 'optional';
+
+/** 分类树节点（与 adapters 的 displayName/defaultIncluded/portability 对齐；宿主可注入覆盖） */
+export interface ExportCategory {
+  id: SectionId;
+  label: string;
+  description: string;
+  defaultIncluded: boolean;
+  portability: Portability;
+  group: ExportGroup;
+  /** 涉及秘密状态（如 credentialsStatus）：UI 需展示安全提示但绝不显示值 */
+  sensitive?: boolean;
+}
+
+export interface ExportGroupDef {
+  id: ExportGroup;
+  label: string;
+  /** automation 组在 DSH 无对应配置时的说明 */
+  note?: string;
+}
+
+/** Custom Export 分组目录（规范 §1；automation 组 DSH 无对应分区，仅说明） */
+export const EXPORT_GROUPS: readonly ExportGroupDef[] = [
+  { id: 'general', label: 'General' },
+  { id: 'ai', label: 'AI' },
+  { id: 'extensions', label: 'Extensions' },
+  { id: 'mcp', label: 'MCP / Tools' },
+  { id: 'customization', label: 'Customization' },
+  { id: 'automation', label: 'Automation', note: 'DSH 当前无 Workflows / Commands 配置文件（运行时注册），无迁移内容' },
+  { id: 'workspace', label: 'Workspace' },
+  { id: 'ui', label: 'UI' },
+  { id: 'optional', label: 'Optional Data' },
+] as const;
+
+/** Quick Export 推荐项 = defaultIncluded 且非 deviceSpecific（设计 §11.1） */
+export function isQuickRecommended(c: ExportCategory): boolean {
+  return c.defaultIncluded && c.portability !== 'deviceSpecific';
+}
+
+/* ---------------- 进度事件（规范 §29） ---------------- */
+
+export interface ProgressEvent {
+  /** 阶段 id（见 progress.ts 的 STAGE_TEXTS） */
+  stage: string;
+  detail?: string;
+  /** 阶段序号（从 1 起，供 UI 显示 n/m） */
+  step?: number;
+  /** 阶段总数 */
+  total?: number;
+}
+
+export type ProgressListener = (event: ProgressEvent) => void;
+
+/* ---------------- 导入向导（规范 §9 / §10 / §28） ---------------- */
+
+export type ImportStep =
+  | 'select'          // 选 ZIP
+  | 'analyzing'       // Analyzing...
+  | 'compatibility'   // Compatibility
+  | 'preview'         // Import Preview（Dry Run 摘要）
+  | 'conflicts'       // Resolve Conflicts（§11）
+  | 'path-mapping'    // Path Mapping（§12）
+  | 'secrets'         // Secrets 补录（§7）
+  | 'importing'       // Importing（含快照/回滚阶段）
+  | 'result';         // Result（§22）
+
+/** Preview 摘要（规范 §10 示例的数值化版本） */
+export interface ImportPreviewSummary {
+  /** 将更新的配置项数（Create+Update+Install 合计） */
+  willChange: number;
+  /** 已存在且一致的项（Skip） */
+  unchanged: number;
+  settingsUpdates: number;
+  pluginsInstalled: number;
+  pluginsToInstall: number;
+  mcpAdds: number;
+  prompts: number;
+  pathMappingsNeeded: number;
+  secretsNeeded: number;
+  conflicts: number;
+  needsRestart: boolean;
+}
+
+/** 向导状态快照（React 客户端可直接绑定渲染） */
+export interface WizardSnapshot {
+  step: ImportStep;
+  zipPath: string | null;
+  analysis: ImportAnalysis | null;
+  plan: ImportPlan | null;
+  result: ImportResult | null;
+  /** 导入执行的回滚策略（场景 E：默认 true 整体回滚） */
+  rollbackOnError: boolean;
+  errors: string[];
+}
+
+/* ---------------- 冲突视图（规范 §11） ---------------- */
+
+/** 单个冲突项的视图数据：当前值 vs 导入值摘要 + 用户决策 */
+export interface ConflictViewItem {
+  item: PlanItem;
+  currentSummary?: string;
+  importedSummary?: string;
+  resolution: ItemResolution | null;
+}
+
+/* ---------------- 路径映射（规范 §12） ---------------- */
+
+/** 路径映射编辑器的单条记录（旧前缀 → 新前缀；未解析时 newPrefix 为空串） */
+export interface PathMappingDraft {
+  /** 关联的原始路径问题值（一条 issue 一条 draft；批量映射用 oldPrefix 聚合） */
+  oldPrefix: string;
+  newPrefix: string;
+  issue?: PathIssue;
+  /** 应用范围（缺省 [] = 全部相关分区，与 core applyMappingsToSections 语义一致） */
+  appliesTo: PathMappingAppliesTo[];
+}
+
+/** 与 core PathMapping.appliesTo 对齐的取值（留空数组 = 全应用） */
+export type PathMappingAppliesTo = 'workspaces' | 'mcp' | 'pluginConfig' | 'skills';
+
+/* ---------------- 兼容性（规范 §30） ---------------- */
+
+export interface CompatibilityView {
+  score: CompatibilityScore;
+  sourceDsh: string;
+  targetDsh: string;
+  description: string;
+}
+
+/* ---------------- 报告（规范 §21 / §22 / §17） ---------------- */
+
+/** 导入结果按分区的统计（report.ts 用） */
+export interface ImportSectionStat {
+  section: SectionId;
+  ok: number;
+  skipped: number;
+  failed: number;
+  items: { itemId: string; status: 'ok' | 'skipped' | 'failed'; message?: string }[];
+}
+
+export type ImportResultAction = 'fixIssues' | 'viewDetails' | 'done';
+
+export interface RollbackView {
+  report: RollbackReport | null;
+  /** 是否有可展示的人工恢复清单（partial 回滚时） */
+  hasManualRecovery: boolean;
+}
+
+/* ---------------- 控制器公共依赖注入 ---------------- */
+
+/** UI 层与 core 的导入端口（宿主注入真实 Importer；测试注入内存 mock） */
+export interface ImportPort {
+  analyzeImport(zipPath: string): Promise<ImportAnalysis>;
+  createImportPlan(zipPath: string, decisions: ImportDecisions): Promise<ImportPlan>;
+  executeImportPlan(
+    zipPath: string,
+    plan: ImportPlan,
+    opts: {
+      /** 用户确认（安全阀，非 true 拒绝执行） */
+      confirm: boolean;
+      secretInputs?: Record<string, string>;
+      /** 显式回滚策略：true=任一项失败整体回滚（场景 E）；false=单项失败继续（§34.17） */
+      rollbackOnError: boolean;
+    },
+  ): Promise<ImportResult>;
+}
+
+/** 选项构造辅助：从 PlanItem 提取稳定决策键（与 core analyzer.applyItemResolution 的 id 语义一致） */
+export function itemDecisionKey(item: PlanItem): string {
+  return item.id;
+}

package/src/utils/hashing.ts

@@ -0,0 +1,53 @@
+/**
+ * SHA-256 完整性工具（integrity/checksums.json 的生成与校验）。
+ * m4 的 security/integrity.ts 可在此之上强化（本模块已实现规范 §18 全部语义）。
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+
+export function sha256Hex(data: Uint8Array | string): string {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+export async function hashFile(filePath: string): Promise<string> {
+  const data = await fs.readFile(filePath);
+  return sha256Hex(data);
+}
+
+/** 生成一组 ZIP 相对路径 → SHA-256 的校验表（路径必须为 ZIP 内正斜杠相对路径） */
+export function buildChecksums(entries: { name: string; data: Uint8Array }[]): Record<string, string> {
+  const checksums: Record<string, string> = {};
+  for (const e of entries) {
+    checksums[e.name] = sha256Hex(e.data);
+  }
+  return checksums;
+}
+
+export interface ChecksumVerifyResult {
+  ok: boolean;
+  mismatches: string[];
+  missing: string[];
+}
+
+/**
+ * 校验：checksums 表内每个相对路径必须在 entries 中存在且 SHA-256 一致。
+ * entries 中多余的文件（如 manifest.json / checksums.json 自身）不参与校验。
+ */
+export function verifyChecksums(
+  entries: ReadonlyMap<string, Uint8Array>,
+  checksums: Record<string, string>,
+): ChecksumVerifyResult {
+  const mismatches: string[] = [];
+  const missing: string[] = [];
+  for (const [relPath, expected] of Object.entries(checksums)) {
+    const data = entries.get(relPath);
+    if (data === undefined) {
+      missing.push(relPath);
+      continue;
+    }
+    if (sha256Hex(data) !== expected) {
+      mismatches.push(relPath);
+    }
+  }
+  return { ok: mismatches.length === 0 && missing.length === 0, mismatches, missing };
+}