dsh-config-manager 0.1.77 → 0.1.79

package/lib/adapters/plugins.js

@@ -13,16 +13,16 @@
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { sha256Hex } from '../utils/hashing.js';
-import { installSpecFor, resolveProcessProfileName } from '../core/plugin-cli.js';
+import { isBundlesOnlyEntry, mergeBundleDeclaration, pluginInstallTarget, resolveProcessProfileName } from '../core/plugin-cli.js';
 import { classifyPluginSpec, LOCAL_PLUGIN_DIR, resolveLocalPluginPath } from '../core/local-plugin-pack.js';
 import { msgOf, zhMsg } from '../core/messages.js';
 import { engineMsg } from './messages.js';
 import { stringifyJsonSafe } from '../utils/json.js';
 import { isPathSafe, normalizePath } from '../utils/paths.js';
 import { isENOENT } from '../utils/guards.js';
-import { PLUGIN_PATCH_REF_PREFIX } from '../core/backup.js';
+import { PLUGIN_PATCH_REF_PREFIX, PLUGIN_PROFILE_MANIFEST_REF } from '../core/backup.js';
 import { readEffectivePatchLines, resolveWriteLayer, USER_PATCH_FILE } from '../core/patch-layers.js';
-import { parsePnpmPatchedDependencies, sanitizePnpmWorkspacePatches } from './pnpm-workspace.js';
+import { parsePnpmPatchedDependencies, restorePnpmMachinePaths, sanitizePnpmWorkspacePatches, stripPnpmMachinePaths, } from './pnpm-workspace.js';
 import { BUILTIN_PLUGIN_DATA_SOURCES, areasForSection } from '../core/plugin-data-registry.js';
 import { declaredProfileName, scanDeclaredDataSources } from './plugin-data-declared.js';
 import { sectionMeta } from '../schema/section-registry.js';
