dsh-config-manager 0.1.78 → 0.1.80

package/lib/routes/sync.js

@@ -40,11 +40,12 @@ function extractPathMappings(body) {
 import { REVIEW_KINDS, ROUTE_TIMEOUT_MS, SYNC_CREDENTIAL_REF, SYNC_WEBDAV_CREDENTIAL_REF, SyncRouteError, buildAutosyncStatus, buildAutosyncStatusByChannel, credentialRef, extractSyncSections, extractSyncSessions, isAutosyncInterval, isGitHubAuthMissing, isToolchainChangeItem, planToConfirmItems, syncPasswordRef, withTimeout, writeSyncRouteError } from '../index.js';
 import { GitHubApiError } from '../market/github-repos.js';
 import { redact } from '../security/redaction.js';
-import { readAutosyncConfig, writeAutosyncConfig } from '../sync/autosync-config.js';
+import { shouldRunOnEnable, readAutosyncConfig, writeAutosyncConfig, clampRemoteCheckMs, clearLastRunResult } from '../sync/autosync-config.js';
 import { isValidExportFileName } from '../sync/backup-files.js';
 import { DeviceFlowStore } from '../sync/github-auth.js';
 import { channelOf, clearSyncChannel, isWebDavConfig, listCloudConfiguredProviders, parseSyncChannel, readFullSyncConfig, writeSyncConfig, gistChannelView, s3ChannelView, cloudSecretRef, S3_COMPAT_PROVIDERS, GIST_PROVIDER } from '../sync/sync-config.js';
 import { SyncEngine } from '../sync/sync-engine.js';
+import { isProbeUnsupported } from '../sync/transport.js';
 import { readSyncHistory } from '../sync/sync-history.js';
 import { SYNC_SELECTION_SCHEMA_VERSION, normalizeSessionsInclude, normalizeSessionsLimit, writeSyncSelection } from '../sync/sync-selection.js';
 import { loadSyncState } from '../sync/sync-state.js';
@@ -83,6 +84,51 @@ export function syncRoutes(env) {
         set: async (ref, value) => { await credentials.set(credentialRef(ref), value); },
         has: async (ref) => (await credentials.describe(credentialRef(ref))).configured,
     };
+    /**
+     * T-ui-merge：合并预览 / 合并执行共用的引擎选项。
+     *
+     * 解密密码口径与 /sync/sync 完全一致：请求体优先，其次已保存的 DECRYPT 凭据
+     * （syncPasswordRef('DECRYPT', channel)）。密码只存在于内存，绝不写进响应 / 日志 / 同步文件；
+     * 明文快照根本不会被解密（引擎只在 manifest.encrypted 时才用密码）。
+     */
+    const mergeEngineOptions = async (body, syncCfg) => {
+        const snapshotId = typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined;
+        const savedDecryptPassword = await resolveSyncPassword(syncPasswordRef('DECRYPT', channelOf(syncCfg)));
+        const decryptPassword = typeof body['decryptPassword'] === 'string' && body['decryptPassword'] !== ''
+            ? body['decryptPassword']
+            : savedDecryptPassword;
+        const pathMappings = extractPathMappings(body);
+        return {
+            ...(snapshotId === undefined ? {} : { snapshotId }),
+            ...(decryptPassword === undefined ? {} : { password: decryptPassword }),
+            ...(pathMappings.length === 0 ? {} : { pathMappings }),
+        };
+    };
+    /**
+     * 合并裁决清单解析（T-ui-merge）。**粒度 = 分区 id**（冻结口径，不做 'id::path' 复合 id）。
+     *
+     * 非法条目直接丢弃 —— 引擎按「未裁决」处理，该分区进 pendingConflicts，界面会如实显示；
+     * 这样既不需要新增宿主文案键，也不会因为客户端字段拼错而静默写坏别的分区。
+     */
+    const extractMergeResolutions = (body) => {
+        const raw = body['resolutions'];
+        if (!Array.isArray(raw))
+            return [];
+        const out = [];
+        for (const entry of raw) {
+            if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+                continue;
+            const rec = entry;
+            const id = rec['id'];
+            const action = rec['action'];
+            if (typeof id !== 'string' || id === '')
+                continue;
+            if (action !== 'keepLocal' && action !== 'useRemote' && action !== 'useMerged' && action !== 'skip')
+                continue;
+            out.push({ id: id, action });
+        }
+        return out;
+    };
     return [
         // ------------------------------------------------------ sync/status
         // m-sync-ui：同步状态（通道配置 / 凭据状态 / 上次同步 / 分区数）。只读，无 secret 值。
@@ -111,7 +157,8 @@ export function syncRoutes(env) {
                     : undefined;
                 // 云端点配置视图（只回 secretStored 布尔；与当前通道无关，配置过即回填）
                 const cloud = await cloudChannelViews(full, credentials);
-                // issue #79：git 工作副本是否已跟随 repoUrl（只读自检，2 条本地只读 git 命令）。
+                // issue #79 / #104 建议 3：git 工作副本是否已跟随 repoUrl，外加「领先远端提交数 /
+                // 远端快照数」（只读自检；后者是「本地一直没真正备份」的预警依据）。
                 // 读不出来时**如实回传错误**（workDirError），不让状态接口静默少一块信息。
                 const gitRepoUrl = full?.git?.repoUrl ?? '';
                 let workDir = null;
@@ -132,6 +179,9 @@ export function syncRoutes(env) {
                     // 已保存的云端点 provider 清单（切换 provider 时回填用；只有名字，无任何值）
                     cloudSavedProviders: await listCloudConfiguredProviders(syncDir),
                     lastSyncAt: state.lastSyncAt === '' ? undefined : state.lastSyncAt,
+                    // 方案 A（同步页按钮瘦身）：是否存在同步基线（本地祖先指针）。**只回布尔，绝不回快照 id** ——
+                    // 界面据此在「有基线 → 三方裁决视图 / 无基线 → 导入确认」之间分派；缺省 undefined 按无基线处理。
+                    hasBaseline: state.lastSnapshotId !== '',
                     sectionCount: Object.keys(state.sections).length,
                     lastTransport: state.transport,
                     // 上次选择的同步通道（磁盘 ui-prefs；UI 回填优先于此，localStorage 仅兜底）
@@ -157,9 +207,11 @@ export function syncRoutes(env) {
             }
         }),
         // ------------------------------------------------------ sync/workdir/reset
-        // issue #79：工作副本的自救入口（改造前 App 内完全没有 —— 改了仓库地址只能手工
-        // git remote set-url，或删掉 <dataDir>/sync/work 重来）。两种模式，破坏性清清楚楚：
+        // issue #79 / #104：工作副本的自救入口（改造前 App 内完全没有 —— 改了仓库地址只能手工
+        // git remote set-url，或删掉 <dataDir>/sync/work 重来）。三种模式，破坏性清清楚楚：
         //   relink  = 只把 origin / push URL 重指向当前配置地址（非破坏性：不碰工作树与本地提交）；
+        //   adopt   = 把远端分支合并进现有工作副本（issue #104：换成另一个仓库、或远端历史被重写后
+        //             两条历史不相交，pull --ff-only 永远失败）；不改写任何本地提交，可 revert；
         //   reclone = 删除工作副本目录后重新 clone（**丢弃未上行的本地提交**）→ 必须显式 confirm。
         // 写动作 → 过 mutation gate（SAFE MODE / 环境锁）；删除边界见 GitTransport.rebuildWorkDir
         // （目录非空且无 .git 一律拒绝，绝不删来路不明的目录）。
@@ -167,8 +219,10 @@ export function syncRoutes(env) {
             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']) }) });
+                if (mode !== 'relink' && mode !== 'adopt' && mode !== 'reclone') {
+                    // 用追加键（含三种模式）而不是既有的 sync.workdirModeInvalid：后者有冻结指纹，
+                    // 只列出了两种模式，继续用会把「adopt 也合法」说反。
+                    writeJson(res, 400, { error: msg('sync.workdirModeInvalidFull', { mode: JSON.stringify(body['mode']) }) });
                     return;
                 }
                 if (mode === 'reclone' && body['confirm'] !== true) {
@@ -605,6 +659,40 @@ export function syncRoutes(env) {
                 writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
             }
         }),
+        // ------------------------------------------------------ sync/probe
+        // cloud-sync 借鉴项 ②：**只读**连通性自检（凭据 / 端点 / 目标容器 / 目录可达），
+        // 供 UI「测试连接」按钮拿到可直接展示的结论（例如 S3 兼容端点该把 region 填成哪个值）。
+        // 只探**已保存**的通道配置（走与 push/pull 同一条配置路径，绝不拿表单里未保存的值去发请求）。
+        // 远端唯一写副作用 = webdav 幂等 MKCOL 补齐上级目录（那正是它要修的故障：目录不存在）。
+        // 失败一律 200 + ok:false —— 「测试连接」是**预期会失败**的诊断动作，用 5xx 表达会被 UI
+        // 当成基础设施故障；文案由通道层本地化并脱敏后原样带回。
+        endpoint({ path: '/api/dsh-config-manager/sync/probe', methods: ['POST'] }, async (req, res) => {
+            const body = await requireJsonObject(req);
+            try {
+                const syncCfg = await prepareSync(body);
+                const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) });
+                const result = await engine.probe();
+                writeJson(res, 200, {
+                    ok: true,
+                    transport: channelOf(syncCfg),
+                    message: result.message,
+                    ...(result.hint !== undefined ? { hint: result.hint } : {}),
+                    ...(result.snapshotCount !== undefined ? { snapshotCount: result.snapshotCount } : {}),
+                    ...(result.createdCollections !== undefined && result.createdCollections.length > 0
+                        ? { createdCollections: result.createdCollections }
+                        : {}),
+                });
+            }
+            catch (error) {
+                // 「该通道不提供自检」是**能力边界**（git 通道按 fast-forward 语义自证），不是故障：
+                // 用稳定错误码标记，界面据此按中性提示渲染，绝不显示成「操作失败」。
+                writeJson(res, 200, {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    ...(isProbeUnsupported(error) ? { unsupported: true } : {}),
+                });
+            }
+        }),
         // ------------------------------------------------------ sync/download
         // 「拉取即导入」：把远端快照**落地成本机 ZIP** 并返回路径，供导入向导消费。
         // 与 /sync/pull 的分工：pull 只做只读差异预览（临时 ZIP 用完即删）；
