dsh-config-manager 0.1.12 → 0.1.13

package/src/cli/index.ts

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+/**
+ * dsh-config-manager CLI（M3，criterion m3-cli-works）：
+ * 离线快照列表与恢复命令，零 DSH 运行时依赖（仅 node 内置 + 本项目 core 引擎，
+ * 引擎本身也只依赖 node 内置；绝不 import @deepseek-ai/*，peerDependencies 缺失也能跑）。
+ *
+ * 子命令：
+ *   snapshots [--data-dir <dir>]         列出快照（listSnapshots）
+ *   restore [--id <uuid>] [--dry-run]    恢复到导入前状态（planRestore 预览 / restore 执行）
+ *           [--data-dir <dir>] [--profile <name>] [--settings <path>]
+ *   --help | -h                           显示用法
+ *
+ * 缺省数据目录 = $DSH_HOME/dsh-config-manager/snapshots（$DSH_HOME 缺省 ~/.dsh）。
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  listSnapshots, planRestore, restore,
+  type RestorePlan, type RestoreReport, type SnapshotMeta,
+} from '../core/restore.ts';
+
+/* ------------------------------------------------------------ 参数解析（纯函数） */
+
+export type CliCommand = 'snapshots' | 'restore' | 'help';
+
+export interface CliOptions {
+  command: CliCommand;
+  /** --data-dir：快照数据目录覆盖 */
+  dataDir?: string;
+  /** --id：目标快照 id（restore 缺省取最近非 rolled-back） */
+  id?: string;
+  /** --dry-run：只打印计划 */
+  dryRun: boolean;
+  /** --profile：管理的 DSH profile（缺省 web） */
+  profile: string;
+  /** --settings：覆盖 settings 文件路径 */
+  settings?: string;
+}
+
+export type ParseResult = { ok: true; options: CliOptions } | { ok: false; error: string };
+
+const VALUE_FLAGS = new Map<string, 'dataDir' | 'id' | 'profile' | 'settings'>([
+  ['--data-dir', 'dataDir'],
+  ['--id', 'id'],
+  ['--profile', 'profile'],
+  ['--settings', 'settings'],
+]);
+
+/** 仅 restore 子命令允许的参数 */
+const RESTORE_ONLY_FLAGS = new Set(['--id', '--dry-run', '--profile', '--settings']);
+
+/** 解析 CLI 参数（纯函数；help 返回 command:'help'，未知/缺值返回错误） */
+export function parseCli(argv: readonly string[]): ParseResult {
+  const command = argv[0];
+  if (command === undefined) return { ok: false, error: '缺少子命令 / missing subcommand' };
+  if (command === '--help' || command === '-h' || command === 'help') {
+    return { ok: true, options: { command: 'help', dryRun: false, profile: 'web' } };
+  }
+  if (command !== 'snapshots' && command !== 'restore') {
+    return { ok: false, error: `未知子命令 / unknown subcommand: ${command}` };
+  }
+
+  const options: CliOptions = { command, dryRun: false, profile: 'web' };
+  const rest = argv.slice(1);
+  for (let i = 0; i < rest.length; i += 1) {
+    const flag = rest[i]!;
+    if (flag === '--help' || flag === '-h') {
+      return { ok: true, options: { ...options, command: 'help' } };
+    }
+    if (command === 'snapshots' && RESTORE_ONLY_FLAGS.has(flag)) {
+      return { ok: false, error: `snapshots 子命令不支持参数 / flag not allowed here: ${flag}` };
+    }
+    if (flag === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    const key = VALUE_FLAGS.get(flag);
+    if (key === undefined) {
+      return { ok: false, error: `未知参数 / unknown flag: ${flag}` };
+    }
+    const value = rest[i + 1];
+    if (value === undefined || value === '' || value.startsWith('-')) {
+      return { ok: false, error: `参数 ${flag} 缺少值 / missing value for ${flag}` };
+    }
+    options[key] = value;
+    i += 1;
+  }
+  return { ok: true, options };
+}
+
+/** $DSH_HOME：环境变量优先，缺省 ~/.dsh（dsh-home-paths 的简化规则，CLI 零依赖版） */
+export function resolveDshHome(env: Record<string, string | undefined> = process.env): string {
+  const fromEnv = env.DSH_HOME;
+  if (fromEnv !== undefined && fromEnv !== '') return fromEnv;
+  return path.join(os.homedir(), '.dsh');
+}
+
+/** 快照数据目录：--data-dir 覆盖优先，缺省 $DSH_HOME/dsh-config-manager/snapshots */
+export function resolveDataDir(flag: string | undefined, env: Record<string, string | undefined> = process.env): string {
+  if (flag !== undefined && flag !== '') return flag;
+  return path.join(resolveDshHome(env), 'dsh-config-manager', 'snapshots');
+}
+
+/** 快照 id 校验：拒绝路径分隔符/保留名（防 join 越界） */
+export function validateSnapshotId(id: string): string {
+  if (id === '' || id === '.' || id === '..' || id.includes('/') || id.includes('\\')) {
+    throw new Error(`非法快照 id / invalid snapshot id: ${JSON.stringify(id)}`);
+  }
+  return id;
+}
+
+/** 缺省快照选择：metas 已按 createdAt 倒序，取第一个 status !== 'rolled-back' */
+export function pickDefaultSnapshotId(metas: readonly SnapshotMeta[]): string | null {
+  const eligible = metas.find((m) => m.status !== 'rolled-back');
+  return eligible?.id ?? null;
+}
+
+/* ------------------------------------------------------------ 输出 */
+
+export interface CliIo {
+  log: (s: string) => void;
+  error: (s: string) => void;
+}
+
+const defaultIo: CliIo = { log: (s) => console.log(s), error: (s) => console.error(s) };
+
+/* ------------------------------------------------------------ 执行 */
+
+export function printUsage(io: CliIo = defaultIo): void {
+  io.log(
+    [
+      'dsh-config-manager — DSH Config Manager 离线恢复工具 / offline restore tool',
+      '',
+      '用法 / Usage:',
+      '  dsh-config-manager snapshots [--data-dir <dir>]',
+      '      列出快照 / list snapshots',
+      '  dsh-config-manager restore [--id <uuid>] [--dry-run] [--data-dir <dir>]',
+      '                            [--profile <name>] [--settings <path>]',
+      '      恢复到导入前状态 / restore to pre-import state（--dry-run 只打印计划）',
+      '  dsh-config-manager --help | -h',
+      '      显示帮助 / show help',
+      '',
+      '选项 / Options:',
+      '  --data-dir <dir>   快照数据目录（缺省 $DSH_HOME/dsh-config-manager/snapshots）',
+      '  --id <uuid>        目标快照 id（缺省取最近一个非 rolled-back 快照）',
+      '  --dry-run          只打印恢复计划，不执行 / print plan only',
+      '  --profile <name>   管理的 DSH profile（缺省 web）',
+      '  --settings <path>  覆盖 settings 文件路径',
+    ].join('\n'),
+  );
+}
+
+function printSnapshots(metas: SnapshotMeta[], io: CliIo): void {
+  if (metas.length === 0) {
+    io.log('（无快照 / no snapshots）');
+    return;
+  }
+  const headers = ['ID', 'CREATED_AT', 'SOURCE_ZIP', 'STATUS', 'ENTRIES', 'HOST_FILES', 'PLUGINS'];
+  const rows = metas.map((m) => [
+    m.id, m.createdAt, m.sourceZip, m.status ?? 'unknown',
+    String(m.entryCount), String(m.hostFileBackupCount), String(m.beforePluginCount),
+  ]);
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i]!.length)));
+  const line = (cells: string[]): string => cells.map((c, i) => c.padEnd(widths[i]!)).join('  ').trimEnd();
+  io.log(line(headers));
+  for (const r of rows) io.log(line(r));
+}
+
+function printPlan(plan: RestorePlan, io: CliIo): void {
+  io.log(`快照 / snapshot: ${plan.snapshotId}`);
+  io.log(`创建时间 / createdAt: ${plan.createdAt}`);
+  io.log(`来源备份 / sourceZip: ${plan.sourceZip}`);
+  io.log(`插件基线 / plugin baseline: ${plan.pluginBaselineConfirmed ? '已确认 / confirmed' : '缺失 / missing（不计划插件卸载）'}`);
+  io.log(`动作计划 / plan（${plan.actions.length} 项 actions）：`);
+  for (const a of plan.actions) {
+    const detail = a.detail !== undefined ? `（${a.detail}）` : '';
+    io.log(`  [${a.kind.padEnd(14)}] ${a.description}${detail}`);
+  }
+  const s = plan.summary;
+  io.log(
+    `汇总 / summary: 整文件还原 ${s.hostFileRestores} · 整文件删除 ${s.hostFileRemoves}`
+    + ` · 插件卸载 ${s.pluginRemoves} · 文件还原 ${s.fileRestores} · 文件删除 ${s.fileRemoves}`
+    + ` · 凭据提示 ${s.credentialHints} · 跳过 ${s.skips}`,
+  );
+}
+
+function printReport(report: RestoreReport, io: CliIo): void {
+  io.log(`恢复完成 / restore done — 快照 ${report.snapshotId}`);
+  io.log(`已还原 / restored（${report.restored.length}）：`);
+  for (const r of report.restored) io.log(`  - ${r}`);
+  io.log(`已卸载插件 / removed plugins（${report.removedPlugins.length}）：`);
+  for (const p of report.removedPlugins) io.log(`  - ${p}`);
+  io.log(`需人工处理 / manual hints（${report.manualHints.length}）：`);
+  for (const h of report.manualHints) io.log(`  - ${h}`);
+  io.log(`失败 / failed（${report.failed.length}）：`);
+  for (const f of report.failed) io.log(`  - ${f.item}: ${f.reason}`);
+  io.log(`跳过 / skipped（${report.skipped.length}）：`);
+  for (const sk of report.skipped) io.log(`  - ${sk}`);
+}
+
+/**
+ * CLI 主流程（io/env 可注入供测试）：
+ * snapshots → 列表；restore → dry-run 打印计划 / 执行并打印诚实报告；
+ * 失败项存在时 exit 1，否则 0。
+ */
+export async function runCli(
+  argv: readonly string[],
+  io: CliIo = defaultIo,
+  env: Record<string, string | undefined> = process.env,
+): Promise<number> {
+  const parsed = parseCli(argv);
+  if (!parsed.ok) {
+    io.error(parsed.error);
+    printUsage(io);
+    return 1;
+  }
+  const { options } = parsed;
+  if (options.command === 'help') {
+    printUsage(io);
+    return 0;
+  }
+
+  const dataDir = resolveDataDir(options.dataDir, env);
+
+  if (options.command === 'snapshots') {
+    const metas = await listSnapshots(dataDir);
+    printSnapshots(metas, io);
+    return 0;
+  }
+
+  // restore
+  let id = options.id;
+  if (id === undefined) {
+    const picked = pickDefaultSnapshotId(await listSnapshots(dataDir));
+    if (picked === null) {
+      io.error('没有可用快照（无快照或全部已回滚）/ no usable snapshot (none or all rolled-back)');
+      return 1;
+    }
+    id = picked;
+  }
+  try {
+    validateSnapshotId(id);
+  } catch (err) {
+    io.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  const snapshotDir = path.join(dataDir, id);
+  const restoreOptions = {
+    snapshotDir,
+    homeDir: resolveDshHome(env),
+    profile: options.profile,
+    settingsPath: options.settings,
+  };
+  if (options.dryRun) {
+    printPlan(await planRestore(restoreOptions), io);
+    return 0;
+  }
+  const report = await restore(restoreOptions);
+  printReport(report, io);
+  return report.failed.length > 0 ? 1 : 0;
+}
+
+/* 直接运行（bin / node src/cli/index.ts）时进入主流程；被 import（测试）时不自动执行 */
+const isDirectRun = process.argv[1] !== undefined
+  && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (isDirectRun) {
+  runCli(process.argv.slice(2))
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((err) => {
+      console.error(`dsh-config-manager 执行失败 / failed: ${err instanceof Error ? err.message : String(err)}`);
+      process.exitCode = 1;
+    });
+}

package/src/client/ConfigManagerSection.tsx

@@ -1,15 +1,21 @@
 /**
  * Config Manager 设置页（settings.section 入口的主页面容器）。
  *
- * owner props 由 settings shell 传入（close）；业务面（api）由注册时的
- * inject face 注入；t 由 locale seat 注入。内部两个主视图：
+ * 业务面（api）由注册时的 inject face 注入；t 由 locale seat 注入。
+ * 关闭按钮由 settings shell 自带，本页不再渲染。内部两个主视图：
  * Export（Quick/Custom）与 Import（九步向导）。
+ *
+ * m2：主视图 tab（view）与全部子视图状态统一由模块级 runStore 持有
+ * （sessionStorage 持久化 + 切 tab/关面板不重建控制器实例）；挂载时
+ * 经 GET /runs + 轮询 /progress 恢复进行中的 run（刷新/重开面板后）。
  */
-import { useState } from 'react'
+import { useEffect, useSyncExternalStore, useState } from 'react'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ConfigManagerSectionInjected, TranslateNS } from './client-types.ts'
+import { runStore, type MainView } from './run-store.ts'
 import { ExportView } from './export/ExportView.tsx'
 import { ImportWizardView } from './import/ImportWizardView.tsx'
