dsh-config-manager 0.1.12 → 0.1.13

package/src/core/run-progress.test.ts

@@ -0,0 +1,237 @@
+/**
+ * m4 测试补齐（任务 t4）：m1 真实进度埋点 —— Exporter onSection / Analyzer onItem。
+ *
+ * 背景：m1 在 core 侧加入进度埋点（exporter.ts onSection、analyzer.ts onItem，
+ * importer.ts 透传），Host 路由用它们更新 RunRegistry（/progress 轮询数据源，
+ * m2 store / m3 ProgressBar 徽章消费）。既有 tests/core/exporter.test.ts 与
+ * tests/core/importer.test.ts 未覆盖埋点的参数语义与「埋点失败不影响业务」的
+ * 容错保证，本文件补齐（仅新增测试，不改业务代码）。
+ *
+ * 覆盖（验收 m4-green）：
+ *  - Exporter.onSection：每导出一个选中分区前调用一次；index 从 1 起严格递增、
+ *    total=选中分区总数、section=adapter id；only 过滤时只对选中分区触发；
+ *    回调抛错不得中断导出（进度是尽力而为）；
+ *  - Analyzer.executeImportPlan onItem（经 Importer 透传）：每个计划项完成后调用；
+ *    index 1-based 递增、total=将执行计划项总数（含 skip 类信息项）、
+ *    status=该项实际状态（ok/skipped…）、detail=计划项 id；
+ *    冲突未解决（skipped）与缺失秘密（skipped）同样计数；
+ *    回调抛错不得中断导入执行。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { Exporter, type SectionProgress } from './exporter.ts'
+import { Importer } from './importer.ts'
+import type { PlanItemProgress } from './analyzer.ts'
+import { createAdapters } from '../adapters/index.ts'
+import { makeContext, MemSnapshotStore, type MockHostContext } from '../adapters/test-helpers.ts'
+import type { ImportPlan } from './types.ts'
+
+const NS = ['general', 'llm-deepseek']
+
+async function withTmp<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-cm-run-progress-'))
+  try {
+    return await fn(dir)
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true })
+  }
+}
+
+/** 最小源：settings(general + llm-deepseek 带 apiKeyEnv/secret 标记) + credentials
+ * （llm-deepseek 的 secret 标记使 credentialsStatus 分区产生 configured 凭据，
+ * 导入时成为 MissingSecret 补录占位 —— 与 tests/core/importer.test.ts 的 I-01 同款） */
+async function seedSource(ctx: MockHostContext): Promise<void> {
+  ctx.settings.ns.set('general', { value: { theme: 'dark', language: 'zh-CN' }, revision: 3, secrets: [] })
+  ctx.settings.ns.set('llm-deepseek', {
+    value: { apiKeyEnv: 'DEEPSEEK_API_KEY', baseURL: 'https://api.deepseek.com', model: 'deepseek-chat' },
+    revision: 5,
+    secrets: [{ path: ['apiKey'], set: true }],
+  })
+  ctx.credentials.values.set('DEEPSEEK_API_KEY', 'sk-super-secret-value-123')
+}
+
+async function exportFixture(src: MockHostContext, outPath: string): Promise<void> {
+  const adapters = createAdapters({ namespaces: NS })
+  await new Exporter({ ctx: src, adapters, now: () => new Date('2026-08-14T12:00:00.000Z') })
+    .export({ includeSecrets: false, outPath })
+}
+
+/** 与 Importer 默认参数一致的目标侧 importer */
+function makeImporter(dst: MockHostContext): Importer {
+  return new Importer({
+    ctx: dst,
+    adapters: createAdapters({ namespaces: NS }),
+    snapshotStore: new MemSnapshotStore(),
+  })
+}
+
+/* ================================================= Exporter onSection 埋点 */
+
+test('m1 埋点: onSection 每导出一个选中分区前调用（index 1-based 递增、total=选中数、section=adapter id）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const adapters = createAdapters({ namespaces: NS })
+    const selected = adapters.filter((a) => a.defaultIncluded).map((a) => a.id)
+    assert.ok(selected.length >= 2, '默认选中分区应 ≥2（本最小源至少 settings+credentialsStatus）')
+
+    const calls: SectionProgress[] = []
+    await new Exporter({
+      ctx: src,
+      adapters,
+      now: () => new Date('2026-08-14T12:00:00.000Z'),
+      onSection: (info) => { calls.push(info) },
+    }).export({ includeSecrets: false, outPath: path.join(dir, 'sections.zip') })
+
+    assert.equal(calls.length, selected.length, '每个选中分区都应触发一次 onSection')
+    calls.forEach((c, i) => {
+      assert.equal(c.index, i + 1, `index 从 1 起严格递增（第 ${i} 次调用）`)
+      assert.equal(c.total, selected.length, 'total=选中分区总数')
+      assert.equal(c.section, selected[i], 'section=当前 adapter id，顺序与导出顺序一致')
+    })
+  })
+})
+
+test('m1 埋点: only 过滤时只对选中分区触发（index/total 按选中集计算）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('linux', '/home/alice')
+    await seedSource(src)
+    const adapters = createAdapters({ namespaces: NS })
+    const only = ['settings', 'plugins'] as const
+
+    const calls: SectionProgress[] = []
+    await new Exporter({
+      ctx: src,
+      adapters,
+      now: () => new Date('2026-08-14T12:00:00.000Z'),
+      onSection: (info) => { calls.push(info) },
+    }).export({ includeSecrets: false, only: [...only], outPath: path.join(dir, 'only.zip') })
+
+    assert.equal(calls.length, only.length, '只对 only 中选中的分区触发')
+    assert.deepEqual(calls.map((c) => c.section), [...only], '触发顺序与 adapters 注册顺序一致')
+    for (const c of calls) {
+      assert.equal(c.total, only.length, 'total=only 过滤后的选中分区数')
+    }
+    assert.equal(calls[0]?.index, 1, 'only 集内 index 从 1 起')
+  })
+})
+
+test('m1 埋点: onSection 抛错不影响导出（进度是尽力而为）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const adapters = createAdapters({ namespaces: NS })
+    let calls = 0
+
+    const result = await new Exporter({
+      ctx: src,
+      adapters,
+      now: () => new Date('2026-08-14T12:00:00.000Z'),
+      onSection: (info) => {
+        calls += 1
+        if (calls === 1) throw new Error('埋点回调故障')
+      },
+    }).export({ includeSecrets: false, outPath: path.join(dir, 'resilient.zip') })
+
+    assert.ok(calls > 0, '埋点被触发过')
+    assert.ok(result.zipPath.endsWith('.zip'), '导出仍成功完成')
+    const stat = await fs.stat(result.zipPath)
+    assert.ok(stat.size > 0, 'ZIP 正常落盘')
+  })
+})
+
+/* ================================================= Analyzer onItem 埋点 */
+
+test('m1 埋点: onItem 每个计划项完成后调用（index 递增、total=计划项数、status/detail 正确）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const zipPath = path.join(dir, 'items.zip')
+    await exportFixture(src, zipPath)
+
+    const dst = makeContext('win32', 'C:\\Users\\bob')
+    dst.settings.registered.add('general')
+    dst.settings.registered.add('llm-deepseek')
+    const importer = makeImporter(dst)
+
+    const plan: ImportPlan = await importer.createImportPlan(zipPath, { strategy: 'merge', resolutions: {}, pathMappings: [] })
+    assert.ok(plan.items.length > 0, '计划应包含待执行项')
+
+    const calls: PlanItemProgress[] = []
+    const result = await importer.executeImportPlan(zipPath, plan, {
+      confirm: true,
+      onItem: (info) => { calls.push(info) },
+    })
+
+    assert.equal(result.ok, true, '导入成功')
+    assert.equal(calls.length, plan.items.length, '每个计划项都应触发一次 onItem')
+    calls.forEach((c, i) => {
+      assert.equal(c.index, i + 1, 'index 从 1 起严格递增')
+      assert.equal(c.total, calls.length, 'total=将执行计划项总数（含 skip 类信息项）')
+      assert.ok(
+        c.status === 'ok' || c.status === 'skipped' || c.status === 'warning' || c.status === 'failed',
+        `status 应为合法值，实际 ${c.status}`,
+      )
+      assert.ok(typeof c.detail === 'string' && c.detail !== '', 'detail=计划项 id（非敏感）')
+    })
+  })
+})
+
+test('m1 埋点: 冲突未解决（skipped）与缺失秘密（skipped）同样计数', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const zipPath = path.join(dir, 'conflict.zip')
+    await exportFixture(src, zipPath)
+
+    const dst = makeContext('win32', 'C:\\Users\\bob')
+    // 目标已有同名 general → merge 无决策 → Conflict → skipped
+    dst.settings.ns.set('general', { value: { theme: 'light' }, revision: 7, secrets: [] })
+    const importer = makeImporter(dst)
+
+    const plan = await importer.createImportPlan(zipPath, { strategy: 'merge', resolutions: {}, pathMappings: [] })
+    assert.ok(plan.items.some((i) => i.id === 'settings:general' && i.kind === 'Conflict'), '应有未决策冲突项')
+    assert.ok(plan.items.some((i) => i.kind === 'MissingSecret'), '应有缺失秘密补录占位')
+
+    const calls: PlanItemProgress[] = []
+    await importer.executeImportPlan(zipPath, plan, {
+      confirm: true,
+      onItem: (info) => { calls.push(info) },
+    })
+
+    const conflict = calls.find((c) => c.detail === 'settings:general')
+    assert.equal(conflict?.status, 'skipped', '冲突未解决 → skipped 且上报')
+    const secret = calls.find((c) => c.detail === 'secret:DEEPSEEK_API_KEY')
+    assert.equal(secret?.status, 'skipped', '秘密未补录 → skipped 且上报（不泄露值）')
+    // skipped 项同样占用 index/total 计数（进度条整体推进）
+    assert.ok(conflict !== undefined && conflict.index > 0, '冲突项计入进度计数')
+    assert.ok(secret !== undefined && secret.index > conflict!.index, '秘密项在冲突项之后计数')
+  })
+})
+
+test('m1 埋点: onItem 抛错不影响导入执行（进度是尽力而为）', async () => {
+  await withTmp(async (dir) => {
+    const src = makeContext('win32', 'C:\\Users\\alice')
+    await seedSource(src)
+    const zipPath = path.join(dir, 'resilient.zip')
+    await exportFixture(src, zipPath)
+
+    const dst = makeContext('win32', 'C:\\Users\\bob')
+    dst.settings.registered.add('general')
+    dst.settings.registered.add('llm-deepseek')
+    const importer = makeImporter(dst)
+
+    const plan = await importer.createImportPlan(zipPath, { strategy: 'merge', resolutions: {}, pathMappings: [] })
+    const result = await importer.executeImportPlan(zipPath, plan, {
+      confirm: true,
+      onItem: () => { throw new Error('埋点回调故障') },
+    })
+
+    assert.equal(result.ok, true, '导入不受埋点故障影响')
+    assert.deepEqual(dst.settings.ns.get('general')?.value, { theme: 'dark', language: 'zh-CN' }, '数据正常写入')
+  })
+})