@@ -682,6 +770,15 @@ export function syncRoutes(env) {
                     sectionCount: m.manifest.sectionIds.length,
                     platform: m.manifest.platform,
                     dshVersion: m.manifest.dshVersion,
+                    // cloud-sync 借鉴项 ⑥：**推送方设备身份**（写在快照 manifest 里；旧快照没有 → 字段不出现）。
+                    // 只回名字与稳定 id（都是本机自己写上去的展示信息，非秘密）；缺字段时绝不回空串占位，
+                    // 让界面能如实区分「旧快照没有这个字段」与「设备名是空的」。
+                    ...(typeof m.manifest.deviceName === 'string' && m.manifest.deviceName !== ''
+                        ? { deviceName: m.manifest.deviceName }
+                        : {}),
+                    ...(typeof m.manifest.deviceId === 'string' && m.manifest.deviceId !== ''
+                        ? { deviceId: m.manifest.deviceId }
+                        : {}),
                 }));
                 const state = await loadSyncState(syncDir);
                 // issue #59：把「远端有但读不出来」的快照如实回传（绝不静默跳过）——
@@ -910,7 +1007,8 @@ export function syncRoutes(env) {
             }
         }),
         // ------------------------------------------------------ sync/autosync
-        // m-sync-v2：自动同步配置读写（按通道：git/webdav 各自的开关 + 间隔 + 启动阈值 + 状态）。
+        // m-sync-v2：自动同步配置读写（按通道：开关 + 兜底间隔 + 启动阈值 + realtime 监听/远端轮询
+        // + 自动应用等级 + 冲突策略 + 运行状态）。
         // GET = 读全部通道状态（{ git, webdav }）；POST = 写指定通道（body.transport，缺省 git）。
         // 同一路径注册为一个 exact 路由（方法内部分发），避免 webserver 对重复 exact 路径报错。
         endpoint({ path: '/api/dsh-config-manager/sync/autosync', methods: ['GET', 'POST'] }, async (req, res) => {
@@ -928,6 +1026,8 @@ export function syncRoutes(env) {
                 // 按通道读写：git/webdav 各自的自动同步配置与运行状态独立（缺省 git 兜底）
                 const channel = parseSyncChannel(body['transport']) ?? 'git';
                 const cfg = await readAutosyncConfig(syncDir, channel);
+                // 「这次 POST 是不是把开关从关拨到开」必须在覆盖字段之前拍下来（issue #105 建议 4）
+                const wasEnabled = cfg.enabled;
                 if (typeof body['enabled'] === 'boolean')
                     cfg.enabled = body['enabled'];
                 if (typeof body['interval'] === 'string' && isAutosyncInterval(body['interval']))
@@ -935,9 +1035,36 @@ export function syncRoutes(env) {
                 if (typeof body['startupMinIntervalMs'] === 'number' && Number.isFinite(body['startupMinIntervalMs']) && body['startupMinIntervalMs'] > 0) {
                     cfg.startupMinIntervalMs = body['startupMinIntervalMs'];
                 }
-                await writeAutosyncConfig(syncDir, channel, cfg);
-                if (scheduler)
+                // 真·自动同步：本地改动即时触发开关 + 远端轮询节奏（非法值一律忽略，绝不写 NaN）
+                if (typeof body['realtime'] === 'boolean')
+                    cfg.realtime = body['realtime'];
+                if (typeof body['remoteCheckMs'] === 'number' && Number.isFinite(body['remoteCheckMs'])) {
+                    cfg.remoteCheckMs = clampRemoteCheckMs(body['remoteCheckMs']);
+                }
+                // 自动应用等级：low = 只自动落低风险分区；medium = plugins/mcp 也自动落盘
+                if (body['autoApplyTier'] === 'low' || body['autoApplyTier'] === 'medium') {
+                    cfg.autoApplyTier = body['autoApplyTier'];
+                }
+                // 冲突策略：ask = 保留冲突待人工裁决；local = 保留本机并推上去（缺省）
+                if (body['conflictPolicy'] === 'ask' || body['conflictPolicy'] === 'local') {
+                    cfg.conflictPolicy = body['conflictPolicy'];
+                }
+                // issue #105：这里写的是**配置**，不是一轮运行结果。此前 readAutosyncConfig 读到的
+                // 上一轮 lastRunMessage/lastRunSkipReason 会被原样写回（"坐实"），于是十天前那次失败的
+                // 错误原文会被一次纯改间隔的保存续命，卡片上继续挂着早已不成立的故障。
+                // 现在：配置落盘前清空上一轮结论 —— 配置变更 ≠ 本轮结论。
+                // issue #105 建议 4：勾选开关是「用户刚刚要求它开始工作」，不该只重排定时器、让卡片
+                // 继续显示上一轮（甚至是十天前）的结论。若距上次运行已超过启动阈值，立刻跑一轮。
+                const runNow = shouldRunOnEnable({ enabled: wasEnabled }, cfg);
+                await writeAutosyncConfig(syncDir, channel, clearLastRunResult(cfg));
+                if (scheduler) {
                     scheduler.reload().catch(() => { });
+                    // 不 await：POST 是配置保存，不能让页面等一次网络同步；结果由调度器自己写进
+                    // sync-autosync.json / sync-history.json。并发由 runOnce 的 running 与 runs 全局防重
+                    // 挡住（在跑时返回 skipped 而不是排队），所以这里不需要额外门控。
+                    if (runNow)
+                        void scheduler.runOnce(channel, { reason: 'enable-toggle' }).catch(() => { });
+                }
                 writeJson(res, 200, await buildAutosyncStatus(syncDir, channel));
             }
             catch (error) {
@@ -1045,6 +1172,43 @@ export function syncRoutes(env) {
                 writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
             }
         })),
+        // ------------------------------------------------------ sync/merge-preview
+        // T-ui-merge：远程合并**只读**预览（三方合并 + 冲突清单 + 摘要）。
+        // 零写入 ⇒ 不过 mutation gate、也不登记同步会话（临时 ZIP 由引擎内部用完即清）；
+        // 解密密码只走内存，响应体不含任何凭据值。
+        endpoint({ path: '/api/dsh-config-manager/sync/merge-preview', methods: ['POST'] }, async (req, res) => {
+            const body = await requireJsonObject(req);
+            try {
+                const syncCfg = await prepareSync(body);
+                const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) });
+                const opts = await mergeEngineOptions(body, syncCfg);
+                const preview = await withTimeout(engine.previewMerge(opts), ROUTE_TIMEOUT_MS, msg('host.syncPullTimeout'));
+                writeJson(res, 200, preview);
+            }
+            catch (error) {
+                writeSyncRouteError(res, error);
+            }
+        }),
+        // ------------------------------------------------------ sync/apply-merge
+        // T-ui-merge：按**分区级**裁决执行合并（写动作 ⇒ mutation gate 'sync-merge-apply'）。
+        // 响应直接透传引擎报告（字段与 /sync/apply-items 同风格）：其中 pendingConflicts =
+        // 执行后仍待裁决的分区 —— skip 不推进同步基线，界面必须如实说明「下次同步仍会出现」。
+        endpoint({ path: '/api/dsh-config-manager/sync/apply-merge', methods: ['POST'] }, withMutationGate('sync-merge-apply', async (req, res, _lockCtx, journalCtx) => {
+            const body = await requireJsonObject(req);
+            try {
+                const syncCfg = await prepareSync(body);
+                const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) });
+                const resolutions = extractMergeResolutions(body);
+                const opts = await mergeEngineOptions(body, syncCfg);
+                // snapshotBinding：与 /sync/apply-items 同口径把 journal 绑定面交给引擎（审计 P0-23），
+                // restoreId 与事务日志因此同源，异常路径下回滚入口拿到的也是同一份快照。
+                const report = await withTimeout(engine.applyMergeResolutions(resolutions, { ...opts, ...(journalCtx !== undefined ? { snapshotBinding: journalCtx } : {}) }), ROUTE_TIMEOUT_MS, msg('host.syncPullTimeout'));
+                writeJson(res, 200, report);
+            }
+            catch (error) {
+                writeSyncRouteError(res, error);
+            }
+        })),
     ];
 }
 //# sourceMappingURL=sync.js.map

