dsh-config-manager 0.1.73 → 0.1.77

package/lib/core/types.d.ts

@@ -145,6 +145,24 @@ export interface ExportUnit {
      * 只下发**事实**，不下发文案 —— 界面按当前语言显示（与 DSH 同口径），绝不用 uuid 冒充标题。
      */
     blank?: boolean;
+    /**
+     * 该插件**声明的第三方数据区域**（只有 \`plugin:<包名>\` 单元可能有值；导出选择器「按插件看」用）。
+     *
+     * 用途：选择器要在**不读任何数据目录**的前提下画出「插件 → 数据目录 / 大文件」的树骨架 ——
+     * 区域清单来自来源注册表（内置来源表 + 插件自述 dsh.dataDirs），是静态知识，零额外 I/O；
+     * 体积与「实际有没有内容」等该分区的清单到货后再填。
+     *
+     * 语义：**纯展示**，不参与勾选/导出契约（契约只认 id）。这里是「注册表说它应该在哪儿」，
+     * **不是**「磁盘上确实有」—— 界面必须把两者分开渲染（unread / 无内容 / 已读到）。
+     */
+    relatedAreas?: readonly PluginAreaRef[];
+}
+/** 插件数据区域引用（pluginData / pluginAssets；只读展示用，不参与勾选契约）。 */
+export interface PluginAreaRef {
+    section: 'pluginData' | 'pluginAssets';
+    /** home 相对 POSIX 路径 —— 就是该分区单元的 id 后缀（\`pluginData:.mnemon/runtime\` 的末段） */
+    relPath: string;
+    role: 'config' | 'assets';
 }
 export interface ValidationResult {
     valid: boolean;

package/lib/index.d.ts

@@ -78,7 +78,7 @@ export declare const name = "config-manager";
 /** Services required before the engine can mount (present in every profile). */
 export declare const inject: string[];
 /** Plugin version, kept in sync with package.json ("version"). */
-export declare const PLUGIN_VERSION = "0.1.73";
+export declare const PLUGIN_VERSION = "0.1.77";
 /**
  * Star 引导弹窗指向的 GitHub 仓库（用户引导点 Star 的目标）。
  * 与 package.json 的 repository 字段保持一致；界面不可改（硬编码，参照
@@ -340,6 +340,11 @@ export declare class DshSessionStoreFacade implements SessionStoreFacade {
     private readonly ctx;
     /** DSH 缺省会话根（配置改过时只影响快路径命中率，慢路径仍正确） */
     private readonly root;
+    /**
+     * 插件数据根（`<DSH_HOME>/dsh-config-manager`）—— **只**用于归位失败的诊断落盘。
+     * 权威状态仍在 DSH（工作区注册表 / 会话存储），这里绝不旁路写任何 DSH 数据。
+     */
+    private readonly dataDir;
     /**
      * 父子关系的短 TTL 缓存（见 `PARENT_RELATIONS_CACHE_TTL_MS`；同 key 并发合并成一次列举）。
      * F-1 后**只缓存成功结果**：列举失败/形状识别失败会让 `parentRelations()` 抛错，
@@ -472,8 +477,26 @@ export declare class DshSessionStoreFacade implements SessionStoreFacade {
      * 宁少不猜（DSH 官方用 `sessionQuery.traceSession`；这里只依赖 `sessions.get(id).header`）。
      */
     private ancestorSessionIds;
-    /** 子会话 header 的 cwd（只读；读不到返回 undefined，绝不猜路径）。 */
-    private liveSessionCwd;
+    /**
+     * 会话 cwd 的**多源**读取（活会话 → 宿主会话存储列举）。
+     *
+     * 为什么不能只读活会话（真机 2026-10-17 根因之一）：旧实现只看 `ctx.get('sessions').get(id)`，
+     * 拿不到就整体放弃归位 ⇒ fork 出来的子会话停在侧栏「未分组」。而 DSH 自己的读法有**磁盘回落**
+     * （`dsh-workspace` 的 `readSessionHeader`：活会话 → `sessionPersistence.list()` 的 header 缓存），
+     * 本方法与该回落同源，绝不猜路径、绝不拿父会话目录以外的任何东西凑数。
+     *
+     * 失败时返回**具体细节**（哪个来源、为什么），由调用方拼进诊断；绝不静默成 undefined。
+     */
+    private sessionCwdOf;
+    /**
+     * 归位失败的**诊断落盘**（一行 JSON，追加写）。
+     *
+     * 为什么需要：桌面版 DSH 的宿主 stdout 不落盘 ⇒ 用户界面上只有「未挂回原工作区」这句，
+     * 具体理由（registry 拿不到 / attach 被拒 / cwd 读不到 / 复核不过）谁都看不到，
+     * 「为什么会进未分组」于是长期不可排查。这里只记 id、理由码与路径来源，**不含任何凭据**。
+     * 落盘失败绝不升级成回退失败（诊断是旁路，不是回退的一部分）。
+     */
+    private recordAttachDiagnostic;
     /**
      * 活会话 header（`ctx.get('sessions').get(id).header`）。
      *

package/lib/index.js

@@ -38,6 +38,7 @@ import { randomBytes } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { createWriteStream, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
+import path from 'node:path';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { promisify } from 'node:util';
@@ -64,7 +65,8 @@ import { RunRegistry } from './core/run-registry.js';
 import { registerModelTools } from './core/model-tools.js';
 import { msgOf, zhMsg } from './core/messages.js';
 import { engineMsg, getEngineLocale, setEngineLanguageSource, setEngineLocale } from './core/engine-locale.js';
-import { RollbackAutoTracker, RollbackPointEngine, rollbackSessionBindingOf, rollbackTrackedEventOf } from './core/rollback-point.js';
+import { RollbackAutoTracker, RollbackPointEngine, ROLLBACK_POINTS_DIR_NAME, rollbackSessionBindingOf, rollbackTrackedEventOf } from './core/rollback-point.js';
+import { ROLLBACK_ATTRIBUTION_FILE_NAME, RollbackWriteAttribution } from './core/rollback-attribution.js';
 import { isRollbackEnabled, onRollbackEnabledChange, setRollbackEnabled } from './core/rollback-gate.js';
 // t3：宿主斜杠命令 /rollback（与 HTTP 路由同一道写入门；命令服务惰取，未组合时安静跳过）。
 import { agentSessionFactsOf, registerRollbackCommand } from './core/command-rollback.js';
@@ -136,7 +138,7 @@ export const name = 'config-manager';
 /** Services required before the engine can mount (present in every profile). */
 export const inject = ['settings', 'credentials'];
 /** Plugin version, kept in sync with package.json ("version"). */
-export const PLUGIN_VERSION = '0.1.73';
+export const PLUGIN_VERSION = '0.1.77';
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager';
 /**
@@ -646,6 +648,7 @@ export function normalizeListedSession(element) {
 const SESSION_STORE_PURPOSE_KEY = {
     reindexSessionHeader: 'host.sessionStorePurposeReindex',
     parentRelations: 'host.sessionStorePurposeParentRelations',
+    rewindWorkspaceAttach: 'host.sessionStorePurposeRewindAttach',
 };
 /**
  * 父子关系缓存的 TTL（毫秒）。
@@ -668,6 +671,18 @@ const PARENT_RELATIONS_CACHE_TTL_MS = 5_000;
 const ANCESTOR_LOOKUP_MAX_DEPTH = 8;
 /** 归位失败时给调用方的 warning 串（稳定前缀 + 具体理由码）。 */
 export const WORKSPACE_ATTACH_FAILED_PREFIX = 'workspace-attach-failed';
+/**
+ * 归位失败后的重试次数与间隔（毫秒）。
+ *
+ * 为什么需要（真机 2026-10-17/10-12）：fork 返回时子会话刚由 `agents.create` 建好，
+ * DSH 侧的会话索引 / 持久化列举可能还没就绪 —— 与「目录根本不存在」这类终结性失败不同，
+ * 这是**时序性**失败。归位本身幂等（`attachSession` 自查成员名单、`mutate` 空操作即不改写），
+ * 因此重试零副作用；不重试则子会话永久停在侧栏「未分组」。
+ */
+const WORKSPACE_ATTACH_ATTEMPTS = 2;
+const WORKSPACE_ATTACH_RETRY_DELAY_MS = 200;
+/** 归位诊断文件的相对路径（相对插件数据根；只在**失败**时追加一行 JSON）。 */
+const WORKSPACE_ATTACH_DIAGNOSTIC_REL = 'logs/rewind-workspace-attach.jsonl';
 /**
  * DSH 官方 fork 在「子会话已创建、但 `workspace.attachSession` 失败」时抛的错误码。
  *
@@ -735,6 +750,11 @@ export class DshSessionStoreFacade {
     ctx;
     /** DSH 缺省会话根（配置改过时只影响快路径命中率，慢路径仍正确） */
     root;
+    /**
+     * 插件数据根（`<DSH_HOME>/dsh-config-manager`）—— **只**用于归位失败的诊断落盘。
+     * 权威状态仍在 DSH（工作区注册表 / 会话存储），这里绝不旁路写任何 DSH 数据。
+     */
+    dataDir;
     /**
      * 父子关系的短 TTL 缓存（见 `PARENT_RELATIONS_CACHE_TTL_MS`；同 key 并发合并成一次列举）。
      * F-1 后**只缓存成功结果**：列举失败/形状识别失败会让 `parentRelations()` 抛错，
@@ -760,6 +780,7 @@ export class DshSessionStoreFacade {
     constructor(ctx, homeDir, msg = zhMsg, log, realpath) {
         this.ctx = ctx;
         this.root = join(homeDir, 'sessions');
+        this.dataDir = join(homeDir, 'dsh-config-manager');
         this.log = log ?? createLogger({ level: 'warn' });
         this.msgFunc = msg;
         this.realpath = realpath ?? (async (value) => await fs.realpath(value));
@@ -819,14 +840,23 @@ export class DshSessionStoreFacade {
             childId = recovered;
         }
         // 工作区归位：官方已归位 → 只复核；官方没归位（或 attach 抛错被上面救回）→ 本兜底写；写后一律复核。
-        const outcome = await this.attachChildToParentWorkspace(sessionId, childId);
+        //
+        // 失败要重试（真机 2026-10-17）：fork 返回时子会话刚建好，DSH 侧的索引/持久化列举可能还没就绪，
+        // 属**时序性**失败；三档判定与 attach 本身幂等，重试零副作用。不重试的代价是子会话永久停在
+        // 侧栏「未分组」（用户 2026-10-11 起的反馈）。
+        let outcome = await this.attachChildToParentWorkspace(sessionId, childId);
+        for (let attempt = 1; attempt < WORKSPACE_ATTACH_ATTEMPTS && !outcome.ok; attempt += 1) {
+            await new Promise((resolve) => { setTimeout(resolve, WORKSPACE_ATTACH_RETRY_DELAY_MS); });
+            outcome = await this.attachChildToParentWorkspace(sessionId, childId);
+        }
         if (outcome.ok) {
             this.log.info('rewind: child session filed into workspace: ' + childId + ' (' + outcome.reason + (outcome.workspaceId !== undefined ? ' ' + outcome.workspaceId : '') + ')');
             return { childSessionId: childId };
         }
         // 归位失败**带具体理由**（绝不静默）：日志留痕 + warning 串交给调用方如实上屏。
-        this.log.warn('rewind: child session not filed into any workspace: ' + childId + ' reason=' + outcome.reason
-            + (outcome.detail !== undefined ? ' detail=' + outcome.detail : ''));
+        //
+        // 桌面版 DSH 拿不到宿主 stdout ⇒ 只有理由码还不够排查「为什么进未分组」，故再落一行诊断。
+        await this.recordAttachDiagnostic({ parentId: sessionId, childId, outcome });
         const warning = workspaceAttachWarningOf(outcome);
         return warning === undefined ? { childSessionId: childId } : { childSessionId: childId, warning };
     }
@@ -896,12 +926,29 @@ export class DshSessionStoreFacade {
                 attachFailure ??= attempt;
             }
             // ③ 同目录：cwd 与某工作区 path 指向同一目录（目录同一性由 DSH 判定，见方法注释）
-            const cwd = this.liveSessionCwd(childId);
-            if (cwd === undefined) {
-                cwdFailure = { ok: false, reason: 'cwd-unavailable' };
+            //
+            // cwd 取**多源候选**（真机 2026-10-17）：旧实现只看子会话的活 header，拿不到就直接
+            // `cwd-unavailable` ⇒ 三档全落空 ⇒ 子会话停在「未分组」。两条候选都来自 DSH 自己写下的 header，
+            // 不是猜测：① 子会话（活 / 落盘 header）；② 父会话 —— DSH 的 fork 逐字继承父 cwd
+            // （`SessionCommandController.fork`：`meta.cwd = source.header.cwd`，见 dsh-api-session-controller）。
+            const candidates = [];
+            const missing = [];
+            const childLookup = await this.sessionCwdOf(childId);
+            if (childLookup.ok)
+                candidates.push({ cwd: childLookup.cwd, source: 'child:' + childLookup.source });
+            else
+                missing.push('child(' + childLookup.detail + ')');
+            const parentLookup = await this.sessionCwdOf(parentId);
+            if (parentLookup.ok) {
+                // 与已入列候选同目录时不重复（同目录再 attach 一次只是白跑一次 list()）
+                if (!candidates.some((c) => foldWorkspacePath(c.cwd) === foldWorkspacePath(parentLookup.cwd))) {
+                    candidates.push({ cwd: parentLookup.cwd, source: 'parent:' + parentLookup.source });
+                }
             }
-            else {
-                const resolution = await this.resolveWorkspaceByCwd(registry, records, cwd);
+            else
+                missing.push('parent(' + parentLookup.detail + ')');
+            for (const candidate of candidates) {
+                const resolution = await this.resolveWorkspaceByCwd(registry, records, candidate.cwd);
                 if (resolution.records !== undefined && resolution.records.length > 0) {
                     for (const record of resolution.records) {
                         const attempt = await this.attachChildTo(record, childId);
@@ -911,9 +958,15 @@ export class DshSessionStoreFacade {
                     }
                 }
                 else {
-                    cwdFailure = resolution.failure;
+                    // 目录不存在 / 不属于任何工作区：按候选来源标注，便于诊断区分「读到的是谁」
+                    const failure = resolution.failure;
+                    if (failure !== undefined) {
+                        cwdFailure ??= { ok: false, reason: failure.reason, detail: candidate.source + ':' + (failure.detail ?? '') };
+                    }
                 }
             }
+            if (candidates.length === 0)
+                cwdFailure = { ok: false, reason: 'cwd-unavailable', detail: missing.join(';') };
             return attachFailure ?? cwdFailure ?? { ok: false, reason: 'no-workspace-for-cwd' };
         }
         catch (error) {
@@ -1090,10 +1143,57 @@ export class DshSessionStoreFacade {
         }
         return out;
     }
-    /** 子会话 header 的 cwd（只读；读不到返回 undefined，绝不猜路径）。 */
-    liveSessionCwd(sessionId) {
-        const cwd = this.liveSessionHeader(sessionId)?.['cwd'];
-        return typeof cwd === 'string' && cwd !== '' ? cwd : undefined;
+    /**
+     * 会话 cwd 的**多源**读取（活会话 → 宿主会话存储列举）。
+     *
+     * 为什么不能只读活会话（真机 2026-10-17 根因之一）：旧实现只看 `ctx.get('sessions').get(id)`，
+     * 拿不到就整体放弃归位 ⇒ fork 出来的子会话停在侧栏「未分组」。而 DSH 自己的读法有**磁盘回落**
+     * （`dsh-workspace` 的 `readSessionHeader`：活会话 → `sessionPersistence.list()` 的 header 缓存），
+     * 本方法与该回落同源，绝不猜路径、绝不拿父会话目录以外的任何东西凑数。
+     *
+     * 失败时返回**具体细节**（哪个来源、为什么），由调用方拼进诊断；绝不静默成 undefined。
+     */
+    async sessionCwdOf(sessionId) {
+        const live = this.liveSessionHeader(sessionId)?.['cwd'];
+        if (typeof live === 'string' && live !== '')
+            return { ok: true, cwd: live, source: 'live' };
+        const store = readService(this.ctx, 'sessionPersistence');
+        if (store === undefined)
+            return { ok: false, detail: 'no-live-cwd;session-persistence-unavailable' };
+        const listed = await this.listSessionElements(store, 'rewindWorkspaceAttach');
+        if (!listed.ok)
+            return { ok: false, detail: 'no-live-cwd;' + listed.reason };
+        const view = listed.items.find((item) => item.id === sessionId);
+        if (view === undefined)
+            return { ok: false, detail: 'no-live-cwd;not-in-stored-sessions' };
+        const raw = isRecord(view.raw) ? view.raw['cwd'] : undefined;
+        if (typeof raw === 'string' && raw !== '')
+            return { ok: true, cwd: raw, source: 'stored' };
+        return { ok: false, detail: 'no-live-cwd;stored-header-has-no-cwd' };
+    }
+    /**
+     * 归位失败的**诊断落盘**（一行 JSON，追加写）。
+     *
+     * 为什么需要：桌面版 DSH 的宿主 stdout 不落盘 ⇒ 用户界面上只有「未挂回原工作区」这句，
+     * 具体理由（registry 拿不到 / attach 被拒 / cwd 读不到 / 复核不过）谁都看不到，
+     * 「为什么会进未分组」于是长期不可排查。这里只记 id、理由码与路径来源，**不含任何凭据**。
+     * 落盘失败绝不升级成回退失败（诊断是旁路，不是回退的一部分）。
+     */
+    async recordAttachDiagnostic(entry) {
+        try {
+            const target = join(this.dataDir, WORKSPACE_ATTACH_DIAGNOSTIC_REL);
+            await fs.mkdir(dirname(target), { recursive: true });
+            await fs.appendFile(target, JSON.stringify({
+                at: new Date().toISOString(),
+                parentId: entry.parentId,
+                childId: entry.childId,
+                reason: entry.outcome.reason,
+                ...(entry.outcome.detail !== undefined ? { detail: entry.outcome.detail } : {}),
+            }) + '\n');
+        }
+        catch {
+            // 诊断写不进去（只读盘 / 权限 / 配额）：静默 —— 回退本身的结论不受影响。
+        }
     }
     /**
      * 活会话 header（`ctx.get('sessions').get(id).header`）。
@@ -4285,10 +4385,19 @@ export function apply(ctx, config) {
     // 不为了这一处调用去改公共接口；端口上确实有 forkSession（DshSessionStoreFacade 实现）才走
     // 真 fork，否则如实结构化 `session-fork-unavailable`（绝不静默降级）。
     const forkPort = host.sessions;
+    // 写入归属台账（2026-10-17 定案 B）：只记「哪个会话的哪次**写类**工具调用写了哪个路径」。
+    // 惰性读盘 + best-effort 落盘：读不到 / 写不进只让归属退化成「未判定」——
+    // 既不影响留点与回退，也绝不会把「不知道」当成「别的会话写的」（见 rollback-attribution.ts）。
+    const rollbackAttribution = new RollbackWriteAttribution({
+        file: path.join(dataDir, ROLLBACK_POINTS_DIR_NAME, ROLLBACK_ATTRIBUTION_FILE_NAME),
+        warn: (line) => host.log.warn(line),
+    });
+    void rollbackAttribution.load();
     const rollbackEngine = new RollbackPointEngine({
         dataDir,
         homeDir,
         log: (line) => host.log.warn(line),
+        attribution: rollbackAttribution,
         fork: async ({ sessionId, boundarySeq }) => {
             const forkSession = forkPort.forkSession;
             if (typeof forkSession !== 'function') {
@@ -4307,7 +4416,11 @@ export function apply(ctx, config) {
             return { ok: false, code: 'fork-failed', detail: result.error };
         },
     });
-    const rollbackTracker = new RollbackAutoTracker({ engine: rollbackEngine, log: (line) => host.log.warn(line) });
+    const rollbackTracker = new RollbackAutoTracker({
+        engine: rollbackEngine,
+        log: (line) => host.log.warn(line),
+        attribution: rollbackAttribution,
+    });
     ctx.effect(() => {
         let chain = Promise.resolve();
         // 「会话没有 cwd」这类**形状合法但信息不全**的情况只记一次日志（避免每回合刷屏）；

package/lib/routes/recovery.js

@@ -766,6 +766,17 @@ export function recoveryRoutes(env) {
                         // A（用户 2026-10-11 定案）：「回到某点之前」要连文件一起退回去 —— 默认把**回退点之后新建**的路径删掉；
                         // 调用方显式传 false 才保留老口径（只报告 leftovers，不删任何东西）。
                         rewindInput.removeCreated = body['removeCreated'] !== false;
+                        // 路径级选择性恢复（2026-10-17 定案 A）：缺省 = 全量口径（一字不变）。
+                        // 给了数组就只恢复这些路径；**空数组**视为无效输入（400）—— 「一个都没勾」应当由
+                        // 界面拦住，而不是让引擎把整次回退悄悄变成 noop。
+                        if (body['onlyPaths'] !== undefined) {
+                            const raw = body['onlyPaths'];
+                            if (!Array.isArray(raw) || raw.length === 0 || raw.some((item) => typeof item !== 'string' || item === '')) {
+                                writeJson(res, 400, { ok: false, code: 'invalid-input', error: 'onlyPaths must be a non-empty array of non-empty strings' });
+                                return;
+                            }
+                            rewindInput.onlyPaths = raw;
+                        }
                         if (body['preRewindGuard'] === 'off' || body['preRewindGuard'] === 'require' || body['preRewindGuard'] === 'warn') {
                             rewindInput.guardPolicy = body['preRewindGuard'];
                         }

package/lib/schema/section-registry.js

@@ -55,7 +55,7 @@ export const SECTION_REGISTRY = {
     },
     plugins: {
         id: 'plugins',
-        displayName: 'Plugins',
+        displayName: 'Plugin list',
         group: 'extensions',
         payload: {
             kind: 'array', zipPath: 'plugins/plugins.json', key: 'plugins',
@@ -152,7 +152,7 @@ export const SECTION_REGISTRY = {
     },
     pluginFiles: {
         id: 'pluginFiles',
-        displayName: "Other Plugins' Loose Files",
+        displayName: 'Plugin config files',
         group: 'extensions',
         payload: { kind: 'files', filePrefix: 'plugin-files/' },
         dataVersion: SECTION_DATA_VERSION,
@@ -205,7 +205,7 @@ export const SECTION_REGISTRY = {
     },
     self: {
         id: 'self',
-        displayName: "This Plugin's Own Config",
+        displayName: 'Config Manager settings',
         group: 'extensions',
         payload: { kind: 'files', filePrefix: 'self/' },
         dataVersion: SECTION_DATA_VERSION,
@@ -218,7 +218,7 @@ export const SECTION_REGISTRY = {
     },
     pluginData: {
         id: 'pluginData',
-        displayName: "Other Plugins' Data",
+        displayName: 'Plugin data dirs',
         group: 'extensions',
         payload: { kind: 'files', filePrefix: 'plugin-data/' },
         dataVersion: SECTION_DATA_VERSION,
@@ -234,7 +234,7 @@ export const SECTION_REGISTRY = {
     },
     pluginAssets: {
         id: 'pluginAssets',
-        displayName: "Other Plugins' Large Files",
+        displayName: 'Plugin large files',
         group: 'extensions',
         payload: { kind: 'files', filePrefix: 'plugin-assets/' },
         dataVersion: SECTION_DATA_VERSION,

package/lib/sync/messages.d.ts

@@ -57,6 +57,7 @@ export declare const zh: {
     readonly 'sync.backupHistoryDone': '{trigger}完成：{zip}';
     readonly 'sync.backupHistorySkipped': '{trigger}跳过：{reason}';
     readonly 'sync.backupHistoryFailed': '{trigger}失败';
+    readonly 'sync.pushPreviewUnpackedLocalSources': '本地源插件（link:/file:）需打包才能精确比对变更，分区 {sections} 本次按「有变化」展示';
 };
 export declare const en: Record<keyof typeof zh, string>;
 /** 本域活翻译器（与 core 的 engineMsg 同一实现；导入本模块即完成目录注册）。 */

package/lib/sync/messages.js

@@ -83,6 +83,8 @@ export const zh = {
     'sync.backupHistoryDone': '{trigger}完成：{zip}',
     'sync.backupHistorySkipped': '{trigger}跳过：{reason}',
     'sync.backupHistoryFailed': '{trigger}失败',
+    // ---------- 推送前只读预览（issue #91） ----------
+    'sync.pushPreviewUnpackedLocalSources': '本地源插件（link:/file:）需打包才能精确比对变更，分区 {sections} 本次按「有变化」展示',
 };
 export const en = {
     'sync.ancestorSnapshotIdRequired': 'loadAncestor: snapshotId must not be empty',
@@ -142,6 +144,7 @@ export const en = {
     'sync.backupHistoryDone': '{trigger} finished: {zip}',
     'sync.backupHistorySkipped': '{trigger} skipped: {reason}',
     'sync.backupHistoryFailed': '{trigger} failed',
+    'sync.pushPreviewUnpackedLocalSources': 'Local-source plugins (link:/file:) must be packed to compare changes exactly; section(s) {sections} are shown as changed',
 };
 registerMessageCatalog({ id: 'sync-domain', zh, en });
 /** 本域活翻译器（与 core 的 engineMsg 同一实现；导入本模块即完成目录注册）。 */

package/lib/sync/sync-engine.js

@@ -22,6 +22,8 @@ import path from 'node:path';
 import { createAdapters } from '../adapters/index.js';
 import { defaultSecretScanner } from '../core/exporter.js';
 import { Importer } from '../core/importer.js';
+// issue #91：只读预览与基线 hash 的口径判定（本地源插件在预览里不会被 npm pack）
+import { isLocalPluginSpec } from '../core/local-plugin-pack.js';
 import { isFileSection, SECTION_FILE_PREFIXES, SECTION_JSON_PATHS } from '../schema/config.js';
 import { buildManifest, CHECKSUMS_FILE, MANIFEST_FILE } from '../schema/manifest.js';
 import { CURRENT_SCHEMA_VERSION } from '../schema/versions.js';
@@ -83,6 +85,24 @@ const FORBIDDEN_SECTIONS = ['credentialsStatus', 'secrets'];
  * 保留导出是为了让既有调用方/测试仍能引用「缺省保留份数」这一事实，不再作为唯一判据。
  */
 export const MAX_REMOTE_SNAPSHOTS = DEFAULT_RETENTION_POLICY.keepLast;
+/**
+ * issue #91：走只读 `preview()` 拿到的产物，能否直接与该分区**基线 hash**（push 时按 export() 产物记录）比对。
+ *
+ * 为什么需要这个判定：`plugins` 适配器的 `preview()` 走 `collect(…, pack=false)` —— 刻意**不做**
+ * 本地源（`link:` / `file:`）插件的 `npm pack`。于是当 profile 里存在本地源插件时，预览产物既没有
+ * `localTarballs`、插件 spec 也保持原样（export() 会改写成 `file:<tarball>`），与基线**不同口径**：
+ * 此时既不能断言「无变化」（本地插件源码改了体积/内容，预览看不见），也不该为了比对去打包
+ * （那正是本 issue 的缺陷本身）。
+ *
+ * 返回 true = 该分区本趟**不可比** ⇒ 调用方只能保守报「有变化」并如实说明原因。
+ * 其余分区的 preview() 产物与 export() 逐字节相同（文件类分区不走 preview()，见 previewPush）。
+ */
+function previewCaliberDiffersFromExport(sectionId, data) {
+    if (sectionId !== 'plugins')
+        return false;
+    const plugins = data.plugins;
+    return Array.isArray(plugins) && plugins.some((p) => isLocalPluginSpec(p?.spec));
+}
 export class SyncEngine {
     ctx;
     transport;
@@ -516,14 +536,29 @@ export class SyncEngine {
         const targets = this.pushTargets(opts.sections, warnings);
         const plainSections = {};
         const counts = {};
+        /** issue #91：本趟只读预览省掉了本地源打包 ⇒ 与基线不可比的分区（不可断言「无变化」） */
+        const unpackedSections = new Set();
         for (const adapter of targets) {
+            const exportOptions = {
+                includeSecrets,
+                // 与 push 同口径：显式勾选清单 > 「最新 N 个」上限
+                ...this.sessionExportOptions(adapter.id, opts.sessions),
+            };
             let section;
             try {
-                section = await adapter.export(this.ctx, {
-                    includeSecrets,
-                    // 与 push 同口径：显式勾选清单 > 「最新 N 个」上限
-                    ...this.sessionExportOptions(adapter.id, opts.sessions),
-                });
+                // issue #91：**非文件类**分区优先走 adapter.preview()。只读预览必须零进程副作用，而
+                // plugins 的 export() 会对每个 `link:`/`file:` 插件真的跑一次 `npm pack`
+                // （真机 2 GB 本地源插件 = 297 s；这段时间全局写锁被该请求占满 ⇒ 界面上所有写操作静默 423）。
+                // 为什么文件类分区**不能**走 preview()：其预览产物是「无内容」形态（条目 data 为空、
+                // contentHash 为空串），既不能与基线 hash 比对，也不能进 assertNoForbiddenSections
+                // —— 那会让预览谎报「每个文件分区都变了」。
+                const summary = !isFileSection(adapter.id) && adapter.preview !== undefined
+                    ? await adapter.preview(this.ctx, exportOptions)
+                    : undefined;
+                section = summary?.section ?? await adapter.export(this.ctx, exportOptions);
+                if (summary !== undefined && previewCaliberDiffersFromExport(adapter.id, section.data)) {
+                    unpackedSections.add(adapter.id);
+                }
             }
             catch (err) {
                 warnings.push(this.msg('sync.sectionFailed', { adapter: adapter.id, reason: err instanceof Error ? err.message : String(err) }));
@@ -544,15 +579,29 @@ export class SyncEngine {
         if (!encrypted) {
             try {
                 const state = await loadSyncState(this.stateDir, this.fsx, this.msg);
-                baselineHashes = state.sections;
+                // 基线条目是 SyncSectionState（{hash, updatedAt}），**不是**裸 hash 字符串。
+                // 这里曾把整个对象 as Record<string,string> 直接比对 ⇒ 对象 !== 字符串 恒真
+                // ⇒ 预览对**每一个**分区都报「有变化」，「N 个有变化」这句永远是「全都有变化」。
+                for (const [sid, rec] of Object.entries(state.sections)) {
+                    if (rec !== undefined && typeof rec.hash === 'string')
+                        baselineHashes[sid] = rec.hash;
+                }
             }
             catch {
                 baselineHashes = {};
             }
         }
+        if (unpackedSections.size > 0) {
+            // 如实说明：本次预览没有为本地源插件执行 npm pack，故这些分区的基线比对不可得
+            warnings.push(this.msg('sync.pushPreviewUnpackedLocalSources', { sections: [...unpackedSections].join(', ') }));
+        }
         const sections = Object.keys(plainSections).map((sid) => {
             const id = sid;
-            const changed = encrypted || baselineHashes[id] === undefined || baselineHashes[id] !== hashSection(plainSections[id]);
+            const changed = encrypted
+                // issue #91：只读预览省掉了本地源打包 ⇒ 产物与基线不同口径，**绝不**据此断言「无变化」
+                || unpackedSections.has(id)
+                || baselineHashes[id] === undefined
+                || baselineHashes[id] !== hashSection(plainSections[id]);
             return { section: id, count: counts[id] ?? 0, changed };
         });
         let remoteSnapshotCount = 0;

package/lib/ui/badge-tone.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 徽章四态 → DSH 原生 Tag tone 的映射（**唯一一份**）。
+ *
+ * 为什么单独成模块：徽章现在优先渲染 DSH 自带的 `Tag`（@deepseek-ai/dsh-client-ui-primitives，
+ * 与宿主同一颗组件），它只有 tone 语义、没有 kind 语义；映射关系是纯函数，放这里可被 node 单测覆盖，
+ * 也让 React 壳保持「只装配」。老宿主拿不到原生包时回落本仓库的 `.badge[data-kind]` 样式，
+ * 两条路径共用同一套 kind → tone 语义，不允许各自漂移。
+ */
+/** 插件侧的四态徽章语义。 */
+export type BadgeKind = 'info' | 'ok' | 'warn' | 'error';
+/** DSH 原生 Tag 的调色板选项（与其 .d.ts 逐字同形）。 */
+export type DshTagTone = 'outline' | 'solid' | 'neutral' | 'quiet' | 'success' | 'info' | 'warning' | 'danger';
+/** 四态 → 原生 tone（ok=success / warn=warning / error=danger / info=info）。 */
+export declare const BADGE_TONE: Readonly<Record<BadgeKind, DshTagTone>>;
+/** 取某个四态对应的原生 tone；未知输入按 info 处理（调用方给的是字面量联合，此为防御）。 */
+export declare function badgeTone(kind: BadgeKind): DshTagTone;

package/lib/ui/badge-tone.js

@@ -0,0 +1,20 @@
+/**
+ * 徽章四态 → DSH 原生 Tag tone 的映射（**唯一一份**）。
+ *
+ * 为什么单独成模块：徽章现在优先渲染 DSH 自带的 `Tag`（@deepseek-ai/dsh-client-ui-primitives，
+ * 与宿主同一颗组件），它只有 tone 语义、没有 kind 语义；映射关系是纯函数，放这里可被 node 单测覆盖，
+ * 也让 React 壳保持「只装配」。老宿主拿不到原生包时回落本仓库的 `.badge[data-kind]` 样式，
+ * 两条路径共用同一套 kind → tone 语义，不允许各自漂移。
+ */
+/** 四态 → 原生 tone（ok=success / warn=warning / error=danger / info=info）。 */
+export const BADGE_TONE = {
+    ok: 'success',
+    info: 'info',
+    warn: 'warning',
+    error: 'danger',
+};
+/** 取某个四态对应的原生 tone；未知输入按 info 处理（调用方给的是字面量联合，此为防御）。 */
+export function badgeTone(kind) {
+    return BADGE_TONE[kind] ?? 'info';
+}
+//# sourceMappingURL=badge-tone.js.map

package/lib/ui/i18n.d.ts

@@ -92,7 +92,7 @@ export declare const uiZh: {
     readonly 'error.downloadFailed': '下载失败：HTTP {status}';
     readonly 'error.exportTimeout': '导出超时（{minutes} 分钟）：导出过程未完成，请重试；若反复超时请检查 DSH 状态';
     readonly 'error.syncTimeout': '同步请求超时（{minutes} 分钟）：请检查网络与仓库可达性后重试';
-    readonly 'error.recoveryTimeout': '恢复请求超时（{minutes} 分钟）：恢复过程未完成，请重试；若反复超时请检查 DSH 状态';
+    readonly 'error.recoveryTimeout': '恢复请求超时（{minutes} 分钟）：过程可能仍在后台进行，请先刷新预览确认；确实未完成再重试';
     readonly 'error.settingsConflict.title': '配置已被并发修改';
     readonly 'error.settingsConflict.action': '目标 DSH 的该配置在导入期间被其他进程修改，为避免覆盖请重新导出或手动核对后再试。';
     readonly 'error.notConfirmed.title': '导入未确认';
@@ -517,10 +517,10 @@ export declare const uiZh: {
     readonly 'export.category.settings': 'DSH 全局设置（namespace 分区，redacted）';
     readonly 'export.category.providers': 'LLM Provider / Model / 默认模型 / BaseURL';
     readonly 'export.category.plugins': '已安装插件清单与启用状态（不含二进制）';
-    readonly 'export.category.pluginFiles': '其他插件放在 ~/.dsh 根下的零散配置文件（白名单 + plugin-config/ 目录，整文件复制）';
-    readonly 'export.category.self': '本插件自身配置（同步/自动同步/分区选择/UI 偏好/市场；sync-*.json 等，不含凭据值）';
-    readonly 'export.category.pluginData': '其他插件在系统主目录下的数据（如 ~/.dsh-wallpaper-engine、~/.mnemon 的配置与状态；可再生成缓存绝不收录）';
-    readonly 'export.category.pluginAssets': '其他插件的大体积文件（上传的壁纸、本地数据库等；默认不勾选）';
+    readonly 'export.category.pluginFiles': '插件放在 ~/.dsh 根下的配置文件（白名单 + plugin-config/ 目录，整文件复制）';
+    readonly 'export.category.self': '配置管理器自身的设置（同步/自动同步/分区选择/UI 偏好/市场；sync-*.json 等，不含凭据值）';
+    readonly 'export.category.pluginData': '插件在系统主目录下的数据（如 ~/.dsh-wallpaper-engine、~/.mnemon 的配置与状态；可再生成缓存绝不收录）';
+    readonly 'export.category.pluginAssets': '插件的大体积文件（上传的壁纸、本地数据库等；默认不勾选）';
     readonly 'export.category.mcp': 'MCP 服务器组合配置（需重启生效）';
     readonly 'export.category.prompts': 'System Prompt / Plan Mode 提示';
     readonly 'export.category.skills': '用户技能文件（~/.dsh/skills）';

package/lib/ui/i18n.js

@@ -99,7 +99,7 @@ export const uiZh = {
     'error.downloadFailed': '下载失败：HTTP {status}',
     'error.exportTimeout': '导出超时（{minutes} 分钟）：导出过程未完成，请重试；若反复超时请检查 DSH 状态',
     'error.syncTimeout': '同步请求超时（{minutes} 分钟）：请检查网络与仓库可达性后重试',
-    'error.recoveryTimeout': '恢复请求超时（{minutes} 分钟）：恢复过程未完成，请重试；若反复超时请检查 DSH 状态',
+    'error.recoveryTimeout': '恢复请求超时（{minutes} 分钟）：过程可能仍在后台进行，请先刷新预览确认；确实未完成再重试',
     'error.settingsConflict.title': '配置已被并发修改',
     'error.settingsConflict.action': '目标 DSH 的该配置在导入期间被其他进程修改，为避免覆盖请重新导出或手动核对后再试。',
     'error.notConfirmed.title': '导入未确认',
@@ -547,10 +547,10 @@ export const uiZh = {
     'export.category.settings': 'DSH 全局设置（namespace 分区，redacted）',
     'export.category.providers': 'LLM Provider / Model / 默认模型 / BaseURL',
     'export.category.plugins': '已安装插件清单与启用状态（不含二进制）',
-    'export.category.pluginFiles': '其他插件放在 ~/.dsh 根下的零散配置文件（白名单 + plugin-config/ 目录，整文件复制）',
-    'export.category.self': '本插件自身配置（同步/自动同步/分区选择/UI 偏好/市场；sync-*.json 等，不含凭据值）',
-    'export.category.pluginData': '其他插件在系统主目录下的数据（如 ~/.dsh-wallpaper-engine、~/.mnemon 的配置与状态；可再生成缓存绝不收录）',
-    'export.category.pluginAssets': '其他插件的大体积文件（上传的壁纸、本地数据库等；默认不勾选）',
+    'export.category.pluginFiles': '插件放在 ~/.dsh 根下的配置文件（白名单 + plugin-config/ 目录，整文件复制）',
+    'export.category.self': '配置管理器自身的设置（同步/自动同步/分区选择/UI 偏好/市场；sync-*.json 等，不含凭据值）',
+    'export.category.pluginData': '插件在系统主目录下的数据（如 ~/.dsh-wallpaper-engine、~/.mnemon 的配置与状态；可再生成缓存绝不收录）',
+    'export.category.pluginAssets': '插件的大体积文件（上传的壁纸、本地数据库等；默认不勾选）',
     'export.category.mcp': 'MCP 服务器组合配置（需重启生效）',
     'export.category.prompts': 'System Prompt / Plan Mode 提示',
     'export.category.skills': '用户技能文件（~/.dsh/skills）',
@@ -662,7 +662,7 @@ export const uiEn = {
     'error.downloadFailed': 'Download failed: HTTP {status}',
     'error.exportTimeout': 'Export timed out ({minutes} min): the export did not complete, please retry; if it keeps timing out, check the DSH state',
     'error.syncTimeout': 'Sync request timed out ({minutes} min): check network and repository reachability, then retry',
-    'error.recoveryTimeout': 'Recovery request timed out ({minutes} min): the recovery did not complete, please retry; if it keeps timing out, check the DSH state',
+    'error.recoveryTimeout': 'Recovery request timed out ({minutes} min): it may still be running in the background — refresh the preview to confirm, then retry if it did not finish',
     'error.settingsConflict.title': 'Configuration changed concurrently',
     'error.settingsConflict.action': 'This configuration on the target DSH was modified by another process during import. To avoid overwriting it, re-export or review it manually, then retry.',
     'error.notConfirmed.title': 'Import not confirmed',
@@ -1093,10 +1093,10 @@ export const uiEn = {
     'export.category.settings': 'Global DSH settings (namespace sections, redacted)',
     'export.category.providers': 'LLM providers / models / default model / base URL',
     'export.category.plugins': 'Installed plugin list and enablement (binaries excluded)',
-    'export.category.pluginFiles': "Other plugins' loose config files at the ~/.dsh root (allowlist + plugin-config/, copied whole)",
-    'export.category.self': "This plugin's own config (sync / autosync / section selection / UI prefs / market; sync-*.json etc., no credential values)",
-    'export.category.pluginData': "Other plugins' data under the system home directory (e.g. the config/state of ~/.dsh-wallpaper-engine and ~/.mnemon; regenerable caches are never included)",
-    'export.category.pluginAssets': "Other plugins' large files (uploaded wallpapers, local databases, ...; not selected by default)",
+    'export.category.pluginFiles': "Plugin config files at the ~/.dsh root (allowlist + plugin-config/, copied whole)",
+    'export.category.self': "Config Manager's own settings (sync / autosync / section selection / UI prefs / market; sync-*.json etc., no credential values)",
+    'export.category.pluginData': "Plugin data under the system home directory (e.g. the config/state of ~/.dsh-wallpaper-engine and ~/.mnemon; regenerable caches are never included)",
+    'export.category.pluginAssets': "Plugins' large files (uploaded wallpapers, local databases, ...; not selected by default)",
     'export.category.mcp': 'MCP server composition (restart required)',
     'export.category.prompts': 'System prompt / Plan Mode prompts',
     'export.category.skills': 'Your skill files (~/.dsh/skills)',