package/src/core/run-registry.test.ts

@@ -0,0 +1,139 @@
+/**
+ * RunRegistry 基础单测（m1 自测，m4 会补全埋点/路由/轮询测试）：
+ *  - register：不可猜 runId、running 初始态、同 kind 并发拒绝（不同 kind 互不阻塞）
+ *  - update：进度字段落账并刷新 updatedAt；完成/失败后晚到更新被忽略
+ *  - finish/fail：状态与 result/error 落账
+ *  - get/listActive：过滤语义与不存在处理
+ *  - 保留期清理：超过 retentionMs 后不可见（含长期 running 僵死任务）
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  DEFAULT_RUN_RETENTION_MS, RunConflictError, RunRegistry,
+} from './run-registry.ts'
+
+test('register: 生成不可猜的 32 hex runId 且初始为 running', () => {
+  const reg = new RunRegistry()
+  const run = reg.register('export')
+  assert.match(run.runId, /^[0-9a-f]{32}$/)
+  assert.equal(run.status, 'running')
+  assert.equal(run.kind, 'export')
+  assert.equal(run.section, null)
+  assert.equal(run.item, null)
+  assert.ok(run.createdAt > 0)
+  assert.equal(run.updatedAt, run.createdAt)
+})
+
+test('register: 同 kind 进行中拒绝新 run（RunConflictError 携带既有 runId）', () => {
+  const reg = new RunRegistry()
+  const first = reg.register('export')
+  assert.throws(
+    () => reg.register('export'),
+    (err: unknown) => {
+      assert.ok(err instanceof RunConflictError)
+      assert.equal((err as RunConflictError).runId, first.runId)
+      return true
+    },
+  )
+})
+
+test('register: 不同 kind 互不阻塞（导出进行中可导入）', () => {
+  const reg = new RunRegistry()
+  reg.register('export')
+  const imp = reg.register('import')
+  assert.equal(imp.kind, 'import')
+  assert.equal(reg.listActive().length, 2)
+})
+
+test('register: 完成/失败后的 run 不阻塞同 kind 新 run', () => {
+  const reg = new RunRegistry()
+  const first = reg.register('export')
+  reg.finish(first.runId, { ok: true })
+  const second = reg.register('export')
+  assert.notEqual(second.runId, first.runId)
+
+  const failed = reg.register('import')
+  reg.fail(failed.runId, 'boom')
+  const retry = reg.register('import')
+  assert.notEqual(retry.runId, failed.runId)
+})
+
+test('update: 进度字段落账并刷新 updatedAt', () => {
+  let now = 1000
+  const reg = new RunRegistry({ now: () => now })
+  const run = reg.register('import')
+  now = 1200
+  reg.update(run.runId, { section: 'plugins', item: 3, itemTotal: 10, detail: 'plugin:pkg-a' })
+  const state = reg.get(run.runId)
+  assert.equal(state?.section, 'plugins')
+  assert.equal(state?.item, 3)
+  assert.equal(state?.itemTotal, 10)
+  assert.equal(state?.detail, 'plugin:pkg-a')
+  assert.equal(state?.updatedAt, 1200, 'update 必须刷新 updatedAt')
+})
+
+test('update: 完成/失败后的晚到更新被忽略（异步回调竞态防御）', () => {
+  const reg = new RunRegistry()
+  const run = reg.register('export')
+  reg.update(run.runId, { detail: 'settings' })
+  reg.finish(run.runId, { zipPath: 'x.zip' })
+  reg.update(run.runId, { detail: 'late-write' })
+  const state = reg.get(run.runId)
+  assert.equal(state?.status, 'done')
+  assert.equal(state?.detail, 'settings', 'finish 后的 update 不得覆盖')
+  assert.deepEqual(state?.result, { zipPath: 'x.zip' })
+})
+
+test('finish/fail: 状态与 result/error 落账', () => {
+  const reg = new RunRegistry()
+  const done = reg.register('export')
+  reg.finish(done.runId, { zipPath: 'dsh-config.zip', manifest: { schemaVersion: 1 } })
+  const after = reg.get(done.runId)
+  assert.equal(after?.status, 'done')
+  assert.deepEqual(after?.result, { zipPath: 'dsh-config.zip', manifest: { schemaVersion: 1 } })
+
+  const failed = reg.register('import')
+  reg.fail(failed.runId, '安装插件失败')
+  const f = reg.get(failed.runId)
+  assert.equal(f?.status, 'failed')
+  assert.equal(f?.error, '安装插件失败')
+})
+
+test('get/listActive: 只列出 running run；不存在返回 undefined', () => {
+  const reg = new RunRegistry()
+  assert.equal(reg.get('nope'), undefined)
+  const a = reg.register('export')
+  const b = reg.register('import')
+  reg.finish(a.runId, {})
+  const active = reg.listActive()
+  assert.equal(active.length, 1)
+  assert.equal(active[0]?.runId, b.runId)
+  // 返回副本：外部改动不影响内部状态
+  active[0]!.detail = 'hacked'
+  assert.notEqual(reg.get(b.runId)?.detail, 'hacked')
+})
+
+test('保留期清理: 超过 retentionMs 后不可见（含长期 running 僵死任务）', () => {
+  let now = 0
+  const reg = new RunRegistry({ retentionMs: 1000, now: () => now })
+  const run = reg.register('export')
+  now = 500
+  reg.finish(run.runId, { ok: true })
+  assert.ok(reg.get(run.runId), '保留期内可见')
+  now = 1501
+  assert.equal(reg.get(run.runId), undefined, '超过保留期清理')
+  assert.equal(reg.listActive().length, 0)
+})
+
+test('保留期清理: 长时间不 settle 的 running run 同样被清理', () => {
+  let now = 0
+  const reg = new RunRegistry({ retentionMs: 60000, now: () => now })
+  reg.register('import')
+  now = 60001
+  assert.equal(reg.listActive().length, 0, '僵死 running run 也要清理')
+})
+
+test('默认保留期常量为 30 分钟', () => {
+  assert.equal(DEFAULT_RUN_RETENTION_MS, 30 * 60 * 1000)
+})

package/src/core/run-registry.ts

@@ -0,0 +1,166 @@
+/**
+ * Host 端 run 注册表（m1）：记录导出/导入任务的运行状态与真实进度。
+ *
+ * 浏览器侧通过 `/api/dsh-config-manager/progress?runId=…` 与
+ * `/api/dsh-config-manager/runs` 轮询/恢复进度（m2 store 刷新恢复、m3 进度 UI
+ * 消费）；本模块是 Host 侧的单一事实源，不依赖任何 DSH 运行时服务。
+ *
+ * 安全纪律：
+ *  - runId 由 crypto.randomBytes(16) 生成（32 hex 字符），不可猜测；
+ *  - RunState 只存非敏感摘要（分区/计数/详情文案），绝不写入密钥、密码、
+ *    秘密补录值或任何敏感内容；
+ *  - result 只存可 JSON 序列化的业务结果（导出为 { zipPath, manifest, report }，
+ *    导入为 ImportResult），不含秘密值。
+ *
+ * 生命周期：register（running）→ update（进度）→ finish（done+result）/
+ * fail（failed+error）；超过保留期（默认 30 分钟）的 run 在任意读操作时惰性清理。
+ * 并发纪律：同一 kind 已有 running 的 run 时，register 抛 RunConflictError
+ * （宿主路由以 409 拒绝新任务，防止重复导出/导入）。
+ */
+import { randomBytes } from 'node:crypto'
+
+/** run 类型：导出 / 导入。 */
+export type RunKind = 'export' | 'import'
+
+/** run 状态：进行中 / 完成 / 失败。 */
+export type RunStatus = 'running' | 'done' | 'failed'
+
+/** 单个 run 的实时状态（/progress 返回体；纯 JSON 可序列化）。 */
+export interface RunState {
+  /** 不可猜测的 run id（32 hex 字符）。 */
+  runId: string
+  kind: RunKind
+  status: RunStatus
+  /** 当前分区（adapter id 或导入阶段名）；无则 null。 */
+  section: string | null
+  /** 分区总数（导出 = 选中分区数；导入无此语义 = null）。 */
+  sectionTotal: number | null
+  /** 已完成的内部计数（导出 = 当前分区序号；导入 = 已处理计划项数）。 */
+  item: number | null
+  /** 内部计数总数（导出 = 分区总数；导入 = 计划项总数）。 */
+  itemTotal: number | null
+  /** 非敏感进度摘要（当前分区 / 当前计划项 id）。 */
+  detail: string | null
+  /** 完成时的业务结果（仅 JSON 可序列化、不含秘密值）。 */
+  result?: unknown
+  /** 失败时的错误消息（非敏感）。 */
+  error?: string
+  createdAt: number
+  updatedAt: number
+}
+
+/** 进行中同 kind 已有 run 时注册被拒（宿主路由 → 409）。 */
+export class RunConflictError extends Error {
+  /** 已在进行中的 run id（供客户端定位既有任务）。 */
+  readonly runId: string
+  constructor(runId: string, kind: RunKind) {
+    super(
+      kind === 'export'
+        ? `已有进行中的导出任务（${runId}），请等待其完成后再试`
+        : `已有进行中的导入任务（${runId}），请等待其完成后再试`,
+    )
+    this.name = 'RunConflictError'
+    this.runId = runId
+  }
+}
+
+/** 完成/失败后的默认保留时长（30 分钟）。 */
+export const DEFAULT_RUN_RETENTION_MS = 30 * 60 * 1000
+
+export interface RunRegistryOptions {
+  /** 完成/失败后保留时长（默认 30 分钟）；超期 run 在下次访问时清理。 */
+  retentionMs?: number
+  /** 时间源（测试注入）。 */
+  now?: () => number
+}
+
+/**
+ * 内存 run 注册表。Node 单线程 + 同步 Map 读写，无并发竞争；
+ * 所有公开读方法返回状态副本，防止外部直接篡改内部状态。
+ */
+export class RunRegistry {
+  private readonly runs = new Map<string, RunState>()
+  private readonly retentionMs: number
+  private readonly now: () => number
+
+  constructor(opts: RunRegistryOptions = {}) {
+    this.retentionMs = opts.retentionMs ?? DEFAULT_RUN_RETENTION_MS
+    this.now = opts.now ?? (() => Date.now())
+  }
+
+  /** 注册新 run；同 kind 已有 running 时抛 RunConflictError。 */
+  register(kind: RunKind): RunState {
+    this.prune()
+    for (const run of this.runs.values()) {
+      if (run.kind === kind && run.status === 'running') throw new RunConflictError(run.runId, kind)
+    }
+    const now = this.now()
+    const state: RunState = {
+      runId: randomBytes(16).toString('hex'),
+      kind,
+      status: 'running',
+      section: null,
+      sectionTotal: null,
+      item: null,
+      itemTotal: null,
+      detail: null,
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.runs.set(state.runId, state)
+    return { ...state }
+  }
+
+  /** 更新进度；run 不存在返回 undefined；已完成/失败后的晚到更新被忽略（防御异步回调竞态）。 */
+  update(
+    runId: string,
+    patch: Partial<Pick<RunState, 'section' | 'sectionTotal' | 'item' | 'itemTotal' | 'detail'>>,
+  ): RunState | undefined {
+    const run = this.runs.get(runId)
+    if (run === undefined) return undefined
+    if (run.status !== 'running') return { ...run }
+    Object.assign(run, patch, { updatedAt: this.now() })
+    return { ...run }
+  }
+
+  /** 读单个 run；超过保留期或不存在返回 undefined。 */
+  get(runId: string): RunState | undefined {
+    this.prune()
+    const run = this.runs.get(runId)
+    return run === undefined ? undefined : { ...run }
+  }
+
+  /** 列出活跃（running）run（刷新恢复时经 /runs 重订阅用）。 */
+  listActive(): RunState[] {
+    this.prune()
+    return [...this.runs.values()].filter((r) => r.status === 'running').map((r) => ({ ...r }))
+  }
+
+  /** 标记完成并写入业务结果；run 不存在返回 undefined。 */
+  finish(runId: string, result: unknown): RunState | undefined {
+    const run = this.runs.get(runId)
+    if (run === undefined) return undefined
+    run.status = 'done'
+    run.result = result
+    run.updatedAt = this.now()
+    return { ...run }
+  }
+
+  /** 标记失败并写入错误消息；run 不存在返回 undefined。 */
+  fail(runId: string, error: string): RunState | undefined {
+    const run = this.runs.get(runId)
+    if (run === undefined) return undefined
+    run.status = 'failed'
+    run.error = error
+    run.updatedAt = this.now()
+    return { ...run }
+  }
+
+  /** 惰性清理：超过保留期的 run（含长期 running 的僵死任务）全部移除。 */
+  private prune(): void {
+    const cutoff = this.now() - this.retentionMs
+    for (const [id, run] of this.runs) {
+      if (run.updatedAt < cutoff) this.runs.delete(id)
+    }
+  }
+}

package/src/core/smoke.test.ts

@@ -152,6 +152,11 @@ class MemSnapshotStore implements SnapshotStore {
     if (!v) throw new Error(`blob not found: ${id}/${blobPath}`);
     return v;
   }
+  async updateStatus(id: string, status: Snapshot['status']): Promise<void> {
+    const s = this.snapshots.get(id);
+    if (!s) throw new Error(`snapshot not found: ${id}`);
+    s.status = status;
+  }
 }
 
 class MockHostContext implements HostContext {

package/src/core/types.ts

@@ -114,6 +114,8 @@ export interface HostContext {
   workspace: WorkspaceFacade;
   patchFile: PatchFileFacade;
   fs: FileSystemFacade;
+  /** 当前管理的 DSH profile 名（如 web）；引擎用它定位 profiles/<profile>/cordis.patch.yml。宿主不暴露时缺省 */
+  profile?: string;
 }
 
 /* ---------------- 导入计划（§13.3 十类 + 决策） ---------------- */
@@ -240,11 +242,29 @@ export interface SnapshotEntry {
   snapshotId?: string;
 }
 
+/** 快照生命周期状态（M1 增强；旧快照无此字段，视为未知/兼容） */
+export type SnapshotStatus = 'pending' | 'done' | 'rolled-back';
+
+/** 宿主整文件备份登记（M1）：导入前对 $DSH_HOME 关键文件的整文件快照。
+ * relPath 相对 $DSH_HOME（如 settings.yaml / cordis.patch.yml / profiles/<p>/cordis.patch.yml），
+ * blobPath 为快照内 blob 路径（existed=false 时为空串，表示该文件当时不存在）。 */
+export interface HostFileBackup {
+  relPath: string;
+  blobPath: string;
+  existed: boolean;
+}
+
 export interface Snapshot {
   id: string;
   createdAt: string;
   sourceZip: string;
   entries: SnapshotEntry[];
+  /** 生命周期状态：pending（已生成，导入未完成）/ done（导入成功）/ rolled-back（失败已回滚）。旧快照缺省 */
+  status?: SnapshotStatus;
+  /** 导入前已安装插件清单（M2 restore 撤销插件时与当前已装对比）。旧快照缺省 */
+  beforePlugins?: PluginInfo[];
+  /** 宿主整文件备份（settings.yaml / settings.json / cordis.patch.yml / profiles/<p>/cordis.patch.yml）。旧快照缺省 */
+  hostFileBackups?: HostFileBackup[];
 }
 
 /** 快照存储（默认文件实现见 core/backup.ts；测试可用内存实现） */
@@ -252,6 +272,8 @@ export interface SnapshotStore {
   save(snapshot: Snapshot, blobs?: Map<string, Uint8Array>): Promise<string>;
   load(id: string): Promise<Snapshot>;
   readBlob(id: string, blobPath: string): Promise<Uint8Array>;
+  /** 标记快照生命周期状态（导入成功→done；失败回滚→rolled-back；持久化由实现负责） */
+  updateStatus(id: string, status: SnapshotStatus): Promise<void>;
 }
 
 export interface RollbackReport {