dsh-plugin-tool-management 0.12.1 → 0.14.0

package/lib/request-gate.js

@@ -3,6 +3,7 @@
 // 这一域管「谁能改、改哪些、什么时候不许改」：
 //   * 访问令牌（可选）—— 两条用途：宿主浏览器鉴权的逃生口，以及写操作的纵深防御；
 //   * 写 / 敏感 op 白名单 —— 哪些 op 要凭令牌（含"只读但会泄露明文"与"只读但会改宿主状态"）；
+//     清单本身在 `./op-registry.ts`，本文件只拼装（`opsWith` / `frozenOps`）。
 //   * 场景锁定 —— 任一场景 locked=true 时五个管理域整体冻结；
 //   * handlers 后处理 —— 把上面三条装到 op 表上（包装顺序即语义，见 installHandlerGuards）。
 //
@@ -14,6 +15,7 @@
 // 都是「读原函数 → 换包装」的原地改写，先装的在内层、后装的在外层；`annotateLocked` 只挂在
 // 五个读 op 上。整段照搬、顺序未变。
 import { createHash, timingSafeEqual } from 'node:crypto';
+import { frozenOps, opsWith } from './op-registry.js';
 /**
  * 建访问令牌三件套。**必须**从 apply 的第二个参数取配置 ——
  * 读 `ctx.config` 不是注入服务，启动时会抛 "cannot get property without inject"。
@@ -96,56 +98,18 @@ export function createAccessToken(deps) {
 }
 /** 建白名单。必须在四个 service 创建之后构造（依赖其 writeOps）。 */
 export function createOpWhitelist(deps) {
-    // HTTP 写操作门禁清单。skills/rules/档案引擎域由各自 service 导出的 writeOps 派生
-    // （与其 ops 表同文件维护，新增写 op 改对应 service 即可）；本文件内联域
-    // （mcpm-* / skill-open / agentsmd-* / history-*）在此列举。
-    // 注意：必须在上述 service 创建之后构造（依赖其 writeOps）。
+    // 清单本身在 `./op-registry.ts` 里逐条登记（判据、口径、为什么）。这里只做拼装：
+    // 写 = 四个 service 自报的 writeOps ∪ 登记表里标了 write 的内联域；敏感 = 登记表标 sensitive。
     const WRITE_OPS = new Set([
         ...deps.writeOps.skills,
         ...deps.writeOps.memories,
         ...deps.writeOps.archives,
         ...deps.writeOps.subagents,
-        'mcpm-add', 'mcpm-edit', 'mcpm-remove', 'mcpm-set-enabled', 'mcpm-set-all', 'mcpm-restart',
-        'mcpm-compact',
-        'mcpm-export', 'mcpm-import', 'mcpm-note', 'mcpm-settings', 'mcpm-tool-enabled',
-        // mcpm-tools-refresh 为了拿实时工具表会临时启用目标服务器、结束后恢复原状（两次
-        // writePatch），恢复失败还会停留在启用态 —— 是写不是读，按写门禁（与 mcpm-restart
-        // 已在清单同理；0.6.0/0.7.0 已有两次写 op 漏列前科）。
-        'mcpm-tools-refresh',
-        // mcpm-reveal returns UNMASKED secrets; even though it is a read, it is
-        // token-gated like a write — on a LAN-exposed port the token must be the
-        // last line of defense for plaintext credentials too, not just writes.
-        'mcpm-reveal',
-        'skill-open',
-        // preset-tools 是只读枚举，但枚举会为预设建立 standing mount（官方语义：每进程只挂一次）。
-        // 未授权调用者不该触发挂载 —— 按写门禁。
-        //
-        // 这条规则的范围写清楚，别当成"凡会写盘就入门禁"：`history-list` / `history-sessions`
-        // 每次都会写工作区快照、`rules-list` / `rules-read` / `rules-diagnose` 会整份覆盖写
-        // `memories-index.json`、`mcpm-list` / `mcpm-tools` 回写 `mcp-known-tools.json` ——
-        // 五个都是读 op 且**不在本清单**。判据是"会不会改**宿主或外部系统**的状态"：
-        // standing mount 改的是宿主进程，而上面那些写的是插件自己的侧车（丢了可重建）。
-        // 想要它们也带令牌就显式加进来，别靠"读操作带副作用"这句话推。
-        'preset-tools',
-        // 提示词写操作（create/update/remove 改预设库；apply 写全局 AGENTS.md；import 从外部内容建预设）
-        'agentsmd-create', 'agentsmd-update', 'agentsmd-apply', 'agentsmd-remove', 'agentsmd-import',
-        // 提示词预设的回收站（恢复 / 永久删除都是写）
-        'agentsmd-trash-restore', 'agentsmd-trash-delete',
-        // history 写操作（archive/unarchive 改归档集合；delete 永久删除；retention-set 写保留期；
-        // workspace-register 会新增一条宿主工作区登记，同样是写）
-        'history-archive', 'history-unarchive', 'history-delete', 'history-retention-set',
-        'history-unarchive-batch', 'history-delete-batch', 'history-import', 'history-export',
-        // 通用导出：往用户指定的目录写文件，按写操作门禁（token）。
-        'bundle-export',
-        'history-archive-batch', 'history-workspace-register',
-        // 注入设置（五个域开关 / 压制型预设口径）写侧车，按写操作门禁。
-        'inject-settings',
-        // 清理 patch 备份：删磁盘文件（含明文凭据副本），按写操作门禁。
-        'backups-clean',
+        ...opsWith('write'),
     ]);
     // 会泄露明文凭据 / 完整配置的 op：**必须**带对的访问令牌，没配令牌就一律拒绝
     // （判定在 http-fence.ts 的 secretOpRejection，含两种情况的区分与理由）。
-    const SENSITIVE_OPS = new Set(['mcpm-reveal', 'mcpm-export']);
+    const SENSITIVE_OPS = new Set(opsWith('sensitive'));
     return { WRITE_OPS, SENSITIVE_OPS };
 }
 // ---------- 场景锁定守卫（v0.8）----------
