dsh-plugin-tool-management 0.16.6 → 0.18.0

package/lib/skills/dir-watch.js

@@ -0,0 +1,71 @@
+// 目录监听：外部改动 200ms 防抖后通知失效（技能来源与规则根目录共用同一份实现）。
+//
+// 从 skills/service.ts 整段搬来，一行未改。为什么走 worker_threads 而不是 fs.watch(recursive)
+// 写在它自己的注释里 —— Windows 上那条路会在目录被删除时静默卡死事件循环。
+import { existsSync } from 'node:fs';
+import { Worker } from 'node:worker_threads';
+// ── 文件监听：外部改动自动失效 ────────────────────────────────────────────
+/**
+ * 监听目录，200ms 防抖后回调：在编辑器或其他工具里新增/修改/删除文件后，无需手动
+ * 刷新即可看到变化。技能来源与规则根目录共用（见 src/memories/service.ts 的场景记忆段缓存）。
+ *
+ * 为什么用 worker_threads：Windows 上 fs.watch(recursive) 的句柄在「被监听
+ * 目录被删除」时会静默卡死事件循环（不触发 error、unref 也无效）——宿主
+ * 进程将永远无法退出。把 watcher 放进独立的 worker 线程，主线程对 worker
+ * unref()，无论目录发生什么，宿主与测试进程都能正常收尾；worker 内部失败
+ * 也不影响主线程。目录不存在或平台不支持递归监听时静默跳过。
+ */
+export function watchDirectories(paths, invalidate) {
+    const valid = paths.filter((dir) => dir && existsSync(dir));
+    if (!valid.length)
+        return () => { };
+    let timer = null;
+    const fire = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            try {
+                invalidate();
+            }
+            catch { /* 失效失败不影响监听 */ }
+        }, 200);
+    };
+    let worker = null;
+    try {
+        // eval 模式内联 worker 代码：无需额外文件与构建步骤。worker 事件循环独立，
+        // 主线程 unref 后完全不参与宿主进程的退出判定。
+        const src = `
+      const { watch } = require('node:fs');
+      const { parentPort, workerData } = require('node:worker_threads');
+      for (const dir of workerData.paths) {
+        try {
+          const w = watch(dir, { recursive: true, persistent: false }, () => {
+            try { parentPort.postMessage('change') } catch { /* worker 正在关闭 */ }
+          });
+          w.on('error', () => { /* 目录被移除等：忽略，不向主线程传播 */ });
+        } catch { /* 不可监听（权限/平台）时跳过该目录 */ }
+      }
+    `;
+        worker = new Worker(src, { eval: true, workerData: { paths: valid } });
+        worker.unref();
+        worker.on('message', () => fire());
+        worker.on('error', () => { });
+    }
+    catch { /* worker 不可用时静默跳过，功能退化为依赖 op 全量扫描 */ }
+    return () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (worker) {
+            const w = worker;
+            worker = null;
+            try {
+                w.removeAllListeners();
+                w.terminate();
+            }
+            catch { /* ignore */ }
+        }
+    };
+}

package/lib/skills/frontmatter.js

