@logictan/dsh-config-manager 0.1.60

package/src/adapters/ui.ts

@@ -0,0 +1,108 @@
+/**
+ * ui 分区 adapter（设计 §3.3/§4.1/§4.3）：
+ * 数据源 = settings.yaml 中「UI 类」namespace（pet / dsh-better-sidebar / remote-web-ui / ui-onboarding / skin 等）。
+ * localStorage 等 Host 不可迁移的 UI 状态以 uiMigrationNotes 纯说明形式导出（不含任何值）。
+ */
+import type { NamespaceRecord, UiSection } from '../schema/types.ts';
+import { zhMsg } from '../core/messages.ts';
+import type { MsgFunc } from '../core/messages.ts';
+import type {
+  ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext,
+  ImportContext, PlanItem, ValidationResult,
+} from '../core/types.ts';
+import { collectNamespaceRecords, planNamespaceItems, applyNamespaceItem, resolveNamespaces, type NamespaceProvider } from './settings.ts';
+
+/** UI 类 namespace 前缀名单（设计 §4.1；随新插件扩展，只影响「某一 namespace 归哪一边」，不影响数据完整性） */
+export const KNOWN_UI_NAMESPACE_PREFIXES: readonly string[] = [
+  'pet',
+  'dsh-better-sidebar',
+  'remote-web-ui',
+  'ui-onboarding',
+  'dsh-client-ui',
+  'skin',
+  'theme',
+  'layout',
+  'sidebar',
+  'appearance',
+];
+
+/** namespace 名是否属于 UI 类（大小写不敏感前缀匹配） */
+export function isUiNamespace(name: string): boolean {
+  const lower = name.toLowerCase();
+  return KNOWN_UI_NAMESPACE_PREFIXES.some((p) => lower.startsWith(p.toLowerCase()));
+}
+
+/** localStorage 等 Host 无通道的 UI 状态说明（纯说明，不含值；研究报告 §2.2/§4.4） */
+export const UI_MIGRATION_NOTES: UiSection['uiMigrationNotes'] = [
+  {
+    plugin: 'dsh-task-board',
+    storage: 'localStorage',
+    key: 'dsh.taskBoard.v1',
+    migratable: false,
+    reason: '任务看板数据存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
+  },
+  {
+    plugin: 'dsh-aionui-panel',
+    storage: 'localStorage',
+    key: 'aionui-panel.*',
+    migratable: false,
+    reason: '面板宽度/折叠状态存于浏览器 localStorage，Host 侧无访问通道，需在目标机器重新配置',
+  },
+  {
+    plugin: 'dsh-client-ui-*',
+    storage: 'localStorage',
+    key: '*',
+    migratable: false,
+    reason: '浏览器端 UI 状态无法经 Host API 迁移',
+  },
+];
+
+export class UiAdapter implements ConfigAdapter<UiSection> {
+  readonly id = 'ui' as const;
+  readonly displayName = 'UI Preferences';
+  readonly defaultIncluded = true;
+  readonly portability = 'portable' as const;
+  private readonly namespaces: string[] | NamespaceProvider;
+
+  constructor(namespaces: string[] | NamespaceProvider = []) {
+    this.namespaces = namespaces;
+  }
+
+  async export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<UiSection>> {
+    const warnings: string[] = [];
+    const all = await resolveNamespaces(this.namespaces, ctx);
+    const uiNames = all.filter((n) => isUiNamespace(n));
+    const namespaces: Record<string, NamespaceRecord> = await collectNamespaceRecords(ctx, uiNames, warnings);
+    return {
+      sectionId: 'ui',
+      data: { version: 1, namespaces, uiMigrationNotes: UI_MIGRATION_NOTES },
+      counts: { namespaces: Object.keys(namespaces).length, notes: UI_MIGRATION_NOTES.length },
+      warnings,
+    };
+  }
+
+  async analyzeImport(data: UiSection, ctx: ImportContext): Promise<PlanItem[]> {
+    return planNamespaceItems(data.namespaces, 'ui', ctx);
+  }
+
+  async applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult> {
+    return applyNamespaceItem(item, 'ui', ctx);
+  }
+
+  async validate(data: UiSection, msg: MsgFunc = zhMsg): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: msg('adapter.validate.object', { subject: 'ui' }), severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
+    }
+    if (data.namespaces === null || typeof data.namespaces !== 'object') {
+      issues.push({ path: 'namespaces', message: msg('adapter.validate.missingObject', { subject: 'namespaces' }), severity: 'error' });
+    }
+    if (data.uiMigrationNotes !== undefined && !Array.isArray(data.uiMigrationNotes)) {
+      issues.push({ path: 'uiMigrationNotes', message: msg('adapter.validate.array', { subject: 'uiMigrationNotes' }), severity: 'error' });
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}

