dsh-config-manager 0.1.0

package/src/adapters/workspaces.ts

@@ -0,0 +1,95 @@
+/**
+ * workspaces 分区 adapter（设计 §3.3/§11）：
+ * 数据源 = ~/.dsh/storages/workspace.json 的 tables.workspaces（经 ctx.workspace 门面）。
+ * workspace.path 为绝对路径 → 跨设备必须 PathMapping（analyzeImport 生成 PathMapping 项，
+ * 映射由引擎 PathMapper 先行应用到 sections，applyItem 拿到的已是映射后数据）。
+ */
+import { isDeepStrictEqual } from 'node:util';
+import type { WorkspaceRecord, WorkspacesSection } from '../schema/types.ts';
+import type {
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ImportContext, PlanItem, ValidationResult,
+} from '../core/types.ts';
+
+export class WorkspacesAdapter implements ConfigAdapter<WorkspacesSection> {
+  readonly id = 'workspaces' as const;
+  readonly displayName = 'Workspaces';
+  readonly defaultIncluded = true;
+  readonly portability = 'platformSpecific' as const;
+
+  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<WorkspacesSection>> {
+    const records = await ctx.workspace.listRecords();
+    return {
+      sectionId: 'workspaces',
+      data: { version: 1, workspaces: records },
+      counts: { workspaces: records.length },
+      warnings: [],
+    };
+  }
+
+  async analyzeImport(data: WorkspacesSection, ctx: ImportContext): Promise<PlanItem[]> {
+    const items: PlanItem[] = [];
+    for (const rec of data.workspaces) {
+      const id = `workspace:${rec.id}`;
+      const existing = (await ctx.target.workspace.listRecords()).find((r) => r.id === rec.id);
+      if (!existing) {
+        items.push({
+          id, kind: 'Create', adapter: 'workspaces',
+          description: `创建工作区 ${rec.title ?? rec.id}（${rec.path}）`, severity: 'info',
+          target: { adapter: 'workspaces', ref: rec.id },
+        });
+      } else if (isDeepStrictEqual(existing, rec)) {
+        items.push({ id, kind: 'Skip', adapter: 'workspaces', description: `工作区 ${rec.id} 已一致`, severity: 'info' });
+      } else {
+        items.push({
+          id, kind: 'Conflict', adapter: 'workspaces',
+          description: `工作区 ${rec.id} 与目标不同`,
+          detail: `current=${JSON.stringify(existing)} imported=${JSON.stringify(rec)}`.slice(0, 200),
+          severity: 'warning', target: { adapter: 'workspaces', ref: rec.id },
+        });
+      }
+      // 绝对路径 → 路径映射提示（oldPrefix 先用整条路径占位，newPrefix 由 UI 确认）
+      if (rec.path.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(rec.path)) {
+        items.push({
+          id: `${id}:path`, kind: 'PathMapping', adapter: 'workspaces',
+          description: `路径需映射: ${rec.path}`, severity: 'warning',
+          pathMapping: { oldPrefix: rec.path, newPrefix: '', appliesTo: ['workspaces'] },
+          target: { adapter: 'workspaces', ref: rec.id },
+        });
+      }
+    }
+    return items;
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    // PathMapping 项：数据已由 PathMapper 应用到 sections，无需额外写入
+    if (item.kind === 'PathMapping') return { ok: true };
+    const ref = item.target?.ref;
+    if (!ref) return { ok: false, message: '缺少 target.ref' };
+    const data = ctx.sections.get('workspaces') as WorkspacesSection | undefined;
+    const rec = data?.workspaces.find((r) => r.id === ref);
+    if (!rec) return { ok: false, message: `导入数据缺少工作区 ${ref}` };
+    await ctx.target.workspace.writeRecord(rec);
+    return { ok: true };
+  }
+
+  async validate(data: WorkspacesSection): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: 'workspaces 数据必须是对象', severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: `version 必须为 1（收到 ${String(data.version)}）`, severity: 'error' });
+    }
+    if (!Array.isArray(data.workspaces)) {
+      issues.push({ path: 'workspaces', message: 'workspaces 必须是数组', severity: 'error' });
+    } else {
+      for (const w of data.workspaces as WorkspaceRecord[]) {
+        if (w === null || typeof w !== 'object' || typeof w.id !== 'string' || typeof w.path !== 'string') {
+          issues.push({ path: 'workspaces[]', message: 'workspace 记录必须含字符串 id 与 path', severity: 'error' });
+        }
+      }
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}

