dsh-config-manager 0.1.71 → 0.1.72

package/src/routes/snapshots.ts

@@ -16,6 +16,17 @@ import { buildFileDiffBody, buildRestoreBody, executeRestorePlan, makeRestoreExe
 import { EnvironmentLockUnavailableError, runWithMutationLock } from '../utils/env-lock.ts'
 import { isENOENT } from '../utils/guards.ts'
 import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+
+/**
+ * 恢复计划指纹（预览-执行一致性）：只取「动作类型 + 目标 + blob」三列 —— 描述文案、详情、顺序无关的
+ * 易变字段一律不进，保证同一份快照 + 同一磁盘状态下指纹稳定。内容变化不会改变指纹（同 kind/target），
+ * 只有**动作集合真的变了**（文件出现/消失、插件增删）才会不同 —— 那正是需要用户重新确认的情况。
+ */
+function restorePlanFingerprint(plan: Awaited<ReturnType<typeof planRestore>>): string {
+  const lines = plan.actions.map((action) => [action.kind, action.target ?? '', action.blobPath ?? ''].join('\u0000'))
+  return createHash('sha256').update(lines.join('\n')).digest('hex')
+}
 
 export function snapshotRoutes(env: RoutesEnv): WebRoute[] {
   const {
@@ -32,7 +43,11 @@ export function snapshotRoutes(env: RoutesEnv): WebRoute[] {
     // M4：列出快照元信息（id/createdAt/sourceZip/status/计数，createdAt 倒序）
     endpoint({ path: '/api/dsh-config-manager/snapshots', methods: ['GET'] }, async (req, res) => {
       try {
-        writeJson(res, 200, { snapshots: await listSnapshots(snapshotsDir) })
+        // 「读不到」与「没有」必须分清（core 的 out.unreadable，验收 F2）：快照目录被权限/占位挡住时
+        // 一律回传事实，界面据此渲染告警 —— 此前这个信号在路由层被丢掉，用户看到的是空列表。
+        const out: { unreadable?: string } = {}
+        const snapshots = await listSnapshots(snapshotsDir, out)
+        writeJson(res, 200, { snapshots, unreadable: out.unreadable ?? null })
       } catch (error) {
         writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
       }
@@ -78,7 +93,8 @@ export function snapshotRoutes(env: RoutesEnv): WebRoute[] {
           // git 风格恢复预览：逐动作的变更状态 + 行数统计（读取有上限，见 core/snapshot-diff.ts）。
           // summarize 内部逐项兜底、绝不抛错 —— 统计失败不影响计划本身。
           const changeSummary = await summarizeRestoreChanges({ plan, snapshotDir, homeDir: host.homeDir, msg })
-          writeJson(res, 200, { dryRun: true, plan, changeSummary })
+          // 指纹随预览一起下发：执行时带回来即可发现「确认后磁盘又变了」
+          writeJson(res, 200, { dryRun: true, plan, changeSummary, planFingerprint: restorePlanFingerprint(plan) })
           return
         }
         // 真实执行（Phase 2 锁：destructive 必须先获取 GLOBAL 环境锁；被挡 → 423）
@@ -95,6 +111,16 @@ export function snapshotRoutes(env: RoutesEnv): WebRoute[] {
             const runId = run.runId
             try {
               const plan = await planRestore(restoreOpts)
+              // 预览-执行一致性：客户端带了预览指纹而当前计划与之不符 → 拒绝（409）并让用户重新预览。
+              // 为什么必须挡：用户确认的是「还原 A/B」，此刻磁盘已被改动的话，同一份快照可能多出
+              // hostFileRemove / fileRemove 这类**破坏性**动作 —— 确认内容与实际执行内容不一致且无人提示。
+              const expectedFingerprint = parsed.value.planFingerprint
+              if (expectedFingerprint !== undefined && expectedFingerprint !== restorePlanFingerprint(plan)) {
+                host.log.warn('恢复被拒：预览后计划已变化', { snapshotId })
+                runs.fail(runId, 'plan-changed')
+                writeJson(res, 409, { error: 'plan-changed', code: 'plan-changed', runId })
+                return
+              }
               const report = await executeRestorePlan(
                 plan,
                 makeRestoreExecutor(snapshotDir, host, host.profile),
@@ -118,7 +144,11 @@ export function snapshotRoutes(env: RoutesEnv): WebRoute[] {
                 snapshotId: snapshotId,
                 runId,
                 source: 'api',
-                summary: `恢复快照 ${snapshotId}：还原 ${report.restored.length} 项${report.removedPlugins.length > 0 ? `，卸载插件 ${report.removedPlugins.length}` : ''}`,
+                summary: msg('route.snapshotRestoreSummary', {
+                  id: snapshotId,
+                  count: report.restored.length,
+                  suffix: report.removedPlugins.length > 0 ? msg('route.snapshotRestoreRemovedPluginsSuffix', { count: report.removedPlugins.length }) : '',
+                }),
               })
               writeJson(res, 200, historyError === undefined ? { dryRun: false, report, runId } : { dryRun: false, report, runId, historyWriteError: historyError })
             } catch (error) {
@@ -159,6 +189,23 @@ export function snapshotRoutes(env: RoutesEnv): WebRoute[] {
           writeJson(res, 400, { error: 'snapshotId is required and must be a valid snapshot id' })
           return
         }
+        // Phase 4 F3 同源：被未收敛 journal 引用的快照是 SAFE MODE 恢复的唯一证据 ——
+        // 自动保留清理早已豁免它们，手动删除也必须挡住（此前只校验了 id 形状）。
+        // 读不到引用集合时**保守拒绝**（与自动 prune 的 fail-closed 同一条口径），并让原因可辨。
+        if (host.phase3Recovery !== undefined) {
+          let referenced: Set<string>
+          try {
+            referenced = await host.phase3Recovery.store.listReferencedSnapshotIds()
+          } catch (error) {
+            host.log.warn('快照删除被拒：读取 recovery 引用集合失败', { error: error instanceof Error ? error.message : String(error) })
+            writeJson(res, 409, { error: 'recovery-reference-unreadable', code: 'recovery-reference-unreadable' })
+            return
+          }
+          if (referenced.has(id)) {
+            writeJson(res, 409, { error: 'snapshot-referenced-by-recovery', code: 'snapshot-referenced-by-recovery' })
+            return
+          }
+        }
         const removed = await deleteSnapshot(snapshotsDir, id)
         const historyError = await tryAppendHistory({
           kind: 'snapshot-delete',
@@ -166,7 +213,7 @@ export function snapshotRoutes(env: RoutesEnv): WebRoute[] {
           sections: [id],
           snapshotId: id,
           source: 'api',
-          summary: `删除快照 ${id}`,
+          summary: msg('route.snapshotDeleteSummary', { id }),
         })
         writeJson(res, 200, historyError === undefined ? { ok: true, removed } : { ok: true, removed, historyWriteError: historyError })
       } catch (error) {

package/src/routes/sync.ts

@@ -118,7 +118,7 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
     resolveSyncPassword,
     scheduler,
     selectionCache,
-    selectionHasOptInSections,
+    selectionOptInSections,
     selectionView,
     selectionViewByChannel,
     syncCredentialsByChannelView,
@@ -126,6 +126,7 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
     syncPasswordConfigured,
     syncSectionCatalog,
     syncSessions,
+    syncWorkDir,
     tmpDir,
     tryAppendHistory,
     withMutationGate,
@@ -163,6 +164,11 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           : undefined
         // 云端点配置视图（只回 secretStored 布尔；与当前通道无关，配置过即回填）
         const cloud = await cloudChannelViews(full, credentials)
+        // issue #79：git 工作副本是否已跟随 repoUrl（只读自检，2 条本地只读 git 命令）。
+        // 读不出来时**如实回传错误**（workDirError），不让状态接口静默少一块信息。
+        const gitRepoUrl = full?.git?.repoUrl ?? ''
+        let workDir: Awaited<ReturnType<typeof syncWorkDir.inspect>> | null = null
+        if (gitRepoUrl !== '') workDir = await syncWorkDir.inspect(gitRepoUrl)
         writeJson(res, 200, {
           ok: true,
           configured: full !== null,
@@ -194,11 +200,44 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           autosync: await buildAutosyncStatus(syncDir, transport),
           // 全部通道的自动同步状态（git/webdav 各自独立；UI 按当前 tab 取对应通道）
           autosyncByChannel: await buildAutosyncStatusByChannel(syncDir),
+          // 工作副本事实（仅 git 且配置了地址时返回；'facts' = 自检成功，'error' = 自检读不出来）
+          ...(workDir === null ? {} : { workDir }),
         })
       } catch (error) {
         writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
       }
     }),
+    // ------------------------------------------------------ sync/workdir/reset
+    // issue #79：工作副本的自救入口（改造前 App 内完全没有 —— 改了仓库地址只能手工
+    // git remote set-url，或删掉 <dataDir>/sync/work 重来）。两种模式，破坏性清清楚楚：
+    //   relink  = 只把 origin / push URL 重指向当前配置地址（非破坏性：不碰工作树与本地提交）；
+    //   reclone = 删除工作副本目录后重新 clone（**丢弃未上行的本地提交**）→ 必须显式 confirm。
+    // 写动作 → 过 mutation gate（SAFE MODE / 环境锁）；删除边界见 GitTransport.rebuildWorkDir
+    // （目录非空且无 .git 一律拒绝，绝不删来路不明的目录）。
+    endpoint({ path: '/api/dsh-config-manager/sync/workdir/reset', methods: ['POST'] }, withMutationGate('sync-workdir-reset', async (req, res) => {
+      try {
+        const body = await requireJsonObject(req)
+        const mode = body['mode'] === undefined ? 'relink' : body['mode']
+        if (mode !== 'relink' && mode !== 'reclone') {
+          writeJson(res, 400, { error: msg('sync.workdirModeInvalid', { mode: JSON.stringify(body['mode']) }) })
+          return
+        }
+        if (mode === 'reclone' && body['confirm'] !== true) {
+          writeJson(res, 400, { error: msg('sync.workdirRecloneNeedsConfirm') })
+          return
+        }
+        const full = await readFullSyncConfig(syncDir)
+        const repoUrl = full?.git?.repoUrl ?? ''
+        if (repoUrl === '') {
+          writeJson(res, 400, { error: msg('sync.workdirNotConfigured') })
+          return
+        }
+        const rebuilt = await syncWorkDir.rebuild(repoUrl, mode)
+        writeJson(res, 200, { ok: true, mode, workDir: { facts: rebuilt } })
+      } catch (error) {
+        writeSyncRouteError(res, error)
+      }
+    })),
     // ------------------------------------------------------ sync/config
     // m-sync-config：保存同步通道配置（parseSyncBody 校验 + password/token 写 DSH credentials +
     // writeSyncConfig 落盘）。UI 表单自动保存 /「保存配置」按钮调用；响应为轻量状态视图
@@ -295,7 +334,8 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
       const body = await requireJsonObject(req)
       try {
         const syncCfg = await prepareSync(body)
-        const engine = makeSyncEngine(syncCfg)
+        // 用户驱动的推送：放行持久化选择里勾选的可选分区（mcp / sessions），否则它们按非 portable 跳过
+        const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) })
         const snapshotId =
           typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined
         const sections = extractSyncSections(body, knownSyncSectionIds)
@@ -311,7 +351,7 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
         // 因为那是用户此刻输入的覆盖值；两者都没有 → 交给 engine 报「加密需要密码」。
         const pushChannel: SyncTransportType = channelOf(syncCfg)
         const effectiveEncryptPassword = encryptPassword ?? await resolveSyncPassword(syncPasswordRef('ENCRYPT', pushChannel))
-        // 可选分区选项（历史会话「最新 N 个」）：只有显式提供才允许 sessions 进同步通道
+        // sessions 的导出参数（「最新 N 个」/ 逐会话点名）；**放行**由引擎的 optInSections 决定
         const sessions = extractSyncSessions(body)
         const sessionsOpt = sections !== undefined && sections.includes('sessions') && sessions !== undefined
           ? { sessions }
@@ -352,8 +392,8 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
       const body = await requireJsonObject(req)
       try {
         const syncCfg = await prepareSync(body)
-        // 用户驱动的拉取：选择里勾了 sessions 时才让会话分区进入差异计划（自动同步不传）
-        const engine = makeSyncEngine(syncCfg, { includeOptInSections: selectionHasOptInSections(channelOf(syncCfg)) })
+        // 用户驱动的拉取：放行持久化选择里勾选的**全部**可选分区（自动同步只放行 'auto' 档）
+        const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) })
         const strategy =
           body['strategy'] === 'replace' || body['strategy'] === 'skipExisting' ? body['strategy'] : 'merge'
         const snapshotId =
@@ -616,7 +656,7 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
       const body = await requireJsonObject(req)
       try {
         const syncCfg = await prepareSync(body)
-        const engine = makeSyncEngine(syncCfg, { includeOptInSections: selectionHasOptInSections(channelOf(syncCfg)) })
+        const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) })
         const snapshotId = typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined
         // 可选落地文件名（产物库「下载」要给用户一个可辨识的名字，而不是固定的 snapshot.zip）。
         // 不安全的名字直接 400 而不是「静默换名」：它会进 path.join(dir, name)，白名单是唯一防线。
