dsh-plugin-tool-management 0.2.0 → 0.5.1

package/lib/skills/core.js

@@ -71,6 +71,22 @@ export function userRoots() {
             native: true,
             rank: 400,
         },
+        {
+            // v0.4：插件**新建/导入**的技能落到 hub 内（用户要求：插件产生的文件收在
+            // $DSH_HOME/tool-management/）。rank 高于 DSH 技能，同名时 hub 版本遮蔽官方目录里的；
+            // 官方 ~/.dsh/skills/ 仍作为可切换来源列出（不搬走、不删）。
+            //
+            // 界面名「导入技能」：它是插件导入/新建技能的落点，不是"管理器自己的一类技能"。
+            // **用户级来源不可删**（dsh / hub 都是）：技能只能停用，删除留给项目级来源。
+            key: "hub",
+            path: join(resolveDshHome(), "tool-management", "skills"),
+            label: "导入技能",
+            localeKey: "hub",
+            mutable: true,
+            toggleable: true,
+            native: false,
+            rank: 350,
+        },
         {
             key: "agents",
             path: join(resolveAgentsHome(), "skills"),
@@ -317,6 +333,9 @@ export async function projectRoots(projectCwds = [], diagnostics) {
         const id = projectIdentity(project.root);
         const common = {
             mutable: false,
+            // 项目级 DSH 根是**唯一**允许删除技能文件的来源；用户级来源（dsh / hub）一律不可删。
+            // 用「作用域」推导而不是再加一个平行开关：这是项目根与用户根的本质差别。
+            deletable: false,
             toggleable: false,
             native: true,
             scope: "project",
@@ -334,6 +353,7 @@ export async function projectRoots(projectCwds = [], diagnostics) {
                 label: "Project DSH",
                 rank: 100,
                 mutable: true,
+                deletable: true,
                 toggleable: true,
             },
             {
@@ -464,6 +484,14 @@ export async function browseDirectories(inputPath) {
 function dshRootPath() {
     return userRoots().find((root) => root.key === "dsh").path;
 }
+/**
+ * v0.4 新建/导入技能的落点：hub 内 `tool-management/skills/`（用户要求插件产物集中）。
+ * hub 根缺失（旧版本状态文件/异常）时退回官方 DSH 技能目录，保证创建功能永不因布局变化而失效。
+ */
+function skillCreateRootPath() {
+    const hub = userRoots().find((root) => root.key === "hub");
+    return hub && hub.path ? hub.path : dshRootPath();
+}
 /** 只读来源的拒绝结果；action 为可翻译语义值（toggle/delete）。 */
 function readonlyError(action) {
     return {
@@ -475,6 +503,19 @@ function readonlyError(action) {
             : "该技能来源不允许启用或停用",
     };
 }
+/**
+ * 来源可写但**不允许删除**时的拒绝结果（用户级 DSH 技能 / 导入技能）。
+ * 与「只读来源」区分开：这两种来源可以创建、可以停用，只是不提供删除 —— 提示要能说清
+ * 「你还能做什么」，否则用户会以为是权限坏了。
+ */
+function notDeletableError(definition) {
+    return {
+        ok: false,
+        code: "error.skill.notDeletable",
+        params: { root: definition && definition.key ? definition.key : "" },
+        error: "该来源的技能不能删除（技能只能停用）：只在项目级来源（<项目>/.dsh/skills）提供删除",
+    };
+}
 function rootDefinition(root) {
     if (root && typeof root === "object" && typeof root.key === "string")
         return root;
@@ -486,7 +527,7 @@ function rootDefinition(root) {
 function rootByKey(key) {
     return userRoots().find((item) => item.key === key) || null;
 }
-/** 只允许用户 DSH 根，或由活动 Session 推导出的项目 DSH 根参与文件写入。 */
+/** 只允许用户 DSH 根 / hub 根，或由活动 Session 推导出的项目 DSH 根参与文件写入。 */
 function writableRootDefinition(root) {
     const definition = rootDefinition(root);
     if (!definition || definition.mutable !== true)
@@ -495,6 +536,11 @@ function writableRootDefinition(root) {
         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" ||
@@ -1048,11 +1094,36 @@ function defaultManagerState() {
         disabledSkills[root.key] = [];
         enabledSkills[root.key] = [];
     }
-    return { version: 1, sources, disabledSkills, enabledSkills, customRoots: [] };
+    return {
+        version: 1,
+        sources,
+        disabledSkills,
+        enabledSkills,
+        customRoots: [],
+        // 同名技能「首选来源」：技能名 → 来源 key。缺键 = 按来源 rank 取最高优先级者。
+        preferredSkills: Object.create(null),
+        // 用户从技能页「移除」的来源：插件**不再读取**这些目录（技能不出现在列表里，
+        // 也不参与 provider 候选）。与「停用来源」不同——停用仍列出技能、只是不可调用。
+        // 源文件一个字节都不动；清空这个数组即可恢复。
+        removedSources: [],
+    };
 }
 function validStateSkillName(name) {
     return validDiscoveryName(name);
 }
+/**
+ * 首选表的键是技能**声明名**（不是文件名）——声明名允许大小写与空格（此时技能本身带
+ * name.invalid 诊断，但仍可被选择）。这里只做「能当 JSON 键、不像路径」的宽松校验，
+ * 避免一个脏键把整份状态文件判为非法（那会让全部技能 fail-closed 停用）。
+ */
+function validPreferredSkillName(name) {
+    return (typeof name === "string" &&
+        name.length > 0 &&
+        name.length <= MAX_ENTRY_NAME_LENGTH &&
+        !name.includes("\0") &&
+        !name.includes("/") &&
+        !name.includes("\\"));
+}
 /** 状态文件已存在但不可用时一律关闭外部来源，避免损坏配置重新暴露技能。 */
 function failClosedManagerState() {
     const state = defaultManagerState();
@@ -1090,6 +1161,22 @@ function validManagerStateDocument(value) {
     // 自定义来源列表：可选字段；容器必须是数组（条目级合法性由 normalize 逐条裁剪）。
     if (value.customRoots !== undefined && !Array.isArray(value.customRoots))
         return false;
+    // 已移除的来源：可选字段；数组里的每一项必须能当来源 key 用。
+    if (value.removedSources !== undefined) {
+        if (!Array.isArray(value.removedSources) ||
+            value.removedSources.some((key) => typeof key !== "string" || key.length === 0 || key.length > 128))
+            return false;
+    }
+    // 同名首选表：可选字段；只校验容器与值类型，键值逐条在 normalize 里裁剪（见 validPreferredSkillName）。
+    if (value.preferredSkills !== undefined) {
+        if (!value.preferredSkills ||
+            typeof value.preferredSkills !== "object" ||
+            Array.isArray(value.preferredSkills))
+            return false;
+        for (const key of Object.values(value.preferredSkills))
+            if (typeof key !== "string")
+                return false;
+    }
     for (const root of userRoots()) {
         if (root.key === "dsh")
             continue;
@@ -1153,8 +1240,50 @@ function normalizeManagerState(value) {
             }
         }
     }
+    // 同名首选表：键必须是技能声明名、值必须指向一个已知来源（用户级 / 自定义 / 项目级），
+    // 否则丢弃该条（源目录被移除后残留的首选会自然失效）。
+    const preferred = value.preferredSkills;
+    if (preferred && typeof preferred === "object" && !Array.isArray(preferred)) {
+        for (const [name, rootKey] of Object.entries(preferred)) {
+            if (!validPreferredSkillName(name) || typeof rootKey !== "string")
+                continue;
+            if (!userRoots().some((root) => root.key === rootKey) &&
+                !customKeys.has(rootKey) &&
+                !PROJECT_ROOT_KEY_RE.test(rootKey))
+                continue;
+            normalized.preferredSkills[name] = rootKey;
+        }
+    }
+    // 已移除的来源：只保留「确实是已知来源 key」的条目，其余丢弃（避免脏键让整份状态非法）。
+    {
+        const raw = Array.isArray(value.removedSources) ? value.removedSources : [];
+        const known = new Set([
+            ...userRoots().map((root) => root.key),
+            ...customKeys,
+        ]);
+        normalized.removedSources = [
+            ...new Set(raw.filter((key) => typeof key === "string" &&
+                known.has(key) &&
+                key !== "dsh" &&
+                key !== "hub")),
+        ].sort();
+    }
     return normalized;
 }
+/**
+ * 参与扫描的来源 = 全部来源 − 用户已移除的。
+ *
+ * 「移除来源」与「停用来源」是两件事：
+ *   - 停用（`sources[key] = false`）：仍然读取并列出技能，只是不可调用；
+ *   - 移除（出现在 `removedSources`）：**连目录都不读**，技能不出现在列表里，
+ *     也不参与 provider 候选。源文件不动，清掉这个标记即恢复。
+ */
+export function activeUserRoots(stateValue) {
+    const removed = new Set(stateValue && Array.isArray(stateValue.removedSources)
+        ? stateValue.removedSources
+        : []);
+    return userRoots().filter((root) => !removed.has(root.key));
+}
 /** 裁剪自定义来源列表：非法条目丢弃，key/path 绑定校验，label 规整。 */
 function normalizeCustomRoots(value) {
     if (!Array.isArray(value))
@@ -1177,14 +1306,51 @@ function normalizeCustomRoots(value) {
     }
     return out;
 }
+/**
+ * 读状态文件。
+ *
+ * **校验的是「归一化之后」的文档，不是磁盘上的原始 JSON** —— 这一条是踩出来的：
+ * 校验器要求每个 `userRoots()` 来源都在 `sources` 里有布尔值、在 `disabledSkills` 里有数组，
+ * 而来源列表会随版本增加（v0.4 加了 `hub` 来源）。于是**版本升级本身**就会把一份完好的旧
+ * 状态文件判成「非法」，紧接着 fail-closed：所有来源停用、写入锁定，Skills 页弹
+ * 「状态文件不可读，已拒绝覆盖」。文件其实一个字节都没坏。
+ *
+ * 归一化会把缺失的键补成默认值（新来源默认启用），所以「我们后来加过键」与「文件真的坏了」
+ * 由此区分开：前者修复后通过，后者（不是对象、version 不是 1、字段类型不对）仍然拒绝。
+ */
 export async function readManagerState() {
     try {
         const raw = await fs.readFile(managerStatePath(), "utf8");
         const parsed = JSON.parse(raw);
-        if (!validManagerStateDocument(parsed))
+        // 版本号在归一化时不会被保留（恒为 1），所以要在解析结果上直接判：
+        // 缺失按 1 处理（更早的文档没有这个字段），存在但不是 1 才判非法。
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            && parsed.version !== undefined && parsed.version !== 1)
+            throw codedError("invalid manager state schema", "error.state.invalid");
+        // 结构守卫：字段**可以缺**（旧文档），但**一旦存在就必须形状正确**。
+        // 少了这道守卫，归一化会把「类型写错」当成「键缺失」一起补默认值——于是 `sources: []`
+        // 或 `disabledSkills: { dsh: "x" }` 这种真损坏反而被自愈放行，静默丢掉文件里的策略。
+        // 契约：**缺键自愈（我们后来加过的东西），类型错必须报错。**
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            for (const field of ["sources", "disabledSkills", "enabledSkills"]) {
+                const value = parsed[field];
+                if (value === undefined)
+                    continue;
+                if (value === null || typeof value !== "object" || Array.isArray(value))
+                    throw codedError("invalid manager state schema", "error.state.invalid");
+                // 策略表的每个桶必须是数组（条目级合法性仍由 normalize 逐条裁剪）。
+                if (field === "disabledSkills" || field === "enabledSkills") {
+                    for (const bucket of Object.values(value))
+                        if (!Array.isArray(bucket))
+                            throw codedError("invalid manager state schema", "error.state.invalid");
+                }
+            }
+        }
+        const normalized = normalizeManagerState(parsed);
+        if (!validManagerStateDocument(normalized))
             throw codedError("invalid manager state schema", "error.state.invalid");
         return {
-            state: normalizeManagerState(parsed),
+            state: normalized,
             warning: null,
             writable: true,
         };
@@ -1282,6 +1448,48 @@ export async function setSourceEnabled(rootOrKey, enabled, log) {
         log(enabled ? "source-enable" : "source-disable", `${enabled ? "启用" : "停用"}来源 ${root.key}: ${root.path}`);
     return { root: root.key, enabled: enabled === true };
 }
+/**
+ * 移除 / 恢复一个来源（用户要求：「是不读取这个文件夹了，不是把文件夹删除」）。
+ *
+ * - `removed = true`：来源进入 `removedSources`，插件**不再读取该目录** —— 技能不出现在
+ *   技能页，也不参与 provider 候选。**源文件与目录一个字节都不动。**
+ * - `removed = false`：清除标记，下一步扫描即恢复。
+ *
+ * 与 `setSourceEnabled(false)` 的区别：停用仍然读目录、仍然列出技能（只是不可调用）；
+ * 移除是"当它不存在"。`dsh`（官方技能目录）与 `hub`（导入技能落点）不允许移除 ——
+ * 它们是插件自身的读写根，移除会让创建/导入无处落脚。
+ */
+export async function setSourceRemoved(rootOrKey, removed, log) {
+    const root = rootOrKey && typeof rootOrKey === "object" && typeof rootOrKey.key === "string"
+        ? rootOrKey
+        : rootByKey(rootOrKey);
+    if (!root)
+        return readonlyError(removed === true ? "remove" : "restore");
+    if (root.key === "dsh" || root.key === "hub")
+        return {
+            ok: false,
+            code: "error.source.reserved",
+            params: { root: root.key },
+            error: root.key === "dsh"
+                ? "DSH 技能目录是官方来源，不能从管理器移除"
+                : "导入技能目录是插件自身的读写落点，不能移除",
+        };
+    if (root.scope === "project")
+        return readonlyError("remove");
+    const current = await readManagerState();
+    if (current.writable === false)
+        return invalidManagerStateWrite();
+    const set = new Set(Array.isArray(current.state.removedSources) ? current.state.removedSources : []);
+    if (removed === true)
+        set.add(root.key);
+    else
+        set.delete(root.key);
+    current.state.removedSources = [...set].sort();
+    await writeManagerState(current.state);
+    if (log)
+        log(removed === true ? "source-remove" : "source-restore", `${removed === true ? "移除（不再读取）" : "恢复读取"}来源 ${root.key}: ${root.path}`);
+    return { root: root.key, removed: removed === true };
+}
 async function checkedPolicyRootDefinition(root) {
     const definition = rootDefinition(root);
     if (!definition || !definition.toggleable)
@@ -1383,6 +1591,62 @@ async function setPolicySkillEnabled(root, name, enabled, log) {
 export async function setSkillEnabled(root, name, enabled, log) {
     return setPolicySkillEnabled(root, name, enabled, log);
 }
+/**
+ * 同名技能「首选来源」：默认同名技能按来源 rank 取优先级最高者生效、其余显示为被覆盖；
+ * 这里让用户显式指定哪个同名技能生效（preferred=false 取消，回到 rank 顺序）。
+ * 只写本地策略，不改任何源文件。
+ */
+export async function setPreferredSkill(root, name, preferred, log) {
+    const definition = await checkedPolicyRootDefinition(root);
+    if (definition && definition.ok === false)
+        return definition;
+    if (!definition)
+        return readonlyError("toggle");
+    const resolved = await resolveEntry(definition, name);
+    if (resolved === null)
+        return {
+            ok: false,
+            error: `技能不存在: ${name}`,
+            code: "error.skill.notFound",
+            params: { name },
+        };
+    let summary;
+    try {
+        summary = entryOf(name, resolved.kind, resolved.docPath, parseSkillDoc(await fs.readFile(resolved.realDocPath || resolved.docPath, "utf8")));
+    }
+    catch {
+        return {
+            ok: false,
+            error: `技能不存在: ${name}`,
+            code: "error.skill.notFound",
+            params: { name },
+        };
+    }
+    if (!summary.loadable)
+        return {
+            ok: false,
+            error: `技能结构不完整，无法设为同名首选: ${name}`,
+            code: "error.skill.notLoadable",
+            params: { name, action: "prefer" },
+        };
+    // 首选表按**声明名**索引（与 groupLoadableSkillsByName 的分组键同源），不是文件名。
+    const canonicalName = summary.declaredName || name;
+    const current = await readManagerState();
+    if (current.writable === false)
+        return invalidManagerStateWrite();
+    const map = { ...(current.state.preferredSkills || {}) };
+    if (preferred === false)
+        delete map[canonicalName];
+    else
+        map[canonicalName] = definition.key;
+    current.state.preferredSkills = map;
+    await writeManagerState(current.state);
+    if (log)
+        log(preferred === false ? "skill-unprefer" : "skill-prefer", preferred === false
+            ? `取消同名首选 ${canonicalName}`
+            : `同名首选 ${canonicalName} → ${definition.key}`);
+    return { name: canonicalName, root: preferred === false ? null : definition.key };
+}
 async function safeExistingEntryPaths(root, name) {
     const paths = [];
     const bundle = entryPath(root, name);
@@ -1498,13 +1762,17 @@ async function restoreRootDefinition(metadata, options = {}) {
     }
     return checkedWritableRootDefinition(root);
 }
-/** 把用户或活动项目的 DSH 根中的单个技能移入 manager-owned 回收站。 */
+/** 把项目级 DSH 根中的单个技能移入 manager-owned 回收站。 */
 export async function deleteSkill(root, name, log, options = {}) {
     const definition = await checkedWritableRootDefinition(root);
     if (definition && definition.ok === false)
         return definition;
     if (!definition)
         return readonlyError("delete");
+    // 用户级来源（dsh / hub）**不可删**：技能只能停用。删除会把用户自己放进去的技能
+    // 从磁盘上搬走，代价远大于收益；项目级来源（本仓库自己的 .dsh/skills）才允许删。
+    if (definition.deletable !== true)
+        return notDeletableError(definition);
     const resolved = await resolveEntry(definition, name);
     if (resolved === null)
         return {
@@ -1866,7 +2134,7 @@ async function replaceWithCopy(source, dest, isDir, existing = []) {
  * 成功返回 { kind, imported, skipped, failed }；失败返回 { ok:false, error }。
  */
 export async function importSkill(source, log, options = {}) {
-    const targetRoot = dshRootPath();
+    const targetRoot = skillCreateRootPath();
     const conflict = options.conflict === "overwrite" ? "overwrite" : "skip";
     const dryRun = options.dryRun === true;
     const analysis = await analyzeSource(source);
@@ -2210,9 +2478,11 @@ function yamlString(value) {
     return JSON.stringify(String(value));
 }
 export async function createSkill(input, log, options = {}) {
+    // v0.4：默认落点由「DSH 技能目录」改为 hub 内的 `tool-management/skills/`；
+    // 调用方显式传 options.root（如项目根）时仍以调用方为准。
     const requestedRoot = Object.prototype.hasOwnProperty.call(options, "root")
         ? options.root
-        : rootByKey("dsh");
+        : rootByKey("hub") || rootByKey("dsh");
     const definition = await checkedWritableRootDefinition(requestedRoot);
     if (definition && definition.ok === false)
         return definition;
@@ -2283,13 +2553,15 @@ export async function skillDetail(keyOrRoot, name, options = {}) {
     const root = (keyOrRoot && typeof keyOrRoot === "object" && typeof keyOrRoot.key === "string" ? keyOrRoot : null) ||
         rootByKey(keyOrRoot) ||
         scopedRoots.find((item) => item.key === keyOrRoot);
-    if (!root)
+    if (!root) {
+        const unknownRoot = (keyOrRoot && typeof keyOrRoot === "object" && keyOrRoot.key) || keyOrRoot;
         return {
             ok: false,
-            error: `未知技能来源: ${key}`,
+            error: `未知技能来源: ${unknownRoot}`,
             code: "error.root.unknown",
-            params: { root: key },
+            params: { root: unknownRoot },
         };
+    }
     const entry = await visibleEntryForRoot(root, name);
     if (!entry)
         return {
@@ -2332,7 +2604,7 @@ export async function skillDetail(keyOrRoot, name, options = {}) {
 export async function listProviderCandidates(options = {}) {
     const policyResult = await readManagerState();
     const candidates = [];
-    const user = userRoots().concat(customRootsFromState(policyResult.state));
+    const user = activeUserRoots(policyResult.state).concat(customRootsFromState(policyResult.state).filter((root) => !policyResult.state.removedSources.includes(root.key)));
     const userScans = await scanDeduplicatedRoots(user);
     const items = user.flatMap((root) => userScans.get(root.key).entries.map((entry) => ({ root, entry })));
     const cwd = options && typeof options.cwd === "string" ? options.cwd : undefined;
@@ -2450,10 +2722,28 @@ export async function getProviderSkill(candidate, options = {}) {
 function canonicalSkillName(item) {
     return item.entry.declaredName || item.entry.name;
 }
-/** 真实路径去重后按声明名分组；管理页与当前工作区 provider 共用来源优先级。 */
-function groupLoadableSkillsByName(items) {
+/**
+ * 真实路径去重后按声明名分组；管理页与当前工作区 provider 共用来源优先级。
+ *
+ * `preferred`（技能名 → 来源 key）是用户对同名技能的显式选择：命中的来源排到同名前，
+ * 其余仍按来源 rank 排序；未命中（或键已失效）时退化为纯 rank 顺序。
+ */
+export function groupLoadableSkillsByName(items, preferred) {
+    const preferredFor = (item) => {
+        if (!preferred)
+            return null;
+        const key = preferred[canonicalSkillName(item)];
+        return typeof key === "string" ? key : null;
+    };
+    const ordered = [...items].sort((a, b) => {
+        const rankA = preferredFor(a) === a.root.key ? 0 : 1;
+        const rankB = preferredFor(b) === b.root.key ? 0 : 1;
+        if (rankA !== rankB)
+            return rankA - rankB;
+        return a.root.rank - b.root.rank;
+    });
     const groups = new Map();
-    for (const item of [...items].sort((a, b) => a.root.rank - b.root.rank)) {
+    for (const item of ordered) {
         if (!item.entry.loadable)
             continue;
         const name = canonicalSkillName(item);
@@ -2465,8 +2755,12 @@ function groupLoadableSkillsByName(items) {
 }
 function markWinners(items, options = {}) {
     const winners = new Map();
-    for (const [canonicalName, [winner, ...shadowed],] of groupLoadableSkillsByName(items)) {
+    const preferred = options.preferred;
+    for (const [canonicalName, [winner, ...shadowed],] of groupLoadableSkillsByName(items, preferred)) {
         winners.set(canonicalName, winner);
+        // 只有「首选命中且确实赢了」才算首选；来源被停用/移除时不谎报。
+        if (preferred && preferred[canonicalName] === winner.root.key)
+            winner.view.preferred = true;
         if (options.markShadowed !== false) {
             for (const item of shadowed)
                 item.view.shadowedBy = {
@@ -2484,8 +2778,16 @@ function markWinners(items, options = {}) {
 /** DSH、常见 Agent、自定义目录与活动 Session 项目根的技能快照。 */
 export async function state(options = {}) {
     const policyResult = await readManagerState();
-    const user = userRoots().concat(customRootsFromState(policyResult.state));
-    const userScans = await scanDeduplicatedRoots(user);
+    const removedKeys = new Set(Array.isArray(policyResult.state.removedSources)
+        ? policyResult.state.removedSources
+        : []);
+    // 已移除的来源仍然出现在 roots 里（界面要能显示「已移除」并允许恢复），但**不扫描**：
+    // 技能不入列表、不参与重名决胜 —— 这正是用户要的「不读取这个文件夹」。
+    // 注意这里必须用**全部**来源 + 自定义来源，不能只用 activeUserRoots()，
+    // 否则被移除的来源会连行都不剩，界面就无从提供「恢复读取」。
+    const user = [...userRoots(), ...customRootsFromState(policyResult.state)];
+    const scannable = user.filter((root) => !removedKeys.has(root.key));
+    const userScans = await scanDeduplicatedRoots(scannable);
     const projectWarnings = [];
     const scoped = await projectRoots(options.projectCwds, projectWarnings);
     const trash = await listTrash();
@@ -2513,9 +2815,35 @@ export async function state(options = {}) {
         });
     const all = [];
     for (const root of [...scoped, ...user]) {
-        const { exists, entries, truncated } = root.scope === "project"
-            ? (await scanDeduplicatedRoots([root])).get(root.key)
-            : userScans.get(root.key);
+        const isRemoved = removedKeys.has(root.key);
+        const { exists, entries, truncated } = isRemoved
+            ? { exists: false, entries: [], truncated: false }
+            : root.scope === "project"
+                ? (await scanDeduplicatedRoots([root])).get(root.key)
+                : userScans.get(root.key);
+        if (isRemoved) {
+            // 已移除：登记一行（供界面显示与恢复），但没有任何技能。
+            result.roots.push({
+                key: root.key,
+                ...(root.kind ? { kind: root.kind } : {}),
+                ...(root.localeKey ? { localeKey: root.localeKey } : {}),
+                path: root.path,
+                label: root.label,
+                mutable: root.mutable,
+                deletable: root.deletable === true,
+                removable: root.key !== "dsh" && root.key !== "hub" && root.scope !== "project",
+                toggleable: root.toggleable,
+                native: root.native,
+                rank: root.rank,
+                scope: root.scope || "user",
+                exists: false,
+                truncated: false,
+                removed: true,
+                enabled: false,
+                skills: [],
+            });
+            continue;
+        }
         // 即使项目 .dsh/skills 尚不存在，也要把可写根返回给创建表单；只读项目根仍按实际存在性展示。
         if (root.scope === "project" && !exists && root.kind !== "project-dsh")
             continue;
@@ -2563,6 +2891,8 @@ export async function state(options = {}) {
             path: root.path,
             label: root.label,
             mutable: root.mutable,
+            // 是否提供「删除」：只有项目级 DSH 根为 true。用户级 dsh / hub 可写但不可删。
+            deletable: root.deletable === true,
             toggleable: root.toggleable,
             native: root.native,
             rank: root.rank,
@@ -2576,6 +2906,9 @@ export async function state(options = {}) {
                 : {}),
             exists,
             truncated: truncated === true,
+            // 界面用：能否从管理器「移除」（不再读取）。dsh / hub / 项目级不可移除。
+            removable: root.key !== "dsh" && root.key !== "hub" && root.scope !== "project",
+            removed: false,
             enabled: policyResult.writable !== false &&
                 (root.scope === "project" ||
                     root.key === "dsh" ||
@@ -2584,7 +2917,8 @@ export async function state(options = {}) {
         });
     }
     const userItems = all.filter((item) => item.root.scope !== "project");
-    markWinners(userItems);
+    const preferredSkills = policyResult.state.preferredSkills || null;
+    markWinners(userItems, { preferred: preferredSkills });
     const projectGroups = new Map();
     for (const item of all.filter((candidate) => candidate.root.scope === "project")) {
         const group = projectGroups.get(item.root.projectRoot) || [];
@@ -2597,7 +2931,7 @@ export async function state(options = {}) {
             ...item,
             view: { ...item.view },
         }));
-        markWinners([...projectItems, ...userCopies]);
+        markWinners([...projectItems, ...userCopies], { preferred: preferredSkills });
     }
     const seenProjects = new Set();
     for (const root of result.roots.filter((item) => item.scope === "project")) {

package/lib/skills/service.js

@@ -9,7 +9,7 @@ import { Worker } from 'node:worker_threads';
 import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
-import { state, setSkillEnabled, setSourceEnabled, deleteSkill, restoreTrash, permanentlyDeleteTrash, importSkill, importUploadedSkill, browseDirectories, createSkill, skillDetail, listProviderCandidates, getProviderSkill, userRoots, projectRoots, readManagerState, customRootsFromState, addCustomRoot, removeCustomRoot, logPath, trashRootPath, } from './core.js';
+import { state, setSkillEnabled, setPreferredSkill, setSourceEnabled, setSourceRemoved, deleteSkill, restoreTrash, permanentlyDeleteTrash, importSkill, importUploadedSkill, browseDirectories, createSkill, skillDetail, listProviderCandidates, getProviderSkill, userRoots, projectRoots, readManagerState, customRootsFromState, addCustomRoot, removeCustomRoot, logPath, trashRootPath, } from './core.js';
 const MAX_LOG_BYTES = 1 << 20;
 const PROVIDER_NAME = 'dsh-plugin-tool-management-external';
 const message = (e) => String((e && e.message) || e);
@@ -282,8 +282,15 @@ function notifyChatCatalog(ctx, invalidateSkills) {
     }
     catch { /* 斜杠菜单刷新失败不影响已完成的操作 */ }
 }
+/** 全插件共用的审计日志：单一串行写队列，避免多处写同一文件交叉。 */
+let sharedLog = null;
+export function pluginLog() {
+    if (!sharedLog)
+        sharedLog = makeLog();
+    return sharedLog;
+}
 export function createSkillsService(ctx) {
-    const log = makeLog();
+    const log = pluginLog();
     const roots = userRoots();
     const rootByKey = Object.fromEntries(roots.map((root) => [root.key, root]));
     const projectOptions = () => ({ projectCwds: activeSessionCwds(ctx) });
@@ -387,18 +394,37 @@ export function createSkillsService(ctx) {
         return { ok: true, data: result };
     };
     const write = (task) => enqueueMutation(task);
+    // 写操作清单：与下方 ops 表同文件同源维护；HTTP 端门禁由 index.ts 从本集合派生，勿在宿主端另抄一份。
+    const writeOps = new Set([
+        'skill-enable', 'skill-disable', 'skill-source-enable', 'skill-source-disable',
+        'skill-prefer', 'skill-unprefer',
+        'skill-create', 'skill-import', 'skill-upload', 'skill-delete',
+        'skill-trash-restore', 'skill-trash-delete', 'skill-custom-add', 'skill-custom-remove',
+    ]);
     const ops = {
         // 读操作（state 走短 TTL 缓存，见上方 readState）
         'skill-state': wrap(() => readState()),
-        'skill-detail': wrap(async (args) => skillDetail(await requestRoot(String(args.root || 'dsh')), String(args.name || ''), projectOptions())),
+        'skill-detail': wrap(async (args) => {
+            const key = String(args.root || 'dsh');
+            // requestRoot 未命中时回传原始 key，让 core 的 error.root.unknown 带上来源名（而非 undefined）。
+            return skillDetail((await requestRoot(key)) || key, String(args.name || ''), projectOptions());
+        }),
         'skill-browse': wrap((args) => browseDirectories(args && args.path)),
         // 启停（写 manager 状态，不改源文件）
         'skill-enable': wrap((args) => write(async () => setSkillEnabled(await requestRoot(String(args.root || 'dsh')), String(args.name || ''), true, log)), afterWrite),
         'skill-disable': wrap((args) => write(async () => setSkillEnabled(await requestRoot(String(args.root || 'dsh')), String(args.name || ''), false, log)), afterWrite),
         'skill-source-enable': wrap((args) => write(async () => setSourceEnabled(await requestRoot(String(args.root || '')), true, log)), afterWrite),
         'skill-source-disable': wrap((args) => write(async () => setSourceEnabled(await requestRoot(String(args.root || '')), false, log)), afterWrite),
+        // 移除 / 恢复来源（「不再读取这个文件夹」）：只改本地状态，源目录一个字节都不动。
+        'skill-source-remove': wrap((args) => write(async () => setSourceRemoved(await requestRoot(String(args.root || '')), true, log)), afterWrite),
+        'skill-source-restore': wrap((args) => write(async () => setSourceRemoved(await requestRoot(String(args.root || '')), false, log)), afterWrite),
+        // 同名技能首选来源（手工指定哪个同名版本生效；只写本地策略）。
+        'skill-prefer': wrap((args) => write(async () => setPreferredSkill(await requestRoot(String(args.root || 'dsh')), String(args.name || ''), true, log)), afterWrite),
+        'skill-unprefer': wrap((args) => write(async () => setPreferredSkill(await requestRoot(String(args.root || 'dsh')), String(args.name || ''), false, log)), afterWrite),
         // 创建 / 导入 / 删除 / 回收站
-        'skill-create': wrap((args) => write(async () => createSkill({ name: args.name, description: args.description, body: args.body }, log, { root: await requestRoot(String(args.root || 'dsh')) })), afterWrite),
+        // 创建默认落 hub（`tool-management/skills/`）：UI 不传 root 时走这里；
+        // core.js 的 createSkill 默认值是第二道保险（同口径）。官方 `~/.dsh/skills/` 仍作为来源列出。
+        'skill-create': wrap((args) => write(async () => createSkill({ name: args.name, description: args.description, body: args.body }, log, { root: await requestRoot(String(args.root || 'hub')) })), afterWrite),
         'skill-import': wrap((args) => write(() => importSkill(String(args.source || ''), log, {
             conflict: args.conflict === 'overwrite' ? 'overwrite' : 'skip',
             dryRun: args.dryRun === true,
@@ -413,5 +439,5 @@ export function createSkillsService(ctx) {
         'skill-custom-add': wrap((args) => write(() => addCustomRoot(args && args.path, args && args.label, log)), afterWrite),
         'skill-custom-remove': wrap((args) => write(() => removeCustomRoot(args && args.key, log)), afterWrite),
     };
-    return { ops, registerProviders };
+    return { ops, writeOps, registerProviders };
 }