+import { SnapshotsPanel } from './snapshots/SnapshotsPanel.tsx'
 import css from './config-manager.module.css'
 
 export type ConfigManagerSectionProps =
@@ -17,13 +23,31 @@ export type ConfigManagerSectionProps =
   & ConfigManagerSectionInjected
   & { t: TranslateNS<'config-manager'> }
 
-type MainView = 'export' | 'import'
-
 /**
- * 设置页容器：Export / Import 双视图切换。
+ * 设置页容器：Export / Import / Snapshots 三视图切换。
+ * Export/Import 状态在模块级 store（切 tab 不丢失）；快照恢复面板为低频显式
+ * 操作，其状态组件内自持（local state，不进 sessionStorage）。
  */
-export function ConfigManagerSection({ close, api, t }: ConfigManagerSectionProps) {
-  const [view, setView] = useState<MainView>('export')
+export function ConfigManagerSection({ api, t }: ConfigManagerSectionProps) {
+  const state = useSyncExternalStore(runStore.subscribe, runStore.getSnapshot)
+  const view = state.view
+  const [snapshotsOpen, setSnapshotsOpen] = useState(false)
+
+  // m2-resume：挂载时重新订阅进行中的 run（刷新 / 重开面板后服务端继续执行，
+  // 这里经 /runs 找回活跃 runId 再轮询 /progress）；卸载时停止轮询，重开再订阅。
+  useEffect(() => {
+    void runStore.resume(api)
+    return () => {
+      runStore.stopResume()
+    }
+  }, [api])
+
+  const setView = (next: MainView): void => {
+    setSnapshotsOpen(false)
+    runStore.patch({ view: next })
+  }
+
+  const activeTab: MainView | 'snapshots' = snapshotsOpen ? 'snapshots' : view
 
   return (
     <div className={css.section}>
@@ -32,8 +56,8 @@ export function ConfigManagerSection({ close, api, t }: ConfigManagerSectionProp
           <button
             type="button"
             role="tab"
-            aria-selected={view === 'export'}
-            data-active={view === 'export' ? '' : undefined}
+            aria-selected={activeTab === 'export'}
+            data-active={activeTab === 'export' ? '' : undefined}
             className={css.viewTab}
             onClick={() => { setView('export') }}
           >
@@ -42,18 +66,29 @@ export function ConfigManagerSection({ close, api, t }: ConfigManagerSectionProp
           <button
             type="button"
             role="tab"
-            aria-selected={view === 'import'}
-            data-active={view === 'import' ? '' : undefined}
+            aria-selected={activeTab === 'import'}
+            data-active={activeTab === 'import' ? '' : undefined}
             className={css.viewTab}
             onClick={() => { setView('import') }}
           >
             {t('view.import')}
           </button>
+          <button
+            type="button"
+            role="tab"
+            aria-selected={activeTab === 'snapshots'}
+            data-active={snapshotsOpen ? '' : undefined}
+            className={css.viewTab}
+            onClick={() => { setSnapshotsOpen(true) }}
+          >
+            {t('view.snapshots')}
+          </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} />}
+        {snapshotsOpen
+          ? <SnapshotsPanel api={api} t={t} />
+          : view === 'export' ? <ExportView api={api} t={t} /> : <ImportWizardView api={api} t={t} />}
       </div>
     </div>
   )

package/src/client/api.ts

@@ -9,12 +9,14 @@
  * 端点契约（Host 半 `src/index.ts` 按此实现，见 CLIENT_DEPENDENCIES.md 的接口说明）：
  * ```
  * GET  /api/dsh-config-manager/status             → ServiceStatus        （健康/版本检查）
- * POST /api/dsh-config-manager/export             → ExportResponse       （body: ExportOptions）
+ * POST /api/dsh-config-manager/export             → ExportResponse       （body: ExportOptions；响应含 runId）
  * 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 }）
+ * POST /api/dsh-config-manager/execute            → ImportResult         （body: { zipPath, plan, opts }；响应含 runId）
+ * GET  /api/dsh-config-manager/progress?runId=…   → RunState             （run 实时状态：轮询/刷新恢复）
+ * GET  /api/dsh-config-manager/runs               → RunState[]           （活跃 run 列表）
  * ```
  * 安全约束：
  *  - 所有响应/错误文本在进入 UI 前经 `redact()`（见 common/ErrorBanner.tsx）；
@@ -24,6 +26,8 @@
 
 import type { ImportAnalysis, ImportDecisions, ImportPlan, ImportResult } from '../core/types.ts';
 import type { ExportOptions, ExportReport } from '../core/types.ts';
+import type { RestorePlan, RestoreReport, SnapshotMeta } from '../core/restore.ts';
+import type { RunState } from '../core/run-registry.ts';
 import type { Manifest } from '../schema/types.ts';
 
 /** Host 半健康检查响应（plugin 版本 / DSH 版本 / 平台，用于主页横幅与兼容性说明） */
@@ -35,11 +39,13 @@ export interface ServiceStatus {
   arch: string;
 }
 
-/** export 端点响应（对齐 ExportFlow 的 ExportRunResult 前半部分） */
+/** export 端点响应（对齐 ExportFlow 的 ExportRunResult 前半部分；runId 为 m1 run 注册表标识） */
 export interface ExportResponse {
   zipPath: string;
   manifest: Manifest;
   report: ExportReport;
+  /** m1：本次导出 run 的 id（可用 /progress 查询状态 / 刷新恢复） */
+  runId: string;
 }
 
 /** upload 端点响应：Host 把用户上传的 ZIP 存入受控临时目录，返回可被 analyze/plan/execute 引用的路径 */
@@ -63,6 +69,13 @@ export interface ExecutePayload {
   };
 }
 
+/** restore 端点响应：dryRun=true 返回 plan；执行返回 report（与 CLI 一致的诚实报告） */
+export interface RestoreResponse {
+  dryRun: boolean;
+  plan?: RestorePlan;
+  report?: RestoreReport;
+}
+
 /** 路由族常量（集中管理，与 Host 半的路由前缀保持一致） */
 export const CONFIG_MANAGER_API = {
   base: '/api/dsh-config-manager',
@@ -73,6 +86,10 @@ export const CONFIG_MANAGER_API = {
   analyze: '/api/dsh-config-manager/analyze',
   plan: '/api/dsh-config-manager/plan',
   execute: '/api/dsh-config-manager/execute',
+  progress: '/api/dsh-config-manager/progress',
+  runs: '/api/dsh-config-manager/runs',
+  snapshots: '/api/dsh-config-manager/snapshots',
+  restore: '/api/dsh-config-manager/restore',
 } as const;
 
 /** 导出请求超时（ms）：与 Host 半 ROUTE_TIMEOUT_MS 对齐，防止宿主卡死时 UI 无限等待 */
@@ -271,7 +288,7 @@ export class ConfigManagerApi {
     zipPath: string,
     plan: ImportPlan,
     opts: { confirm: boolean; secretInputs?: Record<string, string>; rollbackOnError: boolean },
-  ): Promise<ImportResult> {
+  ): Promise<ImportResult & { runId: string }> {
     const payload: ExecutePayload = {
       zipPath,
       plan,
@@ -286,6 +303,37 @@ export class ConfigManagerApi {
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify(payload),
     });
-    return readJson<ImportResult>(response);
+    return readJson<ImportResult & { runId: string }>(response);
+  }
+
+  // ------------------------------------------------------------- run 进度
+  /** m1：查询单个 run 的实时状态（执行中轮询 / 刷新恢复用；404 = 已过保留期或不存在） */
+  async progress(runId: string): Promise<RunState> {
+    const response = await fetch(CONFIG_MANAGER_API.progress + query({ runId }));
+    return readJson<RunState>(response);
+  }
+
+  /** m1：列出当前活跃（running）的 run（刷新后重新订阅进行中任务的入口） */
+  async runs(): Promise<RunState[]> {
+    const response = await fetch(CONFIG_MANAGER_API.runs);
+    return readJson<RunState[]>(response);
+  }
+
+  // ------------------------------------------------------- 快照恢复（M4）
+  /** 列出全部快照元信息（createdAt 倒序；含 status/条目数/宿主文件数/插件数） */
+  async snapshots(): Promise<SnapshotMeta[]> {
+    const response = await fetch(CONFIG_MANAGER_API.snapshots);
+    const body = await readJson<{ snapshots: SnapshotMeta[] }>(response);
+    return body.snapshots;
+  }
+
+  /** 快照恢复：dryRun=true 只取动作计划（零写入）；false 执行并返回诚实报告 */
+  async restoreSnapshot(snapshotId: string, dryRun: boolean): Promise<RestoreResponse> {
+    const response = await fetch(CONFIG_MANAGER_API.restore, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ snapshotId, dryRun }),
+    });
+    return readJson<RestoreResponse>(response);
   }
 }