package/lib/schema/manifest.d.ts

@@ -1,4 +1,4 @@
-import type { Manifest, Platform, SectionId } from './types.ts';
+import type { Manifest, ManifestForeignOrigin, Platform, SectionId } from './types.ts';
 export declare const MANIFEST_FILE = "manifest.json";
 export declare const CHECKSUMS_FILE = "integrity/checksums.json";
 export declare const EXPORTER_NAME = "DSH Config Manager";
@@ -14,6 +14,11 @@ export interface BuildManifestInput {
     exportedAt?: string;
     /** 导出机的 DSH home（可选；见 Manifest.sourceHome，用于跨机基础路径重定基） */
     sourceHome?: string;
+    /**
+     * 外部来源包的溯源块（可选；见 Manifest.foreign）。
+     * **只有显式传入时才写入** —— 缺省不产生该键，DSH 自产备份与旧包逐字不变。
+     */
+    foreign?: ManifestForeignOrigin;
 }
 /** 构造 manifest（schemaVersion 恒为当前版本，集中于此） */
 export declare function buildManifest(input: BuildManifestInput): Manifest;

package/lib/schema/manifest.js

@@ -21,6 +21,7 @@ export function buildManifest(input) {
         },
         exportedAt: input.exportedAt ?? new Date().toISOString(),
         ...(input.sourceHome !== undefined && input.sourceHome !== '' ? { sourceHome: input.sourceHome } : {}),