package/src/client/CLIENT_DEPENDENCIES.md

@@ -0,0 +1,101 @@
+# Client 半（src/client）构建依赖清单 — 给 p3 的输入
+
+> 本文件由 p1（client 半）产出，只描述 `src/client/**` 需要的依赖与 tsconfig 变更；
+> **p1 未修改 package.json / tsconfig**（按任务约定，构建配置由 p3 负责）。
+
+## 1. 必装依赖
+
+### runtime peerDependencies（`dsh.client.inject` 声明，参考 dsh-ssh package.json）
+
+| 包 | 版本基线 | 用途 |
+|---|---|---|
+| `@deepseek-ai/dsh-client-runtime` | `^0.1.0-rc.6` | ClientContext 类型、slots 运行时 |
+| `@deepseek-ai/dsh-client-locale` | `^0.1.0-rc.6` | `ctx.locale` 声明合并（index.ts 用） |
+| `@deepseek-ai/dsh-client-ui-settings` | `^0.1.0-rc.6` | `settings.section` SlotMap 声明合并（index.ts 用） |
+| `@deepseek-ai/dsh-client-ui-slots` | `^0.1.0-rc.6` | SlotMap / LocaleNamespaceMap / PropsRuntime / TranslateNS |
+| `@deepseek-ai/cordis` | `^4.0.1` | Context 基础类型 |
+| `react` / `react-dom` | `^18.2.0`（dsh-ssh 同款） | 组件渲染 |
+| `@types/react` / `@types/react-dom` | `~18.3.1` / `^18.3.5` | dev 类型 |
+
+`dsh.client` 声明（对照 dsh-ssh）：
+
+```jsonc
+"dsh": {
+  "bundle": { "patch": "./cordis.patch.yml" },
+  "client": {
+    "inject": [
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-connection",
+      "@deepseek-ai/dsh-client-ui-settings"
+    ],
+    "platform": "web"
+  }
+}
+```
+
+### devDependencies（构建）
+
+| 包 | 用途 |
+|---|---|
+| `lightningcss` | `^1.32.0`（dsh-ssh 同款）— CSS Modules 编译 |
+| `tsdown` | `^0.22.2`（dsh-ssh 同款）— host+client bundle |
+| `typescript` | `~5.7.2` 或现有 `^5.9.0` 均可 |
+
+## 2. tsconfig 变更（p3 需加）
+
+现有 `tsconfig.json`：`lib: ["ES2023"]` + `types: ["node"]` + include `src/**/*.ts`。
+
+client 需要：
+
+```jsonc
+{
+  "compilerOptions": {
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "types": ["node", "react", "react-dom"]        // 或经 @types 自动解析
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.d.ts"]
+}
+```
+
+> 说明：`src/client/**` 的 `.tsx` 文件当前不在 `include`（`src/**/*.ts` 不匹配 `.tsx`），
+> 不影响现有 `npm run typecheck`（core/ui 仍全绿）；p3 打开 `.tsx` 后
+> 需一并补齐 DOM lib 与 jsx，否则 client 类型不通过。
+
+## 3. Host 半 `/api/dsh-config-manager/*` 路由契约（client 按此调用）
+
+p1 只做 client 侧 fetch 封装（`src/client/api.ts`），Host 半（`src/index.ts`）按此实现：
+
+```
+GET  /api/dsh-config-manager/status        → ServiceStatus { ready, pluginVersion, dshVersion, platform, arch }
+POST /api/dsh-config-manager/export        body: { includeSecrets, only?, password? } → ExportResponse { zipPath, manifest, report }
+GET  /api/dsh-config-manager/download?path → 文件流（content-disposition: filename="..."）
+POST /api/dsh-config-manager/upload?name   body: 原始字节 → UploadResponse { zipPath, name, sizeBytes }
+POST /api/dsh-config-manager/analyze       body: { zipPath } → ImportAnalysis
+POST /api/dsh-config-manager/plan          body: { zipPath, decisions } → ImportPlan
+POST /api/dsh-config-manager/execute       body: { zipPath, plan, opts: { confirm, secretInputs, rollbackOnError } } → ImportResult
+```
+
+- `password` 仅加密备份模式传入（Host 侧 `security/encryption.ts` scrypt+AES-256-GCM），
+  **绝不写入 manifest / 任何配置**；
+- `upload` 落 Host 受控临时目录（如 `~/.dsh/dsh-config-manager/tmp/`），返回的 zipPath
+  供 analyze/plan/execute 引用；
+- 错误响应统一 `{ error: string }`（client `readJson` 依赖该形状）；
+- Host 侧路由安全围栏参考 dsh-ssh `isLoopbackRequest`（仅 127.0.0.1 + 同源）。
+
+## 4. 与 src/ui 的绑定点（p1 实现摘要）
+
+| src/ui 模块 | client 消费 |
+|---|---|
+| `export-flow.ts` 的 `ExportFlow` / `DEFAULT_CATEGORIES` | `export/ExportView.tsx`（port=api） |
+| `types.ts` 的 `EXPORT_GROUPS` / `ProgressEvent` / `ImportPreviewSummary` | 导出勾选目录 / 进度条 / 预览摘要 |
+| `import-wizard.ts` 的 `ImportWizard` | `import/ImportWizardView.tsx`（port=api） |
+| `conflict-view.ts` 的 `ConflictCollector` | `import/ConflictList.tsx` |
+| `report.ts` 的 `renderExportReport` / `renderImportReport` / `renderRollbackReport` / `suggestedActions` / `importSectionStats` | `common/ReportView.tsx` |
+| `errors.ts` 的 `toActionableError` / `formatActionableError` | `common/ErrorBanner.tsx` |
+| `progress.ts` 的 `stageText` / `ProgressTracker` | `common/ProgressBar.tsx` |
+| `security/redaction.ts` 的 `redact` | 全部文本展示前的强制脱敏（双保险） |
+
+> 例外：`ui/path-mapping.ts` 的 `PathMappingEditor` 依赖 `utils/paths.ts`（`node:path`），
+> 浏览器 bundle 不可用 —— `import/PathMappingForm.tsx` 做轻量等价实现（输入输出形状
+> 与 core `PathMapping` 一致，实际前缀替换由 Host 侧 core 在 `createImportPlan` 阶段执行）。