@@ -0,0 +1,96 @@
+// ── 命名规整 ────────────────────────────────────────────────────────────────
+/** 尽量把任意名称规整为 kebab-case；无法生成合法名称时返回空串。 */
+export function toKebab(s) {
+    let t = String(s).trim();
+    if (t === "")
+        return "";
+    t = t.replace(/([a-z0-9])([A-Z])/g, "$1-$2"); // camelCase 边界
+    t = t.toLowerCase();
+    t = t.replace(/[\s_.]+/g, "-");
+    t = t.replace(/[^a-z0-9-]/g, "-");
+    t = t.replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+    return t;
+}
+// ── frontmatter 解析 / 序列化（宽松 YAML 对象，保留键序）────────────────────
+/** 剥离 UTF-8 BOM（Windows 工具常写入，不剥离会导致开头 --- 失配）。 */
+export function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/** 解析 SKILL.md 的 frontmatter。返回 { fields, map, body }，map 保留键序。
+ *  只识别顶层 key: value；缩进嵌套字段（如 metadata.source）不进入 map。 */
+export function parseSkillDoc(text) {
+    const src = stripBom(String(text));
+    const lines = src.split(/\r?\n/);
+    const map = Object.create(null);
+    const fields = [];
+    let body = src;
+    let hasFrontmatter = false;
+    if (lines.length > 0 && lines[0].trim() === "---") {
+        let end = -1;
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === "---") {
+                end = i;
+                break;
+            }
+        }
+        if (end >= 0) {
+            hasFrontmatter = true;
+            for (let i = 1; i < end; i++) {
+                const m = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(lines[i]);
+                if (m) {
+                    fields.push({ key: m[1], raw: m[2] });
+                    const block = /^([>|])[-+]?\s*$/.exec(m[2]);
+                    if (block) {
+                        const content = [];
+                        while (i + 1 < end &&
+                            (/^\s/.test(lines[i + 1]) || lines[i + 1] === "")) {
+                            i++;
+                            content.push(lines[i]);
+                        }
+                        const indentation = content
+                            .filter((line) => line.trim() !== "")
+                            .reduce((min, line) => Math.min(min, (/^\s*/.exec(line) || [""])[0].length), Infinity);
+                        const normalized = content.map((line) => Number.isFinite(indentation)
+                            ? line.slice(Math.min(indentation, line.length))
+                            : line);
+                        map[m[1]] =
+                            block[1] === ">"
+                                ? normalized.join(" ").replace(/\s+/g, " ").trim()
+                                : normalized.join("\n").trim();
+                    }
+                    else {
+                        map[m[1]] = decodeYamlScalar(m[2]);
+                    }
+                }
+            }
+            body = lines.slice(end + 1).join("\n");
+        }
+    }
+    return { fields, map, body, hasFrontmatter };
+}
+/** 读取 YAML 标量的显示值；不依赖第三方 YAML 解析器。 */
+export function decodeYamlScalar(v) {
+    const s = String(v == null ? "" : v).trim();
+    if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+        try {
+            const value = JSON.parse(s);
+            if (typeof value === "string")
+                return value;
+        }
+        catch {
+            /* 保留无法解析的原始内容 */
+        }
+    }
+    if (s.length >= 2 && s[0] === "'" && s[s.length - 1] === "'")
+        return s.slice(1, -1).replace(/''/g, "'");
+    return s;
+}
+export function unquote(v) {
+    const s = String(v == null ? "" : v).trim();
+    if (s.length >= 2 &&
+        ((s[0] === '"' && s[s.length - 1] === '"') ||
+            (s[0] === "'" && s[s.length - 1] === "'"))) {
+        return s.slice(1, -1);
+    }
+    return s;
+}

package/lib/skills/homes.js

@@ -0,0 +1,14 @@
+// $DSH_HOME / ~/.agents 两个用户级 home 的解析。
+//
+// 单独一层是为了断环：core.ts 与 official.ts 都要读它，让它留在 core.ts 里就等于
+// official.ts 反向 import core.js。同目录已有先例（memories/constants.ts 也是为断环抽出）。
+// 两个函数的口径照旧读环境变量，没有引入任何新解析。
+import { homedir } from "node:os";
+import { join } from "node:path";
+// ── 路径解析 ────────────────────────────────────────────────────────────────
+export function resolveDshHome() {
+    return process.env.DSH_HOME || join(homedir(), ".dsh");
+}
+export function resolveAgentsHome() {
+    return process.env.DSH_AGENTS_HOME || join(homedir(), ".agents");
+}

package/lib/skills/import-pipeline.js

