@morehao/dsh-skills-console 0.4.0 → 0.5.1

package/lib/core/state.js

@@ -7,11 +7,14 @@ import path from 'node:path';
  * - v2：`installs[].enabled` + `exports[]`（只给其他 agent 的显式导出）+ `shadows[]`（DSH 扫描根里的停用标记）。
  * - v3：`installs[].enabled` 是**唯一**启停开关；`shadows[]` 退休，`legacyShadows[]` 只放
  *   迁移时删不掉的旧桩与 orphan（v0.4.0 起启停由每个 live agent scope 的 policy provider 负责）。
+ * - v4：`installs[].mode`（auto / manual / hidden）成为调用策略；`enabled` 只保留给 legacy
+ *   `dsh-off`（旧版 DSH-only 停用），manual / hidden 不再借助 provider。`manual` 记录
+ *   frontmatter 的原始值与来源，`hidden` 记录 A′ park 的 marker / 内容哈希。
  *
- * 迁移分两步：`upgradeStateV1` / `upgradeStateV2` 只做**纯结构**改写（可测、无副作用），
- * 删链/删旧桩/剪悬空导出这类要做 IO 的事在 `migrations.js` 里按 manifest 执行。
+ * 迁移分三步：`upgradeStateV1` / `upgradeStateV2` / `upgradeStateV3` 只做**纯结构**改写
+ * （可测、无副作用），删链/删旧桩/剪悬空导出这类要做 IO 的事在 `migrations.js` 里按 manifest 执行。
  */