package/src/client/ConfigManagerSection.tsx

@@ -0,0 +1,60 @@
+/**
+ * Config Manager 设置页（settings.section 入口的主页面容器）。
+ *
+ * owner props 由 settings shell 传入（close）；业务面（api）由注册时的
+ * inject face 注入；t 由 locale seat 注入。内部两个主视图：
+ * Export（Quick/Custom）与 Import（九步向导）。
+ */
+import { useState } from 'react'
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ConfigManagerSectionInjected, TranslateNS } from './client-types.ts'
+import { ExportView } from './export/ExportView.tsx'
+import { ImportWizardView } from './import/ImportWizardView.tsx'
+import css from './config-manager.module.css'
+
+export type ConfigManagerSectionProps =
+  & PropsRuntime<'settings.section'>
+  & ConfigManagerSectionInjected
+  & { t: TranslateNS<'config-manager'> }
+
+type MainView = 'export' | 'import'
+
+/**
+ * 设置页容器：Export / Import 双视图切换。
+ */
+export function ConfigManagerSection({ close, api, t }: ConfigManagerSectionProps) {
+  const [view, setView] = useState<MainView>('export')
+
+  return (
+    <div className={css.section}>
+      <div className={css.sectionHeader}>
+        <div className={css.viewTabs} role="tablist">
+          <button
+            type="button"
+            role="tab"
+            aria-selected={view === 'export'}
+            data-active={view === 'export' ? '' : undefined}
+            className={css.viewTab}
+            onClick={() => { setView('export') }}
+          >
+            {t('view.export')}
+          </button>
+          <button
+            type="button"
+            role="tab"
+            aria-selected={view === 'import'}
+            data-active={view === 'import' ? '' : undefined}
+            className={css.viewTab}
+            onClick={() => { setView('import') }}
+          >
+            {t('view.import')}
+          </button>
+        </div>
+        <button type="button" className={css.iconButton} title={t('common.close')} aria-label={t('common.close')} onClick={close}>×</button>
+      </div>
+      <div className={css.sectionBody}>
+        {view === 'export' ? <ExportView api={api} t={t} /> : <ImportWizardView api={api} t={t} />}
+      </div>
+    </div>
+  )
+}

package/src/client/api.ts

