@morehao/dsh-skills-console 0.4.0 → 0.5.1

package/lib/core/service.js

@@ -13,6 +13,19 @@ import { buildLedger, readLock, scanCanonical } from './inventory.js';
 import { readLockFile, updateLock } from './lock.js';
 import { readBackup, restoreBackup, trashSkill } from './trash.js';
 import { parseSkillFrontmatter } from './skill-md.js';
+import {
+  InvocationError,
+  backupInvocation,
+  hashWithoutInvocation,
+  inspectPark,
+  parkSkill,
+  parseInvocation,
+  planManualRestore,
+  planManualWrite,
+  readSkillText,
+  unparkSkill,
+  writeFileAtomic,
+} from './invocation.js';
 import { readSkillFile, readSkillTree, resolveSkillRoot, SkillFileError } from './skill-files.js';
 import {
   checkSkill,
@@ -26,7 +39,17 @@ import {
   skillTreeSha,
   snapshotId,
 } from './updates.js';
-import { fetchAtomCommit, snapshotFromTarball } from './remote.js';
+import { fetchAtomCommit, fetchRemoteSkillMd, snapshotFromTarball } from './remote.js';
+import {
+  DEFAULT_INTRO_CONFIG,
+  contentFingerprint,
+  buildIntroPrompt,
+  normalizeIntroConfig,
+  runIntroCall,
+  introLang,
+  IntroError,
+  introEntry,
+} from './intro.js';
 
 const QUEUE_LIMIT = 8;
 
@@ -61,6 +84,28 @@ function skillFileFailure(error) {
   return error;
 }
 
+/** 调用策略层的文件事务错误 → 路由错误；保留 409 语义。 */
+function invocationFailure(error) {
+  if (error instanceof InvocationError) {
+    return new ServiceError(error.code, error.message, error.detail ?? null, error.status);
+  }
+  return error;
+}
+
+/**
+ * 客户端覆盖能力表：只承诺已确认的客户端，不写成「所有 Agent 都生效」。
+ * 读不到就返回空表（UI 只显示通用提示），不影响写路径。
+ */
+const INVOCATION_SUPPORT = (() => {
+  try {
+    const raw = fs.readFileSync(new URL('../invocation-support.json', import.meta.url), 'utf8');
+    const parsed = JSON.parse(raw);
+    return { generatedAt: parsed.generatedAt || null, note: parsed.note || null, clients: Array.isArray(parsed.clients) ? parsed.clients : [] };
+  } catch {
+    return { generatedAt: null, note: null, clients: [] };
+  }
+})();
+
 /** 是我方写的 legacy 停用桩（真实目录 + marker）？删除体检时只放过这一类。 */
 function isLegacyStubDir(dirPath) {
   try {
@@ -225,6 +270,14 @@ export function createService({
   invalidatePolicies = async () => {},
   /** `{ available, liveAgents, registered, errors[] }`；没有 provider 时启停必须 409。 */
   policyStatus = () => ({ available: false, liveAgents: 0, registered: 0, errors: [] }),
+  /** 技能介绍缓存（可丢）；缺省时介绍接口返回 501，其余功能不受影响。 */
+  introStore = null,
+  /** 归一化后的介绍配置（provider/model 可空，空则用宿主默认模型）。 */
+  introOptions = normalizeIntroConfig(DEFAULT_INTRO_CONFIG),
+  /** 宿主 `llm` 服务（`ctx.get('llm')`）；按需取，不能要求它在插件加载时已就绪。 */
+  getLlm = () => null,
+  /** 宿主 `agentDefaultModel.currentSelection()`；返回 `{ provider, model }` 或 null。 */
+  getDefaultModel = () => null,
 }) {
   const enqueue = createQueue(logger);
   const tokenOf = (env.GITHUB_TOKEN || env.GH_TOKEN) || null;
@@ -267,6 +320,203 @@ export function createService({
     return capabilities;
   }
 
+  // ---- 技能介绍（模型生成） -------------------------------------------------
+  // 全局只允许一个生成在跑：辅助调用不进 agent 的重试/限流体系，并发越高越容易撞 429。
+  // 在第一个 await 之前占位，避免两个请求同时通过检查。
+  let introInFlight = null;
+
+  /** `/state` 下发的介绍能力：前端据此决定按钮显隐与提示。 */
+  function introCapability() {
+    return {
+      enabled: Boolean(introOptions.enabled),
+      available: Boolean(introStore) && Boolean(getLlm()),
+      langs: ['zh', 'en'],
+      timeoutMs: introOptions.timeoutMs,
+    };
+  }
+
+  /** 介绍用的模型路由：显式配置 > 宿主默认模型；解析不出来就是「没有可用模型」。 */
+  function resolveIntroRoute() {
+    if (introOptions.provider && introOptions.model) {
+      return { provider: introOptions.provider, model: introOptions.model };
+    }
+    let selection = null;
+    try {
+      selection = getDefaultModel();
+    } catch (error) {
+      logger('intro.default-model.failed', { message: error?.message });
+      selection = null;
+    }
+    if (selection?.provider && selection?.model) {
+      return { provider: selection.provider, model: selection.model };
+    }
+    return null;
+  }
+
+  /** 读 SKILL.md（只读；根反查与路径校验沿用查看器那一层）。 */
+  async function readIntroSource(name) {
+    assertSafeSkillName(name);
+    try {
+      const root = await resolveSkillRoot(paths, name);
+      const file = await readSkillFile({ root: root.root, kind: root.kind });
+      return { root, file };
+    } catch (error) {
+      throw skillFileFailure(error);
+    }
+  }
+
+  /** 只列文件名（不发内容）：让模型知道技能还带哪些资料，不扩大数据外发面。 */
+  async function introFileNames(root, bodyRelPath) {
+    const names = new Set(bodyRelPath ? [bodyRelPath] : ['SKILL.md']);
+    try {
+      const tree = await readSkillTree({ root: root.root, kind: root.kind });
+      for (const item of tree.files) {
+        if (item.kind === 'file' && item.path) names.add(item.path);
+      }
+    } catch (error) {
+      logger('intro.files.failed', { message: error?.message });
+    }
+    return [...names].slice(0, 30);
+  }
+
+  /** 缓存条目 → 接口形状；`stale` 只表示 SKILL.md 的内容哈希对不上。 */
+  function publicIntro(entry, hash) {
+    return {
+      text: entry.text,
+      stale: Boolean(hash) && entry.hash !== hash,
+      generatedAt: entry.generatedAt,
+      provider: entry.provider,
+      model: entry.model,
+      truncated: Boolean(entry.truncated),
+      usage: entry.usage || null,
+    };
+  }
+
+  /**
+   * 订阅候选：按订阅 id + 条目名反查快照，`skillPath` 只从服务端状态取。
+   * 客户端只给 id 与名字，永远不能自带路径。
+   */
+  function remoteIntroTarget(subscriptionId, name) {
+    if (typeof subscriptionId !== 'string' || !subscriptionId || typeof name !== 'string' || !name) {
+      throw new ServiceError('error.skills.bad-request', '缺少订阅 id 或技能名', null, 400);
+    }
+    const subscriptions = Array.isArray(store.state?.subscriptions) ? store.state.subscriptions : [];
+    const subscription = subscriptions.find((item) => item.id === subscriptionId) || null;
+    if (!subscription) {
+      throw new ServiceError(
+        'error.skills.subscription-not-found',
+        '订阅不存在，可能已被取消',
+        { subscriptionId },
+        404,
+      );
+    }
+    const snapshot = subscription.snapshot || null;
+    const entry = (Array.isArray(snapshot?.entries) ? snapshot.entries : []).find((item) => item.name === name) || null;
+    if (!entry?.skillPath || !snapshot?.commit) {
+      throw new ServiceError(
+        'error.skills.intro-no-source',
+        '订阅快照里没有这个技能，请先点「检查更新」刷新快照',
+        { name },
+        409,
+      );
+    }
+    return {
+      subscription,
+      entry,
+      source: subscription.source,
+      commit: snapshot.commit,
+      skillPath: entry.skillPath,
+      description: typeof entry.description === 'string' ? entry.description : '',
+      cacheKey: `remote:${subscription.source}@${snapshot.commit}:${entry.skillPath}`,
+    };
+  }
+
+  /** 远端介绍没有「过期」概念：缓存 key 已经带 commit，换 commit 就是另一条。 */
+  function publicRemoteIntro(entry) {
+    return {
+      text: entry.text,
+      stale: false,
+      generatedAt: entry.generatedAt,
+      provider: entry.provider,
+      model: entry.model,
+      truncated: Boolean(entry.truncated),
+      usage: entry.usage || null,
+    };
+  }
+
+  function remoteIntroSourceFailure(error) {
+    const detail = { code: error?.code || null, status: error?.status ?? null, bytes: error?.bytes ?? null };
+    if (error?.code === 'intro-source-timeout') {
+      return new ServiceError('error.skills.intro-source-timeout', error.message, detail, 504);
+    }
+    if (error?.code === 'intro-source-too-large') {
+      return new ServiceError('error.skills.intro-source-too-large', error.message, detail, 413);
+    }
+    return new ServiceError('error.skills.intro-source', error?.message || '读不到远端的 SKILL.md', detail, 502);
+  }
+
+  /** 一次模型调用的统一超时：到点 abort，映射成 504（与用户取消区分）。 */
+  async function callIntroModel({ llm, route, prompt, signal }) {
+    let timedOut = false;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, introOptions.timeoutMs);
+    const combined = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
+    try {
+      return await runIntroCall({
+        llm,
+        route,
+        prompt,
+        maxOutputTokens: introOptions.maxOutputTokens,
+        signal: combined,
+      });
+    } catch (error) {
+      if (timedOut) {
+        throw new ServiceError(
+          'error.skills.intro-timeout',
+          `生成超时（${Math.round(introOptions.timeoutMs / 1000)} 秒），请重试`,
+          { timeoutMs: introOptions.timeoutMs },
+          504,
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** 全局单飞：辅助调用不进 agent 的重试/限流体系，并发越高越容易撞 429。 */
+  async function withIntroInFlight(meta, task) {
+    if (introInFlight) {
+      throw new ServiceError(
+        'error.skills.intro-busy',
+        '正在生成另一个技能介绍，请稍后再试',
+        introInFlight,
+        409,
+      );
+    }
+    const startedAt = Date.now();
+    introInFlight = { ...meta, startedAt };
+    try {
+      return await task(startedAt);
+    } catch (error) {
+      if (error instanceof IntroError) throw introFailure(error);
+      throw error;
+    } finally {
+      introInFlight = null;
+    }
+  }
+
+  /** 介绍层的异常统一转成路由能识别的 ServiceError（保留 429/413/504 语义）。 */
+  function introFailure(error) {
+    if (error instanceof IntroError) {
+      return new ServiceError(error.code, error.message, error.detail, error.status);
+    }
+    return error;
+  }
+
 
 
   function detectedTargets() {
@@ -656,6 +906,200 @@ export function createService({
     return records;
   }
 
+  function canonicalDir(name) {
+    return path.join(paths.canonical, name);
+  }
+
+  function skillKindOf(dir) {
+    try {
+      const stat = fs.lstatSync(dir);
+      if (stat.isSymbolicLink()) return 'symlink';
+      if (stat.isDirectory()) return 'dir';
+      return 'other';
+    } catch {
+      /* 继续看平铺 .md */
+    }
+    return fs.existsSync(`${dir}.md`) ? 'file' : 'missing';
+  }
+
+  function isParkedNow(name, install) {
+    return inspectPark(canonicalDir(name)).parked || install?.mode === 'hidden';
+  }
+
+  function assertNotParked(name, action) {
+    if (isParkedNow(name, store.findInstall(name))) {
+      throw new ServiceError(
+        'error.skills.parked',
+        `${name} 已完全停用；${action}前请先恢复。否则安装器会把 SKILL.md 写回来，界面却还以为停着`,
+        { name, action },
+        409,
+      );
+    }
+  }
+
+  function markDrift(name) {
+    if (store.readOnly) return;
+    try {
+      store.update((draft) => {
+        const row = draft.installs.find((item) => item.name === name);
+        if (!row?.manual) return;
+        row.manual = { ...row.manual, drift: true };
+      });
+    } catch (error) {
+      logger('invocation.drift.persist.failed', { name, message: error.message });
+    }
+  }
+
+  /**
+   * 更新 / 回滚 / 重装后重放「仅手动」。失败不谎报成功：把 manual.drift 置 true，
+   * 由 UI 标「需修复」；更新本身已经成功，不回滚正文。
+   */
+  function reapplyInvocation(name) {
+    const install = store.findInstall(name);
+    if (!install || install.mode !== 'manual' || install.hidden) return { ok: true, skipped: true };
+    const dir = canonicalDir(name);
+    let text;
+    try {
+      text = readSkillText(dir);
+    } catch (error) {
+      markDrift(name);
+      return { ok: false, code: error.code || 'error.skills.not-writable', message: error.message };
+    }
+    let parsed;
+    try {
+      parsed = parseInvocation(text);
+    } catch (error) {
+      markDrift(name);
+      return { ok: false, code: error.code || 'error.skills.unsupported', message: error.message };
+    }
+    // 只重放「缺失」；已经是 true 就当已生效。false / 其它值是被外部改过，
+    // 宁可标 drift 让用户看，也不覆盖作者或用户的编辑。
+    if (parsed.value !== 'absent' && parsed.value !== 'true') {
+      markDrift(name);
+      return { ok: false, code: 'error.skills.drift', message: '标记被改成非 true，未自动覆盖' };
+    }
+    let plan;
+    try {
+      plan = planManualWrite(text);
+    } catch (error) {
+      markDrift(name);
+      return { ok: false, code: error.code || 'error.skills.unsupported', message: error.message };
+    }
+    if (plan.author) {
+      // 这一行可能正是插件自己写的（状态里 origin=plugin）；不能把所有权误判给作者
+      if (install.manual?.origin === 'plugin') return { ok: true, origin: 'plugin', changed: false };
+      store.update((draft) => {
+        const row = draft.installs.find((item) => item.name === name);
+        if (!row) return;
+        row.manual = { origin: 'author', original: 'true', appliedAt: nowIso(), drift: false };
+      });
+      return { ok: true, origin: 'author', changed: false };
+    }
+    if (!plan.changed) return { ok: true, origin: 'plugin', changed: false };
+    try {
+      backupInvocation({ backupDir: paths.backupsDir, name, content: text });
+      writeFileAtomic(path.join(dir, 'SKILL.md'), plan.nextText);
+      store.update((draft) => {
+        const row = draft.installs.find((item) => item.name === name);
+        if (!row) return;
+        row.manual = { origin: 'plugin', original: plan.original, appliedAt: nowIso(), drift: false };
+      });
+      return { ok: true, origin: 'plugin', changed: true, original: plan.original };
+    } catch (error) {
+      markDrift(name);
+      return { ok: false, code: error.code || 'error.skills.write-failed', message: error.message };
+    }
+  }
+
+  /**
+   * 启动 reconcile：只处理 state 已经是 manual 的行。
+   * - 文件里已有 true：视为已生效（若是作者声明，状态改成 author）；
+   * - 文件里没有 / 是 false：重放（覆盖「更新成功但 reapply 前崩溃」的窗口）；
+   * - 作者声明但被外部删掉：只标 drift，绝不替作者写回。
+   */
+  function reconcileInvocations() {
+    if (store.readOnly) return [];
+    const reports = [];
+    for (const install of state().installs) {
+      if (install.mode !== 'manual' || install.hidden) continue;
+      let parsed;
+      try {
+        parsed = parseInvocation(readSkillText(canonicalDir(install.name)));
+      } catch (error) {
+        markDrift(install.name);
+        reports.push({ name: install.name, status: 'unreadable', message: error.message });
+        continue;
+      }
+      if (parsed.value === 'true') {
+        if (!install.manual) {
+          store.update((draft) => {
+            const row = draft.installs.find((item) => item.name === install.name);
+            if (row) row.manual = { origin: 'author', original: 'true', appliedAt: nowIso(), drift: false };
+          });
+        }
+        continue;
+      }
+      if (install.manual?.origin === 'author') {
+        markDrift(install.name);
+        reports.push({ name: install.name, status: 'author-marker-missing' });
+        continue;
+      }
+      const result = reapplyInvocation(install.name);
+      reports.push({ name: install.name, ...result });
+      if (!result.ok) logger('invocation.reconcile.failed', { name: install.name, message: result.message });
+    }
+    if (reports.length > 0) logger('invocation.reconcile', { reports });
+    return reports;
+  }
+
+  /**
+   * 「仅手动」文件事务：备份 → 原子写 → state；state 写失败把原文件写回去。
+   * 不在这里做「是否已经如此」的判断，调用方拿 `plan` 决定。
+   */
+  function commitManual({ name, dir, plan, text }) {
+    try {
+      backupInvocation({ backupDir: paths.backupsDir, name, content: text });
+    } catch (error) {
+      throw new InvocationError(
+        'error.skills.not-writable',
+        `无法备份 ${name} 的 SKILL.md：${error.message}`,
+        { name },
+        409,
+      );
+    }
+    writeFileAtomic(path.join(dir, 'SKILL.md'), plan.nextText);
+    try {
+      store.update((draft) => {
+        const row = draft.installs.find((item) => item.name === name);
+        if (!row) return;
+        row.mode = 'manual';
+        row.enabled = true;
+        delete row.legacy;
+        row.hidden = null;
+        row.manual = { origin: 'plugin', original: plan.original, appliedAt: nowIso(), drift: false };
+      });
+    } catch (error) {
+      try {
+        writeFileAtomic(path.join(dir, 'SKILL.md'), text);
+      } catch (rollbackError) {
+        logger('invocation.rollback.failed', { name, message: rollbackError.message });
+      }
+      throw error;
+    }
+  }
+
+  function commitAuthorManual(name) {
+    store.update((draft) => {
+      const row = draft.installs.find((item) => item.name === name);
+      if (!row) return;
+      row.mode = 'manual';
+      row.enabled = true;
+      delete row.legacy;
+      row.hidden = null;
+      row.manual = { origin: 'author', original: 'true', appliedAt: nowIso(), drift: false };
+    });
+  }
+
   return {
     paths,
     store,
@@ -680,7 +1124,18 @@ export function createService({
 
     /** 供插件 apply 时主动跑一次迁移（不必等到第一个请求）。 */
     ensureMigrated() {
-      return this.reloadState();
+      const current = this.reloadState();
+      try {
+        reconcileInvocations();
+      } catch (error) {
+        logger('invocation.reconcile.failed', { message: error?.message });
+      }
+      return current;
+    },
+
+    /** 诊断/测试用：手动跑一次「仅手动」重放。 */
+    reconcileInvocations() {
+      return reconcileInvocations();
     },
 
     async getState({ cwd, workspace } = {}) {
@@ -712,6 +1167,12 @@ export function createService({
         // unscanned：canonical 被挪到扫描根之外，本插件不提供可见性兜底（/diagnostics 会报出来）
         mode: paths.canonicalScanned ? 'direct' : 'unscanned',
         settings: state().settings,
+        invocation: {
+          support: INVOCATION_SUPPORT,
+          modes: ['auto', 'manual', 'hidden'],
+        },
+        // 技能介绍（模型生成）：前端据此决定按钮显隐；可用 ≠ 已登录，失败会在生成时如实报错
+        intro: introCapability(),
         agents: { all: registry.all(), detected: detectedTargets() },
         subscriptions: state().subscriptions,
         workspaces: await workspaceList(),
@@ -768,7 +1229,7 @@ export function createService({
         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;
+          if (item.enabled === false || item.mode === 'hidden') return false;
           const view = visible.byName.get(item.name);
           if (view?.visible) return false;
           const canonical = path.join(paths.canonical, item.name);
@@ -904,6 +1365,265 @@ export function createService({
       }
     },
 
+    /**
+     * 读缓存的技能介绍（只读，**不触发模型调用**）。
+     * `stale` 表示 SKILL.md 已被改动过；文本仍然返回，让用户先看到东西。
+     */
+    async getSkillIntro({ name, lang } = {}) {
+      assertSafeSkillName(name);
+      const language = introLang(lang);
+      const capability = introCapability();
+      if (!introStore) return { ok: true, name, lang: language, intro: null, capability };
+      const { file } = await readIntroSource(name);
+      const entry = introStore.get(name, language);
+      return {
+        ok: true,
+        name,
+        lang: language,
+        intro: entry ? publicIntro(entry, contentFingerprint(file.content)) : null,
+        capability,
+      };
+    },
+
+    /**
+     * 生成技能介绍：显式操作，一次一个模型调用。
+     * 命中缓存且内容未变时直接返回（`cached: true`），不烧额度。
+     */
+    async generateSkillIntro({ name, lang, force = false, signal = null } = {}) {
+      assertSafeSkillName(name);
+      const language = introLang(lang);
+      if (!introOptions.enabled) {
+        throw new ServiceError('error.skills.intro-disabled', '技能介绍已关闭（config.intro.enabled = false）', null, 501);
+      }
+      if (!introStore) {
+        throw new ServiceError('error.skills.intro-unavailable', '介绍缓存不可用', null, 501);
+      }
+      const llm = getLlm();
+      if (!llm) {
+        throw new ServiceError(
+          'error.skills.intro-unavailable',
+          '当前宿主没有模型服务（llm），无法生成介绍',
+          null,
+          501,
+        );
+      }
+
+      return withIntroInFlight({ name, lang: language, kind: 'local' }, async (startedAt) => {
+        try {
+          const { root, file } = await readIntroSource(name);
+          const hash = contentFingerprint(file.content);
+          const cached = introStore.get(name, language);
+          if (cached && !force) {
+            const intro = publicIntro(cached, hash);
+            if (!intro.stale) {
+              return { ok: true, name, lang: language, cached: true, intro, usage: null };
+            }
+          }
+
+          const route = resolveIntroRoute();
+          if (!route) {
+            throw new ServiceError(
+              'error.skills.intro-no-model',
+              '还没有可用的默认模型，请先在 DSH 里选择模型',
+              null,
+              409,
+            );
+          }
+
+          const prompt = buildIntroPrompt({
+            name,
+            description: parseSkillFrontmatter(file.content).description || '',
+            files: await introFileNames(root, file.relPath),
+            content: file.content,
+            maxInputBytes: introOptions.maxInputBytes,
+            lang: language,
+          });
+
+          const result = await callIntroModel({ llm, route, prompt, signal });
+          const entry = introEntry({
+            text: result.text,
+            hash,
+            provider: result.provider,
+            model: result.model,
+            usage: result.usage,
+            inputBytes: prompt.inputBytes,
+            truncated: prompt.truncated,
+            sourceBytes: prompt.sourceBytes,
+          });
+          introStore.put(name, language, entry);
+          logger('intro.generate', {
+            name,
+            lang: language,
+            provider: result.provider,
+            model: result.model,
+            inputBytes: prompt.inputBytes,
+            truncated: prompt.truncated,
+            durationMs: Date.now() - startedAt,
+            usage: result.usage || null,
+          });
+          return {
+            ok: true,
+            name,
+            lang: language,
+            cached: false,
+            intro: publicIntro(entry, hash),
+            usage: result.usage || null,
+          };
+        } catch (error) {
+          if (!(error instanceof ServiceError)) {
+            logger('intro.generate.failed', { name, message: error?.message, code: error?.code });
+          }
+          throw error;
+        }
+      });
+    },
+
+    /** 读订阅候选的介绍缓存（只读，不联网、不调模型）。 */
+    async getRemoteIntro({ subscriptionId, name, lang } = {}) {
+      const language = introLang(lang);
+      const capability = introCapability();
+      const target = remoteIntroTarget(subscriptionId, name);
+      const entry = introStore ? introStore.get(target.cacheKey, language) : null;
+      return {
+        ok: true,
+        subscriptionId,
+        name,
+        lang: language,
+        source: target.source,
+        commit: target.commit,
+        skillPath: target.skillPath,
+        description: target.description,
+        intro: entry ? publicRemoteIntro(entry) : null,
+        capability,
+      };
+    },
+
+    /**
+     * 生成订阅候选的介绍：先按快照 commit 拉远端 SKILL.md，再走同一套提示词与模型调用。
+     * 拉不到 / 超限只影响这次介绍，不影响安装按钮。
+     */
+    async generateRemoteIntro({ subscriptionId, name, lang, force = false, signal = null } = {}) {
+      const language = introLang(lang);
+      if (!introOptions.enabled) {
+        throw new ServiceError('error.skills.intro-disabled', '技能介绍已关闭（config.intro.enabled = false）', null, 501);
+      }
+      if (!introStore) {
+        throw new ServiceError('error.skills.intro-unavailable', '介绍缓存不可用', null, 501);
+      }
+      const llm = getLlm();
+      if (!llm) {
+        throw new ServiceError(
+          'error.skills.intro-unavailable',
+          '当前宿主没有模型服务（llm），无法生成介绍',
+          null,
+          501,
+        );
+      }
+
+      const target = remoteIntroTarget(subscriptionId, name);
+      const cached = introStore.get(target.cacheKey, language);
+      if (cached && !force) {
+        return {
+          ok: true,
+          subscriptionId,
+          name,
+          lang: language,
+          cached: true,
+          source: target.source,
+          commit: target.commit,
+          skillPath: target.skillPath,
+          intro: publicRemoteIntro(cached),
+          usage: null,
+        };
+      }
+
+      return withIntroInFlight(
+        { name, lang: language, kind: 'remote', source: target.source },
+        async (startedAt) => {
+          try {
+            const route = resolveIntroRoute();
+            if (!route) {
+              throw new ServiceError(
+                'error.skills.intro-no-model',
+                '还没有可用的默认模型，请先在 DSH 里选择模型',
+                null,
+                409,
+              );
+            }
+
+            let file;
+            try {
+              file = await fetchRemoteSkillMd({
+                source: target.source,
+                ref: target.commit,
+                skillPath: target.skillPath,
+                token: tokenOf,
+                fetchImpl,
+              });
+            } catch (error) {
+              throw remoteIntroSourceFailure(error);
+            }
+
+            const prompt = buildIntroPrompt({
+              name,
+              description: target.description,
+              files: [],
+              content: file.text,
+              maxInputBytes: introOptions.maxInputBytes,
+              lang: language,
+            });
+
+            const result = await callIntroModel({ llm, route, prompt, signal });
+            const entry = introEntry({
+              text: result.text,
+              hash: target.commit,
+              provider: result.provider,
+              model: result.model,
+              usage: result.usage,
+              inputBytes: prompt.inputBytes,
+              truncated: prompt.truncated,
+              sourceBytes: prompt.sourceBytes,
+            });
+            introStore.put(target.cacheKey, language, entry);
+            logger('intro.generate.remote', {
+              source: target.source,
+              name,
+              lang: language,
+              commit: target.commit,
+              provider: result.provider,
+              model: result.model,
+              inputBytes: prompt.inputBytes,
+              truncated: prompt.truncated,
+              durationMs: Date.now() - startedAt,
+              usage: result.usage || null,
+            });
+            return {
+              ok: true,
+              subscriptionId,
+              name,
+              lang: language,
+              cached: false,
+              source: target.source,
+              commit: target.commit,
+              skillPath: target.skillPath,
+              intro: publicRemoteIntro(entry),
+              usage: result.usage || null,
+            };
+          } catch (error) {
+            if (!(error instanceof ServiceError)) {
+              logger('intro.generate.remote.failed', {
+                source: target.source,
+                name,
+                message: error?.message,
+                code: error?.code,
+              });
+            }
+            throw error;
+          }
+        },
+      );
+    },
+
     /** 列技能目录的文件树（只读，不跟随符号链接）。 */
     async listSkillFiles({ name }) {
       assertSafeSkillName(name);
@@ -952,6 +1672,332 @@ export function createService({
       };
     },
 
+    /**
+     * 调用策略：auto / manual / hidden。
+     *
+     * - manual：只改 canonical SKILL.md 的 frontmatter；作者已声明 true 时只读；
+     * - hidden：A′ park（改名为 SKILL.md.disabled + marker），失败回滚文件；
+     * - auto：按 state 的 original 移除/还原插件行；作者声明不改，返回 409；
+     * - hidden 期间不允许直接改成 auto/manual，必须先 unpark（避免「界面以为停着，实际已恢复」）。
+     */
+    async setInvocation({ name, mode }) {
+      assertSafeSkillName(name);
+      assertWritable();
+      if (!['auto', 'manual', 'hidden'].includes(mode)) {
+        throw new ServiceError('error.skills.bad-mode', 'mode 只能是 auto / manual / hidden');
+      }
+      const initial = store.findInstall(name);
+      if (!initial) throw new ServiceError('error.skills.not-managed', `${name} 没有安装记录`);
+      return enqueue(`mode:${name}`, async () => {
+        const install = store.findInstall(name) || initial;
+        const dir = canonicalDir(name);
+        const kind = skillKindOf(dir);
+        if (kind === 'file') {
+          throw new ServiceError('error.skills.unsupported', `${name} 是平铺 .md 技能，不支持调用策略`, { name, kind }, 400);
+        }
+        if (kind !== 'dir') {
+          throw new ServiceError('error.skills.not-installed', `${name} 不在 canonical 里`, { name, kind }, 400);
+        }
+        if (fs.lstatSync(dir).isSymbolicLink()) {
+          throw new ServiceError('error.skills.not-writable', `${name} 的 canonical 是符号链接，拒绝编辑`, { name }, 409);
+        }
+
+        const park = inspectPark(dir);
+        const currentMode = park.parked || install.mode === 'hidden' ? 'hidden' : (install.mode || 'auto');
+
+        if (mode === 'hidden') {
+          if (currentMode === 'hidden') return { ok: true, name, mode: 'hidden', already: true, policy: 'park' };
+          const previousMode = currentMode === 'manual' ? 'manual' : 'auto';
+          // marker + SKILL.md（崩在 rename 前 / 外部手动恢复）：先把陈旧 marker 清掉再 park
+          if (park.marker && park.hasSkill && !park.hasDisabled) {
+            try {
+              fs.rmSync(path.join(dir, '.dsh-skills-console.park.json'), { force: true });
+            } catch {
+              /* parkSkill 会再报 */
+            }
+          }
+          let parked;
+          try {
+            parked = parkSkill({ dir, name, previousMode });
+          } catch (error) {
+            throw invocationFailure(error);
+          }
+          const hidden = {
+            disabledFile: parked.marker?.disabledFile || 'SKILL.md.disabled',
+            marker: '.dsh-skills-console.park.json',
+            previousMode,
+            canonicalHash: parked.canonicalHash || parked.marker?.canonicalHash || null,
+            at: nowIso(),
+          };
+          try {
+            store.update((draft) => {
+              const row = draft.installs.find((item) => item.name === name);
+              if (!row) return;
+              row.mode = 'hidden';
+              row.enabled = true;
+              delete row.legacy;
+              row.hidden = hidden;
+            });
+          } catch (error) {
+            try {
+              unparkSkill({ dir, name, fallbackMode: previousMode });
+            } catch (rollbackError) {
+              logger('invocation.park.rollback.failed', { name, message: rollbackError.message });
+            }
+            throw error;
+          }
+          try {
+            await invalidatePolicies();
+          } catch (error) {
+            logger('policy.invalidate.failed', { name, message: error.message });
+          }
+          logger('invocation.hidden', { name, previousMode });
+          return { ok: true, name, mode: 'hidden', previousMode, already: false, policy: 'park' };
+        }
+
+        if (currentMode === 'hidden') {
+          throw new ServiceError(
+            'error.skills.parked',
+            `${name} 已完全停用；请先恢复，再改调用策略`,
+            { name, action: 'invocation', previousMode: install.hidden?.previousMode || 'auto' },
+            409,
+          );
+        }
+
+        if (mode === 'manual') {
+          let text;
+          let plan;
+          try {
+            text = readSkillText(dir);
+            plan = planManualWrite(text);
+          } catch (error) {
+            throw invocationFailure(error);
+          }
+          if (plan.author) {
+            if (install.mode === 'manual' && install.manual?.origin === 'author') {
+              return { ok: true, name, mode: 'manual', origin: 'author', already: true, policy: 'frontmatter' };
+            }
+            commitAuthorManual(name);
+            try {
+              await invalidatePolicies();
+            } catch (error) {
+              logger('policy.invalidate.failed', { name, message: error.message });
+            }
+            logger('invocation.manual', { name, origin: 'author' });
+            return { ok: true, name, mode: 'manual', origin: 'author', already: false, policy: 'frontmatter' };
+          }
+          if (install.mode === 'manual' && install.manual?.origin === 'plugin' && !plan.changed) {
+            return { ok: true, name, mode: 'manual', origin: 'plugin', already: true, policy: 'frontmatter' };
+          }
+          try {
+            commitManual({ name, dir, plan, text });
+          } catch (error) {
+            throw invocationFailure(error);
+          }
+          try {
+            await invalidatePolicies();
+          } catch (error) {
+            logger('policy.invalidate.failed', { name, message: error.message });
+          }
+          logger('invocation.manual', { name, origin: 'plugin', original: plan.original });
+          return {
+            ok: true,
+            name,
+            mode: 'manual',
+            origin: 'plugin',
+            original: plan.original,
+            already: false,
+            policy: 'frontmatter',
+          };
+        }
+
+        // auto
+        if (install.mode === 'manual' && install.manual) {
+          if (install.manual.origin === 'author') {
+            throw new ServiceError(
+              'error.skills.author',
+              '这个技能由作者声明了仅手动，插件不能替你改回自动；请编辑 SKILL.md',
+              { name, action: 'auto' },
+              409,
+            );
+          }
+          let text;
+          let plan;
+          try {
+            text = readSkillText(dir);
+            plan = planManualRestore(text, install.manual.original);
+          } catch (error) {
+            if (error instanceof InvocationError && error.code === 'error.skills.drift') {
+              markDrift(name);
+            }
+            throw invocationFailure(error);
+          }
+          if (plan.changed) {
+            try {
+              try {
+                backupInvocation({ backupDir: paths.backupsDir, name, content: text });
+              } catch (error) {
+                throw new InvocationError(
+                  'error.skills.not-writable',
+                  `无法备份 ${name} 的 SKILL.md：${error.message}`,
+                  { name },
+                  409,
+                );
+              }
+              writeFileAtomic(path.join(dir, 'SKILL.md'), plan.nextText);
+            } catch (error) {
+              throw invocationFailure(error);
+            }
+            try {
+              store.update((draft) => {
+                const row = draft.installs.find((item) => item.name === name);
+                if (!row) return;
+                row.mode = 'auto';
+                row.enabled = true;
+                delete row.legacy;
+                row.manual = null;
+                row.hidden = null;
+              });
+            } catch (error) {
+              try {
+                writeFileAtomic(path.join(dir, 'SKILL.md'), text);
+              } catch (rollbackError) {
+                logger('invocation.rollback.failed', { name, message: rollbackError.message });
+              }
+              throw error;
+            }
+          } else {
+            store.update((draft) => {
+              const row = draft.installs.find((item) => item.name === name);
+              if (!row) return;
+              row.mode = 'auto';
+              row.enabled = true;
+              delete row.legacy;
+              row.manual = null;
+              row.hidden = null;
+            });
+          }
+          try {
+            await invalidatePolicies();
+          } catch (error) {
+            logger('policy.invalidate.failed', { name, message: error.message });
+          }
+          logger('invocation.auto', { name, changed: plan.changed });
+          return { ok: true, name, mode: 'auto', already: false, policy: 'frontmatter' };
+        }
+
+        if (install.mode === 'auto' && !install.legacy) {
+          return { ok: true, name, mode: 'auto', already: true, policy: 'frontmatter' };
+        }
+        store.update((draft) => {
+          const row = draft.installs.find((item) => item.name === name);
+          if (!row) return;
+          row.mode = 'auto';
+          row.enabled = true;
+          delete row.legacy;
+          row.manual = null;
+          row.hidden = null;
+        });
+        try {
+          await invalidatePolicies();
+        } catch (error) {
+          logger('policy.invalidate.failed', { name, message: error.message });
+        }
+        logger('invocation.auto', { name, changed: false, legacy: true });
+        return { ok: true, name, mode: 'auto', already: false, policy: 'frontmatter' };
+      });
+    },
+
+    /**
+     * A′ 恢复：校验 marker / disabled，把文件名改回来；不重新下载、不重建导出链。
+     * 停用期间外部写回 SKILL.md 时默认 409；`keep='current' | 'parked'` 明确选择保留哪份。
+     */
+    async unpark({ name, keep = null }) {
+      assertSafeSkillName(name);
+      assertWritable();
+      if (keep !== null && keep !== 'current' && keep !== 'parked') {
+        throw new ServiceError('error.skills.bad-mode', 'keep 只能是 current / parked');
+      }
+      return enqueue(`mode:${name}`, async () => {
+        const dir = canonicalDir(name);
+        const park = inspectPark(dir);
+        const existing = store.findInstall(name);
+        if (!park.parked) {
+          // state 说 hidden，但 marker 和 disabled 都没了：内容已丢，不能假装恢复
+          if (existing?.mode === 'hidden') {
+            throw new ServiceError(
+              'error.skills.park-broken',
+              `${name} 记录为完全停用，但技能文件不在；请从回收站或备份找回`,
+              { name, reason: 'both-missing' },
+              409,
+            );
+          }
+          throw new ServiceError('error.skills.not-parked', `${name} 没有处于完全停用状态`, { name }, 409);
+        }
+        let install = existing;
+        const fallbackMode = install?.hidden?.previousMode || install?.mode || 'auto';
+        let result;
+        try {
+          result = unparkSkill({ dir, name, fallbackMode: fallbackMode === 'manual' ? 'manual' : 'auto', keep });
+        } catch (error) {
+          throw invocationFailure(error);
+        }
+
+        if (!install) {
+          // state 丢了但 marker 还在：先补一条接管记录，后面才有行可更新
+          const lock = readLock(paths);
+          const record = adoptionRecord(name, lock.skills?.[name] || null);
+          store.update((draft) => applyAdoptions(draft, [record]));
+          install = store.findInstall(name);
+        }
+
+        let mode = result.mode === 'manual' ? 'manual' : 'auto';
+        let manual = install?.manual || null;
+        if (mode === 'manual') {
+          if (!manual) {
+            let parsed = null;
+            try {
+              parsed = parseInvocation(readSkillText(dir));
+            } catch {
+              /* 按 auto 收敛 */
+            }
+            if (parsed?.value === 'true') {
+              manual = { origin: 'author', original: 'true', appliedAt: nowIso(), drift: false };
+            } else {
+              mode = 'auto';
+            }
+          }
+        }
+        // 恢复时内容被外部改过 / 选了保留当前版本：manual 标记可能不再可信，标 drift 让 UI 报
+        if (mode === 'manual' && manual && result.hashMismatch) manual = { ...manual, drift: true };
+        store.update((draft) => {
+          const row = draft.installs.find((item) => item.name === name);
+          if (!row) return;
+          row.mode = mode;
+          row.enabled = true;
+          delete row.legacy;
+          row.hidden = null;
+          if (mode === 'manual') row.manual = manual;
+          else row.manual = null;
+        });
+        try {
+          await invalidatePolicies();
+        } catch (error) {
+          logger('policy.invalidate.failed', { name, message: error.message });
+        }
+        logger('invocation.unpark', { name, mode, hashMismatch: result.hashMismatch });
+        return {
+          ok: true,
+          name,
+          mode,
+          previousMode: result.previousMode,
+          hashMismatch: result.hashMismatch,
+          kept: result.kept,
+          removed: result.removed,
+        };
+      });
+    },
+
     /**
      * 停用 = 只写 state（由 policy provider 覆盖 canonical 候选）；启用 = 写 state 并清掉
      * 可能残留的 legacy 停用桩。
@@ -977,10 +2023,27 @@ export function createService({
       }
       const install = store.findInstall(name);
       if (!install) throw new ServiceError('error.skills.not-managed', `${name} 没有安装记录`);
+      // 旧 /mode 只服务 legacy dsh-off；manual / hidden 必须走 /invocation，避免两套开关打架
+      if (install.mode === 'manual' || install.mode === 'hidden' || install.hidden) {
+        throw new ServiceError(
+          'error.skills.mode-conflict',
+          `${name} 使用三档调用策略，请用 /invocation 而不是旧 /mode`,
+          { name, mode: install.mode },
+          409,
+        );
+      }
       return enqueue(`mode:${name}`, async () => {
         const canonicalPath = path.join(paths.canonical, name);
         // 在队列里重新读一次：并发两次 off/on 时不能拿入队前的快照判断「已经如此」。
         const current = store.findInstall(name) || install;
+        if (current.mode === 'manual' || current.mode === 'hidden' || current.hidden) {
+          throw new ServiceError(
+            'error.skills.mode-conflict',
+            `${name} 使用三档调用策略，请用 /invocation 而不是旧 /mode`,
+            { name, mode: current.mode },
+            409,
+          );
+        }
         const already = mode === 'off' ? current.enabled === false : current.enabled !== false;
 
         if (mode === 'off') {
@@ -1032,7 +2095,11 @@ export function createService({
           }
           store.update((draft) => {
             const row = draft.installs.find((item) => item.name === name);
-            if (row) row.enabled = false;
+            if (row) {
+              row.enabled = false;
+              row.mode = 'auto';
+              row.legacy = 'dsh-off';
+            }
           });
           await invalidatePolicies();
           logger('mode.off', { name, policy: 'provider' });
@@ -1061,7 +2128,11 @@ export function createService({
         }
         store.update((draft) => {
           const row = draft.installs.find((item) => item.name === name);
-          if (row) row.enabled = true;
+          if (row) {
+            row.enabled = true;
+            row.mode = 'auto';
+            delete row.legacy;
+          }
           draft.legacyShadows = (draft.legacyShadows || []).filter((item) => item.skill !== name);
         });
         await invalidatePolicies();
@@ -1074,7 +2145,11 @@ export function createService({
       assertWritable();
       await requireInstaller();
       const requested = (skills || []).filter(Boolean);
-      for (const name of requested) assertSafeSkillName(name);
+      for (const name of requested) {
+        assertSafeSkillName(name);
+        // parked 期间安装/重装会把 SKILL.md 写回来，界面却还以为停着 —— 必须先恢复
+        assertNotParked(name, '安装');
+      }
 
       return enqueue('install', async () => {
         const subscription = subscriptionId
@@ -1161,6 +2236,11 @@ export function createService({
               draft.installs.push({ ...record, enabled: true });
             }
           });
+          // 重装 / 更新同一个 manual 技能时，新内容没有插件行；按 state 重新写回。
+          const invocation = reapplyInvocation(item.name);
+          if (!invocation.ok) {
+            warnings.push({ name: item.name, warning: `仅手动标记未能重放：${invocation.message || invocation.code}` });
+          }
           installed.push({
             name: item.name,
             lockHash,
@@ -1168,6 +2248,7 @@ export function createService({
             treeSha: record.treeSha,
             installedHash,
             backup: item.backup || null,
+            invocation,
           });
         }
 
@@ -1641,7 +2722,12 @@ export function createService({
         ref,
         targetTreeSha,
         skillPath,
-        localModified: Boolean(install.installedHash) && contentHash(path.join(paths.canonical, name)) !== install.installedHash,
+        // 归一化哈希：manual 的插件行不算本地改动，否则每次更新都被自己的标记挡住
+        localModified: (() => {
+          if (install.mode === 'hidden' || inspectPark(path.join(paths.canonical, name)).parked) return false;
+          const current = hashWithoutInvocation(path.join(paths.canonical, name), install.manual);
+          return Boolean(install.installedHash) && (current === null || current !== install.installedHash);
+        })(),
       };
     },
 
@@ -1649,6 +2735,7 @@ export function createService({
       assertWritable();
       await requireInstaller();
       return enqueue(`apply:${name}`, async () => {
+        assertNotParked(name, '更新');
         const plan = await this.planUpdate({ name });
         if (token && token !== plan.token) {
           throw new ServiceError('error.skills.stale-plan', '计划已失效（磁盘或上游被改动过），请重新检查');
@@ -1727,6 +2814,9 @@ export function createService({
         // 更新重建的是 canonical 目录：导出链按原目标复验补建。`enabled` 保持不变——
         // 停用期间更新，模型仍然看不到新正文，直到启用（不再需要刷新任何桩的 hash）。
         const relinked = exportSkill(name, exportTargetsFor(name));
+        // 新内容默认没有插件行；仍 manual 就重放，失败只标 drift，不回滚已成功的更新
+        const invocation = reapplyInvocation(name);
+        if (!invocation.ok) logger('invocation.reapply.failed', { name, message: invocation.message });
         logger('updates.apply', { name, from: plan.fromCommit, to: plan.toCommit, backup: item.backup || null });
         return {
           ok: true,
@@ -1735,6 +2825,7 @@ export function createService({
           toCommit: plan.toCommit || null,
           backup: item.backup || null,
           relinked,
+          invocation,
         };
       });
     },
@@ -1742,6 +2833,7 @@ export function createService({
     async rollback({ name }) {
       assertWritable();
       return enqueue(`rollback:${name}`, async () => {
+        assertNotParked(name, '回滚');
         const install = store.findInstall(name);
         if (!install?.backup?.key) throw new ServiceError('error.skills.no-backup', `${name} 没有可回滚的备份`);
         const backup = readBackup({ paths, key: install.backup.key });
@@ -1767,7 +2859,8 @@ export function createService({
             },
           });
         }
-        const installedHash = contentHash(canonicalPath);
+        // 备份可能带着插件写的 frontmatter 行；基线统一用归一化哈希
+        const installedHash = hashWithoutInvocation(canonicalPath, install.manual) || contentHash(canonicalPath);
         store.update((draft) => {
           const row = draft.installs.find((item) => item.name === name);
           if (!row) return;
@@ -1778,8 +2871,9 @@ export function createService({
           row.treeSha = install.backup.treeSha ?? null;
           draft.checks[name] = { name, status: 'unknown', detail: '已回滚，需重新检查', checkedAt: nowIso() };
         });
+        const invocation = reapplyInvocation(name);
         logger('updates.rollback', { name, backup: install.backup.key });
-        return { ok: true, name, restoredFrom: install.backup.key, installedHash };
+        return { ok: true, name, restoredFrom: install.backup.key, installedHash, invocation };
       });
     },
   };