dsh-config-manager 0.1.69 → 0.1.71

package/lib/adapters/providers.js

@@ -88,17 +88,18 @@ export class ProvidersAdapter {
                     severity: 'warning', target: { adapter: 'providers', ref: entry.namespace },
                 });
             }
+            else if (current !== null && isDeepStrictEqual(current.value, entry.raw ?? stripEntry(entry))) {
+                // 值相等优先于「目标为空」——与 settings.planNamespaceItems 同一口径与顺序（issue #73）
+                items.push({ id, kind: 'Skip', adapter: 'providers', description: msg('adapter.providerSame', { route }), severity: 'info' });
+            }
             else if (current === null || isEmptyValue(current.value)) {
-                // 目标已注册但为空 → 初始化（Create）
+                // 目标已注册但为空**且导入值非空** → 初始化（Create）
                 items.push({
                     id, kind: 'Create', adapter: 'providers',
                     description: msg('adapter.providerCreate', { route, ns: entry.namespace }), severity: 'info',
                     target: { adapter: 'providers', ref: entry.namespace },
                 });
             }
-            else if (isDeepStrictEqual(current.value, entry.raw ?? stripEntry(entry))) {
-                items.push({ id, kind: 'Skip', adapter: 'providers', description: msg('adapter.providerSame', { route }), severity: 'info' });
-            }
             else {
                 items.push({
                     id, kind: 'Conflict', adapter: 'providers',

package/lib/adapters/self.d.ts

@@ -14,6 +14,10 @@
  * 快照/回滚路径一致）；**清单来自覆写的 listRelPaths()（白名单），export() 与 preview() 都经
  * 基类 collect()**（self 目录内存在大量非配置子目录，不能像 skills/sessions 那样整体递归）。
  *
+ * **例外：两个调度配置的比对口径见覆写的 comparableContent()** —— sync-autosync.json /
+ * backup-schedule.json 内含每次执行收尾都被改写的运行态字段，整文件哈希会恒判 Conflict
+ * （每轮同步都重现，用户点「应用」还会把远端陈旧运行态倒灌回本机；issue #73）。
+ *
  * 为什么必须靠 listRelPaths() 而不是覆写 export() 来收窄（2026-10 真机报告）：
  * `preview()` / `listRelPaths()` 是后来才加进基类的。本类此前只覆写 export()，于是只读预览
  * 落到基类的目录递归 —— 把整个 $DSH_HOME/dsh-config-manager（快照、config-snapshots、
@@ -63,4 +67,20 @@ export declare class SelfAdapter extends FileCollectionAdapter {
      * 同时是单元 id（self:<rel>）与 includeItems 的比对键 —— 不能随平台漂移成反斜杠。
      */
     protected listRelPaths(ctx: HostContext): Promise<RecursiveListing>;
+    /**
+     * 幂等比对口径：两个调度配置剔除**运行态字段**后比对，其余白名单文件保持整文件哈希。
+     *
+     * 为什么必要（issue #73）：sync-autosync.json 由调度器在每次执行收尾改写
+     * lastRunAt / lastRunStatus / lastRunMessage / lastRunHistoryId / consecutiveFailures
+     * （src/sync/autosync-scheduler.ts），backup-schedule.json 同理（backup-scheduler）。
+     * 整文件 SHA-256 因此永远与远端不同 → 每轮同步都重现一条 self 分区的 Conflict，
+     * 且用户点「应用」会把远端的陈旧运行态倒灌回本机。
+     * 剔除后：**仅运行态不同 → Skip**（什么都不写，本机运行态保留）；
+     * 配置本体（enabled / interval / startupMinIntervalMs / customSchedule / retention …）不同 → 仍是 Conflict。
+     *
+     * 其余白名单文件（sync-config / sync-selection / ui-prefs / market-config / .backup-notes）
+     * 已核实不含易变字段，保持内容寻址的整文件哈希。
+     * 解析不出 JSON 时原样返回 —— 「判不出来」按整文件哈希处理，绝不猜。
+     */
+    protected comparableContent(relativePath: string, data: Uint8Array): Uint8Array;
 }

package/lib/adapters/self.js

@@ -11,6 +11,58 @@ export const SELF_CONFIG_FILES = [
     // 换机器后备份列表仍能看到手动导出时填写的备注
     'exports/.backup-notes.json',
 ];
+/**
+ * 调度配置里的**运行态字段**：每次执行收尾都会被调度器改写，不属于「配置身份」。
+ * 仅比对时剔除（见 comparableContent）；写盘仍写完整文件。
+ */
+const VOLATILE_RUN_STATE_KEYS = new Set([
+    'lastRunAt', 'lastRunStatus', 'lastRunMessage', 'lastRunHistoryId', 'consecutiveFailures',
+]);
+/** 含运行态字段的调度配置（相对 baseDir）。 */
+const SCHEDULER_CONFIG_RELS = new Set([
+    'sync/sync-autosync.json',
+    'sync/backup-schedule.json',
+]);
+/** 递归剔除运行态键（sync-autosync v2 的 channels.git / channels.webdav 是嵌套对象）。 */
+function stripRunState(node) {
+    if (Array.isArray(node))
+        return node.map(stripRunState);
+    if (node === null || typeof node !== 'object')
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (VOLATILE_RUN_STATE_KEYS.has(key))
+            continue;
+        out[key] = stripRunState(value);
+    }
+    return out;
+}
+/** 键排序的稳定序列化：两边键序不同（手改过的文件）时不应凭空判 Conflict。 */
+function stableStringify(node) {
+    if (Array.isArray(node))
+        return '[' + node.map(stableStringify).join(',') + ']';
+    if (node === null || typeof node !== 'object')
+        return JSON.stringify(node) ?? 'null';
+    const entries = Object.entries(node)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return '{' + entries.map(([k, v]) => JSON.stringify(k) + ':' + stableStringify(v)).join(',') + '}';
+}
+/**
+ * 剔除运行态后的规范化 JSON 字节；解析不出 JSON（或顶层不是对象）→ null。
+ * **null = 「判不出可比形态」**，调用方回落原字节按整文件哈希处理 —— 不猜。
+ */
+function canonicalizeWithoutRunState(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(raw));
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    return new TextEncoder().encode(stableStringify(stripRunState(parsed)));
+}
 export class SelfAdapter extends FileCollectionAdapter {
     id = 'self';
     displayName = 'Plugin Self Config';
@@ -64,5 +116,26 @@ export class SelfAdapter extends FileCollectionAdapter {
         }
         return { ...empty, paths: found };
     }
+    /**
+     * 幂等比对口径：两个调度配置剔除**运行态字段**后比对，其余白名单文件保持整文件哈希。
+     *
+     * 为什么必要（issue #73）：sync-autosync.json 由调度器在每次执行收尾改写
+     * lastRunAt / lastRunStatus / lastRunMessage / lastRunHistoryId / consecutiveFailures
+     * （src/sync/autosync-scheduler.ts），backup-schedule.json 同理（backup-scheduler）。
+     * 整文件 SHA-256 因此永远与远端不同 → 每轮同步都重现一条 self 分区的 Conflict，
+     * 且用户点「应用」会把远端的陈旧运行态倒灌回本机。
+     * 剔除后：**仅运行态不同 → Skip**（什么都不写，本机运行态保留）；
+     * 配置本体（enabled / interval / startupMinIntervalMs / customSchedule / retention …）不同 → 仍是 Conflict。
+     *
+     * 其余白名单文件（sync-config / sync-selection / ui-prefs / market-config / .backup-notes）
+     * 已核实不含易变字段，保持内容寻址的整文件哈希。
+     * 解析不出 JSON 时原样返回 —— 「判不出来」按整文件哈希处理，绝不猜。
+     */
+    comparableContent(relativePath, data) {
+        if (!SCHEDULER_CONFIG_RELS.has(relativePath))
+            return data;
+        // 回落原引用（解析失败 / 非对象）：走整文件哈希，且不额外重算包内哈希
+        return canonicalizeWithoutRunState(data) ?? data;
+    }
 }
 //# sourceMappingURL=self.js.map