@@ -0,0 +1,270 @@
+/**
+ * Config Manager 浏览器半 —— `/api/dsh-config-manager/*` 的类型化 fetch 封装。
+ *
+ * 设计对齐 dsh-ssh 的 `src/client/api.ts` 范式（同源 fetch、readJson、query helper），
+ * 但方法签名直接实现 `src/ui/types.ts` 的 `ExportPort` / `ImportPort` 端口契约：
+ * 客户端控制器（ExportFlow / ImportWizard）把本类实例当作 port 注入即可，
+ * 无需任何额外适配层 —— 这是「直接绑定 src/ui，不重复实现」的关键。
+ *
+ * 端点契约（Host 半 `src/index.ts` 按此实现，见 CLIENT_DEPENDENCIES.md 的接口说明）：
+ * ```
+ * GET  /api/dsh-config-manager/status             → ServiceStatus        （健康/版本检查）
+ * POST /api/dsh-config-manager/export             → ExportResponse       （body: ExportOptions）
+ * GET  /api/dsh-config-manager/download?path=…    → 文件流（content-disposition 文件名）
+ * POST /api/dsh-config-manager/upload?name=…      → UploadResponse       （body: 原始字节）
+ * POST /api/dsh-config-manager/analyze            → ImportAnalysis       （body: { zipPath }）
+ * POST /api/dsh-config-manager/plan               → ImportPlan           （body: { zipPath, decisions }）
+ * POST /api/dsh-config-manager/execute            → ImportResult         （body: { zipPath, plan, opts }）
+ * ```
+ * 安全约束：
+ *  - 所有响应/错误文本在进入 UI 前经 `redact()`（见 common/ErrorBanner.tsx）；
+ *  - secretInputs 只存在于请求体内，绝不落日志；
+ *  - 本文件不 import 任何 node 模块（纯浏览器 bundle）。
+ */
+
+import type { ImportAnalysis, ImportDecisions, ImportPlan, ImportResult } from '../core/types.ts';
+import type { ExportOptions, ExportReport } from '../core/types.ts';
+import type { Manifest } from '../schema/types.ts';
+
+/** Host 半健康检查响应（plugin 版本 / DSH 版本 / 平台，用于主页横幅与兼容性说明） */
+export interface ServiceStatus {
+  ready: boolean;
+  pluginVersion: string;
+  dshVersion: string;
+  platform: string;
+  arch: string;
+}
+
+/** export 端点响应（对齐 ExportFlow 的 ExportRunResult 前半部分） */
+export interface ExportResponse {
+  zipPath: string;
+  manifest: Manifest;
+  report: ExportReport;
+}
+
+/** upload 端点响应：Host 把用户上传的 ZIP 存入受控临时目录，返回可被 analyze/plan/execute 引用的路径 */
+export interface UploadResponse {
+  zipPath: string;
+  name: string;
+  sizeBytes: number;
+}
+
+/** execute 端点请求体（对齐 ImportWizard.execute 的 opts） */
+export interface ExecutePayload {
+  zipPath: string;
+  plan: ImportPlan;
+  opts: {
+    /** 安全阀：非 true 拒绝执行（core ImportNotConfirmedError） */
+    confirm: boolean;
+    /** 秘密补录值（仅内存，经 HTTPS 传输，Host 端不落盘） */
+    secretInputs: Record<string, string>;
+    /** true=任一项失败整体回滚（场景 E）；false=单项失败继续 */
+    rollbackOnError: boolean;
+  };
+}
+
+/** 路由族常量（集中管理，与 Host 半的路由前缀保持一致） */
+export const CONFIG_MANAGER_API = {
+  base: '/api/dsh-config-manager',
+  status: '/api/dsh-config-manager/status',
+  export: '/api/dsh-config-manager/export',
+  download: '/api/dsh-config-manager/download',
+  upload: '/api/dsh-config-manager/upload',
+  analyze: '/api/dsh-config-manager/analyze',
+  plan: '/api/dsh-config-manager/plan',
+  execute: '/api/dsh-config-manager/execute',
+} as const;
+
+/** 携带路由 JSON error 消息的错误类型 */
+export class ConfigManagerApiError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigManagerApiError';
+  }
+}
+
+/** 解析 JSON 响应；非 2xx 时抛出带路由 error 消息的 ConfigManagerApiError */
+async function readJson<T>(response: Response): Promise<T> {
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    throw new ConfigManagerApiError(`HTTP ${response.status}: invalid JSON response`);
+  }
+  if (!response.ok) {
+    const message =
+      typeof body === 'object' && body !== null && typeof (body as { error?: unknown }).error === 'string'
+        ? (body as { error: string }).error
+        : `HTTP ${response.status}`;
+    throw new ConfigManagerApiError(message);
+  }
+  return body as T;
+}
+
+/** query-string 辅助（跳过 undefined/空串，与 dsh-ssh 一致） */
+function query(params: Record<string, string | number | undefined>): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== '') search.set(key, String(value));
+  }
+  const text = search.toString();
+  return text === '' ? '' : '?' + text;
+}
+
+/** 浏览器 File System Access API 的最小表面（非全部 lib.dom 版本都有） */
+interface WindowWithFileSystemAccess {
+  showSaveFilePicker?: (options: { suggestedName?: string }) => Promise<{
+    createWritable: () => Promise<{ write: (data: Uint8Array) => Promise<void>; close: () => Promise<void> }>;
+  }>;
+}
+
+/** 导出下载结果（流式落盘或内存 Blob 兜底） */
+export interface DownloadResult {
+  blob?: Blob;
+  filename: string;
+  streamed: boolean;
+  bytes: number;
+}
+
+/**
+ * Config Manager 浏览器半的唯一数据入口。
+ * 同时实现 `ExportPort`（export-flow 用）与 `ImportPort`（import-wizard 用）。
+ */
+export class ConfigManagerApi {
+  /**
+   * 加密备份密码（仅内存，默认 null = 普通备份）。
+   * ExportView 在 run 前设置；export 请求体携带给 Host 半做 AES-256-GCM 加密。
+   * 绝不写入 manifest / 任何 DSH 配置 / localStorage。
+   */
+  exportPassword: string | null = null
+
+  // ------------------------------------------------------------- status
+  /** 健康/版本检查（主页横幅：插件版本 / DSH 版本 / 平台） */
+  async status(): Promise<ServiceStatus> {
+    const response = await fetch(CONFIG_MANAGER_API.status);
+    return readJson<ServiceStatus>(response);
+  }
+
+  // ------------------------------------------------------------- export
+  /** ExportPort.export：调用 Host 侧导出编排（core Exporter）。加密密码随请求体传输（仅内存）。 */
+  async export(options: ExportOptions): Promise<ExportResponse> {
+    const body: ExportOptions & { password?: string } = {
+      ...options,
+      password: this.exportPassword ?? undefined,
+    };
+    const response = await fetch(CONFIG_MANAGER_API.export, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return readJson<ExportResponse>(response);
+  }
+
+  /**
+   * 把导出的 ZIP 下载到本机。优先 File System Access API 流式落盘
+   * （不占整文件内存），不可用时回退内存 Blob（dsh-ssh downloadFile 同款策略）。
+   */
+  async download(
+    zipPath: string,
+    onProgress?: (received: number, total: number) => void,
+  ): Promise<DownloadResult> {
+    const response = await fetch(CONFIG_MANAGER_API.download + query({ path: zipPath }));
+    if (!response.ok || response.body === null) {
+      const text = await response.text().catch(() => '');
+      throw new ConfigManagerApiError(text !== '' ? text : `download failed: HTTP ${response.status}`);
+    }
+    const total = Number(response.headers.get('content-length') ?? '0');
+    const disposition = response.headers.get('content-disposition') ?? '';
+    const match = /filename="([^"]+)"/.exec(disposition);
+    const filename = match?.[1] ?? zipPath.split(/[\\/]/).pop() ?? 'dsh-config.zip';
+    const reader = response.body.getReader();
+    const picker =
+      typeof window !== 'undefined'
+        ? (window as WindowWithFileSystemAccess).showSaveFilePicker
+        : undefined;
+    let streamed = false;
+    let writable: { write: (data: Uint8Array) => Promise<void>; close: () => Promise<void> } | undefined;
+    const chunks: Uint8Array<ArrayBuffer>[] = [];
+    let received = 0;
+    try {
+      if (picker !== undefined) {
+        const handle = await picker.call(window, { suggestedName: filename });
+        writable = await handle.createWritable();
+        streamed = true;
+      }
+    } catch {
+      // 用户取消保存对话框或 API 不可用：回退内存 Blob。
+    }
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (writable !== undefined) {
+        await writable.write(value as Uint8Array);
+      } else {
+        chunks.push(value as Uint8Array<ArrayBuffer>);
+      }
+      received += value.length;
+      onProgress?.(received, total);
+    }
+    if (writable !== undefined) await writable.close();
+    return {
+      blob: streamed ? undefined : new Blob(chunks),
+      filename,
+      streamed,
+      bytes: received,
+    };
+  }
+
+  // ------------------------------------------------------------- import
+  /** 上传用户选择的 ZIP 到 Host 受控临时目录，返回可引用的 zipPath（dsh-ssh 同款原始字节上传） */
+  async upload(file: File): Promise<UploadResponse> {
+    const response = await fetch(CONFIG_MANAGER_API.upload + query({ name: file.name }), {
+      method: 'POST',
+      body: file,
+    });
+    return readJson<UploadResponse>(response);
+  }
+
+  /** ImportPort.analyzeImport：零写入分析（校验/兼容性/差异/路径/秘密检测） */
+  async analyzeImport(zipPath: string): Promise<ImportAnalysis> {
+    const response = await fetch(CONFIG_MANAGER_API.analyze, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ zipPath }),
+    });
+    return readJson<ImportAnalysis>(response);
+  }
+
+  /** ImportPort.createImportPlan：用用户决策（冲突/路径映射/策略）生成最终计划（Dry Run 零写入） */
+  async createImportPlan(zipPath: string, decisions: ImportDecisions): Promise<ImportPlan> {
+    const response = await fetch(CONFIG_MANAGER_API.plan, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ zipPath, decisions }),
+    });
+    return readJson<ImportPlan>(response);
+  }
+
+  /** ImportPort.executeImportPlan：快照→分阶段 apply→validate→commit/rollback */
+  async executeImportPlan(
+    zipPath: string,
+    plan: ImportPlan,
+    opts: { confirm: boolean; secretInputs?: Record<string, string>; rollbackOnError: boolean },
+  ): Promise<ImportResult> {
+    const payload: ExecutePayload = {
+      zipPath,
+      plan,
+      opts: {
+        confirm: opts.confirm,
+        secretInputs: opts.secretInputs ?? {},
+        rollbackOnError: opts.rollbackOnError,
+      },
+    };
+    const response = await fetch(CONFIG_MANAGER_API.execute, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    return readJson<ImportResult>(response);
+  }
+}