+        ...(input.foreign !== undefined ? { foreign: input.foreign } : {}),
         sections: input.sections,
         security: {
             containsSecrets: input.containsSecrets,
@@ -43,6 +44,57 @@ export function parseManifest(raw) {
     }
     return parsed;
 }
+/**
+ * `manifest.foreign`（外部来源溯源块）的**宽容校验**。
+ *
+ * 铁律：本字段**绝不允许**成为拒绝一个包的理由 —— 旧包没有它、新包可能带畸形值，
+ * 两者都必须能继续导入。因此这里只产出 `warning`，且**只落一条**汇总（路径恒为 `foreign`），
+ * 出错字段名以机器码形式列在文案参数里（不逐字段刷屏、不新增用户可见文案）。
+ */
+function validateForeignOrigin(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return [{
+                path: 'foreign',
+                message: schemaMsg('schema.sectionDataInvalid', { section: 'manifest.foreign', issues: 'not-an-object' }),
+                severity: 'warning',
+            }];
+    }
+    const f = value;
+    const bad = [];
+    if (typeof f['agent'] !== 'string')
+        bad.push('agent');
+    if (f['locations'] !== undefined && !isStringArray(f['locations']))
+        bad.push('locations');
+    if (f['sourceVersion'] !== undefined && typeof f['sourceVersion'] !== 'string')
+        bad.push('sourceVersion');
+    if (f['projects'] !== undefined && !isStringArray(f['projects']))
+        bad.push('projects');
+    if (f['credentialRefs'] !== undefined && !isStringArray(f['credentialRefs']))
+        bad.push('credentialRefs');
+    if (f['skipped'] !== undefined && !isSkippedAggregates(f['skipped']))
+        bad.push('skipped');
+    if (f['plugins'] !== undefined && !isPluginSummaries(f['plugins']))
+        bad.push('plugins');
+    if (bad.length === 0)
+        return [];
+    return [{
+            path: 'foreign',
+            message: schemaMsg('schema.sectionDataInvalid', { section: 'manifest.foreign', issues: bad.join(',') }),
+            severity: 'warning',
+        }];
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+function isSkippedAggregates(value) {
+    return Array.isArray(value) && value.every((v) => v !== null && typeof v === 'object'
+        && typeof v['code'] === 'string'
+        && typeof v['count'] === 'number');
+}
+function isPluginSummaries(value) {
+    return Array.isArray(value) && value.every((v) => v !== null && typeof v === 'object'
+        && typeof v['name'] === 'string');
+}
 /** 结构校验：字段类型 / sections 键集合 / security 形状 */
 export function validateManifest(m) {
     const issues = [];
@@ -106,6 +158,9 @@ export function validateManifest(m) {
             issues.push({ path: 'security.encryption', message: schemaMsg('schema.encryptionMustBeObjectOrNull'), severity: 'error' });
         }
     }