@@ -708,8 +748,8 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
       const body = await requireJsonObject(req)
       try {
         const syncCfg = await prepareSync(body)
-        // 用户驱动的一键同步：选择里勾了 sessions 时才让会话分区进入差异计划（自动同步不传）
-        const engine = makeSyncEngine(syncCfg, { includeOptInSections: selectionHasOptInSections(channelOf(syncCfg)) })
+        // 用户驱动的一键同步：放行持久化选择里勾选的**全部**可选分区（自动同步只放行 'auto' 档）
+        const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) })
         const snapshotId = typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined
         // 解密密码：请求体 > 已保存（DSH credentials）。明文快照根本不会被解密
         // （engine.prepareSnapshot 只在 manifest.encrypted 时才用密码），因此「未加密备份
@@ -731,7 +771,7 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           msg('host.syncPullTimeout'),
         )
         if (!preview.ok || preview.plan === null || preview.analysis === null) {
-          writeJson(res, 200, { ok: false, syncSessionId: '', snapshotId: preview.snapshotId, items: [], needsReview: false, compatibility: 'unsupported', message: preview.message ?? '同步预览失败' })
+          writeJson(res, 200, { ok: false, syncSessionId: '', snapshotId: preview.snapshotId, items: [], needsReview: false, compatibility: 'unsupported', message: preview.message ?? msg('route.syncPreviewFailed') })
           return
         }
         // T1：abort 处置在**预览阶段**就阻断（此刻仍零写入：临时 ZIP 与内存会话都还没登记）。