package/src/client/client-types.ts

@@ -0,0 +1,27 @@
+/**
+ * Client 半的类型集中出口：把对 @deepseek-ai 运行时包的类型依赖收敛到本文件，
+ * 其余组件只从 `../client-types.ts` 引用，避免类型散落与误用值导入。
+ *
+ * p3 构建前需安装的依赖（见 CLIENT_DEPENDENCIES.md）：
+ *   - @deepseek-ai/dsh-client-runtime（ClientContext 声明合并）
+ *   - @deepseek-ai/dsh-client-locale（ctx.locale 声明合并）
+ *   - @deepseek-ai/dsh-client-ui-settings（settings.section SlotMap 声明合并）
+ *   - @deepseek-ai/dsh-client-ui-slots（SlotMap / LocaleNamespaceMap / TranslateNS）
+ *   - @deepseek-ai/cordis（Context 基础类型）
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+
+export type { ClientContext }
+export type { TranslateNS }
+
+/** settings.section 注册项的 owner props（shell 传入 close） */
+export interface SettingsSectionProps {
+  /** 关闭设置面板（shell 拥有 open 状态） */
+  close: () => void
+}
+
+/** 本插件 Client 半的注入业务面：每个 settings.section 注册项都拿到同一个 api 实例 */
+export interface ConfigManagerSectionInjected {
+  api: import('./api.ts').ConfigManagerApi
+}