+    // foreign 是**外部来源包**的溯源块：缺省 = 旧包（合法）；形状/字段类型不对 = 仅 warning（绝不拒绝）。
+    if (obj['foreign'] !== undefined)
+        issues.push(...validateForeignOrigin(obj['foreign']));
     return issues;
 }
 //# sourceMappingURL=manifest.js.map

package/lib/schema/types.d.ts

@@ -27,6 +27,44 @@ export interface EncryptionInfo {
     authTag: string;
     version: number;
 }
+/**
+ * **外部来源包**的溯源块（manifest.foreign，2026-10-18 新增，纯 additive）。
+ *
+ * 为什么需要它：外部来源（Claude Code / Hermes / …）合成的包是**标准 bundle v1**，
+ * 落盘后与 DSH 自产备份**逐字同构** —— 事后无法复核「这包从哪来」。本块把来源标识、
+ * 读取位置、项目根、插件元数据与跳过聚合写进 manifest，供用户与界面核对。
+ *
+ * 三条纪律（与 src/foreign/types.ts 的 ForeignOrigin 同口径）：
+ *  ① **只放标识与计数，绝不放值**（凭据只有引用名，诊断只有机器码，无一字配置内容）；
+ *  ② 向后兼容：旧包没有该字段 ⇒ 缺省即合法；本字段的存在**绝不能**让旧/新包被拒；
+ *  ③ 缺字段即「不知道」，绝不填默认值假装知道。
+ */
+export interface ManifestForeignOrigin {
+    /** 来源 agent id（稳定机器标识，如 claude-code / hermes；不随文案变化） */
+    agent: string;
+    /** 实际读取的位置（相对 home 的 POSIX 路径；不含任何值） */
+    locations?: string[];
+    /** 来源侧版本标记（读不到即省略） */
+    sourceVersion?: string;
+    /** 被扫描的项目根绝对路径（仅溯源，供用户核对；绝不进任何分区载荷） */
+    projects?: string[];
+    /** 插件清单（名称 / 版本 / 市场 / 来源仓库 / ref / 组件种类；**不含凭据**） */
+    plugins?: {
+        name: string;
+        version?: string;
+        marketplace?: string;
+        repo?: string;
+        ref?: string;
+        components?: string[];
+    }[];
+    /** 跳过与诊断汇总（机器码 + 条数，**不含任何值**） */
+    skipped?: {
+        code: string;
+        count: number;
+    }[];
+    /** 需要用户在目标机补录的凭据引用名（只有名字，**没有任何值**） */
+    credentialRefs?: string[];
+}
 /** 每个导出 ZIP 根部的 manifest.json */
 export interface Manifest {
     schemaVersion: number;
@@ -50,6 +88,12 @@ export interface Manifest {
      * 宽容读取：非字符串/缺失一律按「未知」处理（不重定基，不报错）。
      */
     sourceHome?: string;
+    /**
+     * **外部来源包的溯源块**（见 ManifestForeignOrigin）；DSH 自产备份没有该字段。
+     *
+     * 宽容读取：缺省 = 旧包（合法）；存在但形状/字段类型不对 = 仅 warning（绝不因此拒绝导入）。
+     */
+    foreign?: ManifestForeignOrigin;
     sections: Record<SectionId, boolean>;
     security: {
         containsSecrets: boolean;
@@ -107,8 +151,9 @@ export interface PluginEntry {
     /**
      * 声明依赖 spec（profile package.json dependencies 原样），如 ^0.3.6、
      * github:csyangwen/dsh-memory-evolve、file:/link: 等。
-     * 导入时非 registry 来源（github:/git+/file:/link:/workspace: 等）按此 spec 安装，
-     * 否则按裸包名走 npm 最新版（官方机制）。
+     * 导入时的安装目标由 `core/plugin-cli.ts` 的 `pluginInstallTarget()` 统一推导（issue #101）：
+     * 非 registry 来源按此 spec 原样安装；`version` 是具体 semver 时按 `<name>@<version>` 精确安装；
+     * 其余 spec 按 `<name>@<spec>`；都没有才退回裸包名（npm 最新版）。
      */
     spec?: string;
     /**

package/lib/sync/ancestor.d.ts

@@ -15,6 +15,28 @@ export declare function loadAncestor(localSnapshotsDir: string, snapshotId: stri
  * 用户可见且可裁决。loadAncestor 的「不存在即抛」契约保持不变（显式读取祖先仍应大声失败）。
  */
 export declare function tryLoadAncestor(localSnapshotsDir: string, snapshotId: string, fsx?: SnapshotFs): Promise<SyncSnapshot | undefined>;
+/**
+ * 加密祖先副本的密文载荷文件名（issue #107）。
+ * 加密快照无法平铺成明文 JSON 分区，因此加密祖先目录 = manifest.json + 这一个密文载荷文件。
+ */
+export declare const ENCRYPTED_ANCESTOR_FILE = "sections.encrypted.json";
+/**
+ * 读祖先副本目录：manifest.encrypted=true → 读密文单载荷；否则按散文件布局读回明文。
+ *
+ * 为什么要在这里分派（而不是改 layout.readSnapshotFromDir）：散文件布局对加密快照是**结构性拒绝**
+ * （layoutEncryptedDirUnsupported，git 通道的密文单文件布局依赖它）；祖先副本是本地缓存目录，
+ * 允许有自己的加密形态，且不该让「本地缓存」把明文布局的契约搞松。
+ * 读不出 / 形态不符一律抛错 —— 是否降级为 undefined 由 tryLoadAncestor 决定。
+ */
+export declare function readAncestorSnapshot(dir: string, fsx?: SnapshotFs): Promise<SyncSnapshot>;
+/**
+ * 把**加密**祖先副本写入本地目录（issue #107）。
+ *
+ * 磁盘上只有 manifest.json（manifest.encrypted=true，sectionHashes 为空）+ 单个 AES-GCM 密文载荷；
+ * 密码绝不落盘（载荷里只有 salt/iv/authTag 与密文，与远端加密快照同口径）。
+ * 目录里有 manifest.json ⇒ 仍被 listAncestors / pruneAncestors 当成普通祖先副本，保留策略不变。
+ */
+export declare function writeEncryptedAncestor(localSnapshotsDir: string, snapshot: SyncSnapshot, fsx?: SnapshotFs): Promise<void>;
 /** 把合并后的快照写入本地祖先副本目录（覆盖同名 id）。 */
 export declare function writeAncestor(localSnapshotsDir: string, snapshot: SyncSnapshot, fsx?: SnapshotFs): Promise<void>;
 /** 列出 localSnapshotsDir 下全部祖先快照目录的 (id, createdAt) 对，按 createdAt 升序。 */

package/lib/sync/ancestor.js

@@ -7,6 +7,8 @@ import { createSnapshotFs, joinFs } from './fs.js';
 import { engineMsg } from './messages.js';
 import { readSnapshotFromDir, writeSnapshotToDir } from './layout.js';
 import { SNAPSHOT_MANIFEST_FILE } from './layout.js';
+import { isEncryptedSections } from './transport.js';
+import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
 /** 默认保留的祖先快照数量（最旧超出则被裁剪）。 */
 export const DEFAULT_ANCESTOR_KEEP = 10;
 /** 按 snapshotId 读取祖先快照目录；不存在抛错，不静默降级。 */
@@ -15,7 +17,7 @@ export async function loadAncestor(localSnapshotsDir, snapshotId, fsx = createSn
         throw new Error(engineMsg('sync.ancestorSnapshotIdRequired'));
     }
     const dir = joinFs(localSnapshotsDir, snapshotId);
-    return await readSnapshotFromDir(dir, fsx);
+    return await readAncestorSnapshot(dir, fsx);
 }
 /**
  * 同 loadAncestor，但「目录不存在 / 不可读 / 损坏」→ undefined（P0-7 的降级路径，供三方合并用）。
@@ -31,12 +33,74 @@ export async function tryLoadAncestor(localSnapshotsDir, snapshotId, fsx = creat
     if (typeof snapshotId !== 'string' || snapshotId === '')
         return undefined;
     try {
-        return await readSnapshotFromDir(joinFs(localSnapshotsDir, snapshotId), fsx);
+        return await readAncestorSnapshot(joinFs(localSnapshotsDir, snapshotId), fsx);
     }
     catch {
         return undefined;
     }
 }
+/**
+ * 加密祖先副本的密文载荷文件名（issue #107）。
+ * 加密快照无法平铺成明文 JSON 分区，因此加密祖先目录 = manifest.json + 这一个密文载荷文件。
+ */
+export const ENCRYPTED_ANCESTOR_FILE = 'sections.encrypted.json';
+/**
+ * 读祖先副本目录：manifest.encrypted=true → 读密文单载荷；否则按散文件布局读回明文。
+ *
+ * 为什么要在这里分派（而不是改 layout.readSnapshotFromDir）：散文件布局对加密快照是**结构性拒绝**
+ * （layoutEncryptedDirUnsupported，git 通道的密文单文件布局依赖它）；祖先副本是本地缓存目录，
+ * 允许有自己的加密形态，且不该让「本地缓存」把明文布局的契约搞松。
+ * 读不出 / 形态不符一律抛错 —— 是否降级为 undefined 由 tryLoadAncestor 决定。
+ */
+export async function readAncestorSnapshot(dir, fsx = createSnapshotFs()) {
+    const manifestAbs = joinFs(dir, SNAPSHOT_MANIFEST_FILE);
+    if (!(await fsx.exists(manifestAbs))) {
+        throw new Error(engineMsg('sync.layoutManifestMissing', { file: SNAPSHOT_MANIFEST_FILE, dir }));
+    }
+    const parsed = parseJsonSafe(Buffer.from(await fsx.readFile(manifestAbs)).toString('utf8'));
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(engineMsg('sync.layoutManifestNotObject'));
+    }
+    const m = parsed;
+    const manifest = m['manifest'];
+    if (manifest !== null && typeof manifest === 'object' && !Array.isArray(manifest)
+        && manifest['encrypted'] === true) {
+        const payloadAbs = joinFs(dir, ENCRYPTED_ANCESTOR_FILE);
+        if (!(await fsx.exists(payloadAbs))) {
+            throw new Error(engineMsg('sync.layoutManifestMissing', { file: ENCRYPTED_ANCESTOR_FILE, dir }));
+        }
+        const payload = parseJsonSafe(Buffer.from(await fsx.readFile(payloadAbs)).toString('utf8'));
+        if (!isEncryptedSections(payload)) {
+            throw new Error(engineMsg('sync.layoutManifestMissingFields'));
+        }
+        return {
+            id: typeof m['id'] === 'string' ? m['id'] : '',
+            createdAt: typeof m['createdAt'] === 'string' ? m['createdAt'] : '',
+            manifest: manifest,
+            sections: payload,
+        };
+    }
+    return await readSnapshotFromDir(dir, fsx);
+}
+/**
+ * 把**加密**祖先副本写入本地目录（issue #107）。
+ *
+ * 磁盘上只有 manifest.json（manifest.encrypted=true，sectionHashes 为空）+ 单个 AES-GCM 密文载荷；
+ * 密码绝不落盘（载荷里只有 salt/iv/authTag 与密文，与远端加密快照同口径）。
+ * 目录里有 manifest.json ⇒ 仍被 listAncestors / pruneAncestors 当成普通祖先副本，保留策略不变。
+ */
+export async function writeEncryptedAncestor(localSnapshotsDir, snapshot, fsx = createSnapshotFs()) {
+    if (!isEncryptedSections(snapshot.sections)) {
+        // 结构性断言：明文快照必须走 writeAncestor（散文件布局），不得落进密文单载荷形态
+        throw new Error(engineMsg('sync.layoutEncryptedDirUnsupported'));
+    }
+    const dir = joinFs(localSnapshotsDir, snapshot.id);
+    await fsx.mkdir(dir);
+    const manifest = { id: snapshot.id, createdAt: snapshot.createdAt, manifest: snapshot.manifest, sectionHashes: {} };
+    const enc = new TextEncoder();
+    await fsx.writeFile(joinFs(dir, SNAPSHOT_MANIFEST_FILE), enc.encode(stringifyJsonSafe(manifest, { space: 2 })));
+    await fsx.writeFile(joinFs(dir, ENCRYPTED_ANCESTOR_FILE), enc.encode(stringifyJsonSafe(snapshot.sections, { space: 2 })));
+}
 /** 把合并后的快照写入本地祖先副本目录（覆盖同名 id）。 */
 export async function writeAncestor(localSnapshotsDir, snapshot, fsx = createSnapshotFs()) {
     const dir = joinFs(localSnapshotsDir, snapshot.id);