ygc-dsh-sync 1.2.0 → 1.2.2

package/lib/core.js

@@ -1,484 +1,484 @@
-/**
- * 基础层：机器标识、projectKey 编码、路径前缀匹配、写权限边界、状态持久化。
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import crypto from 'node:crypto';
-
-export const STATE_DIR = path.join(os.homedir(), '.dsh', 'storages');
-
-/**
- * 插件状态文件。
- *
- * 默认 ~/.dsh/storages/sync-backup.json。允许用 DSH_SYNC_STATE_FILE 覆盖——
- * 端到端测试必须写进临时目录：测试中途抛异常时恢复逻辑跑不到，
- * 会把假的母版路径留在真实 state 里，下次开机同步就对着空目录拉。
- */
-export const STATE_FILE = process.env.DSH_SYNC_STATE_FILE
-  ? path.resolve(process.env.DSH_SYNC_STATE_FILE)
-  : path.join(STATE_DIR, 'sync-backup.json');
-
-/**
- * 本机会话库根目录，惰性求值。
- *
- * 默认 ~/.dsh/sessions。允许用环境变量 DSH_SYNC_SESSIONS_ROOT 覆盖——
- * 这只为测试服务：端到端测试必须写进临时目录，否则会把伪造的会话
- * （同一个 header.id 出现在多个 projectKey 下）留在真实会话库里，
- * 让 sessionPersistence 抛 `duplicate JSONL session id`，整块工作区停摆。
- */
-export function sessionsRoot() {
-  const override = process.env.DSH_SYNC_SESSIONS_ROOT;
-  return override ? path.resolve(override) : path.join(os.homedir(), '.dsh', 'sessions');
-}
-
-/** 兼容写法：默认会话库根。读写会话请用 sessionsRoot()，别在模块顶层固化。 */
-export const SESSIONS_ROOT = path.join(os.homedir(), '.dsh', 'sessions');
-
-/** 工作区内的相对目录：会话文件夹 / 本机标识。本机只写自己那一格。 */
-export const TARGET_DIR_NAME = path.join('.dsh-sync', 'sessions');
-
-/* ---------------------------------------------------------------- 机器标识 */
-
-/**
- * 生成一次性特征值。
- *
- * 语义：插件第一次安装时生成一个，之后永久固定，永不重算。
- * 用随机字节而不是主机名 / MachineGuid 复算，这样换主机名、
- * 注册表读不到、甚至重装系统都不会让标识漂移。
- */
-export function generateHash() {
-  return crypto.randomBytes(6).toString('hex').slice(0, 12);
-}
-
-/** 当前主机名，只作为标识里的「名称」默认值，不参与哈希。 */
-export function hostName() {
-  return (os.hostname() || 'DSH').replace(/[^A-Za-z0-9_-]/g, '') || 'DSH';
-}
-
-/** 默认标识：<电脑名>-<特征值>。 */
-export function computeMachineId() {
-  return `${hostName()}-${generateHash()}`;
-}
-
-/* ------------------------------------------------------------- projectKey */
-
-/**
- * 由 header.cwd 推出 dsh 的会话目录名。
- * 规则：去掉前导分隔符 → `\` `/` 记作 `-`、`:` 丢弃、非 ASCII 记作 `~XXXX`
- * → 前后各加 `--`。
- */
-export function projectKeyOf(cwd) {
-  if (typeof cwd !== 'string' || cwd.length === 0) return null;
-  let s = cwd.replace(/^[\\/]+/, '');
-  let out = '';
-  for (let i = 0; i < s.length; i++) {
-    const code = s.charCodeAt(i);
-    const ch = s[i];
-    if (ch === '\\' || ch === '/') out += '-';
-    else if (ch === ':') continue;
-    else if (code < 0x80) out += ch;
-    else out += '~' + code.toString(16).toUpperCase().padStart(4, '0');
-  }
-  return `--${out}--`;
-}
-
-/* ----------------------------------------------------------------- 路径 */
-
-export function normSlash(p) {
-  return String(p).replace(/[\\/]+/g, '\\').replace(/\\+$/, '');
-}
-
-/** Windows 下大小写不敏感。 */
-export function pathKey(p) {
-  const n = normSlash(path.resolve(String(p)));
-  return process.platform === 'win32' ? n.toLowerCase() : n;
-}
-
-/** target 是否位于 prefix 之内（含相等）。 */
-export function isInside(prefix, target) {
-  const a = pathKey(prefix);
-  const b = pathKey(target);
-  if (a === b) return true;
-  return b.startsWith(a + '\\');
-}
-
-export function matchAnyPrefix(prefixes, target) {
-  for (const p of prefixes || []) {
-    if (!p) continue;
-    try {
-      if (isInside(p, target)) return p;
-    } catch {
-      /* 无效前缀跳过 */
-    }
-  }
-  return null;
-}
-
-/* ------------------------------------------------------------- 状态 */
-
-const DEFAULT_STATE = {
-  version: 2,
-  machineId: '',
-  machineHash: '',
-  machineName: '',
-  folders: [],
-  history: [],
-  lastBackupAt: 0,
-  lastPullAt: 0,
-  patrol: {
-    enabled: false,
-    /** 固定间隔：每 N 分钟巡检一次。 */
-    intervalMinutes: 30,
-    lastRunAt: 0,
-    lastResult: null,
-  },
-  skills: {
-    /** 母版根目录；空表示未配置。 */
-    masterRoot: '',
-    /** 自动拉取开关。 */
-    enabled: false,
-    /** 拉取间隔，默认 120 分钟。 */
-    intervalMinutes: 120,
-    /**
-     * 记忆插件（dsh-mnemon）技能优化自动落地；默认开。
-     * 关掉后草稿只在账本里堆着，等人到面板上逐个采纳。
-     */
-    mnemonAuto: true,
-    /**
-     * 记忆插件技能优化闭环（发现 → 判断 → 入队 → 审核 → 通过）；默认开。
-     * 关掉后只做草稿落地，不主动发现和处理新建议。
-     */
-    mnemonOptimize: true,
-    /** 分诊时的置信度门槛，低于它的建议不处理。 */
-    mnemonMinConfidence: 0.7,
-    /** 一轮优化闭环最多起草几条：模型调用要花时间，默认 6 条一批。 */
-    mnemonMaxDrafts: 6,
-    lastRunAt: 0,
-    lastResult: null,
-    /**
-     * 技能的单机属性（只存本机，不随母版同步）：技能名 → 'sync' | 'local' | 'master'
-     *   sync   同步（双向）
-     *   local  本机独属（母版不该有它）
-     *   master 母版有·本机不拉取
-     * 未列出的按自动：本机有母版没有 → local，其余 → sync。
-     */
-    modes: {},
-  },
-  /**
-   * 插件清单共享（特征文件夹）。1.0.0 从 ygc-dsh-plugin-autoupdate 迁移过来：
-   * 自动更新器只剩「更新已装插件」，清单共享归到同步插件这一侧。
-   *
-   * 规矩没变：只写 `插件库\<本机标识>\` 那一格；只存清单不存插件文件；
-   * 安装只能按 installSpec 联网拉。
-   */
-  plugins: {
-    /** 每轮巡检顺带同步一次我自己的特征文件夹。 */
-    enabled: true,
-    /** 插件库根目录；空 = 用默认 `D:\Ai工作空间\插件库`。 */
-    libraryRoot: '',
-    /** 上次同步时间与结果摘要。 */
-    lastSyncAt: 0,
-    lastResult: null,
-    lastError: '',
-  },
-  /**
-   * 本机特征文件夹的采纳状态（1.2.0 新增）。
-   *
-   * 判据永远是磁盘：`<工作区>/.dsh-sync/sessions/<本机标识>/` 存在 = 已采纳。
-   * 这里只记两样辅助信息：
-   *   decisions  人对某个路径的表态（adopt / decline），防止每轮重复问；
-   *   known      上一轮看到的工作区清单，用来判「本机新建」与「本机已删除」。
-   */
-  features: {
-    /** 1.2.0 首次运行是否已把「存量工作区」归过档：没有就一律问人，不自己建。 */
-    initialized: false,
-    /** 路径（小写归一）→ { action, path, at } */
-    decisions: {},
-    /** 工作区 id → 路径；只记已采纳过的 */
-    known: {},
-    lastPlanAt: 0,
-  },
-};
-
-export function loadState() {
-  let state = { ...DEFAULT_STATE };
-  /** 磁盘原始结构的标记。只记布尔量，不持有对象引用（避免与 state 共享后被就地改写）。 */
-  let diskHas = {
-    machineHash: false,
-    machineHashValue: '',
-    skills: false,
-    modes: false,
-    mnemonAuto: false,
-    patrol: false,
-    patrolInterval: false,
-    plugins: false,
-    features: false,
-  };
-  try {
-    const raw = fs.readFileSync(STATE_FILE, 'utf8');
-    const parsed = JSON.parse(raw);
-    diskHas = {
-      machineHash: typeof parsed.machineHash === 'string' && !!parsed.machineHash,
-      machineHashValue: parsed.machineHash || '',
-      skills: parsed.skills !== undefined,
-      modes: !!(parsed.skills && parsed.skills.modes !== undefined),
-      mnemonAuto: !!(parsed.skills && typeof parsed.skills.mnemonAuto === 'boolean'),
-      patrol: parsed.patrol !== undefined,
-      patrolInterval: !!(parsed.patrol && parsed.patrol.intervalMinutes !== undefined),
-      plugins: parsed.plugins !== undefined,
-      features: parsed.features !== undefined,
-    };
-    state = { ...state, ...parsed };
-    // skills 与 patrol 需要深拷贝，否则后续就地修改会改到 parsed
-    if (parsed.skills && typeof parsed.skills === 'object') {
-      state.skills = { ...parsed.skills };
-      if (parsed.skills.modes && typeof parsed.skills.modes === 'object') {
-        state.skills.modes = { ...parsed.skills.modes };
-      }
-    }
-    if (parsed.patrol && typeof parsed.patrol === 'object') state.patrol = { ...parsed.patrol };
-    if (parsed.plugins && typeof parsed.plugins === 'object') state.plugins = { ...parsed.plugins };
-    if (parsed.features && typeof parsed.features === 'object') {
-      state.features = {
-        initialized: parsed.features.initialized === true,
-        decisions: { ...(parsed.features.decisions || {}) },
-        known: { ...(parsed.features.known || {}) },
-        lastPlanAt: Number(parsed.features.lastPlanAt) || 0,
-      };
-    }
-    if (!Array.isArray(state.folders)) state.folders = [];
-    if (!Array.isArray(state.history)) state.history = [];
-  } catch {
-    /* 首次运行 */
-  }
-  // 老版本的 state 没有这些字段，补齐
-  if (!state.patrol || typeof state.patrol !== 'object') {
-    state.patrol = { ...DEFAULT_STATE.patrol };
-  }
-  // 旧版按「每日 HH:MM」调度；迁移成固定间隔，并避免留下无用字段
-  if (state.patrol.intervalMinutes === undefined || state.patrol.intervalMinutes === null) {
-    state.patrol.intervalMinutes = DEFAULT_STATE.patrol.intervalMinutes;
-  }
-  if (state.patrol.time !== undefined) delete state.patrol.time;
-  const iv = Number(state.patrol.intervalMinutes);
-  state.patrol.intervalMinutes =
-    Number.isFinite(iv) && iv >= 1 ? Math.min(Math.floor(iv), 1440) : DEFAULT_STATE.patrol.intervalMinutes;
-
-  // 技能同步配置
-  if (!state.skills || typeof state.skills !== 'object') {
-    state.skills = { ...DEFAULT_STATE.skills };
-  }
-  // 旧版字段清理
-  if (state.skills.syncedSkills !== undefined) delete state.skills.syncedSkills;
-  // 单机属性表：只接受三种合法值
-  if (!state.skills.modes || typeof state.skills.modes !== 'object' || Array.isArray(state.skills.modes)) {
-    state.skills.modes = {};
-  } else {
-    const clean = {};
-    for (const [k, v] of Object.entries(state.skills.modes)) {
-      if (typeof k !== 'string' || !k) continue;
-      if (v === 'sync' || v === 'local' || v === 'master') clean[k] = v;
-    }
-    state.skills.modes = clean;
-  }
-  const siv = Number(state.skills.intervalMinutes);
-  state.skills.intervalMinutes =
-    Number.isFinite(siv) && siv >= 1 ? Math.min(Math.floor(siv), 10080) : DEFAULT_STATE.skills.intervalMinutes;
-  // 老版本没有这个字段：补成默认值（开）
-  if (typeof state.skills.mnemonAuto !== 'boolean') {
-    state.skills.mnemonAuto = DEFAULT_STATE.skills.mnemonAuto;
-  }
-  if (typeof state.skills.mnemonOptimize !== 'boolean') {
-    state.skills.mnemonOptimize = DEFAULT_STATE.skills.mnemonOptimize;
-  }
-  if (!Number.isFinite(Number(state.skills.mnemonMinConfidence))) {
-    state.skills.mnemonMinConfidence = DEFAULT_STATE.skills.mnemonMinConfidence;
-  }
-  if (!Number.isFinite(Number(state.skills.mnemonMaxDrafts)) || Number(state.skills.mnemonMaxDrafts) < 0) {
-    state.skills.mnemonMaxDrafts = DEFAULT_STATE.skills.mnemonMaxDrafts;
-  }
-
-  // 插件清单同步配置（1.0.0 新增；老 state 没有这一段）
-  if (!state.plugins || typeof state.plugins !== 'object' || Array.isArray(state.plugins)) {
-    state.plugins = { ...DEFAULT_STATE.plugins };
-  }
-  // 默认开：迁移过来的老用户本来就在同步清单，不该因为升级而静默停止
-  state.plugins.enabled = state.plugins.enabled !== false;
-  state.plugins.libraryRoot =
-    typeof state.plugins.libraryRoot === 'string' ? state.plugins.libraryRoot.trim().slice(0, 400) : '';
-  state.plugins.lastSyncAt = Number(state.plugins.lastSyncAt) || 0;
-  state.plugins.lastResult =
-    state.plugins.lastResult && typeof state.plugins.lastResult === 'object' ? state.plugins.lastResult : null;
-  state.plugins.lastError = typeof state.plugins.lastError === 'string' ? state.plugins.lastError.slice(0, 800) : '';
-
-  // 本机特征文件夹的采纳状态（1.2.0 新增；老 state 没有这一段）
-  if (!state.features || typeof state.features !== 'object' || Array.isArray(state.features)) {
-    state.features = { initialized: false, decisions: {}, known: {}, lastPlanAt: 0 };
-  }
-  state.features.initialized = state.features.initialized === true;
-  if (!state.features.decisions || typeof state.features.decisions !== 'object' || Array.isArray(state.features.decisions)) {
-    state.features.decisions = {};
-  }
-  if (!state.features.known || typeof state.features.known !== 'object' || Array.isArray(state.features.known)) {
-    state.features.known = {};
-  }
-  state.features.lastPlanAt = Number(state.features.lastPlanAt) || 0;
-
-  if (!state.machineHashGeneratedAt) state.machineHashGeneratedAt = 0;
-
-  /**
-   * 特征值策略（按用户要求）：
-   * 插件第一次安装时生成一次，此后永久固定，绝不重算。
-   * 唯一的迁移来源是旧版本 state 里已经存在的哈希——那是既有目录名，
-   * 必须原样继承，否则已备份的会话就找不回来了。
-   */
-  const hashFromId = String(state.machineId || '').match(/-([0-9a-f]{6,})$/i);
-  const legacyHash = state.machineHash || (hashFromId ? hashFromId[1].toLowerCase() : '');
-  const nameFromId = String(state.machineId || '').match(/^(.*)-[0-9a-f]{6,}$/i);
-
-  if (!legacyHash) {
-    // 真正的首次安装：生成并固定
-    state.machineHash = generateHash();
-    state.machineHashGeneratedAt = Date.now();
-  } else if (state.machineHash !== legacyHash) {
-    // 继承旧值，不改写
-    state.machineHash = legacyHash;
-  }
-
-  // 名称：machineId 里的名称部分是既有目录名的真相，优先于独立字段
-  if (nameFromId) state.machineName = nameFromId[1];
-  else if (!state.machineName) state.machineName = hostName();
-  state.machineId = joinId(state.machineName, state.machineHash);
-
-  // 落盘条件（用磁盘原始标记判断，不能看 state——它已被就地改写）：
-  //   1) 首次安装 / 特征值继承
-  //   2) 文件不存在
-  //   3) 结构缺字段（老版本升级）——保证磁盘与内存一致
-  const needsWrite =
-    !diskHas.machineHash ||
-    diskHas.machineHashValue !== state.machineHash ||
-    !fs.existsSync(STATE_FILE) ||
-    !diskHas.skills ||
-    !diskHas.modes ||
-    !diskHas.mnemonAuto ||
-    !diskHas.patrol ||
-    !diskHas.patrolInterval ||
-    !diskHas.features;
-
-  if (needsWrite) saveState(state);
-  return state;
-}
-
-/** 拼标识：空名用哈希本身。与 patrol.js 的规则保持一致。 */
-export function joinId(name, hash) {
-  const n = String(name || '')
-    .trim()
-    .replace(/[\\/:*?"<>|\s]+/g, '_')
-    .replace(/^-+|-+$/g, '');
-  const h = String(hash || '').trim();
-  if (!h) return n;
-  return n ? `${n}-${h}` : h;
-}
-
-export function saveState(state) {
-  fs.mkdirSync(STATE_DIR, { recursive: true });
-  const tmp = STATE_FILE + '.tmp';
-  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
-  fs.renameSync(tmp, STATE_FILE);
-  return state;
-}
-
-export function pushHistory(state, kind, detail, limit = 60) {
-  state.history.unshift({ at: Date.now(), kind, detail });
-  if (state.history.length > limit) state.history.length = limit;
-}
-
-/* ------------------------------------------------------- 写权限边界 */
-
-export class WriteDeniedError extends Error {
-  constructor(target, reason) {
-    super(`拒绝写入：${target}（${reason}）`);
-    this.name = 'WriteDeniedError';
-    this.code = 'WRITE_DENIED';
-    this.target = target;
-  }
-}
-
-/** 本机允许写入的根：<工作区>/.dsh-sync/machine-sessions/<机器标识>/ */
-export function ownRoot(workspacePath, machineId) {
-  return path.join(normSlash(workspacePath), TARGET_DIR_NAME, machineId);
-}
-
-/**
- * 唯一写入口的守卫。所有写操作必须先过这里，
- * 目标不在 <工作区>/.dsh-sync/machine-sessions/<本机标识>/ 下就抛错。
- */
-export function assertWritable(target, { workspacePath, machineId }) {
-  if (!workspacePath) throw new WriteDeniedError(target, '缺少工作区路径');
-  if (!machineId) throw new WriteDeniedError(target, '缺少本机标识');
-  const allowed = ownRoot(workspacePath, machineId);
-  const key = pathKey(target);
-  const rootKey = pathKey(allowed);
-  if (!(key === rootKey || key.startsWith(rootKey + '\\'))) {
-    throw new WriteDeniedError(target, `只允许写 ${allowed}`);
-  }
-  return target;
-}
-
-/** 安全写文件：先写临时文件再 rename，且强制走写边界。 */
-export function writeGuarded(target, data, ctx) {
-  assertWritable(target, ctx);
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  const tmp = `${target}.tmp-${process.pid}`;
-  fs.writeFileSync(tmp, data);
-  fs.renameSync(tmp, target);
-  return target;
-}
-
-/* ------------------------------------------------------------ 小工具 */
-
-export function humanBytes(n) {
-  if (!Number.isFinite(n) || n < 0) return '0 B';
-  const units = ['B', 'KB', 'MB', 'GB'];
-  let v = n;
-  let i = 0;
-  while (v >= 1024 && i < units.length - 1) {
-    v /= 1024;
-    i++;
-  }
-  return `${v >= 100 || i === 0 ? Math.round(v) : v.toFixed(1)} ${units[i]}`;
-}
-
-export function safeStat(p) {
-  try {
-    return fs.statSync(p);
-  } catch {
-    return null;
-  }
-}
-
-export function listDirs(p) {
-  try {
-    return fs
-      .readdirSync(p, { withFileTypes: true })
-      .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
-      .map((d) => d.name);
-  } catch {
-    return [];
-  }
-}
-
-/** 找出某会话目录下的会话日志文件。 */
-export function findSessionLog(dir) {
-  let names;
-  try {
-    names = fs.readdirSync(dir);
-  } catch {
-    return null;
-  }
-  const exact = names.find((n) => /^session\..*\.zstd$/.test(n));
-  if (exact) return path.join(dir, exact);
-  const anyZstd = names.find((n) => n.endsWith('.zstd'));
-  return anyZstd ? path.join(dir, anyZstd) : null;
-}
+/**
+ * 基础层：机器标识、projectKey 编码、路径前缀匹配、写权限边界、状态持久化。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+export const STATE_DIR = path.join(os.homedir(), '.dsh', 'storages');
+
+/**
+ * 插件状态文件。
+ *
+ * 默认 ~/.dsh/storages/sync-backup.json。允许用 DSH_SYNC_STATE_FILE 覆盖——
+ * 端到端测试必须写进临时目录：测试中途抛异常时恢复逻辑跑不到，
+ * 会把假的母版路径留在真实 state 里，下次开机同步就对着空目录拉。
+ */
+export const STATE_FILE = process.env.DSH_SYNC_STATE_FILE
+  ? path.resolve(process.env.DSH_SYNC_STATE_FILE)
+  : path.join(STATE_DIR, 'sync-backup.json');
+
+/**
+ * 本机会话库根目录，惰性求值。
+ *
+ * 默认 ~/.dsh/sessions。允许用环境变量 DSH_SYNC_SESSIONS_ROOT 覆盖——
+ * 这只为测试服务：端到端测试必须写进临时目录，否则会把伪造的会话
+ * （同一个 header.id 出现在多个 projectKey 下）留在真实会话库里，
+ * 让 sessionPersistence 抛 `duplicate JSONL session id`，整块工作区停摆。
+ */
+export function sessionsRoot() {
+  const override = process.env.DSH_SYNC_SESSIONS_ROOT;
+  return override ? path.resolve(override) : path.join(os.homedir(), '.dsh', 'sessions');
+}
+
+/** 兼容写法：默认会话库根。读写会话请用 sessionsRoot()，别在模块顶层固化。 */
+export const SESSIONS_ROOT = path.join(os.homedir(), '.dsh', 'sessions');
+
+/** 工作区内的相对目录：会话文件夹 / 本机标识。本机只写自己那一格。 */
+export const TARGET_DIR_NAME = path.join('.dsh-sync', 'sessions');
+
+/* ---------------------------------------------------------------- 机器标识 */
+
+/**
+ * 生成一次性特征值。
+ *
+ * 语义：插件第一次安装时生成一个，之后永久固定，永不重算。
+ * 用随机字节而不是主机名 / MachineGuid 复算，这样换主机名、
+ * 注册表读不到、甚至重装系统都不会让标识漂移。
+ */
+export function generateHash() {
+  return crypto.randomBytes(6).toString('hex').slice(0, 12);
+}
+
+/** 当前主机名，只作为标识里的「名称」默认值，不参与哈希。 */
+export function hostName() {
+  return (os.hostname() || 'DSH').replace(/[^A-Za-z0-9_-]/g, '') || 'DSH';
+}
+
+/** 默认标识：<电脑名>-<特征值>。 */
+export function computeMachineId() {
+  return `${hostName()}-${generateHash()}`;
+}
+
+/* ------------------------------------------------------------- projectKey */
+
+/**
+ * 由 header.cwd 推出 dsh 的会话目录名。
+ * 规则：去掉前导分隔符 → `\` `/` 记作 `-`、`:` 丢弃、非 ASCII 记作 `~XXXX`
+ * → 前后各加 `--`。
+ */
+export function projectKeyOf(cwd) {
+  if (typeof cwd !== 'string' || cwd.length === 0) return null;
+  let s = cwd.replace(/^[\\/]+/, '');
+  let out = '';
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    const ch = s[i];
+    if (ch === '\\' || ch === '/') out += '-';
+    else if (ch === ':') continue;
+    else if (code < 0x80) out += ch;
+    else out += '~' + code.toString(16).toUpperCase().padStart(4, '0');
+  }
+  return `--${out}--`;
+}
+
+/* ----------------------------------------------------------------- 路径 */
+
+export function normSlash(p) {
+  return String(p).replace(/[\\/]+/g, '\\').replace(/\\+$/, '');
+}
+
+/** Windows 下大小写不敏感。 */
+export function pathKey(p) {
+  const n = normSlash(path.resolve(String(p)));
+  return process.platform === 'win32' ? n.toLowerCase() : n;
+}
+
+/** target 是否位于 prefix 之内（含相等）。 */
+export function isInside(prefix, target) {
+  const a = pathKey(prefix);
+  const b = pathKey(target);
+  if (a === b) return true;
+  return b.startsWith(a + '\\');
+}
+
+export function matchAnyPrefix(prefixes, target) {
+  for (const p of prefixes || []) {
+    if (!p) continue;
+    try {
+      if (isInside(p, target)) return p;
+    } catch {
+      /* 无效前缀跳过 */
+    }
+  }
+  return null;
+}
+
+/* ------------------------------------------------------------- 状态 */
+
+const DEFAULT_STATE = {
+  version: 2,
+  machineId: '',
+  machineHash: '',
+  machineName: '',
+  folders: [],
+  history: [],
+  lastBackupAt: 0,
+  lastPullAt: 0,
+  patrol: {
+    enabled: false,
+    /** 固定间隔：每 N 分钟巡检一次。 */
+    intervalMinutes: 30,
+    lastRunAt: 0,
+    lastResult: null,
+  },
+  skills: {
+    /** 母版根目录；空表示未配置。 */
+    masterRoot: '',
+    /** 自动拉取开关。 */
+    enabled: false,
+    /** 拉取间隔，默认 120 分钟。 */
+    intervalMinutes: 120,
+    /**
+     * 记忆插件（dsh-mnemon）技能优化自动落地；默认开。
+     * 关掉后草稿只在账本里堆着，等人到面板上逐个采纳。
+     */
+    mnemonAuto: true,
+    /**
+     * 记忆插件技能优化闭环（发现 → 判断 → 入队 → 审核 → 通过）；默认开。
+     * 关掉后只做草稿落地，不主动发现和处理新建议。
+     */
+    mnemonOptimize: true,
+    /** 分诊时的置信度门槛，低于它的建议不处理。 */
+    mnemonMinConfidence: 0.7,
+    /** 一轮优化闭环最多起草几条：模型调用要花时间，默认 6 条一批。 */
+    mnemonMaxDrafts: 6,
+    lastRunAt: 0,
+    lastResult: null,
+    /**
+     * 技能的单机属性（只存本机，不随母版同步）：技能名 → 'sync' | 'local' | 'master'
+     *   sync   同步（双向）
+     *   local  本机独属（母版不该有它）
+     *   master 母版有·本机不拉取
+     * 未列出的按自动：本机有母版没有 → local，其余 → sync。
+     */
+    modes: {},
+  },
+  /**
+   * 插件清单共享（特征文件夹）。1.0.0 从 ygc-dsh-plugin-autoupdate 迁移过来：
+   * 自动更新器只剩「更新已装插件」，清单共享归到同步插件这一侧。
+   *
+   * 规矩没变：只写 `插件库\<本机标识>\` 那一格；只存清单不存插件文件；
+   * 安装只能按 installSpec 联网拉。
+   */
+  plugins: {
+    /** 每轮巡检顺带同步一次我自己的特征文件夹。 */
+    enabled: true,
+    /** 插件库根目录；空 = 用默认 `D:\Ai工作空间\插件库`。 */
+    libraryRoot: '',
+    /** 上次同步时间与结果摘要。 */
+    lastSyncAt: 0,
+    lastResult: null,
+    lastError: '',
+  },
+  /**
+   * 本机特征文件夹的采纳状态（1.2.0 新增）。
+   *
+   * 判据永远是磁盘：`<工作区>/.dsh-sync/sessions/<本机标识>/` 存在 = 已采纳。
+   * 这里只记两样辅助信息：
+   *   decisions  人对某个路径的表态（adopt / decline），防止每轮重复问；
+   *   known      上一轮看到的工作区清单，用来判「本机新建」与「本机已删除」。
+   */
+  features: {
+    /** 1.2.0 首次运行是否已把「存量工作区」归过档：没有就一律问人，不自己建。 */
+    initialized: false,
+    /** 路径（小写归一）→ { action, path, at } */
+    decisions: {},
+    /** 工作区 id → 路径；只记已采纳过的 */
+    known: {},
+    lastPlanAt: 0,
+  },
+};
+
+export function loadState() {
+  let state = { ...DEFAULT_STATE };
+  /** 磁盘原始结构的标记。只记布尔量，不持有对象引用（避免与 state 共享后被就地改写）。 */
+  let diskHas = {
+    machineHash: false,
+    machineHashValue: '',
+    skills: false,
+    modes: false,
+    mnemonAuto: false,
+    patrol: false,
+    patrolInterval: false,
+    plugins: false,
+    features: false,
+  };
+  try {
+    const raw = fs.readFileSync(STATE_FILE, 'utf8');
+    const parsed = JSON.parse(raw);
+    diskHas = {
+      machineHash: typeof parsed.machineHash === 'string' && !!parsed.machineHash,
+      machineHashValue: parsed.machineHash || '',
+      skills: parsed.skills !== undefined,
+      modes: !!(parsed.skills && parsed.skills.modes !== undefined),
+      mnemonAuto: !!(parsed.skills && typeof parsed.skills.mnemonAuto === 'boolean'),
+      patrol: parsed.patrol !== undefined,
+      patrolInterval: !!(parsed.patrol && parsed.patrol.intervalMinutes !== undefined),
+      plugins: parsed.plugins !== undefined,
+      features: parsed.features !== undefined,
+    };
+    state = { ...state, ...parsed };
+    // skills 与 patrol 需要深拷贝，否则后续就地修改会改到 parsed
+    if (parsed.skills && typeof parsed.skills === 'object') {
+      state.skills = { ...parsed.skills };
+      if (parsed.skills.modes && typeof parsed.skills.modes === 'object') {
+        state.skills.modes = { ...parsed.skills.modes };
+      }
+    }
+    if (parsed.patrol && typeof parsed.patrol === 'object') state.patrol = { ...parsed.patrol };
+    if (parsed.plugins && typeof parsed.plugins === 'object') state.plugins = { ...parsed.plugins };
+    if (parsed.features && typeof parsed.features === 'object') {
+      state.features = {
+        initialized: parsed.features.initialized === true,
+        decisions: { ...(parsed.features.decisions || {}) },
+        known: { ...(parsed.features.known || {}) },
+        lastPlanAt: Number(parsed.features.lastPlanAt) || 0,
+      };
+    }
+    if (!Array.isArray(state.folders)) state.folders = [];
+    if (!Array.isArray(state.history)) state.history = [];
+  } catch {
+    /* 首次运行 */
+  }
+  // 老版本的 state 没有这些字段，补齐
+  if (!state.patrol || typeof state.patrol !== 'object') {
+    state.patrol = { ...DEFAULT_STATE.patrol };
+  }
+  // 旧版按「每日 HH:MM」调度；迁移成固定间隔，并避免留下无用字段
+  if (state.patrol.intervalMinutes === undefined || state.patrol.intervalMinutes === null) {
+    state.patrol.intervalMinutes = DEFAULT_STATE.patrol.intervalMinutes;
+  }
+  if (state.patrol.time !== undefined) delete state.patrol.time;
+  const iv = Number(state.patrol.intervalMinutes);
+  state.patrol.intervalMinutes =
+    Number.isFinite(iv) && iv >= 1 ? Math.min(Math.floor(iv), 1440) : DEFAULT_STATE.patrol.intervalMinutes;
+
+  // 技能同步配置
+  if (!state.skills || typeof state.skills !== 'object') {
+    state.skills = { ...DEFAULT_STATE.skills };
+  }
+  // 旧版字段清理
+  if (state.skills.syncedSkills !== undefined) delete state.skills.syncedSkills;
+  // 单机属性表：只接受三种合法值
+  if (!state.skills.modes || typeof state.skills.modes !== 'object' || Array.isArray(state.skills.modes)) {
+    state.skills.modes = {};
+  } else {
+    const clean = {};
+    for (const [k, v] of Object.entries(state.skills.modes)) {
+      if (typeof k !== 'string' || !k) continue;
+      if (v === 'sync' || v === 'local' || v === 'master') clean[k] = v;
+    }
+    state.skills.modes = clean;
+  }
+  const siv = Number(state.skills.intervalMinutes);
+  state.skills.intervalMinutes =
+    Number.isFinite(siv) && siv >= 1 ? Math.min(Math.floor(siv), 10080) : DEFAULT_STATE.skills.intervalMinutes;
+  // 老版本没有这个字段：补成默认值（开）
+  if (typeof state.skills.mnemonAuto !== 'boolean') {
+    state.skills.mnemonAuto = DEFAULT_STATE.skills.mnemonAuto;
+  }
+  if (typeof state.skills.mnemonOptimize !== 'boolean') {
+    state.skills.mnemonOptimize = DEFAULT_STATE.skills.mnemonOptimize;
+  }
+  if (!Number.isFinite(Number(state.skills.mnemonMinConfidence))) {
+    state.skills.mnemonMinConfidence = DEFAULT_STATE.skills.mnemonMinConfidence;
+  }
+  if (!Number.isFinite(Number(state.skills.mnemonMaxDrafts)) || Number(state.skills.mnemonMaxDrafts) < 0) {
+    state.skills.mnemonMaxDrafts = DEFAULT_STATE.skills.mnemonMaxDrafts;
+  }
+
+  // 插件清单同步配置（1.0.0 新增；老 state 没有这一段）
+  if (!state.plugins || typeof state.plugins !== 'object' || Array.isArray(state.plugins)) {
+    state.plugins = { ...DEFAULT_STATE.plugins };
+  }
+  // 默认开：迁移过来的老用户本来就在同步清单，不该因为升级而静默停止
+  state.plugins.enabled = state.plugins.enabled !== false;
+  state.plugins.libraryRoot =
+    typeof state.plugins.libraryRoot === 'string' ? state.plugins.libraryRoot.trim().slice(0, 400) : '';
+  state.plugins.lastSyncAt = Number(state.plugins.lastSyncAt) || 0;
+  state.plugins.lastResult =
+    state.plugins.lastResult && typeof state.plugins.lastResult === 'object' ? state.plugins.lastResult : null;
+  state.plugins.lastError = typeof state.plugins.lastError === 'string' ? state.plugins.lastError.slice(0, 800) : '';
+
+  // 本机特征文件夹的采纳状态（1.2.0 新增；老 state 没有这一段）
+  if (!state.features || typeof state.features !== 'object' || Array.isArray(state.features)) {
+    state.features = { initialized: false, decisions: {}, known: {}, lastPlanAt: 0 };
+  }
+  state.features.initialized = state.features.initialized === true;
+  if (!state.features.decisions || typeof state.features.decisions !== 'object' || Array.isArray(state.features.decisions)) {
+    state.features.decisions = {};
+  }
+  if (!state.features.known || typeof state.features.known !== 'object' || Array.isArray(state.features.known)) {
+    state.features.known = {};
+  }
+  state.features.lastPlanAt = Number(state.features.lastPlanAt) || 0;
+
+  if (!state.machineHashGeneratedAt) state.machineHashGeneratedAt = 0;
+
+  /**
+   * 特征值策略（按用户要求）：
+   * 插件第一次安装时生成一次，此后永久固定，绝不重算。
+   * 唯一的迁移来源是旧版本 state 里已经存在的哈希——那是既有目录名，
+   * 必须原样继承，否则已备份的会话就找不回来了。
+   */
+  const hashFromId = String(state.machineId || '').match(/-([0-9a-f]{6,})$/i);
+  const legacyHash = state.machineHash || (hashFromId ? hashFromId[1].toLowerCase() : '');
+  const nameFromId = String(state.machineId || '').match(/^(.*)-[0-9a-f]{6,}$/i);
+
+  if (!legacyHash) {
+    // 真正的首次安装：生成并固定
+    state.machineHash = generateHash();
+    state.machineHashGeneratedAt = Date.now();
+  } else if (state.machineHash !== legacyHash) {
+    // 继承旧值，不改写
+    state.machineHash = legacyHash;
+  }
+
+  // 名称：machineId 里的名称部分是既有目录名的真相，优先于独立字段
+  if (nameFromId) state.machineName = nameFromId[1];
+  else if (!state.machineName) state.machineName = hostName();
+  state.machineId = joinId(state.machineName, state.machineHash);
+
+  // 落盘条件（用磁盘原始标记判断，不能看 state——它已被就地改写）：
+  //   1) 首次安装 / 特征值继承
+  //   2) 文件不存在
+  //   3) 结构缺字段（老版本升级）——保证磁盘与内存一致
+  const needsWrite =
+    !diskHas.machineHash ||
+    diskHas.machineHashValue !== state.machineHash ||
+    !fs.existsSync(STATE_FILE) ||
+    !diskHas.skills ||
+    !diskHas.modes ||
+    !diskHas.mnemonAuto ||
+    !diskHas.patrol ||
+    !diskHas.patrolInterval ||
+    !diskHas.features;
+
+  if (needsWrite) saveState(state);
+  return state;
+}
+
+/** 拼标识：空名用哈希本身。与 patrol.js 的规则保持一致。 */
+export function joinId(name, hash) {
+  const n = String(name || '')
+    .trim()
+    .replace(/[\\/:*?"<>|\s]+/g, '_')
+    .replace(/^-+|-+$/g, '');
+  const h = String(hash || '').trim();
+  if (!h) return n;
+  return n ? `${n}-${h}` : h;
+}
+
+export function saveState(state) {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+  const tmp = STATE_FILE + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+  fs.renameSync(tmp, STATE_FILE);
+  return state;
+}
+
+export function pushHistory(state, kind, detail, limit = 60) {
+  state.history.unshift({ at: Date.now(), kind, detail });
+  if (state.history.length > limit) state.history.length = limit;
+}
+
+/* ------------------------------------------------------- 写权限边界 */
+
+export class WriteDeniedError extends Error {
+  constructor(target, reason) {
+    super(`拒绝写入：${target}（${reason}）`);
+    this.name = 'WriteDeniedError';
+    this.code = 'WRITE_DENIED';
+    this.target = target;
+  }
+}
+
+/** 本机允许写入的根：<工作区>/.dsh-sync/machine-sessions/<机器标识>/ */
+export function ownRoot(workspacePath, machineId) {
+  return path.join(normSlash(workspacePath), TARGET_DIR_NAME, machineId);
+}
+
+/**
+ * 唯一写入口的守卫。所有写操作必须先过这里，
+ * 目标不在 <工作区>/.dsh-sync/machine-sessions/<本机标识>/ 下就抛错。
+ */
+export function assertWritable(target, { workspacePath, machineId }) {
+  if (!workspacePath) throw new WriteDeniedError(target, '缺少工作区路径');
+  if (!machineId) throw new WriteDeniedError(target, '缺少本机标识');
+  const allowed = ownRoot(workspacePath, machineId);
+  const key = pathKey(target);
+  const rootKey = pathKey(allowed);
+  if (!(key === rootKey || key.startsWith(rootKey + '\\'))) {
+    throw new WriteDeniedError(target, `只允许写 ${allowed}`);
+  }
+  return target;
+}
+
+/** 安全写文件：先写临时文件再 rename，且强制走写边界。 */
+export function writeGuarded(target, data, ctx) {
+  assertWritable(target, ctx);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const tmp = `${target}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, target);
+  return target;
+}
+
+/* ------------------------------------------------------------ 小工具 */
+
+export function humanBytes(n) {
+  if (!Number.isFinite(n) || n < 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let v = n;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v >= 100 || i === 0 ? Math.round(v) : v.toFixed(1)} ${units[i]}`;
+}
+
+export function safeStat(p) {
+  try {
+    return fs.statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+export function listDirs(p) {
+  try {
+    return fs
+      .readdirSync(p, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+/** 找出某会话目录下的会话日志文件。 */
+export function findSessionLog(dir) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const exact = names.find((n) => /^session\..*\.zstd$/.test(n));
+  if (exact) return path.join(dir, exact);
+  const anyZstd = names.find((n) => n.endsWith('.zstd'));
+  return anyZstd ? path.join(dir, anyZstd) : null;
+}