@morehao/dsh-skills-console 0.3.7 → 0.4.0

package/lib/core/service.js

@@ -2,7 +2,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { StateReadOnlyError } from './state.js';
 import { contentHash } from './hash.js';
-import { ensureLink, inspectTarget, removeLink } from './links.js';
+import { inspectTarget, removeLink } from './links.js';
+import { exportSkills, unexportSkill } from './exporter.js';
+import { ensureMigrated } from './migrations.js';
+import { findProjectRoot } from './paths.js';
+import { listRoots } from './roots.js';
+import { readShadowMarker, removeShadow } from './shadow.js';
+import { resolveVisibility } from './visibility.js';
 import { buildLedger, readLock, scanCanonical } from './inventory.js';
 import { readLockFile, updateLock } from './lock.js';
 import { readBackup, restoreBackup, trashSkill } from './trash.js';
@@ -25,10 +31,12 @@ import { fetchAtomCommit, snapshotFromTarball } from './remote.js';
 const QUEUE_LIMIT = 8;
 
 export class ServiceError extends Error {
-  constructor(code, message, detail) {
+  constructor(code, message, detail, status = 400) {
     super(message);
     this.code = code;
     this.detail = detail;
+    // 路由默认按 400 返回；少数「能力缺失/状态冲突」用 409，调用方显式传入。
+    this.status = status;
   }
 }
 
@@ -53,6 +61,17 @@ function skillFileFailure(error) {
   return error;
 }
 
+/** 是我方写的 legacy 停用桩（真实目录 + marker）？删除体检时只放过这一类。 */
+function isLegacyStubDir(dirPath) {
+  try {
+    const stat = fs.lstatSync(dirPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) return false;
+    return readShadowMarker(dirPath) !== null;
+  } catch {
+    return false;
+  }
+}
+
 /** 路由参数里的技能名：在拼任何路径之前先校验，拒绝穿越/分隔符/控制字符。 */
 function assertSafeSkillName(name) {
   if (
@@ -202,6 +221,10 @@ export function createService({
   fetchImpl = fetch,
   visibleProvider = async () => ({ skills: [], complete: true }),
   workspacesProvider = async () => [],
+  /** 启停写完后让每个 live agent 的 policy provider 失效（宿主下次 list 重新收集）。 */
+  invalidatePolicies = async () => {},
+  /** `{ available, liveAgents, registered, errors[] }`；没有 provider 时启停必须 409。 */
+  policyStatus = () => ({ available: false, liveAgents: 0, registered: 0, errors: [] }),
 }) {
   const enqueue = createQueue(logger);
   const tokenOf = (env.GITHUB_TOKEN || env.GH_TOKEN) || null;
@@ -250,49 +273,43 @@ export function createService({
     return registry.detected();
   }
 
-  function defaultTargets(current) {
-    const targets = ['dsh-global'];
-    // null = 老语义「所有探测到的 Agent」；数组 = 用户在「自动接入」里勾选的那些
-    const selected = current.settings.autoLinkTargets ?? null;
-    for (const target of detectedTargets()) {
-      if (target.kind !== 'agent') continue;
-      if (selected === null || selected.includes(target.target)) targets.push(target.target);
-    }
-    return targets;
+  /**
+   * 新安装/更新时默认导出的目标。v2 起默认空：导出是逐 agent 的显式动作，
+   * 「装完就到处建链」正是 v1 那套「链接 = 可见性」的残留。
+   */
+  /**
+   * 这个 agent 需要导出吗？判据由注册表算好（`exportable`）：读共享根的不需要、
+   * DSH 自己的扫描根也不需要。`unknown` 仍然算「需要」——没验证过就按需要处理。
+   */
+  function needsExport(entry) {
+    return entry.exportable === true;
   }
 
-  /** 建链：逐条幂等，冲突跳过不覆盖，失败收集错误继续。 */
-  function linkSkill(name, targets, { scopeProjects = [], record = true } = {}) {
-    const created = [];
-    const skipped = [];
-    const failed = [];
-    const canonicalPath = path.join(paths.canonical, name);
-    if (!fs.existsSync(canonicalPath)) {
-      throw new ServiceError('error.skills.not-installed', `${name} 不在 canonical 里`);
-    }
+  function exportTargetList(current) {
+    const selected = Array.isArray(current.settings.exportTargets) ? current.settings.exportTargets : [];
+    if (selected.length === 0) return [];
+    const detected = new Set(
+      detectedTargets()
+        .filter((item) => needsExport(item))
+        .map((item) => item.target),
+    );
+    return selected.filter((target) => detected.has(target));
+  }
 
-    const resolved = [];
-    for (const target of targets) {
-      try {
-        resolved.push(registry.resolve(target));
-      } catch (error) {
-        failed.push({ target, reason: error.message });
-      }
-    }
-    // 作用范围非空 = 只写项目链，不写全局链（否则项目链没有额外效果，见 §4.6）
-    for (const root of scopeProjects) {
-      resolved.push(registry.resolve(`project:${root}`));
-    }
-    const effective = scopeProjects.length > 0 ? resolved.filter((item) => item.target !== 'dsh-global') : resolved;
-
-    for (const target of effective) {
-      const linkPath = path.join(target.dir, name);
-      const result = ensureLink({ linkPath, canonicalPath });
-      if (result.created) created.push({ target: target.target, linkPath, mode: result.mode });
-      else if (result.skipped) skipped.push({ target: target.target, linkPath, reason: result.state });
-      if (record) recordLink(name, target, linkPath, result.mode || 'relative', result.created);
-    }
-    return { created, skipped, failed };
+  /** 某条技能已记账的导出目标（更新后复验用；不看 settings，导出是逐技能的） */
+  function exportTargetsFor(skill) {
+    return [...new Set(state().exports.filter((item) => item.skill === skill).map((item) => item.target))];
+  }
+
+  /** 导出（建链）：逐条幂等，冲突跳过不覆盖，失败收集原因继续。 */
+  function exportSkill(name, targets, { record = true } = {}) {
+    return exportSkills({
+      paths,
+      registry,
+      name,
+      targets,
+      record: record ? (row) => recordExport(name, row) : () => {},
+    });
   }
 
   /**
@@ -484,23 +501,66 @@ export function createService({
     }
   }
 
-  function recordLink(name, target, linkPath, mode, created) {
+  /**
+   * 记账：只在链**确实存在且指向 canonical** 时写。
+   * `created: false` 但没记账 = 链是上一次运行/别人建的、我们刚接管，也要补记。
+   */
+  function recordExport(name, { target, agentDir, linkPath, mode }) {
     if (store.readOnly) return;
-    const existing = state().links.find((item) => item.skill === name && item.target === target.target);
-    if (existing) return;
-    if (!created) return;
+    if (state().exports.some((item) => item.skill === name && item.target === target)) return;
     store.update((draft) => {
-      draft.links.push({
+      if (draft.exports.some((item) => item.skill === name && item.target === target)) return;
+      draft.exports.push({
         skill: name,
-        target: target.target,
-        agentDir: target.dir,
+        target,
+        agentDir,
         linkPath,
-        mode,
+        mode: mode === 'junction' ? 'junction' : 'relative',
         createdAt: nowIso(),
       });
     });
   }
 
+  /** cwd → 项目根（最近含 .git 的祖先）。拿不到就返回 null：不能凭空造 project 扫描根。 */
+  function projectRootOf(cwd) {
+    if (!cwd || typeof cwd !== 'string') return null;
+    const start = path.resolve(cwd);
+    if (!fs.existsSync(start)) return null;
+    return findProjectRoot(start, fs.existsSync);
+  }
+
+  /**
+   * 本地策略隐藏的 canonical 目录：`enabled === false` 且目录真实存在。
+   * 与 provider 的条件发候选对齐——只有 canonical 是 native winner 时才会命中。
+   */
+  function policyHiddenPathsOf() {
+    const hidden = new Set();
+    if (!paths.canonicalScanned) return hidden;
+    for (const install of state().installs || []) {
+      if (!install || install.enabled !== false) continue;
+      const dir = path.join(paths.canonical, install.name);
+      try {
+        if (fs.statSync(dir).isDirectory()) hidden.add(dir);
+      } catch {
+        /* 真身不在：不隐藏（provider 也不会发候选） */
+      }
+    }
+    return hidden;
+  }
+
+  /** 组装一次可见性视图：扫根 + 合并宿主 snapshot 的 global 层 + 本地策略。 */
+  async function visibilityFor(cwd, { withHost = true } = {}) {
+    const projectRoot = projectRootOf(cwd);
+    const roots = listRoots({ paths, projectRoot });
+    const host = withHost ? await visibleSkills(cwd) : { skills: [], complete: true };
+    const resolved = resolveVisibility({
+      roots,
+      hostSkills: host.skills,
+      policyHiddenPaths: policyHiddenPathsOf(),
+    });
+    return { ...resolved, hostComplete: host.complete !== false, projectRoot };
+  }
+
   async function visibleSkills(cwd) {
     try {
       const snapshot = await visibleProvider(cwd);
@@ -531,8 +591,6 @@ export function createService({
     const ref = lockEntry?.ref || null;
     const subscriptionId = source ? snapshotId({ source, ref, subpath: null }) : null;
     const installedHash = fs.statSync(canonicalPath).isDirectory() ? contentHash(canonicalPath) : null;
-    const dshLink = path.join(paths.dshGlobalSkills, name);
-    const live = inspectTarget({ linkPath: dshLink, canonicalPath });
     return {
       name,
       subscriptionId,
@@ -540,8 +598,6 @@ export function createService({
       ref,
       skillPath: lockEntry?.skillPath || `${name}/SKILL.md`,
       installedHash,
-      // 之前由 CLI/别人建的 DSH 链，接管后要记成自己的（否则账本里一直是 managed-external）
-      link: live.state === 'managed-external' ? { target: 'dsh-global', agentDir: paths.dshGlobalSkills, linkPath: dshLink } : null,
     };
   }
 
@@ -570,22 +626,11 @@ export function createService({
           installedHash: record.installedHash,
           installedAt: nowIso(),
           updatedAt: nowIso(),
-          mode: 'on',
-          scopeProjects: [],
+          enabled: true,
           backup: null,
           adopted: true,
         });
       }
-      if (record.link && !draft.links.some((item) => item.skill === record.name && item.target === 'dsh-global')) {
-        draft.links.push({
-          skill: record.name,
-          target: record.link.target,
-          agentDir: record.link.agentDir,
-          linkPath: record.link.linkPath,
-          mode: 'relative',
-          createdAt: nowIso(),
-        });
-      }
     }
   }
 
@@ -621,27 +666,62 @@ export function createService({
       // 有写操作在跑时不要重读：否则会把队列里刚写完但尚未落盘的状态冲掉
       if (enqueue.pending() > 0) return store.state;
       store.load();
+      // v1 → v2 的文件侧迁移（删历史 DSH 链 / 剪悬空导出 / 补停用标记）。
+      // 幂等且带 manifest：中断后下次 load 接着做。
+      if (!store.readOnly && store.state.migration && store.state.migration.status !== 'done') {
+        try {
+          ensureMigrated({ paths, store, logger });
+        } catch (error) {
+          logger('state.migrate.failed', { message: error.message });
+        }
+      }
       return store.state;
     },
 
+    /** 供插件 apply 时主动跑一次迁移（不必等到第一个请求）。 */
+    ensureMigrated() {
+      return this.reloadState();
+    },
+
     async getState({ cwd, workspace } = {}) {
       const lock = readLock(paths);
       reconcileTracking(lock);
-      const visible = await visibleSkills(cwd);
-      const visibleNames = new Map(visible.skills.map((item) => [item.name, item.source || item.provider || 'unknown']));
-      const ledger = buildLedger({ paths, state: state(), registry, lock, visibleNames });
+      const visible = await visibilityFor(cwd);
+      const ledger = buildLedger({ paths, state: state(), registry, lock, visibility: visible });
       const capabilities = nativeCapabilities();
+      const rowByName = new Map(ledger.rows.map((row) => [row.name, row]));
+      const visibleList = [];
+      for (const [name, item] of visible.byName) {
+        if (!item.visible) continue;
+        const row = rowByName.get(name);
+        visibleList.push({
+          name,
+          description: row?.description ?? null,
+          source: item.winnerSource,
+          provider: item.hostOnly ? 'host' : 'filesystem',
+          path: item.path,
+          nameConflict: Boolean(item.nameConflict),
+          shadowedBy: item.shadowedBy || [],
+        });
+      }
       return {
         ok: true,
         readOnly: store.readOnly,
         readOnlyReason: store.problem,
+        // direct：canonical 就是 rank 500 的扫描根，装完即可见；
+        // unscanned：canonical 被挪到扫描根之外，本插件不提供可见性兜底（/diagnostics 会报出来）
+        mode: paths.canonicalScanned ? 'direct' : 'unscanned',
         settings: state().settings,
         agents: { all: registry.all(), detected: detectedTargets() },
         subscriptions: state().subscriptions,
         workspaces: await workspaceList(),
         installs: ledger.rows,
-        visible: visible.skills,
-        visibleComplete: visible.complete !== false,
+        exports: state().exports,
+        legacyShadows: state().legacyShadows,
+        roots: visible.roots,
+        visible: visibleList,
+        visibleComplete: visible.hostComplete && visible.complete,
+        visibleErrors: visible.errors,
         visibleOnly: ledger.visibleOnly,
         checks: state().checks,
         cli: capabilities,
@@ -649,9 +729,11 @@ export function createService({
           canonical: paths.canonical,
           lock: paths.lockFile,
           dshGlobal: paths.dshGlobalSkills,
+          userAgents: paths.userAgentsSkills,
           state: paths.stateFile,
         },
         cwd: cwd || null,
+        projectRoot: visible.projectRoot,
         workspace: workspace || null,
         scannedAt: ledger.scannedAt,
       };
@@ -661,7 +743,9 @@ export function createService({
       const capabilities = nativeCapabilities();
       const lock = readLock(paths);
       reconcileTracking(lock);
-      const rows = buildLedger({ paths, state: state(), registry, lock, visibleNames: new Map() }).rows;
+      // 诊断不传 cwd：只看 user 两个根，避免把某个项目目录的副本算成全局事实
+      const visible = await visibilityFor(null);
+      const rows = buildLedger({ paths, state: state(), registry, lock, visibility: visible }).rows;
       const mismatched = rows
         .filter((row) => row.managed && row.lockHash)
         .map((row) => ({
@@ -671,15 +755,60 @@ export function createService({
           paired: row.sourceType === 'github' ? /^[0-9a-f]{40}$/.test(row.lockHash) : true,
         }))
         .filter((item) => !item.paired);
+
+      const legacyShadows = state().legacyShadows || [];
+      const exportsRows = state().exports || [];
+      const policy = policyStatus() || {};
+      const drift = {
+        /** 账上有链、磁盘上没有（迁移会收缩，运行期只报告） */
+        exportsMissing: exportsRows.filter((row) => !row.linkPath || !fs.existsSync(row.linkPath)),
+        /** 迁移删不掉的旧停用桩；用户可手动处理，或在控制台点启用时再试 */
+        legacyShadows,
+        /** 说不该出现的组合：界面停用、模型仍可见（更靠前的同名副本赢了） */
+        disabledButVisible: state().installs.filter((item) => item.enabled === false && visible.byName.get(item.name)?.visible),
+        /** 界面启用、模型不可见（真身缺失，或同名停用技能排在前面）；自己声明 manual-only 的不算异常 */
+        enabledButHidden: state().installs.filter((item) => {
+          if (item.enabled === false) return false;
+          const view = visible.byName.get(item.name);
+          if (view?.visible) return false;
+          const canonical = path.join(paths.canonical, item.name);
+          const selfHidden = Boolean(view?.foreignHidden && view.winnerPath
+            && path.resolve(view.winnerPath) === path.resolve(canonical));
+          return !selfHidden;
+        }),
+      };
+
       return {
         ok: true,
         cli: capabilities,
+        mode: paths.canonicalScanned ? 'direct' : 'unscanned',
         lock: { present: lock.present, version: lock.version, entries: Object.keys(lock.skills || {}).length, problem: lock.problem },
-        canonical: { path: paths.canonical, entries: rows.length },
+        canonical: { path: paths.canonical, entries: rows.length, scanned: paths.canonicalScanned },
         paths,
+        roots: visible.roots,
+        // 环境层面的硬限制：canonical 不在任何 DSH 扫描根里时，装好的技能对 DSH 不可见。
+        // 这不是「还能补救」的状态，所以在诊断里明说，而不是静默假装支持。
+        warnings: paths.canonicalScanned
+          ? []
+          : [{
+              code: 'canonical-not-scanned',
+              path: paths.canonical,
+              message: `canonical ${paths.canonical} 不在 DSH 的扫描根里（DSH_AGENTS_HOME 被改过？），本插件不保证技能对 DSH 可见`,
+            }],
         hashMismatch: mismatched,
+        // 宿主 provider 能力与每个 live agent scope 的注册结果。
+        // 盲区（customSkillDirs / plugin runtime 技能）如实标出，不假装支持。
+        policy: {
+          available: Boolean(policy.available),
+          agents: policy.registered || 0,
+          liveAgents: policy.liveAgents || 0,
+          errors: policy.errors || [],
+          blindSpots: ['custom-dirs', 'plugin-skills'],
+        },
         installs: state().installs.length,
-        links: state().links.length,
+        exports: exportsRows.length,
+        legacyShadows: legacyShadows.length,
+        drift,
         subscriptions: state().subscriptions.length,
         backups: state().installs.filter((item) => item.backup).length,
       };
@@ -687,18 +816,26 @@ export function createService({
 
     async setSettings(patch) {
       assertWritable();
-      const detected = new Set(detectedTargets().filter((target) => target.kind === 'agent').map((target) => target.target));
+      // 读共享根的 agent 不进设置：存下来也永远不会建链（exporter 会跳过），
+      // 留着只会让「新安装时自动导出 · N」数出一个人人都看不见的 1。
+      const detected = new Set(detectedTargets().filter((target) => needsExport(target)).map((target) => target.target));
+      const onlyDetected = (list) => [
+        ...new Set((Array.isArray(list) ? list : []).filter((target) => typeof target === 'string' && detected.has(target))),
+      ];
       store.update((draft) => {
-        if (patch.autoLinkTargets === null) {
-          draft.settings.autoLinkTargets = null;
+        if (patch.exportTargets === null) {
+          draft.settings.exportTargets = [];
+        } else if (Array.isArray(patch.exportTargets)) {
+          draft.settings.exportTargets = onlyDetected(patch.exportTargets);
+        } else if (patch.autoLinkTargets === null) {
+          // v1 客户端兼容：`null` 原本表示「所有探测到的 Agent」，语义照搬成显式全导出
+          draft.settings.exportTargets = onlyDetected(detectedTargets().map((item) => item.target));
         } else if (Array.isArray(patch.autoLinkTargets)) {
-          // 只接受当前探测到的 Agent，避免把任意 target 字符串写进设置
-          draft.settings.autoLinkTargets = [
-            ...new Set(patch.autoLinkTargets.filter((target) => typeof target === 'string' && detected.has(target))),
-          ];
+          draft.settings.exportTargets = onlyDetected(patch.autoLinkTargets);
         } else if (typeof patch.autoLinkAgents === 'boolean') {
-          // 旧客户端兼容：true = 所有探测到的 Agent
-          draft.settings.autoLinkTargets = patch.autoLinkAgents ? null : [];
+          draft.settings.exportTargets = patch.autoLinkAgents
+            ? onlyDetected(detectedTargets().map((item) => item.target))
+            : [];
         }
         if (patch.placement === 'settings' || patch.placement === 'sidebar') {
           draft.settings.placement = patch.placement;
@@ -707,25 +844,38 @@ export function createService({
       return { ok: true, settings: state().settings };
     },
 
-    async setLinks({ skill, targets = [], action = 'add', scopeProjects = [] }) {
+    async setExports({ skill, targets = [], action = 'add' }) {
+      assertSafeSkillName(skill);
       assertWritable();
-      const install = store.findInstall(skill);
-      if (!install && action !== 'add') throw new ServiceError('error.skills.not-managed', `${skill} 没有安装记录`);
+      const canonicalPath = path.join(paths.canonical, skill);
+      const exists = fs.existsSync(canonicalPath);
       if (action === 'remove') {
+        const rows = state().exports.filter(
+          (item) => item.skill === skill && (targets.length === 0 || targets.includes(item.target)),
+        );
         const removed = [];
-        for (const target of targets) {
-          const resolved = registry.resolve(target);
-          const result = removeLink({ linkPath: path.join(resolved.dir, skill), canonicalPath: path.join(paths.canonical, skill) });
-          if (result.removed) removed.push({ target, linkPath: path.join(resolved.dir, skill) });
+        const failed = [];
+        for (const row of rows) {
+          const outcome = unexportSkill({ linkPath: row.linkPath, canonicalPath, name: skill, allowDangling: !exists });
+          if (outcome.removed || outcome.reason === 'absent') removed.push(row.target);
+          else failed.push({ target: row.target, reason: outcome.reason || null, linkPath: row.linkPath });
         }
-        if (!store.readOnly) {
-          store.update((draft) => {
-            draft.links = draft.links.filter((link) => !(link.skill === skill && targets.includes(link.target)));
-          });
-        }
-        return { ok: true, removed };
+        // 只清「真的删掉 / 本来就不存在」的记录：删链失败仍记账会把漂移重新长出来
+        store.update((draft) => {
+          draft.exports = draft.exports.filter((item) => !(item.skill === skill && removed.includes(item.target)));
+        });
+        logger('exports.remove', { skill, removed, failed: failed.length });
+        return { ok: true, action: 'remove', removed, failed };
       }
-      return { ok: true, ...linkSkill(skill, targets, { scopeProjects }) };
+      if (!exists) throw new ServiceError('error.skills.not-installed', `${skill} 不在 canonical 里`);
+      const result = exportSkill(skill, targets);
+      logger('exports.add', { skill, created: result.created.length, skipped: result.skipped.length, failed: result.failed.length });
+      return { ok: true, action: 'add', ...result };
+    },
+
+    /** @deprecated v2 起叫 `setExports`；`/links` 路由别名仍指到这里 */
+    async setLinks(args) {
+      return this.setExports(args);
     },
 
     /**
@@ -802,49 +952,125 @@ export function createService({
       };
     },
 
-    async setMode({ name, mode }) {
+    /**
+     * 停用 = 只写 state（由 policy provider 覆盖 canonical 候选）；启用 = 写 state 并清掉
+     * 可能残留的 legacy 停用桩。
+     *
+     * 四条不变量：
+     * - 不写/删 `~/.dsh/skills`（唯一例外：清理 旧版迁移残桩），不碰 canonical/lock；
+     * - 宿主没有 provider 能力（或所有 live agent 都注册失败）时 409，绝不写
+     *   「界面说停用、模型照样看见」的状态；
+     * - 项目级启停已移除（400）：项目副本优先，停用 canonical 不会隐藏项目副本；
+     * - 已经 on/off 时返回 `already`，不重复写 state。
+     */
+    async setMode({ name, mode, scope = 'user', projectRoot = null }) {
       assertSafeSkillName(name);
       assertWritable();
       if (mode !== 'on' && mode !== 'off') throw new ServiceError('error.skills.bad-mode', 'mode 只能是 on / off');
+      if (projectRoot || scope !== 'user') {
+        throw new ServiceError(
+          'error.skills.scope-unsupported',
+          '项目级启停已移除；项目副本优先，停用 canonical 不会隐藏项目副本',
+          { scope, projectRoot },
+          400,
+        );
+      }
       const install = store.findInstall(name);
       if (!install) throw new ServiceError('error.skills.not-managed', `${name} 没有安装记录`);
       return enqueue(`mode:${name}`, async () => {
-        const scopeProjects = install.scopeProjects || [];
+        const canonicalPath = path.join(paths.canonical, name);
+        // 在队列里重新读一次：并发两次 off/on 时不能拿入队前的快照判断「已经如此」。
+        const current = store.findInstall(name) || install;
+        const already = mode === 'off' ? current.enabled === false : current.enabled !== false;
+
         if (mode === 'off') {
-          // 只摘 DSH 侧链接（全局链 + 项目链），其他 Agent 与文件一律不动
-          const dshTargets = ['dsh-global', ...scopeProjects.map((root) => `project:${root}`)];
-          const removed = [];
-          for (const target of dshTargets) {
-            const resolved = registry.resolve(target);
-            const result = removeLink({
-              linkPath: path.join(resolved.dir, name),
-              canonicalPath: path.join(paths.canonical, name),
-              force: true,
+          if (already) return { ok: true, mode: 'off', enabled: false, policy: 'provider', already: true };
+          if (!fs.existsSync(canonicalPath)) {
+            if (fs.existsSync(`${canonicalPath}.md`)) {
+              throw new ServiceError(
+                'error.skills.unsupported',
+                `${name} 是平铺 .md 技能，本期不支持启停`,
+                { name, kind: 'file' },
+                400,
+              );
+            }
+            throw new ServiceError('error.skills.not-installed', `${name} 不在 canonical 里，没有可停用的真身`);
+          }
+          let isDir = false;
+          try {
+            isDir = fs.statSync(canonicalPath).isDirectory();
+          } catch {
+            isDir = false;
+          }
+          if (!isDir) {
+            throw new ServiceError(
+              'error.skills.unsupported',
+              `${name} 不是目录型技能，本期不支持启停`,
+              { name, kind: 'file' },
+              400,
+            );
+          }
+          const status = policyStatus() || {};
+          if (!status.available || (status.liveAgents > 0 && status.registered === 0)) {
+            logger('mode.off.rejected', {
+              name,
+              available: Boolean(status.available),
+              liveAgents: status.liveAgents || 0,
+              registered: status.registered || 0,
             });
-            if (result.removed) removed.push(target);
+            throw new ServiceError(
+              'error.skills.policy-unavailable',
+              '宿主没有可用的 skill provider 注册接口，停用无法保证生效',
+              {
+                available: Boolean(status.available),
+                liveAgents: status.liveAgents || 0,
+                registered: status.registered || 0,
+                errors: status.errors || [],
+              },
+              409,
+            );
           }
           store.update((draft) => {
             const row = draft.installs.find((item) => item.name === name);
-            if (row) row.mode = 'off';
-            draft.links = draft.links.filter(
-              (link) => !(link.skill === name && dshTargets.includes(link.target)),
-            );
+            if (row) row.enabled = false;
           });
-          logger('mode.off', { name, removed });
-          return { ok: true, mode: 'off', removed };
+          await invalidatePolicies();
+          logger('mode.off', { name, policy: 'provider' });
+          return { ok: true, mode: 'off', enabled: false, policy: 'provider' };
         }
 
-        const result = linkSkill(name, ['dsh-global'], { scopeProjects });
+        // 启用：先清掉 旧版留下的旧桩（只认本插件 marker）；删不掉就不改 enabled
+        const legacy = (state().legacyShadows || []).filter((row) => row.skill === name);
+        const removed = [];
+        const failed = [];
+        for (const row of legacy) {
+          const outcome = removeShadow({ stubPath: row.stubPath, name: row.skill });
+          if (outcome.removed || outcome.reason === 'absent') removed.push(row.stubPath);
+          else failed.push({ stubPath: row.stubPath, reason: outcome.reason || 'locked' });
+        }
+        if (failed.length > 0) {
+          throw new ServiceError(
+            'error.skills.shadow-locked',
+            `旧停用桩删不掉（${failed[0].reason}），技能仍是停用状态`,
+            { failed },
+            409,
+          );
+        }
+        if (already && removed.length === 0) {
+          return { ok: true, mode: 'on', enabled: true, policy: 'provider', already: true };
+        }
         store.update((draft) => {
           const row = draft.installs.find((item) => item.name === name);
-          if (row) row.mode = 'on';
+          if (row) row.enabled = true;
+          draft.legacyShadows = (draft.legacyShadows || []).filter((item) => item.skill !== name);
         });
-        logger('mode.on', { name, created: result.created.length });
-        return { ok: true, mode: 'on', ...result };
+        await invalidatePolicies();
+        logger('mode.on', { name, policy: 'provider', removedLegacy: removed.length });
+        return { ok: true, mode: 'on', enabled: true, policy: 'provider', ...(already ? { already: true } : {}) };
       });
     },
 
-    async install({ source, subscriptionId, skills = [], commit, targets, scopeProjects = [] }) {
+    async install({ source, subscriptionId, skills = [], commit, targets }) {
       assertWritable();
       await requireInstaller();
       const requested = (skills || []).filter(Boolean);
@@ -918,8 +1144,6 @@ export function createService({
             installedHash,
             installedAt: recordedAt,
             updatedAt: recordedAt,
-            mode: 'on',
-            scopeProjects: scopeProjects || [],
             backup: item.backup
               ? { key: item.backup, hash: item.backupHash || null, treeSha: item.backupTreeSha || null }
               : null,
@@ -933,7 +1157,8 @@ export function createService({
                 installedAt: draft.installs[index].installedAt || record.installedAt,
               };
             } else {
-              draft.installs.push(record);
+              // 重新安装不改变启停意图：装之前停用的，装完仍然停用
+              draft.installs.push({ ...record, enabled: true });
             }
           });
           installed.push({
@@ -946,10 +1171,11 @@ export function createService({
           });
         }
 
-        const linkTargets = Array.isArray(targets) && targets.length > 0 ? targets : defaultTargets(state());
+        // 导出是显式动作：默认一个都不建；请求里点名了才建
+        const exportTargets = Array.isArray(targets) && targets.length > 0 ? targets : exportTargetList(state());
         const linkResult = { created: [], skipped: [], failed: [] };
         for (const item of installed) {
-          const one = linkSkill(item.name, linkTargets, { scopeProjects });
+          const one = exportSkill(item.name, exportTargets);
           linkResult.created.push(...one.created);
           linkResult.skipped.push(...one.skipped);
           linkResult.failed.push(...one.failed);
@@ -976,11 +1202,26 @@ export function createService({
           throw new ServiceError('error.skills.not-found', `${name} 不在 canonical 里`);
         }
 
-        // ① 体检：只动自己建的链接；真实目录/外来链接先拦下（前端弹窗依赖 detail.conflicts）
+        // ① 体检：只动自己建的链接；真实目录/外来链接先拦下（前端弹窗依赖 detail.conflicts）。
+        // 顺手记下「此刻确认指向 canonical 的自家链」——真身删掉之后就没法再验了。
         const conflicts = [];
+        const ownLinks = [];
+        const legacyStubs = new Set((state().legacyShadows || []).map((item) => item.stubPath));
+        // 只体检「记账里有导出」的目标：别的 Agent 自己放的同名目录/链与我无关，
+        // 删除 canonical 也不会连带删掉它（例如 OpenCode 指向另一个仓库的 handoff）。
+        const recordedTargets = new Set(
+          (state().exports || []).filter((item) => item.skill === name).map((item) => item.target),
+        );
         for (const target of detectedTargets()) {
           const linkPath = path.join(target.dir, name);
+          // legacy 停用桩也是「真实目录」，但它就是我们要清掉的东西。
+          // 只跳过我方 marker 的真实目录：同路径若是软链，仍要交给体检判定，不能误删。
+          if (legacyStubs.has(linkPath) && isLegacyStubDir(linkPath)) continue;
           const live = inspectTarget({ linkPath, canonicalPath });
+          if (live.state === 'managed' || live.state === 'managed-external') {
+            ownLinks.push({ target: target.target, linkPath, state: live.state });
+          }
+          if (!recordedTargets.has(target.target)) continue;
           if (live.state === 'real') conflicts.push({ target: target.target, label: target.label, linkPath, reason: 'real' });
           if (live.state === 'foreign-link' && !live.broken) {
             conflicts.push({ target: target.target, label: target.label, linkPath, reason: 'foreign-link' });
@@ -989,7 +1230,7 @@ export function createService({
         if (conflicts.length > 0) {
           throw new ServiceError(
             'error.skills.remove-conflict',
-            `${conflicts.map((item) => item.label).join('、')} 里有不是本插件创建的 ${name}，继续会连带删掉它`,
+            `${conflicts.map((item) => item.label).join('、')} 里的 ${name} 不是本插件创建的，删除已停下；先处理它再重试`,
             { conflicts },
           );
         }
@@ -1024,22 +1265,34 @@ export function createService({
           };
         }
 
-        // ④ 清自家链接
+        // ④ 清自家导出链：只删 ① 里验证过「指向 canonical」的那些，不按 force 乱扫
         const cleaned = [];
-        for (const link of state().links.filter((item) => item.skill === name)) {
-          const outcome = removeLink({ linkPath: link.linkPath, canonicalPath, force: true });
-          if (outcome.removed) cleaned.push(link.linkPath);
+        for (const item of ownLinks) {
+          const outcome = removeLink({ linkPath: item.linkPath, canonicalPath, force: true });
+          if (outcome.removed) cleaned.push(item.linkPath);
+        }
+
+        // ⑤ 清 legacy 停用桩：不带它走，删除后会留一个「看不见也不存在」的幽灵目录。
+        // 失败只记报告，不阻塞删除（真身已经删了，强留桩没有意义）。
+        const legacyResults = [];
+        for (const row of (state().legacyShadows || []).filter((item) => item.skill === name)) {
+          const outcome = removeShadow({ stubPath: row.stubPath, name });
+          legacyResults.push({ stubPath: row.stubPath, ...outcome });
+          if (!outcome.removed && outcome.reason !== 'absent') {
+            logger('remove.legacy-shadow.kept', { name, stubPath: row.stubPath, reason: outcome.reason || null });
+          }
         }
 
-        // ⑤ 清记账
+        // ⑥ 清记账
         store.update((draft) => {
           draft.installs = draft.installs.filter((item) => item.name !== name);
-          draft.links = draft.links.filter((item) => item.skill !== name);
+          draft.exports = draft.exports.filter((item) => item.skill !== name);
+          draft.legacyShadows = (draft.legacyShadows || []).filter((item) => item.skill !== name);
           delete draft.checks[name];
         });
 
-        logger('remove', { name, trash: trash.key });
-        return { ok: true, name, trash: trash.key, removedLinks: cleaned };
+        logger('remove', { name, trash: trash.key, legacyShadows: legacyResults.length });
+        return { ok: true, name, trash: trash.key, removedLinks: cleaned, removedLegacyShadows: legacyResults };
       });
     },
 
@@ -1471,8 +1724,9 @@ export function createService({
           };
         });
 
-        // 复验软链：更新重建的是目录，链接理论上不受影响，断一条就补一条
-        const relinked = linkSkill(name, ['dsh-global'], { scopeProjects: install.scopeProjects || [] });
+        // 更新重建的是 canonical 目录：导出链按原目标复验补建。`enabled` 保持不变——
+        // 停用期间更新，模型仍然看不到新正文，直到启用（不再需要刷新任何桩的 hash）。
+        const relinked = exportSkill(name, exportTargetsFor(name));
         logger('updates.apply', { name, from: plan.fromCommit, to: plan.toCommit, backup: item.backup || null });
         return {
           ok: true,