ygc-dsh-sync 1.1.0 → 1.2.1

package/lib/api.js

@@ -1,1510 +1,1815 @@
-/**
- * Host 侧的 HTTP API。
- * 路由：/api/local/dsh-sync-backup/*
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import {
-  loadState,
-  saveState,
-  pushHistory,
-  computeMachineId,
-  normSlash,
-  humanBytes,
-  pathKey,
-} from './core.js';
-import {
-  backupWorkspace,
-  listMachines,
-  pickWorkspaces,
-  previewPull,
-  projectKeysFor,
-  pullWorkspace,
-  scanLocalSessions,
-} from './backup.js';
-import { attachMany, attachedIds, findPulledUnattached, findUnattached } from './attach.js';
-import { ensureOwnFolder, joinMachineId, repairAll, scanFolders, splitMachineId } from './patrol.js';
-import {
-  LINEAGE_FILE,
-  LOCAL_SKILLS_ROOT,
-  applyModeChange,
-  applyPull,
-  applyPush,
-  buildHistoryIndex,
-  diffSummary,
-  judgeUpdate,
-  loadLineage,
-  makeStamp,
-  planSync,
-  readMnemonLedger,
-  recordLineage,
-  resolveMode,
-  saveLineage,
-  scanSkills,
-} from './skills.js';
-import {
-  appendMasterChanges,
-  changelogPath,
-  ensureChangelog,
-  readChangelog,
-  readChangelogTimes,
-} from './changelog.js';
-import { runMnemonPrepass } from './mnemon.js';
-import {
-  runOptimizationCycle,
-  readQueue,
-  triage,
-  discoverOptimizations,
-  auditDraft,
-  MNEMON_LEDGER,
-} from './mnemon-optimize.js';
-import { createHostDrafter } from './mnemon-drafter.js';
-import {
-  SHARE_POLICY,
-  installSharedPlugin,
-  libraryRoot as pluginsLibraryRoot,
-  shareSnapshot,
-} from './plugins.js';
-
-export const API_PREFIX = '/api/local/dsh-sync-backup';
-
-/** 三种单机属性的中文名。 */
-export const MODE_LABEL = {
-  sync: '同步',
-  local: '本机独属',
-  master: '母版有·本机不拉取',
-};
-
-const json = (res, code, body) => {
-  const text = JSON.stringify(body);
-  res.writeHead(code, {
-    'content-type': 'application/json; charset=utf-8',
-    'cache-control': 'no-store',
-  });
-  res.end(text);
-};
-
-async function readJson(req) {
-  const chunks = [];
-  for await (const chunk of req) chunks.push(chunk);
-  if (!chunks.length) return {};
-  try {
-    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-  } catch {
-    return {};
-  }
-}
-
-/**
- * @param {{ workspaces: () => Array<{id:string,path:string,title:string}>,
- *           machineId: () => string,
- *           registerWorkspace?: (path:string, title:string) => Promise<{id:string,created:boolean}>,
- *           wsEntity?: (id:string) => ({attachSession:(sid:string)=>Promise<void>, sessionIds:string[]}|undefined),
- *           entities?: () => Array<{id:string,sessionIds?:string[]}> }} deps
- */
-/** 手动触发的那一轮的运行态：路由异步化之后，进度只能从这里读。 */
-const optimizeRun = { running: false, startedAt: null, finishedAt: null, lastReport: null, lastError: null };
-
-export function createApi(deps) {
-  /**
-   * 起草器：宿主的 LLM。没有就返回 null，流水线会跳过起草阶段（只审核已有草稿）。
-   * 每轮现取现造，不缓存 —— 宿主换模型后下一轮就跟着换。
-   */
-  const drafter = () => (typeof deps.drafter === 'function' ? deps.drafter() : null);
-
-  /**
-   * 日志：api.js 是模块层，拿不到 index.js 里的 log。必须由 deps 注入。
-   * 不注入就静默 —— 静默比 ReferenceError 好：后者会让整条路由 500，
-   * 前端只看到「点了没反应」（实测就是这么被投诉的）。
-   */
-  const log = (m) => {
-    try {
-      if (typeof deps.log === 'function') deps.log(m);
-    } catch {
-      /* 日志失败不能影响主流程 */
-    }
-  };
-  const listWorkspaces = () =>
-    typeof deps.workspaces === 'function' ? deps.workspaces() : [];
-
-  /** 取某个工作区实体（能 attachSession 的那个），拿不到就返回 undefined。 */
-  const wsEntity = (id) =>
-    typeof deps.wsEntity === 'function' ? deps.wsEntity(id) : undefined;
-
-  /** 全部工作区实体，用于判断某个 sessionId 是否已有归属。 */
-  const entities = () =>
-    typeof deps.entities === 'function' ? deps.entities() || [] : [];
-
-  /** 本机某工作区路径对应的 projectKey 集合。 */
-  const projectKeysOf = (p) => projectKeysFor(p);
-
-  /**
-   * 判新旧要的三份只读证据。
-   *
-   * lineage      ：母版根目录的 `.skill-lineage.json`，同步插件自己的观测记录——
-   *                每侧内容何时变成现在这样、上次一致时的内容树是哪份。
-   * mnemonLedger：`~/.mnemon/skills/ledger.json`，记忆插件的技能账本，
-   *                里面每条 hash 就是 SKILL.md 的 sha256，reason='evolution'
-   *                就是它改的。只读，不写。
-   * history      ：母版 `_backup/`、本机 `.pre-pull-*`、记忆插件 `versions/`
-   *                里的历史全文，按内容哈希索引出「这份内容何时出现过」。
-   */
-  const judgeEvidence = (masterRoot) => ({
-    lineage: masterRoot ? loadLineage(path.join(masterRoot, LINEAGE_FILE)) : {},
-    mnemonLedger: readMnemonLedger(),
-    history: buildHistoryIndex({
-      masterRoot,
-      localRoot: LOCAL_SKILLS_ROOT,
-      changelogTimes: masterRoot ? readChangelogTimes(masterRoot) : null,
-    }),
-  });
-
-  /**
-   * 记录一次比对观测：两侧各自当前是什么内容、各自何时变成这样。
-   *
-   * 这是「内容修改时间」的唯一来源——不是 mtime（同步/NAS 搬运都会刷），
-   * 而是同步插件真正看到内容变化的那一刻。内容没变则时间保持不动。
-   *
-   * 两侧内容一致时顺手把 baseline 更新成这一份：基线就是「上次两侧一致的
-   * 内容树」，只有一致的时候才有意义。
-   */
-  const observeLineage = (masterRoot, plan, by) => {
-    if (!masterRoot) return 0;
-    const file = path.join(masterRoot, LINEAGE_FILE);
-    let map = loadLineage(file);
-    const now = Date.now();
-    let touched = 0;
-    for (const [name, m] of plan.master) {
-      const l = plan.local.get(name);
-      if (!l) continue; // 只有一侧有，没有可比性
-      const same = m.treeHash === l.treeHash;
-      map = recordLineage(map, {
-        name,
-        ...(same ? { baseline: m.treeHash } : {}),
-        master: m,
-        local: l,
-        by: by || '',
-        at: now,
-      });
-      touched++;
-    }
-    return saveLineage(file, map) ? touched : 0;
-  };
-
-  /** 同步真正落地之后，把两侧一致的内容登记成新基线。 */
-  const stampBaseline = (masterRoot, entries, by) => {
-    if (!masterRoot || !entries.length) return 0;
-    const file = path.join(masterRoot, LINEAGE_FILE);
-    let map = loadLineage(file);
-    for (const e of entries) {
-      if (!e) continue;
-      map = recordLineage(map, {
-        name: e.name,
-        baseline: e.treeHash,
-        master: e,
-        local: e,
-        by: by || '',
-      });
-    }
-    return saveLineage(file, map) ? entries.length : 0;
-  };
-
-  const routes = {
-    /** 全量状态：配置、匹配工作区、备份统计、其他机器。 */
-    'GET /state': async (req, res) => {
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const all = listWorkspaces();
-      const matched = pickWorkspaces(all, state.folders);
-      const localIndex = scanLocalSessions();
-
-      const workspaces = matched.map((ws) => {
-        const machines = listMachines(ws.path);
-        const own = machines.find((m) => m.machineId === machineId);
-        const others = machines.filter((m) => m.machineId !== machineId);
-        return {
-          id: ws.id,
-          path: ws.path,
-          title: ws.title || ws.path,
-          matchedPrefix: ws.matchedPrefix,
-          own: own ? { sessions: own.sessions, bytes: own.bytes, newest: own.newest } : { sessions: 0, bytes: 0, newest: 0 },
-          others: others.map((o) => ({
-            machineId: o.machineId,
-            sessions: o.sessions,
-            bytes: o.bytes,
-            newest: o.newest,
-          })),
-        };
-      });
-
-      json(res, 200, {
-        ok: true,
-        machineId,
-        machineName: state.machineName,
-        machineHash: state.machineHash,
-        machineIdSuggested: computeMachineId(),
-        folders: state.folders,
-        lastBackupAt: state.lastBackupAt,
-        lastPullAt: state.lastPullAt,
-        patrol: state.patrol,
-        skills: { ...state.skills, localRoot: LOCAL_SKILLS_ROOT },
-        // 插件清单共享（1.0.0 从自动更新器迁来）：配置 + 运行态 + 口径声明
-        plugins: {
-          ...state.plugins,
-          // 面板没填时告诉用户实际会落到哪，避免「留空 = 不知道去哪」
-          effectiveRoot: pluginsLibraryRoot({ libraryRoot: state.plugins.libraryRoot }),
-          policy: SHARE_POLICY,
-        },
-        history: state.history.slice(0, 20),
-        workspaceCount: all.length,
-        matchedCount: workspaces.length,
-        workspaces,
-        totals: {
-          ownSessions: workspaces.reduce((n, w) => n + w.own.sessions, 0),
-          ownBytes: workspaces.reduce((n, w) => n + w.own.bytes, 0),
-          otherSessions: workspaces.reduce(
-            (n, w) => n + w.others.reduce((m, o) => m + o.sessions, 0),
-            0,
-          ),
-        },
-      });
-    },
-
-    /** 保存配置：文件夹前缀 / 机器标识。 */
-    'POST /config': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      if (Array.isArray(body.folders)) {
-        const seen = new Set();
-        state.folders = [];
-        for (const raw of body.folders) {
-          if (typeof raw !== 'string') continue;
-          const p = normSlash(raw.trim());
-          if (!p) continue;
-          const k = pathKey(p);
-          if (seen.has(k)) continue;
-          seen.add(k);
-          state.folders.push(p);
-        }
-      }
-      if (typeof body.machineName === 'string') {
-        // 只改名称部分，哈希固定不变
-        state.machineName = body.machineName.replace(/[\\/:*?"<>|\s]+/g, '_').trim();
-        state.machineHash = deps.machineHash ? deps.machineHash() || state.machineHash : state.machineHash;
-        state.machineId = joinMachineId(state.machineName, state.machineHash);
-      }
-      if (typeof body.machineId === 'string' && body.machineId.trim() && body.machineName === undefined) {
-        // 兼容：直接给完整标识时，拆出名称，哈希仍以本地为准
-        const parsed = splitMachineId(body.machineId.trim(), state.machineHash);
-        state.machineName = parsed.name.replace(/[\\/:*?"<>|\s]+/g, '_');
-        state.machineId = joinMachineId(state.machineName, state.machineHash);
-      }
-      saveState(state);
-      json(res, 200, {
-        ok: true,
-        folders: state.folders,
-        machineId: state.machineId,
-        machineName: state.machineName,
-        machineHash: state.machineHash,
-      });
-    },
-
-    /** 立即备份：全部匹配工作区，或指定 id 列表。 */
-    'POST /backup': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const all = listWorkspaces();
-      const matched = pickWorkspaces(all, state.folders);
-      const chosen =
-        Array.isArray(body.workspaceIds) && body.workspaceIds.length
-          ? matched.filter((w) => body.workspaceIds.includes(w.id))
-          : matched;
-
-      const localIndex = scanLocalSessions();
-      const results = [];
-      for (const ws of chosen) {
-        results.push(backupWorkspace({ workspace: ws, machineId, localIndex }));
-      }
-
-      const created = results.reduce((n, r) => n + r.created, 0);
-      const updated = results.reduce((n, r) => n + r.updated, 0);
-      const bytes = results.reduce((n, r) => n + r.bytes, 0);
-
-      const next = loadState();
-      next.lastBackupAt = Date.now();
-      pushHistory(
-        next,
-        'backup',
-        `备份 ${chosen.length} 个工作区：新增 ${created}、更新 ${updated}、${humanBytes(bytes)}`,
-      );
-      saveState(next);
-
-      json(res, 200, {
-        ok: true,
-        results,
-        summary: { workspaces: chosen.length, created, updated, bytes },
-      });
-    },
-
-    /** 一键拉取：多选工作区。 */
-    'POST /pull': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const all = listWorkspaces();
-      const matched = pickWorkspaces(all, state.folders);
-      const chosen =
-        Array.isArray(body.workspaceIds) && body.workspaceIds.length
-          ? matched.filter((w) => body.workspaceIds.includes(w.id))
-          : matched;
-
-      /**
-       * 有备份、但没注册成工作区的目录。
-       *
-       * 这是「拉取后显示在未分组」最常见的原因之一：目录里有别的机器的
-       * 会话备份，可它压根不在 workspaceRegistry 里，/pull 的匹配范围就没有它。
-       * 用户点「一键拉取」本身就是明确意图，这里先注册再拉。
-       */
-      const autoRegister = body.autoRegister !== false;
-      const registered = [];
-      const registerErrors = [];
-      if (autoRegister && typeof deps.registerWorkspace === 'function') {
-        const scan = scanFolders({
-          folders: state.folders,
-          workspaces: all,
-          machineId,
-        });
-        for (const item of scan.discover) {
-          // 只自动处理「确实有别的机器的备份」那些，别把空壳目录也注册进来
-          const hasRemote = listMachines(item.path).some((m) => m.machineId !== machineId);
-          if (!hasRemote) continue;
-          try {
-            const out = await deps.registerWorkspace(item.path, item.title);
-            registered.push({ path: item.path, id: out?.id });
-            all.push({ id: out?.id, path: item.path, title: item.title });
-          } catch (err) {
-            registerErrors.push({ path: item.path, message: String((err && err.message) || err) });
-          }
-        }
-      }
-
-      // 注册完重新匹配一次，把新注册的目录纳入拉取范围
-      const matched2 = pickWorkspaces(all, state.folders);
-      const chosen2 =
-        Array.isArray(body.workspaceIds) && body.workspaceIds.length
-          ? matched2.filter((w) =>
-              body.workspaceIds.includes(w.id) ||
-              registered.some((r) => r.path === w.path),
-            )
-          : matched2;
-
-      const localIndex = scanLocalSessions();
-      const results = [];
-      for (const ws of chosen2) {
-        const r = pullWorkspace({
-          workspace: ws,
-          machineId,
-          localIndex,
-          machines: Array.isArray(body.machines) && body.machines.length ? body.machines : null,
-        });
-
-        // 关键一步：把刚落盘的会话登记进工作区归属账。
-        // 只写文件不登记，DSH 侧栏只会把它显示成「未分组」。
-        const entity = wsEntity(ws.id);
-        if (r.newSessionIds.length) {
-          const att = await attachMany(entity, r.newSessionIds);
-          r.attached = att.attached;
-          r.attachFailed = att.failed;
-        } else {
-          r.attached = [];
-          r.attachFailed = [];
-        }
-        results.push(r);
-      }
-
-      const imported = results.reduce((n, r) => n + r.imported, 0);
-      const updated = results.reduce((n, r) => n + r.updated, 0);
-      const forked = results.reduce((n, r) => n + r.forked, 0);
-      const attached = results.reduce((n, r) => n + (r.attached || []).length, 0);
-      const attachFailed = results.reduce((n, r) => n + (r.attachFailed || []).length, 0);
-
-      const next = loadState();
-      next.lastPullAt = Date.now();
-      pushHistory(
-        next,
-        'pull',
-        `拉取 ${chosen2.length} 个工作区：新增 ${imported}、更新 ${updated}、分叉 ${forked}、登记 ${attached}${
-          attachFailed ? `、登记失败 ${attachFailed}` : ''
-        }${registered.length ? `、自动注册 ${registered.length}` : ''}`,
-      );
-      saveState(next);
-
-      json(res, 200, {
-        ok: true,
-        results,
-        registered,
-        registerErrors,
-        summary: {
-          workspaces: chosen2.length,
-          imported,
-          updated,
-          forked,
-          attached,
-          attachFailed,
-          registered: registered.length,
-        },
-        // 全部登记成功就不需要重开会话索引：会话列表是实时读盘 + 归属表的
-        needsRestart: imported + forked > attached,
-      });
-    },
-
-    /**
-     * 补登记：把「本插件拉进来、但没进归属账」的会话补进 sessionIds。
-     *
-     * 这是历史遗留数据的清理入口——旧版拉取只写文件不登记，
-     * 那些会话至今仍散在「未分组」里。
-     *
-     * 默认只补拉取产物（别的机器备份目录里有它），不会把自动化插件和
-     * 子代理留下的会话一起刷进来。要全量补必须显式传 all:true。
-     */
-    'POST /attach/repair': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const all = listWorkspaces();
-      const matched = pickWorkspaces(all, state.folders);
-      const chosen =
-        Array.isArray(body.workspaceIds) && body.workspaceIds.length
-          ? matched.filter((w) => body.workspaceIds.includes(w.id))
-          : matched;
-
-      const localIndex = scanLocalSessions();
-      const ents = entities();
-      const scopeAll = body.all === true;
-      const results = [];
-
-      for (const ws of chosen) {
-        const entity = wsEntity(ws.id);
-        if (!entity) {
-          results.push({ id: ws.id, title: ws.title || ws.path, attached: [], skipped: '当前环境不支持登记会话归属' });
-          continue;
-        }
-        const missing = scopeAll
-          ? findUnattached({ workspace: ws, entities: ents, localIndex, projectKeysFor })
-          : findPulledUnattached({
-              workspace: ws,
-              machineId,
-              entities: ents,
-              localIndex,
-              projectKeysFor,
-            });
-        const att = await attachMany(entity, missing);
-        results.push({
-          id: ws.id,
-          title: ws.title || ws.path,
-          scope: scopeAll ? 'all' : 'pulled',
-          candidates: missing.length,
-          attached: att.attached,
-          failed: att.failed,
-        });
-      }
-
-      const total = results.reduce((n, r) => n + (r.attached || []).length, 0);
-      const failed = results.reduce((n, r) => n + ((r.failed && r.failed.length) || 0), 0);
-
-      const next = loadState();
-      if (total || failed) {
-        pushHistory(next, 'attach', `补登记归属：成功 ${total}、失败 ${failed}`);
-        saveState(next);
-      }
-
-      json(res, 200, {
-        ok: true,
-        scope: scopeAll ? 'all' : 'pulled',
-        results,
-        summary: { attached: total, failed },
-      });
-    },
-
-    /** 巡检：发现待注册工作区 + 缺本机特征文件夹的。只扫描，不改任何东西。 */
-    'POST /patrol/scan': async (req, res) => {
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const result = scanFolders({
-        folders: state.folders,
-        workspaces: listWorkspaces(),
-        machineId,
-      });
-
-      const next = loadState();
-      next.patrol = { ...next.patrol, lastRunAt: Date.now(), lastResult: {
-        discover: result.discover.length,
-        repair: result.repair.length,
-      } };
-      saveState(next);
-
-      json(res, 200, { ok: true, ...result, machineId });
-    },
-
-    /** 注册：把选中的目录注册为工作区（用户确认后才调用）。 */
-    'POST /patrol/register': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const paths = Array.isArray(body.paths) ? body.paths.filter((p) => typeof p === 'string') : [];
-      if (!paths.length) {
-        json(res, 400, { ok: false, error: '未选择任何目录' });
-        return;
-      }
-      if (typeof deps.registerWorkspace !== 'function') {
-        json(res, 503, { ok: false, error: '当前环境不支持注册工作区' });
-        return;
-      }
-
-      const registered = [];
-      const errors = [];
-      const existing = new Set(listWorkspaces().map((w) => pathKey(w.path)));
-
-      for (const p of paths) {
-        try {
-          if (existing.has(pathKey(p))) {
-            registered.push({ path: p, skipped: '已注册' });
-            continue;
-          }
-          const out = await deps.registerWorkspace(p, path.basename(p));
-          // 注册完顺手补齐本机特征文件夹
-          const target = ensureOwnFolder(p, machineId);
-          registered.push({ path: p, id: out?.id, created: !!out?.created, own: target });
-        } catch (err) {
-          errors.push({ path: p, message: String((err && err.message) || err) });
-        }
-      }
-
-      const next = loadState();
-      pushHistory(next, 'register', `注册 ${registered.length} 个工作区`);
-      saveState(next);
-
-      json(res, 200, { ok: true, registered, errors });
-    },
-
-    /** 补全：给缺本机特征文件夹的工作区补上。 */
-    'POST /patrol/repair': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const all = listWorkspaces();
-      const targets = Array.isArray(body.paths) && body.paths.length
-        ? all.filter((w) => body.paths.some((p) => pathKey(p) === pathKey(w.path)))
-        : pickWorkspaces(all, state.folders);
-
-      const out = repairAll(targets, machineId);
-      const next = loadState();
-      pushHistory(next, 'repair', `补全 ${out.created.length} 个特征文件夹`);
-      saveState(next);
-
-      json(res, 200, { ok: true, ...out });
-    },
-
-    /** 定时巡检设置。 */
-    'POST /patrol/config': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const patrol = { ...state.patrol };
-
-      if (typeof body.enabled === 'boolean') patrol.enabled = body.enabled;
-      if (body.intervalMinutes !== undefined) {
-        const n = Number(body.intervalMinutes);
-        if (!Number.isFinite(n) || n < 1 || n > 1440) {
-          json(res, 400, { ok: false, error: '间隔应为 1–1440 之间的整数（分钟）' });
-          return;
-        }
-        patrol.intervalMinutes = Math.floor(n);
-      }
-      state.patrol = patrol;
-      saveState(state);
-      json(res, 200, { ok: true, patrol: state.patrol });
-    },
-
-    /* ---------------- 技能同步 ---------------- */
-
-    /**
-     * 比对 + 自动同步。
-     *
-     * 语义（用户 2026-11-01 定）：同步属性的技能，比对时就把能定下来的更新做掉——
-     * 母版更新就拉下来，本机更新就推上去。只有**判不出谁新**的才留给用户裁决。
-     *
-     * body.auto === false 时退化为纯比对（只报告，不动任何文件）。
-     */
-    'POST /skills/scan': async (req, res) => {
-      const body = await readJson(req).catch(() => ({}));
-      const auto = body && body.auto === false ? false : true;
-      const dryRunFlag = body?.dryRun === true;
-      const state = loadState();
-      const master = state.skills.masterRoot;
-      if (!master) {
-        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
-        return;
-      }
-      if (!fs.existsSync(master)) {
-        json(res, 400, { ok: false, error: `母版文件夹不存在或不可访问：${master}` });
-        return;
-      }
-
-      // ── 阶段 0：记忆插件技能优化闭环（发现 → 起草 → 审核 → 落地 → 结案）
-      // 0.8.0 起这一步会写账本（结案）并调模型起草；dryRun 时只报告。
-      const optimize = auto
-        ? await runOptimizationCycle({
-            localRoot: LOCAL_SKILLS_ROOT,
-            masterRoot: master,
-            stageDir: process.env.DSH_SYNC_STAGE_DIR || 'C:/DSH-Work/mnemon-drafts/stage',
-            minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
-            enabled: state.skills.mnemonOptimize !== false,
-            // 比对/巡检必须自己把「生成草案」这一步走完。
-            //
-            // 历史：这里曾经写死 `draft: null`，理由是「比对是同步语义，起草要调模型会卡住」。
-            // 结果是任何走比对路径的巡检（面板点「比对」、开机首拉、每 120 分钟的定时轮）
-            // 都只发现建议、从不起草，建议永远停在 pending；只有单独点「立即优化」
-            // 或走定时器那条后台链路才会起草。用户要的是「巡检发现待处理就自己处理完」，
-            // 所以把起草器接回来，由 body 控制：
-            //   body.draft   === false → 只比对（显式要求纯比对时才这样）
-            //   body.dryRun  === true  → 不调模型（预演）
-            // 其余情况一律带起草器，让「发现 → 起草 → 审核 → 落地 → 结案」在一条路径里跑完。
-            draft: dryRunFlag || body?.draft === false ? null : drafter(),
-            maxDrafts: Number(state.skills.mnemonMaxDrafts) || 6,
-            onEvent: (kind, payload) => log(`优化闭环 ${kind}: ${JSON.stringify(payload)}`),
-          })
-        : { enabled: false, skipped: 'auto=false', discovered: { suggestions: 0, drafts: 0 }, todo: [], dropped: [], enqueued: [], audited: [], accepted: [], errors: [] };
-
-      // 记忆插件草稿预处理：auto 时先落地再比对，比对看到的就是落地后的内容
-      const prepass = auto
-        ? runMnemonPrepass({
-            masterRoot: master,
-            localRoot: LOCAL_SKILLS_ROOT,
-            modes: state.skills.modes || {},
-            machineId: state.machineId,
-            machineName: state.machineName,
-            enabled: state.skills.mnemonAuto !== false,
-          })
-        : { enabled: false, drafts: 0, apply: [], skipped: [], applied: [], pushed: [], errors: [] };
-
-      const plan = planSync({
-        masterRoot: master,
-        localRoot: LOCAL_SKILLS_ROOT,
-        modes: state.skills.modes || {},
-        ...judgeEvidence(master),
-      });
-
-      // 比对本身就是一次观测：记下两侧各自现在是什么内容、何时变成这样
-      const next = loadState();
-      const observed = observeLineage(master, plan, next.machineId);
-
-      const stamp = makeStamp();
-      let pulled = { pulled: [], errors: [] };
-      let pushed = { pushed: [], errors: [] };
-
-      if (auto && (plan.pull.length || plan.autoPush.length)) {
-        // 母版更新 → 拉到本机
-        if (plan.pull.length) {
-          pulled = applyPull({ items: plan.pull, localRoot: LOCAL_SKILLS_ROOT, stamp });
-        }
-        // 本机更新（同步属性）→ 推回母版，旧版先存档
-        if (plan.autoPush.length) {
-          const backRoot = path.join(master, '_backup');
-          pushed = applyPush({ items: plan.autoPush, masterRoot: master, backRoot, stamp });
-          const auditItems = pushed.pushed.map((p) => ({
-            skill: p.name,
-            operation: p.operation,
-            detail: `${p.operation === '覆盖' ? `旧版备份于 _backup/${p.name}.${stamp}` : '母版此前无此技能'}（自动：内容更新）`,
-          }));
-          if (auditItems.length) {
-            try {
-              appendMasterChanges(auditItems, {
-                masterRoot: master,
-                machineId: next.machineId,
-                machineName: next.machineName,
-                trigger: '自动同步',
-              });
-            } catch {
-              /* 记录写不进去不影响同步本身 */
-            }
-          }
-        }
-        // 同步过的内容现在两侧一致，登记成新基线
-        const aligned = [
-          ...plan.pull.map((x) => x.master),
-          ...plan.autoPush.map((x) => x.local),
-          ...plan.same.map((x) => x.master),
-        ].filter(Boolean);
-        if (aligned.length) {
-          let map = loadLineage(path.join(master, LINEAGE_FILE));
-          for (const e of aligned) {
-            map = recordLineage(map, { name: e.name, baseline: e.treeHash, master: e, local: e, by: next.machineId });
-          }
-          saveLineage(path.join(master, LINEAGE_FILE), map);
-        }
-      }
-
-      next.skills.lastRunAt = Date.now();
-      next.skills.lastResult = {
-        pull: plan.pull.length,
-        autoPush: plan.autoPush.length,
-        push: plan.push.length,
-        same: plan.same.length,
-        localOnly: plan.localOnly.length,
-        pulled: pulled.pulled.length,
-        pushed: pushed.pushed.length,
-        observed,
-        auto,
-        scannedAt: plan.scannedAt,
-        mnemon: {
-          drafts: prepass.drafts,
-          applied: prepass.applied.length,
-          pushed: prepass.pushed.length,
-          skipped: prepass.skipped.length,
-        },
-      };
-      if (auto && (pulled.pulled.length || pushed.pushed.length || prepass.applied.length)) {
-        pushHistory(
-          next,
-          'skills',
-          `技能自动同步：拉取 ${pulled.pulled.length}、推送 ${pushed.pushed.length}、待裁决 ${plan.push.length}${
-            prepass.applied.length ? `、记忆插件草稿落地 ${prepass.applied.length}` : ''
-          }`,
-        );
-      }
-      saveState(next);
-
-      const brief = (x) => ({
-        name: x.name,
-        action: x.action,
-        reason: x.reason || (x.action === 'new' ? '母版新增' : ''),
-        basis: x.basis || null,
-      });
-
-      const pulledNames = new Set(pulled.pulled.map((p) => p.name));
-      const pushedNames = new Set(pushed.pushed.map((p) => p.name));
-
-      json(res, 200, {
-        ok: true,
-        masterRoot: master,
-        localRoot: LOCAL_SKILLS_ROOT,
-        auto,
-        stamp,
-        // 母版更新：自动拉取
-        pull: plan.pull.map((x) => ({ ...brief(x), version: x.master.version, done: pulledNames.has(x.name) })),
-        // 本机更新（同步属性）：自动推送
-        autoPush: plan.autoPush.map((x) => ({
-          ...brief(x),
-          masterVersion: x.master.version,
-          localVersion: x.local.version,
-          done: pushedNames.has(x.name),
-        })),
-        // 判不出来的：只报告，等用户裁决（附差异摘要，方便一眼决定）
-        push: plan.push.map((x) => ({
-          ...brief(x),
-          masterVersion: x.master.version,
-          localVersion: x.local.version,
-          diff: x.diff || null,
-        })),
-        same: plan.same.map((x) => x.name),
-        localOnly: plan.localOnly.map((x) => x.name),
-        // 优化闭环：发现了什么、判断结果、入队、审核、通过
-        optimize,
-        // 记忆插件草稿：这一轮落地了哪些、跳过了哪些（跳过都带原因）
-        mnemon: {
-          enabled: prepass.enabled,
-          drafts: prepass.drafts,
-          apply: prepass.apply,
-          applied: prepass.applied.map((a) => ({
-            name: a.name,
-            action: a.action,
-            draftId: a.draftId,
-            targetRoot: a.targetRoot,
-            backup: a.backup,
-          })),
-          pushed: prepass.pushed.map((p) => ({ name: p.name, operation: p.operation })),
-          skipped: prepass.skipped,
-        },
-        errors: [...pulled.errors, ...pushed.errors, ...prepass.errors],
-        observed,
-      });
-    },
-
-    /**
-     * 优化闭环的只读快照：队列里在等什么、账本里还有多少建议没做。
-     *
-     * 不改任何文件。面板用它显示「现在积压了多少」。
-     */
-    /**
-     * 手动跑一轮完整流程（发现 → 起草 → 审核 → 落地 → 结案）。
-     *
-     * body: { dryRun?: boolean, maxDrafts?: number, wait?: boolean }
-     *
-     * **默认立刻返回 202，起草在后台跑**。为什么：一轮 6 条草稿要两分钟以上，
-     * 串在 HTTP 响应里会让前端「点了没反应」（实测就是这么被投诉的），
-     * 浏览器/代理还可能先超时。要同步结果就传 `wait:true`（只建议 dryRun 时用）。
-     * 进度用 `POST /skills/optimize/state` 的 running/nextRun 两个字段轮询。
-     */
-    'POST /skills/optimize/run': async (req, res) => {
-      const body = (await readJson(req).catch(() => ({}))) || {};
-      const state = loadState();
-      // 母版不是必需品：没有母版照样能落地并结案（结案不依赖母版是既有约定），
-      // 只是跳过「推母版」这一步。所以这里不拦，只在报告里说明。
-      const master = state.skills.masterRoot || undefined;
-      const enabled = state.skills.mnemonOptimize !== false;
-      const maxDrafts = Number(body.maxDrafts) || Number(state.skills.mnemonMaxDrafts) || 6;
-      const dryRun = body.dryRun === true;
-
-      const runOnce = () =>
-        runOptimizationCycle({
-          localRoot: LOCAL_SKILLS_ROOT,
-          masterRoot: master,
-          stageDir: process.env.DSH_SYNC_STAGE_DIR || 'C:/DSH-Work/mnemon-drafts/stage',
-          minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
-          maxDrafts,
-          dryRun,
-          // dryRun 不调模型：那样「预演」也要两分钟，且没有意义（没落地可预演）
-          draft: dryRun ? null : drafter(),
-          enabled,
-          onEvent: (kind, payload) => log(`优化闭环 ${kind}: ${JSON.stringify(payload)}`),
-        });
-
-      // 同步模式：只给 dryRun / 明确要 wait 的调用方
-      if (body.wait === true || dryRun) {
-        try {
-          const report = await runOnce();
-          json(res, 200, { ok: true, report });
-        } catch (err) {
-          json(res, 500, { ok: false, error: String((err && err.message) || err) });
-        }
-        return;
-      }
-
-      // 异步模式（默认）：立刻回 202，后台跑
-      if (optimizeRun.running) {
-        json(res, 202, {
-          ok: true,
-          started: false,
-          running: true,
-          startedAt: optimizeRun.startedAt,
-          note: '上一轮还在跑，本次不重复启动',
-        });
-        return;
-      }
-      optimizeRun.running = true;
-      optimizeRun.startedAt = new Date().toISOString();
-      optimizeRun.lastReport = null;
-      optimizeRun.lastError = null;
-      runOnce()
-        .then((report) => {
-          optimizeRun.lastReport = {
-            at: new Date().toISOString(),
-            remaining: report.remaining,
-            closed: report.closed,
-            landed: (report.pipeline && report.pipeline.stage && report.pipeline.stage.landed) || [],
-            drafted: (report.pipeline && report.pipeline.stage && report.pipeline.stage.drafted) || [],
-            failed: (report.pipeline && report.pipeline.stage && report.pipeline.stage.failed) || [],
-            errors: report.errors,
-          };
-          log(
-            `优化闭环（手动）：起草 ${optimizeRun.lastReport.drafted.length}、` +
-              `落地 ${optimizeRun.lastReport.landed.length}、失败 ${optimizeRun.lastReport.failed.length}、` +
-              `剩余 ${report.remaining}`,
-          );
-        })
-        .catch((err) => {
-          optimizeRun.lastError = String((err && err.message) || err);
-          log(`优化闭环（手动）失败：${optimizeRun.lastError}`);
-        })
-        .finally(() => {
-          optimizeRun.running = false;
-          optimizeRun.finishedAt = new Date().toISOString();
-        });
-      json(res, 202, {
-        ok: true,
-        started: true,
-        running: true,
-        startedAt: optimizeRun.startedAt,
-        maxDrafts,
-        note: '起草已转后台，用 POST /skills/optimize/state 轮询进度',
-      });
-    },
-
-    'POST /skills/optimize/state': async (req, res) => {
-      const state = loadState();
-      const queue = readQueue();
-      const found = discoverOptimizations({ localRoot: LOCAL_SKILLS_ROOT });
-      const { todo, dropped } = triage({
-        suggestions: found.suggestions,
-        minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
-        seen: queue.seen,
-      });
-      // 账本视角的三段计数：没有草稿的 / 有 ready 草稿的 / 已经在磁盘上的
-      let ledgerView = { pending: 0, withDraft: 0, readyDrafts: 0, adopted: 0, generation: null };
-      try {
-        const raw = JSON.parse(fs.readFileSync(MNEMON_LEDGER, 'utf8'));
-        const sug = Array.isArray(raw.suggestions) ? raw.suggestions : [];
-        const drf = Array.isArray(raw.drafts) ? raw.drafts : [];
-        const readyBySuggestion = new Set(drf.filter((d) => d && d.status === 'ready' && d.suggestionId).map((d) => d.suggestionId));
-        const pending = sug.filter((s) => s && s.status === 'pending');
-        ledgerView = {
-          pending: pending.length,
-          withDraft: pending.filter((s) => readyBySuggestion.has(s.id)).length,
-          readyDrafts: drf.filter((d) => d && d.status === 'ready').length,
-          adopted: sug.filter((s) => s && s.status === 'adopted').length,
-          generation: typeof raw.generation === 'number' ? raw.generation : null,
-        };
-      } catch {
-        /* 账本读不到就返回零值，面板不报错 */
-      }
-      json(res, 200, {
-        ok: true,
-        ledgerView,
-        // 手动触发那一轮的运行态：面板靠这两个字段显示「在跑 / 上次结果」
-        running: optimizeRun.running,
-        startedAt: optimizeRun.startedAt,
-        finishedAt: optimizeRun.finishedAt,
-        lastReport: optimizeRun.lastReport,
-        lastError: optimizeRun.lastError,
-        enabled: state.skills.mnemonOptimize !== false,
-        minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
-        queue: {
-          file: '~/.mnemon/skills/external-drafts.json',
-          generation: queue.generation,
-          waiting: queue.items.filter((x) => x.status === 'waiting-draft').length,
-          done: queue.items.filter((x) => x.status === 'done').length,
-          seen: queue.seen.length,
-          items: queue.items.slice(-40),
-        },
-        ledger: { suggestions: found.suggestions.length, readyDrafts: found.drafts.length },
-        todo: todo.map((x) => ({ skillName: x.skillName, action: x.action, priority: x.priority, reason: x.reason })),
-        dropped,
-      });
-    },
-
-    /**
-     * 只审核不落地：把暂存区里的草稿过一遍机械审核，看哪些能通过。
-     * 用来在真正落地前先看一眼。
-     */
-    'POST /skills/optimize/audit': async (req, res) => {
-      const body = await readJson(req).catch(() => ({}));
-      const stageDir = body.stageDir || process.env.DSH_SYNC_STAGE_DIR || 'C:/DSH-Work/mnemon-drafts/stage';
-      const state = loadState();
-      const queue = readQueue();
-      const found = discoverOptimizations({ localRoot: LOCAL_SKILLS_ROOT });
-      const { todo } = triage({
-        suggestions: found.suggestions,
-        minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
-        seen: queue.seen,
-      });
-
-      const rows = [];
-      for (const item of todo) {
-        const file = `${stageDir}/${item.skillName}/SKILL.md`;
-        if (!fs.existsSync(file)) {
-          rows.push({ skillName: item.skillName, action: item.action, staged: false, ok: null, problems: [] });
-          continue;
-        }
-        const text = fs.readFileSync(file, 'utf8');
-        const audit = auditDraft({ text, name: item.skillName, isUpdate: item.action === 'update', localRoot: LOCAL_SKILLS_ROOT });
-        rows.push({ skillName: item.skillName, action: item.action, staged: true, ok: audit.ok, problems: audit.problems, info: audit.info });
-      }
-      json(res, 200, { ok: true, stageDir, rows });
-    },
-
-    /** 执行拉取（母版 → 本地）+ 移除母版已删的。 */
-    'POST /skills/pull': async (req, res) => {
-      const state = loadState();
-      const master = state.skills.masterRoot;
-      if (!master) {
-        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
-        return;
-      }
-      if (!fs.existsSync(master)) {
-        json(res, 400, { ok: false, error: `母版文件夹不存在或不可访问：${master}` });
-        return;
-      }
-
-      const plan = planSync({
-        masterRoot: master,
-        localRoot: LOCAL_SKILLS_ROOT,
-        modes: state.skills.modes || {},
-        ...judgeEvidence(master),
-      });
-      const stamp = makeStamp();
-
-      const pulled = applyPull({ items: plan.pull, localRoot: LOCAL_SKILLS_ROOT, stamp });
-
-      // 拉取落地后，被拉的和本来就一致的两侧都对齐了，一起登记成基线
-      const next = loadState();
-      const stamped = stampBaseline(
-        master,
-        [...plan.pull.map((x) => x.master), ...plan.same.map((x) => x.master)].filter(Boolean),
-        next.machineId,
-      );
-
-      next.skills.lastRunAt = Date.now();
-      next.skills.lastResult = {
-        pulled: pulled.pulled.length,
-        pendingPush: plan.push.length,
-        errors: pulled.errors.length,
-        lineage: stamped,
-      };
-      pushHistory(
-        next,
-        'skills',
-        `技能拉取：更新 ${pulled.pulled.length}、待推 ${plan.push.length}`,
-      );
-      saveState(next);
-
-      json(res, 200, {
-        ok: true,
-        pulled: pulled.pulled,
-        errors: pulled.errors,
-        pendingPush: plan.push.map((x) => ({ name: x.name, reason: x.reason, basis: x.basis || null })),
-        lineage: stamped,
-        stamp,
-      });
-    },
-
-    /** 把本地技能推回母版（用户确认后才调用）。支持覆盖，也支持新增本地独有技能。 */
-    'POST /skills/push': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const master = state.skills.masterRoot;
-      if (!master) {
-        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
-        return;
-      }
-      const names = Array.isArray(body.names) ? body.names.filter((n) => typeof n === 'string') : [];
-      if (!names.length) {
-        json(res, 400, { ok: false, error: '未选择任何技能' });
-        return;
-      }
-
-      const plan = planSync({
-        masterRoot: master,
-        localRoot: LOCAL_SKILLS_ROOT,
-        modes: state.skills.modes || {},
-        ...judgeEvidence(master),
-      });
-      const stamp = makeStamp();
-
-      // 覆盖项：本机更新的（同步属性，在 autoPush 里）+ 待裁决里被指名的
-      // 新增项：localOnly（用户显式指名才推）
-      // 注意 autoPush 也要算进来——否则「本机更新」这条在面板上点「推送」
-      // 会报「没有可推送的变更」。
-      const overwrites = [...plan.autoPush, ...plan.push].filter((x) => names.includes(x.name));
-      const creates = plan.localOnly
-        .filter((x) => names.includes(x.name))
-        .map((x) => ({ name: x.name, action: 'create', local: x.local, master: null }));
-      const items = [...overwrites, ...creates];
-
-      if (!items.length) {
-        json(res, 400, { ok: false, error: '选中的技能当前没有可推送的变更' });
-        return;
-      }
-
-      const backRoot = path.join(master, '_backup');
-      const out = applyPush({ items, masterRoot: master, backRoot, stamp });
-
-      // 每一次实际写入都留记录
-      const audit = appendMasterChanges(
-        out.pushed.map((p) => ({
-          skill: p.name,
-          operation: p.operation,
-          detail: p.operation === '覆盖' ? `旧版备份于 _backup/${p.name}.${stamp}` : '母版此前无此技能',
-        })),
-        {
-          masterRoot: master,
-          machineId: state.machineId,
-          machineName: state.machineName,
-          trigger: '用户授权',
-        },
-      );
-
-      const next = loadState();
-      // 推送落地后母版就是本机这一份，登记成新基线
-      const stamped = stampBaseline(
-        master,
-        out.pushed.map((p) => items.find((i) => i.name === p.name)).filter(Boolean).map((i) => i.local).filter(Boolean),
-        next.machineId,
-      );
-      pushHistory(
-        next,
-        'skills',
-        `技能推送：覆盖 ${out.pushed.filter((p) => p.operation === '覆盖').length}、新增 ${
-          out.pushed.filter((p) => p.operation === '新增').length
-        }`,
-      );
-      saveState(next);
-
-      json(res, 200, {
-        ok: true,
-        pushed: out.pushed,
-        errors: out.errors,
-        backupRoot: backRoot,
-        stamp,
-        lineage: stamped,
-        changelog: {
-          path: audit.written[0]?.path || changelogPath(master),
-          written: audit.written.length,
-          failed: audit.failed,
-        },
-      });
-    },
-
-    /** 读取母版修改记录。 */
-    'POST /skills/changelog': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const master = state.skills.masterRoot;
-      if (!master) {
-        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
-        return;
-      }
-      const limit = Number(body.limit) > 0 ? Math.min(Math.floor(Number(body.limit)), 200) : 30;
-      const log = readChangelog(master, limit);
-      json(res, 200, { ok: true, ...log });
-    },
-
-    /** 技能列表：合并母版与本机，带单机属性。 */
-    'POST /skills/list': async (req, res) => {
-      const state = loadState();
-      const master = state.skills.masterRoot;
-      if (!master) {
-        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
-        return;
-      }
-      if (!fs.existsSync(master)) {
-        json(res, 400, { ok: false, error: `母版文件夹不存在或不可访问：${master}` });
-        return;
-      }
-
-      const modes = state.skills.modes || {};
-      const m = scanSkills(master);
-      const l = scanSkills(LOCAL_SKILLS_ROOT);
-      const names = new Set([...m.keys(), ...l.keys()]);
-      const { lineage, mnemonLedger, history } = judgeEvidence(master);
-
-      const items = [...names].sort().map((name) => {
-        const mm = m.get(name);
-        const ll = l.get(name);
-        const mode = resolveMode(name, modes, m, l);
-        let status;
-        if (mm && !ll) status = mode === 'master' ? 'master-only' : 'missing-local';
-        else if (!mm && ll) status = 'local-only';
-        else status = mm.treeHash === ll.treeHash ? 'same' : 'diff';
-
-        // 内容不同时顺便给出「谁更新」的结论，前端不用再自己算
-        let verdict = null;
-        let basis = null;
-        let hint = '';
-        let diff = null;
-        if (status === 'diff') {
-          const j = judgeUpdate({ name, master: mm, local: ll, record: lineage[name], ledger: mnemonLedger, history });
-          verdict = j.verdict;
-          basis = j.basis;
-          hint = j.detail;
-          diff = diffSummary(mm.text, ll.text);
-        }
-
-        return {
-          name,
-          mode,
-          explicit: Object.prototype.hasOwnProperty.call(modes, name),
-          status,
-          verdict,
-          basis,
-          hint,
-          diff,
-          masterVersion: (mm && mm.version) || '',
-          localVersion: (ll && ll.version) || '',
-          inMaster: !!mm,
-          inLocal: !!ll,
-        };
-      });
-
-      json(res, 200, { ok: true, masterRoot: master, localRoot: LOCAL_SKILLS_ROOT, items });
-    },
-
-    /** 切换单机属性，并执行对应的实质动作（删母版 / 删本机 / 推送）。 */
-    'POST /skills/mode': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const master = state.skills.masterRoot;
-      if (!master) {
-        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
-        return;
-      }
-      const mode = body.mode;
-      if (mode !== 'sync' && mode !== 'local' && mode !== 'master') {
-        json(res, 400, { ok: false, error: '属性只能是 sync / local / master' });
-        return;
-      }
-      const names = Array.isArray(body.names) ? body.names.filter((n) => typeof n === 'string' && n) : [];
-      if (!names.length) {
-        json(res, 400, { ok: false, error: '未选择任何技能' });
-        return;
-      }
-
-      const stamp = makeStamp();
-      const backRoot = path.join(master, '_backup');
-      const modes = state.skills.modes || {};
-      const m0 = scanSkills(master);
-      const l0 = scanSkills(LOCAL_SKILLS_ROOT);
-
-      const results = [];
-      const applied = [];
-
-      for (const name of names) {
-        const from = resolveMode(name, modes, m0, l0);
-        const out = applyModeChange({
-          name,
-          from,
-          to: mode,
-          masterRoot: master,
-          localRoot: LOCAL_SKILLS_ROOT,
-          backRoot,
-          stamp,
-        });
-        results.push(out);
-        if (out.ok) applied.push({ name, mode });
-      }
-
-      // 只有成功的才落属性
-      const next = loadState();
-      for (const a of applied) next.skills.modes[a.name] = a.mode;
-      const auditItems = results.flatMap((r) => (r.ok && r.audit ? r.audit : []));
-      if (applied.length) {
-        pushHistory(next, 'skills', `技能属性：${applied.length} 个改为「${MODE_LABEL[mode]}」`);
-      }
-      saveState(next);
-
-      // 对母版的实际改动写审计
-      let audit = { written: 0, failed: [] };
-      if (auditItems.length) {
-        const w = appendMasterChanges(auditItems, {
-          masterRoot: master,
-          machineId: next.machineId,
-          machineName: next.machineName,
-          trigger: '用户授权',
-        });
-        audit = { written: w.written.length, failed: w.failed, path: w.written[0] && w.written[0].path };
-      }
-
-      json(res, 200, {
-        ok: true,
-        mode,
-        results,
-        applied: applied.length,
-        failed: results.filter((r) => !r.ok).length,
-        audit,
-      });
-    },
-
-    /** 技能同步配置。 */
-    'POST /skills/config': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const skills = { ...state.skills };
-
-      if (typeof body.masterRoot === 'string') {
-        const p = body.masterRoot.trim();
-        skills.masterRoot = p ? normSlash(p) : '';
-        // 设置路径时就把记录文件准备好，用户能立刻看到
-        if (skills.masterRoot && fs.existsSync(skills.masterRoot)) {
-          try {
-            ensureChangelog(skills.masterRoot);
-          } catch {
-            /* 母版只读时建不了，不影响后续 */
-          }
-        }
-      }
-      if (typeof body.enabled === 'boolean') skills.enabled = body.enabled;
-      // 记忆插件技能优化自动落地：默认开，显式传 false 才关
-      if (typeof body.mnemonAuto === 'boolean') skills.mnemonAuto = body.mnemonAuto;
-      // 优化闭环（发现 → 判断 → 入队 → 审核 → 通过）：默认开
-      if (typeof body.mnemonOptimize === 'boolean') skills.mnemonOptimize = body.mnemonOptimize;
-      if (body.mnemonMinConfidence !== undefined) {
-        const n = Number(body.mnemonMinConfidence);
-        if (!Number.isFinite(n) || n < 0 || n > 1) {
-          json(res, 400, { ok: false, error: '置信度门槛应在 0 到 1 之间' });
-          return;
-        }
-        skills.mnemonMinConfidence = n;
-      }
-      if (body.intervalMinutes !== undefined) {
-        const n = Number(body.intervalMinutes);
-        if (!Number.isFinite(n) || n < 1 || n > 10080) {
-          json(res, 400, { ok: false, error: '间隔应为 1–10080 之间的整数（分钟）' });
-          return;
-        }
-        skills.intervalMinutes = Math.floor(n);
-      }
-      state.skills = skills;
-      saveState(state);
-      json(res, 200, { ok: true, skills: state.skills, localRoot: LOCAL_SKILLS_ROOT });
-    },
-    /** 插件清单同步的配置：开关与插件库根目录。 */
-    'POST /plugins/config': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const next = { ...state.plugins };
-      if (typeof body.enabled === 'boolean') next.enabled = body.enabled;
-      if (typeof body.libraryRoot === 'string') {
-        const p = body.libraryRoot.trim();
-        next.libraryRoot = p ? normSlash(p) : '';
-        // 填了就必须是已存在的目录：不存在的路径建出来也是空的，同步一定失败
-        if (next.libraryRoot && !fs.existsSync(next.libraryRoot)) {
-          json(res, 400, { ok: false, error: `插件库目录不存在：${next.libraryRoot}` });
-          return;
-        }
-      }
-      state.plugins = next;
-      saveState(state);
-      json(res, 200, { ok: true, plugins: state.plugins });
-    },
-
-    /** 插件清单快照：我的特征文件夹 + 他人清单（只读，扫盘）。 */
-    'GET /plugins': async (req, res) => {
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const snap = shareSnapshot({
-        config: { libraryRoot: state.plugins.libraryRoot },
-        machineId,
-        machineHash: state.machineHash,
-        machineName: state.machineName,
-        publishedNames: Array.isArray(state.plugins.publishedNames) ? state.plugins.publishedNames : [],
-      });
-      json(res, 200, {
-        ok: true,
-        plugins: { ...state.plugins, effectiveRoot: pluginsLibraryRoot({ libraryRoot: state.plugins.libraryRoot }) },
-        share: snap,
-      });
-    },
-
-    /** 立即同步一次我的特征文件夹，并重新汇集他人清单。 */
-    'POST /plugins/sync': async (req, res) => {
-      if (typeof deps.syncPlugins !== 'function') {
-        json(res, 400, { ok: false, error: '宿主未提供清单同步能力' });
-        return;
-      }
-      const result = await deps.syncPlugins({ reason: '手动' });
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      json(res, 200, {
-        ok: result.ok !== false,
-        result,
-        plugins: { ...state.plugins, effectiveRoot: pluginsLibraryRoot({ libraryRoot: state.plugins.libraryRoot }) },
-        share: shareSnapshot({
-          config: { libraryRoot: state.plugins.libraryRoot },
-          machineId,
-          machineHash: state.machineHash,
-          machineName: state.machineName,
-          publishedNames: [],
-        }),
-      });
-    },
-
-    /** 装他人清单里的一个插件（人工点选；只走联网拉取）。 */
-    'POST /plugins/install': async (req, res) => {
-      const body = await readJson(req);
-      const name = typeof body.name === 'string' ? body.name.trim() : '';
-      if (!name) {
-        json(res, 400, { ok: false, error: '缺少 name' });
-        return;
-      }
-      if (typeof deps.pluginInstall !== 'function') {
-        json(res, 400, { ok: false, error: '宿主未提供插件安装通道' });
-        return;
-      }
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const result = await installSharedPlugin({
-        config: { libraryRoot: state.plugins.libraryRoot },
-        machineId,
-        publishedNames: [],
-        name,
-        installSpec: deps.pluginInstall,
-        addToBundles: deps.addToBundles,
-        log,
-      });
-      pushHistory(state, {
-        kind: result.ok ? 'plugins-install' : 'plugins-install-failed',
-        detail: result.ok
-          ? `从共享装 ${name}：${result.message}`
-          : `从共享装 ${name} 失败：${result.message}`,
-      });
-      saveState(state);
-      json(res, result.ok ? 200 : 400, {
-        ok: result.ok,
-        result,
-        share: shareSnapshot({
-          config: { libraryRoot: state.plugins.libraryRoot },
-          machineId,
-          machineHash: state.machineHash,
-          machineName: state.machineName,
-          publishedNames: [],
-        }),
-      });
-    },
-
-    'POST /preview': async (req, res) => {
-      const body = await readJson(req);
-      const state = loadState();
-      const machineId = deps.machineId() || state.machineId;
-      const all = listWorkspaces();
-      const matched = pickWorkspaces(all, state.folders);
-      const chosen =
-        Array.isArray(body.workspaceIds) && body.workspaceIds.length
-          ? matched.filter((w) => body.workspaceIds.includes(w.id))
-          : matched;
-
-      const localIndex = scanLocalSessions();
-      const out = chosen.map((ws) => {
-        const plan = previewPull({ workspace: ws, machineId, localIndex });
-        return {
-          id: ws.id,
-          title: ws.title || ws.path,
-          path: ws.path,
-          plan,
-          counts: plan.reduce((acc, p) => {
-            acc[p.action] = (acc[p.action] || 0) + 1;
-            return acc;
-          }, {}),
-        };
-      });
-      json(res, 200, { ok: true, workspaces: out });
-    },
-  };
-
-  return {
-    prefix: API_PREFIX,
-    routes,
-    /** 供 webServer 注册的统一 handler。 */
-    handle: async (req, res) => {
-      const url = new URL(req.url || '/', 'http://localhost');
-      if (!url.pathname.startsWith(API_PREFIX)) {
-        json(res, 404, { ok: false, error: 'not found' });
-        return;
-      }
-      const sub = url.pathname.slice(API_PREFIX.length) || '/';
-      const key = `${req.method} ${sub}`;
-      const handler = routes[key];
-      if (!handler) {
-        json(res, 404, { ok: false, error: `no route ${key}` });
-        return;
-      }
-      try {
-        await handler(req, res);
-      } catch (err) {
-        json(res, 500, {
-          ok: false,
-          error: String(err && err.message ? err.message : err),
-        });
-      }
-    },
-  };
-}
+/**
+ * Host 侧的 HTTP API。
+ * 路由：/api/local/dsh-sync-backup/*
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  loadState,
+  saveState,
+  pushHistory,
+  computeMachineId,
+  normSlash,
+  humanBytes,
+  pathKey,
+} from './core.js';
+import {
+  backupWorkspace,
+  listMachines,
+  pickWorkspaces,
+  previewPull,
+  projectKeysFor,
+  pullWorkspace,
+  scanLocalSessions,
+} from './backup.js';
+import { attachMany, attachedIds, findPulledUnattached, findUnattached } from './attach.js';
+import { joinMachineId, repairAll, scanFolders, splitMachineId } from './patrol.js';
+import {
+  adoptFeature,
+  decisionOf,
+  dropFeature,
+  featurePath,
+  forgetDecision,
+  hasFeature,
+  inactiveReason,
+  planFeatures,
+  rememberDecision,
+} from './features.js';
+import {
+  LINEAGE_FILE,
+  LOCAL_SKILLS_ROOT,
+  applyModeChange,
+  applyPull,
+  applyPush,
+  buildHistoryIndex,
+  diffSummary,
+  judgeUpdate,
+  loadLineage,
+  makeStamp,
+  planSync,
+  readMnemonLedger,
+  recordLineage,
+  resolveMode,
+  saveLineage,
+  scanSkills,
+} from './skills.js';
+import {
+  appendMasterChanges,
+  changelogPath,
+  ensureChangelog,
+  readChangelog,
+  readChangelogTimes,
+} from './changelog.js';
+import { runMnemonPrepass } from './mnemon.js';
+import {
+  runOptimizationCycle,
+  readQueue,
+  triage,
+  discoverOptimizations,
+  auditDraft,
+  MNEMON_LEDGER,
+} from './mnemon-optimize.js';
+import { createHostDrafter } from './mnemon-drafter.js';
+import {
+  SHARE_POLICY,
+  installSharedPlugin,
+  libraryRoot as pluginsLibraryRoot,
+  shareSnapshot,
+} from './plugins.js';
+
+export const API_PREFIX = '/api/local/dsh-sync-backup';
+
+/** 三种单机属性的中文名。 */
+export const MODE_LABEL = {
+  sync: '同步',
+  local: '本机独属',
+  master: '母版有·本机不拉取',
+};
+
+const json = (res, code, body) => {
+  const text = JSON.stringify(body);
+  res.writeHead(code, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  res.end(text);
+};
+
+async function readJson(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  if (!chunks.length) return {};
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * @param {{ workspaces: () => Array<{id:string,path:string,title:string}>,
+ *           machineId: () => string,
+ *           registerWorkspace?: (path:string, title:string) => Promise<{id:string,created:boolean}>,
+ *           wsEntity?: (id:string) => ({attachSession:(sid:string)=>Promise<void>, sessionIds:string[]}|undefined),
+ *           entities?: () => Array<{id:string,sessionIds?:string[]}> }} deps
+ */
+/** 手动触发的那一轮的运行态：路由异步化之后，进度只能从这里读。 */
+const optimizeRun = { running: false, startedAt: null, finishedAt: null, lastReport: null, lastError: null };
+
+export function createApi(deps) {
+  /**
+   * 起草器：宿主的 LLM。没有就返回 null，流水线会跳过起草阶段（只审核已有草稿）。
+   * 每轮现取现造，不缓存 —— 宿主换模型后下一轮就跟着换。
+   */
+  const drafter = () => (typeof deps.drafter === 'function' ? deps.drafter() : null);
+
+  /**
+   * 日志：api.js 是模块层，拿不到 index.js 里的 log。必须由 deps 注入。
+   * 不注入就静默 —— 静默比 ReferenceError 好：后者会让整条路由 500，
+   * 前端只看到「点了没反应」（实测就是这么被投诉的）。
+   */
+  const log = (m) => {
+    try {
+      if (typeof deps.log === 'function') deps.log(m);
+    } catch {
+      /* 日志失败不能影响主流程 */
+    }
+  };
+  const listWorkspaces = () =>
+    typeof deps.workspaces === 'function' ? deps.workspaces() : [];
+
+  /** 取某个工作区实体（能 attachSession 的那个），拿不到就返回 undefined。 */
+  const wsEntity = (id) =>
+    typeof deps.wsEntity === 'function' ? deps.wsEntity(id) : undefined;
+
+  /** 全部工作区实体，用于判断某个 sessionId 是否已有归属。 */
+  const entities = () =>
+    typeof deps.entities === 'function' ? deps.entities() || [] : [];
+
+  /** 本机某工作区路径对应的 projectKey 集合。 */
+  const projectKeysOf = (p) => projectKeysFor(p);
+
+  /**
+   * 判新旧要的三份只读证据。
+   *
+   * lineage      ：母版根目录的 `.skill-lineage.json`，同步插件自己的观测记录——
+   *                每侧内容何时变成现在这样、上次一致时的内容树是哪份。
+   * mnemonLedger：`~/.mnemon/skills/ledger.json`，记忆插件的技能账本，
+   *                里面每条 hash 就是 SKILL.md 的 sha256，reason='evolution'
+   *                就是它改的。只读，不写。
+   * history      ：母版 `_backup/`、本机 `.pre-pull-*`、记忆插件 `versions/`
+   *                里的历史全文，按内容哈希索引出「这份内容何时出现过」。
+   */
+  const judgeEvidence = (masterRoot) => ({
+    lineage: masterRoot ? loadLineage(path.join(masterRoot, LINEAGE_FILE)) : {},
+    mnemonLedger: readMnemonLedger(),
+    history: buildHistoryIndex({
+      masterRoot,
+      localRoot: LOCAL_SKILLS_ROOT,
+      changelogTimes: masterRoot ? readChangelogTimes(masterRoot) : null,
+    }),
+  });
+
+  /**
+   * 记录一次比对观测：两侧各自当前是什么内容、各自何时变成这样。
+   *
+   * 这是「内容修改时间」的唯一来源——不是 mtime（同步/NAS 搬运都会刷），
+   * 而是同步插件真正看到内容变化的那一刻。内容没变则时间保持不动。
+   *
+   * 两侧内容一致时顺手把 baseline 更新成这一份：基线就是「上次两侧一致的
+   * 内容树」，只有一致的时候才有意义。
+   */
+  const observeLineage = (masterRoot, plan, by) => {
+    if (!masterRoot) return 0;
+    const file = path.join(masterRoot, LINEAGE_FILE);
+    let map = loadLineage(file);
+    const now = Date.now();
+    let touched = 0;
+    for (const [name, m] of plan.master) {
+      const l = plan.local.get(name);
+      if (!l) continue; // 只有一侧有，没有可比性
+      const same = m.treeHash === l.treeHash;
+      map = recordLineage(map, {
+        name,
+        ...(same ? { baseline: m.treeHash } : {}),
+        master: m,
+        local: l,
+        by: by || '',
+        at: now,
+      });
+      touched++;
+    }
+    return saveLineage(file, map) ? touched : 0;
+  };
+
+  /** 同步真正落地之后，把两侧一致的内容登记成新基线。 */
+  const stampBaseline = (masterRoot, entries, by) => {
+    if (!masterRoot || !entries.length) return 0;
+    const file = path.join(masterRoot, LINEAGE_FILE);
+    let map = loadLineage(file);
+    for (const e of entries) {
+      if (!e) continue;
+      map = recordLineage(map, {
+        name: e.name,
+        baseline: e.treeHash,
+        master: e,
+        local: e,
+        by: by || '',
+      });
+    }
+    return saveLineage(file, map) ? entries.length : 0;
+  };
+
+  const routes = {
+    /** 全量状态：配置、匹配工作区、备份统计、其他机器。 */
+    'GET /state': async (req, res) => {
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const all = listWorkspaces();
+      const matched = pickWorkspaces(all, state.folders);
+      const localIndex = scanLocalSessions();
+
+      // 1.2.0：匹配的工作区里只把「有本机特征文件夹」的算作参与同步的；
+      // 其余的单独列一份「未参与」清单，面板上给原因和采纳按钮。
+      const active = matched.filter((ws) => hasFeature(ws.path, machineId));
+      const inactive = matched
+        .filter((ws) => !hasFeature(ws.path, machineId))
+        .map((ws) => ({
+          id: ws.id,
+          path: ws.path,
+          title: ws.title || ws.path,
+          featurePath: featurePath(ws.path, machineId),
+          declined: decisionOf(state, ws.path) === 'decline',
+          reason: inactiveReason(ws.path, machineId, state),
+        }));
+
+      const workspaces = active.map((ws) => {
+        const machines = listMachines(ws.path);
+        const own = machines.find((m) => m.machineId === machineId);
+        const others = machines.filter((m) => m.machineId !== machineId);
+        return {
+          id: ws.id,
+          path: ws.path,
+          title: ws.title || ws.path,
+          matchedPrefix: ws.matchedPrefix,
+          featurePath: featurePath(ws.path, machineId),
+          own: own ? { sessions: own.sessions, bytes: own.bytes, newest: own.newest } : { sessions: 0, bytes: 0, newest: 0 },
+          others: others.map((o) => ({
+            machineId: o.machineId,
+            sessions: o.sessions,
+            bytes: o.bytes,
+            newest: o.newest,
+          })),
+        };
+      });
+
+      // 待人工确认的清单（按矩阵，只有「没我的格子 + 没工作区」才问人）
+      const scan = scanFolders({
+        folders: state.folders,
+        workspaces: all,
+        machineId,
+      });
+      const plan = planFeatures({
+        folders: state.folders,
+        workspaces: all,
+        discover: scan.discover,
+        state,
+        machineId,
+      });
+
+      json(res, 200, {
+        ok: true,
+        machineId,
+        machineName: state.machineName,
+        machineHash: state.machineHash,
+        machineIdSuggested: computeMachineId(),
+        folders: state.folders,
+        lastBackupAt: state.lastBackupAt,
+        lastPullAt: state.lastPullAt,
+        patrol: state.patrol,
+        // 特征文件夹采纳：待人工确认清单 + 已有格子的工作区数
+        features: {
+          initialized: state.features.initialized === true,
+          pending: plan.ask,
+          pendingCount: plan.ask.length,
+          activeCount: active.length,
+          inactiveCount: inactive.length,
+          // 巡检会自动处理的（面板上只报个数）
+          autoCreateFolder: plan.createFolder.length,
+          autoRestoreWorkspace: plan.restoreWorkspace.length,
+        },
+        skills: { ...state.skills, localRoot: LOCAL_SKILLS_ROOT },
+        // 插件清单共享（1.0.0 从自动更新器迁来）：配置 + 运行态 + 口径声明
+        plugins: {
+          ...state.plugins,
+          // 面板没填时告诉用户实际会落到哪，避免「留空 = 不知道去哪」
+          effectiveRoot: pluginsLibraryRoot({ libraryRoot: state.plugins.libraryRoot }),
+          policy: SHARE_POLICY,
+        },
+        history: state.history.slice(0, 20),
+        workspaceCount: all.length,
+        matchedCount: workspaces.length,
+        matchedTotal: matched.length,
+        inactive,
+        workspaces,
+        totals: {
+          ownSessions: workspaces.reduce((n, w) => n + w.own.sessions, 0),
+          ownBytes: workspaces.reduce((n, w) => n + w.own.bytes, 0),
+          otherSessions: workspaces.reduce(
+            (n, w) => n + w.others.reduce((m, o) => m + o.sessions, 0),
+            0,
+          ),
+        },
+      });
+    },
+
+    /** 保存配置：文件夹前缀 / 机器标识。 */
+    'POST /config': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      if (Array.isArray(body.folders)) {
+        const seen = new Set();
+        state.folders = [];
+        for (const raw of body.folders) {
+          if (typeof raw !== 'string') continue;
+          const p = normSlash(raw.trim());
+          if (!p) continue;
+          const k = pathKey(p);
+          if (seen.has(k)) continue;
+          seen.add(k);
+          state.folders.push(p);
+        }
+      }
+      if (typeof body.machineName === 'string') {
+        // 只改名称部分，哈希固定不变
+        state.machineName = body.machineName.replace(/[\\/:*?"<>|\s]+/g, '_').trim();
+        state.machineHash = deps.machineHash ? deps.machineHash() || state.machineHash : state.machineHash;
+        state.machineId = joinMachineId(state.machineName, state.machineHash);
+      }
+      if (typeof body.machineId === 'string' && body.machineId.trim() && body.machineName === undefined) {
+        // 兼容：直接给完整标识时，拆出名称，哈希仍以本地为准
+        const parsed = splitMachineId(body.machineId.trim(), state.machineHash);
+        state.machineName = parsed.name.replace(/[\\/:*?"<>|\s]+/g, '_');
+        state.machineId = joinMachineId(state.machineName, state.machineHash);
+      }
+      saveState(state);
+      json(res, 200, {
+        ok: true,
+        folders: state.folders,
+        machineId: state.machineId,
+        machineName: state.machineName,
+        machineHash: state.machineHash,
+      });
+    },
+
+    /** 立即备份：只备份「有本机特征文件夹」的工作区。 */
+    'POST /backup': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const all = listWorkspaces();
+      // 1.2.0：只对「特征文件夹存在」的工作区干活；没建格子的跳过并报原因
+      const matchedAll = pickWorkspaces(all, state.folders);
+      const matched = matchedAll.filter((w) => hasFeature(w.path, machineId));
+      const skipped = matchedAll
+        .filter((w) => !hasFeature(w.path, machineId))
+        .map((w) => ({
+          id: w.id,
+          path: w.path,
+          title: w.title || w.path,
+          reason: '没有本机特征文件夹（未参与备份）',
+        }));
+      const chosen =
+        Array.isArray(body.workspaceIds) && body.workspaceIds.length
+          ? matched.filter((w) => body.workspaceIds.includes(w.id))
+          : matched;
+
+      const localIndex = scanLocalSessions();
+      const results = [];
+      for (const ws of chosen) {
+        results.push(backupWorkspace({ workspace: ws, machineId, localIndex }));
+      }
+
+      const created = results.reduce((n, r) => n + r.created, 0);
+      const updated = results.reduce((n, r) => n + r.updated, 0);
+      const bytes = results.reduce((n, r) => n + r.bytes, 0);
+
+      const next = loadState();
+      next.lastBackupAt = Date.now();
+      pushHistory(
+        next,
+        'backup',
+        `备份 ${chosen.length} 个工作区：新增 ${created}、更新 ${updated}、${humanBytes(bytes)}` +
+          `${skipped.length ? `；跳过 ${skipped.length} 个没有本机特征文件夹的` : ''}`,
+      );
+      saveState(next);
+
+      json(res, 200, {
+        ok: true,
+        results,
+        skipped,
+        summary: { workspaces: chosen.length, created, updated, bytes, skipped: skipped.length },
+      });
+    },
+
+    /**
+     * 一键拉取：多选工作区。
+     *
+     * 1.2.0 起只拉「有本机特征文件夹」的工作区——没建格子的本机不参与同步，
+     * 往里拉会话等于替人做决定。拉完的会话归属登记是拉取的一部分，不再单列按钮：
+     * 只写文件不登记，DSH 侧栏只会把它显示成「未分组」。
+     */
+    'POST /pull': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const all = listWorkspaces();
+      const matchedAll = pickWorkspaces(all, state.folders);
+      const matched = matchedAll.filter((w) => hasFeature(w.path, machineId));
+      const skipped = matchedAll
+        .filter((w) => !hasFeature(w.path, machineId))
+        .map((w) => ({
+          id: w.id,
+          path: w.path,
+          title: w.title || w.path,
+          reason: '没有本机特征文件夹（未参与拉取）',
+        }));
+      const chosen =
+        Array.isArray(body.workspaceIds) && body.workspaceIds.length
+          ? matched.filter((w) => body.workspaceIds.includes(w.id))
+          : matched;
+
+      /**
+       * 有备份、但没注册成工作区的目录。
+       *
+       * 这是「拉取后显示在未分组」最常见的原因之一：目录里有别的机器的
+       * 会话备份，可它压根不在 workspaceRegistry 里，/pull 的匹配范围就没有它。
+       *
+       * 但它同时是「本机还没建特征文件夹」的目录 —— 1.2.0 起**不再自动注册**：
+       * 注册 + 建格子必须由人在面板上确认（POST /features/adopt）。
+       * 这里只把它们列在 unregistered 里交回去。
+       */
+      const autoRegister = body.autoRegister === true;
+      const registered = [];
+      const registerErrors = [];
+      const unregistered = [];
+      if (typeof deps.registerWorkspace === 'function') {
+        const scan = scanFolders({
+          folders: state.folders,
+          workspaces: all,
+          machineId,
+        });
+        for (const item of scan.discover) {
+          // 只关心「确实有别的机器的备份」那些，空壳目录不提
+          const hasRemote = listMachines(item.path).some((m) => m.machineId !== machineId);
+          if (!hasRemote) continue;
+          if (hasFeature(item.path, machineId)) continue;
+          if (!autoRegister) {
+            unregistered.push({ path: item.path, title: item.title, why: '需要先建本机特征文件夹' });
+            continue;
+          }
+          // 显式 autoRegister:true（供脚本/测试用），仍然要先建格子再注册
+          try {
+            adoptFeature(item.path, machineId);
+            const out = await deps.registerWorkspace(item.path, item.title);
+            registered.push({ path: item.path, id: out?.id });
+            all.push({ id: out?.id, path: item.path, title: item.title });
+          } catch (err) {
+            registerErrors.push({ path: item.path, message: String((err && err.message) || err) });
+          }
+        }
+      }
+
+      // 注册完重新匹配一次，把新注册的目录纳入拉取范围（仍只含有格子的）
+      const matched2 = pickWorkspaces(all, state.folders).filter((w) => hasFeature(w.path, machineId));
+      const chosen2 =
+        Array.isArray(body.workspaceIds) && body.workspaceIds.length
+          ? matched2.filter((w) =>
+              body.workspaceIds.includes(w.id) ||
+              registered.some((r) => r.path === w.path),
+            )
+          : matched2;
+
+      const localIndex = scanLocalSessions();
+      const results = [];
+      for (const ws of chosen2) {
+        const r = pullWorkspace({
+          workspace: ws,
+          machineId,
+          localIndex,
+          machines: Array.isArray(body.machines) && body.machines.length ? body.machines : null,
+        });
+
+        // 关键一步：把刚落盘的会话登记进工作区归属账。
+        // 只写文件不登记，DSH 侧栏只会把它显示成「未分组」。
+        const entity = wsEntity(ws.id);
+        if (r.newSessionIds.length) {
+          const att = await attachMany(entity, r.newSessionIds);
+          r.attached = att.attached;
+          r.attachFailed = att.failed;
+        } else {
+          r.attached = [];
+          r.attachFailed = [];
+        }
+        results.push(r);
+      }
+
+      const imported = results.reduce((n, r) => n + r.imported, 0);
+      const updated = results.reduce((n, r) => n + r.updated, 0);
+      const forked = results.reduce((n, r) => n + r.forked, 0);
+      const attached = results.reduce((n, r) => n + (r.attached || []).length, 0);
+      const attachFailed = results.reduce((n, r) => n + (r.attachFailed || []).length, 0);
+
+      const next = loadState();
+      next.lastPullAt = Date.now();
+      pushHistory(
+        next,
+        'pull',
+        `拉取 ${chosen2.length} 个工作区：新增 ${imported}、更新 ${updated}、分叉 ${forked}、登记 ${attached}${
+          attachFailed ? `、登记失败 ${attachFailed}` : ''
+        }${registered.length ? `、自动注册 ${registered.length}` : ''}`,
+      );
+      saveState(next);
+
+      json(res, 200, {
+        ok: true,
+        results,
+        skipped,
+        registered,
+        registerErrors,
+        unregistered,
+        summary: {
+          workspaces: chosen2.length,
+          imported,
+          updated,
+          forked,
+          attached,
+          attachFailed,
+          registered: registered.length,
+          skipped: skipped.length,
+        },
+        // 全部登记成功就不需要重开会话索引：会话列表是实时读盘 + 归属表的
+        needsRestart: imported + forked > attached,
+      });
+    },
+
+    /**
+     * 采纳：给选中的目录建本机特征文件夹；未注册的顺带注册成工作区。
+     *
+     * 这是「检测到匹配的工作区文件夹 → 人工选择要不要在里面建本机特征文件夹」
+     * 的那个人工入口。同意之后立刻生效：进侧边栏、参与备份与拉取，
+     * 不需要再点一次注册。
+     */
+    'POST /features/adopt': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const wanted = Array.isArray(body.paths)
+        ? body.paths.filter((p) => typeof p === 'string' && p.trim())
+        : [];
+      if (!wanted.length) {
+        json(res, 400, { ok: false, error: '未选择任何目录' });
+        return;
+      }
+
+      const existing = new Set(listWorkspaces().map((w) => pathKey(w.path)));
+      const adopted = [];
+      const registeredList = [];
+      const errors = [];
+
+      for (const raw of wanted) {
+        const p = normSlash(raw);
+        try {
+          const target = adoptFeature(p, machineId);
+          rememberDecision(state, p, 'adopt');
+          let registeredId;
+          if (!existing.has(pathKey(p))) {
+            if (typeof deps.registerWorkspace === 'function') {
+              const out = await deps.registerWorkspace(p, path.basename(p));
+              registeredId = out?.id;
+              existing.add(pathKey(p));
+              registeredList.push({ path: p, id: registeredId });
+            }
+          } else {
+            registeredId = listWorkspaces().find((w) => pathKey(w.path) === pathKey(p))?.id;
+          }
+          adopted.push({ path: p, id: registeredId, feature: target });
+        } catch (err) {
+          errors.push({ path: p, message: String((err && err.message) || err) });
+        }
+      }
+
+      // 基线补上：刚采纳的立刻算「已知」，否则下一轮会被当成新建/缺失再处理一遍
+      if (!state.features) state.features = { initialized: true, decisions: {}, known: {} };
+      for (const item of adopted) {
+        if (item.id !== undefined && item.id !== null) state.features.known[String(item.id)] = item.path;
+      }
+      pushHistory(
+        state,
+        'features',
+        `按人工选择建本机特征文件夹 ${adopted.length} 个${
+          registeredList.length ? `（其中注册工作区 ${registeredList.length} 个）` : ''
+        }`,
+      );
+      saveState(state);
+
+      json(res, 200, { ok: true, adopted, registered: registeredList, errors });
+    },
+
+    /** 拒绝：记录「这个目录本机不要建格子」，之后巡检不再反复建。 */
+    'POST /features/decline': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const wanted = Array.isArray(body.paths)
+        ? body.paths.filter((p) => typeof p === 'string' && p.trim())
+        : [];
+      if (!wanted.length) {
+        json(res, 400, { ok: false, error: '未选择任何目录' });
+        return;
+      }
+      for (const raw of wanted) rememberDecision(state, normSlash(raw), 'decline');
+      pushHistory(state, 'features', `跳过 ${wanted.length} 个目录（不建本机特征文件夹）`);
+      saveState(state);
+      json(res, 200, { ok: true, declined: wanted.map((p) => normSlash(p)) });
+    },
+
+    /**
+     * 删除：删本机特征文件夹（等于本机不再参与这个工作区的同步）。
+     *
+     * body.removeWorkspace=true 时连工作区注册一起去掉（侧边栏不再显示）；
+     * 默认只删格子，保留工作区，因为「不想同步」和「不想在这里干活」是两件事。
+     */
+    'POST /features/drop': async (req, res) => {
+      const body = await readJson(req);
+      const machineId = deps.machineId() || loadState().machineId;
+      const wanted = Array.isArray(body.paths)
+        ? body.paths.filter((p) => typeof p === 'string' && p.trim())
+        : [];
+      if (!wanted.length) {
+        json(res, 400, { ok: false, error: '未选择任何目录' });
+        return;
+      }
+      if (typeof deps.deleteWorkspace !== 'function') {
+        json(res, 503, { ok: false, error: '当前环境不支持删除工作区' });
+        return;
+      }
+
+      /**
+       * 删工作区（连带删本机特征文件夹）。语义按「有没有别人的格子」分两种：
+       *
+       *   - **只有本机这一格**：连 `.dsh-sync/` 一起收掉。巡检就再也扫不到它，
+       *     不会追问、也不会被当成本机没建的共享工作区（用户明确要求）。
+       *   - **还有别人的格子**：只删我这一格（连同格里备份的对话），`.dsh-sync/` 留着。
+       *     巡检据此认为「本机没有这个共享工作区」，进人工队列问要不要重建。
+       *
+       * 必须删工作区注册本身：只删格子会留下「已注册但没格子」的工作区，
+       * 下一轮巡检按矩阵会把它判成「有工作区没格子 → 补文件夹」，看起来就是删不掉。
+       */
+      const all = listWorkspaces();
+      const dropped = [];
+      const errors = [];
+
+      for (const raw of wanted) {
+        const p = normSlash(raw);
+        try {
+          const hit = all.find((w) => pathKey(w.path) === pathKey(p));
+          if (!hit) {
+            errors.push({ path: p, message: '这个目录没有注册成工作区，无需删除' });
+            continue;
+          }
+          await deps.deleteWorkspace(hit.id);
+          const out = dropFeature(p, machineId, { log });
+          const state = loadState();
+          for (const [id, knownPath] of Object.entries(state.features.known || {})) {
+            if (pathKey(knownPath) === pathKey(p)) delete state.features.known[id];
+          }
+          // 删掉 ≠「本机不要这个目录」：它是删工作区。不清这条记录，巡检会把它过滤掉。
+          forgetDecision(state, p);
+          pushHistory(
+            state,
+            'features',
+            `删除工作区并清掉本机特征文件夹：${path.basename(p)}${
+              out.keptStructure && (out.others || []).length
+                ? `（保留 ${out.others.length} 个其他机器的格子，巡检会问要不要重建）`
+                : '（目录结构一并收掉，巡检不再列出）'
+            }`,
+          );
+          saveState(state);
+          dropped.push({
+            path: p,
+            title: hit.title,
+            id: hit.id,
+            removed: out.removed,
+            removedWorkspace: true,
+            others: out.others || [],
+            keptStructure: !!out.keptStructure,
+          });
+        } catch (err) {
+          errors.push({ path: p, message: String((err && err.message) || err) });
+        }
+      }
+
+      json(res, 200, { ok: true, dropped, errors });
+    },
+
+    /**
+     * 补登记：把「本插件拉进来、但没进归属账」的会话补进 sessionIds。
+     *
+     * 这是历史遗留数据的清理入口——旧版拉取只写文件不登记，
+     * 那些会话至今仍散在「未分组」里。**日常不需要点**：/pull 拉完自己会登记。
+     *
+     * 默认只补拉取产物（别的机器备份目录里有它），不会把自动化插件和
+     * 子代理留下的会话一起刷进来。要全量补必须显式传 all:true。
+     * 1.2.0 起只处理有本机特征文件夹的工作区。
+     */
+    'POST /attach/repair': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const all = listWorkspaces();
+      const matched = pickWorkspaces(all, state.folders).filter((w) => hasFeature(w.path, machineId));
+      const chosen =
+        Array.isArray(body.workspaceIds) && body.workspaceIds.length
+          ? matched.filter((w) => body.workspaceIds.includes(w.id))
+          : matched;
+
+      const localIndex = scanLocalSessions();
+      const ents = entities();
+      const scopeAll = body.all === true;
+      const results = [];
+
+      for (const ws of chosen) {
+        const entity = wsEntity(ws.id);
+        if (!entity) {
+          results.push({ id: ws.id, title: ws.title || ws.path, attached: [], skipped: '当前环境不支持登记会话归属' });
+          continue;
+        }
+        const missing = scopeAll
+          ? findUnattached({ workspace: ws, entities: ents, localIndex, projectKeysFor })
+          : findPulledUnattached({
+              workspace: ws,
+              machineId,
+              entities: ents,
+              localIndex,
+              projectKeysFor,
+            });
+        const att = await attachMany(entity, missing);
+        results.push({
+          id: ws.id,
+          title: ws.title || ws.path,
+          scope: scopeAll ? 'all' : 'pulled',
+          candidates: missing.length,
+          attached: att.attached,
+          failed: att.failed,
+        });
+      }
+
+      const total = results.reduce((n, r) => n + (r.attached || []).length, 0);
+      const failed = results.reduce((n, r) => n + ((r.failed && r.failed.length) || 0), 0);
+
+      const next = loadState();
+      if (total || failed) {
+        pushHistory(next, 'attach', `补登记归属：成功 ${total}、失败 ${failed}`);
+        saveState(next);
+      }
+
+      json(res, 200, {
+        ok: true,
+        scope: scopeAll ? 'all' : 'pulled',
+        results,
+        summary: { attached: total, failed },
+      });
+    },
+
+    /**
+     * 巡检：只扫描，不动任何文件。
+     *
+     * 返回四类：
+     *   discover   符合插件结构、但本机还没注册的目录（要人点）
+     *   pending    需要人工决定「要不要在本机建特征文件夹」的（含 discover 与存量工作区）
+     *   restore/drop  下一轮巡检会自动做的（外部删除自愈 / 随工作区删除）
+     *   repair     已注册但缺格子——1.2.0 起不再自动补，归到 pending 让人点头
+     */
+    'POST /patrol/scan': async (req, res) => {
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const all = listWorkspaces();
+      const result = scanFolders({
+        folders: state.folders,
+        workspaces: all,
+        machineId,
+      });
+      const plan = planFeatures({
+        folders: state.folders,
+        workspaces: all,
+        discover: result.discover,
+        state,
+        machineId,
+      });
+
+      const next = loadState();
+      next.patrol = {
+        ...next.patrol,
+        lastRunAt: Date.now(),
+        lastResult: {
+          discover: result.discover.length,
+          repair: result.repair.length,
+          ask: plan.ask.length,
+          createFolder: plan.createFolder.length,
+          restoreWorkspace: plan.restoreWorkspace.length,
+        },
+      };
+      saveState(next);
+
+      json(res, 200, {
+        ok: true,
+        ...result,
+        // 人要看的那一档
+        pending: plan.ask,
+        // 下面三类巡检会自己做，这里只报个数方便核对
+        autoCreateFolder: plan.createFolder,
+        autoRestoreWorkspace: plan.restoreWorkspace,
+        autoDrop: plan.drop,
+        machineId,
+      });
+    },
+
+    /**
+     * 注册：把选中的目录注册为工作区，并建本机特征文件夹。
+     *
+     * 与 /features/adopt 等价（保留旧路由给已有面板/脚本用）。
+     */
+    'POST /patrol/register': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const paths = Array.isArray(body.paths) ? body.paths.filter((p) => typeof p === 'string') : [];
+      if (!paths.length) {
+        json(res, 400, { ok: false, error: '未选择任何目录' });
+        return;
+      }
+      if (typeof deps.registerWorkspace !== 'function') {
+        json(res, 503, { ok: false, error: '当前环境不支持注册工作区' });
+        return;
+      }
+
+      const registered = [];
+      const errors = [];
+      const existing = new Set(listWorkspaces().map((w) => pathKey(w.path)));
+
+      for (const p of paths) {
+        try {
+          if (existing.has(pathKey(p))) {
+            // 已注册但可能缺格子：这次点了同意就等于确认建格子
+            const target = adoptFeature(p, machineId);
+            rememberDecision(state, p, 'adopt');
+            registered.push({ path: p, skipped: '已注册', own: target });
+            continue;
+          }
+          const out = await deps.registerWorkspace(p, path.basename(p));
+          // 注册 + 建格子一起做：人点了同意，就该立刻参与
+          const target = adoptFeature(p, machineId);
+          rememberDecision(state, p, 'adopt');
+          if (out?.id !== undefined) state.features.known[String(out.id)] = normSlash(p);
+          registered.push({ path: p, id: out?.id, created: !!out?.created, own: target });
+        } catch (err) {
+          errors.push({ path: p, message: String((err && err.message) || err) });
+        }
+      }
+
+      pushHistory(state, 'register', `注册 ${registered.length} 个工作区（含建本机特征文件夹）`);
+      saveState(state);
+
+      json(res, 200, { ok: true, registered, errors });
+    },
+
+    /**
+     * 补建：给选中的工作区建本机特征文件夹。
+     *
+     * 1.2.0 起**不再**「发现问题就自动补」：只补传进来的 paths，
+     * 没传就什么都不做（历史上这里会对全部匹配工作区动手）。
+     */
+    'POST /patrol/repair': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const all = listWorkspaces();
+      const targets = Array.isArray(body.paths) && body.paths.length
+        ? all.filter((w) => body.paths.some((p) => pathKey(p) === pathKey(w.path)))
+        : [];
+
+      const out = repairAll(targets, machineId);
+      for (const p of body.paths || []) rememberDecision(state, p, 'adopt');
+      if (!state.features) state.features = { initialized: true, decisions: {}, known: {} };
+      for (const ws of targets) {
+        if (!hasFeature(ws.path, machineId)) continue;
+        state.features.known[String(ws.id)] = normSlash(ws.path);
+      }
+      pushHistory(state, 'repair', `补建 ${out.created.length} 个本机特征文件夹（人工指定）`);
+      saveState(state);
+
+      json(res, 200, { ok: true, ...out });
+    },
+
+    /** 定时巡检设置。 */
+    'POST /patrol/config': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const patrol = { ...state.patrol };
+
+      if (typeof body.enabled === 'boolean') patrol.enabled = body.enabled;
+      if (body.intervalMinutes !== undefined) {
+        const n = Number(body.intervalMinutes);
+        if (!Number.isFinite(n) || n < 1 || n > 1440) {
+          json(res, 400, { ok: false, error: '间隔应为 1–1440 之间的整数（分钟）' });
+          return;
+        }
+        patrol.intervalMinutes = Math.floor(n);
+      }
+      state.patrol = patrol;
+      saveState(state);
+      json(res, 200, { ok: true, patrol: state.patrol });
+    },
+
+    /* ---------------- 技能同步 ---------------- */
+
+    /**
+     * 比对 + 自动同步。
+     *
+     * 语义（用户 2026-11-01 定）：同步属性的技能，比对时就把能定下来的更新做掉——
+     * 母版更新就拉下来，本机更新就推上去。只有**判不出谁新**的才留给用户裁决。
+     *
+     * body.auto === false 时退化为纯比对（只报告，不动任何文件）。
+     */
+    'POST /skills/scan': async (req, res) => {
+      const body = await readJson(req).catch(() => ({}));
+      const auto = body && body.auto === false ? false : true;
+      const dryRunFlag = body?.dryRun === true;
+      const state = loadState();
+      const master = state.skills.masterRoot;
+      if (!master) {
+        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
+        return;
+      }
+      if (!fs.existsSync(master)) {
+        json(res, 400, { ok: false, error: `母版文件夹不存在或不可访问：${master}` });
+        return;
+      }
+
+      // ── 阶段 0：记忆插件技能优化闭环（发现 → 起草 → 审核 → 落地 → 结案）
+      // 0.8.0 起这一步会写账本（结案）并调模型起草；dryRun 时只报告。
+      const optimize = auto
+        ? await runOptimizationCycle({
+            localRoot: LOCAL_SKILLS_ROOT,
+            masterRoot: master,
+            stageDir: process.env.DSH_SYNC_STAGE_DIR || 'C:/DSH-Work/mnemon-drafts/stage',
+            minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
+            enabled: state.skills.mnemonOptimize !== false,
+            // 比对/巡检必须自己把「生成草案」这一步走完。
+            //
+            // 历史：这里曾经写死 `draft: null`，理由是「比对是同步语义，起草要调模型会卡住」。
+            // 结果是任何走比对路径的巡检（面板点「比对」、开机首拉、每 120 分钟的定时轮）
+            // 都只发现建议、从不起草，建议永远停在 pending；只有单独点「立即优化」
+            // 或走定时器那条后台链路才会起草。用户要的是「巡检发现待处理就自己处理完」，
+            // 所以把起草器接回来，由 body 控制：
+            //   body.draft   === false → 只比对（显式要求纯比对时才这样）
+            //   body.dryRun  === true  → 不调模型（预演）
+            // 其余情况一律带起草器，让「发现 → 起草 → 审核 → 落地 → 结案」在一条路径里跑完。
+            draft: dryRunFlag || body?.draft === false ? null : drafter(),
+            maxDrafts: Number(state.skills.mnemonMaxDrafts) || 6,
+            onEvent: (kind, payload) => log(`优化闭环 ${kind}: ${JSON.stringify(payload)}`),
+          })
+        : { enabled: false, skipped: 'auto=false', discovered: { suggestions: 0, drafts: 0 }, todo: [], dropped: [], enqueued: [], audited: [], accepted: [], errors: [] };
+
+      // 记忆插件草稿预处理：auto 时先落地再比对，比对看到的就是落地后的内容
+      const prepass = auto
+        ? runMnemonPrepass({
+            masterRoot: master,
+            localRoot: LOCAL_SKILLS_ROOT,
+            modes: state.skills.modes || {},
+            machineId: state.machineId,
+            machineName: state.machineName,
+            enabled: state.skills.mnemonAuto !== false,
+          })
+        : { enabled: false, drafts: 0, apply: [], skipped: [], applied: [], pushed: [], errors: [] };
+
+      const plan = planSync({
+        masterRoot: master,
+        localRoot: LOCAL_SKILLS_ROOT,
+        modes: state.skills.modes || {},
+        ...judgeEvidence(master),
+      });
+
+      // 比对本身就是一次观测：记下两侧各自现在是什么内容、何时变成这样
+      const next = loadState();
+      const observed = observeLineage(master, plan, next.machineId);
+
+      const stamp = makeStamp();
+      let pulled = { pulled: [], errors: [] };
+      let pushed = { pushed: [], errors: [] };
+
+      if (auto && (plan.pull.length || plan.autoPush.length)) {
+        // 母版更新 → 拉到本机
+        if (plan.pull.length) {
+          pulled = applyPull({ items: plan.pull, localRoot: LOCAL_SKILLS_ROOT, stamp });
+        }
+        // 本机更新（同步属性）→ 推回母版，旧版先存档
+        if (plan.autoPush.length) {
+          const backRoot = path.join(master, '_backup');
+          pushed = applyPush({ items: plan.autoPush, masterRoot: master, backRoot, stamp });
+          const auditItems = pushed.pushed.map((p) => ({
+            skill: p.name,
+            operation: p.operation,
+            detail: `${p.operation === '覆盖' ? `旧版备份于 _backup/${p.name}.${stamp}` : '母版此前无此技能'}（自动：内容更新）`,
+          }));
+          if (auditItems.length) {
+            try {
+              appendMasterChanges(auditItems, {
+                masterRoot: master,
+                machineId: next.machineId,
+                machineName: next.machineName,
+                trigger: '自动同步',
+              });
+            } catch {
+              /* 记录写不进去不影响同步本身 */
+            }
+          }
+        }
+        // 同步过的内容现在两侧一致，登记成新基线
+        const aligned = [
+          ...plan.pull.map((x) => x.master),
+          ...plan.autoPush.map((x) => x.local),
+          ...plan.same.map((x) => x.master),
+        ].filter(Boolean);
+        if (aligned.length) {
+          let map = loadLineage(path.join(master, LINEAGE_FILE));
+          for (const e of aligned) {
+            map = recordLineage(map, { name: e.name, baseline: e.treeHash, master: e, local: e, by: next.machineId });
+          }
+          saveLineage(path.join(master, LINEAGE_FILE), map);
+        }
+      }
+
+      next.skills.lastRunAt = Date.now();
+      next.skills.lastResult = {
+        pull: plan.pull.length,
+        autoPush: plan.autoPush.length,
+        push: plan.push.length,
+        same: plan.same.length,
+        localOnly: plan.localOnly.length,
+        pulled: pulled.pulled.length,
+        pushed: pushed.pushed.length,
+        observed,
+        auto,
+        scannedAt: plan.scannedAt,
+        mnemon: {
+          drafts: prepass.drafts,
+          applied: prepass.applied.length,
+          pushed: prepass.pushed.length,
+          skipped: prepass.skipped.length,
+        },
+      };
+      if (auto && (pulled.pulled.length || pushed.pushed.length || prepass.applied.length)) {
+        pushHistory(
+          next,
+          'skills',
+          `技能自动同步：拉取 ${pulled.pulled.length}、推送 ${pushed.pushed.length}、待裁决 ${plan.push.length}${
+            prepass.applied.length ? `、记忆插件草稿落地 ${prepass.applied.length}` : ''
+          }`,
+        );
+      }
+      saveState(next);
+
+      const brief = (x) => ({
+        name: x.name,
+        action: x.action,
+        reason: x.reason || (x.action === 'new' ? '母版新增' : ''),
+        basis: x.basis || null,
+      });
+
+      const pulledNames = new Set(pulled.pulled.map((p) => p.name));
+      const pushedNames = new Set(pushed.pushed.map((p) => p.name));
+
+      json(res, 200, {
+        ok: true,
+        masterRoot: master,
+        localRoot: LOCAL_SKILLS_ROOT,
+        auto,
+        stamp,
+        // 母版更新：自动拉取
+        pull: plan.pull.map((x) => ({ ...brief(x), version: x.master.version, done: pulledNames.has(x.name) })),
+        // 本机更新（同步属性）：自动推送
+        autoPush: plan.autoPush.map((x) => ({
+          ...brief(x),
+          masterVersion: x.master.version,
+          localVersion: x.local.version,
+          done: pushedNames.has(x.name),
+        })),
+        // 判不出来的：只报告，等用户裁决（附差异摘要，方便一眼决定）
+        push: plan.push.map((x) => ({
+          ...brief(x),
+          masterVersion: x.master.version,
+          localVersion: x.local.version,
+          diff: x.diff || null,
+        })),
+        same: plan.same.map((x) => x.name),
+        localOnly: plan.localOnly.map((x) => x.name),
+        // 优化闭环：发现了什么、判断结果、入队、审核、通过
+        optimize,
+        // 记忆插件草稿：这一轮落地了哪些、跳过了哪些（跳过都带原因）
+        mnemon: {
+          enabled: prepass.enabled,
+          drafts: prepass.drafts,
+          apply: prepass.apply,
+          applied: prepass.applied.map((a) => ({
+            name: a.name,
+            action: a.action,
+            draftId: a.draftId,
+            targetRoot: a.targetRoot,
+            backup: a.backup,
+          })),
+          pushed: prepass.pushed.map((p) => ({ name: p.name, operation: p.operation })),
+          skipped: prepass.skipped,
+        },
+        errors: [...pulled.errors, ...pushed.errors, ...prepass.errors],
+        observed,
+      });
+    },
+
+    /**
+     * 优化闭环的只读快照：队列里在等什么、账本里还有多少建议没做。
+     *
+     * 不改任何文件。面板用它显示「现在积压了多少」。
+     */
+    /**
+     * 手动跑一轮完整流程（发现 → 起草 → 审核 → 落地 → 结案）。
+     *
+     * body: { dryRun?: boolean, maxDrafts?: number, wait?: boolean }
+     *
+     * **默认立刻返回 202，起草在后台跑**。为什么：一轮 6 条草稿要两分钟以上，
+     * 串在 HTTP 响应里会让前端「点了没反应」（实测就是这么被投诉的），
+     * 浏览器/代理还可能先超时。要同步结果就传 `wait:true`（只建议 dryRun 时用）。
+     * 进度用 `POST /skills/optimize/state` 的 running/nextRun 两个字段轮询。
+     */
+    'POST /skills/optimize/run': async (req, res) => {
+      const body = (await readJson(req).catch(() => ({}))) || {};
+      const state = loadState();
+      // 母版不是必需品：没有母版照样能落地并结案（结案不依赖母版是既有约定），
+      // 只是跳过「推母版」这一步。所以这里不拦，只在报告里说明。
+      const master = state.skills.masterRoot || undefined;
+      const enabled = state.skills.mnemonOptimize !== false;
+      const maxDrafts = Number(body.maxDrafts) || Number(state.skills.mnemonMaxDrafts) || 6;
+      const dryRun = body.dryRun === true;
+
+      const runOnce = () =>
+        runOptimizationCycle({
+          localRoot: LOCAL_SKILLS_ROOT,
+          masterRoot: master,
+          stageDir: process.env.DSH_SYNC_STAGE_DIR || 'C:/DSH-Work/mnemon-drafts/stage',
+          minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
+          maxDrafts,
+          dryRun,
+          // dryRun 不调模型：那样「预演」也要两分钟，且没有意义（没落地可预演）
+          draft: dryRun ? null : drafter(),
+          enabled,
+          onEvent: (kind, payload) => log(`优化闭环 ${kind}: ${JSON.stringify(payload)}`),
+        });
+
+      // 同步模式：只给 dryRun / 明确要 wait 的调用方
+      if (body.wait === true || dryRun) {
+        try {
+          const report = await runOnce();
+          json(res, 200, { ok: true, report });
+        } catch (err) {
+          json(res, 500, { ok: false, error: String((err && err.message) || err) });
+        }
+        return;
+      }
+
+      // 异步模式（默认）：立刻回 202，后台跑
+      if (optimizeRun.running) {
+        json(res, 202, {
+          ok: true,
+          started: false,
+          running: true,
+          startedAt: optimizeRun.startedAt,
+          note: '上一轮还在跑，本次不重复启动',
+        });
+        return;
+      }
+      optimizeRun.running = true;
+      optimizeRun.startedAt = new Date().toISOString();
+      optimizeRun.lastReport = null;
+      optimizeRun.lastError = null;
+      runOnce()
+        .then((report) => {
+          optimizeRun.lastReport = {
+            at: new Date().toISOString(),
+            remaining: report.remaining,
+            closed: report.closed,
+            landed: (report.pipeline && report.pipeline.stage && report.pipeline.stage.landed) || [],
+            drafted: (report.pipeline && report.pipeline.stage && report.pipeline.stage.drafted) || [],
+            failed: (report.pipeline && report.pipeline.stage && report.pipeline.stage.failed) || [],
+            errors: report.errors,
+          };
+          log(
+            `优化闭环（手动）：起草 ${optimizeRun.lastReport.drafted.length}、` +
+              `落地 ${optimizeRun.lastReport.landed.length}、失败 ${optimizeRun.lastReport.failed.length}、` +
+              `剩余 ${report.remaining}`,
+          );
+        })
+        .catch((err) => {
+          optimizeRun.lastError = String((err && err.message) || err);
+          log(`优化闭环（手动）失败：${optimizeRun.lastError}`);
+        })
+        .finally(() => {
+          optimizeRun.running = false;
+          optimizeRun.finishedAt = new Date().toISOString();
+        });
+      json(res, 202, {
+        ok: true,
+        started: true,
+        running: true,
+        startedAt: optimizeRun.startedAt,
+        maxDrafts,
+        note: '起草已转后台，用 POST /skills/optimize/state 轮询进度',
+      });
+    },
+
+    'POST /skills/optimize/state': async (req, res) => {
+      const state = loadState();
+      const queue = readQueue();
+      const found = discoverOptimizations({ localRoot: LOCAL_SKILLS_ROOT });
+      const { todo, dropped } = triage({
+        suggestions: found.suggestions,
+        minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
+        seen: queue.seen,
+      });
+      // 账本视角的三段计数：没有草稿的 / 有 ready 草稿的 / 已经在磁盘上的
+      let ledgerView = { pending: 0, withDraft: 0, readyDrafts: 0, adopted: 0, generation: null };
+      try {
+        const raw = JSON.parse(fs.readFileSync(MNEMON_LEDGER, 'utf8'));
+        const sug = Array.isArray(raw.suggestions) ? raw.suggestions : [];
+        const drf = Array.isArray(raw.drafts) ? raw.drafts : [];
+        const readyBySuggestion = new Set(drf.filter((d) => d && d.status === 'ready' && d.suggestionId).map((d) => d.suggestionId));
+        const pending = sug.filter((s) => s && s.status === 'pending');
+        ledgerView = {
+          pending: pending.length,
+          withDraft: pending.filter((s) => readyBySuggestion.has(s.id)).length,
+          readyDrafts: drf.filter((d) => d && d.status === 'ready').length,
+          adopted: sug.filter((s) => s && s.status === 'adopted').length,
+          generation: typeof raw.generation === 'number' ? raw.generation : null,
+        };
+      } catch {
+        /* 账本读不到就返回零值，面板不报错 */
+      }
+      json(res, 200, {
+        ok: true,
+        ledgerView,
+        // 手动触发那一轮的运行态：面板靠这两个字段显示「在跑 / 上次结果」
+        running: optimizeRun.running,
+        startedAt: optimizeRun.startedAt,
+        finishedAt: optimizeRun.finishedAt,
+        lastReport: optimizeRun.lastReport,
+        lastError: optimizeRun.lastError,
+        enabled: state.skills.mnemonOptimize !== false,
+        minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
+        queue: {
+          file: '~/.mnemon/skills/external-drafts.json',
+          generation: queue.generation,
+          waiting: queue.items.filter((x) => x.status === 'waiting-draft').length,
+          done: queue.items.filter((x) => x.status === 'done').length,
+          seen: queue.seen.length,
+          items: queue.items.slice(-40),
+        },
+        ledger: { suggestions: found.suggestions.length, readyDrafts: found.drafts.length },
+        todo: todo.map((x) => ({ skillName: x.skillName, action: x.action, priority: x.priority, reason: x.reason })),
+        dropped,
+      });
+    },
+
+    /**
+     * 只审核不落地：把暂存区里的草稿过一遍机械审核，看哪些能通过。
+     * 用来在真正落地前先看一眼。
+     */
+    'POST /skills/optimize/audit': async (req, res) => {
+      const body = await readJson(req).catch(() => ({}));
+      const stageDir = body.stageDir || process.env.DSH_SYNC_STAGE_DIR || 'C:/DSH-Work/mnemon-drafts/stage';
+      const state = loadState();
+      const queue = readQueue();
+      const found = discoverOptimizations({ localRoot: LOCAL_SKILLS_ROOT });
+      const { todo } = triage({
+        suggestions: found.suggestions,
+        minConfidence: Number(state.skills.mnemonMinConfidence) || 0.7,
+        seen: queue.seen,
+      });
+
+      const rows = [];
+      for (const item of todo) {
+        const file = `${stageDir}/${item.skillName}/SKILL.md`;
+        if (!fs.existsSync(file)) {
+          rows.push({ skillName: item.skillName, action: item.action, staged: false, ok: null, problems: [] });
+          continue;
+        }
+        const text = fs.readFileSync(file, 'utf8');
+        const audit = auditDraft({ text, name: item.skillName, isUpdate: item.action === 'update', localRoot: LOCAL_SKILLS_ROOT });
+        rows.push({ skillName: item.skillName, action: item.action, staged: true, ok: audit.ok, problems: audit.problems, info: audit.info });
+      }
+      json(res, 200, { ok: true, stageDir, rows });
+    },
+
+    /** 执行拉取（母版 → 本地）+ 移除母版已删的。 */
+    'POST /skills/pull': async (req, res) => {
+      const state = loadState();
+      const master = state.skills.masterRoot;
+      if (!master) {
+        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
+        return;
+      }
+      if (!fs.existsSync(master)) {
+        json(res, 400, { ok: false, error: `母版文件夹不存在或不可访问：${master}` });
+        return;
+      }
+
+      const plan = planSync({
+        masterRoot: master,
+        localRoot: LOCAL_SKILLS_ROOT,
+        modes: state.skills.modes || {},
+        ...judgeEvidence(master),
+      });
+      const stamp = makeStamp();
+
+      const pulled = applyPull({ items: plan.pull, localRoot: LOCAL_SKILLS_ROOT, stamp });
+
+      // 拉取落地后，被拉的和本来就一致的两侧都对齐了，一起登记成基线
+      const next = loadState();
+      const stamped = stampBaseline(
+        master,
+        [...plan.pull.map((x) => x.master), ...plan.same.map((x) => x.master)].filter(Boolean),
+        next.machineId,
+      );
+
+      next.skills.lastRunAt = Date.now();
+      next.skills.lastResult = {
+        pulled: pulled.pulled.length,
+        pendingPush: plan.push.length,
+        errors: pulled.errors.length,
+        lineage: stamped,
+      };
+      pushHistory(
+        next,
+        'skills',
+        `技能拉取：更新 ${pulled.pulled.length}、待推 ${plan.push.length}`,
+      );
+      saveState(next);
+
+      json(res, 200, {
+        ok: true,
+        pulled: pulled.pulled,
+        errors: pulled.errors,
+        pendingPush: plan.push.map((x) => ({ name: x.name, reason: x.reason, basis: x.basis || null })),
+        lineage: stamped,
+        stamp,
+      });
+    },
+
+    /** 把本地技能推回母版（用户确认后才调用）。支持覆盖，也支持新增本地独有技能。 */
+    'POST /skills/push': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const master = state.skills.masterRoot;
+      if (!master) {
+        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
+        return;
+      }
+      const names = Array.isArray(body.names) ? body.names.filter((n) => typeof n === 'string') : [];
+      if (!names.length) {
+        json(res, 400, { ok: false, error: '未选择任何技能' });
+        return;
+      }
+
+      const plan = planSync({
+        masterRoot: master,
+        localRoot: LOCAL_SKILLS_ROOT,
+        modes: state.skills.modes || {},
+        ...judgeEvidence(master),
+      });
+      const stamp = makeStamp();
+
+      // 覆盖项：本机更新的（同步属性，在 autoPush 里）+ 待裁决里被指名的
+      // 新增项：localOnly（用户显式指名才推）
+      // 注意 autoPush 也要算进来——否则「本机更新」这条在面板上点「推送」
+      // 会报「没有可推送的变更」。
+      const overwrites = [...plan.autoPush, ...plan.push].filter((x) => names.includes(x.name));
+      const creates = plan.localOnly
+        .filter((x) => names.includes(x.name))
+        .map((x) => ({ name: x.name, action: 'create', local: x.local, master: null }));
+      const items = [...overwrites, ...creates];
+
+      if (!items.length) {
+        json(res, 400, { ok: false, error: '选中的技能当前没有可推送的变更' });
+        return;
+      }
+
+      const backRoot = path.join(master, '_backup');
+      const out = applyPush({ items, masterRoot: master, backRoot, stamp });
+
+      // 每一次实际写入都留记录
+      const audit = appendMasterChanges(
+        out.pushed.map((p) => ({
+          skill: p.name,
+          operation: p.operation,
+          detail: p.operation === '覆盖' ? `旧版备份于 _backup/${p.name}.${stamp}` : '母版此前无此技能',
+        })),
+        {
+          masterRoot: master,
+          machineId: state.machineId,
+          machineName: state.machineName,
+          trigger: '用户授权',
+        },
+      );
+
+      const next = loadState();
+      // 推送落地后母版就是本机这一份，登记成新基线
+      const stamped = stampBaseline(
+        master,
+        out.pushed.map((p) => items.find((i) => i.name === p.name)).filter(Boolean).map((i) => i.local).filter(Boolean),
+        next.machineId,
+      );
+      pushHistory(
+        next,
+        'skills',
+        `技能推送：覆盖 ${out.pushed.filter((p) => p.operation === '覆盖').length}、新增 ${
+          out.pushed.filter((p) => p.operation === '新增').length
+        }`,
+      );
+      saveState(next);
+
+      json(res, 200, {
+        ok: true,
+        pushed: out.pushed,
+        errors: out.errors,
+        backupRoot: backRoot,
+        stamp,
+        lineage: stamped,
+        changelog: {
+          path: audit.written[0]?.path || changelogPath(master),
+          written: audit.written.length,
+          failed: audit.failed,
+        },
+      });
+    },
+
+    /** 读取母版修改记录。 */
+    'POST /skills/changelog': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const master = state.skills.masterRoot;
+      if (!master) {
+        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
+        return;
+      }
+      const limit = Number(body.limit) > 0 ? Math.min(Math.floor(Number(body.limit)), 200) : 30;
+      const log = readChangelog(master, limit);
+      json(res, 200, { ok: true, ...log });
+    },
+
+    /** 技能列表：合并母版与本机，带单机属性。 */
+    'POST /skills/list': async (req, res) => {
+      const state = loadState();
+      const master = state.skills.masterRoot;
+      if (!master) {
+        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
+        return;
+      }
+      if (!fs.existsSync(master)) {
+        json(res, 400, { ok: false, error: `母版文件夹不存在或不可访问：${master}` });
+        return;
+      }
+
+      const modes = state.skills.modes || {};
+      const m = scanSkills(master);
+      const l = scanSkills(LOCAL_SKILLS_ROOT);
+      const names = new Set([...m.keys(), ...l.keys()]);
+      const { lineage, mnemonLedger, history } = judgeEvidence(master);
+
+      const items = [...names].sort().map((name) => {
+        const mm = m.get(name);
+        const ll = l.get(name);
+        const mode = resolveMode(name, modes, m, l);
+        let status;
+        if (mm && !ll) status = mode === 'master' ? 'master-only' : 'missing-local';
+        else if (!mm && ll) status = 'local-only';
+        else status = mm.treeHash === ll.treeHash ? 'same' : 'diff';
+
+        // 内容不同时顺便给出「谁更新」的结论，前端不用再自己算
+        let verdict = null;
+        let basis = null;
+        let hint = '';
+        let diff = null;
+        if (status === 'diff') {
+          const j = judgeUpdate({ name, master: mm, local: ll, record: lineage[name], ledger: mnemonLedger, history });
+          verdict = j.verdict;
+          basis = j.basis;
+          hint = j.detail;
+          diff = diffSummary(mm.text, ll.text);
+        }
+
+        return {
+          name,
+          mode,
+          explicit: Object.prototype.hasOwnProperty.call(modes, name),
+          status,
+          verdict,
+          basis,
+          hint,
+          diff,
+          masterVersion: (mm && mm.version) || '',
+          localVersion: (ll && ll.version) || '',
+          inMaster: !!mm,
+          inLocal: !!ll,
+        };
+      });
+
+      json(res, 200, { ok: true, masterRoot: master, localRoot: LOCAL_SKILLS_ROOT, items });
+    },
+
+    /** 切换单机属性，并执行对应的实质动作（删母版 / 删本机 / 推送）。 */
+    'POST /skills/mode': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const master = state.skills.masterRoot;
+      if (!master) {
+        json(res, 400, { ok: false, error: '尚未设置技能母版文件夹' });
+        return;
+      }
+      const mode = body.mode;
+      if (mode !== 'sync' && mode !== 'local' && mode !== 'master') {
+        json(res, 400, { ok: false, error: '属性只能是 sync / local / master' });
+        return;
+      }
+      const names = Array.isArray(body.names) ? body.names.filter((n) => typeof n === 'string' && n) : [];
+      if (!names.length) {
+        json(res, 400, { ok: false, error: '未选择任何技能' });
+        return;
+      }
+
+      const stamp = makeStamp();
+      const backRoot = path.join(master, '_backup');
+      const modes = state.skills.modes || {};
+      const m0 = scanSkills(master);
+      const l0 = scanSkills(LOCAL_SKILLS_ROOT);
+
+      const results = [];
+      const applied = [];
+
+      for (const name of names) {
+        const from = resolveMode(name, modes, m0, l0);
+        const out = applyModeChange({
+          name,
+          from,
+          to: mode,
+          masterRoot: master,
+          localRoot: LOCAL_SKILLS_ROOT,
+          backRoot,
+          stamp,
+        });
+        results.push(out);
+        if (out.ok) applied.push({ name, mode });
+      }
+
+      // 只有成功的才落属性
+      const next = loadState();
+      for (const a of applied) next.skills.modes[a.name] = a.mode;
+      const auditItems = results.flatMap((r) => (r.ok && r.audit ? r.audit : []));
+      if (applied.length) {
+        pushHistory(next, 'skills', `技能属性：${applied.length} 个改为「${MODE_LABEL[mode]}」`);
+      }
+      saveState(next);
+
+      // 对母版的实际改动写审计
+      let audit = { written: 0, failed: [] };
+      if (auditItems.length) {
+        const w = appendMasterChanges(auditItems, {
+          masterRoot: master,
+          machineId: next.machineId,
+          machineName: next.machineName,
+          trigger: '用户授权',
+        });
+        audit = { written: w.written.length, failed: w.failed, path: w.written[0] && w.written[0].path };
+      }
+
+      json(res, 200, {
+        ok: true,
+        mode,
+        results,
+        applied: applied.length,
+        failed: results.filter((r) => !r.ok).length,
+        audit,
+      });
+    },
+
+    /** 技能同步配置。 */
+    'POST /skills/config': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const skills = { ...state.skills };
+
+      if (typeof body.masterRoot === 'string') {
+        const p = body.masterRoot.trim();
+        skills.masterRoot = p ? normSlash(p) : '';
+        // 设置路径时就把记录文件准备好，用户能立刻看到
+        if (skills.masterRoot && fs.existsSync(skills.masterRoot)) {
+          try {
+            ensureChangelog(skills.masterRoot);
+          } catch {
+            /* 母版只读时建不了，不影响后续 */
+          }
+        }
+      }
+      if (typeof body.enabled === 'boolean') skills.enabled = body.enabled;
+      // 记忆插件技能优化自动落地：默认开，显式传 false 才关
+      if (typeof body.mnemonAuto === 'boolean') skills.mnemonAuto = body.mnemonAuto;
+      // 优化闭环（发现 → 判断 → 入队 → 审核 → 通过）：默认开
+      if (typeof body.mnemonOptimize === 'boolean') skills.mnemonOptimize = body.mnemonOptimize;
+      if (body.mnemonMinConfidence !== undefined) {
+        const n = Number(body.mnemonMinConfidence);
+        if (!Number.isFinite(n) || n < 0 || n > 1) {
+          json(res, 400, { ok: false, error: '置信度门槛应在 0 到 1 之间' });
+          return;
+        }
+        skills.mnemonMinConfidence = n;
+      }
+      if (body.intervalMinutes !== undefined) {
+        const n = Number(body.intervalMinutes);
+        if (!Number.isFinite(n) || n < 1 || n > 10080) {
+          json(res, 400, { ok: false, error: '间隔应为 1–10080 之间的整数（分钟）' });
+          return;
+        }
+        skills.intervalMinutes = Math.floor(n);
+      }
+      state.skills = skills;
+      saveState(state);
+      json(res, 200, { ok: true, skills: state.skills, localRoot: LOCAL_SKILLS_ROOT });
+    },
+    /** 插件清单同步的配置：开关与插件库根目录。 */
+    'POST /plugins/config': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const next = { ...state.plugins };
+      if (typeof body.enabled === 'boolean') next.enabled = body.enabled;
+      if (typeof body.libraryRoot === 'string') {
+        const p = body.libraryRoot.trim();
+        next.libraryRoot = p ? normSlash(p) : '';
+        // 填了就必须是已存在的目录：不存在的路径建出来也是空的，同步一定失败
+        if (next.libraryRoot && !fs.existsSync(next.libraryRoot)) {
+          json(res, 400, { ok: false, error: `插件库目录不存在：${next.libraryRoot}` });
+          return;
+        }
+      }
+      state.plugins = next;
+      saveState(state);
+      json(res, 200, { ok: true, plugins: state.plugins });
+    },
+
+    /** 插件清单快照：我的特征文件夹 + 他人清单（只读，扫盘）。 */
+    'GET /plugins': async (req, res) => {
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const snap = shareSnapshot({
+        config: { libraryRoot: state.plugins.libraryRoot },
+        machineId,
+        machineHash: state.machineHash,
+        machineName: state.machineName,
+        publishedNames: Array.isArray(state.plugins.publishedNames) ? state.plugins.publishedNames : [],
+      });
+      json(res, 200, {
+        ok: true,
+        plugins: { ...state.plugins, effectiveRoot: pluginsLibraryRoot({ libraryRoot: state.plugins.libraryRoot }) },
+        share: snap,
+      });
+    },
+
+    /** 立即同步一次我的特征文件夹，并重新汇集他人清单。 */
+    'POST /plugins/sync': async (req, res) => {
+      if (typeof deps.syncPlugins !== 'function') {
+        json(res, 400, { ok: false, error: '宿主未提供清单同步能力' });
+        return;
+      }
+      const result = await deps.syncPlugins({ reason: '手动' });
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      json(res, 200, {
+        ok: result.ok !== false,
+        result,
+        plugins: { ...state.plugins, effectiveRoot: pluginsLibraryRoot({ libraryRoot: state.plugins.libraryRoot }) },
+        share: shareSnapshot({
+          config: { libraryRoot: state.plugins.libraryRoot },
+          machineId,
+          machineHash: state.machineHash,
+          machineName: state.machineName,
+          publishedNames: [],
+        }),
+      });
+    },
+
+    /** 装他人清单里的一个插件（人工点选；只走联网拉取）。 */
+    'POST /plugins/install': async (req, res) => {
+      const body = await readJson(req);
+      const name = typeof body.name === 'string' ? body.name.trim() : '';
+      if (!name) {
+        json(res, 400, { ok: false, error: '缺少 name' });
+        return;
+      }
+      if (typeof deps.pluginInstall !== 'function') {
+        json(res, 400, { ok: false, error: '宿主未提供插件安装通道' });
+        return;
+      }
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const result = await installSharedPlugin({
+        config: { libraryRoot: state.plugins.libraryRoot },
+        machineId,
+        publishedNames: [],
+        name,
+        installSpec: deps.pluginInstall,
+        addToBundles: deps.addToBundles,
+        log,
+      });
+      pushHistory(state, {
+        kind: result.ok ? 'plugins-install' : 'plugins-install-failed',
+        detail: result.ok
+          ? `从共享装 ${name}：${result.message}`
+          : `从共享装 ${name} 失败：${result.message}`,
+      });
+      saveState(state);
+      json(res, result.ok ? 200 : 400, {
+        ok: result.ok,
+        result,
+        share: shareSnapshot({
+          config: { libraryRoot: state.plugins.libraryRoot },
+          machineId,
+          machineHash: state.machineHash,
+          machineName: state.machineName,
+          publishedNames: [],
+        }),
+      });
+    },
+
+    'POST /preview': async (req, res) => {
+      const body = await readJson(req);
+      const state = loadState();
+      const machineId = deps.machineId() || state.machineId;
+      const all = listWorkspaces();
+      const matched = pickWorkspaces(all, state.folders);
+      const chosen =
+        Array.isArray(body.workspaceIds) && body.workspaceIds.length
+          ? matched.filter((w) => body.workspaceIds.includes(w.id))
+          : matched;
+
+      const localIndex = scanLocalSessions();
+      const out = chosen.map((ws) => {
+        const plan = previewPull({ workspace: ws, machineId, localIndex });
+        return {
+          id: ws.id,
+          title: ws.title || ws.path,
+          path: ws.path,
+          plan,
+          counts: plan.reduce((acc, p) => {
+            acc[p.action] = (acc[p.action] || 0) + 1;
+            return acc;
+          }, {}),
+        };
+      });
+      json(res, 200, { ok: true, workspaces: out });
+    },
+  };
+
+  return {
+    prefix: API_PREFIX,
+    routes,
+    /** 供 webServer 注册的统一 handler。 */
+    handle: async (req, res) => {
+      const url = new URL(req.url || '/', 'http://localhost');
+      if (!url.pathname.startsWith(API_PREFIX)) {
+        json(res, 404, { ok: false, error: 'not found' });
+        return;
+      }
+      const sub = url.pathname.slice(API_PREFIX.length) || '/';
+      const key = `${req.method} ${sub}`;
+      const handler = routes[key];
+      if (!handler) {
+        json(res, 404, { ok: false, error: `no route ${key}` });
+        return;
+      }
+      try {
+        await handler(req, res);
+      } catch (err) {
+        json(res, 500, {
+          ok: false,
+          error: String(err && err.message ? err.message : err),
+        });
+      }
+    },
+  };
+}