@@ -777,7 +817,7 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
         const syncSessionId = typeof body['syncSessionId'] === 'string' ? body['syncSessionId'] : ''
         const session = syncSessions.get(syncSessionId)
         if (session === undefined) {
-          writeJson(res, 400, { error: '同步会话不存在或已过期，请重新拉取预览' })
+          writeJson(res, 400, { error: msg('route.syncSessionExpired') })
           return
         }
         // T1：abort 处置在**应用前**再判一次（客户端可能绕过 preview 直接 apply，或预览后改了处置）。
@@ -804,7 +844,7 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           if (d === undefined || !d.adopt) return []
           // Conflict 项必须有 resolution；keepLocal/skip 不写入本地 → 剔除
           if (item.kind === 'Conflict') {
-            if (d.resolution === undefined) throw new SyncRouteError(`冲突项 ${item.id} 必须提供 resolution（useRemote/keepLocal/skip）`)
+            if (d.resolution === undefined) throw new SyncRouteError(msg('route.syncConflictResolutionRequired', { id: item.id }))
             if (d.resolution === 'keepLocal' || d.resolution === 'skip') return []
             // useRemote → 转成 Update 计划项（镜像 analyzer.applyItemResolution 的
             // useImported 分支），applyOne 才会把远端值真正写进本地。
@@ -850,10 +890,14 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           source: 'api',
           // issue #56：历史如实区分「全部成功 / 部分成功（N 项未生效）」——
           // 此前 ok:true 一律写「N 项」+ 无 error，用户在历史里看到的就是一次干净的成功。
-          summary: `一键同步应用：${(Array.isArray(report.applied) ? report.applied.length : subItems.length)} 项${report.rolledBack === true ? '（已回滚）' : ''}${report.ineffective.length > 0 ? `（${report.ineffective.length} 项未生效）` : ''}`,
+          summary: msg('route.syncApplySummary', {
+            count: Array.isArray(report.applied) ? report.applied.length : subItems.length,
+            status: report.rolledBack === true ? (report.rollbackFull === false ? msg('route.syncRollbackIncomplete') : msg('route.syncRolledBack')) : '',
+            ineffective: report.ineffective.length > 0 ? msg('route.syncIneffectiveSuffix', { count: report.ineffective.length }) : '',
+          }),
           error: report.ok
-            ? (report.ineffective.length > 0 ? '同步应用部分成功：有项未生效（见告警明细）' : undefined)
-            : '同步应用未完全成功',
+            ? (report.ineffective.length > 0 ? msg('route.syncApplyPartial') : undefined)
+            : msg('route.syncApplyFailed'),
         })
         writeJson(res, 200, historyError === undefined ? {
           ok: report.ok,
@@ -863,6 +907,8 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           warnings: report.warnings,
           restoreId: report.restoreId,
           rolledBack: report.rolledBack,
+          // 诚实性（2026-10）：整体回滚是否完整（false = 有项没恢复，失败项已并入 warnings）
+          ...(report.rollbackFull === undefined ? {} : { rollbackFull: report.rollbackFull }),
           failed: report.failed,
           // issue #56：未生效项（warning）单独回传，界面据此把「成功」降级为「部分成功」
           ineffective: report.ineffective,
@@ -875,6 +921,8 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           warnings: report.warnings,
           restoreId: report.restoreId,
           rolledBack: report.rolledBack,
+          // 诚实性（2026-10）：整体回滚是否完整（false = 有项没恢复，失败项已并入 warnings）
+          ...(report.rollbackFull === undefined ? {} : { rollbackFull: report.rollbackFull }),
           failed: report.failed,
           ineffective: report.ineffective,
           result: report.result,
@@ -1019,9 +1067,12 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           sections: [],
           snapshotId: restoreId,
           source: 'api',
-          summary: `一键同步回滚（${restoreId}）`,
+          summary: msg('route.syncRollbackSummary', { id: restoreId }),
         })