-export const STATE_VERSION = 3;
+export const STATE_VERSION = 4;
 
 export function emptyState() {
   return {
@@ -150,6 +153,37 @@ export function upgradeStateV2(value, { now = new Date().toISOString() } = {}) {
   return next;
 }
 
+const INVOCATION_MODES = new Set(['auto', 'manual', 'hidden']);
+
+/**
+ * v3 → v4 的结构升级。**不读写任何文件**：
+ * - 老记录没有 `mode` → `auto`（行为与 v3 完全一致）；
+ * - `enabled === false` → 额外 `legacy: 'dsh-off'`，仍由 provider 隐藏，绝不静默改成 manual；
+ * - `manual` / `hidden` 只做形状占位（null），真实值由后续写操作填充。
+ *
+ * 不写 `migration`：v1→v2→v3 的 migration 是文件侧待办清单，v4 只是字段迁移，没有 IO。
+ */
+export function upgradeStateV3(value) {
+  const installs = (Array.isArray(value.installs) ? value.installs : []).map((item) => {
+    const next = isPlainObject(item) ? { ...item } : {};
+    if (!INVOCATION_MODES.has(next.mode)) next.mode = 'auto';
+    if (next.mode === 'auto') {
+      if (next.enabled === false) next.legacy = 'dsh-off';
+      else delete next.legacy;
+    } else {
+      // manual / hidden 都不再依赖 provider：enabled 必须是 true，否则会双重隐藏。
+      next.enabled = true;
+      delete next.legacy;
+    }
+    if (next.mode === 'auto') {
+      next.manual = null;
+      next.hidden = null;
+    }
+    return next;
+  });
+  return { ...value, version: 4, installs };
+}
+
 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` };
@@ -202,6 +236,69 @@ function validateV3(state) {
   return { ok: true, state };
 }
 
+/**
+ * v4 的形状校验。只修「缺省即可推断」的字段（mode 缺省 auto、hidden 的固定文件名），
+ * 不猜冲突语义：mode 写错、manual 缺 origin / original 一律只读，避免拿坏状态去写文件。
+ */
+function validateV4(state) {
+  for (const row of state.installs) {
+    if (row.mode === undefined) row.mode = 'auto';
+    if (!INVOCATION_MODES.has(row.mode)) {
+      return { ok: false, reason: `state.installs[] ${row.name} has invalid mode ${String(row.mode)}` };
+    }
+    if (row.legacy !== undefined && row.legacy !== 'dsh-off') {
+      return { ok: false, reason: `state.installs[] ${row.name} has invalid legacy ${String(row.legacy)}` };
+    }
+    if (row.mode === 'auto') {
+      row.manual = null;
+      row.hidden = null;
+      if (row.legacy === 'dsh-off') row.enabled = false;
+      else delete row.legacy;
+      continue;
+    }
+    row.enabled = true;
+    delete row.legacy;
+    if (row.mode === 'manual') {
+      row.hidden = null;
+      if (!isPlainObject(row.manual)) {
+        return { ok: false, reason: `state.installs[] ${row.name} manual metadata is missing` };
+      }
+      if (row.manual.origin !== 'plugin' && row.manual.origin !== 'author') {
+        return { ok: false, reason: `state.installs[] ${row.name} manual.origin is invalid` };
+      }
+      if (!['absent', 'true', 'false'].includes(row.manual.original)) {
+        return { ok: false, reason: `state.installs[] ${row.name} manual.original is invalid` };
+      }
+      if (typeof row.manual.appliedAt !== 'string' || !row.manual.appliedAt) {
+        row.manual.appliedAt = new Date().toISOString();
+      }
+      continue;
+    }
+    // hidden
+    if (!isPlainObject(row.hidden)) {
+      return { ok: false, reason: `state.installs[] ${row.name} hidden metadata is missing` };
+    }
+    if (row.hidden.previousMode !== 'auto' && row.hidden.previousMode !== 'manual') {
+      return { ok: false, reason: `state.installs[] ${row.name} hidden.previousMode is invalid` };
+    }
+    if (typeof row.hidden.disabledFile !== 'string' || !row.hidden.disabledFile) {
+      row.hidden.disabledFile = 'SKILL.md.disabled';
+    }
+    if (typeof row.hidden.marker !== 'string' || !row.hidden.marker) {
+      row.hidden.marker = '.dsh-skills-console.park.json';
+    }
+    if (row.hidden.canonicalHash !== undefined && row.hidden.canonicalHash !== null
+      && typeof row.hidden.canonicalHash !== 'string') {
+      return { ok: false, reason: `state.installs[] ${row.name} hidden.canonicalHash is invalid` };
+    }
+    if (typeof row.hidden.at !== 'string' || !row.hidden.at) row.hidden.at = new Date().toISOString();
+    if (row.manual !== undefined && row.manual !== null && !isPlainObject(row.manual)) {
+      return { ok: false, reason: `state.installs[] ${row.name} manual metadata is invalid` };
+    }
+  }
+  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)) {
@@ -229,8 +326,9 @@ export function validateState(value) {
   }
 
   let upgraded;
-  if (value.version === 1) upgraded = upgradeStateV2(upgradeStateV1(value));
-  else if (value.version === 2) upgraded = upgradeStateV2(value);
+  if (value.version === 1) upgraded = upgradeStateV3(upgradeStateV2(upgradeStateV1(value)));
+  else if (value.version === 2) upgraded = upgradeStateV3(upgradeStateV2(value));
+  else if (value.version === 3) upgraded = upgradeStateV3(value);
   else upgraded = value;
 
   const state = { ...emptyState(), ...upgraded };
@@ -238,7 +336,9 @@ export function validateState(value) {
   // v1 的顶层 links[] 在 v2 升级时已拆成 exports[] + migration.legacyLinks；
   // 旧版本只搬家没删原字段，v3 里读到就剪掉，不再往外写。
   delete state.links;
-  const verdict = validateV3(state);
+  const v3 = validateV3(state);
+  if (!v3.ok) return v3;
+  const verdict = validateV4(v3.state);
   if (!verdict.ok) return verdict;
   state.version = STATE_VERSION;
   return { ok: true, state: verdict.state };

package/lib/index.js

@@ -4,6 +4,8 @@ import { createPaths } from './core/paths.js';
 import { createRegistry } from './core/agents.js';
 import { createPolicyProvider, installPolicyProviders } from './core/policy.js';
 import { createService } from './core/service.js';
+import { normalizeIntroConfig } from './core/intro.js';
+import { createIntroStore } from './core/intro-store.js';
 import { StateStore } from './core/state.js';
 import { createRoutes, ROUTE_PREFIX } from './routes.js';
 
@@ -86,6 +88,20 @@ export function apply(ctx, config = {}) {
     workspacesProvider,
     invalidatePolicies: () => policies.invalidate(),
     policyStatus: () => policies.status(),
+    // 技能介绍：走宿主已挂载的模型服务（可选服务，缺失时接口 501，其他功能不受影响）
+    introStore: createIntroStore({ paths, logger }),
+    introOptions: normalizeIntroConfig(config.intro || {}),
+    getLlm: () => ctx.get('llm'),
+    getDefaultModel: () => {
+      const defaults = ctx.get('agentDefaultModel');
+      if (!defaults?.currentSelection) return null;
+      try {
+        return defaults.currentSelection();
+      } catch (error) {
+        logger('intro.default-model.failed', { message: error?.message });
+        return null;
+      }
+    },
   });
 
   // 迁移必须尽早跑：GUI 一打开就该是「停用 = 真不可见」，而不是等用户点到某一行才发现。

package/lib/invocation-support.json

@@ -0,0 +1,46 @@
+{
+  "generatedAt": "2026-10-26",
+  "note": "只承诺已确认的客户端；`disable-model-invocation` 是客户端扩展，不是 Agent Skills 规范字段。",
+  "clients": [
+    {
+      "id": "dsh",
+      "label": "DSH",
+      "manual": "yes",
+      "hidden": "yes",
+      "verifiedAt": "2026-10-26",
+      "source": "宿主 SKILL.md frontmatter + 扫描根"
+    },
+    {
+      "id": "claude",
+      "label": "Claude Code",
+      "manual": "yes",
+      "hidden": "yes",
+      "verifiedAt": "2026-10-26",
+      "source": "Claude Code skills frontmatter"
+    },
+    {
+      "id": "cursor",
+      "label": "Cursor",
+      "manual": "yes",
+      "hidden": "yes",
+      "verifiedAt": "2026-10-26",
+      "source": "Cursor skills frontmatter"
+    },
+    {
+      "id": "opencode",
+      "label": "OpenCode",
+      "manual": "version",
+      "hidden": "yes",
+      "verifiedAt": null,
+      "source": "版本相关，未逐版验证"
+    },
+    {
+      "id": "other",
+      "label": "其他 / 未验证",
+      "manual": "unverified",
+      "hidden": "spec",
+      "verifiedAt": null,
+      "source": "目录里没有 SKILL.md 即不符合规范发现"
+    }
+  ]
+}

package/lib/routes.js

@@ -73,12 +73,23 @@ function matchRoute(method, pathname) {
   if (segments[0] === 'skills' && segments.length === 3 && segments[2] === 'files' && method === 'GET') {
     return { name: 'skill.files', params: { name: decodeURIComponent(segments[1]) } };
   }
+  // 技能介绍（模型生成）：GET 只读缓存，POST 才真正调模型
+  if (segments[0] === 'skills' && segments.length === 3 && segments[2] === 'intro') {
+    if (method === 'GET') return { name: 'skill.intro.get', params: { name: decodeURIComponent(segments[1]) } };
+    if (method === 'POST') return { name: 'skill.intro.generate', params: { name: decodeURIComponent(segments[1]) } };
+  }
   if (segments[0] === 'skills' && segments.length === 3 && segments[2] === 'adopt' && method === 'POST') {
     return { name: 'skill.adopt', params: { name: decodeURIComponent(segments[1]) } };
   }
   if (segments[0] === 'skills' && segments.length === 3 && segments[2] === 'mode' && method === 'POST') {
     return { name: 'skill.mode', params: { name: decodeURIComponent(segments[1]) } };
   }
+  if (segments[0] === 'skills' && segments.length === 3 && segments[2] === 'invocation' && method === 'POST') {
+    return { name: 'skill.invocation', params: { name: decodeURIComponent(segments[1]) } };
+  }
+  if (segments[0] === 'skills' && segments.length === 3 && segments[2] === 'unpark' && method === 'POST') {
+    return { name: 'skill.unpark', params: { name: decodeURIComponent(segments[1]) } };
+  }
   if (segments[0] === 'skills' && segments.length === 2 && method === 'DELETE') {
     return { name: 'skill.remove', params: { name: decodeURIComponent(segments[1]) } };
   }
@@ -91,6 +102,13 @@ function matchRoute(method, pathname) {
     if (segments.length === 3 && segments[2] === 'refresh' && method === 'POST') {
       return { name: 'subscriptions.refresh', params: { id: decodeURIComponent(segments[1]) } };
     }
+    // 订阅候选的介绍：路径由服务端按快照反查，客户端只给订阅 id + 条目名
+    if (segments.length === 5 && segments[2] === 'entries' && segments[4] === 'intro') {
+      const id = decodeURIComponent(segments[1]);
+      const entryName = decodeURIComponent(segments[3]);
+      if (method === 'GET') return { name: 'subscription.intro.get', params: { id, name: entryName } };
+      if (method === 'POST') return { name: 'subscription.intro.generate', params: { id, name: entryName } };
+    }
   }
 
   if (segments[0] === 'updates') {
@@ -123,13 +141,24 @@ export function createRoutes({ service, logger }) {
       return;
     }
 
+    // 客户端断开（关抽屉 / 关页面）就取消模型调用：摘要是一次性辅助请求，没必要跑完再丢。
+    // 测试里的 fake res 没有 on/off，所以要按能力探测。
+    const abort = new AbortController();
+    const onClose = () => {
+      if (!res.writableEnded) abort.abort();
+    };
+    if (typeof res.on === 'function') res.on('close', onClose);
+
     try {
       service.reloadState();
       const body = method === 'GET' ? {} : await readBody(req);
       const query = Object.fromEntries(url.searchParams.entries());
-      const result = await dispatch(route, { body, query, service });
+      const result = await dispatch(route, { body, query, service, signal: abort.signal });
+      // 生成期间客户端可能已经走了：往已关闭的响应写会抛 ERR_STREAM_WRITE_AFTER_END
+      if (res.writableEnded || res.destroyed) return;
       sendJson(res, 200, result);
     } catch (error) {
+      if (res.writableEnded || res.destroyed) return;
       if (error instanceof StateReadOnlyError) {
         sendJson(res, 409, {
           ok: false,
@@ -146,11 +175,13 @@ export function createRoutes({ service, logger }) {
       }
       logger('route.error', { message: error?.message, stack: String(error?.stack || '').slice(0, 800) });
       sendJson(res, 500, { ok: false, code: 'error.skills.internal', message: error?.message || 'internal error' });
+    } finally {
+      if (typeof res.off === 'function') res.off('close', onClose);
     }
   };
 }
 
-async function dispatch(route, { body, query, service }) {
+async function dispatch(route, { body, query, service, signal = null }) {
   switch (route.name) {
     case 'state': {
       const state = await service.getState({ cwd: query.cwd || body.cwd, workspace: query.workspace });
@@ -174,6 +205,29 @@ async function dispatch(route, { body, query, service }) {
       return service.listSkillBody({ name: route.params.name, path: query.path });
     case 'skill.files':
       return service.listSkillFiles({ name: route.params.name });
+    case 'skill.intro.get':
+      return service.getSkillIntro({ name: route.params.name, lang: query.lang });
+    case 'subscription.intro.get':
+      return service.getRemoteIntro({
+        subscriptionId: route.params.id,
+        name: route.params.name,
+        lang: query.lang,
+      });
+    case 'subscription.intro.generate':
+      return service.generateRemoteIntro({
+        subscriptionId: route.params.id,
+        name: route.params.name,
+        lang: body.lang ?? query.lang,
+        force: body.force === true,
+        signal,
+      });
+    case 'skill.intro.generate':
+      return service.generateSkillIntro({
+        name: route.params.name,
+        lang: body.lang ?? query.lang,
+        force: body.force === true,
+        signal,
+      });
     case 'skill.adopt':
       return service.adopt({ name: route.params.name });
     case 'skill.mode':
@@ -183,6 +237,10 @@ async function dispatch(route, { body, query, service }) {
         scope: body.scope,
         projectRoot: body.projectRoot,
       });
+    case 'skill.invocation':
+      return service.setInvocation({ name: route.params.name, mode: body.mode });
+    case 'skill.unpark':
+      return service.unpark({ name: route.params.name, keep: body.keep || null });
     case 'skill.remove':
       return service.remove({ name: route.params.name });
     case 'subscriptions.add':

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Skills Console",
-    "description": "Install, update, remove, link and enable local agent skills. Skill bodies stay owned by the skills CLI."
+    "description": "Install, update, remove and manage invocation policies for local agent skills. Skill bodies stay untouched; only Manual-only adds one marker line."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "技能控制台",
-    "description": "安装、更新、删除、接入与启停本机 Agent 技能；技能正文始终由 skills CLI 写入。"
+    "description": "安装、更新、删除与调用策略管理本机 Agent 技能；技能正文保持原样，仅「仅手动」会加一行标记。"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morehao/dsh-skills-console",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "统一管理本地技能的安装、更新、删除与接入，让同一份技能在多个 Agent 间复用。A skill manager for DeepSeek Harness: install, update, remove, link and toggle agent skills.",
   "license": "MIT",
   "author": "morehao <morehao@qq.com>",