@morehao/dsh-skills-console 0.5.0 → 0.5.2

package/lib/core/remote.js

@@ -190,7 +190,14 @@ export async function snapshotFromTarball({
       } catch (error) {
         throw new RemoteError('scan-failed', `计算 ${skill.name} tree 失败: ${error.message}`, { cause: error });
       }
-      entries.push({ name: skill.name, skillPath: skill.skillPath, treeSha });
+      entries.push({
+        name: skill.name,
+        skillPath: skill.skillPath,
+        treeSha,
+        // 订阅条目在界面上还要用一行原文描述帮用户决定装不装：只是 frontmatter 里作者自己的话，
+        // 不调模型、也不进提示词；截断避免 state.json 被超长描述撑大。
+        description: typeof skill.description === 'string' ? skill.description.slice(0, 600) : '',
+      });
       const dir = skillDirOf(skill.skillPath);
       if (dir && !seenDirs.has(dir)) {
         seenDirs.add(dir);
@@ -332,3 +339,98 @@ export async function downloadTarball({
     if (timer) clearTimeout(timer);
   }
 }
+
+// ---- 订阅候选的 SKILL.md（AI 介绍用） -------------------------------------
+// 只读单个文件、只允许 raw.githubusercontent.com；按 commit 读取，避免分支移动导致内容漂移。
+
+export const REMOTE_SKILL_MD_MAX_BYTES = 512 * 1024;
+export const REMOTE_SKILL_MD_TIMEOUT_MS = 20_000;
+const COMMIT_SHA = /^[0-9a-f]{40}$/i;
+
+/** 技能文件路径校验：快照里的 skillPath 也不盲信，逐段拒绝越界与特殊字符。 */
+function assertSkillFilePath(skillPath) {
+  if (typeof skillPath !== 'string' || skillPath.length === 0 || skillPath.length > 400) {
+    throw new RemoteError('intro-source-failed', '技能路径非法');
+  }
+  if (skillPath.startsWith('/') || skillPath.includes('\\') || /^[A-Za-z]:/.test(skillPath)) {
+    throw new RemoteError('intro-source-failed', `技能路径不是仓库内相对路径: ${skillPath}`);
+  }
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f]/.test(skillPath)) {
+    throw new RemoteError('intro-source-failed', '技能路径含控制字符');
+  }
+  const segments = skillPath.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    throw new RemoteError('intro-source-failed', `技能路径含非法段: ${skillPath}`);
+  }
+  return segments.map(encodeURIComponent).join('/');
+}
+
+/**
+ * 读订阅快照里某个技能的 `SKILL.md`（用于按需生成能力介绍）。
+ *
+ * - `ref` 必须是快照里的 40 位 commit：订阅页的「介绍」要可复现，不能读会移动的分支；
+ * - 只允许 GitHub 的 raw host，路径由服务端从快照反查后传入，不接受客户端拼路径；
+ * - 大小 / 超时都有上限，超限抛 RemoteError，由 Service 转成 4xx/5xx。
+ *
+ * @returns {Promise<{ text: string, bytes: number, source: string, ref: string, skillPath: string }>}
+ */
+export async function fetchRemoteSkillMd({
+  source,
+  ref,
+  skillPath,
+  token = null,
+  fetchImpl = fetch,
+  maxBytes = REMOTE_SKILL_MD_MAX_BYTES,
+  timeoutMs = REMOTE_SKILL_MD_TIMEOUT_MS,
+}) {
+  const parsed = parseSource(source);
+  if (!parsed) throw new RemoteError('invalid-source', `不是 GitHub 来源: ${source}`);
+  if (typeof ref !== 'string' || !COMMIT_SHA.test(ref)) {
+    throw new RemoteError('invalid-ref', '订阅介绍必须按 40 位 commit 读取');
+  }
+  const repo = `${parsed.owner}/${parsed.repo}`;
+  const relPath = assertSkillFilePath(skillPath);
+  const url = `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/${ref.toLowerCase()}/${relPath}`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url, {
+      headers: {
+        'user-agent': 'dsh-skills-console',
+        accept: 'text/plain, text/markdown;q=0.9, */*;q=0.1',
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+      signal: controller.signal,
+    });
+    if (!response?.ok) {
+      throw new RemoteError(
+        'intro-source-failed',
+        `读不到 ${repo}@${ref.slice(0, 7)} 的 ${skillPath}（HTTP ${response?.status ?? '?'}）`,
+        { status: response?.status ?? null },
+      );
+    }
+    const text = await response.text();
+    const bytes = Buffer.byteLength(text, 'utf8');
+    if (bytes > maxBytes) {
+      throw new RemoteError(
+        'intro-source-too-large',
+        `${repo}@${ref.slice(0, 7)} 的 ${skillPath} 太大（${bytes} 字节），无法作为介绍素材`,
+        { bytes, maxBytes },
+      );
+    }
+    if (!text.trim()) throw new RemoteError('intro-source-failed', `${repo} 的 ${skillPath} 是空文件`);
+    return { text, bytes, source: repo, ref: ref.toLowerCase(), skillPath };
+  } catch (error) {
+    if (error instanceof RemoteError) throw error;
+    if (controller.signal.aborted) {
+      throw new RemoteError('intro-source-timeout', `读取 ${repo} 的 SKILL.md 超时（${timeoutMs}ms）`, { cause: error });
+    }
+    throw new RemoteError('intro-source-failed', `读取 ${repo} 的 SKILL.md 失败：${error?.message || '网络错误'}`, {
+      cause: error,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/lib/core/service.js

@@ -39,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;
 
@@ -260,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;
@@ -302,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() {
@@ -956,6 +1171,8 @@ export function createService({
           support: INVOCATION_SUPPORT,
           modes: ['auto', 'manual', 'hidden'],
         },
+        // 技能介绍（模型生成）：前端据此决定按钮显隐；可用 ≠ 已登录，失败会在生成时如实报错
+        intro: introCapability(),
         agents: { all: registry.all(), detected: detectedTargets() },
         subscriptions: state().subscriptions,
         workspaces: await workspaceList(),
@@ -1148,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);

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 一打开就该是「停用 = 真不可见」，而不是等用户点到某一行才发现。