package/src/adapters/workspaces.test.ts

@@ -0,0 +1,106 @@
+/**
+ * workspaces adapter 测试：绝对路径导出、Create/Skip/Conflict + PathMapping 项、
+ * applyItem 写 record（PathMapper 先行后的映射数据）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { WorkspacesAdapter } from './workspaces.ts';
+import { makeContext, makeImportContext } from './test-helpers.ts';
+import { applyPrefixMappings } from '../utils/paths.ts';
+import type { WorkspacesSection } from '../schema/types.ts';
+import type { PlanItem } from '../core/types.ts';
+
+test('workspaces: 导出 records（含绝对路径）', async () => {
+  const ctx = makeContext('win32', 'C:\\Users\\alice');
+  ctx.workspace.records.set('ws-ops', {
+    id: 'ws-ops', path: 'C:\\Users\\alice\\projects\\ops', title: 'OpsFlow', sessionIds: [],
+  });
+  const adapter = new WorkspacesAdapter();
+  const out = await adapter.export(ctx, { includeSecrets: false });
+  assert.equal(out.data.workspaces.length, 1);
+  assert.equal(out.data.workspaces[0]?.path, 'C:\\Users\\alice\\projects\\ops');
+  assert.equal(out.counts.workspaces, 1);
+  const v = await adapter.validate(out.data);
+  assert.equal(v.valid, true);
+});
+
+test('workspaces: analyzeImport 生成 Create + PathMapping（绝对路径）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.workspace.records.set('ws-ops', {
+    id: 'ws-ops', path: 'C:\\Users\\alice\\projects\\ops', title: 'OpsFlow', sessionIds: [],
+  });
+  const adapter = new WorkspacesAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['workspaces', exported.data]]);
+
+  const dst = makeContext('linux', '/home/bob');
+  const items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+  assert.equal(items.length, 2);
+  const create = items.find((i) => i.id === 'workspace:ws-ops');
+  const pathItem = items.find((i) => i.id === 'workspace:ws-ops:path');
+  assert.equal(create?.kind, 'Create');
+  assert.equal(pathItem?.kind, 'PathMapping');
+  assert.deepEqual(pathItem?.pathMapping?.appliesTo, ['workspaces']);
+  assert.equal(pathItem?.pathMapping?.oldPrefix, 'C:\\Users\\alice\\projects\\ops');
+});
+
+test('workspaces: applyItem 写入映射后数据（PathMapper 先行）', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.workspace.records.set('ws-ops', {
+    id: 'ws-ops', path: 'C:\\Users\\alice\\projects\\ops', title: 'OpsFlow', sessionIds: [],
+  });
+  const adapter = new WorkspacesAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+
+  // 模拟 PathMapper：把映射应用到 sections
+  const mappedData = applyPrefixMappings(exported.data, [
+    { oldPrefix: 'C:\\Users\\alice', newPrefix: '/home/bob', appliesTo: ['workspaces'] },
+  ]) as WorkspacesSection;
+  assert.equal(mappedData.workspaces[0]?.path, '/home/bob/projects/ops');
+
+  const sections = new Map([['workspaces', mappedData]]);
+  const dst = makeContext('linux', '/home/bob');
+  const items = await adapter.analyzeImport(mappedData, makeImportContext(dst, sections));
+  const create = items.find((i) => i.id === 'workspace:ws-ops') as PlanItem;
+  const r = await adapter.applyItem(create, makeImportContext(dst, sections));
+  assert.equal(r.ok, true);
+  const rec = dst.workspace.records.get('ws-ops');
+  assert.ok(rec);
+  assert.equal(rec.path, '/home/bob/projects/ops', '写入的是映射后路径');
+
+  // PathMapping 项 applyItem 无副作用
+  const pathItem = items.find((i) => i.id === 'workspace:ws-ops:path') as PlanItem;
+  const r2 = await adapter.applyItem(pathItem, makeImportContext(dst, sections));
+  assert.equal(r2.ok, true);
+
+  // 幂等
+  const items2 = await adapter.analyzeImport(mappedData, makeImportContext(dst, sections));
+  assert.equal(items2.find((i) => i.id === 'workspace:ws-ops')?.kind, 'Skip');
+});
+
+test('workspaces: applyItem 写入失败（路径 realpath ENOENT）→ warning 非致命，不抛错', async () => {
+  const src = makeContext('win32', 'C:\\Users\\alice');
+  src.workspace.records.set('ws-ops', {
+    id: 'ws-ops', path: 'C:\\Users\\alice\\projects\\ops', title: 'OpsFlow', sessionIds: [],
+  });
+  const adapter = new WorkspacesAdapter();
+  const exported = await adapter.export(src, { includeSecrets: false });
+  const sections = new Map([['workspaces', exported.data]]);
+  const dst = makeContext('linux', '/home/bob');
+  // 模拟目标端工作区服务对不存在路径 realpath 失败（dsh-workspace 真实行为）
+  const original = dst.workspace.writeRecord.bind(dst.workspace);
+  dst.workspace.writeRecord = async () => {
+    throw new Error("ENOENT: no such file or directory, realpath '/home/bob/projects/ops'");
+  };
+  try {
+    const items = await adapter.analyzeImport(exported.data, makeImportContext(dst, sections));
+    const create = items.find((i) => i.id === 'workspace:ws-ops') as PlanItem;
+    const r = await adapter.applyItem(create, makeImportContext(dst, sections));
+    assert.equal(r.ok, false, '写入失败');
+    assert.equal(r.warning, true, '应为非致命警告（§34.17：不拖垮整体导入）');
+    assert.match(r.message ?? '', /未能写入|realpath/);
+  } finally {
+    dst.workspace.writeRecord = original;
+  }
+});
+

package/src/adapters/workspaces.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 { zhMsg } from '../core/messages.ts';
+import type { MsgFunc } from '../core/messages.ts';
+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 msg = ctx.msg;
+    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: msg('adapter.workspaceCreate', { title: rec.title ?? rec.id, path: rec.path }), severity: 'info',
+          target: { adapter: 'workspaces', ref: rec.id },
+        });
+      } else if (isDeepStrictEqual(existing, rec)) {
+        items.push({ id, kind: 'Skip', adapter: 'workspaces', description: msg('adapter.workspaceSame', { id: rec.id }), severity: 'info' });
+      } else {
+        items.push({
+          id, kind: 'Conflict', adapter: 'workspaces',
+          description: msg('adapter.workspaceDiff', { id: 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: msg('adapter.workspacePathMapping', { path: 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: ctx.msg('adapter.missingTargetRef') };
+    const data = ctx.sections.get('workspaces') as WorkspacesSection | undefined;
+    const rec = data?.workspaces.find((r) => r.id === ref);
+    if (!rec) return { ok: false, message: ctx.msg('adapter.workspaceMissing', { ref }) };
+    try {
+      await ctx.target.workspace.writeRecord(rec);
+      return { ok: true };
+    } catch (err) {
+      // 目标端无法写入（如路径 realpath 失败/目录不存在）→ 非致命警告（§34.17），
+      // 不触发整体回滚——否则一个失效路径会拖垮已成功导入的其余配置。
+      const reason = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false,
+        warning: true,
+        message: ctx.msg('adapter.workspaceWriteFailed', { ref, msg: reason }),
+      };
+    }
+  }
+
+  async validate(data: WorkspacesSection, msg: MsgFunc = zhMsg): Promise<ValidationResult> {
+    const issues: ValidationResult['issues'] = [];
+    if (data === null || typeof data !== 'object') {
+      return { valid: false, issues: [{ path: '$', message: msg('adapter.validate.object', { subject: 'workspaces' }), severity: 'error' }] };
+    }
+    if (data.version !== 1) {
+      issues.push({ path: 'version', message: msg('adapter.validate.version', { value: String(data.version) }), severity: 'error' });
+    }
+    if (!Array.isArray(data.workspaces)) {
+      issues.push({ path: 'workspaces', message: msg('adapter.validate.array', { subject: '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: msg('adapter.validate.workspaceIdentity'), severity: 'error' });
+        }
+      }
+    }
+    return { valid: issues.filter((i) => i.severity === 'error').length === 0, issues };
+  }
+}

package/src/client/ConfigManagerSection.tsx

@@ -0,0 +1,90 @@
+/**
+ * Config Manager 设置页（settings.section 入口）—— Workbench Shell。
+ * 宽读法改造：仅保留「远程同步」单一标签页。
+ */
+import { useEffect, useState, useSyncExternalStore } from 'react'
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ConfigManagerSectionInjected, TranslateNS } from './client-types.ts'
+import type { ServiceStatus } from './api.ts'
+import { runStore } from './run-store.ts'
+import { SyncSettingsView } from './sync/SyncSettingsView.tsx'
+import { MODAL_ROOT_ID } from './common/Modal.tsx'
+import { StatusDot } from './common/ui.tsx'
+import { ToastViewport } from './common/ToastViewport.tsx'
+import css from './config-manager.module.css'
+
+export type ConfigManagerSectionProps =
+  & PropsRuntime<'settings.section'>
+  & ConfigManagerSectionInjected
+  & { t: TranslateNS<'config-manager'> }
+
+/** 一级导航（宽读法：仅保留同步页）。 */
+const NAV_ITEMS = [
+  { id: 'sync' as const, label: 'nav.sync' },
+]
+
+export function ConfigManagerSection({ api, syncApi, syncT, t }: ConfigManagerSectionProps) {
+  const state = useSyncExternalStore(runStore.subscribe, runStore.getSnapshot)
+
+  /* ---------------- 状态栏版本（挂载时取一次；失败隐藏） ---------------- */
+  const [version, setVersion] = useState<ServiceStatus | null>(null)
+  useEffect(() => {
+    let cancelled = false
+    api.status().then(
+      (s) => { if (!cancelled) setVersion(s) },
+      () => { /* 版本信息失败不影响功能 */ },
+    )
+    return () => { cancelled = true }
+  }, [api])
+
+  /* ---------------- 状态栏数据 ---------------- */
+  const runningCount = state.sync.busy !== null ? 1 : 0
+  const statusKind: 'ok' | 'info' | 'error' = runningCount > 0 ? 'info' : 'ok'
+  const statusText = runningCount > 0
+    ? t('shell.status.running', { count: String(runningCount) })
+    : t('shell.status.idle')
+
+  return (
+    <div className={css.section} id={MODAL_ROOT_ID}>
+      {/* 顶部导航条：页签 */}
+      <nav className={css.shellNav} aria-label={t('section.label')}>
+        <div className={css.navStrip} role="tablist">
+          {NAV_ITEMS.map((item) => (
+            <button
+              key={item.id}
+              type="button"
+              role="tab"
+              aria-selected={true}
+              data-active=""
+              className={css.navTab}
+            >
+              {t(item.label as Parameters<TranslateNS<'config-manager'>>[0])}
+            </button>
+          ))}
+        </div>
+      </nav>
+
+      {/* 页面主体（独立滚动） */}
+      <main className={css.shellMain}>
+        <div className={css.pagePad}>
+          <SyncSettingsView api={syncApi} t={syncT} />
+        </div>
+      </main>
+
+      {/* 底部状态栏：运行状态 + 版本 */}
+      <footer className={css.statusBar}>
+        <StatusDot kind={statusKind} pulse={runningCount > 0} />
+        <span className={css.statusText}>{statusText}</span>
+        <span className={css.statusSpacer} />
+        {version !== null && (
+          <span className={css.statusMeta}>
+            {t('shell.version', { plugin: version.pluginVersion, dsh: version.dshVersion })}
+          </span>
+        )}
+      </footer>
+
+      {/* 全局通知视口（右下角堆叠） */}
+      <ToastViewport t={t} />
+    </div>
+  )
+}