package/src/client/common/ErrorBanner.tsx

@@ -0,0 +1,68 @@
+/**
+ * 可操作错误展示（规范 §23，绑 src/ui/errors.ts）。
+ *
+ * 安全约束：**强制 redact 不泄 Secret** —— 展示前对错误消息、关联项文本
+ * 统一过 `redact()`（字段名黑名单 + sk-/JWT/PEM/Bearer 等值形状模式），
+ * 渲染结果只含 Reason / Suggested action / Item，绝不出现密钥原文。
+ */
+import { useState } from 'react'
+import { formatActionableError, toActionableError } from '../../ui/errors.ts'
+import { redact } from '../../security/redaction.ts'
+import { Button } from './ui.tsx'
+import css from '../config-manager.module.css'
+
+export interface ErrorBannerProps {
+  /** 任意未知错误（Error / 字符串 / API 错误） */
+  error: unknown
+  /** 可重试时显示的重试按钮（缺省不显示） */
+  onRetry?: () => void
+  /** 重试中的 loading 态 */
+  retrying?: boolean
+}
+
+/**
+ * 错误横幅：toActionableError 解析为标题 + 原因 + 建议动作，
+ * 文本在渲染前再经 redact() 兜底（双保险），Reason 以等宽块展示。
+ */
+export function ErrorBanner({ error, onRetry, retrying }: ErrorBannerProps) {
+  const [actionable] = useState(() => toActionableError(error))
+  const reason = redact(actionable.reason)
+  const item = actionable.item !== undefined ? redact(actionable.item) : undefined
+
+  return (
+    <div className={css.errorBanner} role="alert">
+      <div className={css.errorTitle}>{redact(actionable.title)}</div>
+      <pre className={css.errorReason}>{reason}</pre>
+      {actionable.suggestedAction !== undefined && (
+        <div className={css.errorAction}>
+          <span className={css.errorActionLabel}>→</span> {redact(actionable.suggestedAction)}
+        </div>
+      )}
+      {item !== undefined && <div className={css.errorItem}>{item}</div>}
+      {actionable.retryable && onRetry !== undefined && (
+        <div className={css.errorFooter}>
+          <Button variant="primary" onClick={onRetry} disabled={retrying === true}>
+            {retrying === true ? '…' : 'Retry'}
+          </Button>
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** 多行错误文本展示（Wizard.errors 数组用；同样强制 redact） */
+export function ErrorList({ errors }: { errors: readonly string[] }) {
+  if (errors.length === 0) return null
+  return (
+    <div className={css.errorList}>
+      {errors.map((line, i) => (
+        <pre key={i} className={css.errorLine}>{redact(line)}</pre>
+      ))}
+    </div>
+  )
+}
+
+/** formatActionableError 的文本化出口（供非 React 渲染场景复用） */
+export function formatErrorText(error: unknown): string {
+  return formatActionableError(toActionableError(error))
+}

package/src/client/common/ProgressBar.tsx

@@ -0,0 +1,49 @@
+/**
+ * 进度条（规范 §29，绑 src/ui/progress.ts）。
+ *
+ * 控制器（ExportFlow / ImportWizard）在调用 core 前后发出 ProgressEvent，
+ * 本组件按 stage 文案 + step/total 渲染进度条；未知阶段回退显示 id 本身。
+ */
+import { stageText } from '../../ui/progress.ts'
+import type { ProgressEvent } from '../../ui/types.ts'
+import css from '../config-manager.module.css'
+
+export interface ProgressBarProps {
+  /** 当前阶段事件（null = 未开始） */
+  event: ProgressEvent | null
+  /** 是否正在执行（false 时显示为完成态） */
+  active: boolean
+}
+
+/**
+ * 进度条：阶段文字 + 百分比（有 step/total 时计算，否则不定态动画）。
+ */
+export function ProgressBar({ event, active }: ProgressBarProps) {
+  const percent =
+    event !== null && event.step !== undefined && event.total !== undefined && event.total > 0
+      ? Math.round((event.step / event.total) * 100)
+      : null
+  const label = event !== null ? stageText(event.stage) : ''
+
+  return (
+    <div className={css.progressBlock}>
+      <div className={css.progressMeta}>
+        <span className={css.progressLabel}>{label}</span>
+        {event?.detail !== undefined && event.detail !== '' && (
+          <span className={css.progressDetail}>{event.detail}</span>
+        )}
+        {percent !== null && <span className={css.progressPercent}>{percent}%</span>}
+      </div>
+      <div className={css.progressTrack}>
+        {percent !== null ? (
+          <div
+            className={`${css.progressBar} ${active ? '' : css.progressBarDone}`}
+            style={{ width: `${percent}%` }}
+          />
+        ) : (
+          <div className={`${css.progressBar} ${css.progressIndeterminate}`} />
+        )}
+      </div>
+    </div>
+  )
+}