package/src/client/client-types.ts

@@ -15,12 +15,6 @@ 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/ProgressBar.tsx

@@ -1,44 +1,56 @@
 /**
- * 进度条（规范 §29，绑 src/ui/progress.ts）。
+ * 进度条（规范 §29 + m3 真实进度）。
  *
- * 控制器（ExportFlow / ImportWizard）在调用 core 前后发出 ProgressEvent，
- * 本组件按 stage 文案 + step/total 渲染进度条；未知阶段回退显示 id 本身。
+ * 数据流：
+ *  - 控制器（ExportFlow / ImportWizard）onProgress 发出普通 ProgressEvent
+ *    （阶段文案 + step/total），走兼容路径；
+ *  - m3：store 经 /runs + /progress 轮询得到的 RunState 映射为 RunProgress
+ *    （额外携带 section/sectionTotal/item/itemTotal/detail），渲染为
+ *    「分区徽章（settings · 3/12）+ 内部计数徽章（plugins · 6/18）+ 当前项名」。
+ *
+ * 所有换算逻辑在 progress-view.ts 的 computeProgressView()（纯函数，可单测）；
+ * 本组件只做渲染。未知阶段回退显示 id 本身。
  */
-import { stageText } from '../../ui/progress.ts'
-import type { ProgressEvent } from '../../ui/types.ts'
+import { computeProgressView } from './progress-view.ts'
+import type { RunProgress } from './progress-view.ts'
 import css from '../config-manager.module.css'
 
 export interface ProgressBarProps {
-  /** 当前阶段事件（null = 未开始） */
-  event: ProgressEvent | null
+  /** 当前进度事件（null = 未开始）；普通 ProgressEvent 亦兼容 */
+  event: RunProgress | 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) : ''
+  const view = computeProgressView(event)
 
   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>