@@ -85,6 +85,20 @@ async function writeLocalTarball(ctx, tarball) {
 export const PNPM_PROFILE_DIR = (profile) => `profiles/${profile !== undefined && profile !== '' ? profile : 'web'}`;
 /** pnpm-workspace.yaml 相对 $DSH_HOME 的路径（plugins 分区内按「插件安装配置」管理）。 */
 export const PNPM_WORKSPACE_REL = (profile) => `${PNPM_PROFILE_DIR(profile)}/pnpm-workspace.yaml`;
+/**
+ * pnpm 配置可移植净化的可见文案（导出告警 / 导入计划项 detail / 写入结果三处**同一句**，
+ * 不另造通道）：来源机的机器路径键被剥离、本机原有的机器路径键被保留，都必须说出来。
+ */
+function machinePathNotes(msg, stripped, restored) {
+    const notes = [];
+    if (stripped.length > 0) {
+        notes.push(msg('adapter.pwMachinePathStripped', { count: String(stripped.length), keys: stripped.join(', ') }));
+    }
+    if (restored.length > 0) {
+        notes.push(msg('adapter.pwMachinePathKept', { count: String(restored.length), keys: restored.join(', ') }));
+    }
+    return notes;
+}
 /** 单个 patch 文件随备份迁移的体积上限（issue #35；patch 是纯文本，超过说明放错了东西）。 */
 export const MAX_PATCH_FILE_BYTES = 2 * 1024 * 1024;
 /** patch 行 raw 是否由其他 adapter 管理（mcp-client 行 / systemPrompt / planMode 行）。
@@ -246,7 +260,9 @@ function unitsOf(data, tarballBytes, related) {
     const patchFileIds = (data.patchFiles ?? []).map((pf) => `plugins:patch:${normalizePath(pf.relativePath)}`);
     const group = [wsId, ...patchFileIds];
     const units = [];
-    for (const pl of data.plugins) {
+    // data.plugins 可能缺省（空分区 / 手写 section）：按空表处理，不抛错 ——
+    // 选择器对任何分区都会调 listUnits，抛错会让整行退化成不可展开。
+    for (const pl of data.plugins ?? []) {
         const tarball = tarballOf(data, pl.name);
         const measured = tarballBytes?.get(pl.name);
         const areas = related?.get(pl.name);
@@ -261,7 +277,7 @@ function unitsOf(data, tarballBytes, related) {
             ...(areas !== undefined && areas.length > 0 ? { relatedAreas: areas } : {}),
         });
     }
-    for (const line of data.patch) {
+    for (const line of data.patch ?? []) {
         // 由 mcp / prompts adapter 管理的行不属本分区（applyItem 同样跳过），列出来只会误导用户
         if (isManagedElsewhere(line.raw))
             continue;
@@ -351,6 +367,9 @@ export class PluginsAdapter {
                     isBundle: p.isBundle ?? false,
                     inBundles: p.inBundles ?? [],
                     enabled: p.enabled,
+                    // issue #95：只在 dsh.profile.bundles 里声明的层（源机无依赖声明）必须带上这个标记，
+                    // 导入端据此走「只声明」而不是 npm 安装。缺省不写，普通依赖的字节与改造前逐字一致。
+                    ...(p.bundlesOnly === true ? { bundlesOnly: true } : {}),
                 });
             }
         }
@@ -372,7 +391,16 @@ export class PluginsAdapter {
         try {
             const rel = PNPM_WORKSPACE_REL(ctx.profile);
             if (await ctx.fs.exists(rel)) {
-                pnpmWorkspace = new TextDecoder().decode(await ctx.fs.readFile(rel));
+                const raw = new TextDecoder().decode(await ctx.fs.readFile(rel));
+                // 可移植性净化（收集侧）：storeDir / cacheDir … 的值是本机绝对路径，跟着快照跑到
+                // 别的机器上必然指向不存在的目录 → 只带「可移植」的那部分（逐行删除，其余逐字不变）。
+                const strip = stripPnpmMachinePaths(raw);
+                pnpmWorkspace = strip.text;
+                if (strip.stripped.length > 0) {
+                    warnings.push(msgOf(ctx)('adapter.pwMachinePathStripped', {
+                        count: String(strip.stripped.length), keys: strip.stripped.join(', '),
+                    }));
+                }
             }
         }
         catch (err) {
@@ -543,6 +571,83 @@ export class PluginsAdapter {
         }
         return set;
     }
+    /**
+     * 读目标机 profile 的 `dsh.profile.bundles`（issue #95）。
+     *
+     * 相对路径与写入目标同源（`profiles/<profile>/package.json`），走 `ctx.target.fs` 而不是
+     * 宿主私有通道：与 pnpm-workspace.yaml / patch 文件同一条 I/O 纪律（受限、可被 MemFs 测试）。
+     */
+    async targetBundles(ctx) {
+        const rel = `${PNPM_PROFILE_DIR(ctx.target.profile)}/package.json`;
+        try {
+            if (!(await ctx.target.fs.exists(rel)))
+                return { state: 'absent' };
+            const text = new TextDecoder().decode(await ctx.target.fs.readFile(rel));
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                return { state: 'unreadable', reason: ctx.msg('adapter.pluginHostBundleBadJson') };
+            }
+            const bundles = parsed?.dsh?.profile?.bundles;
+            if (!Array.isArray(bundles) || bundles.some((entry) => typeof entry !== 'string')) {
+                return { state: 'unreadable', reason: ctx.msg('adapter.pluginHostBundleBadShape') };
+            }
+            return { state: 'ok', names: new Set(bundles), text };
+        }
+        catch (err) {
+            return { state: 'unreadable', reason: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    /**
+     * 把 host 自带的层声明进目标机 profile 的 `dsh.profile.bundles`（issue #95）。
+     *
+     * 为什么**不走安装通道**：这类层的包由 DSH 从自己的安装位置解析；按裸包名 `dsh plugin add`
+     * 会把 npm `dist-tags.latest` 的副本装进 profile，与 host 的版本线脱节 —— 真机故障：
+     * host 0.2.1-rc.2 + 包 0.2.1-alpha.2 的隔离组契约对不上 → `session-controller` 一直 pending
+     * → 新建会话 service-unavailable。声明不了时只报非致命 warning（§34.17），不拖垮其余配置。
+     */
+    async declareHostBundle(name, ctx) {
+        const msg = ctx.msg;
+        const rel = `${PNPM_PROFILE_DIR(ctx.target.profile)}/package.json`;
+        const view = await this.targetBundles(ctx);
+        if (view.state === 'absent') {
+            return { ok: false, warning: true, message: msg('adapter.pluginHostBundleNoManifest', { name }) };
+        }
+        if (view.state === 'unreadable') {
+            return {
+                ok: false,
+                warning: true,
+                message: msg('adapter.pluginHostBundleManifestUnreadable', { name, reason: view.reason }),
+            };
+        }
+        if (view.names.has(name)) {
+            return { ok: true, needsRestart: false, message: msg('adapter.pluginHostBundleSame', { name }) };
+        }
+        const merged = mergeBundleDeclaration(view.text, name);
+        if (merged === null) {
+            return {
+                ok: false,
+                warning: true,
+                message: msg('adapter.pluginHostBundleManifestUnreadable', {
+                    name,
+                    reason: msg('adapter.pluginHostBundleBadShape'),
+                }),
+            };
+        }
+        try {
+            await ctx.target.fs.writeFile(rel, new TextEncoder().encode(merged.text));
+        }
+        catch (err) {
+            return {
+                ok: false,
+                warning: true,
+                message: msg('adapter.pluginHostBundleWriteFailed', { name, reason: err instanceof Error ? err.message : String(err) }),
+            };
+        }
+        return { ok: true, needsRestart: true, message: msg('adapter.pluginHostBundleDeclared', { name }) };
+    }
     async analyzeImport(data, ctx) {
         const msg = ctx.msg;
         const items = [];
@@ -587,7 +692,10 @@ export class PluginsAdapter {
             // issue #35：目标机满足不了的 patchedDependencies 声明必须剔除——否则写进去之后，
             // 目标机 pnpm 会因为「patch 文件读不到」拒绝**一切** add（含本次要装的插件）。
             const available = await this.patchAvailability(data, ctx);
-            const clean = sanitizePnpmWorkspacePatches(data.pnpmWorkspace, (rel) => available.has(rel));
+            // 可移植性净化（写回侧·纵深防御）：老版本备份 / 第三方工具产出的载荷里可能仍带着
+            // 来源机的机器路径键（本版本收集侧已剥离，正常路径这里就是 no-op）。
+            const stripped = stripPnpmMachinePaths(data.pnpmWorkspace);
+            const clean = sanitizePnpmWorkspacePatches(stripped.text, (rel) => available.has(rel));
             const droppedNames = clean.dropped.map((d) => d.name).join(', ');
             let current = null;
             try {
@@ -599,15 +707,27 @@ export class PluginsAdapter {
             catch {
                 current = null;
             }
-            if (current !== clean.text) {
+            // 写回侧：不搬运来源机的机器路径，也不清掉**本机**自己的设置 → 接回目标机原有的那几行。
+            const merged = restorePnpmMachinePaths(clean.text, current);
+            // 「只差机器路径行」= 目标机现文本剥掉它自己的机器路径行后与将要写入的内容逐字一致。
+            // 此时写回只会把本机那几行挪到末尾（YAML 映射顺序无语义），没有意义 → 不生成计划项：
+            // 零写入、本机设置原地不动，也不给用户造一条无意义的 Update 噪音。
+            const onlyMachinePaths = current !== null && stripPnpmMachinePaths(current).text === clean.text;
+            // 剥完机器路径键后**没有可移植内容**（来源机的配置只剩机器路径）→ 不产出空文件项：
+            // 「无内容形态不得交给 importer」与 collect() 的口径一致。
+            if (merged.text !== '' && !onlyMachinePaths && current !== merged.text) {
+                const details = machinePathNotes(msg, stripped.stripped, merged.restored);
+                if (clean.dropped.length > 0) {
+                    // 既有口径不变：剔除声明的那句话排在最前
+                    details.unshift(msg('adapter.pwPatchesDroppedDetail', { count: String(clean.dropped.length), names: droppedNames }));
+                }
                 items.push({
                     id: 'plugins:pnpm-workspace',
                     kind: current === null ? 'Create' : 'Update',
                     adapter: 'plugins',
                     description: current === null ? msg('adapter.pwCreate') : msg('adapter.pwUpdate'),
-                    ...(clean.dropped.length > 0
-                        ? { detail: msg('adapter.pwPatchesDroppedDetail', { count: String(clean.dropped.length), names: droppedNames }) }
-                        : {}),
+                    // detail 非空 ⇒ isToolchainChangeItem ⇒ 进确认列表（可见、可取消）——净化绝不静默
+                    ...(details.length > 0 ? { detail: details.join(msg('adapter.listSeparator')) } : {}),
                     severity: 'info',
                     target: { adapter: 'plugins', ref: 'pnpm-workspace.yaml' },
                 });
@@ -634,8 +754,44 @@ export class PluginsAdapter {
         }
         // 插件：包名唯一键；同版本 Skip / 未装 Install / 版本不同 Conflict
         const targetInstalled = await ctx.target.plugins.listInstalled();
+        // issue #95：只在 dsh.profile.bundles 里声明的层（源机没有依赖声明）**不装 npm 包** ——
+        // 它的名字只声明进目标机的 bundles，由 DSH 从自己的安装位置解析。只在真出现这类条目时才读
+        // 目标清单（其余场景零额外 I/O，行为与改造前逐字一致）。
+        const bundleView = data.plugins.some((p) => isBundlesOnlyEntry(p)) ? await this.targetBundles(ctx) : null;
         for (const p of data.plugins) {
             const id = `plugin:${p.name}`;
+            if (isBundlesOnlyEntry(p)) {
+                if (bundleView !== null && bundleView.state === 'ok' && bundleView.names.has(p.name)) {
+                    items.push({
+                        id, kind: 'Skip', adapter: 'plugins',
+                        description: msg('adapter.pluginHostBundleSame', { name: p.name }),
+                        detail: msg('adapter.pluginHostBundleDetail'),
+                        severity: 'info',
+                    });
+                }
+                else if (bundleView !== null && bundleView.state === 'ok') {
+                    items.push({
+                        id, kind: 'Create', adapter: 'plugins',
+                        description: msg('adapter.pluginHostBundleDeclare', { name: p.name }),
+                        detail: msg('adapter.pluginHostBundleDetail'),
+                        severity: 'info',
+                        target: { adapter: 'plugins', ref: PLUGIN_PROFILE_MANIFEST_REF },
+                    });
+                }
+                else {
+                    // 清单缺 / 读不到 / 形态不符：**不猜也不重建**，如实告警（非致命，其余分区照常导入）
+                    items.push({
+                        id,
+                        kind: 'Warning',
+                        adapter: 'plugins',
+                        description: bundleView === null || bundleView.state === 'absent'
+                            ? msg('adapter.pluginHostBundleNoManifest', { name: p.name })
+                            : msg('adapter.pluginHostBundleManifestUnreadable', { name: p.name, reason: bundleView.reason }),
+                        severity: 'warning',
+                    });
+                }
+                continue;
+            }
             const tp = targetInstalled.find((t) => t.name === p.name);
             // T1：该插件在备份内自带 tarball（本地源 link:/file:）→ 目标机无需原始路径即可安装。
             const hasTarball = tarballOf(data, p.name) !== undefined;
@@ -748,9 +904,32 @@ export class PluginsAdapter {
                         throw err;
                 }
             }
-            const clean = sanitizePnpmWorkspacePatches(text, (rel) => available.has(rel));
+            // 可移植性净化（写回侧）：先剥掉载荷里的机器路径键（纵深防御），再把目标机**原有的**
+            // 那几行接回去 —— 既不搬运来源机的路径，也不清掉本机自己的 store / 缓存位置。
+            const stripped = stripPnpmMachinePaths(text);
+            const clean = sanitizePnpmWorkspacePatches(stripped.text, (rel) => available.has(rel));
+            const wsRel = PNPM_WORKSPACE_REL(ctx.target.profile);
+            let local = null;
+            try {
+                local = (await ctx.target.fs.exists(wsRel))
+                    ? new TextDecoder().decode(await ctx.target.fs.readFile(wsRel))
+                    : null;
+            }
+            catch (err) {
+                // 「存在但读不到」必须显式失败（只有 ENOENT 才算本来就没有）：读不到就无法保证本机的
+                // 路径设置不被清掉 —— 宁可不写，也不静默丢掉本机的 store / 缓存位置。
+                if (!isENOENT(err)) {
+                    return {
+                        ok: false,
+                        warning: true,
+                        message: msg('adapter.pwLocalReadFailed', { reason: err instanceof Error ? err.message : String(err) }),
+                    };
+                }
+                local = null;
+            }
+            const merged = restorePnpmMachinePaths(clean.text, local);
             try {
-                await ctx.target.fs.writeFile(PNPM_WORKSPACE_REL(ctx.target.profile), new TextEncoder().encode(clean.text));
+                await ctx.target.fs.writeFile(wsRel, new TextEncoder().encode(merged.text));
                 const notes = [msg('adapter.pwWritten')];
                 if (clean.dropped.length > 0) {
                     notes.push(msg('adapter.pwWrittenPatchesDropped', {
@@ -758,6 +937,7 @@ export class PluginsAdapter {
                         names: clean.dropped.map((d) => d.name).join(', '),
                     }));
                 }
+                notes.push(...machinePathNotes(msg, stripped.stripped, merged.restored));
                 return { ok: true, needsRestart: true, message: notes.join(msg('adapter.listSeparator')) };
             }
             catch (err) {
@@ -777,29 +957,56 @@ export class PluginsAdapter {
         // 拖垮已成功导入的其余配置——与 workspaces 的「目标不可达 → warning」同款语义。
         if (item.id.startsWith('plugin:')) {
             const name = item.id.replace(/^plugin:/, '');
+            const data = ctx.sections.get('plugins');
+            // issue #95：host 自带的层（源机只在 dsh.profile.bundles 声明、没有依赖声明）走「只声明」，
+            // 绝不进 npm 安装通道（按裸包名装 = 把 dist-tag latest 的副本塞进 profile）。
+            const entry = data?.plugins.find((p) => p.name === name);
+            if (entry !== undefined && isBundlesOnlyEntry(entry)) {
+                return await this.declareHostBundle(name, ctx);
+            }
             try {
-                // 非 registry 来源（github:/file: 等）按来源 spec 安装，registry 包按裸包名装 npm 最新版
-                const data = ctx.sections.get('plugins');
-                let spec = data?.plugins.find((p) => p.name === name)?.spec;
-                // T1：备份内自带 tarball → 解包到 homeDir 内的本地插件缓存目录，把 spec 重写为绝对路径。
+                // 安装目标由 pluginInstallTarget 统一决策（issue #101）：备份里有具体版本时精确安装，
+                // 其余 registry 包带「包名@spec」；非 registry 来源原样。
+                // T1：备份内自带 tarball → 解包到 homeDir 内的本地插件缓存目录，改以 file:<abs> 安装。
                 // 这是「换机后本地插件不再丢失」的关键：原始绝对路径在目标机不存在，解包出的 tgz 一定存在。
+                let tarballPath;
                 const tarball = data !== undefined ? tarballOf(data, name) : undefined;
                 if (tarball !== undefined) {
                     try {
-                        const abs = await writeLocalTarball(ctx, tarball);
-                        spec = `file:${abs}`;
+                        tarballPath = await writeLocalTarball(ctx, tarball);
                     }
                     catch (err) {
                         // 解包失败不阻断安装尝试：退回原 spec（可能失败，但会如实报错而非静默丢失）
                         ctx.onLog?.(msg('adapter.localTarballUnpackFailed', { name, err: err instanceof Error ? err.message : String(err) }));
                     }
                 }
+                const target = pluginInstallTarget(name, { version: entry?.version, spec: entry?.spec, tarballPath });
                 // 执行日志：记录实际将发起的子进程命令行（与宿主 DshPluginsFacade 的
-                // dsh plugin --profile <p> add <spec> 一致）；仅非敏感文本，渲染前 UI 再 redact 兜底
-                ctx.onLog?.(`$ dsh plugin --profile ${ctx.target.profile ?? resolveProcessProfileName()} add ${installSpecFor(name, spec)}`);
+                // dsh plugin --profile <p> add <target> 一致）；仅非敏感文本，渲染前 UI 再 redact 兜底
+                ctx.onLog?.(`$ dsh plugin --profile ${ctx.target.profile ?? resolveProcessProfileName()} add ${target}`);
                 // 透传中止信号：用户「跳过当前插件」→ 宿主 kill 子进程 + 清半装状态 → 抛 ImportUserSkippedError
-                const result = await ctx.target.plugins.install(name, spec, ctx.signal);
+                const result = await ctx.target.plugins.install(name, target, ctx.signal);
                 const suffix = result.needsRestart ? msg('adapter.pluginRestartSuffix') : '';
+                // 落地校验（issue #101）：官方 CLI 退出 0 不等于版本变了 —— pnpm 会尊重目标机既有
+                // package.json spec，固定版已装、区间已满足时「什么都没装」同样返回 0。回读实际版本再下结论。
+                const expected = entry?.version;
+                const actual = result.installedVersion ?? null;
+                if (expected !== undefined && expected !== '' && actual !== null && actual !== expected) {
+                    return {
+                        ok: false,
+                        warning: true,
+                        needsRestart: true,
+                        message: msg('adapter.pluginVersionMismatch', {
+                            name,
+                            expected,
+                            actual,
+                            command: `dsh plugin --profile ${ctx.target.profile ?? resolveProcessProfileName()} add ${name}@${expected}`,
+                        }),
+                    };
+                }
+                if (actual !== null) {
+                    return { ok: true, needsRestart: true, message: msg('adapter.pluginInstalledAtVersion', { name, version: actual, suffix }) };
+                }
                 return {
                     ok: true,
                     needsRestart: true,
@@ -860,6 +1067,11 @@ export class PluginsAdapter {
                     if (typeof name !== 'string' || name === '') {
                         issues.push({ path: `plugins[${i}].name`, message: msg('adapter.validate.requiredField', { subject: 'plugins[].name' }), severity: 'error' });
                     }
+                    // issue #95：`bundlesOnly` 决定走不走 npm 安装通道，写错类型必须拦下（缺省合法）
+                    const bundlesOnly = p.bundlesOnly;
+                    if (bundlesOnly !== undefined && typeof bundlesOnly !== 'boolean') {
+                        issues.push({ path: `plugins[${i}].bundlesOnly`, message: msg('adapter.validate.boolean', { subject: 'plugins[].bundlesOnly' }), severity: 'error' });
+                    }
                 }
             }
             if (section.patch !== undefined && !Array.isArray(section.patch)) {

package/lib/adapters/pnpm-workspace.d.ts

@@ -24,3 +24,35 @@ export interface SanitizeResult {
  * @param available 判断某相对路径（相对 profile 目录）在**导入后**是否存在
  */
 export declare function sanitizePnpmWorkspacePatches(text: string, available: (relPath: string) => boolean): SanitizeResult;
+/**
+ * 机器相关 pnpm 设置键（根层）。camelCase 是 pnpm-workspace.yaml 的权威拼写；
+ * kebab 变体是同一组设置的另一方言（.npmrc / 部分版本），根层出现同样是本机路径绑定。
+ */
+export declare const PNPM_MACHINE_PATH_KEYS: readonly string[];
+export interface MachinePathStripResult {
+    /** 剥离后的文本（无需改动时与入参**逐字节相同**；只做整行删除，EOL 原样保留） */
+    text: string;
+    /** 被剥离的键（按首次出现顺序去重） */
+    stripped: string[];
+}
+/**
+ * 剥掉机器相关路径键（行级过滤）。
+ *
+ * 值写在同行 → 只删这一行；值写在缩进块里（`storeDir:` / `storeDir: |`）→ 连它的缩进续行
+ * 一起删，避免留下孤儿缩进行把文件变成坏 YAML。其余内容（含注释、空行、行尾缺换行）逐字不变。
+ */
+export declare function stripPnpmMachinePaths(text: string): MachinePathStripResult;
+export interface MachinePathRestoreResult {
+    /** 接回本机路径行后的文本（无需恢复时与入参逐字相同） */
+    text: string;
+    /** 接回的键（按首次出现顺序去重） */
+    restored: string[];
+}
+/**
+ * 把**目标机自己原有的**机器路径行接回将要写入的文本（写回侧）。
+ *
+ * 来源机的路径已在收集侧剥离（这里对老载荷再剥一次是纵深防御），所以本函数接回的只可能是
+ * 目标机原本就有的设置 —— 既不搬运来源机的路径，也不让一次导入清掉本机自己的 store 位置。
+ * `local` 为 null（目标机本来就没有该文件）时原样返回。接回行统一用 incoming 的 EOL。
+ */
+export declare function restorePnpmMachinePaths(incoming: string, local: string | null | undefined): MachinePathRestoreResult;

package/lib/adapters/pnpm-workspace.js

@@ -6,11 +6,13 @@
  * 组合，此后**任何** `pnpm add`（含 dsh plugin add）都失败于
  * `Failed to read patch file ... (os error 2)` —— 用户实测 13/13 插件安装全灭。
  *
- * 本模块做两件事，且**不做整文件重写**（保留用户注释与格式）：
+ * 本模块做三件事，且**不做整文件重写**（保留用户注释与格式）：
  *  1. `parsePnpmPatchedDependencies`：按行解析声明（供导出侧收集 patch 文件）；
  *  2. `sanitizePnpmWorkspacePatches`：把「目标机没有对应文件」的条目整行删掉
  *     （含其上方注释），全部被删时连键一起删 —— 宁可少迁移一条 patch 声明，
- *     也不让目标机的 pnpm 从此拒绝一切安装。
+ *     也不让目标机的 pnpm 从此拒绝一切安装；
+ *  3. `stripPnpmMachinePaths` / `restorePnpmMachinePaths`：机器相关路径键的
+ *     可移植性净化（见文末「可移植性净化」一节）。
  */
 import { isPathSafe, normalizePath } from '../utils/paths.js';
 const KEY_RE = /^patchedDependencies\s*:(.*)$/;
@@ -144,4 +146,113 @@ export function sanitizePnpmWorkspacePatches(text, available) {
         unsupported: null,
     };
 }
+/* ------------------------------------------------------------------ *
+ * 可移植性净化（跨机同步）：机器相关路径键
+ *
+ * `storeDir` / `cacheDir` … 的值是**本机绝对路径**。它们跟着快照跑到另一台机器后必然指向
+ * 不存在的目录（pnpm 会去那里建 store / 缓存）。纪律只有两条：
+ *  1. 收集（导出 / push）与写回（导入 / pull）两侧都**整行删除**这些键 —— 其余内容逐字不变，
+ *     EOL 原样保留（CRLF 输入绝不引入 LF 漂移）；只删「根层 `key:`」形态，
+ *     缩进块里的同名键（如插件的自定义配置）一律不碰；
+ *  2. 写回时把**目标机自己原有的**那几行接回去：不搬运来源机的路径，也不清掉本机自己的设置。
+ *
+ * `.npmrc` 刻意**不进同步面**（见 plugins.ts 的说明）：纳入它会改变 bundle 载荷形态
+ * （docs/spec/bundle-format-v1.md + conformance），而本机 .npmrc 从来就不由本插件写 ——
+ * 「不碰 = 本机保留」。
+ * ------------------------------------------------------------------ */
+/**
+ * 机器相关 pnpm 设置键（根层）。camelCase 是 pnpm-workspace.yaml 的权威拼写；
+ * kebab 变体是同一组设置的另一方言（.npmrc / 部分版本），根层出现同样是本机路径绑定。
+ */
+export const PNPM_MACHINE_PATH_KEYS = [
+    'storeDir', 'store-dir',
+    'globalDir', 'global-dir',
+    'globalBinDir', 'global-bin-dir',
+    'cacheDir', 'cache-dir',
+    'stateDir', 'state-dir',
+    'configDir', 'config-dir',
+];
+const MACHINE_PATH_KEY_SET = new Set(PNPM_MACHINE_PATH_KEYS);
+/** 根层的 `key: value` 形态；缩进行、注释行、块标量内容都不会命中（它们不从行首开始）。 */
+const ROOT_KEY_RE = /^([A-Za-z_][A-Za-z0-9_-]*)[ \t]*:(.*)$/;
+/** 空值或 YAML 块标量（`|` / `>` 及其修饰符）⇒ 值写在其后的缩进行里 */
+function isBlockValue(raw) {
+    const v = raw.trim();
+    return v === '' || /^[|>][+-]?\d*$/.test(v);
+}
+/** 行首若是机器相关键 → 返回键名与冒号后的原文；否则 null（`\r` 不算值的一部分） */
+function rootMachineKey(line) {
+    const m = ROOT_KEY_RE.exec(line.endsWith('\r') ? line.slice(0, -1) : line);
+    if (m === null)
+        return null;
+    const key = m[1] ?? '';
+    if (!MACHINE_PATH_KEY_SET.has(key))
+        return null;
+    return { key, value: m[2] ?? '' };
+}
+/**
+ * 剥掉机器相关路径键（行级过滤）。
+ *
+ * 值写在同行 → 只删这一行；值写在缩进块里（`storeDir:` / `storeDir: |`）→ 连它的缩进续行
+ * 一起删，避免留下孤儿缩进行把文件变成坏 YAML。其余内容（含注释、空行、行尾缺换行）逐字不变。
+ */
+export function stripPnpmMachinePaths(text) {
+    if (text === '')
+        return { text, stripped: [] };
+    const lines = text.split('\n');
+    const out = [];
+    const stripped = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const hit = rootMachineKey(line);
+        if (hit === null) {
+            out.push(line);
+            continue;
+        }
+        if (!stripped.includes(hit.key))
+            stripped.push(hit.key);
+        if (isBlockValue(hit.value)) {
+            while (i + 1 < lines.length && /^[ \t]/.test(lines[i + 1] ?? ''))
+                i += 1;
+        }
+    }
+    return { text: out.join('\n'), stripped };
+}
+/**
+ * 把**目标机自己原有的**机器路径行接回将要写入的文本（写回侧）。
+ *
+ * 来源机的路径已在收集侧剥离（这里对老载荷再剥一次是纵深防御），所以本函数接回的只可能是
+ * 目标机原本就有的设置 —— 既不搬运来源机的路径，也不让一次导入清掉本机自己的 store 位置。
+ * `local` 为 null（目标机本来就没有该文件）时原样返回。接回行统一用 incoming 的 EOL。
+ */
+export function restorePnpmMachinePaths(incoming, local) {
+    if (incoming === '' || local === null || local === undefined || local === '') {
+        return { text: incoming, restored: [] };
+    }
+    const lines = local.split('\n');
+    const kept = [];
+    const restored = [];
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? '';
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        const hit = rootMachineKey(line);
+        if (hit === null)
+            continue;
+        if (!restored.includes(hit.key))
+            restored.push(hit.key);
+        kept.push(line);
+        if (isBlockValue(hit.value)) {
+            while (i + 1 < lines.length && /^[ \t]/.test(lines[i + 1] ?? '')) {
+                i += 1;
+                const cont = lines[i] ?? '';
+                kept.push(cont.endsWith('\r') ? cont.slice(0, -1) : cont);
+            }
+        }
+    }
+    if (kept.length === 0)
+        return { text: incoming, restored: [] };
+    const eol = incoming.includes('\r\n') ? '\r\n' : '\n';
+    const head = incoming.endsWith('\n') ? incoming : incoming + eol;
+    return { text: head + kept.map((l) => l + eol).join(''), restored };
+}
 //# sourceMappingURL=pnpm-workspace.js.map

package/lib/adapters/prompts.d.ts

@@ -1,7 +1,7 @@
 import type { MsgFunc } from '../core/messages.ts';
 import './messages.ts';
 import type { PromptEntry } from '../schema/types.ts';
-import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
+import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
 /** 导出记录：PromptEntry 之外记录来源行名与所在层（导入重建 / 写回定位用） */
 export interface PromptExportEntry extends PromptEntry {
     sourceLineName?: string;
@@ -34,7 +34,11 @@ export declare class PromptsAdapter implements ConfigAdapter<PromptsExportSectio
     readonly displayName: string;
     readonly defaultIncluded: boolean;
     readonly portability: import("../schema/section-registry.ts").SectionPortability;
-    export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<PromptsExportSection>>;
+    export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<PromptsExportSection>>;
+    /** 单元 id：`prompts:<条目 id>`（条目 id 已含来源行与 persona/section 名，天然唯一） */
+    private unitId;
+    /** 条目级单元清单（零 I/O）；label = 条目名，detail = 类型（数据，不是 UI 文案） */
+    listUnits(section: ExportSection<PromptsExportSection>): ExportUnit[];
     analyzeImport(data: PromptsExportSection, ctx: ImportContext): Promise<PlanItem[]>;
     applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
     validate(data: PromptsExportSection, msg?: MsgFunc): Promise<ValidationResult>;

package/lib/adapters/prompts.js

@@ -18,6 +18,7 @@ import './messages.js';
 import { locatePatchLineLayer, readEffectivePatchLines, resolveWriteLayer } from '../core/patch-layers.js';
 import { sectionMeta } from '../schema/section-registry.js';
 import { validateJsonSection } from './json-section.js';
+import { entryByteSize, filterByUnits } from './units.js';
 /**
  * 从 patch 行 config 中提取 prompt 条目（systemPrompt.persona / planMode.sections[].text）。
  *
@@ -115,14 +116,15 @@ export class PromptsAdapter {
     displayName = sectionMeta('prompts').displayName;
     defaultIncluded = sectionMeta('prompts').defaultIncluded;
     portability = sectionMeta('prompts').portability;
-    async export(ctx, _options) {
+    async export(ctx, options) {
         const warnings = [];
         // issue #71：两层都读（home 层优先），否则 profile 层里的 persona / planMode 全部丢失
         const read = await readEffectivePatchLines(ctx.patchFile, ctx.profile);
         for (const f of read.failures) {
             warnings.push(msgOf(ctx)('adapter.patchReadFailedPrompts', { reason: `${f.file}: ${f.reason}` }));
         }
-        const prompts = extractPrompts(read.lines);
+        // 条目级白名单：未勾选的 persona / plan-mode section 不进包
+        const prompts = filterByUnits(extractPrompts(read.lines), options.includeItems?.[this.id], (p) => this.unitId(p));
         return {
             sectionId: 'prompts',
             data: { version: 1, prompts },
@@ -130,6 +132,19 @@ export class PromptsAdapter {
             warnings,
         };
     }
+    /** 单元 id：`prompts:<条目 id>`（条目 id 已含来源行与 persona/section 名，天然唯一） */
+    unitId(prompt) {
+        return this.id + ':' + prompt.id;
+    }
+    /** 条目级单元清单（零 I/O）；label = 条目名，detail = 类型（数据，不是 UI 文案） */
+    listUnits(section) {
+        return (section.data.prompts ?? []).map((p) => ({
+            id: this.unitId(p),
+            label: p.name,
+            detail: p.kind,
+            sizeBytes: entryByteSize(p),
+        }));
+    }
     async analyzeImport(data, ctx) {
         const msg = ctx.msg;
         const items = [];

package/lib/adapters/providers.d.ts

@@ -1,6 +1,6 @@
 import type { MsgFunc } from '../core/messages.ts';
 import type { ProviderEntry } from '../schema/types.ts';
-import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
+import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
 import { type NamespaceProvider } from './settings.ts';
 /** 导出记录：ProviderEntry 之外附加 namespace 级元数据（导入写回用），满足 ProvidersSection 形状 */
 export interface ProviderExportEntry extends ProviderEntry {
@@ -27,7 +27,24 @@ export declare class ProvidersAdapter implements ConfigAdapter<ProviderExportSec
     readonly portability: import("../schema/section-registry.ts").SectionPortability;
     private readonly namespaces;
     constructor(namespaces?: string[] | NamespaceProvider);
-    export(ctx: HostContext, _options: ExportOptions): Promise<ExportSection<ProviderExportSection>>;
+    export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<ProviderExportSection>>;
+    /** 单元 id：`providers:<route>`（route 是 providers 记录的键，天然唯一） */
+    private unitId;
+    /**
+     * 条目级单元清单（零 I/O）：一台 provider（记录里的一个 route）= 一个单元。
+     *
+     * detail 给来源 namespace —— 用户靠它区分「同一个模型走哪个 ns」，不放任何 key 值。
+     */
+    listUnits(section: ExportSection<ProviderExportSection>): ExportUnit[];
+    /**
+     * 白名单过滤 + raw 重建。
+     *
+     * 为什么必须重建 raw：每个 entry.raw 存的是**整个 namespace** 的快照（导入按 namespace 整体替换）。
+     * 只勾 llm-pi-ai 下的一条 route 时若原样带走 raw，未勾的 route 会随 raw 一起进包、
+     * 导入时又被整 namespace 写回目标机 —— 用户看到「没勾却没生效」，选择器等于撒谎。
+     * 因此这里把每个 namespace 的 raw.providers 收窄成「该 ns 里被勾选的 route」集合。
+     */
+    private pickProviders;
     analyzeImport(data: ProviderExportSection, ctx: ImportContext): Promise<PlanItem[]>;
     applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
     validate(data: ProviderExportSection, msg?: MsgFunc): Promise<ValidationResult>;