package/src/client/api.ts

@@ -0,0 +1,66 @@
+/**
+ * Config Manager 浏览器半 API 客户端 —— 精简版（仅保留 status 与通用 API 错误类）。
+ * 远程同步端点由 ./sync/sync-api.ts 的 SyncApi 承载。
+ */
+import { zhUiT, type UiT } from '../ui/i18n.ts'
+
+/** Host 半健康检查响应（plugin 版本 / DSH 版本 / 平台，用于主页横幅与兼容性说明） */
+export interface ServiceStatus {
+  ready: boolean
+  pluginVersion: string
+  dshVersion: string
+  platform: string
+  arch: string
+  homeDir?: string
+  profile?: string
+  profileManifestReadable?: boolean
+  installedPluginCount?: number
+  installedPluginNames?: string[]
+  bundles?: string[]
+}
+
+export const CONFIG_MANAGER_API = {
+  status: '/api/dsh-config-manager/status',
+} as const
+
+/** 携带路由 JSON error 消息的错误类型 */
+export class ConfigManagerApiError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ConfigManagerApiError'
+  }
+}
+
+async function readJson<T>(response: Response, t: UiT): Promise<T> {
+  const notMountedMessage = t('error.notMounted')
+  let body: unknown
+  try {
+    body = await response.json()
+  } catch {
+    if (response.status === 404) throw new ConfigManagerApiError(notMountedMessage)
+    throw new ConfigManagerApiError(t('error.httpInvalidJson', { status: String(response.status) }))
+  }
+  if (!response.ok) {
+    const message =
+      typeof body === 'object' && body !== null && typeof (body as { error?: unknown }).error === 'string'
+        ? (body as { error: string }).error
+        : response.status === 404
+          ? notMountedMessage
+          : `HTTP ${response.status}`
+    throw new ConfigManagerApiError(message)
+  }
+  return body as T
+}
+
+export class ConfigManagerApi {
+  public readonly t: UiT
+
+  constructor(t: UiT = zhUiT) {
+    this.t = t
+  }
+
+  async status(): Promise<ServiceStatus> {
+    const response = await fetch(CONFIG_MANAGER_API.status)
+    return readJson<ServiceStatus>(response, this.t)
+  }
+}

