@morehao/dsh-skills-console 0.3.0 → 0.3.2

package/lib/core/inventory.js

@@ -75,7 +75,7 @@ export function readFrontmatterDescription(skillPath) {
   }
 }
 
-function statusOf({ install, check, locallyModified, brokenLinks }) {
+function statusOf({ install, check, locallyModified, brokenLinks, subscribed }) {
   if (!install) return 'unmanaged';
   if (locallyModified && check?.status === 'update-available') return 'conflict';
   if (locallyModified) return 'locally-modified';
@@ -83,6 +83,9 @@ function statusOf({ install, check, locallyModified, brokenLinks }) {
   if (check?.status === 'update-available') return 'update-available';
   if (brokenLinks.length > 0) return 'broken-link';
   if (check?.status === 'current') return 'current';
+  // 没有可用的上游订阅 = 永远拿不到更新结论（检查更新只覆盖有订阅的技能）。
+  // 这跟「这次没判定出来」是两件事，混进 unknown 会让待检查计数永远降不下来。
+  if (!subscribed) return 'no-upstream';
   return 'unknown';
 }
 
@@ -94,6 +97,9 @@ export function buildLedger({ paths, state, registry, lock, visibleNames = new M
   const scanned = scanCanonical(paths);
   const targets = registry.detected();
   const installs = new Map(state.installs.map((item) => [item.name, item]));
+  // 只有「state 里真有这条订阅记录」才算可检查：订阅被删掉（keepInstalled）后
+  // install.subscriptionId 会指向一个不存在的 id，那种行同样永远等不到结论。
+  const subscriptions = new Set((state.subscriptions || []).map((item) => item.id));
 
   const rows = scanned.map((entry) => {
     const install = installs.get(entry.name);
@@ -129,6 +135,7 @@ export function buildLedger({ paths, state, registry, lock, visibleNames = new M
 
     const check = state.checks?.[entry.name] || null;
     const visibleSource = visibleNames.get(entry.name);
+    const subscribed = Boolean(install?.subscriptionId) && subscriptions.has(install.subscriptionId);
     return {
       name: entry.name,
       path: entry.path,
@@ -155,7 +162,7 @@ export function buildLedger({ paths, state, registry, lock, visibleNames = new M
       backup: install?.backup ?? null,
       links,
       brokenLinks: brokenLinks.length,
-      status: statusOf({ install, check, locallyModified, brokenLinks }),
+      status: statusOf({ install, check, locallyModified, brokenLinks, subscribed }),
       check,
       visible: visibleNames.has(entry.name),
       visibleSource: visibleSource ?? null,

package/lib/core/service.js

@@ -7,6 +7,7 @@ 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 { readSkillFile, readSkillTree, resolveSkillRoot, SkillFileError } from './skill-files.js';
 import {
   checkSkill,
   fetchDefaultBranch,
@@ -35,6 +36,23 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+/**
+ * 上次检查是否已经得出可用结论。`unknown` 不是结论（是「没能判定」），
+ * 所以 304 时不能拿它当「上次结论」沿用，否则待检查会一直粘着。
+ */
+function isSettledCheck(check) {
+  const status = check?.status;
+  return status === 'current' || status === 'update-available' || status === 'upstream-deleted';
+}
+
+/** 读取层错误 → ServiceError（路由只认 ServiceError → 400），保留原 code / detail。 */
+function skillFileFailure(error) {
+  if (error instanceof SkillFileError) {
+    return new ServiceError(error.code, error.message, error.detail ?? null);
+  }
+  return error;
+}
+
 /** 路由参数里的技能名：在拼任何路径之前先校验，拒绝穿越/分隔符/控制字符。 */
 function assertSafeSkillName(name) {
   if (
@@ -710,22 +728,52 @@ export function createService({
       return { ok: true, ...linkSkill(skill, targets, { scopeProjects }) };
     },
 
-    async listSkillBody({ name }) {
-      const candidateDirs = [path.join(paths.canonical, name), path.join(paths.canonical, `${name}.md`)];
-      for (const candidate of candidateDirs) {
-        try {
-          const stat = fs.statSync(candidate);
-          if (stat.isDirectory()) {
-            const body = await fs.promises.readFile(path.join(candidate, 'SKILL.md'), 'utf8');
-            return { ok: true, name, content: body, path: path.join(candidate, 'SKILL.md') };
-          }
-          const body = await fs.promises.readFile(candidate, 'utf8');
-          return { ok: true, name, content: body, path: candidate };
-        } catch {
-          // 继续找下一种形态
-        }
+    /**
+     * 读技能正文 / 单个文件（只读）：`path` 是技能根内的相对路径，省略时读 SKILL.md（平铺读 `<name>.md`）。
+     * 技能名与相对路径都在拼路径之前校验；越界一律 400，不落文件系统。
+     */
+    async listSkillBody({ name, path: relPath }) {
+      assertSafeSkillName(name);
+      try {
+        const root = await resolveSkillRoot(paths, name);
+        const file = await readSkillFile({ root: root.root, kind: root.kind, relPath });
+        return {
+          ok: true,
+          name,
+          kind: root.kind,
+          relPath: file.relPath,
+          path: file.path,
+          content: file.content,
+          meta: parseSkillFrontmatter(file.content),
+          size: file.size,
+          truncated: file.truncated,
+          mtime: file.mtime,
+        };
+      } catch (error) {
+        throw skillFileFailure(error);
+      }
+    },
+
+    /** 列技能目录的文件树（只读，不跟随符号链接）。 */
+    async listSkillFiles({ name }) {
+      assertSafeSkillName(name);
+      try {
+        const root = await resolveSkillRoot(paths, name);
+        const tree = await readSkillTree({ root: root.root, kind: root.kind });
+        return {
+          ok: true,
+          name,
+          root: tree.root,
+          kind: tree.kind,
+          body: tree.body,
+          hasSkillMd: tree.hasSkillMd,
+          files: tree.files,
+          totalBytes: tree.totalBytes,
+          truncated: tree.truncated,
+        };
+      } catch (error) {
+        throw skillFileFailure(error);
       }
-      throw new ServiceError('error.skills.not-found', `${name} 不在 canonical 里`);
     },
 
     /**
@@ -1238,6 +1286,30 @@ export function createService({
           }
           continue;
         }
+        // 304 只说明「树没变」，它本身不含任何树内容，能不能沿用取决于**上次有没有结论**。
+        // 上次是 unknown（更早一次探测失败留下的）时，沿用就等于把「待检查」永久粘住：
+        // 用户点多少次刷新都还是 unknown。此时只能无视 ETag 完整读一次，才拿得到真判定。
+        if (probe.notModified && groupInstalls.some((install) => !isSettledCheck(state().checks?.[install.name]))) {
+          try {
+            probe = await readSnapshot(subscription, {
+              force: true,
+              withCommit: false,
+              persistRef: true,
+              allowUnchanged: false,
+            });
+          } catch (error) {
+            for (const install of groupInstalls) {
+              results.push({
+                name: install.name,
+                status: 'unknown',
+                detail: error.message,
+                code: error.code || null,
+                checkedAt: nowIso(),
+              });
+            }
+            continue;
+          }
+        }
         if (probe.notModified) {
           for (const install of groupInstalls) {
             const previousCheck = state().checks?.[install.name];

package/lib/core/skill-files.js

@@ -0,0 +1,336 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isUtf8 } from 'node:buffer';
+
+import { isInside } from './paths.js';
+
+/**
+ * 技能正文/文件的只读读取层：只做文件系统，不依赖 service，避免循环引用。
+ *
+ * 安全边界（与 AGENTS.md「不接收任意路径」一致）：
+ * - 根只从 canonical 反查：`<canonical>/<name>/` 或 `<canonical>/<name>.md`，不接受外部路径；
+ * - 相对路径逐段校验，拒绝绝对路径 / 盘符 / 反斜杠 / NUL / `..`；
+ * - lexic 包含判断 + realpath 包含判断双保险，符号链接一律不跟随（`lstat` + `O_NOFOLLOW` + `fstat`）；
+ * - 只读：本模块从不写 canonical / lock。
+ *
+ * 错误一律抛 SkillFileError，由 Service 包成 ServiceError（HTTP 400）。
+ */
+
+/** 单文件读取上限：超出只读前 256KB，并置 `truncated`。 */
+export const MAX_FILE_BYTES = 256 * 1024;
+/** 文件树条目上限，超过置 `truncated`。 */
+export const MAX_TREE_ENTRIES = 500;
+/** 文件树递归深度上限。 */
+export const MAX_TREE_DEPTH = 8;
+/** 相对路径长度上限。 */
+export const MAX_REL_PATH = 300;
+/** 二进制嗅探窗口：前 8KB 出现 NUL 即视为二进制。 */
+const SNIFF_BYTES = 8 * 1024;
+
+/**
+ * 明确不预览的扩展名（图片 / 音视频 / 压缩包 / 字体 / 可执行与二进制数据）。
+ * 其余扩展名一律按内容判定：能解码成 UTF-8 且没有 NUL 就当源码显示，
+ * 这样 `.html` / `.jsx` / `.css` / 无扩展名的脚本也能看。
+ */
+export const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.icns', '.tif', '.tiff', '.avif', '.heic',
+  '.mp3', '.wav', '.m4a', '.flac', '.ogg', '.aac', '.mp4', '.mov', '.webm', '.avi', '.mkv',
+  '.zip', '.gz', '.tgz', '.tar', '.bz2', '.xz', '.7z', '.rar',
+  '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+  '.woff', '.woff2', '.ttf', '.otf', '.eot',
+  '.so', '.dylib', '.dll', '.exe', '.dmg', '.wasm', '.class', '.jar', '.o', '.a', '.pyc',
+  '.db', '.sqlite', '.sqlite3', '.ds_store',
+]);
+
+/** 文件树里永不进入的目录名。 */
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+
+export class SkillFileError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = 'SkillFileError';
+    this.code = code;
+    this.detail = detail ?? null;
+  }
+}
+
+function badPath(message, detail) {
+  return new SkillFileError('error.skills.bad-path', message, detail);
+}
+
+async function lstatOrNull(target) {
+  try {
+    return await fs.promises.lstat(target);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null;
+    throw new SkillFileError('error.skills.file-unreadable', `无法读取 ${target}`, error?.code || null);
+  }
+}
+
+/**
+ * 相对路径归一化：只接受技能根内的 POSIX 相对路径。
+ * `allowEmpty` 用于「默认读 SKILL.md」。
+ */
+export function normalizeRelPath(relPath, { allowEmpty = false } = {}) {
+  if (relPath === undefined || relPath === null) {
+    if (allowEmpty) return '';
+    throw badPath('缺少文件路径');
+  }
+  if (typeof relPath !== 'string') throw badPath('文件路径必须是字符串');
+  if (relPath.length === 0) {
+    if (allowEmpty) return '';
+    throw badPath('文件路径不能为空');
+  }
+  if (relPath.length > MAX_REL_PATH) throw badPath('文件路径过长');
+  if (relPath.includes('\u0000')) throw badPath('文件路径不能包含 NUL');
+  if (relPath.includes('\\')) throw badPath('文件路径不能包含反斜杠');
+  if (/^[A-Za-z]:/.test(relPath)) throw badPath('不接受绝对路径');
+  if (path.posix.isAbsolute(relPath)) throw badPath('不接受绝对路径');
+
+  const segments = relPath.split('/');
+  if (segments.some((segment) => segment === '..')) throw badPath('文件路径不能越出技能目录');
+
+  // 归一化后再检查一次：`a//b`、`./a` 之类的变体归一后仍必须留在根内
+  const normalized = path.posix.normalize(relPath);
+  if (normalized === '.') return allowEmpty ? '' : badPath('文件路径不能为空');
+  if (path.posix.isAbsolute(normalized) || normalized === '..' || normalized.startsWith('../')) {
+    throw badPath('文件路径不能越出技能目录');
+  }
+  if (normalized.split('/').includes('..')) throw badPath('文件路径不能越出技能目录');
+  return normalized;
+}
+
+/**
+ * 反查技能根：目录包（`<canonical>/<name>/`）或平铺（`<canonical>/<name>.md`）。
+ * 根自身是符号链接时直接拒绝（v1 不跟随根链）；两种形态都不存在 → not-found。
+ */
+export async function resolveSkillRoot(paths, name) {
+  const canonical = path.resolve(paths.canonical);
+  const dirPath = path.join(canonical, name);
+  const filePath = path.join(canonical, `${name}.md`);
+
+  const dirStat = await lstatOrNull(dirPath);
+  if (dirStat) {
+    if (dirStat.isSymbolicLink()) throw badPath(`${name} 在 canonical 里是符号链接，拒绝读取`);
+    if (dirStat.isDirectory()) {
+      return { name, kind: 'dir', root: dirPath, body: 'SKILL.md', canonical };
+    }
+  }
+
+  const fileStat = await lstatOrNull(filePath);
+  if (fileStat) {
+    if (fileStat.isSymbolicLink()) throw badPath(`${name}.md 是符号链接，拒绝读取`);
+    if (fileStat.isFile()) {
+      return { name, kind: 'file', root: filePath, body: path.basename(filePath), canonical };
+    }
+  }
+
+  throw new SkillFileError('error.skills.not-found', `${name} 不在 canonical 里`);
+}
+
+/** 把相对路径解析成受控的绝对路径；lexic 检查通过后再用 realpath 复核。 */
+async function resolveInside(root, relPath) {
+  const target = path.resolve(root, relPath);
+  if (!isInside(root, target)) throw badPath('文件路径越出技能目录', { relPath });
+  // realpath 复核：中间层目录可能是符号链接，lexic 判断看不出越界
+  let realRoot;
+  let realTarget;
+  try {
+    realRoot = await fs.promises.realpath(root);
+    realTarget = await fs.promises.realpath(target);
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new SkillFileError('error.skills.file-not-found', `${relPath} 不存在`);
+    if (error?.code === 'ELOOP') throw badPath('文件路径经过符号链接，拒绝读取');
+    throw new SkillFileError('error.skills.file-unreadable', `无法读取 ${relPath}`, error?.code || null);
+  }
+  if (!isInside(realRoot, realTarget)) throw badPath('文件路径越出技能目录', { relPath });
+  return target;
+}
+
+function notPreviewable(relPath, detail) {
+  return new SkillFileError('error.skills.binary', `${relPath} 暂不支持预览`, detail ?? null);
+}
+
+/** 内容判定：已知二进制扩展名直接拒绝；其余看前 8KB 有没有 NUL、整体能不能按 UTF-8 解码。 */
+function assertPreviewable(buffer, relPath, truncated = false) {
+  const ext = path.extname(relPath).toLowerCase();
+  if (BINARY_EXTENSIONS.has(ext)) throw notPreviewable(relPath, { ext });
+  const window = buffer.subarray(0, Math.min(buffer.length, SNIFF_BYTES));
+  if (window.includes(0)) throw notPreviewable(relPath, { reason: 'nul' });
+  // 截断缓冲区可能切在多字节字符中间：只验嗅探窗口，避免把正常文本误判成二进制
+  const sample = truncated ? window : buffer;
+  if (sample.length > 0 && !isUtf8(sample)) throw notPreviewable(relPath, { reason: 'encoding' });
+}
+
+/**
+ * 读单个文件。返回 `{ relPath, path, content, size, truncated, mtime }`，`size` 是真实大小。
+ * 平铺技能只允许读它自己那一个文件。
+ */
+export async function readSkillFile({ root, kind = 'dir', relPath }) {
+  const relative = normalizeRelPath(relPath, { allowEmpty: true });
+  let target;
+  let effective;
+
+  if (kind === 'file') {
+    const base = path.basename(root);
+    if (relative !== '' && relative !== base) {
+      throw badPath('平铺技能只有一个文件', { relPath: relative });
+    }
+    effective = base;
+    target = root;
+  } else {
+    effective = relative === '' ? 'SKILL.md' : relative;
+    try {
+      target = await resolveInside(root, effective);
+    } catch (error) {
+      // 目录包缺 SKILL.md 是最常见的状态，单独给一个码，前端据此提示「DSH 读不到这个技能」
+      if (error?.code === 'error.skills.file-not-found' && effective === 'SKILL.md') {
+        throw new SkillFileError('error.skills.no-skill-md', '这个技能目录里没有 SKILL.md');
+      }
+      throw error;
+    }
+  }
+
+  const stat = await lstatOrNull(target);
+  if (!stat) {
+    if (kind === 'dir' && effective === 'SKILL.md') {
+      throw new SkillFileError('error.skills.no-skill-md', '这个技能目录里没有 SKILL.md');
+    }
+    throw new SkillFileError('error.skills.file-not-found', `${effective} 不存在`);
+  }
+  if (stat.isSymbolicLink()) throw badPath(`${effective} 是符号链接，拒绝读取`);
+  if (!stat.isFile()) throw new SkillFileError('error.skills.not-a-file', `${effective} 不是普通文件`);
+
+  const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0);
+  let handle;
+  try {
+    handle = await fs.promises.open(target, flags);
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new SkillFileError('error.skills.file-not-found', `${effective} 不存在`);
+    if (error?.code === 'ELOOP') throw badPath(`${effective} 是符号链接，拒绝读取`);
+    if (error?.code === 'EISDIR') throw new SkillFileError('error.skills.not-a-file', `${effective} 不是普通文件`);
+    throw new SkillFileError('error.skills.file-unreadable', `无法读取 ${effective}`, error?.code || null);
+  }
+
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile()) throw new SkillFileError('error.skills.not-a-file', `${effective} 不是普通文件`);
+    const size = opened.size;
+    const truncated = size > MAX_FILE_BYTES;
+    const length = Math.min(size, MAX_FILE_BYTES);
+    const buffer = Buffer.alloc(length);
+    if (length > 0) await handle.read(buffer, 0, length, 0);
+    assertPreviewable(buffer, effective, truncated);
+    const decoded = buffer.toString('utf8');
+    return {
+      relPath: effective,
+      path: target,
+      content: decoded.startsWith('\uFEFF') ? decoded.slice(1) : decoded,
+      size,
+      truncated,
+      mtime: opened.mtime.toISOString(),
+    };
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
+/**
+ * 列技能目录的文件树：递归、深度 ≤ 8、条目 ≤ 500。
+ * 跳过符号链接、点文件、`node_modules`、`.git`；目录在前、文件在后，各自按名称排序。
+ * 平铺技能返回单文件树。
+ */
+export async function readSkillTree({ root, kind = 'dir' }) {
+  if (kind === 'file') {
+    const stat = await lstatOrNull(root);
+    if (!stat) throw new SkillFileError('error.skills.file-not-found', `${path.basename(root)} 不存在`);
+    if (stat.isSymbolicLink()) throw badPath(`${path.basename(root)} 是符号链接，拒绝读取`);
+    const name = path.basename(root);
+    const size = stat.size;
+    return {
+      root,
+      kind: 'file',
+      body: name,
+      hasSkillMd: true,
+      files: [{ path: name, kind: 'file', size }],
+      totalBytes: size,
+      truncated: false,
+    };
+  }
+
+  const files = [];
+  let totalBytes = 0;
+  let truncated = false;
+
+  async function walk(dir, prefix, depth) {
+    if (truncated) return;
+    if (depth > MAX_TREE_DEPTH) {
+      truncated = true;
+      return;
+    }
+    let dirents;
+    try {
+      dirents = await fs.promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const dirs = [];
+    const plain = [];
+    for (const dirent of dirents) {
+      const name = dirent.name;
+      if (!name || name.startsWith('.')) continue;
+      const rel = prefix ? `${prefix}/${name}` : name;
+      if (dirent.isSymbolicLink()) continue;
+      if (dirent.isDirectory()) {
+        if (SKIP_DIRS.has(name)) continue;
+        dirs.push({ name, rel });
+        continue;
+      }
+      if (!dirent.isFile()) continue;
+      plain.push({ name, rel });
+    }
+    dirs.sort((left, right) => left.name.localeCompare(right.name));
+    plain.sort((left, right) => left.name.localeCompare(right.name));
+
+    // 目录在前、文件在后：目录条目也占用上限名额，先占位再递归
+    for (const entry of dirs) {
+      if (files.length >= MAX_TREE_ENTRIES) {
+        truncated = true;
+        return;
+      }
+      files.push({ path: entry.rel, kind: 'dir' });
+      await walk(path.join(dir, entry.name), entry.rel, depth + 1);
+      if (truncated) return;
+    }
+
+    for (const entry of plain) {
+      if (files.length >= MAX_TREE_ENTRIES) {
+        truncated = true;
+        return;
+      }
+      let size = 0;
+      try {
+        const stat = await fs.promises.lstat(path.join(dir, entry.name));
+        if (!stat.isFile()) continue;
+        size = stat.size;
+      } catch {
+        continue;
+      }
+      totalBytes += size;
+      files.push({ path: entry.rel, kind: 'file', size });
+    }
+  }
+
+  await walk(root, '', 0);
+
+  const hasSkillMd = files.some((entry) => entry.kind === 'file' && entry.path === 'SKILL.md');
+  return {
+    root,
+    kind: 'dir',
+    body: hasSkillMd ? 'SKILL.md' : null,
+    hasSkillMd,
+    files,
+    totalBytes,
+    truncated,
+  };
+}

package/lib/routes.js

@@ -65,6 +65,9 @@ function matchRoute(method, pathname) {
   if (segments[0] === 'skills' && segments.length === 2 && method === 'GET') {
     return { name: 'skill.body', params: { name: decodeURIComponent(segments[1]) } };
   }
+  if (segments[0] === 'skills' && segments.length === 3 && segments[2] === 'files' && method === 'GET') {
+    return { name: 'skill.files', 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]) } };
   }
@@ -160,7 +163,9 @@ async function dispatch(route, { body, query, service }) {
     case 'diagnostics':
       return service.diagnostics();
     case 'skill.body':
-      return service.listSkillBody({ name: route.params.name });
+      return service.listSkillBody({ name: route.params.name, path: query.path });
+    case 'skill.files':
+      return service.listSkillFiles({ name: route.params.name });
     case 'skill.adopt':
       return service.adopt({ name: route.params.name });
     case 'skill.mode':

package/package.json

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