@@ -214,37 +178,16 @@ export function installHandlerGuards(deps) {
             };
         }
     }
-    guardLockedOps([
-        // MCP：改配置 / 服务器启停 / 工具启停 / 导入导出配置 / 备注 / 设置。
-        // restart 仍放行（它是"重连"这条恢复路径），但它**不是只读**：实现会两次 `writePatch`
-        //（先强制停用、轮询、再按重启前状态恢复）。所以它不改的是**用户选的启停值**，
-        // 不是"不碰补丁文件" —— 锁定期间它是唯一能落盘改补丁的入口，进程中断会把服务器
-        // 留在停用态。别按"只重连"去理解它。
-        'mcpm-add', 'mcpm-edit', 'mcpm-remove', 'mcpm-set-enabled', 'mcpm-set-all', 'mcpm-tool-enabled', 'mcpm-import', 'mcpm-compact', 'mcpm-note', 'mcpm-settings',
-        // 技能：启停 / 来源启停与移除恢复 / 首选 / 删除 / 创建导入 / 自定义目录 / 回收站 / 批量启停。
-        'skill-enable', 'skill-disable', 'skill-source-enable', 'skill-source-disable', 'skill-source-remove', 'skill-source-restore',
-        'skill-prefer', 'skill-unprefer', 'skill-delete', 'skill-create', 'skill-import', 'skill-upload', 'skill-set-all',
-        'skill-custom-add', 'skill-custom-remove', 'skill-trash-restore', 'skill-trash-delete',
-        // 子智能体：开关 / 改名保存 / 删除 / 导入 / 回收站。
-        'subagent-create', 'subagent-update', 'subagent-delete', 'subagent-toggle', 'subagent-import', 'subagent-trash-restore', 'subagent-trash-delete',
-        // 记忆：增删改 / 开关 / 导入 / 回收站 / 绑定。set-active 是场景启停，不在冻结范围。
-        'rules-create', 'rules-update', 'rules-remove', 'rules-toggle', 'rules-import', 'rules-restore', 'rules-trash-remove', 'rules-attach', 'rules-detach', 'rules-set-index',
-        // 提示词：建改删 / 应用（切换生效基线）/ 导入 / 回收站。
-        'agentsmd-create', 'agentsmd-update', 'agentsmd-remove', 'agentsmd-apply', 'agentsmd-import', 'agentsmd-trash-restore', 'agentsmd-trash-delete',
-    ], '修改');
+    // 冻结清单与档案同步清单都来自 `./op-registry.ts`：加 op 时在那里登记一条，这里不再抄。
+    guardLockedOps(frozenOps('all'), '修改');
     // 场景内「开关」类操作（用户裁定 2026-09-17）：未锁定时**可用**，改动同步进当前场景档案。
     // 与「锁定」正交：锁定冻结全部写操作，这里只是把页面开关的意图也写进档案。