+        <span className={css.progressLabel}>{view.label}</span>
+        {view.sectionBadge !== null && (
+          <span className={`${css.progressBadge} ${css.progressBadgeSection}`}>
+            {view.sectionBadge.label} · {view.sectionBadge.current}/{view.sectionBadge.total}
+          </span>
+        )}
+        {view.countBadge !== null && (
+          <span className={`${css.progressBadge} ${css.progressBadgeCount}`}>
+            {view.countBadge.label !== '' ? `${view.countBadge.label} · ` : ''}
+            {view.countBadge.current}/{view.countBadge.total}
+          </span>
         )}
-        {percent !== null && <span className={css.progressPercent}>{percent}%</span>}
+        {view.detail !== null && <span className={css.progressDetail}>{view.detail}</span>}
+        {view.percent !== null && <span className={css.progressPercent}>{view.percent}%</span>}
       </div>
       <div className={css.progressTrack}>
-        {percent !== null ? (
+        {view.percent !== null ? (
           <div
             className={`${css.progressBar} ${active ? '' : css.progressBarDone}`}
-            style={{ width: `${percent}%` }}
+            style={{ width: `${view.percent}%` }}
           />
         ) : (
           <div className={`${css.progressBar} ${css.progressIndeterminate}`} />

package/src/client/common/progress-view-edge.test.ts

@@ -0,0 +1,60 @@
+/**
+ * m4 测试补齐（任务 t4）：computeProgressView 边界补充。
+ *
+ * m3 主路径已由 progress-view.test.ts 覆盖（null/兼容路径/分区徽章/内部计数徽章/
+ * 冗余去重/未知阶段）；本文件补充未覆盖的判定分支：
+ *  - step/total 与 item/itemTotal 同时存在时百分比优先 step/total（文档优先级）；
+ *  - section 存在但 sectionTotal 为 0 → 无分区徽章（total 必须 >0）；
+ *  - itemTotal 为 0 → 无内部计数徽章且百分比回退不定态（除零防御）；
+ *  - section 有值但 item 为 null → 分区徽章不渲染（徽章需要 current 计数）；
+ *  - 百分比取整（Math.round，非截断）。
+ * 全部为纯函数断言，不改动 m3 业务代码。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { computeProgressView } from './progress-view.ts'
+import type { RunProgress } from './progress-view.ts'
+
+test('m3-render 边界: step/total 与 item/itemTotal 并存时百分比优先 step/total', () => {
+  // 若误用 item/itemTotal 会算出 25%（3/12）；文档行为是优先 step/total → 33%
+  const event: RunProgress = {
+    stage: 'exporting',
+    step: 1,
+    total: 3,
+    section: 'settings',
+    sectionTotal: 12,
+    item: 3,
+    itemTotal: 12,
+    detail: 'settings',
+  }
+  const view = computeProgressView(event)
+  assert.equal(view.percent, 33, '百分比取 step/total（1/3 → 33%）而非 item/itemTotal')
+  assert.deepEqual(view.sectionBadge, { label: 'settings', current: 3, total: 12 }, '徽章仍用分区计数')
+})
+
+test('m3-render 边界: sectionTotal 为 0 → 无分区徽章（total 必须 >0）', () => {
+  const view = computeProgressView({ stage: 'executing', section: 'plugins', sectionTotal: 0, item: 2, itemTotal: 10 })
+  assert.equal(view.sectionBadge, null, 'total=0 时不渲染分区徽章')
+  assert.deepEqual(view.countBadge, { label: 'plugins', current: 2, total: 10 }, '内部计数徽章不受影响')
+})
+
+test('m3-render 边界: itemTotal 为 0 → 无内部计数徽章且百分比不定态（除零防御）', () => {
+  const view = computeProgressView({ stage: 'executing', section: 'plugins', item: 0, itemTotal: 0, detail: 'x' })
+  assert.equal(view.countBadge, null, 'itemTotal=0 不渲染计数徽章')
+  assert.equal(view.percent, null, 'total=0 时百分比不定态（避免除零）')
+  assert.equal(view.detail, 'x', 'detail 与 section 不同时保留')
+})
+
+test('m3-render 边界: section 有值但 item 为 null → 分区徽章不渲染（徽章需 current）', () => {
+  const view = computeProgressView({ stage: 'executing', section: 'settings', sectionTotal: 5, item: null, itemTotal: 5 })
+  assert.equal(view.sectionBadge, null)
+  assert.equal(view.countBadge, null)
+  assert.equal(view.percent, null, '无 step/total 且 item null → 不定态')
+})
+
+test('m3-render 边界: 百分比取整（Math.round 而非截断）', () => {
+  assert.equal(computeProgressView({ stage: 'exporting', step: 1, total: 3 }).percent, 33)
+  assert.equal(computeProgressView({ stage: 'exporting', step: 2, total: 3 }).percent, 67)
+  assert.equal(computeProgressView({ stage: 'exporting', step: 1, total: 6 }).percent, 17)
+})