package/lib/adapters/sessions.d.ts

@@ -135,5 +135,13 @@ export declare class SessionsAdapter extends FileCollectionAdapter {
      */
     private orphanSubagentWarnings;
     applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
+    /**
+     * 目标机上是否存在该会话单元的**任何文件**（ui-F1 的判据）。
+     *
+     * 用途：归位失败且宿主报 `unavailable` 时，区分「目录不存在（本次没写它）」与「真的搬不动」。
+     * 目录列表都读不到（门面抛错）按「不确定」处理 → 返回 true：保守地保留原有的硬失败上报，
+     * 绝不把一次真实的搬迁失败悄悄降级成成功。
+     */
+    private unitOnTargetDisk;
     finalizeApply(ctx: ImportContext): Promise<ApplyResult[]>;
 }

package/lib/adapters/sessions.js

@@ -29,6 +29,15 @@ const MTIME_BATCH = 16;
  * 请求结束后计数随之消失（不会把会话内容或路径长期留在内存里）。
  */
 const writtenSessionFiles = new WeakMap();
+/**
+ * 本次导入**真正写过的会话单元**（`<项目键>/<会话目录>`，与 `unitIdOf` 同一口径）。
+ *
+ * 为什么需要它（ui-F1）：`finalizeApply` 拿到的是**整份分区载荷**，而用户可以在确认页
+ * 逐条取消勾选（`buildSelectedPlan` 只裁 `plan.items`，载荷不受影响）。按载荷做归位判定时，
+ * 「用户取消勾选、盘上根本没有」的会话会以 `relocateDir → unavailable` 收场，被记成**硬失败**
+ * → `anyFailed` → 在 `rollbackOnError=true`（向导默认、同步通道恒 true）下**整笔导入回滚**。
+ * 与 `writtenSessionFiles` 同样以 ImportContext 为键：宿主每个进程只建一次 adapters。 */
+const writtenSessionUnits = new WeakMap();
 export class SessionsAdapter extends FileCollectionAdapter {
     id = 'sessions';
     displayName = 'Sessions';
@@ -437,10 +446,36 @@ export class SessionsAdapter extends FileCollectionAdapter {
     async applyItem(item, ctx) {
         const result = await super.applyItem(item, ctx);
         // 只累计「本次导入（同一 ImportContext）」写成功的数量 —— 见 writtenSessionFiles 的说明。
-        if (result.ok)
+        if (result.ok) {
             writtenSessionFiles.set(ctx, (writtenSessionFiles.get(ctx) ?? 0) + 1);
+            const ref = item.target?.ref;
+            if (ref !== undefined && ref !== '') {
+                let units = writtenSessionUnits.get(ctx);
+                if (units === undefined) {
+                    units = new Set();
+                    writtenSessionUnits.set(ctx, units);
+                }
+                units.add(toPosixRel(this.unitIdOf(ref)));
+            }
+        }
         return result;
     }
+    /**
+     * 目标机上是否存在该会话单元的**任何文件**（ui-F1 的判据）。
+     *
+     * 用途：归位失败且宿主报 `unavailable` 时，区分「目录不存在（本次没写它）」与「真的搬不动」。
+     * 目录列表都读不到（门面抛错）按「不确定」处理 → 返回 true：保守地保留原有的硬失败上报，
+     * 绝不把一次真实的搬迁失败悄悄降级成成功。
+     */
+    async unitOnTargetDisk(ctx, unit) {
+        try {
+            const listing = await listFilesDetailed(ctx.target.fs, this.baseDir + '/' + unit);
+            return listing.paths.length > 0;
+        }
+        catch {
+            return true;
+        }
+    }
     async finalizeApply(ctx) {
         const data = ctx.sections.get('sessions');
         if (data === undefined || !Array.isArray(data.files))
@@ -471,7 +506,13 @@ export class SessionsAdapter extends FileCollectionAdapter {
         const mappings = ctx.pathMappings ?? [];
         const rewrite = store.rewriteLogDir;
         const reindex = store.reindexSessionHeader;
+        // ui-F1：本次没有写过的单元（用户取消勾选 / 未进计划）不做归位与改写判定 ——
+        // 「目录不存在」是它的正常形态，不是失败。appliedUnits 缺省（整批都没走 applyItem，
+        // 例如用户取消全部会话或单测直接调用）时保持既有行为：按载荷逐单元判定。
+        const appliedUnits = writtenSessionUnits.get(ctx);
         for (const [unit, files] of byUnit) {
+            if (appliedUnits !== undefined && !appliedUnits.has(unit))
+                continue;
             let cwd;
             for (const file of files) {
                 const name = toPosixRel(file.relativePath).split('/').pop() ?? '';
@@ -552,6 +593,11 @@ export class SessionsAdapter extends FileCollectionAdapter {
             if (moved.moved) {
                 results.push({ ok: true, message: ctx.msg('import.sessionRelocated', { unit, from: current, to: expected }) });
             }
+            else if (moved.reason === 'unavailable' && !(await this.unitOnTargetDisk(ctx, unit))) {
+                // ui-F1：目录在目标机上根本不存在 ⇒ 本次没有它的数据（用户取消勾选 / 未写盘）。
+                // 没有可归位的东西，绝不能记硬失败（会 no-op 地触发 rollbackOnError 整体回滚）。
+                continue;
+            }
             else {
                 results.push({ ok: false, message: ctx.msg('import.sessionRelocateFailed', { unit, reason: moved.reason ?? 'unavailable' }) });
             }

package/lib/adapters/settings.d.ts

@@ -1,16 +1,34 @@
 import type { MsgFunc } from '../core/messages.ts';
 import type { NamespaceRecord, SettingsSection } from '../schema/types.ts';
-import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext, ImportContext, PlanItem, ValidationResult } from '../core/types.ts';
+import type { ApplyResult, ConfigAdapter, ExportOptions, ExportSection, HostContext, ImportContext, NamespaceInfo, PlanItem, ValidationResult } from '../core/types.ts';
 /** namespace 清单提供者：宿主从 settings.yaml 顶层 key / 插件注册表获得 */
 export type NamespaceProvider = (ctx: HostContext) => Promise<string[]> | string[];
 export declare function resolveNamespaces(namespaces: string[] | NamespaceProvider, ctx: HostContext): Promise<string[]>;
+/**
+ * 一次读回全部 namespace 的 redacted 记录（仅当宿主实现了 `SettingsFacade.describeAll`）。
+ *
+ * 为什么需要：真实 DSH 的 `SettingsProvider.describe()` 是「无参 = 全量」的 —— 每次调用都对
+ * 全部注册项重跑 `schema.toJSON()` + 多次 `structuredClone` + `redactSecrets`，所以「按名单
+ * 逐个 describe」实际是 O(N²)：真机 24 个 namespace 实测 ≈1.7 s，而一次全量只需 ≈70 ms。
+ * 宿主未实现 describeAll（或调用抛错）时返回 `null`，调用方退回逐名 describe —— 与改造前逐字一致。
+ */
+export declare function readNamespaceMap(ctx: HostContext): Promise<Map<string, NamespaceInfo> | null>;
+/**
+ * 从全量 Map 取单个 namespace；缺失时抛出与逐名 `describe()` **逐字相同**的错误
+ * （`namespace not found: <name>`），保证快慢两条路径的告警文案与条目一致。
+ */
+export declare function namespaceFromMap(all: Map<string, NamespaceInfo>, name: string): NamespaceInfo;
 /** 批量读取 namespace 的 redacted 记录（settings/ui 共用；单项失败跳过并告警） */
 export declare function collectNamespaceRecords(ctx: HostContext, names: string[], warnings: string[]): Promise<Record<string, NamespaceRecord>>;
 /** 值是否“空”（目标已注册但从未配置 → 视为待初始化，Create 而非 Conflict） */
 export declare function isEmptyValue(v: unknown): boolean;
-/** 对比导入记录与目标当前值：不存在 → Create；一致 → Skip；不同 → Conflict；
+/** 对比导入记录与目标当前值：一致（含两端皆空）→ Skip；目标为空且导入非空 → Create；其余不同 → Conflict；
  * 目标端 describe 抛错（命名空间未注册：提供它的插件在目标未激活/未安装）→ MissingDependency（§15 依赖检测），
- * 此时 Create/Update 必然失败，标记为“需注意”让导入继续，而不是整体失败。纯计算，零写入。 */
+ * 此时 Create/Update 必然失败，标记为“需注意”让导入继续，而不是整体失败。纯计算，零写入。
+ *
+ * **判定顺序不得回退**（issue #73）：一致判定必须排在「目标为空」之前 —— isEmptyValue({}) 为真，
+ * 反序会把「{} 覆盖 {}」判成 Create，而写入 {} 是空写入 no-op，下一轮 describe 仍返回 {}，
+ * 于是每次同步都重现同一项，永不收敛。 */
 export declare function planNamespaceItems(data: Record<string, NamespaceRecord>, adapter: 'settings' | 'ui', ctx: ImportContext): Promise<PlanItem[]>;
 /** 写入单个 namespace（settings/ui 共用）：读时锁 + expectedRevision 乐观锁，防覆盖并发修改 */
 export declare function applyNamespaceItem(item: PlanItem, sectionId: 'settings' | 'ui', ctx: ImportContext): Promise<ApplyResult>;

package/lib/adapters/settings.js

@@ -14,12 +14,44 @@ import { validateJsonSection } from './json-section.js';
 export async function resolveNamespaces(namespaces, ctx) {
     return typeof namespaces === 'function' ? namespaces(ctx) : namespaces;
 }
+/**
+ * 一次读回全部 namespace 的 redacted 记录（仅当宿主实现了 `SettingsFacade.describeAll`）。
+ *
+ * 为什么需要：真实 DSH 的 `SettingsProvider.describe()` 是「无参 = 全量」的 —— 每次调用都对
+ * 全部注册项重跑 `schema.toJSON()` + 多次 `structuredClone` + `redactSecrets`，所以「按名单
+ * 逐个 describe」实际是 O(N²)：真机 24 个 namespace 实测 ≈1.7 s，而一次全量只需 ≈70 ms。
+ * 宿主未实现 describeAll（或调用抛错）时返回 `null`，调用方退回逐名 describe —— 与改造前逐字一致。
+ */
+export async function readNamespaceMap(ctx) {
+    const describeAll = ctx.settings.describeAll;
+    if (typeof describeAll !== 'function')
+        return null;
+    try {
+        const all = await describeAll.call(ctx.settings, { redactSecrets: true });
+        return new Map(all.map((d) => [d.ns, d.info]));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 从全量 Map 取单个 namespace；缺失时抛出与逐名 `describe()` **逐字相同**的错误
+ * （`namespace not found: <name>`），保证快慢两条路径的告警文案与条目一致。
+ */
+export function namespaceFromMap(all, name) {
+    const info = all.get(name);
+    if (info === undefined)
+        throw new Error(`namespace not found: ${name}`);
+    return info;
+}
 /** 批量读取 namespace 的 redacted 记录（settings/ui 共用；单项失败跳过并告警） */
 export async function collectNamespaceRecords(ctx, names, warnings) {
     const namespaces = {};
+    // 快路径：宿主能一次读回全部 namespace 时只读一趟；否则逐名读（见 readNamespaceMap）
+    const all = names.length > 0 ? await readNamespaceMap(ctx) : null;
     for (const name of names) {
         try {
-            const info = await ctx.settings.describe(name, { redactSecrets: true });
+            const info = all !== null ? namespaceFromMap(all, name) : await ctx.settings.describe(name, { redactSecrets: true });
             namespaces[name] = {
                 value: info.value,
                 base: info.base,
@@ -42,9 +74,13 @@ export function isEmptyValue(v) {
         return Object.keys(v).length === 0;
     return false;
 }
-/** 对比导入记录与目标当前值：不存在 → Create；一致 → Skip；不同 → Conflict；
+/** 对比导入记录与目标当前值：一致（含两端皆空）→ Skip；目标为空且导入非空 → Create；其余不同 → Conflict；
  * 目标端 describe 抛错（命名空间未注册：提供它的插件在目标未激活/未安装）→ MissingDependency（§15 依赖检测），
- * 此时 Create/Update 必然失败，标记为“需注意”让导入继续，而不是整体失败。纯计算，零写入。 */
+ * 此时 Create/Update 必然失败，标记为“需注意”让导入继续，而不是整体失败。纯计算，零写入。
+ *
+ * **判定顺序不得回退**（issue #73）：一致判定必须排在「目标为空」之前 —— isEmptyValue({}) 为真，
+ * 反序会把「{} 覆盖 {}」判成 Create，而写入 {} 是空写入 no-op，下一轮 describe 仍返回 {}，
+ * 于是每次同步都重现同一项，永不收敛。 */
 export async function planNamespaceItems(data, adapter, ctx) {
     const msg = ctx.msg;
     const items = [];
@@ -67,16 +103,17 @@ export async function planNamespaceItems(data, adapter, ctx) {
                 severity: 'warning', target: { adapter, ref: name },
             });
         }
+        else if (current !== null && isDeepStrictEqual(current.value, rec.value)) {
+            // 值相等优先于「目标为空」：两端皆空（如注册后从未配置的 {}）必须 Skip（issue #73）。
+            items.push({ id, kind: 'Skip', adapter, description: msg('adapter.settingsSame', { name }), severity: 'info' });
+        }
         else if (current === null || isEmptyValue(current.value)) {
-            // 目标已注册但从未配置（空值）→ 初始化（Create）
+            // 目标已注册但从未配置（空值）**且导入值非空** → 初始化（Create）
             items.push({
                 id, kind: 'Create', adapter, description: msg('adapter.settingsCreate', { name }), severity: 'info',
                 target: { adapter, ref: name },
             });
         }
-        else if (isDeepStrictEqual(current.value, rec.value)) {
-            items.push({ id, kind: 'Skip', adapter, description: msg('adapter.settingsSame', { name }), severity: 'info' });
-        }
         else {
             items.push({
                 id, kind: 'Conflict', adapter, description: msg('adapter.settingsDiff', { name }),

package/lib/adapters/skills.d.ts

@@ -1,13 +1,45 @@
+import { FileCollectionAdapter } from './file-collection.ts';
+import type { HostContext, SkillDefinitionView } from '../core/types.ts';
+import type { RecursiveListing } from '../utils/recursive-walk.ts';
+/** 技能服务技能的虚拟路径（相对 baseDir）：`<name>/SKILL.md`。 */
+export declare function skillServiceRel(name: string): string;
 /**
- * skills 分区 adapter（设计 §3.3）：
- * 数据源 = ~/.dsh/skills/（flat .md + 目录 bundle；dsh-skill-filesystem 发现）。
- * 仅迁移用户主目录技能；~/.agents/skills、项目级技能默认不迁（研究报告 §2.2）。
+ * 由技能定义重建 `SKILL.md` 文本。
+ *
+ * 字段口径与 dsh-skill-filesystem 的解析器逐一对齐（多写一个键就会让 DSH 报
+ * 「unsupported」并**忽略整个技能**，少写一个键则会丢失调用策略）：
+ *  - 必需：`name` / `description`；
+ *  - 可选：`whenToUse`；
+ *  - 调用策略**只接受** `disable-model-invocation` / `user-invocable`
+ *    （`modelInvocable` / `userInvocable` 会被判为 legacy 键并拒绝）。
  */
-import { FileCollectionAdapter } from './file-collection.ts';
+export declare function buildSkillFile(def: SkillDefinitionView): string;
 export declare class SkillsAdapter extends FileCollectionAdapter {
     readonly id: 'skills';
     readonly displayName: string;
     readonly defaultIncluded: boolean;
     readonly portability: import("../schema/section-registry.ts").SectionPortability;
     readonly baseDir = "skills";
+    /** 本趟由技能服务贡献的技能定义（相对路径 → 定义）。每次 collect 前重建，避免跨趟串味。 */
+    private serviceSkills;
+    /**
+     * 枚举 = 目录扫描 ∪ 技能服务清单。
+     *
+     * 服务不可用（旧宿主 / 无 skills 服务）时**完全退回**目录扫描：一个告警都不多加，
+     * 行为与改造前逐项一致（file-collection.test.ts 钉住「无服务时不产生新告警」）。
+     */
+    protected listRelPaths(ctx: HostContext): Promise<RecursiveListing>;
+    /** 分区内相对路径 → 枚举清单口径（含 baseDir；本分区 baseDir 恒为 `skills`，没有根分区形态）。 */
+    private listRelPathOf;
+    /**
+     * 读成员：先看本趟的服务清单（虚拟 `<name>/SKILL.md`），命中则用重建文本；
+     * 否则走基类的文件读（含 statSize 快路径）。
+     *
+     * 两条路都必须给出**同一个体积口径**（UTF-8 字节数），否则字节闸门在预览与导出之间分叉。
+     */
+    protected readMember(ctx: HostContext, rel: string, mode: 'content' | 'size', statTimes?: Map<string, number>): Promise<{
+        data: Uint8Array;
+        sizeBytes: number;
+        contentHash: string;
+    }>;
 }

package/lib/adapters/skills.js

@@ -1,10 +1,153 @@
 /**
- * skills 分区 adapter（设计 §3.3）：
- * 数据源 = ~/.dsh/skills/（flat .md + 目录 bundle；dsh-skill-filesystem 发现）。
- * 仅迁移用户主目录技能；~/.agents/skills、项目级技能默认不迁（研究报告 §2.2）。
+ * skills 分区 adapter（设计 §3.3；issue #71 重做数据源）。
+ *
+ * 数据源**两路合并**：
+ *  1. **文件目录** `$DSH_HOME/skills`（flat `.md` + `<name>/SKILL.md` bundle）；
+ *  2. **技能服务** `ctx.skills`（DSH 的 `@deepseek-ai/dsh-skill` 注册表）—— 这是**唯一**能
+ *     看见「外壳技能」的通道。
+ *
+ * 为什么必须加第 2 路（真机报告「备份不到外壳 skills」）：技能 provider 由插件在 apply 时注册
+ * （`ctx.skills.registerProvider`），来源可以是
+ *  - pnpm 装进 profile 的插件包（`profiles/<p>/node_modules` 下任意层级的 `SKILL.md`，如 dsh-reverse-skill）；
+ *  - 插件配置项 `customSkillDirs` 指向的任意目录；
+ *  - 内置目录 `DSH_BUNDLED_SKILL_DIR`。
+ * 这些技能**一个都不在** `$DSH_HOME/skills` 里，只扫目录的结果就是「技能分区恒为空」。
+ *
+ * 合并语义（与 `ctx.skills` 自己的层级语义一致：global 打底、scope 链覆盖）：
+ *  - 服务里的技能统一映射成虚拟路径 `<name>/SKILL.md`（DSH 自己的目录形态）；
+ *  - 同一相对路径**文件系统优先**（用户磁盘上的原文是事实源，服务可能已做归一化）；
+ *  - 单元 id 仍是首个路径段 = 技能名（`unitIdOf` 缺省规则），因此选择器上「一个技能一个勾选项」，
+ *    且与导入侧 `PlanItem.unitId` 自动对齐。
+ *
+ * 仅迁移用户可迁移的技能：项目级技能（`.agents/skills`、仓库内 skills 目录）不在本分区射程内
+ * （研究报告 §2.2 同策略）。
  */
+import path from 'node:path';
 import { FileCollectionAdapter } from './file-collection.js';
+import { sha256Hex } from '../utils/hashing.js';
+import { isPathSafe, normalizePath } from '../utils/paths.js';
 import { sectionMeta } from '../schema/section-registry.js';
+/** 技能服务技能的虚拟路径（相对 baseDir）：`<name>/SKILL.md`。 */
+export function skillServiceRel(name) {
+    return normalizePath(path.join(name, 'SKILL.md'));
+}
+/**
+ * YAML 标量编码（issue #71 真机验收发现的缺陷修复）。
+ *
+ * 原实现只做单引号转义（`'` → `''`），**值里含换行时会写出跨行的单引号标量**：真机
+ * `binary-diff` 的 `description` 是块标量（解析后含换行），落盘即非法 YAML，外壳
+ * `dsh-skill-filesystem` 会 `skill file … ignored: invalid YAML frontmatter` 把**整个技能丢掉**
+ * ——比不备份更糟。三档策略（都不 import `js-yaml`，adapters 层不该依赖它）：
+ *  1. 能安全缩进的多行值 → 块标量 `|`（可读、便于 diff）；
+ *  2. 含换行 / 回车 / 控制字符的值 → 双引号 + 转义（转义表与 js-yaml dumper 一致）；
+ *  3. 其余单行值 → 单引号（与原行为一致，`'` 用 `''` 转义）。
+ * 三档都保证解析回来与原字符串**逐字符相等**。
+ */
+const NAMED_ESCAPES = {
+    '\0': '\\0',
+    '\x07': '\\a',
+    '\b': '\\b',
+    '\t': '\\t',
+    '\n': '\\n',
+    '\v': '\\v',
+    '\f': '\\f',
+    '\r': '\\r',
+    '\x1b': '\\e',
+    '"': '\\"',
+    '\\': '\\\\',
+    '\x85': '\\N',
+    '\xa0': '\\_',
+    '\u2028': '\\L',
+    '\u2029': '\\P',
+};
+/** 该字符必须转义才能安全出现在 YAML 标量里（控制字符 / DEL / C1 / BOM / 代理对）。 */
+function needsEscape(ch) {
+    const code = ch.codePointAt(0) ?? 0;
+    return (code < 0x20 ||
+        code === 0x7f ||
+        (code >= 0x80 && code <= 0xa0) ||
+        code === 0xfeff ||
+        code === 0xfffe ||
+        code === 0xffff ||
+        (code >= 0xd800 && code <= 0xdfff));
+}
+/** 双引号标量（唯一能无损表达任意字符串的 YAML 标量形态）。 */
+function doubleQuoteYaml(value) {
+    let out = '"';
+    for (const ch of value) {
+        const named = NAMED_ESCAPES[ch];
+        if (named !== undefined)
+            out += named;
+        else if (needsEscape(ch)) {
+            const code = ch.codePointAt(0) ?? 0;
+            const hex = code.toString(16).toUpperCase();
+            out += code <= 0xff ? `\\x${hex.padStart(2, '0')}` : `\\u${hex.padStart(4, '0')}`;
+        }
+        else
+            out += ch;
+    }
+    return `${out}"`;
+}
+/**
+ * 该值能否写成块标量 `|`（缩进 2 空格）。
+ *
+ * 块标量默认 clip chomping：**恰好一个**尾换行会被还原，没有尾换行会多补一个、多个尾换行会被裁到
+ * 一个（实测 `a\n\n` → `a\n`）⇒ 只对「以恰好一个换行结尾」的值无损。行内空行本身安全
+ * （实测 `a\n\nb\n` 精确往返）；含回车、非空行有首尾空白、或含需转义字符的仍走双引号。
+ */
+function canUseBlockScalar(value) {
+    if (!value.endsWith('\n') || value.endsWith('\n\n'))
+        return false;
+    if (value.includes('\r'))
+        return false;
+    for (const line of value.split('\n')) {
+        if (line === '')
+            continue;
+        if (/^[ \t]|[ \t]$/.test(line))
+            return false;
+        for (const ch of line)
+            if (needsEscape(ch))
+                return false;
+    }
+    return true;
+}
+/** 值 → YAML 标量（三档策略见上方注释）。 */
+function yamlScalar(value) {
+    if (canUseBlockScalar(value)) {
+        // 尾换行交给块标量的 clip chomping 还原（见 canUseBlockScalar 注释），故先摘掉
+        const body = value
+            .slice(0, -1)
+            .split('\n')
+            .map((line) => `  ${line}`)
+            .join('\n');
+        return `|\n${body}`;
+    }
+    if (/[\n\r]/.test(value) || [...value].some(needsEscape))
+        return doubleQuoteYaml(value);
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * 由技能定义重建 `SKILL.md` 文本。
+ *
+ * 字段口径与 dsh-skill-filesystem 的解析器逐一对齐（多写一个键就会让 DSH 报
+ * 「unsupported」并**忽略整个技能**，少写一个键则会丢失调用策略）：
+ *  - 必需：`name` / `description`；
+ *  - 可选：`whenToUse`；
+ *  - 调用策略**只接受** `disable-model-invocation` / `user-invocable`
+ *    （`modelInvocable` / `userInvocable` 会被判为 legacy 键并拒绝）。
+ */
+export function buildSkillFile(def) {
+    const lines = ['---', `name: ${yamlScalar(def.name)}`, `description: ${yamlScalar(def.description)}`];
+    if (def.whenToUse !== undefined && def.whenToUse !== '')
+        lines.push(`whenToUse: ${yamlScalar(def.whenToUse)}`);
+    const invocation = def.invocation;
+    if (invocation !== undefined && invocation.modelInvocable === false)
+        lines.push('disable-model-invocation: true');
+    if (invocation !== undefined && invocation.userInvocable === false)
+        lines.push('user-invocable: false');
+    // 正文原样保留（服务返回的 content 已是 frontmatter 之后的正文；不 trim，避免丢用户排版）
+    return `${lines.join('\n')}\n---\n\n${def.content}`;
+}
 export class SkillsAdapter extends FileCollectionAdapter {
     id = 'skills';
     // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
@@ -12,5 +155,81 @@ export class SkillsAdapter extends FileCollectionAdapter {
     defaultIncluded = sectionMeta('skills').defaultIncluded;
     portability = sectionMeta('skills').portability;
     baseDir = 'skills';
+    /** 本趟由技能服务贡献的技能定义（相对路径 → 定义）。每次 collect 前重建，避免跨趟串味。 */
+    serviceSkills = new Map();
+    /**
+     * 枚举 = 目录扫描 ∪ 技能服务清单。
+     *
+     * 服务不可用（旧宿主 / 无 skills 服务）时**完全退回**目录扫描：一个告警都不多加，
+     * 行为与改造前逐项一致（file-collection.test.ts 钉住「无服务时不产生新告警」）。
+     */
+    async listRelPaths(ctx) {
+        const listing = await super.listRelPaths(ctx);
+        this.serviceSkills = new Map();
+        if (ctx.skills === undefined)
+            return listing;
+        let summaries;
+        try {
+            summaries = await ctx.skills.list();
+        }
+        catch (err) {
+            ctx.log.warn(`技能服务列举失败（该路技能未进备份）: ${err instanceof Error ? err.message : String(err)}`);
+            return listing;
+        }
+        const extra = [];
+        // 目录清单里的是「含 baseDir 的路径」（`skills/<name>/SKILL.md`），服务侧算的是分区内相对路径，
+        // 必须先归一到同一口径再比，否则同路径判不出重合 → 磁盘原文会被服务重建文本挤掉。
+        const onDisk = new Set(listing.paths.map((p) => this.relPathOf(p)));
+        for (const summary of summaries) {
+            // 名字要能当路径用：DSH 的 SKILL_NAME 是 [a-z0-9-]，这里再做一道通用安全校验（拒 `..`/绝对路径）
+            if (typeof summary.name !== 'string' || !isPathSafe(summary.name) || summary.name.includes('/'))
+                continue;
+            const rel = skillServiceRel(summary.name);
+            if (onDisk.has(rel))
+                continue; // 文件系统优先
+            let definition;
+            try {
+                definition = await ctx.skills.get(summary.name);
+            }
+            catch (err) {
+                ctx.log.warn(`技能 ${summary.name} 读取失败（未进备份）: ${err instanceof Error ? err.message : String(err)}`);
+                continue;
+            }
+            if (definition === undefined || typeof definition.content !== 'string')
+                continue;
+            this.serviceSkills.set(rel, definition);
+            // ui-F5：listing.paths 是「含 baseDir」的路径（与磁盘清单同口径），服务侧算出来的是
+            // **分区内相对路径** —— 必须补回 baseDir 前缀再入列。否则技能名恰好等于 baseDir（`skills`，
+            // 合法技能名）时，虚拟路径 skills/SKILL.md 会在 collect() 里被 relPathOf() 二次剥前缀成
+            // SKILL.md：单元 id 变了、readMember 查不到服务定义 → 回落磁盘读 → ENOENT → 整个 skills
+            // 分区预览/导出失败（导出侧被 exporter 整块剔除）。
+            extra.push(this.listRelPathOf(rel));
+        }
+        if (extra.length === 0)
+            return listing;
+        return { ...listing, paths: [...listing.paths, ...extra] };
+    }
+    /** 分区内相对路径 → 枚举清单口径（含 baseDir；本分区 baseDir 恒为 `skills`，没有根分区形态）。 */
+    listRelPathOf(rel) {
+        return normalizePath(`${this.baseDir}/${rel}`);
+    }
+    /**
+     * 读成员：先看本趟的服务清单（虚拟 `<name>/SKILL.md`），命中则用重建文本；
+     * 否则走基类的文件读（含 statSize 快路径）。
+     *
+     * 两条路都必须给出**同一个体积口径**（UTF-8 字节数），否则字节闸门在预览与导出之间分叉。
+     */
+    async readMember(ctx, rel, mode, statTimes) {
+        const definition = this.serviceSkills.get(this.relPathOf(rel));
+        if (definition === undefined)
+            return super.readMember(ctx, rel, mode, statTimes);
+        const text = buildSkillFile(definition);
+        const data = new TextEncoder().encode(text);
+        if (mode === 'size') {
+            // 预览：不建哈希（与基类的 size 模式同语义），但体积必须精确
+            return { data: new Uint8Array(0), sizeBytes: data.byteLength, contentHash: '' };
+        }
+        return { data, sizeBytes: data.byteLength, contentHash: sha256Hex(data) };
+    }
 }
 //# sourceMappingURL=skills.js.map