package/src/client/client-types.ts

@@ -0,0 +1,18 @@
+/**
+ * Client 半的类型集中出口：把对 @deepseek-ai 运行时包的类型依赖收敛到本文件，
+ * 其余组件只从 `../client-types.ts` 引用，避免类型散落与误用值导入。
+ */
+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 }
+
+/** 本插件 Client 半的注入业务面：每个 settings.section 注册项都拿到同一个 api 实例 */
+export interface ConfigManagerSectionInjected {
+  api: import('./api.ts').ConfigManagerApi
+  /** 远程同步 API */
+  syncApi: import('./sync/sync-api.ts').SyncApi
+  /** 远程同步 locale（config-manager-sync 命名空间） */
+  syncT: import('@deepseek-ai/dsh-client-ui-slots').TranslateNS<'config-manager-sync'>
+}

package/src/client/common/ErrorBanner.tsx

@@ -0,0 +1,73 @@
+/**
+ * 可操作错误展示（规范 §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 { zhUiT, type UiT } from '../../ui/i18n.ts'
+import { Button, Spinner } from './ui.tsx'
+import { ArrowRightIcon } from './Icon.tsx'
+import css from '../config-manager.module.css'
+
+export interface ErrorBannerProps {
+  /** 任意未知错误（Error / 字符串 / API 错误） */
+  error: unknown
+  /** 可重试时显示的重试按钮（缺省不显示） */
+  onRetry?: () => void
+  /** 重试中的 loading 态 */
+  retrying?: boolean
+  /** 展示层翻译器（缺省 zh；ErrorBanner 为通用组件，不绑定 settings 命名空间字典） */
+  t?: UiT
+}
+
+/**
+ * 错误横幅：toActionableError 解析为标题 + 原因 + 建议动作，
+ * 文本在渲染前再经 redact() 兜底（双保险），Reason 以等宽块展示。
+ * 重试按钮：进行中（retrying）时显示 Spinner 并禁用（防重复点击）。
+ */
+export function ErrorBanner({ error, onRetry, retrying, t = zhUiT }: 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}><ArrowRightIcon size={13} /></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} loading={retrying === true}>
+            {retrying === true ? <Spinner /> : t('commonRetry')}
+          </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))
+}