-        writeJson(res, 200, historyError === undefined ? { ok: true, full: report.full } : { ok: true, full: report.full, historyWriteError: historyError })
+        // 诚实回传：full=false 时把 failed（含 manualHint）一并给出，界面据此列出「哪些项没回滚、
+        // 需要人工补录」而不是无条件报「已回滚」。CLI 侧同口径见 src/cli/actions.ts 的 rollback 文案。
+        const payload = { ok: true, full: report.full, failed: report.failed }
+        writeJson(res, 200, historyError === undefined ? payload : { ...payload, historyWriteError: historyError })
       } catch (error) {
         writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
       }

package/src/schema/config.ts

@@ -8,7 +8,8 @@
  */
 import { parseJsonSafe } from '../utils/json.ts';
 import { isPathSafe } from '../utils/paths.ts';
-import { sectionMetaOf } from './section-registry.ts';
+import { schemaMsg } from './messages.ts';
+import { sectionMetaOf, type SectionMeta } from './section-registry.ts';
 import { sectionDataVersionIssue } from './versions.ts';
 import type { SectionData, SectionId } from './types.ts';
 
@@ -22,7 +23,6 @@ export {
   SECTION_DATA_VERSION,
   sectionMeta,
   sectionMetaOf,
-  requireSectionMeta,
   isSectionId,
   jsonPathOf,
   filePrefixOf,
@@ -36,13 +36,29 @@ export type {
   SectionPortability,
 } from './section-registry.ts';
 
+/**
+ * 拿不到元数据就**显式失败**（绝不让未注册分区按其它分区语义继续）。
+ * core 侧修正「未知分区静默记成 settingsNamespace」时用它替代 default 分支。
+ *
+ * t7：本函数原在 `section-registry.ts`；该模块受「只 import 一个类型」的零依赖铁律约束
+ * （client bundle 侧 `ui/export-flow.ts` 也在用它），故把唯一的用户可见文案抛出点迁到本文件
+ * （已持有本域消息目录）。public surface 不变：`config.ts` 与 `schema/index.ts` 仍照旧导出它。
+ */
+export function requireSectionMeta(id: string): SectionMeta {
+  const meta = sectionMetaOf(id);
+  if (meta === null) {
+    throw new Error(schemaMsg('schema.sectionNotRegistered', { section: id }));
+  }
+  return meta;
+}
+
 /** 从 ZIP 内 JSON 解析分区数据（深度保护 + 结构校验） */
 export function parseSectionJson<T extends SectionData>(sectionId: SectionId, raw: string): T {
   const parsed = parseJsonSafe(raw) as T;
   const issues = validateSectionData(sectionId, parsed);
   const errors = issues.filter((i) => i.severity === 'error');
   if (errors.length > 0) {
-    throw new Error(`分区 ${sectionId} 数据无效: ${errors.map((e) => e.message).join('; ')}`);
+    throw new Error(schemaMsg('schema.sectionDataInvalid', { section: sectionId, issues: errors.map((e) => e.message).join('; ') }));
   }
   return parsed;
 }
@@ -60,11 +76,11 @@ export interface SectionIssue { path: string; message: string; severity: 'error'
 export function validateSectionData(sectionId: SectionId, data: unknown): SectionIssue[] {
   const issues: SectionIssue[] = [];
   if (data === null || typeof data !== 'object') {
-    return [{ path: '$', message: `分区 ${sectionId} 数据必须是对象`, severity: 'error' }];
+    return [{ path: '$', message: schemaMsg('schema.sectionDataMustBeObject', { section: sectionId }), severity: 'error' }];
   }
   const meta = sectionMetaOf(sectionId);
   if (meta === null) {
-    return [{ path: '$', message: `未注册分区 ${String(sectionId)}：拒绝校验（新增分区须在 schema/section-registry.ts 注册）`, severity: 'error' }];
+    return [{ path: '$', message: schemaMsg('schema.sectionUnregistered', { section: String(sectionId) }), severity: 'error' }];
   }
   const obj = data as Record<string, unknown>;
   const versionIssue = sectionDataVersionIssue(meta.id, obj['version']);
@@ -77,32 +93,32 @@ export function validateSectionData(sectionId: SectionId, data: unknown): Sectio
     case 'namespaces': {
       const ns = obj['namespaces'];
       if (ns === null || typeof ns !== 'object') {
-        issues.push({ path: 'namespaces', message: `分区 ${meta.id} 缺少 namespaces 对象`, severity: 'error' });
+        issues.push({ path: 'namespaces', message: schemaMsg('schema.namespacesMissing', { section: meta.id }), severity: 'error' });
       } else {
         for (const [name, rec] of Object.entries(ns as Record<string, unknown>)) {
           if (rec === null || typeof rec !== 'object') {
-            issues.push({ path: `namespaces.${name}`, message: 'namespace 记录必须是对象', severity: 'error' });
+            issues.push({ path: `namespaces.${name}`, message: schemaMsg('schema.namespaceRecordMustBeObject'), severity: 'error' });
             continue;
           }
           const r = rec as Record<string, unknown>;
-          if (typeof r['revision'] !== 'number') issues.push({ path: `namespaces.${name}.revision`, message: 'revision 必须是数字', severity: 'error' });
-          if (!('value' in r)) issues.push({ path: `namespaces.${name}.value`, message: '缺少 value', severity: 'error' });
+          if (typeof r['revision'] !== 'number') issues.push({ path: `namespaces.${name}.revision`, message: schemaMsg('schema.revisionMustBeNumber'), severity: 'error' });
+          if (!('value' in r)) issues.push({ path: `namespaces.${name}.value`, message: schemaMsg('schema.valueMissing'), severity: 'error' });
           const secrets = r['secrets'];
-          if (secrets !== undefined && !Array.isArray(secrets)) issues.push({ path: `namespaces.${name}.secrets`, message: 'secrets 必须是数组', severity: 'error' });
+          if (secrets !== undefined && !Array.isArray(secrets)) issues.push({ path: `namespaces.${name}.secrets`, message: schemaMsg('schema.secretsMustBeArray'), severity: 'error' });
         }
       }
       break;
     }
     case 'object': {
       const value = obj[payload.key];
-      if (value === null || typeof value !== 'object') issues.push({ path: payload.key, message: `缺少 ${payload.key} 对象`, severity: 'error' });
+      if (value === null || typeof value !== 'object') issues.push({ path: payload.key, message: schemaMsg('schema.objectMissing', { key: payload.key }), severity: 'error' });
       break;
     }
     case 'array': {
-      if (!Array.isArray(obj[payload.key])) issues.push({ path: payload.key, message: `${payload.key} 必须是数组`, severity: 'error' });
+      if (!Array.isArray(obj[payload.key])) issues.push({ path: payload.key, message: schemaMsg('schema.keyMustBeArray', { key: payload.key }), severity: 'error' });
       for (const extra of payload.extraArrayKeys ?? []) {
         if (obj[extra] !== undefined && !Array.isArray(obj[extra])) {
-          issues.push({ path: extra, message: `${extra} 必须是数组`, severity: 'error' });
+          issues.push({ path: extra, message: schemaMsg('schema.keyMustBeArray', { key: extra }), severity: 'error' });
         }
       }
       if (payload.validatePatchFiles === true) {
@@ -111,20 +127,20 @@ export function validateSectionData(sectionId: SectionId, data: unknown): Sectio
         const patchFiles = obj['patchFiles'];
         if (patchFiles !== undefined) {
           if (!Array.isArray(patchFiles)) {
-            issues.push({ path: 'patchFiles', message: 'patchFiles 必须是数组', severity: 'error' });
+            issues.push({ path: 'patchFiles', message: schemaMsg('schema.keyMustBeArray', { key: 'patchFiles' }), severity: 'error' });
           } else {
             patchFiles.forEach((pf, i) => {
               const rec = (pf !== null && typeof pf === 'object') ? pf as Record<string, unknown> : null;
               if (rec === null) {
-                issues.push({ path: `patchFiles[${i}]`, message: 'patch 文件条目必须是对象', severity: 'error' });
+                issues.push({ path: `patchFiles[${i}]`, message: schemaMsg('schema.patchFileEntryMustBeObject'), severity: 'error' });
                 return;
               }
               const rel = rec['relativePath'];
               if (typeof rel !== 'string' || rel === '' || !isPathSafe(rel)) {
-                issues.push({ path: `patchFiles[${i}].relativePath`, message: 'patch 文件路径必须是安全的相对路径（不得为绝对路径或含 ..）', severity: 'error' });
+                issues.push({ path: `patchFiles[${i}].relativePath`, message: schemaMsg('schema.patchFilePathUnsafe'), severity: 'error' });
               }
               if (typeof rec['base64'] !== 'string') {
-                issues.push({ path: `patchFiles[${i}].base64`, message: 'patch 文件内容必须是 base64 字符串', severity: 'error' });
+                issues.push({ path: `patchFiles[${i}].base64`, message: schemaMsg('schema.patchFileContentMustBeBase64'), severity: 'error' });
               }
             });
           }
@@ -133,14 +149,31 @@ export function validateSectionData(sectionId: SectionId, data: unknown): Sectio
       break;
     }
     case 'files': {
-      if (!Array.isArray(obj['files'])) issues.push({ path: 'files', message: 'files 必须是数组', severity: 'error' });
+      const files = obj['files'];
+      if (!Array.isArray(files)) {
+        issues.push({ path: 'files', message: schemaMsg('schema.keyMustBeArray', { key: 'files' }), severity: 'error' });
+        break;
+      }
+      // 与 patchFiles 同级的防线（此前只判了 Array.isArray）：relativePath 会被写到 <home> 之下，
+      // 不可信 bundle 的路径穿越向量必须逐项过 isPathSafe（不得为绝对路径 / 含 ..）。
+      files.forEach((entry, i) => {
+        const rec = (entry !== null && typeof entry === 'object') ? entry as Record<string, unknown> : null;
+        if (rec === null) {
+          issues.push({ path: `files[${i}]`, message: schemaMsg('schema.fileEntryMustBeObject'), severity: 'error' });
+          return;
+        }
+        const rel = rec['relativePath'];
+        if (typeof rel !== 'string' || rel === '' || !isPathSafe(rel)) {
+          issues.push({ path: `files[${i}].relativePath`, message: schemaMsg('schema.filePathUnsafe'), severity: 'error' });
+        }
+      });
       break;
     }
     case 'none': {
       // secrets：凭据值走独立加密容器（.credentials.yaml / secrets.enc），没有分区 JSON 可校验
       issues.push({
         path: '$',
-        message: `分区 ${meta.id} 无 JSON 载荷（凭据值走独立加密容器，不参与分区 JSON 校验）`,
+        message: schemaMsg('schema.sectionNoJsonPayload', { section: meta.id }),
         severity: 'error',
       });
       break;
@@ -148,7 +181,7 @@ export function validateSectionData(sectionId: SectionId, data: unknown): Sectio
     default: {
       // 判别联合已穷尽：新增 payload.kind 时此赋值会编译失败（提醒补校验分支）
       const exhaustive: never = payload;
-      issues.push({ path: '$', message: `未处理的分区载荷形态 ${JSON.stringify(exhaustive)}`, severity: 'error' });
+      issues.push({ path: '$', message: schemaMsg('schema.unhandledPayloadKind', { payload: JSON.stringify(exhaustive) }), severity: 'error' });
     }
   }
   return issues;

package/src/schema/index.ts

@@ -19,10 +19,12 @@
  * 本文件把 `./schema` 变成真实可用的运行时入口。
  *
  * 约束（勿破）：本文件只 import 同目录模块（`./config.ts` / `./section-registry.ts` / `./types.ts` /
- * `./versions.ts`）。`section-registry.ts` 自身只 import 一个**类型**（`type { SectionId }`），
- * 故本出口仍保持零 `node:` / 零 npm 依赖。
- * 不 import `../core/*`、不 import `node:*`、不 import 任何 UI / DSH 包——否则会破坏
- * headless 消费（见 `docs/spec/headless-consumption.md`）与 `tests/architecture-boundaries.test.ts`。
+ * `./versions.ts`）。`section-registry.ts` 自身仍然只 import 一个**类型**（`type { SectionId }`；
+ * 未注册分区的错误文案 t7 起在 `config.ts`，见那里）。
+ * 目标性质是**零 `node:` / 零 npm / 零 @deepseek-ai 依赖**（headless 消费：
+ * `docs/spec/headless-consumption.md`；client bundle 自包含）。唯一的跨层依赖是本域消息目录
+ * （`./messages.ts` → `../core/engine-locale.ts`，纯函数、零 node / 零 npm），不破坏该性质；
+ * 除此之外不得 import `../core/*`、`node:*` 或任何 UI / DSH 包。
  */
 
 /* —— 版本判定（唯一出口，业务代码零散落 `if (v === 1)`） —— */
@@ -44,6 +46,7 @@ export {
   SECTION_JSON_PATHS,
   SECTION_FILE_PREFIXES,
   isFileSection,
+  requireSectionMeta,
 } from './config.ts';
 
 /*
@@ -57,7 +60,6 @@ export {
   SECTION_DATA_VERSION,
   sectionMeta,
   sectionMetaOf,
-  requireSectionMeta,
   isSectionId,
   jsonPathOf,
   filePrefixOf,

package/src/schema/manifest.ts

@@ -6,6 +6,7 @@ import { parseJsonSafe } from '../utils/json.ts';
 import { CURRENT_SCHEMA_VERSION } from './versions.ts';
 import type { Manifest, Platform, SectionId } from './types.ts';
 import { SECTION_IDS } from './config.ts';
+import { schemaMsg } from './messages.ts';
 
 export const MANIFEST_FILE = 'manifest.json';
 export const CHECKSUMS_FILE = 'integrity/checksums.json';
@@ -57,7 +58,7 @@ export function parseManifest(raw: string): Manifest {
   const issues = validateManifest(parsed);
   const errors = issues.filter((i) => i.severity === 'error');
   if (errors.length > 0) {
-    throw new Error(`manifest.json 无效: ${errors.map((e) => e.message).join('; ')}`);
+    throw new Error(schemaMsg('schema.manifestInvalid', { issues: errors.map((e) => e.message).join('; ') }));
   }
   return parsed as Manifest;
 }
@@ -68,58 +69,58 @@ export interface ManifestIssue { path: string; message: string; severity: 'error
 export function validateManifest(m: unknown): ManifestIssue[] {
   const issues: ManifestIssue[] = [];
   if (m === null || typeof m !== 'object') {
-    return [{ path: '$', message: 'manifest 必须是对象', severity: 'error' }];
+    return [{ path: '$', message: schemaMsg('schema.manifestMustBeObject'), severity: 'error' }];
   }
   const obj = m as Record<string, unknown>;
 
   if (typeof obj['schemaVersion'] !== 'number') {
-    issues.push({ path: 'schemaVersion', message: 'schemaVersion 必须是数字', severity: 'error' });
+    issues.push({ path: 'schemaVersion', message: schemaMsg('schema.schemaVersionMustBeNumber'), severity: 'error' });
   }
 
   const exporter = obj['exporter'] as Record<string, unknown> | undefined;
   if (!exporter || typeof exporter !== 'object') {
-    issues.push({ path: 'exporter', message: 'exporter 缺失', severity: 'error' });
+    issues.push({ path: 'exporter', message: schemaMsg('schema.exporterMissing'), severity: 'error' });
   } else {
-    if (typeof exporter['name'] !== 'string') issues.push({ path: 'exporter.name', message: 'exporter.name 必须是字符串', severity: 'error' });
-    if (typeof exporter['version'] !== 'string') issues.push({ path: 'exporter.version', message: 'exporter.version 必须是字符串', severity: 'error' });
+    if (typeof exporter['name'] !== 'string') issues.push({ path: 'exporter.name', message: schemaMsg('schema.exporterNameMustBeString'), severity: 'error' });
+    if (typeof exporter['version'] !== 'string') issues.push({ path: 'exporter.version', message: schemaMsg('schema.exporterVersionMustBeString'), severity: 'error' });
   }
 
   const source = obj['source'] as Record<string, unknown> | undefined;
   if (!source || typeof source !== 'object') {
-    issues.push({ path: 'source', message: 'source 缺失', severity: 'error' });
+    issues.push({ path: 'source', message: schemaMsg('schema.sourceMissing'), severity: 'error' });
   } else {
-    if (typeof source['dshVersion'] !== 'string') issues.push({ path: 'source.dshVersion', message: 'source.dshVersion 必须是字符串', severity: 'error' });
-    if (typeof source['platform'] !== 'string') issues.push({ path: 'source.platform', message: 'source.platform 必须是字符串', severity: 'error' });
-    if (typeof source['arch'] !== 'string') issues.push({ path: 'source.arch', message: 'source.arch 必须是字符串', severity: 'error' });
+    if (typeof source['dshVersion'] !== 'string') issues.push({ path: 'source.dshVersion', message: schemaMsg('schema.sourceDshVersionMustBeString'), severity: 'error' });
+    if (typeof source['platform'] !== 'string') issues.push({ path: 'source.platform', message: schemaMsg('schema.sourcePlatformMustBeString'), severity: 'error' });
+    if (typeof source['arch'] !== 'string') issues.push({ path: 'source.arch', message: schemaMsg('schema.sourceArchMustBeString'), severity: 'error' });
   }
 
   if (typeof obj['exportedAt'] !== 'string' || Number.isNaN(Date.parse(obj['exportedAt']))) {
-    issues.push({ path: 'exportedAt', message: 'exportedAt 必须是合法 ISO-8601 时间', severity: 'error' });
+    issues.push({ path: 'exportedAt', message: schemaMsg('schema.exportedAtInvalid'), severity: 'error' });
   }
 
   const sections = obj['sections'] as Record<string, unknown> | undefined;
   if (!sections || typeof sections !== 'object') {
-    issues.push({ path: 'sections', message: 'sections 缺失', severity: 'error' });
+    issues.push({ path: 'sections', message: schemaMsg('schema.sectionsMissing'), severity: 'error' });
   } else {
     for (const key of Object.keys(sections)) {
       if (!(SECTION_IDS as readonly string[]).includes(key)) {
-        issues.push({ path: `sections.${key}`, message: `未知分区 "${key}"`, severity: 'warning' });
+        issues.push({ path: `sections.${key}`, message: schemaMsg('schema.unknownSection', { section: key }), severity: 'warning' });
       }
       if (typeof sections[key] !== 'boolean') {
-        issues.push({ path: `sections.${key}`, message: `sections.${key} 必须是布尔`, severity: 'error' });
+        issues.push({ path: `sections.${key}`, message: schemaMsg('schema.sectionFlagMustBeBoolean', { section: key }), severity: 'error' });
       }
     }
   }
 
   const security = obj['security'] as Record<string, unknown> | undefined;
   if (!security || typeof security !== 'object') {
-    issues.push({ path: 'security', message: 'security 缺失', severity: 'error' });
+    issues.push({ path: 'security', message: schemaMsg('schema.securityMissing'), severity: 'error' });
   } else {
-    if (typeof security['containsSecrets'] !== 'boolean') issues.push({ path: 'security.containsSecrets', message: 'containsSecrets 必须是布尔', severity: 'error' });
-    if (typeof security['encrypted'] !== 'boolean') issues.push({ path: 'security.encrypted', message: 'encrypted 必须是布尔', severity: 'error' });
+    if (typeof security['containsSecrets'] !== 'boolean') issues.push({ path: 'security.containsSecrets', message: schemaMsg('schema.containsSecretsMustBeBoolean'), severity: 'error' });
+    if (typeof security['encrypted'] !== 'boolean') issues.push({ path: 'security.encrypted', message: schemaMsg('schema.encryptedMustBeBoolean'), severity: 'error' });
     const enc = security['encryption'];
     if (enc !== null && (typeof enc !== 'object' || enc === undefined)) {
-      issues.push({ path: 'security.encryption', message: 'encryption 必须是对象或 null', severity: 'error' });
+      issues.push({ path: 'security.encryption', message: schemaMsg('schema.encryptionMustBeObjectOrNull'), severity: 'error' });
     }
   }