@@ -0,0 +1,231 @@
+// 导入预检链路：把来源目录读成候选清单、拒符号链接、拷进同目录临时件、原子替换目标。
+//
+// 声明从 skills/core.ts 按行号区间搬来，正文一字未改（唯一的容差是 `--export-top-level`
+// 加的 `export ` 前缀，moved-verify 逐字对拍）。
+//
+// 为什么这一层要独立：它是「导入」这条链的下半段，向下只引 ./core-util.js 与 node:* /
+// ../paths.js，**不回引 core.js** —— 所以 core.js 反过来引它是单向的，加载图无环。
+// 留在 core.ts 里时，任何想把上传/导入段搬出去的尝试都会撞到这个环上（0.18.0 试过一回，
+// 判给不做就是这个原因）。
+import { basename, dirname, join } from "node:path";
+import { promises as fs } from "node:fs";
+import { attachCode, codedError, lstatOrNull, renameWithRetry, temporaryPath } from "./core-util.js";
+import { toKebab } from "./frontmatter.js";
+export const MAX_SOURCE_DEPTH = 64;
+export async function analyzeSource(source) {
+    let st;
+    try {
+        st = await fs.lstat(source);
+    }
+    catch {
+        return {
+            kind: "none",
+            error: `路径不存在: ${source}`,
+            code: "error.source.notFound",
+            params: { path: source },
+        };
+    }
+    if (st.isSymbolicLink())
+        return {
+            kind: "none",
+            error: `不支持包含符号链接的 skill 来源: ${source}`,
+            code: "error.source.symlink",
+            params: { path: source },
+        };
+    if (st.isDirectory()) {
+        const sk = join(source, "SKILL.md");
+        const skSt = await lstatOrNull(sk);
+        // 预检与实际导入口径一致：SKILL.md 本身是链接时直接拒绝，避免 dry-run 通过、正式导入才失败。
+        if (skSt && skSt.isSymbolicLink())
+            return {
+                kind: "none",
+                error: `不支持包含符号链接的 skill 来源: ${sk}`,
+                code: "error.source.symlink",
+                params: { path: sk },
+            };
+        if (skSt && skSt.isFile()) {
+            return {
+                kind: "single",
+                rawName: basename(source),
+                kebab: toKebab(basename(source)),
+                source,
+                isDir: true,
+                skillFile: sk,
+            };
+        }
+        return { kind: "batch", rawName: basename(source), source, isDir: true };
+    }
+    if (st.isFile() && source.toLowerCase().endsWith(".md")) {
+        if (basename(source).toLowerCase() === "skill.md") {
+            const parent = dirname(source);
+            return {
+                kind: "single",
+                rawName: basename(parent),
+                kebab: toKebab(basename(parent)),
+                source: parent,
+                isDir: true,
+                skillFile: source,
+            };
+        }
+        const rawName = basename(source).slice(0, -3);
+        return {
+            kind: "single",
+            rawName,
+            kebab: toKebab(rawName),
+            source,
+            isDir: false,
+            skillFile: source,
+        };
+    }
+    return {
+        kind: "none",
+        error: `无法识别的 skill 来源: ${source}`,
+        code: "error.source.unrecognized",
+        params: { path: source },
+    };
+}
+export async function collectCandidates(dir) {
+    const items = await fs.readdir(dir, { withFileTypes: true });
+    const out = [];
+    for (const it of items) {
+        if (it.isSymbolicLink())
+            throw codedError(`不支持包含符号链接的 skill 来源: ${join(dir, it.name)}`, "error.source.symlink", { path: join(dir, it.name) });
+        if (it.isDirectory()) {
+            const sk = join(dir, it.name, "SKILL.md");
+            // lstatOrNull 吞掉 IO 异常（返回 null 即跳过）；symlink 必须抛出，不能被“跳过”逻辑掩盖。
+            const st = await lstatOrNull(sk);
+            if (st && st.isSymbolicLink())
+                throw codedError(`不支持包含符号链接的 skill 来源: ${sk}`, "error.source.symlink", { path: sk });
+            if (st && st.isFile()) {
+                out.push({
+                    source: join(dir, it.name),
+                    kebab: toKebab(it.name),
+                    rawName: it.name,
+                    isDir: true,
+                });
+            }
+        }
+        else if (it.isFile() &&
+            it.name.toLowerCase().endsWith(".md") &&
+            it.name.toLowerCase() !== "skill.md") {
+            out.push({
+                source: join(dir, it.name),
+                kebab: toKebab(it.name.slice(0, -3)),
+                rawName: it.name.slice(0, -3),
+                isDir: false,
+            });
+        }
+    }
+    return out;
+}
+export async function assertNoSymbolicLinks(source) {
+    const pending = [
+        { path: source, depth: 0 },
+    ];
+    while (pending.length) {
+        // while 条件保证栈非空，断言只为让类型收敛。
+        const current = pending.pop();
+        if (current.depth > MAX_SOURCE_DEPTH)
+            throw codedError(`skill 来源目录层级超过 ${MAX_SOURCE_DEPTH} 层: ${source}`, "error.source.tooDeep", { depth: MAX_SOURCE_DEPTH, path: source });
+        const st = await fs.lstat(current.path);
+        if (st.isSymbolicLink())
+            throw codedError(`不支持包含符号链接的 skill 来源: ${current.path}`, "error.source.symlink", { path: current.path });
+        if (!st.isDirectory())
+            continue;
+        const items = await fs.readdir(current.path, { withFileTypes: true });
+        for (const item of items) {
+            const path = join(current.path, item.name);
+            if (item.isSymbolicLink())
+                throw codedError(`不支持包含符号链接的 skill 来源: ${path}`, "error.source.symlink", { path });
+            if (item.isDirectory())
+                pending.push({ path, depth: current.depth + 1 });
+        }
+    }
+}
+export async function preflightCandidates(pending, conflicts, failed) {
+    for (const group of [pending, conflicts]) {
+        for (let i = group.length - 1; i >= 0; i--) {
+            const candidate = group[i];
+            try {
+                await assertNoSymbolicLinks(candidate.source);
+            }
+            catch (error) {
+                // 系统异常按可选 message 读取，保持既有失败明细文案。
+                failed.push(attachCode({
+                    source: candidate.source,
+                    error: String(error && error.message ? error.message : error),
+                }, error));
+                group.splice(i, 1);
+            }
+        }
+    }
+}
+export async function copyToTemporary(source, target, isDir) {
+    const temp = temporaryPath(target, "stage");
+    try {
+        await assertNoSymbolicLinks(source);
+        if (isDir)
+            await fs.cp(source, temp, { recursive: true, dereference: false });
+        else
+            await fs.copyFile(source, temp);
+        await assertNoSymbolicLinks(temp);
+        return temp;
+    }
+    catch (error) {
+        await fs.rm(temp, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export async function replaceWithCopy(source, dest, isDir, existing = []) {
+    const stage = await copyToTemporary(source, dest, isDir);
+    const backups = [];
+    // 三处 rename 一律走 `renameWithRetry`：瞬时占用（Windows 杀软 / 索引器 / 资源管理器）返回的
+    // EACCES / EBUSY / EPERM 正是它重试的那些码。此前只有 `:959` 的回滚用了带重试的版本，
+    // 而**发布与它的补偿回滚用的是裸 rename** —— 发布因瞬时锁抛错时，紧随其后的回滚在同一刻、
+    // 同一目录上大概率撞同一个句柄，于是留下"目标已空、真值还叫 backup"的半态（无自动恢复路径）。
+    // 保护覆盖不均不是取舍，是漏。
+    try {
+        for (const path of existing) {
+            const backup = temporaryPath(path, "backup");
+            await renameWithRetry(path, backup);
+            backups.push({ path, backup });
+        }
+        await renameWithRetry(stage, dest);
+    }
+    catch (error) {
+        // 系统异常按可选 message 读取，保持既有回滚失败明细。
+        await fs.rm(stage, { recursive: true, force: true }).catch(() => undefined);
+        const rollbackFailures = [];
+        for (const item of backups.reverse()) {
+            try {
+                await renameWithRetry(item.backup, item.path);
+            }
+            catch (rollbackError) {
+                rollbackFailures.push(item.backup);
+            }
+        }
+        if (rollbackFailures.length) {
+            const causeText = String(error && error.message ? error.message : error);
+            throw codedError(`${causeText}；覆盖导入回滚失败，备份保留在: ${rollbackFailures.join("、")}`, "error.import.rollbackFailed", { path: rollbackFailures.join("; "), error: causeText });
+        }
+        throw error;
+    }
+    const warnings = [];
+    for (const item of backups) {
+        try {
+            await fs.rm(item.backup, { recursive: true, force: true });
+        }
+        catch (error) {
+            // 系统异常按可选 message 读取，保持既有告警文案。
+            warnings.push({
+                code: "warning.backupUncleaned",
+                params: {
+                    path: item.backup,
+                    error: String(error && error.message ? error.message : error),
+                },
+                error: `旧版本备份未清理: ${item.backup}（${String(error && error.message ? error.message : error)}）`,
+            });
+        }
+    }
+    return warnings;
+}