@morehao/dsh-skills-console 0.3.7 → 0.4.0

package/lib/core/shadow.js

@@ -0,0 +1,195 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 停用标记（shadow）：在某个 DSH 扫描根里放一个**真实目录**，用官方 frontmatter 语义
+ * 把同名技能挡在模型目录之外。
+ *
+ * 为什么不是软链、也不是改 canonical：
+ * - 改 canonical 的 `SKILL.md` 会被安装/更新整份覆盖（F13），停用态会丢；
+ * - 软链在这里没有意义：扫描器只看目录内容，链接指向的仍是可用的 SKILL.md；
+ * - 停用必须是「可见性」事实，而不是「链接存在与否」的推断。
+ */
+
+export const SHADOW_MARKER = '.dsh-skills-console.json';
+export const SHADOW_TOOL = '@morehao/dsh-skills-console';
+export const SHADOW_DESCRIPTION = '已停用（由 DSH 技能控制台生成，请勿使用）';
+
+const MARKER_VERSION = 1;
+
+/** 停用态 SKILL.md：三个字段缺一不可，见 design §5.2。 */
+export function shadowSkillMd({ name, description = SHADOW_DESCRIPTION }) {
+  return [
+    '---',
+    `name: ${name}`,
+    `description: "${description}"`,
+    'disable-model-invocation: true',
+    'user-invocable: false',
+    '---',
+    '',
+    `# ${name}（已停用）`,
+    '',
+    '本目录由 DSH 技能控制台生成，用来在当前扫描根内隐藏同名技能。',
+    '技能真身仍在 `~/.agents/skills`，没有删除。',
+    '',
+    '恢复方式二选一：',
+    '- 在技能控制台里点「启用」；',
+    '- 直接删除本目录（会退化为「可见」，不会丢技能）。',
+    '',
+  ].join('\n');
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 读标记；不存在或不是本工具的标记都返回 null。 */
+export function readShadowMarker(dirPath) {
+  try {
+    const raw = fs.readFileSync(path.join(dirPath, SHADOW_MARKER), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!isPlainObject(parsed)) return null;
+    if (parsed.tool !== SHADOW_TOOL || parsed.kind !== 'shadow') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 判定一个路径是不是「我们建的停用标记」。
+ * - `absent`：什么都没有（可以建）；
+ * - `ours`：标记与 SKILL.md 都在（幂等）；
+ * - `broken`：标记在但 SKILL.md 丢了/被改（要修，不能当成功）；
+ * - `foreign`：同名目录是别的东西（真实技能 / 别人的目录）——不覆盖；
+ * - `link`：是软链（export 模式下的导出链），要先摘链才能建标记。
+ */
+export function inspectShadow(stubPath, name) {
+  let st;
+  try {
+    st = fs.lstatSync(stubPath);
+  } catch {
+    return { state: 'absent', stubPath };
+  }
+  if (st.isSymbolicLink()) return { state: 'link', stubPath };
+  if (!st.isDirectory()) return { state: 'foreign', stubPath, reason: 'not-a-directory' };
+
+  const marker = readShadowMarker(stubPath);
+  if (!marker) return { state: 'foreign', stubPath, reason: 'no-marker' };
+  if (marker.skill !== name) return { state: 'foreign', stubPath, reason: 'marker-name-mismatch' };
+
+  const skillMdPath = path.join(stubPath, 'SKILL.md');
+  let raw;
+  try {
+    raw = fs.readFileSync(skillMdPath, 'utf8');
+  } catch {
+    return { state: 'broken', stubPath, reason: 'skill-md-missing', marker };
+  }
+  if (!/^disable-model-invocation:\s*true\s*$/m.test(raw)) {
+    return { state: 'broken', stubPath, reason: 'flag-missing', marker };
+  }
+  if (!new RegExp(`^name:\\s*${name}\\s*$`, 'm').test(raw)) {
+    return { state: 'broken', stubPath, reason: 'name-mismatch', marker };
+  }
+  return { state: 'ours', stubPath, marker };
+}
+
+/**
+ * 建停用标记：同层临时目录写完再 rename，避免扫描器看到半个目录。
+ * `stubPath` 已存在且不是 ours 时直接拒绝（调用方转 409，带 detail）。
+ */
+export function createShadow({ stubPath, name, scope, canonicalHash = null, now = new Date().toISOString() }) {
+  const current = inspectShadow(stubPath, name);
+  if (current.state === 'ours') return { created: false, already: true, stubPath };
+  if (current.state !== 'absent') {
+    const error = new Error(`无法在 ${stubPath} 建停用标记：${current.state}${current.reason ? `/${current.reason}` : ''}`);
+    error.code = 'error.skills.shadow-conflict';
+    error.detail = { stubPath, state: current.state, reason: current.reason || null };
+    throw error;
+  }
+
+  const parent = path.dirname(stubPath);
+  fs.mkdirSync(parent, { recursive: true });
+  const staging = path.join(parent, `.shadow-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  fs.mkdirSync(staging, { recursive: false });
+  try {
+    fs.writeFileSync(path.join(staging, 'SKILL.md'), shadowSkillMd({ name }), 'utf8');
+    const marker = {
+      tool: SHADOW_TOOL,
+      kind: 'shadow',
+      version: MARKER_VERSION,
+      skill: name,
+      scope,
+      createdAt: now,
+      canonicalHash,
+      description: SHADOW_DESCRIPTION,
+    };
+    fs.writeFileSync(path.join(staging, SHADOW_MARKER), `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+    if (fs.existsSync(stubPath)) {
+      // 竞态：staging 期间有人抢先建了同名目录
+      const error = new Error(`无法在 ${stubPath} 建停用标记：已被占用`);
+      error.code = 'error.skills.shadow-conflict';
+      error.detail = { stubPath, state: 'race' };
+      throw error;
+    }
+    fs.renameSync(staging, stubPath);
+    return { created: true, stubPath, marker };
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  } finally {
+    if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+/**
+ * 删停用标记：先 rename 出扫描根（原子），再递归删。
+ * 删不掉就返回 removed:false 让调用方保留记账——**不许先清账再删**。
+ *
+ * v0.4.0 起只服务迁移与 legacy 清理：`foreign` / `link` 一律保留并报告，绝不替用户
+ * 拆掉别人的软链或真实目录。
+ */
+export function removeShadow({ stubPath, name }) {
+  const current = inspectShadow(stubPath, name);
+  if (current.state === 'absent') return { removed: false, reason: 'absent', stubPath };
+  if (current.state === 'foreign') return { removed: false, reason: 'not-managed', stubPath };
+  if (current.state === 'link') return { removed: false, reason: 'link', stubPath };
+
+  const parent = path.dirname(stubPath);
+  const graveyard = path.join(parent, `.shadow-trash-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    fs.renameSync(stubPath, graveyard);
+  } catch (error) {
+    // Windows 上被占用时 rename 会失败；退回原地删，删不掉就如实返回
+    try {
+      fs.rmSync(stubPath, { recursive: true, force: false });
+      return { removed: true, stubPath, via: 'rm' };
+    } catch (rmError) {
+      return { removed: false, reason: 'locked', stubPath, error: rmError.message || String(rmError) };
+    }
+  }
+  try {
+    fs.rmSync(graveyard, { recursive: true, force: true });
+  } catch {
+    /* 已移出扫描根，删不掉也不影响可见性 */
+  }
+  return { removed: true, stubPath };
+}
+
+/** 回收 `.shadow-*` 残骸（进程中断留下的 staging / trash 目录）。 */
+export function reapShadowLeftovers(dirPath) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const reaped = [];
+  for (const entry of entries) {
+    if (!entry.name.startsWith('.shadow-')) continue;
+    fs.rmSync(path.join(dirPath, entry.name), { recursive: true, force: true });
+    reaped.push(entry.name);
+  }
+  return reaped;
+}

package/lib/core/skill-md.js

@@ -2,11 +2,16 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * SKILL.md 的极简 frontmatter 解析：只取安装与清单需要的 `name` / `description`，
+ * SKILL.md 的极简 frontmatter 解析：取安装与清单需要的 `name` / `description`，
+ * 以及宿主用来决定「模型/用户能不能调用」的 `disable-model-invocation` / `user-invocable`，
  * 不引入 YAML 依赖。支持 `|` / `>` 块与单/双引号，解析失败按“没有 frontmatter”处理。
  *
- * Service（探测补名）与 Installer（落盘发现）共用同一份实现，避免两处规则漂移。
+ * Service（探测补名）、Installer（落盘发现）、roots（扫描可见性）与 policy provider
+ * 共用同一份实现，避免规则漂移。
  */
+const STRING_FIELDS = new Set(['name', 'description']);
+const BOOLEAN_FIELDS = new Set(['disable-model-invocation', 'user-invocable']);
+
 export function parseSkillFrontmatter(text) {
   const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(String(text || ''));
   if (!match) return {};
@@ -18,7 +23,7 @@ export function parseSkillFrontmatter(text) {
     const colon = line.indexOf(':');
     if (colon <= 0) continue;
     const key = line.slice(0, colon).trim();
-    if (key !== 'name' && key !== 'description') continue;
+    if (!STRING_FIELDS.has(key) && !BOOLEAN_FIELDS.has(key)) continue;
     let value = line.slice(colon + 1).trim();
     const block = /^([|>])[+-]?$/.exec(value);
     if (block) {
@@ -34,7 +39,9 @@ export function parseSkillFrontmatter(text) {
       value = value.slice(1, -1);
       if (quote === '"') value = value.replace(/\\"/g, '"').replace(/\\n/g, '\n');
     }
-    fields[key] = value.trim();
+    value = value.trim();
+    if (BOOLEAN_FIELDS.has(key)) fields[key] = value === 'true' ? true : value === 'false' ? false : value;
+    else fields[key] = value;
   }
   return fields;
 }
@@ -47,3 +54,15 @@ export function readSkillFrontmatter(skillDir) {
     return {};
   }
 }
+
+/**
+ * 读一份 SKILL.md：frontmatter 字段 + 去掉 frontmatter 的正文。
+ * 供 policy provider 的 `get` 使用；读不到就抛（调用方决定 fail-open 还是报错）。
+ */
+export function readSkillDocument(skillFile) {
+  const text = fs.readFileSync(skillFile, 'utf8');
+  const fields = parseSkillFrontmatter(text);
+  const match = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/.exec(text);
+  const body = match ? text.slice(match[0].length) : text;
+  return { fields, body, text };
+}

package/lib/core/state.js

@@ -1,17 +1,29 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-export const STATE_VERSION = 1;
+/**
+ * 状态版本史：
+ * - v1：`installs[].mode` + `installs[].scopeProjects` + 顶层 `links[]`（DSH 侧软链 = 可见性）。
+ * - v2：`installs[].enabled` + `exports[]`（只给其他 agent 的显式导出）+ `shadows[]`（DSH 扫描根里的停用标记）。
+ * - v3：`installs[].enabled` 是**唯一**启停开关；`shadows[]` 退休，`legacyShadows[]` 只放
+ *   迁移时删不掉的旧桩与 orphan（v0.4.0 起启停由每个 live agent scope 的 policy provider 负责）。
+ *
+ * 迁移分两步：`upgradeStateV1` / `upgradeStateV2` 只做**纯结构**改写（可测、无副作用），
+ * 删链/删旧桩/剪悬空导出这类要做 IO 的事在 `migrations.js` 里按 manifest 执行。
+ */
+export const STATE_VERSION = 3;
 
 export function emptyState() {
   return {
     version: STATE_VERSION,
-    settings: { autoLinkTargets: null, placement: 'settings' },
+    settings: { exportTargets: [], placement: 'settings' },
     agents: { custom: [], dismissed: [] },
     subscriptions: [],
     installs: [],
-    links: [],
+    exports: [],
+    legacyShadows: [],
     checks: {},
+    migration: null,
   };
 }
 
@@ -19,6 +31,219 @@ function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+function isoOrNull(value) {
+  return typeof value === 'string' && value ? value : null;
+}
+
+/**
+ * v1 的 `autoLinkTargets` → v2 的 `exportTargets`。
+ * - `null` / 缺失：v1 语义是「全部已装 agent」，v2 默认是「一个都不导出」——**不继承**，
+ *   否则升级会把「以前默认全都接」变成「以后默认全都导出」，与 v2 的设计前提相反。
+ * - 显式数组：用户点选过，原样继承（只保留 `agent:*`，其余目标在 v2 里已无意义）。
+ */
+function legacyExportTargets(settings) {
+  const raw = settings?.autoLinkTargets;
+  if (!Array.isArray(raw)) return [];
+  return [...new Set(raw.filter((target) => typeof target === 'string' && target.startsWith('agent:')))];
+}
+
+/**
+ * v1 → v2 的结构升级。**不读写任何文件**，只决定数据怎么摆：
+ * - `mode: 'off'` → `enabled: false`（v3 起只靠它启停，不再建标记）；
+ * - 顶层 `links[]` 拆成 `exports[]`（agent 链，保留）+ `migration.legacyLinks`（DSH 链/项目链，待删）；
+ * - `scopeProjects` 先挂在 `legacyScopeProjects` 上，migrations.js 处理完再删。
+ */
+export function upgradeStateV1(value, { now = new Date().toISOString() } = {}) {
+  const links = Array.isArray(value.links) ? value.links : [];
+  const exportsRows = [];
+  const legacyLinks = [];
+  for (const link of links) {
+    if (!isPlainObject(link) || typeof link.skill !== 'string' || typeof link.target !== 'string') continue;
+    const row = {
+      skill: link.skill,
+      target: link.target,
+      agentDir: typeof link.agentDir === 'string' ? link.agentDir : null,
+      linkPath: typeof link.linkPath === 'string' ? link.linkPath : null,
+      mode: link.mode === 'junction' ? 'junction' : 'relative',
+      createdAt: isoOrNull(link.createdAt) || now,
+    };
+    if (link.target.startsWith('agent:')) exportsRows.push(row);
+    else if (link.target === 'dsh-global' || link.target.startsWith('project:')) legacyLinks.push(row);
+  }
+
+  const installs = (Array.isArray(value.installs) ? value.installs : []).map((item) => {
+    const { mode, scopeProjects, ...rest } = isPlainObject(item) ? item : {};
+    const next = { ...rest, enabled: mode !== 'off' };
+    if (Array.isArray(scopeProjects) && scopeProjects.length > 0) next.legacyScopeProjects = scopeProjects;
+    return next;
+  });
+
+  const next = {
+    ...value,
+    version: 2,
+    settings: {
+      exportTargets: legacyExportTargets(value.settings),
+      placement: value.settings?.placement === 'sidebar' ? 'sidebar' : 'settings',
+    },
+    installs,
+    exports: exportsRows,
+    shadows: [],
+    migration: { from: 1, at: now, status: 'links-pending', legacyLinks },
+  };
+  // 拆完就删：v2/v3 不再有顶层 links[]，留着会被后续 upgrade 一层层带下去
+  delete next.links;
+  return next;
+}
+
+/**
+ * v2 → v3 的结构升级。**不读写任何文件**：
+ * - `shadows[]` 全部搬进 `legacyShadows[]` 当待办清单（`reason` 先写占位，文件侧迁移再改成
+ *   `locked` / `foreign` / `link` 或删除成功）；
+ * - `scope === 'user'` 且能找到同名 install → 同步 `enabled = false`（幂等）；
+ * - `scope === 'user'` 却找不到 install → 不凭空造 install，标 `orphan`；
+ * - `project:*` 只清理桩，**不**转成全局停用；
+ * - 删除 `shadows`，版本写 3；v1 遗留的链清理任务保留在 `migration` 里。
+ */
+export function upgradeStateV2(value, { now = new Date().toISOString() } = {}) {
+  const installs = Array.isArray(value.installs) ? value.installs.map((item) => ({ ...item })) : [];
+  const known = new Set(installs.map((item) => item.name));
+  const legacyShadows = [];
+  for (const row of Array.isArray(value.shadows) ? value.shadows : []) {
+    if (!isPlainObject(row) || typeof row.skill !== 'string' || typeof row.stubPath !== 'string') continue;
+    const scope = typeof row.scope === 'string' ? row.scope : 'user';
+    const at = isoOrNull(row.createdAt) || isoOrNull(row.at) || now;
+    let reason = 'pending';
+    if (scope.startsWith('project:')) {
+      reason = 'project-scope';
+    } else if (scope === 'user') {
+      if (known.has(row.skill)) {
+        const install = installs.find((item) => item.name === row.skill);
+        if (install) install.enabled = false;
+      } else {
+        reason = 'orphan';
+      }
+    }
+    legacyShadows.push({ skill: row.skill, stubPath: row.stubPath, reason, at });
+  }
+
+  const previous = isPlainObject(value.migration) ? value.migration : null;
+  const previousPending = Boolean(previous && previous.status !== 'done');
+  const pending = previousPending || legacyShadows.length > 0;
+  const migration = previousPending
+    ? { ...previous, to: 3, status: 'pending' }
+    : {
+        from: 2,
+        at: now,
+        to: 3,
+        status: pending ? 'pending' : 'done',
+        ...(pending ? {} : { completedAt: now }),
+      };
+
+  const next = {
+    ...value,
+    version: 3,
+    installs,
+    legacyShadows,
+    migration,
+  };
+  delete next.shadows;
+  return next;
+}
+
+function validateV3(state) {
+  for (const key of ['subscriptions', 'installs', 'exports', 'legacyShadows']) {
+    if (!Array.isArray(state[key])) return { ok: false, reason: `state.${key} is not an array` };
+  }
+  if (!isPlainObject(state.settings)) return { ok: false, reason: 'state.settings is not an object' };
+  if (!isPlainObject(state.agents)) return { ok: false, reason: 'state.agents is not an object' };
+  if (!isPlainObject(state.checks)) state.checks = {};
+  if (!Array.isArray(state.agents.custom)) state.agents.custom = [];
+  if (!Array.isArray(state.agents.dismissed)) state.agents.dismissed = [];
+  if (state.migration !== null && state.migration !== undefined && !isPlainObject(state.migration)) {
+    state.migration = null;
+  }
+  if (state.migration === undefined) state.migration = null;
+
+  const settings = state.settings;
+  if (!Array.isArray(settings.exportTargets)) {
+    // v1 的老字段在升级时已经丢掉；这里只兜手工编辑把类型写坏的情况。
+    settings.exportTargets = [];
+  }
+  settings.exportTargets = [
+    ...new Set(
+      settings.exportTargets.filter((item) => typeof item === 'string' && item.startsWith('agent:')),
+    ),
+  ];
+  if (settings.placement !== 'sidebar') settings.placement = 'settings';
+
+  for (const row of state.installs) {
+    if (!isPlainObject(row) || typeof row.name !== 'string' || !row.name) {
+      return { ok: false, reason: 'state.installs[] has a row without name' };
+    }
+    if (typeof row.enabled !== 'boolean') row.enabled = true;
+  }
+  for (const [key, fields] of [
+    ['exports', ['skill', 'target']],
+    ['legacyShadows', ['skill', 'stubPath']],
+  ]) {
+    for (const row of state[key]) {
+      if (!isPlainObject(row)) return { ok: false, reason: `state.${key}[] is not an object` };
+      for (const field of fields) {
+        if (typeof row[field] !== 'string' || !row[field]) {
+          return { ok: false, reason: `state.${key}[] is missing ${field}` };
+        }
+      }
+      if (key === 'legacyShadows') {
+        if (typeof row.reason !== 'string' || !row.reason) row.reason = 'pending';
+        if (typeof row.at !== 'string' || !row.at) row.at = new Date().toISOString();
+      }
+    }
+  }
+  return { ok: true, state };
+}
+
+export function validateState(value) {
+  if (!isPlainObject(value)) return { ok: false, reason: 'state is not an object' };
+  if (typeof value.version !== 'number' || !Number.isInteger(value.version)) {
+    return { ok: false, reason: 'state.version missing' };
+  }
+  if (value.version > STATE_VERSION) {
+    return { ok: false, reason: `state.version ${value.version} newer than ${STATE_VERSION}` };
+  }
+  if (value.version < 1) return { ok: false, reason: `state.version ${value.version} invalid` };
+
+  // v2 的旧桩清单在结构升级时会被搬进 legacyShadows；先按原结构校验，
+  // 避免「少字段的旧桩」被静默丢掉、状态却看起来正常。
+  if (value.version === 2 && value.shadows !== undefined && !Array.isArray(value.shadows)) {
+    return { ok: false, reason: 'state.shadows is not an array' };
+  }
+  if (value.version === 2 && Array.isArray(value.shadows)) {
+    for (const row of value.shadows) {
+      if (!isPlainObject(row) || typeof row.skill !== 'string' || !row.skill) {
+        return { ok: false, reason: 'state.shadows[] is missing skill' };
+      }
+      if (typeof row.stubPath !== 'string' || !row.stubPath) {
+        return { ok: false, reason: 'state.shadows[] is missing stubPath' };
+      }
+    }
+  }
+
+  let upgraded;
+  if (value.version === 1) upgraded = upgradeStateV2(upgradeStateV1(value));
+  else if (value.version === 2) upgraded = upgradeStateV2(value);
+  else upgraded = value;
+
+  const state = { ...emptyState(), ...upgraded };
+  delete state.shadows;
+  // v1 的顶层 links[] 在 v2 升级时已拆成 exports[] + migration.legacyLinks；
+  // 旧版本只搬家没删原字段，v3 里读到就剪掉，不再往外写。
+  delete state.links;
+  const verdict = validateV3(state);
+  if (!verdict.ok) return verdict;
+  state.version = STATE_VERSION;
+  return { ok: true, state: verdict.state };
+}
+
 /**
  * 状态读写。写入规则：全量读 → 校验 → 临时文件 → rename。
  * 损坏时**只读降级**，绝不 fail-open：宁可只读，也不要拿坏状态去覆盖链接。
@@ -70,12 +295,77 @@ export class StateStore {
     this.state = verdict.state;
     this.readOnly = false;
     this.problem = null;
+    const versionUpgrade = parsed.version !== STATE_VERSION;
+    // v1 迁移漏删的顶层 links：v3 不再有它，读到就写回干净状态，否则会一直留在文件里
+    const hasLegacyLinks = 'links' in parsed;
+    const legacyLinks = hasLegacyLinks ? parsed.links : null;
+    // 升级过的状态还没落盘：必须立刻写回，否则下一次 load 又按旧版升级一遍。
+    // 写回之前先留原文件副本——迁移是单向的，没有副本就没有回滚。
+    if (versionUpgrade || hasLegacyLinks) {
+      if (versionUpgrade) {
+        if (!this.backupRaw(raw, parsed.version)) {
+          this.readOnly = true;
+          this.problem = `state upgrade aborted: cannot back up v${parsed.version} state`;
+          return this.state;
+        }
+        // v1→v3 跨两级：额外留一份 v2 形状的快照，出问题能看到中间态。
+        if (parsed.version === 1) this.backupValue(upgradeStateV1(parsed), 2);
+      }
+      try {
+        this.save(this.state);
+        if (versionUpgrade) this.logger('state.upgraded', { from: parsed.version, to: STATE_VERSION });
+        else {
+          this.logger('state.links.pruned', {
+            count: Array.isArray(legacyLinks) ? legacyLinks.length : 0,
+          });
+        }
+      } catch (error) {
+        // 剪 v1 残留失败不该把整个状态打成只读：内存里已经是干净结构，下次写入会再试
+        if (versionUpgrade) {
+          this.readOnly = true;
+          this.problem = `state upgrade failed: ${error.message}`;
+          this.logger('state.upgrade.failed', { reason: this.problem });
+        } else {
+          this.logger('state.links.prune.failed', { message: error.message });
+        }
+      }
+    }
     return this.state;
   }
 
+  /** 迁移前把原文件整份留一份（`migrations/state-v<n>-<ts>.json`）。 */
+  backupRaw(raw, fromVersion) {
+    try {
+      fs.mkdirSync(this.paths.migrationsDir, { recursive: true });
+      const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+      fs.writeFileSync(path.join(this.paths.migrationsDir, `state-v${fromVersion}-${stamp}.json`), raw, 'utf8');
+      return true;
+    } catch (error) {
+      this.logger('state.backup.failed', { message: error.message });
+      return false;
+    }
+  }
+
+  /** 把升级中间态写一份副本（`migrations/state-v<n>-<ts>.json`）。 */
+  backupValue(value, version) {
+    try {
+      fs.mkdirSync(this.paths.migrationsDir, { recursive: true });
+      const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = path.join(this.paths.migrationsDir, `state-v${version}-${stamp}.json`);
+      fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+      return true;
+    } catch (error) {
+      this.logger('state.backup.failed', { message: error.message });
+      return false;
+    }
+  }
+
   save(next) {
     if (this.readOnly) throw new StateReadOnlyError(this.problem);
     const state = { ...next, version: STATE_VERSION };
+    delete state.shadows;
+    // v1 的顶层 links[] 已退休；任何调用方误带也不能再写回文件
+    delete state.links;
     fs.mkdirSync(this.paths.stateDir, { recursive: true });
     const tmp = path.join(this.paths.stateDir, `.state.${process.pid}.${Date.now()}.tmp`);
     fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
@@ -108,42 +398,3 @@ export class StateReadOnlyError extends Error {
     this.problem = problem;
   }
 }
-
-export function validateState(value) {
-  if (!isPlainObject(value)) return { ok: false, reason: 'state is not an object' };
-  if (typeof value.version !== 'number' || !Number.isInteger(value.version)) {
-    return { ok: false, reason: 'state.version missing' };
-  }
-  if (value.version > STATE_VERSION) {
-    return { ok: false, reason: `state.version ${value.version} newer than ${STATE_VERSION}` };
-  }
-  if (value.version < 1) return { ok: false, reason: `state.version ${value.version} invalid` };
-
-  const state = { ...emptyState(), ...value };
-  for (const key of ['subscriptions', 'installs', 'links']) {
-    if (!Array.isArray(state[key])) return { ok: false, reason: `state.${key} is not an array` };
-  }
-  if (!isPlainObject(state.settings)) return { ok: false, reason: 'state.settings is not an object' };
-  if (!isPlainObject(state.agents)) return { ok: false, reason: 'state.agents is not an object' };
-  if (!isPlainObject(state.checks)) state.checks = {};
-  if (!Array.isArray(state.agents.custom)) state.agents.custom = [];
-  if (!Array.isArray(state.agents.dismissed)) state.agents.dismissed = [];
-  // v1 的老状态只有布尔 autoLinkAgents：true 表示"所有探测到的 Agent"（null），false 表示一个都不选。
-  const settings = state.settings;
-  if (settings.autoLinkTargets === undefined) {
-    settings.autoLinkTargets = settings.autoLinkAgents === false ? [] : null;
-  }
-  if (settings.autoLinkTargets !== null && !Array.isArray(settings.autoLinkTargets)) {
-    settings.autoLinkTargets = null;
-  }
-  if (Array.isArray(settings.autoLinkTargets)) {
-    settings.autoLinkTargets = settings.autoLinkTargets.filter(
-      (item) => typeof item === 'string' && item.startsWith('agent:'),
-    );
-  }
-  delete settings.autoLinkAgents;
-  // 入口位置：settings = 设置页分区（默认），sidebar = 左侧栏独立面板。
-  if (settings.placement !== 'sidebar') settings.placement = 'settings';
-  state.version = STATE_VERSION;
-  return { ok: true, state };
-}