-    syncSceneArchiveOnSwitch([
-        'mcpm-set-enabled', 'mcpm-set-all', 'mcpm-tool-enabled',
-        'skill-enable', 'skill-disable', 'skill-set-all', 'skill-source-enable', 'skill-source-disable',
-        'subagent-toggle',
-    ]);
-    // `rules-set-active` 不在 `guardLockedOps` 里（场景启停本身要可用），但它能把**当前
-    // 场景清空** —— 而「当前场景已锁定」是模型侧 `lockedSceneGuard` 唯一的判据，场景一空
-    // 它就返回 null，四个写工具全部放开，运行时却仍是那个场景的档案态（2026-09-19 审计
-    // T-32）。所以这里单独挡一刀：锁着的场景正在生效时，不许改启用集合（先解锁再说）。
-    // 没有锁定场景在生效时（全局态 / 场景未锁）照旧可用 —— 那本来就是允许的。
-    for (const [opName, what] of [['rules-set-active', '切换场景']]) {
+    syncSceneArchiveOnSwitch(opsWith('syncsArchive'));
+    // 口径 `frozenScope: 'active-scene'` 的那几条（判据与理由登记在 op-registry.ts 的
+    // `rules-set-active` 条目上）。没有锁定场景在生效时（全局态 / 场景未锁）照旧可用。
+    const ACTIVE_SCENE_LABEL = { 'rules-set-active': '切换场景' };
+    for (const opName of frozenOps('active-scene')) {
+        const what = ACTIVE_SCENE_LABEL[opName] ?? '改它';
         const original = handlers[opName];
         if (typeof original !== 'function')
             continue;
@@ -264,16 +207,16 @@ export function installHandlerGuards(deps) {
             return original(args);
         };
     }
-    // 被锁场景自身的档案与删除：只挡它自己，别的场景照常。
-    for (const [opName, pickScene, what] of [
-        ['scene-archive-save', (args) => (args && args.scene) || '', '改档案'],
-        ['rules-remove-scene', (args) => (args && args.name) || '', '删除'],
-    ]) {
+    // 被锁场景自身的档案与删除：只挡它自己，别的场景照常（口径 `frozenScope: 'self-scene'`）。
+    // 目标场景一律从 `args.scene` / `args.name` 里取 —— 这两个键名就是本插件 op 的惯例。
+    const SELF_SCENE_LABEL = { 'scene-archive-save': '改档案', 'rules-remove-scene': '删除' };
+    for (const opName of frozenOps('self-scene')) {
+        const what = SELF_SCENE_LABEL[opName] ?? '改它';
         const original = handlers[opName];
         if (typeof original !== 'function')
             continue;
         handlers[opName] = async (args) => {
-            const scene = String(pickScene(args) || '').trim();
+            const scene = String((args && (args.scene || args.name)) || '').trim();
             const locked = await lockedSceneNames();
             if (scene && locked.includes(scene))
                 return { ok: false, error: `场景「${scene}」已锁定：先解锁再${what}` };
@@ -298,7 +241,7 @@ export function installHandlerGuards(deps) {
         }
         return res;
     }
-    for (const opName of ['mcpm-list', 'mcpm-reveal', 'skill-state', 'subagent-list', 'agentsmd-list']) {
+    for (const opName of opsWith('annotatesLock')) {
         const original = handlers[opName];
         if (typeof original !== 'function')
             continue;

package/lib/scene-settings.js

@@ -0,0 +1,17 @@
+// 场景页的界面设置（侧车 `scene-settings.json`，界面在场景页右上的按钮）。
+//
+// 目前只有一项：进入场景前要不要先弹那张「会改什么」的卡。它是**界面提示**，不是管理动作 ——
+// 所以它既不受场景锁定影响（锁着场景照样能关提醒），也不参与任何门禁判定；改了只影响下一次
+// 点「启用这个场景」时弹不弹卡。
+//
+// 为什么放在服务端而不是浏览器本地：与其余设置同一个家（侧车 + op + 登记表），换浏览器
+// 也在；写在 localStorage 里就只有那个浏览器认，而这个开关的意义正是"我不想每次都被拦一下"，
+// 换了浏览器又冒出来会显得是 bug。
+export const DEFAULT_SCENE_SETTINGS = { enterPreview: true };
+/** 把任意输入夹成合法设置（缺项/类型不对一律退回默认：默认不阻止任何确认）。 */
+export function normalizeSceneSettings(raw) {
+    const obj = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        enterPreview: typeof obj.enterPreview === 'boolean' ? obj.enterPreview : DEFAULT_SCENE_SETTINGS.enterPreview,
+    };
+}

package/lib/scenes/candidates.js

@@ -15,6 +15,15 @@
 // 放进本文件会让两个域互相引用。
 import { presetRosterOf } from '../compat/preset-reach.js';
 import { injectionFactsOf, readCompositionFacts } from '../compat/preset-reach.js';
+/**
+ * 问 adapter 的等待上限。官方签名 `resolveModelInfo(provider, model, signal?)` 的 signal 是
+ * "optional cancellation for adapter-owned asynchronous lookup"，所以给一个上限 —— 界面那一格
+ * 是懒加载 + loading 态，挂住不返回会让它一直转。
+ *
+ * ⚠️ 10s 是**防御性**取值，没有实测依据：本机拿不到活着的 adapter，量不出真实耗时。
+ * 真机上若发现常见 provider 只要几十毫秒，可以调小；若某个 provider 稳定超过它，就该调大。
+ */
+const MODEL_REASONING_TIMEOUT_MS = 10_000;
 export function createCandidates(deps) {
     // 外部能力一次解构成局部名：块内代码逐字搬来，保持原样最不容易出错。
     const { get, tools, mcp, skillsService, memoriesService, toolKeyParts } = deps;
@@ -329,6 +338,52 @@ export function createCandidates(deps) {
         }
         return { models };
     }
+    /**
+     * 某个 (provider, model) 的思考强度档位。见 `Candidates.modelReasoning` 的注释。
+     *
+     * `llm` 与 `modelCandidates` 同一路径取（**不在 inject 声明里**，所以必须 `ctx.get('llm')`
+     * 而不是 `ctx.llm` —— 后者在未声明该服务时 cordis 代理会抛
+     * "cannot get property without inject"）。
+     */
+    async function modelReasoning(provider, model) {
+        const llm = (typeof ctx.get === 'function' ? ctx.get('llm') : undefined);
+        if (!llm || typeof llm.resolveModelInfo !== 'function') {
+            return { ok: false, error: '宿主没有提供 llm.resolveModelInfo（拿不到档位清单）' };
+        }
+        const ac = typeof AbortController === 'function' ? new AbortController() : null;
+        const timer = ac ? setTimeout(() => ac.abort(), MODEL_REASONING_TIMEOUT_MS) : null;
+        try {
+            const info = await llm.resolveModelInfo(provider, model, ac ? ac.signal : undefined);
+            const reasoning = info && info.reasoning;
+            const raw = reasoning && Array.isArray(reasoning.efforts) ? reasoning.efforts : [];
+            const efforts = [];
+            for (const e of raw) {
+                const id = String((e && e.id) || '');
+                if (!id)
+                    continue;
+                // 官方结构：`{ id, name, description? }`（`dsh-llm/lib/types/types.d.ts:295-302`）。
+                // name 是给人看的档位名，id 才是要传回去的值 —— 两者都要留着，界面按 name 显示、按 id 提交。
+                efforts.push({
+                    id,
+                    name: String((e && e.name) || id),
+                    ...(e && typeof e.description === 'string' && e.description ? { description: e.description } : {}),
+                });
+            }
+            return {
+                ok: true,
+                efforts,
+                // 缺省（null）= 由 provider 自己的默认决定（官方注释：Absence preserves the provider's own default）。
+                defaultEffort: reasoning && reasoning.defaultEffort ? String(reasoning.defaultEffort) : null,
+            };
+        }
+        catch (e) {
+            return { ok: false, error: (e && e.message) ? String(e.message) : String(e) };
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     return {
         presetRoster,
         presetFactsForAgent,
@@ -338,6 +393,7 @@ export function createCandidates(deps) {
         presetToolNames,
         presetNames,
         modelCandidates,
+        modelReasoning,
         memoryCandidates,
         memorySceneCandidates,
     };

package/lib/skills/catalog.js

@@ -21,7 +21,7 @@
 /** 描述截断长度（与官方目录的 `catalogDescriptionMaxLength` 默认值一致）。 */
 export const SKILL_CATALOG_DESCRIPTION_MAX_LENGTH = 500;
 /** 目录最多列几条；超出只报数量（让模型去调 `skill_manager_list`）。 */
-export const SKILL_CATALOG_MAX_ENTRIES = 60;
+export const SKILL_CATALOG_MAX_ENTRIES = 50;
 /** 描述归一化 + 截断（与官方 `catalogDescription` 同款：折叠空白、超出补省略号）。 */
 function catalogDescription(value, maxLength) {
     const normalized = String(value ?? '').replaceAll(/\s+/g, ' ').trim();
@@ -41,7 +41,7 @@ function isEnabled(row) {
  * 返回 `''` 表示没有可注入的技能 —— 没装技能的用户零 token 成本。
  * 名字按字典序排序：底层目录枚举顺序变化时文本仍逐字节稳定（前缀缓存契约）。
  */
-export function renderSkillCatalog(data, maxEntries = SKILL_CATALOG_MAX_ENTRIES, maxDescription = SKILL_CATALOG_DESCRIPTION_MAX_LENGTH) {
+export function renderSkillCatalog(data, maxEntries = SKILL_CATALOG_MAX_ENTRIES, maxDescription = SKILL_CATALOG_DESCRIPTION_MAX_LENGTH, listToolVisible = true) {
     const roots = (data && typeof data === 'object' ? data.roots : undefined) ?? [];
     const byName = new Map();
     if (Array.isArray(roots)) {
@@ -77,8 +77,13 @@ export function renderSkillCatalog(data, maxEntries = SKILL_CATALOG_MAX_ENTRIES,
     // （2026-09-18 起，见 context-inject.ts 的 DOMAIN_FRAME 的 `how` 行）—— 一处内容一个出处。
     const out = [...lines];
     const hidden = sorted.length - shown.length;
-    if (hidden > 0)
-        out.push('', `（另有 ${hidden} 个未列出，用 \`skill_manager_list\` 查。）`);
+    // 查询工具被关掉（兼容页的模型工具表）时只说"还有几个"：点名一个模型手里没有的工具，
+    // 它只会去猜名字。数量照报 —— 那是实话，与有没有出口无关。
+    if (hidden > 0) {
+        out.push('', listToolVisible
+            ? `（另有 ${hidden} 个未列出，用 \`skill_manager_list\` 查。）`
+            : `（另有 ${hidden} 个未列出。）`);
+    }
     return out.join('\n');
 }
 /**
@@ -95,7 +100,7 @@ export function createSkillCatalog(deps, opts = {}) {
         try {
             const result = await deps.state();
             if (result && result.ok !== false) {
-                value = renderSkillCatalog(result.data ?? result, opts.maxEntries, opts.maxDescription);
+                value = renderSkillCatalog(result.data ?? result, opts.maxEntries, opts.maxDescription, deps.listToolVisible ? deps.listToolVisible() : true);
             }
         }
         catch { /* 保留上一次的值；首次失败则维持 '' */ }

package/lib/skills/core.js

@@ -2696,6 +2696,99 @@ export async function createSkill(input, log, options = {}) {
         log("create", `创建 ${join(target, "SKILL.md")}`);
     return { name, path: join(target, "SKILL.md"), root: definition.key };
 }
+/**
+ * 改写一份**已存在**的技能（bundle 的 `SKILL.md` 或 flat 的 `<name>.md`）。
+ *
+ * 为什么是独立函数、而不是给 `createSkill` 加一个 `allowOverwriteInOwnRoot` 开关：
+ * 「静默覆盖」这件事不该出现在同一个入口的签名里 —— 调用方读到的函数名必须已经说明了
+ * 它是破坏性的，否则一次参数写错就从"新建"变成"覆盖别人的技能"。
+ *
+ * 写入复用同一套原子写（stage 文件 + `renameWithRetry`）。bundle 形态**只换 SKILL.md**，
+ * 目录里其余文件（附件、脚本、参考文档）原样留着 —— 整目录替换会把它们全删掉。
+ *
+ * 边界：只在 `options.root`（默认 hub = `$DSH_HOME/tool-management/skills`）**里面已经
+ * 存在**的那一份上写。文件不在那里就是"不存在"，**绝不新建**（新建是 `createSkill` 的事，
+ * 它的冲突检查会拒掉同名）。
+ *
+ * 「胜出者必须是 hub 这一份」这层判定不在这里：它要读来源排序与首选设置，属于状态层
+ * （见 service.ts 的 `skill-update` op）。本函数只保证"不越出给定根"。
+ */
+export async function updateSkill(input, log, options = {}) {
+    const requestedRoot = Object.prototype.hasOwnProperty.call(options, "root")
+        ? options.root
+        : rootByKey("hub") || rootByKey("dsh");
+    const definition = await checkedWritableRootDefinition(requestedRoot);
+    if (definition && definition.ok === false)
+        return definition;
+    if (!definition) {
+        if (!rootDefinition(requestedRoot)) {
+            return {
+                ok: false,
+                code: "error.root.unknown",
+                params: { root: String(requestedRoot == null ? "" : requestedRoot) },
+                error: `技能来源不存在：${requestedRoot == null || requestedRoot === "" ? "(空)" : requestedRoot}`,
+            };
+        }
+        return readonlyError("update");
+    }
+    const root = definition.path;
+    const requestedName = String((input && input.name) || "").trim();
+    const name = toKebab(requestedName);
+    if (!name || !KEBAB_RE.test(name) || entryPath(root, name) === null)
+        return {
+            ok: false,
+            error: `无法生成合法 kebab-case 名称（原始名: ${requestedName}）`,
+            code: "error.import.invalidName",
+            params: { name: requestedName },
+        };
+    // 形态判定与 `resolveEntry` 同口径：bundle 目录优先，其次 flat 单文件。
+    const bundleDir = entryPath(root, name);
+    const bundleDoc = join(bundleDir, "SKILL.md");
+    const flatDoc = resolve(root, `${name}.md`);
+    const exists = async (p) => await fs.stat(p).then(() => true).catch(() => false);
+    const existingDoc = (await exists(bundleDoc)) ? bundleDoc : (await exists(flatDoc)) ? flatDoc : null;
+    if (!existingDoc)
+        return {
+            ok: false,
+            code: "error.update.notFound",
+            error: `技能不存在（本插件落点里没有 ${name}）：本工具只改本插件自己写的技能，不新建、也不动官方根里的`,
+            params: { name },
+        };
+    const current = parseSkillDoc(await fs.readFile(existingDoc, "utf8"));
+    const curDescription = unquote(String(current.map.description ?? "")).trim();
+    const curBody = String(current.body ?? "").trim();
+    // 省略 = 保持。注意区分"未给"与"给了空串"：空串是显式意图，会被下面的必填校验挡下并
+    // 说明缺哪个 —— 静默保留会让模型以为清掉了。
+    const description = input && input.description !== undefined
+        ? String(input.description).trim()
+        : curDescription;
+    const body = input && input.body !== undefined ? String(input.body).trim() : curBody;
+    if (!description)
+        return { ok: false, error: "技能简介不能为空", code: "error.create.descriptionRequired" };
+    if (!body)
+        return { ok: false, error: "技能正文不能为空", code: "error.create.bodyRequired" };
+    if (description.length > 500 || body.length > 1 << 18)
+        return { ok: false, error: "技能内容过长", code: "error.create.tooLarge" };
+    const content = `---\nname: ${name}\ndescription: ${yamlString(description)}\n---\n\n${body}\n`;
+    if (existingDoc === flatDoc) {
+        await writeFileAtomically(flatDoc, content);
+        if (log)
+            log("update", `更新 ${flatDoc}`);
+        return { name, path: flatDoc, root: definition.key };
+    }
+    const stage = temporaryPath(existingDoc, "update");
+    try {
+        await fs.writeFile(stage, content, "utf8");
+        await renameWithRetry(stage, existingDoc);
+    }
+    catch (error) {
+        await fs.rm(stage, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    if (log)
+        log("update", `更新 ${existingDoc}`);
+    return { name, path: existingDoc, root: definition.key };
+}
 export async function skillDetail(keyOrRoot, name, options = {}) {
     const scopedRoots = await projectRoots(options.projectCwds);
     // 支持传 key 或 definition（自定义来源由 service 层解析后传入）。
@@ -2840,6 +2933,15 @@ export async function getProviderSkill(candidate, options = {}) {
         typeof options.cwd === "string") {
         root = (await projectRoots([options.cwd])).find((item) => item.key === locator.rootKey);
     }
+    // 自定义技能目录不住在 `userRoots()` 里，它住在状态文件的 `customRoots` 里，所以
+    // `rootByKey()` 恒取不到。少了这一支就是「列得出、调不动」：`state()` 扫的是
+    // `userRoots() + customRootsFromState()`，官方 catalog 因此把目录里的技能列给模型，
+    // 而模型真去 `skill` 工具取正文时这里返回 undefined —— 症状是
+    // `skill "brainstorming" is unknown or no longer available`（用户 2026-09-22 报的）。
+    if (!root &&
+        CUSTOM_ROOT_KEY_RE.test(locator.rootKey)) {
+        root = customRootsFromState((await readManagerState()).state).find((item) => item.key === locator.rootKey);
+    }
     if (!root)
         return undefined;
     try {

package/lib/skills/service.js

@@ -10,7 +10,7 @@ import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { isInsideRootResolved } from '../paths.js';
-import { state, setSkillEnabled, setPreferredSkill, markSkillsDisabled, setSourceEnabled, setSourceRemoved, 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, markSkillsDisabled, setSourceEnabled, setSourceRemoved, deleteSkill, restoreTrash, permanentlyDeleteTrash, importSkill, importUploadedSkill, browseDirectories, createSkill, updateSkill, 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);
@@ -455,7 +455,7 @@ export function createSkillsService(ctx) {
         // 也变），是写操作；漏在这份清单里 = 配了访问令牌也不会被要求带令牌。
         'skill-source-remove', 'skill-source-restore',
         'skill-prefer', 'skill-unprefer',
-        'skill-create', 'skill-import', 'skill-upload', 'skill-delete',
+        'skill-create', 'skill-update', 'skill-import', 'skill-upload', 'skill-delete',
         // 批量启停与单条启停同权：配了访问令牌的宿主必须同样要求带令牌。
         'skill-set-all',
         'skill-trash-restore', 'skill-trash-delete', 'skill-custom-add', 'skill-custom-remove',
@@ -549,6 +549,38 @@ export function createSkillsService(ctx) {
             }
             return res;
         }), afterWrite),
+        // 改写**本插件自己写的那一份**技能。只认 hub 里的胜出者：同名技能在 dsh / agents /
+        // claude / 自定义根各有一份时只有一份生效，改错那一份会返回 OK 而技能毫无变化
+        // （用户实测踩过：同一技能四份并存，启错根等于没启）。胜出者判定要读来源排序与首选
+        // 设置，属于状态层，所以在这里做；core 的 `updateSkill` 只保证不越出给定根。
+        'skill-update': wrap((args) => write(async () => {
+            const wanted = String(args.name || '').trim();
+            const s = await readState();
+            const hits = [];
+            for (const root of (s && s.roots) || []) {
+                for (const skill of root.skills || []) {
+                    if (String(skill.declaredName || skill.name || '') !== wanted)
+                        continue;
+                    hits.push({
+                        rootKey: String(root.key || ''),
+                        shadowedBy: skill.shadowedBy && skill.shadowedBy.root ? String(skill.shadowedBy.root) : '',
+                    });
+                }
+            }
+            if (!hits.length) {
+                return { ok: false, code: 'error.update.notFound', params: { name: wanted }, error: `技能不存在：${wanted}` };
+            }
+            const winner = hits.find((h) => !h.shadowedBy) || hits[0];
+            if (winner.rootKey !== 'hub') {
+                return {
+                    ok: false,
+                    code: 'error.update.notOwnRoot',
+                    params: { name: wanted, root: winner.rootKey },
+                    error: `技能 ${wanted} 的生效副本在来源「${winner.rootKey}」，不在本插件落点（hub = $DSH_HOME/tool-management/skills）：本插件不修改官方根里的技能`,
+                };
+            }
+            return updateSkill({ name: args.name, description: args.description, body: args.body }, log, { root: (await requestRoot('hub')) || 'hub' });
+        }), afterWrite),
         'skill-import': wrap((args) => write(async () => {
             const res = await importSkill(String(args.source || ''), log, {
                 conflict: args.conflict === 'overwrite' ? 'overwrite' : 'skip',

package/lib/subagents/catalog.js

@@ -11,7 +11,7 @@ import { filterBySceneBinding } from './tools.js';
  */
 export const DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH = 500;
 /** 段里最多列几个人设；超出部分只报数量，让模型自己去调 subagent_manager_list。 */
-export const DEFAULT_CATALOG_MAX_ENTRIES = 60;
+export const DEFAULT_CATALOG_MAX_ENTRIES = 50;
 /** 无描述时的占位，与 `subagent_manager_list` 工具的输出保持同一口径。 */
 const NO_DESCRIPTION = '(无描述)';
 /**
@@ -43,7 +43,7 @@ export function catalogDescription(value, maxLength) {
  * （`- **名字** — 描述`），"这是什么 + 该拿它做什么"整句交给注入通道的引导语。于是这里
  * 既没有标题也没有"可委派给下列子智能体"那句：一处内容只有一个出处。
  */
-export function renderSubagentCatalog(allowed, maxEntries = DEFAULT_CATALOG_MAX_ENTRIES, maxDescription = DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH) {
+export function renderSubagentCatalog(allowed, maxEntries = DEFAULT_CATALOG_MAX_ENTRIES, maxDescription = DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH, listToolVisible = true) {
     if (!allowed.length)
         return '';
     const sorted = [...allowed].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
@@ -58,8 +58,12 @@ export function renderSubagentCatalog(allowed, maxEntries = DEFAULT_CATALOG_MAX_
     // 查询工具**只在真被 40 条上限截掉时**才出现：常态下不提，省常驻字符，也免得模型为了
     // 「确认一遍」去调它（用户裁定：没列出来的就是当前不想要的）。与 MCP 状态段的
     // `（另有 N 台未列出。）` 同一句式，但这里多给一个出口——不给人设就真的找不回来了。
-    if (hidden > 0)
-        out.push('', `（另有 ${hidden} 个未列出，用 \`subagent_manager_list\` 查。）`);
+    if (hidden > 0) {
+        // 与技能目录同一条纪律：点名一个被关掉的工具只会让模型去猜名字。数量照报。
+        out.push('', listToolVisible
+            ? `（另有 ${hidden} 个未列出，用 \`subagent_manager_list\` 查。）`
+            : `（另有 ${hidden} 个未列出。）`);
+    }
     return out.join('\n');
 }
 /**
@@ -101,7 +105,7 @@ export function createSubagentCatalog(deps, opts = {}) {
             const cached = rendered.get(depth);
             if (cached !== undefined)
                 return cached;
-            const out = renderSubagentCatalog(allowed.filter((p) => catalogInjectedAt(p, depth)), maxEntries, maxDescription);
+            const out = renderSubagentCatalog(allowed.filter((p) => catalogInjectedAt(p, depth)), maxEntries, maxDescription, deps.listToolVisible ? deps.listToolVisible() : true);
             rendered.set(depth, out);
             return out;
         },

package/lib/subagents/service.js

@@ -99,6 +99,17 @@ export function parsePresetToolRules(frontmatter) {
     return Object.keys(rules).length ? rules : undefined;
 }
 /** 行式 frontmatter 解析：只认 description / provider / model / tools / toolsDeny / toolsByPreset / catalogDepth / output。 */
+/**
+ * 思考强度档位 id 的归一：单行、去空白、限长。**不校验它是不是合法档位** —— 清单要问 adapter
+ * 才拿得到（可能拿不到），而官方本来就会在 provider I/O 之前拒掉不支持的显式值。
+ *
+ * 为什么必须去换行：frontmatter 是**逐行**解析的（`parsePersona`），值里带换行会把后面半截
+ * 变成一行无主文本。限长是防脏值（正常档位 id 都很短）。
+ */
+export const REASONING_EFFORT_MAX_LENGTH = 64;
+export function normalizeReasoningEffort(value) {
+    return String(value ?? '').replace(/[\r\n]+/g, ' ').trim().slice(0, REASONING_EFFORT_MAX_LENGTH);
+}
 export function parsePersona(raw, fallbackName) {
     const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
     const data = {};
@@ -133,6 +144,8 @@ export function parsePersona(raw, fallbackName) {
         description: data.description || firstLine,
         provider: data.provider || undefined,
         model: data.model || undefined,
+        // frontmatter 键统一小写后是 `reasoningeffort`（写出去的是 camelCase）。
+        reasoningEffort: normalizeReasoningEffort(data.reasoningeffort) || undefined,
         tools,
         toolsDeny,
         ...(toolsByPreset === undefined ? {} : { toolsByPreset }),
@@ -618,8 +631,22 @@ export function createSubagentService(ctx, opts) {
             // provider 与 model 是模型路由的两半：DSH 的 resolveModel(provider, model) 不做
             // `provider/model` 字符串拆分，只改 model 会落在**主会话的 provider** 上——跨来源
             // 指定模型（如 sensenova 的 sensenova-6.8-flash-lite）必须两个键一起给。
-            ...(p.provider || p.model
-                ? { agentOptions: { ...(p.provider ? { provider: p.provider } : {}), ...(p.model ? { model: p.model } : {}) } }
+            // 2026-09-23 加 `reasoningEffort`：条件是"三个键任一有值"—— 只设强度（不改模型）也得
+            // 把这个对象发出去，否则那一格永远不生效。官方合并语义（`dsh-subagent/lib/index.js:471-483`）
+            // 是"先继承主会话的三项、再用这里的覆盖"，所以只给 reasoningEffort 时 provider/model
+            // 照旧继承；反过来，改了 provider/model 而没给 reasoningEffort 时，**继承来的那一档会被
+            // 删掉**（回落到该模型自己的默认）—— 那不是 bug，是官方的显式语义。
+            ...(p.provider || p.model || p.reasoningEffort
+                ? {
+                    agentOptions: {
+                        ...(p.provider ? { provider: p.provider } : {}),
+                        ...(p.model ? { model: p.model } : {}),
+                        // 类型是官方的品牌串 `ReasoningEffortId`；我们的值本来就是 adapter 自己给的
+                        // opaque id（界面从 `resolveModelInfo` 的清单里选出来的），所以这里只做归一、
+                        // 不重新校验 —— 不支持的档位由官方在 provider I/O 之前拒。
+                        ...(p.reasoningEffort ? { reasoningEffort: p.reasoningEffort } : {}),
+                    },
+                }
                 : {}),
         });
         try {
@@ -660,7 +687,8 @@ export function createSubagentService(ctx, opts) {
             return {
                 ok: true,
                 // catalogDepth 报**生效值**（没写就是默认 1），界面与模型都不必各自知道默认是多少。
-                subagents: docs.map((p) => ({ name: p.name, enabled: p.enabled !== false, description: p.description, provider: p.provider ?? null, model: p.model ?? null, tools: p.tools ?? null, toolsDeny: p.toolsDeny ?? null, toolsByPreset: p.toolsByPreset ?? null, catalogDepth: catalogDepthOf(p), output: p.output ?? null })),
+                // 手写 map：新增字段必须**两处都加**（list 与 get），少一处就是界面读不到。
+                subagents: docs.map((p) => ({ name: p.name, enabled: p.enabled !== false, description: p.description, provider: p.provider ?? null, model: p.model ?? null, reasoningEffort: p.reasoningEffort ?? null, tools: p.tools ?? null, toolsDeny: p.toolsDeny ?? null, toolsByPreset: p.toolsByPreset ?? null, catalogDepth: catalogDepthOf(p), output: p.output ?? null })),
             };
         },
         'subagent-get': async (args) => {
@@ -669,7 +697,7 @@ export function createSubagentService(ctx, opts) {
             const p = docs.find((d) => d.name === name);
             if (!p)
                 return { ok: false, error: `人设不存在: ${name}` };
-            return { ok: true, persona: { name: p.name, description: p.description, provider: p.provider ?? '', model: p.model ?? '', tools: p.tools ?? [], toolsDeny: p.toolsDeny ?? [], toolsByPreset: p.toolsByPreset ?? {}, catalogDepth: catalogDepthOf(p), output: p.output ?? '', body: p.body } };
+            return { ok: true, persona: { name: p.name, description: p.description, provider: p.provider ?? '', model: p.model ?? '', reasoningEffort: p.reasoningEffort ?? '', tools: p.tools ?? [], toolsDeny: p.toolsDeny ?? [], toolsByPreset: p.toolsByPreset ?? {}, catalogDepth: catalogDepthOf(p), output: p.output ?? '', body: p.body } };
         },
         'subagent-create': async (args) => {
             const name = String((args && args.name) || '').trim();
@@ -982,6 +1010,9 @@ export function serializePersona(args) {
     const description = String((args && args.description) || '').replace(/\r?\n/g, ' ').trim();
     const provider = String((args && args.provider) || '').trim();
     const model = String((args && args.model) || '').trim();
+    // 思考强度：空值**不落盘**（与 `catalogDepth` 默认值同规矩）—— 免得每个新建的人设都多一行
+    // 说明"它和默认一样"，也保证老的人设文件回写后逐字节不变。
+    const reasoningEffort = normalizeReasoningEffort(args?.reasoningEffort);
     const tools = toStringList(args?.tools);
     // 黑名单字段兼容两种入参名：toolsDeny（UI/camel）与 tools_deny（snake）。
     const toolsDeny = toStringList(args?.toolsDeny ?? args?.tools_deny);
@@ -1006,6 +1037,8 @@ export function serializePersona(args) {
         lines.push('provider: ' + provider);
     if (model)
         lines.push('model: ' + model);
+    if (reasoningEffort)
+        lines.push('reasoningEffort: ' + reasoningEffort);
     if (hasCatalogDepth)
         lines.push('catalogDepth: ' + String(catalogDepth));
     for (const line of outputLines)