dsh-plugin-tool-management 0.17.0 → 0.18.0

package/lib/skills/skill-roots.js

@@ -0,0 +1,287 @@
+// 技能来源与路径底座：四个用户级来源、项目级来源、各类 root/state/trash 路径的推导，
+// 以及「这条路径算不算在那个来源里」的比较口径。
+//
+// 声明从 skills/core.ts 按行号区间搬来，正文一字未改（唯一的容差是 `--export-top-level`
+// 加的 `export ` 前缀，moved-verify 逐字对拍）。
+//
+// 为什么先剥这一层：core.ts 里往上数的每一个域（manager 状态、启停策略、导入链路、上传、
+// 回收站）都落在这组路径函数上，而它们自己只向下引 ./official.js / ./homes.js / node:*。
+// 于是这一层搬出去是**单向**的：core.js 引它，它不引 core.js，加载图无环。
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
+import { lstatOrNull, pathIdentity } from "./core-util.js";
+import { OFFICIAL_SOURCE_KEY, officialSkillRoot } from "./official.js";
+import { resolveAgentsHome, resolveDshHome } from "./homes.js";
+import { isSameOrDescendant } from "../paths.js";
+export function userRoots() {
+    const official = officialSkillRoot();
+    return [
+        {
+            key: "dsh",
+            path: join(resolveDshHome(), "skills"),
+            label: "DSH 技能",
+            mutable: true,
+            // 默认来源：路径不可移除、不可停用（必须读取），但里面的技能可删（见 isDefaultSkillSource）。
+            deletable: true,
+            // 注意：`toggleable` 指的是「这个来源里的**单个技能**能否启停」，与来源开关无关 ——
+            // 来源层的启停/移除由 isDefaultSkillSource 判定，两者别混。
+            toggleable: true,
+            native: true,
+            rank: 400,
+        },
+        // 官方内置紧随 DSH 技能之后（用户裁定）：同为一眼要看的来源，排在导入技能之前。
+        ...(official === null ? [] : [official]),
+        {
+            // v0.4：插件**新建/导入**的技能落到 hub 内（用户要求：插件产生的文件收在
+            // $DSH_HOME/tool-management/）。rank 高于 DSH 技能，同名时 hub 版本遮蔽官方目录里的；
+            // 官方 ~/.dsh/skills/ 仍作为可切换来源列出（不搬走、不删）。
+            //
+            // 界面名「导入技能」：它是插件导入/新建技能的落点，不是"管理器自己的一类技能"。
+            // 与 dsh 同为默认来源：路径必须读取（不可移除、不可停用），里面的技能可删。
+            key: "hub",
+            path: join(resolveDshHome(), "tool-management", "skills"),
+            label: "导入技能",
+            localeKey: "hub",
+            mutable: true,
+            deletable: true,
+            toggleable: true,
+            native: false,
+            rank: 350,
+        },
+        {
+            key: "agents",
+            path: join(resolveAgentsHome(), "skills"),
+            label: "公共 Agent",
+            mutable: false,
+            toggleable: true,
+            native: true,
+            rank: 450,
+        },
+        {
+            key: "codex",
+            path: join(process.env.DSH_CODEX_HOME || join(homedir(), ".codex"), "skills"),
+            label: "Codex",
+            mutable: false,
+            toggleable: true,
+            native: false,
+            rank: 520,
+        },
+        {
+            key: "claude",
+            path: join(process.env.DSH_CLAUDE_HOME || join(homedir(), ".claude"), "skills"),
+            label: "Claude",
+            mutable: false,
+            toggleable: true,
+            native: false,
+            rank: 530,
+        },
+    ];
+}
+export const DEFAULT_SOURCE_KEYS = Object.freeze(["dsh", "hub", OFFICIAL_SOURCE_KEY]);
+export function isDefaultSkillSource(rootOrKey) {
+    const key = rootOrKey && typeof rootOrKey === "object"
+        ? rootOrKey.key
+        : rootOrKey;
+    return DEFAULT_SOURCE_KEYS.includes(key);
+}
+export function projectIdentity(path) {
+    const canonical = pathIdentity(path);
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+export function customRootKey(path) {
+    return "custom-" + projectIdentity(path);
+}
+export async function nearestProjectRoot(cwd) {
+    if (typeof cwd !== "string" || !isAbsolute(cwd))
+        return null;
+    let start;
+    try {
+        start = await fs.realpath(resolve(cwd));
+        if (!(await fs.stat(start)).isDirectory())
+            return null;
+    }
+    catch (error) {
+        // 目录不存在（会话还开着、项目已被删）是最常见的一类：带上系统错误码，
+        // 调用方对 ENOENT 静默跳过 —— 报警留给真正读不了的目录。
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : undefined;
+        return { unavailable: true, cwd, ...(code ? { code } : {}) };
+    }
+    let current = start;
+    for (;;) {
+        try {
+            await fs.lstat(join(current, ".git"));
+            return { root: current, cwd: start };
+        }
+        catch {
+            /* 继续向上查找最近的项目根 */
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export async function projectSourceSafe(definition) {
+    // 只读来源允许目录链接，但重叠来源会绕过用户根的停用策略。
+    if (definition.kind === "project-agents")
+        return !(await overlapsUserSkillRoot(definition.path));
+    const container = join(definition.projectRoot, definition.kind === "project-dsh" ? ".dsh" : ".agents");
+    for (const path of [container, definition.path]) {
+        const st = await lstatOrNull(path);
+        if (st && (!st.isDirectory() || st.isSymbolicLink()))
+            return false;
+    }
+    return !(await overlapsUserSkillRoot(definition.path));
+}
+export async function projectRoots(projectCwds = [], diagnostics) {
+    const projects = new Map();
+    for (const cwd of Array.isArray(projectCwds) ? projectCwds : []) {
+        const found = await nearestProjectRoot(cwd);
+        if (!found || !found.root) {
+            // 目录不存在（ENOENT）= 会话开着、项目已删：这是常态而不是故障，静默跳过。
+            // 报警只留给真实读不了的目录（权限、损坏的链接等）。
+            if (found && found.unavailable && found.code === "ENOENT")
+                continue;
+            if (found &&
+                found.unavailable &&
+                Array.isArray(diagnostics) &&
+                typeof cwd === "string" &&
+                isAbsolute(cwd)) {
+                diagnostics.push({
+                    code: "warning.project.unavailable",
+                    params: { path: cwd },
+                    error: `活动会话的项目目录不可访问，项目技能未显示: ${cwd}`,
+                });
+            }
+            continue;
+        }
+        const identity = pathIdentity(found.root);
+        const existing = projects.get(identity) || {
+            root: found.root,
+            cwds: new Set(),
+        };
+        existing.cwds.add(found.cwd);
+        projects.set(identity, existing);
+    }
+    const roots = [];
+    for (const project of [...projects.values()].sort((a, b) => a.root.localeCompare(b.root))) {
+        const id = projectIdentity(project.root);
+        const common = {
+            mutable: false,
+            // 未知/只读来源（外部 Agent 与自定义绝对路径）一律不可删；用户级 dsh / hub
+            // 与本仓库的项目级 .dsh/skills 都是可删的（见上方两处 `deletable: true`）。
+            deletable: false,
+            toggleable: false,
+            native: true,
+            scope: "project",
+            projectRoot: project.root,
+            projectName: basename(project.root) || project.root,
+            workspaceCwds: [...project.cwds].sort(),
+        };
+        const candidates = [
+            {
+                ...common,
+                key: `project-dsh:${id}`,
+                kind: "project-dsh",
+                localeKey: "projectDsh",
+                path: join(project.root, ".dsh", "skills"),
+                label: "Project DSH",
+                rank: 100,
+                mutable: true,
+                deletable: true,
+                toggleable: true,
+            },
+            {
+                ...common,
+                key: `project-agents:${id}`,
+                kind: "project-agents",
+                localeKey: "projectAgents",
+                path: join(project.root, ".agents", "skills"),
+                label: "Project Agent",
+                rank: 200,
+                toggleable: true,
+            },
+        ];
+        for (const candidate of candidates) {
+            if (await projectSourceSafe(candidate))
+                roots.push(candidate);
+        }
+    }
+    return roots;
+}
+export function managerHomePath() {
+    return join(resolveDshHome(), "tool-management");
+}
+export function managerStatePath() {
+    return join(managerHomePath(), "skills-state.json");
+}
+export function trashRootPath() {
+    return join(managerHomePath(), "trash", "skills-trash");
+}
+export function dshRootPath() {
+    // userRoots() 恒含 dsh 来源（见上方列表），断言只为让类型收敛。
+    return userRoots().find((root) => root.key === "dsh").path;
+}
+export function skillCreateRootPath() {
+    const hub = userRoots().find((root) => root.key === "hub");
+    return hub && hub.path ? hub.path : dshRootPath();
+}
+export function readonlyError(action) {
+    return {
+        ok: false,
+        code: "error.root.readonly",
+        params: { action },
+        error: action === "delete"
+            ? "该技能来源不允许删除"
+            : "该技能来源不允许启用或停用",
+    };
+}
+export function rootDefinition(root) {
+    if (root && typeof root === "object" && typeof root.key === "string")
+        return root;
+    if (typeof root !== "string")
+        return null;
+    const resolved = resolve(root);
+    return userRoots().find((item) => resolve(item.path) === resolved) || null;
+}
+export function rootByKey(key) {
+    return userRoots().find((item) => item.key === key) || null;
+}
+export async function resolvedPath(path) {
+    try {
+        return await fs.realpath(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+export async function comparisonPath(path) {
+    let current = resolve(path);
+    const missing = [];
+    for (;;) {
+        try {
+            return resolve(await fs.realpath(current), ...missing);
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return resolve(path);
+            missing.unshift(basename(current));
+            current = parent;
+        }
+    }
+}
+export async function overlapsUserSkillRoot(path) {
+    const candidate = await comparisonPath(path);
+    for (const root of userRoots()) {
+        const userPath = await comparisonPath(root.path);
+        if (isSameOrDescendant(candidate, userPath) ||
+            isSameOrDescendant(userPath, candidate))
+            return true;
+    }
+    return false;
+}

package/lib/skills/skill-trash.js

@@ -0,0 +1,265 @@
+// 技能回收站：可写根目录的判定、把条目移进/移出回收站的落盘动作，与回收站清单的读写。
+//
+// 声明从 skills/core.ts 按行号区间搬来，正文一字未改（唯一的容差是 `--export-top-level`
+// 加的 `export ` 前缀，moved-verify 逐字对拍）。
+//
+// 与 ./system-trash.ts 不是一回事：那一层管的是**操作系统**回收站（把删掉的东西交给
+// explorer / Finder / gio），这一层管的是本插件自己的 `~/.dsh/tool-management/trash/`。
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { isSameOrDescendant } from "../paths.js";
+import { codedError, entryPath, lstatOrNull, pathIdentity, renameWithRetry, } from "./core-util.js";
+import { dshRootPath, overlapsUserSkillRoot, projectIdentity, projectRoots, readonlyError, rootByKey, rootDefinition, skillCreateRootPath, trashRootPath, } from "./skill-roots.js";
+export function writableRootDefinition(root) {
+    const definition = rootDefinition(root);
+    if (!definition || definition.mutable !== true)
+        return null;
+    if (definition.key === "dsh")
+        return resolve(definition.path) === resolve(dshRootPath())
+            ? rootByKey("dsh")
+            : null;
+    // v0.4：hub 内技能目录同为用户级可写根（插件新建/导入的落点）。
+    if (definition.key === "hub")
+        return resolve(definition.path) === resolve(skillCreateRootPath())
+            ? rootByKey("hub")
+            : null;
+    if (definition.scope !== "project" ||
+        definition.kind !== "project-dsh" ||
+        typeof definition.projectRoot !== "string" ||
+        !isAbsolute(definition.projectRoot) ||
+        definition.key !==
+            `project-dsh:${projectIdentity(definition.projectRoot)}` ||
+        resolve(definition.path) !==
+            resolve(join(definition.projectRoot, ".dsh", "skills")))
+        return null;
+    return definition;
+}
+export async function checkedWritableRootDefinition(root) {
+    const definition = writableRootDefinition(root);
+    if (!definition || definition.scope !== "project")
+        return definition;
+    if (await overlapsUserSkillRoot(definition.path)) {
+        return {
+            ok: false,
+            error: `项目技能目录与用户技能目录重叠，拒绝写入: ${definition.path}`,
+            code: "error.root.unsafe",
+            params: { path: definition.path },
+        };
+    }
+    // 项目仓库内容不可信；拒绝通过 .dsh 或 skills 链接把写入重定向到项目之外。
+    // definition.scope === "project" 时 projectRoot 必有值（见 ProjectSource），断言只为让类型收敛。
+    for (const path of [
+        join(definition.projectRoot, ".dsh"),
+        definition.path,
+    ]) {
+        const st = await lstatOrNull(path);
+        if (st && (!st.isDirectory() || st.isSymbolicLink())) {
+            return {
+                ok: false,
+                error: `项目技能目录不安全，拒绝写入: ${path}`,
+                code: "error.root.unsafe",
+                params: { path },
+            };
+        }
+    }
+    return definition;
+}
+export async function removeMovedPath(path) {
+    const st = await lstatOrNull(path);
+    if (!st)
+        return;
+    if (st.isDirectory() && !st.isSymbolicLink())
+        await fs.rm(path, { recursive: true, force: false });
+    else
+        await fs.unlink(path);
+}
+export async function movePathWithFallback(source, destination, options = {}) {
+    try {
+        await renameWithRetry(source, destination, options);
+        return { copied: false, cleanupError: null };
+    }
+    catch (error) {
+        // 系统异常按可选 code 读取，保持既有 EXDEV 判定。
+        if (!error || error.code !== "EXDEV")
+            throw error;
+    }
+    const quarantine = join(dirname(source), `.${basename(source)}.dssm-move-${randomUUID()}`);
+    try {
+        await fs.cp(source, destination, {
+            recursive: true,
+            dereference: false,
+            errorOnExist: true,
+            force: false,
+            verbatimSymlinks: true,
+        });
+        // 源与 quarantine 位于同一目录；成功后原技能名立即消失，避免递归删除留下半份可见条目。
+        await renameWithRetry(source, quarantine, options);
+    }
+    catch (error) {
+        await removeMovedPath(destination).catch(() => undefined);
+        throw error;
+    }
+    let cleanupError = null;
+    try {
+        await removeMovedPath(quarantine);
+    }
+    catch (error) {
+        // 调用方按可选 message 读取该清理异常，保持既有告警文案。
+        cleanupError = error;
+    }
+    return { copied: true, cleanupError, quarantine };
+}
+export async function safeExistingEntryPaths(root, name) {
+    const paths = [];
+    const bundle = entryPath(root, name);
+    if (bundle === null)
+        return paths;
+    const flat = resolve(root, `${name}.md`);
+    const bundleStat = await lstatOrNull(bundle);
+    if (bundleStat && (bundleStat.isDirectory() || bundleStat.isSymbolicLink()))
+        paths.push({ path: bundle, fileName: name, recursive: true });
+    const flatStat = await lstatOrNull(flat);
+    if (flatStat && (flatStat.isFile() || flatStat.isSymbolicLink()))
+        paths.push({ path: flat, fileName: `${name}.md`, recursive: false });
+    return paths;
+}
+export async function readTrashMetadata(id) {
+    if (entryPath(trashRootPath(), id) === null)
+        return null;
+    try {
+        const value = JSON.parse(await fs.readFile(join(trashRootPath(), id, "metadata.json"), "utf8"));
+        if (!value ||
+            value.id !== id ||
+            typeof value.name !== "string" ||
+            !Array.isArray(value.entries))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export function trashRootMetadata(definition) {
+    if (definition.scope !== "project")
+        return { key: definition.key, scope: "user", label: definition.label };
+    return {
+        key: definition.key,
+        scope: "project",
+        kind: "project-dsh",
+        projectRoot: definition.projectRoot,
+        projectName: definition.projectName,
+        label: definition.label,
+    };
+}
+export async function restoreRootDefinition(metadata, options = {}) {
+    // version 1 entries predate scoped Trash and always belong to $DSH_HOME/skills.
+    if (!metadata.root)
+        return rootByKey("dsh");
+    // 用户级来源按 key 重新解析：路径来自 userRoots()，不信元数据里记住的 path
+    // （DSH_HOME 换过之后，旧路径可能已经不在读取范围内了）。
+    if (metadata.root.scope === "user")
+        return rootByKey(metadata.root.key);
+    if (metadata.root.scope !== "project" ||
+        metadata.root.kind !== "project-dsh" ||
+        typeof metadata.root.key !== "string" ||
+        typeof metadata.root.projectRoot !== "string" ||
+        !isAbsolute(metadata.root.projectRoot))
+        return {
+            ok: false,
+            error: `回收站条目来源非法: ${metadata.id}`,
+            code: "error.trash.invalid",
+            params: { id: metadata.id },
+        };
+    const roots = await projectRoots(options.projectCwds);
+    const normalizedProjectRoot = pathIdentity(metadata.root.projectRoot);
+    const root = roots.find((item) => item.key === metadata.root.key &&
+        item.kind === "project-dsh" &&
+        pathIdentity(item.projectRoot) === normalizedProjectRoot);
+    if (!root) {
+        return {
+            ok: false,
+            error: `原项目当前不在活动工作区中，无法恢复: ${metadata.root.projectRoot}`,
+            code: "error.trash.projectUnavailable",
+            params: { path: metadata.root.projectRoot },
+        };
+    }
+    return checkedWritableRootDefinition(root);
+}
+export async function listTrash() {
+    let items;
+    try {
+        items = await fs.readdir(trashRootPath(), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const result = [];
+    for (const item of items) {
+        if (!item.isDirectory() || item.name.startsWith("."))
+            continue;
+        const metadata = await readTrashMetadata(item.name);
+        if (metadata)
+            result.push(metadata);
+    }
+    return result.sort((a, b) => String(b.deletedAt).localeCompare(String(a.deletedAt)));
+}
+export async function restoreTrash(id, log, options = {}) {
+    const metadata = await readTrashMetadata(id);
+    if (!metadata)
+        return {
+            ok: false,
+            error: `回收站条目不存在: ${id}`,
+            code: "error.trash.notFound",
+            params: { id },
+        };
+    const definition = await restoreRootDefinition(metadata, options);
+    if (!definition || definition.ok === false)
+        return definition || readonlyError("restore");
+    const root = definition.path;
+    const conflicts = await safeExistingEntryPaths(root, metadata.name);
+    if (conflicts.length)
+        return {
+            ok: false,
+            error: `无法恢复，同名技能已存在: ${metadata.name}`,
+            code: "error.trash.conflict",
+            params: { name: metadata.name },
+        };
+    await fs.mkdir(root, { recursive: true });
+    const itemRoot = join(trashRootPath(), id);
+    const moved = [];
+    try {
+        for (const fileName of metadata.entries) {
+            const source = join(itemRoot, fileName);
+            const destination = join(root, fileName);
+            if (!isSameOrDescendant(itemRoot, source) ||
+                !isSameOrDescendant(root, destination))
+                throw codedError("回收站条目路径非法", "error.trash.invalid", { id });
+            await movePathWithFallback(source, destination, options.renameOptions);
+            moved.push({ source, destination });
+        }
+        await fs.rm(itemRoot, { recursive: true, force: true });
+        if (log)
+            log("restore", `从回收站恢复 ${metadata.name} -> ${root}`);
+        return { id, name: metadata.name, root: trashRootMetadata(definition) };
+    }
+    catch (error) {
+        for (const item of moved.reverse())
+            await movePathWithFallback(item.destination, item.source, options.renameOptions).catch(() => undefined);
+        throw error;
+    }
+}
+export async function permanentlyDeleteTrash(id, log) {
+    const metadata = await readTrashMetadata(id);
+    if (!metadata)
+        return {
+            ok: false,
+            error: `回收站条目不存在: ${id}`,
+            code: "error.trash.notFound",
+            params: { id },
+        };
+    await fs.rm(join(trashRootPath(), id), { recursive: true, force: true });
+    if (log)
+        log("trash-delete", `永久删除回收站条目 ${metadata.name} (${id})`);
+    return { id, name: metadata.name };
+}

package/lib/skills/system-trash.js

@@ -0,0 +1,97 @@
+// 系统回收站：永久删除前的最后一道保险（Win 走 PowerShell、macOS 移进 ~/.Trash、Linux 用 gio）。
+//
+// 从 skills/service.ts 整段搬来，一行未改。这一层只跟外部进程打交道，不认识技能也不碰状态；
+// 外部命令一律带超时上限，失败返回 false 而不是抛出 —— 调用方据此决定要不要继续真删。
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { rename } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { isSameOrDescendant, isValidSegment } from '../paths.js';
+import { permanentlyDeleteTrash, trashRootPath } from './core.js';
+// ── 系统回收站（永久删除的最后一道保险） ──────────────────────────────────
+/**
+ * 外部进程（PowerShell / gio）的超时上限。这些调用在技能的**写队列**里被 await
+ * （skill-trash-delete），进程一旦挂起，该域全部写操作会永久停摆且无任何提示 ——
+ * 回收站 API 在文件被占用、系统弹窗等情况下确实会挂住。超时后杀掉进程并返回 false，
+ * 让调用方按既有的「回收站失败 → 硬删除」兜底走下去，队列得以继续。
+ */
+export const EXTERNAL_CMD_TIMEOUT_MS = 30_000;
+export function runQuietly(command, args) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer = null;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            resolve(ok);
+        };
+        let child;
+        try {
+            child = spawn(command, args, { stdio: 'ignore', windowsHide: true });
+        }
+        catch {
+            finish(false);
+            return;
+        }
+        timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* 进程可能已自行退出 */ }
+            finish(false);
+        }, EXTERNAL_CMD_TIMEOUT_MS);
+        child.on('error', () => finish(false));
+        child.on('close', (code) => finish(code === 0));
+    });
+}
+export function psQuote(value) {
+    return "'" + String(value).replace(/'/g, "''") + "'";
+}
+/** Win → 回收站；macOS → ~/.Trash；Linux → gio trash。失败返回 false。 */
+export async function moveToSystemTrash(abs) {
+    try {
+        if (process.platform === 'win32') {
+            const script = [
+                'Add-Type -AssemblyName Microsoft.VisualBasic',
+                "[Microsoft.VisualBasic.FileIO.FileSystem]::DeleteDirectory(" + psQuote(abs) + ", 'OnlyErrorDialogs', 'SendToRecycleBin')",
+            ].join('; ');
+            return await runQuietly('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script]);
+        }
+        if (process.platform === 'darwin') {
+            await rename(abs, join(homedir(), '.Trash', basename(abs) + '-' + Date.now()));
+            return true;
+        }
+        return await runQuietly('gio', ['trash', abs]);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 永久删除回收站条目：先尝试系统回收站（用户仍可在系统里找回），
+ * 失败才落到 core 的硬删除 —— 让「永久删除」也不会静默丢数据。
+ */
+export async function permanentlyDeleteTrashSafely(id, log) {
+    const clean = String(id || '').trim();
+    const root = trashRootPath();
+    // 走 `paths.ts` 的单段名校验，而不是自写白名单（审查 F1，0.17.0）：
+    // 原判据 `/^[A-Za-z0-9._-]{1,128}$/` 放行 `.` 与 `..`，而 `root + sep + '..'` 解析后
+    // 正是**回收站根目录**，末尾那句字符串前缀比对拦不住它 —— 于是「删掉某一条」变成
+    // 「把整个 `trash/`（技能/场景/子智能体/提示词四类）送进系统回收站」，且返回 `ok:true`。
+    // 换成 `isValidSegment` 还让两条路同源：能通过这里的 id，必定也能通过
+    // `permanentlyDeleteTrash` 内部的 `entryPath`（同一个谓词），不会一个放行、一个拒绝。
+    const target = isValidSegment(clean) ? join(root, clean) : null;
+    if (target && isSameOrDescendant(root, target) && existsSync(target)) {
+        if (await moveToSystemTrash(target)) {
+            await log('trash-delete-system', { id: clean, path: target });
+            return { id: clean, method: 'system-trash' };
+        }
+    }
+    return permanentlyDeleteTrash(clean, log);
+}