dsh-config-manager 0.1.71 → 0.1.73

package/src/core/model-tools.ts

@@ -20,6 +20,7 @@
  *   - config_sync_pull 零写入（只 analyze+plan 出差异）；落地需另走确认导入管道；
  *   - 分区/路径走既有白名单（SECTION_IDS 过滤；同步引擎 portable + FORBIDDEN_SECTIONS 双保险）。
  */
+import { engineMsg } from './messages-core.ts';
 import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { randomBytes } from 'node:crypto'
@@ -68,7 +69,7 @@ export interface ModelToolsDeps {
 /** 快照 id 校验：拒绝路径分隔符与 `.`/`..`（防 join(snapshotsDir, id) 越界）。 */
 function assertValidSnapshotId(snapshotId: string): void {
   if (snapshotId === '' || snapshotId.includes('/') || snapshotId.includes('\\')) {
-    throw new Error(`非法快照 id：${JSON.stringify(snapshotId)}`)
+    throw new Error(engineMsg('core.modelTools.illegalSnapshotId', { id: JSON.stringify(snapshotId) }))
   }
 }
 
@@ -99,7 +100,7 @@ async function resolveEngine(
   const ch: SyncTransportType = channel ?? parseSyncChannel(full?.transport) ?? 'git'
   const cfg = await readSyncConfigFor(deps.syncDir, ch)
   if (cfg === null) {
-    throw new Error(`同步通道 ${ch} 尚未配置（sync-config.json 缺失或损坏）`)
+    throw new Error(engineMsg('core.modelTools.syncChannelNotConfigured', { channel: ch }))
   }
   return { engine: deps.makeSyncEngine(cfg), channel: ch }
 }
@@ -171,7 +172,7 @@ export function createModelTools(deps: ModelToolsDeps) {
       const { snapshotId, confirm } = input
       assertValidSnapshotId(snapshotId)
       if (!(await snapshotDirExists(deps, snapshotId))) {
-        throw new Error(`快照不存在：${snapshotId}（用 config_list_snapshots 查看可用快照）`)
+        throw new Error(engineMsg('core.modelTools.snapshotNotFound', { id: snapshotId }))
       }
       const snapshotDir = join(deps.snapshotsDir, snapshotId)
       // profile：host.profile 由宿主 resolveProfileName 保证非空（缺省 'web'，见 ConfigManagerHostContext），
@@ -315,7 +316,7 @@ type ModelTools = ReturnType<typeof createModelTools>
 export function registerModelTools(ctx: Context, deps: ModelToolsDeps): void {
   const toolsSvc = ctx.get('tools')
   if (toolsSvc === null || toolsSvc === undefined || typeof toolsSvc !== 'object') {
-    deps.host.log.warn?.('tools 服务不可用：跳过模型工具注册（引擎能力仍可用）')
+    deps.host.log.warn?.(engineMsg('core.modelTools.toolsServiceUnavailable'))
     return
   }
   const tools: ModelTools = createModelTools(deps)
@@ -329,22 +330,22 @@ export function registerModelTools(ctx: Context, deps: ModelToolsDeps): void {
 
   register(defineTool({
     name: 'config_backup',
-    description: '全量备份 DSH 配置到本地 exports 目录（默认不含 secret；可传 password 加密导出）。返回 ZIP 文件名/大小/分区清单/加密状态。',
+    description: engineMsg('core.modelTools.backupToolDesc'),
     parameters: {
       only: {
         type: 'array',
         items: { type: 'string', enum: [...SECTION_IDS] },
-        description: '仅导出的分区 id 白名单；缺省 = 全部推荐分区',
+        description: engineMsg('core.modelTools.backupOnlyParam'),
       },
       password: {
         type: 'string',
-        description: '可选：加密备份密码（仅内存，不落盘/不回显；提供即加密导出）',
+        description: engineMsg('core.modelTools.backupPasswordParam'),
       },
     },
     output: {
       schema: {
         type: 'json',
-        description: '备份结果（zip 文件名 / sizeBytes / 分区清单 / excluded / encrypted / containsSecrets / redactedHits / warnings）',
+        description: engineMsg('core.modelTools.backupOutputDesc'),
       },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
@@ -355,12 +356,12 @@ export function registerModelTools(ctx: Context, deps: ModelToolsDeps): void {
 
   register(defineTool({
     name: 'config_list_snapshots',
-    description: '列出 DSH 配置的本地回滚快照（id / 创建时间 / 来源 / 状态 / 条目数），供后续 config_restore 使用。',
+    description: engineMsg('core.modelTools.listSnapshotsToolDesc'),
     parameters: {},
     output: {
       schema: {
         type: 'json',
-        description: '快照数组（id / createdAt / sourceZip / status / entryCount）',
+        description: engineMsg('core.modelTools.listSnapshotsOutputDesc'),
       },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
@@ -372,20 +373,20 @@ export function registerModelTools(ctx: Context, deps: ModelToolsDeps): void {
   register(defineTool({
     name: 'config_restore',
     description:
-      '恢复到指定快照。默认只返回动作计划（零写入）；确认要真实执行时传 confirm:true（会覆盖/删除 $DSH_HOME 文件并卸载导入期间新增插件，属破坏性操作，务必先预览）。',
+      engineMsg('core.modelTools.restoreToolDesc'),
     parameters: {
       snapshotId: {
         type: 'string',
         required: true,
-        description: '要恢复的快照 id（用 config_list_snapshots 获取）',
+        description: engineMsg('core.modelTools.restoreSnapshotIdParam'),
       },
       confirm: {
         type: 'boolean',
-        description: 'true 才真实执行恢复；缺省 false 只预览计划（零写入）',
+        description: engineMsg('core.modelTools.restoreConfirmParam'),
       },
     },
     output: {
-      schema: { type: 'json', description: 'dryRun=true 时为恢复计划；dryRun=false 时为执行报告' },
+      schema: { type: 'json', description: engineMsg('core.modelTools.restoreOutputDesc') },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
     async execute(args) {
@@ -396,33 +397,33 @@ export function registerModelTools(ctx: Context, deps: ModelToolsDeps): void {
   register(defineTool({
     name: 'config_sync_push',
     description:
-      '手动推送 DSH 配置同步到远端（Git/WebDAV），复用已持久化的通道配置。写远端属主动操作；加密/含凭据须传 password 且引擎强制 encrypt。',
+      engineMsg('core.modelTools.syncPushToolDesc'),
     parameters: {
       channel: {
         type: 'string',
         enum: [...SYNC_CHANNELS],
-        description: '同步通道；缺省 = 已配置的活动通道',
+        description: engineMsg('core.modelTools.channelParam'),
       },
       sections: {
         type: 'array',
         items: { type: 'string', enum: [...SECTION_IDS] },
-        description: '仅推送的分区；缺省 = 全部推荐 portable 分区（非 portable 自动跳过）',
+        description: engineMsg('core.modelTools.syncPushSectionsParam'),
       },
       encrypt: {
         type: 'boolean',
-        description: '加密快照；开启必须提供 password',
+        description: engineMsg('core.modelTools.syncPushEncryptParam'),
       },
       includeSecrets: {
         type: 'boolean',
-        description: '推送真实凭据值（必须同时 encrypt=true，否则引擎拒绝）',
+        description: engineMsg('core.modelTools.syncPushIncludeSecretsParam'),
       },
       password: {
         type: 'string',
-        description: '加密密码（仅内存，不落盘/不回显）',
+        description: engineMsg('core.modelTools.syncPushPasswordParam'),
       },
     },
     output: {
-      schema: { type: 'json', description: '推送报告（snapshotId / 实际同步分区 / 告警）' },
+      schema: { type: 'json', description: engineMsg('core.modelTools.syncPushOutputDesc') },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
     async execute(args) {
@@ -433,29 +434,29 @@ export function registerModelTools(ctx: Context, deps: ModelToolsDeps): void {
   register(defineTool({
     name: 'config_sync_pull',
     description:
-      '拉取远端同步差异预览（Git/WebDAV，零写入：只下载 + 分析出差异报告，绝不直接写配置）。若要落地差异需另走确认导入管道。',
+      engineMsg('core.modelTools.syncPullToolDesc'),
     parameters: {
       channel: {
         type: 'string',
         enum: [...SYNC_CHANNELS],
-        description: '同步通道；缺省 = 已配置的活动通道',
+        description: engineMsg('core.modelTools.channelParam'),
       },
       snapshotId: {
         type: 'string',
-        description: '远端快照 id；缺省 = 最新',
+        description: engineMsg('core.modelTools.syncPullSnapshotIdParam'),
       },
       strategy: {
         type: 'string',
         enum: ['merge', 'replace', 'skipExisting'],
-        description: '冲突全局策略；缺省 merge（冲突保留待决策）',
+        description: engineMsg('core.modelTools.syncPullStrategyParam'),
       },
       password: {
         type: 'string',
-        description: '解密密码（加密快照需要；仅内存）',
+        description: engineMsg('core.modelTools.syncPullPasswordParam'),
       },
     },
     output: {
-      schema: { type: 'json', description: '差异报告（changes 列表 / needsReview）' },
+      schema: { type: 'json', description: engineMsg('core.modelTools.syncPullOutputDesc') },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
     async execute(args) {

package/src/core/phase3-host.ts

@@ -22,11 +22,12 @@ import { inspectStartup, type ReconcileProbeHooks, type ReconcileEnv } from './r
 import { OWNERSHIP_FILE, type LockState, type MutationLockContext } from '../utils/env-lock.ts';
 import { sha256Hex } from '../utils/hashing.ts';
 import type { JournalStepRecord } from './types.ts';
+import { engineMsg } from './messages-core.ts';
 
 /** 存在未收敛的 active transaction → 拒绝创建第二个（active≤1）。 */
 export class TransactionRecoveryRequiredError extends Error {
   constructor(opId: string) {
-    super(`active transaction ${opId} 未收敛（待 recover / reconcile），拒绝创建新 transaction`)
+    super(engineMsg('core.phase3.transactionNotConverged', { opId }))
     this.name = 'TransactionRecoveryRequiredError'
   }
 }
@@ -75,6 +76,9 @@ export interface JournalRunContext {
 export function mapLockStateForStartup(state: LockState): 'LOCKED' | 'STALE_LOCK_DETECTED' | 'UNKNOWN_STATE' | 'FREE' {
   if (state === 'STALE_LOCK_DETECTED') return 'STALE_LOCK_DETECTED';
   if (state === 'UNKNOWN_STATE') return 'UNKNOWN_STATE';
+  // issue #79：FREE（ownership 确实不存在）如实透传。此前它落到下面的兜底被映射成 LOCKED ——
+  // 与 inspectLockState 的 missing→LOCKED 一起，把「没有锁」的系统性误报成「有活跃锁」。
+  if (state === 'FREE') return 'FREE';
   return 'LOCKED'; // ACQUIRED / LOCKED / LOCK_IO_ERROR / PERMISSION_ERROR → 保守 LOCKED
 }
 
@@ -209,7 +213,19 @@ export class Phase3Recovery {
         if (step.beforeFp !== null && fp === step.beforeFp) return 'before-match';
         return 'none';
       },
-      probeExternal: async () => 'unknown',
+      // issue #87：external step 的**真实只读探测**（仅在 journal 里确实记录了指纹时才可能得出结论）。
+      // 语义仍是「证不出来就说 unknown」：ref 为空 / 无指纹 / 读失败 / 与两个指纹都不符 → unknown。
+      // 注意：runExternalIntent 目前写入的 external step 恒无指纹（beforeFp/afterFp 皆 null），
+      // 对它们本探测必然返回 unknown —— 那是刻意的，放行判断在 reconcile 的「可自证残留」门（独立判据）。
+      probeExternal: async (step) => {
+        if (step.ref === '' || step.beforeFp === null || step.afterFp === null) return 'unknown'
+        let data: Buffer
+        try { data = await fs.readFile(step.ref) } catch { return 'unknown' }
+        const fp = sha256Hex(data)
+        if (fp === step.afterFp) return 'installed'
+        if (fp === step.beforeFp) return 'not-installed'
+        return 'unknown'
+      },
       snapshotExists: async (snapshotId, binding) => {
         if (snapshotExists === undefined) return false; // 未注入 → 保守 false
         return snapshotExists(snapshotId, binding);
@@ -330,7 +346,7 @@ export class Phase3Recovery {
         const snapId = await snapshotProvider();
         // P1-2 修复：snapshotProvider 返回 null 表示快照创建失败 → 显式 abort（不得在无快照下继续 mutation）
         if (snapId === null) {
-          throw new Error(`snapshotProvider 返回 null（快照创建失败），abort operation ${operationType}`);
+          throw new Error(engineMsg('core.phase3.snapshotProviderNull', { operationType }));
         }
         await journalCtx.bindSnapshot(snapId);
       } else if (deferredSnapshot !== true) {
@@ -446,7 +462,7 @@ export class Phase3Recovery {
       environmentFingerprint: this.environmentFingerprint || 'unknown',
       ownerInstanceId,
       bindSnapshot: async (snapshotId: string) => {
-        if (snapshotId === null || snapshotId === '') throw new Error('bindSnapshot: snapshotId 为空');
+        if (snapshotId === null || snapshotId === '') throw new Error(engineMsg('core.phase3.bindSnapshotEmptyId'));
         // Reviewer A P2①：持久化失败必须传播（fail-closed）——若 journal 无法 durable 绑定 SNAPSHOT_CREATED，
         // 引擎的 await bindSnapshot 抛错 → fn 抛错 → runJournaled catch（NEEDS_ATTENTION），mutation 绝不在无绑定下继续。
         await this.store.update(opId, (j) => {
@@ -454,7 +470,7 @@ export class Phase3Recovery {
           if (next.state === 'CREATED') next = transitionJournalState(next, 'SNAPSHOT_CREATED');
           else if (next.state === 'SNAPSHOT_CREATED') { /* 幂等：已绑定 */ }
           else if (next.state === 'APPLYING') { /* 允许：绑定已晚但幂等记录 */ }
-          else throw new Error(`bindSnapshot 非法 state: ${next.state}`);
+          else throw new Error(engineMsg('core.phase3.bindSnapshotIllegalState', { state: next.state }));
           return next;
         });
       },

package/src/core/phase3-p2b-fingerprint.test.ts

@@ -68,6 +68,28 @@ test('verifyStepFingerprint：本地文件 step 真实磁盘指纹判定', async
   assert.equal(await hooks.verifyStepFingerprint({ adapter: 'plugins', ref: 'plugin:@x', kind: 'Install', external: true, beforeFp: null, afterFp: null, status: 'planned', appliedAt: null }), 'unable');
 });
 
+test('issue #87 probeExternal：有指纹时做真实只读探测；证不出来一律 unknown（默认保守语义不变）', async (t) => {
+  const dir = tmp(t);
+  const recovery = await makeRecovery(dir);
+  const target = path.join(dir, 'artifact.bin');
+  const fpA = sha256Hex(Buffer.from('A'));
+  const fpB = sha256Hex(Buffer.from('B'));
+  const step = (beforeFp: string | null, afterFp: string | null, ref = target): import('./journal.ts').JournalStep => ({
+    adapter: 'plugins', ref, kind: 'Install', external: true, beforeFp, afterFp, status: 'planned', appliedAt: null,
+  });
+  const hooks = recovery.recoveryHooks;
+
+  fssync.writeFileSync(target, 'A');
+  assert.equal(await hooks.probeExternal(step(fpA, fpB)), 'not-installed', '磁盘仍等于 beforeFp → 可自证未装');
+  fssync.writeFileSync(target, 'B');
+  assert.equal(await hooks.probeExternal(step(fpA, fpB)), 'installed', '磁盘等于 afterFp → 已装');
+  fssync.writeFileSync(target, 'C');
+  assert.equal(await hooks.probeExternal(step(fpA, fpB)), 'unknown', '与两个指纹都不符 → unknown（绝不猜）');
+  assert.equal(await hooks.probeExternal(step(null, null)), 'unknown', '无指纹（runExternalIntent 的真实形态）→ unknown');
+  assert.equal(await hooks.probeExternal(step(fpA, fpB, '')), 'unknown', 'ref 为空 → unknown');
+  assert.equal(await hooks.probeExternal(step(fpA, fpB, path.join(dir, 'missing.bin'))), 'unknown', '读失败 → unknown');
+});
+
 // ---------- 2. recordStep 持久化 ----------
 
 test('runJournaled journalCtx.recordStep：文件/外部 step 落 journal', async (t) => {

package/src/core/plugin-cli.ts

@@ -15,6 +15,7 @@
  * 只依赖 node 内置模块，零 DSH 运行时依赖（M5 的 TDD 可直接单测本模块）。
  */
 
+import { engineMsg } from './messages-core.ts';
 import { spawn } from 'node:child_process'
 import type { ChildProcess, SpawnOptions } from 'node:child_process'
 import { readFileSync, rmSync } from 'node:fs'
@@ -609,35 +610,35 @@ export function classifyDshPluginFailure(output: string): DshPluginFailure | nul
     return {
       code: 'hoist-pattern-diff',
       recoverable: true,
-      message: 'profile 的 node_modules 由旧版 pnpm 创建，与当前 pnpm 的默认配置不兼容；在 profile 目录执行一次 pnpm install 重建后重试 / this profile\'s node_modules was created by a different pnpm major; rebuild it (pnpm install) before retrying',
+      message: engineMsg('core.pluginCli.hoistPatternDiff'),
     }
   }
   if (output.includes('ERR_PNPM_ADDING_TO_ROOT')) {
     return {
       code: 'adding-to-root',
       recoverable: true,
-      message: 'profile 是 pnpm workspace，当前 dsh CLI 转发未带 -w 被 pnpm 拒绝；可手动执行 dsh plugin --profile <name> add -w <pkg> / pnpm refused to add at a workspace root (missing -w); run dsh plugin --profile <name> add -w <pkg> by hand',
+      message: engineMsg('core.pluginCli.addingToRoot'),
     }
   }
   if (/--workspace-root may only be used inside a workspace/i.test(output)) {
     return {
       code: 'not-a-workspace',
       recoverable: false,
-      message: 'profile 目录不是 pnpm workspace，却传入了 -w，因此被 pnpm 拒绝 / -w was passed but the profile is not a pnpm workspace, so pnpm refused the operation',
+      message: engineMsg('core.pluginCli.notAWorkspace'),
     }
   }
   if (output.includes('ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION') || output.includes('ERR_PNPM_NO_MATURE_MATCHING_VERSION')) {
     return {
       code: 'release-age-violation',
       recoverable: true,
-      message: 'profile 里有刚发布不久的插件版本，pnpm 的安全等待期检查拒绝了本次改动（即使改的是别的插件）；等待发布期满，或临时以 --config.minimumReleaseAge=0 重试 / a recently-published plugin version in this profile trips pnpm\'s fresh-release safety check, blocking any change (even to other plugins); wait for the release to mature, or retry once with --config.minimumReleaseAge=0',
+      message: engineMsg('core.pluginCli.releaseAgeViolation'),
     }
   }
   if (output.includes('ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED') || /git-hosted package "[^"]+" needs to execute build scripts/i.test(output)) {
     return {
       code: 'git-build-blocked',
       recoverable: false,
-      message: '该 git 插件需要在安装时执行构建脚本，被 pnpm 的 allowBuilds 白名单拦截；把 pnpm 提示的包名加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试 / this git-hosted plugin needs to run its build script at install time, which pnpm blocks until allowed — add the exact package pnpm printed to allowBuilds in the profile\'s pnpm-workspace.yaml, then re-run',
+      message: engineMsg('core.pluginCli.gitBuildBlocked'),
     }
   }
   // issue #35：pnpm-workspace.yaml 的 patchedDependencies 指向不存在的 patch 文件时，
@@ -647,29 +648,27 @@ export function classifyDshPluginFailure(output: string): DshPluginFailure | nul
     // 路径可能含盘符冒号（C:\...），故按整行取、再切掉尾随的 ':' 或 ': <错误文本>'
     const raw = /Failed to read patch file\s+([^\r\n]+)/i.exec(output)?.[1]?.trim()
     const file = raw === undefined ? undefined : raw.split(/:\s/)[0]?.replace(/:\s*$/, '').trim()
-    const zh = file === undefined ? '' : `（${file}）`
-    const en = file === undefined ? '' : ` (${file})`
+    const patchSuffix = file === undefined ? '' : engineMsg('core.pluginCli.parenValue', { value: file })
     return {
       code: 'patch-file-missing',
       recoverable: false,
-      message: `profile 的 pnpm-workspace.yaml 声明了 patchedDependencies，但对应的 patch 文件不存在${zh}；pnpm 因此拒绝任何安装（含与补丁无关的插件）。把缺失的 patch 文件放回 profile 的 patches/ 目录，或从 pnpm-workspace.yaml 删除该条目后重试 / the profile's pnpm-workspace.yaml declares patchedDependencies but the patch file is missing${en}; pnpm then refuses every install (even unrelated plugins). Put the patch file back under the profile's patches/ directory, or remove that entry from pnpm-workspace.yaml and retry`,
+      message: engineMsg('core.pluginCli.patchFileMissing', { patch: patchSuffix }),
     }
   }
   if (output.includes('ERR_PNPM_FETCH_404')) {
     const pkg = /GET\s+\S*\/([^/\s]+):/.exec(output)?.[1]?.replace(/%2[Ff]/g, '/')
-    const zh = pkg === undefined ? '' : `（${pkg}）`
-    const en = pkg === undefined ? '' : ` (${pkg})`
+    const pkgSuffix = pkg === undefined ? '' : engineMsg('core.pluginCli.parenValue', { value: pkg })
     return {
       code: 'fetch-404',
       recoverable: false,
-      message: `有一个依赖在 registry 上不存在${zh}，pnpm 拒绝任何安装操作；它可能是之前失败操作残留在 profile package.json 里的幽灵依赖（手动删除该行），也可能是需要登录的私有包 / a dependency cannot be resolved from the registry${en}; pnpm refuses every install while it is present — it may be a ghost entry left in the profile's package.json by an earlier failed operation (remove that line by hand), or a private package needing registry credentials`,
+      message: engineMsg('core.pluginCli.fetch404', { pkg: pkgSuffix }),
     }
   }
   if (isTransientDshPluginFailure(output)) {
     return {
       code: 'transient-network',
       recoverable: true,
-      message: '拉取依赖时网络临时失败（安装会重放整个依赖树，任何一个既有依赖抖动都会中断本次操作）；稍后直接重试通常即可 / a transient network failure while fetching dependencies (installs replay the whole dependency tree, so any existing dependency can hiccup); a plain retry usually succeeds',
+      message: engineMsg('core.pluginCli.transientNetwork'),
     }
   }
   // 桌面端保留档案：普通 dsh CLI（< 0.2 的旧版尤其）对 `--profile desktop` 直接报
@@ -680,14 +679,14 @@ export function classifyDshPluginFailure(output: string): DshPluginFailure | nul
     return {
       code: 'desktop-profile-reserved',
       recoverable: false,
-      message: 'desktop 是 DeepSeek Harness Desktop 独占管理的保留档案，普通 dsh CLI 拒绝操作它；请在桌面端应用内重试（新版本插件会自动改用桌面端自带的 CLI 载体），或改用其它档案 / the "desktop" profile is managed exclusively by the DeepSeek Harness Desktop application and the plain dsh CLI refuses to touch it; retry from inside the Desktop app (a current version of this plugin switches to the Desktop-bundled CLI carrier) or target another profile',
+      message: engineMsg('core.pluginCli.desktopProfileReserved'),
     }
   }
   if (output.includes('pnpm not found on PATH')) {
     return {
       code: 'pnpm-missing',
       recoverable: false,
-      message: '找不到 pnpm（dsh 转发 pnpm 失败）：请先安装 pnpm（npm install -g pnpm 或 corepack enable pnpm），然后重试 / pnpm is not on PATH (dsh forwards to pnpm): install pnpm (npm install -g pnpm or corepack enable pnpm) and retry',
+      message: engineMsg('core.pluginCli.pnpmMissing'),
     }
   }
   return null
@@ -696,18 +695,18 @@ export function classifyDshPluginFailure(output: string): DshPluginFailure | nul
 /** 安装失败 → 分类后的双语可读 Error；未识别则保留 stderr 尾部摘要。 */
 export function installErrorFor(pkg: string, result: DshPluginResult): Error {
   if (result.spawnError !== undefined && /ENOENT|EINVAL/.test(result.spawnError)) {
-    return new Error(`无法启动 dsh CLI（${result.spawnError}）：请确认 dsh 已安装且在 PATH 上，然后重试安装 ${pkg} / cannot start dsh CLI (${result.spawnError}): make sure dsh is installed and on PATH, then retry installing ${pkg}`)
+    return new Error(engineMsg('core.pluginCli.dshCliStartFailed', { spawnError: result.spawnError, pkg }))
   }
   if (result.timedOut) {
-    return new Error(`安装 ${pkg} 超时（进程已终止，默认 15 分钟）：请检查网络或稍后重试 / install ${pkg} timed out (process killed, default 15 min): check your network and retry later`)
+    return new Error(engineMsg('core.pluginCli.installTimeout', { pkg }))
   }
   const output = `${result.stderr}\n${result.stdout}`
   const failure = classifyDshPluginFailure(output)
   if (failure !== null) {
-    return new Error(`安装 ${pkg} 失败（${failure.code}）：${failure.message}`)
+    return new Error(engineMsg('core.pluginCli.installFailed', { pkg, code: failure.code, message: failure.message }))
   }
   const tail = (result.stderr.trim().split('\n').slice(-8).join('\n')
     || result.stdout.trim().split('\n').slice(-8).join('\n')
-    || '无输出')
-  return new Error(`dsh plugin 安装 ${pkg} 失败（exit ${String(result.exitCode)}）：${tail}`)
+    || engineMsg('core.pluginCli.noOutput'))
+  return new Error(engineMsg('core.pluginCli.installFailedWithTail', { pkg, exitCode: String(result.exitCode), tail }))
 }

package/src/core/plugin-data-registry.test.ts

@@ -0,0 +1,113 @@
+/**
+ * pluginData / pluginAssets 来源注册表的纯函数单测（零 I/O）。
+ *
+ * 这里钉的是「收录口径」的四条硬性质：
+ *  ① 区域归属（角色 → 分区）与内置来源的取证标签；
+ *  ② 最长前缀归属 —— 大资产不能被短前缀的配置区域吞掉；
+ *  ③ 排除与安全（cache 不进包；非法 home 相对路径一律拒绝）；
+ *  ④ 自述声明（dsh.dataDirs）的形状解析：不认识就整条丢弃，绝不猜。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  BUILTIN_PLUGIN_DATA_SOURCES, areaOfPath, areasForSection, isExcludedRel, normalizeHomeRel,
+  parseDeclaredDataDirs, relInArea, sectionOfRole,
+} from './plugin-data-registry.ts';
+import type { PluginDataArea, PluginDataSource } from './plugin-data-registry.ts';
+
+/** 区域条目（与 adapter 的 PluginDataEntry 同形；core 测试不反向依赖 adapters 层） */
+type AreaEntry = { source: PluginDataSource; area: PluginDataArea };
+
+const ALL: AreaEntry[] = [];
+for (const source of BUILTIN_PLUGIN_DATA_SOURCES) {
+  for (const area of source.areas) ALL.push({ source, area });
+}
+
+test('全局唯一来源：id 不重复，且每个来源都如实标注取证强度', () => {
+  const ids = BUILTIN_PLUGIN_DATA_SOURCES.map((s) => s.id);
+  assert.equal(new Set(ids).size, ids.length);
+  for (const s of BUILTIN_PLUGIN_DATA_SOURCES) {
+    assert.ok(['measured', 'fixture', 'documented'].includes(s.evidence), s.id);
+    assert.ok(s.areas.length > 0, s.id);
+  }
+  // 本机实测的两个来源必须真有 measured 证据（其余是文档取证，不得美化）
+  assert.equal(BUILTIN_PLUGIN_DATA_SOURCES.find((s) => s.id === 'mnemon')?.evidence, 'measured');
+});
+
+test('角色 → 分区：config 进 pluginData，assets 进 pluginAssets，cache 两个都不进', () => {
+  assert.equal(sectionOfRole('config'), 'pluginData');
+  assert.equal(sectionOfRole('assets'), 'pluginAssets');
+  assert.equal(sectionOfRole('cache'), null);
+
+  const config = areasForSection(BUILTIN_PLUGIN_DATA_SOURCES, 'pluginData').map((e) => e.area.relPath);
+  const assets = areasForSection(BUILTIN_PLUGIN_DATA_SOURCES, 'pluginAssets').map((e) => e.area.relPath);
+  assert.ok(config.includes('.dsh-wallpaper-engine'));
+  assert.ok(config.includes('.mnemon/runtime'));
+  assert.ok(!config.includes('.dsh-wallpaper-engine/uploads'), '大资产不得出现在配置分区');
+  assert.ok(assets.includes('.dsh-wallpaper-engine/uploads'));
+  assert.ok(assets.includes('.mnemon/data'));
+  assert.ok(![...config, ...assets].includes('.dsh-wallpaper-engine/cache'), '缓存永不进任何分区');
+});
+
+test('最长前缀归属：uploads 下的文件归 uploads 区域，不是它祖先的配置区域', () => {
+  const hit = areaOfPath(ALL, '.dsh-wallpaper-engine/uploads/a.mp4');
+  assert.equal(hit?.area.relPath, '.dsh-wallpaper-engine/uploads');
+  assert.equal(hit?.area.role, 'assets');
+
+  // 配置分区视角：upload 路径被祖先区域的 excludeRel 挡住 → 判 null（导入侧据此拒绝写）
+  const configOnly = areasForSection(BUILTIN_PLUGIN_DATA_SOURCES, 'pluginData');
+  assert.equal(areaOfPath(configOnly, '.dsh-wallpaper-engine/uploads/a.mp4'), null);
+  assert.equal(areaOfPath(configOnly, '.dsh-wallpaper-engine/config.json')?.area.relPath, '.dsh-wallpaper-engine');
+});
+
+test('relInArea / isExcludedRel：文件区域精确匹配，目录区域前缀匹配', () => {
+  const fileArea = { relPath: '.x/state.json', role: 'config' as const };
+  assert.equal(relInArea(fileArea, '.x/state.json'), true);
+  assert.equal(relInArea(fileArea, '.x/state.json.bak'), false);
+
+  const dirArea = { relPath: '.x', role: 'config' as const, excludeRel: ['cache'] };
+  assert.equal(relInArea(dirArea, '.x/a/b'), true);
+  assert.equal(isExcludedRel(dirArea, '.x/cache'), true);
+  assert.equal(isExcludedRel(dirArea, '.x/cache/deep/b'), true);
+  assert.equal(isExcludedRel(dirArea, '.x/cacheX'), false, '前缀必须是完整路径段');
+  assert.equal(isExcludedRel(dirArea, '.x/a'), false);
+});
+
+test('normalizeHomeRel：拒绝一切可能越界的写法，反斜杠归一为 POSIX', () => {
+  assert.equal(normalizeHomeRel('.a/b'), '.a/b');
+  assert.equal(normalizeHomeRel('.a\\b'), '.a/b');
+  assert.equal(normalizeHomeRel('  .a/b  '), '.a/b');
+
+  for (const bad of ['', '  ', '/abs/x', 'C:/x', 'a/../b', '..', './a', 'a/', 'a//b', 'a/\u0000b', 42, null, undefined]) {
+    assert.equal(normalizeHomeRel(bad), null, JSON.stringify(bad));
+  }
+});
+
+test('parseDeclaredDataDirs：合法声明解析成来源；形状不认识整条丢弃（不猜）', () => {
+  const source = parseDeclaredDataDirs('dsh-fake', {
+    dsh: { dataDirs: [
+      { path: '.fake-plugin', role: 'config', env: ['FAKE_DATA_DIR'] },
+      { path: '.fake-plugin/uploads', role: 'assets', exclude: ['tmp'] },
+    ] },
+  });
+  assert.ok(source);
+  assert.equal(source?.id, 'declared:dsh-fake');
+  assert.deepEqual(source?.packages, ['dsh-fake']);
+  assert.equal(source?.areas.length, 2);
+  assert.deepEqual(source?.areas[0]?.envOverrides, ['FAKE_DATA_DIR']);
+  assert.deepEqual(source?.areas[1]?.excludeRel, ['tmp']);
+  assert.equal(source?.areas[1]?.role, 'assets');
+
+  // 缺省角色 = config
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: [{ path: '.p' }] } })?.areas[0]?.role, 'config');
+
+  // 整条丢弃的形态
+  assert.equal(parseDeclaredDataDirs('p', null), null);
+  assert.equal(parseDeclaredDataDirs('p', {}), null);
+  assert.equal(parseDeclaredDataDirs('p', { dsh: {} }), null);
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: [] } }), null);
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: 'nope' } }), null);
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: [{ path: '/abs' }] } }), null, '绝对路径 → 整条丢弃');
+  assert.equal(parseDeclaredDataDirs('p', { dsh: { dataDirs: [{ path: '.ok' }, { path: '../escape' }] } }), null, '任一非法 → 整条丢弃');
+});