dsh-plugin-tool-management 0.16.6 → 0.18.0

package/lib/host-names.js

@@ -6,6 +6,156 @@
  * 少改一处就是「开关点了没反应」或「列表凭空少一行」。档案目录名同理。
  */
 export const MCP_CLIENT_MODULE = '@deepseek-ai/dsh-mcp-client';
+/**
+ * MCP 工具在模型工具表里的**命名前缀**：`mcp__<serverName>__<toolName>`。
+ *
+ * 这是宿主侧（MCP client 注册工具时）定的字符串契约，插件里十余处按它拼、按它解析
+ * （生成侧 `disabledToolNames`、执行侧 `isToolDisabledIn`、列表侧 `liveNames`、工具计数）。
+ * 抽到这里是为了"官方改了前缀"只需改一处 —— 但**改一处不够**：前缀一漂，停用表 / 门禁 /
+ * 工具计数会一起**静默**失明（守卫以为"这工具不在我的表里"于是放行）。
+ *
+ * 前向兼容的诚实边界（2026-09-30 审查 §5 F6）：这个契约**没有能力探测可做** ——
+ * `tools.schemas()` 只回 `name`/`description`（官方源码明确它「NEVER sent to the model」
+ * 的其余字段不暴露），拿不到"这条工具属于哪个模块"，所以无法独立判定一条 schema 是不是
+ * MCP 工具。唯一的可用线索是"工具名以 `mcp` 开头但不是本前缀"（官方改前缀多半会保留
+ * `mcp` 词根），据此在 `mcpmListView` 里做一次 inform-only 上报；换成完全不同的词根就
+ * 只能靠宿主升级清单人工核对。真要靠探测兜住，得先有官方暴露工具归属的接口。
+ */
+export const MCP_TOOL_PREFIX = 'mcp__';
+/**
+ * 一个工具名算不算「MCP 前缀漂移」的**证据**：以 `mcp` 开头，但词根后面**不是** `_`。
+ *
+ * 为什么要这么窄（2026-09-30 审查 §5 F6 实现时的自查）：本插件自己的工具就叫
+ * `mcp_manager_list` / `mcp_manager_…` —— 它们同样「以 mcp 开头但不是 `mcp__`」，把它们
+ * 算成证据会让这条上报在**每台机器上**误报（只要当前没有 MCP 服务器在跑）。而真正的前缀
+ * 漂移（`mcp:` / `mcp-` / `mcpX`）恰恰表现为「词根后面的分隔符变了」这一种形态。
+ * `mcp___` 这类改法会落进「没有证据」—— 宁可不报，也不给用户一个错的诊断。
+ */
+export function looksLikeMcpPrefixDrift(name) {
+    return /^mcp[^_]/.test(String(name == null ? '' : name));
+}
+/**
+ * MCP 工具全名 `mcp__<server>__<tool>` 的**唯一切分口径**。
+ *
+ * 为什么必须只有一个：同一个全名在插件里有两处要还原成 `(server, tool)` —— 执行侧守卫
+ * （`mcp/manager.ts` 的 `isToolDisabledIn`，决定「这个工具还能不能调」）与显示侧
+ * （`index.ts` 的 `toolKeyParts`，决定界面上的勾选键 `server/tool`）。它们此前**各写一套规则**：
+ * 守卫取「最长已知 serverName 前缀」，显示侧取「最后一个 `__`」。规则不同 = 同一份数据两边
+ * 结论不同；而 `serverName` 的校验（`/^[A-Za-z0-9_-]{1,32}$/`）**允许含 `__`**，所以这个歧义
+ * 真的能踩到（2026-09-30 审查 N1）。现在两处都走本函数。
+ *
+ * **残余歧义（如实标注）**：`mcp__a__b__t` 既可能是「server=a, tool=b__t」也可能是
+ * 「server=a__b, tool=t」—— 光看全名无法判定，必须有候选 serverName 集合才谈得上「切对」。
+ * 所以集合是**必填参数**，且两个调用点的集合**天然不同**，这不是漏改：
+ *
+ *   * 守卫问的是「这个工具被停用了吗」，权威依据就是**停用表**，集合 = 停用表的键。
+ *     把集合放宽到「全部已配置服务器」会**漏拦**：设 `a` 的 `b__c` 被停用、而 `a__b` 只是
+ *     配置了、没停用任何工具，全名 `mcp__a__b__c` 放宽后最长匹配取 `a__b`（tool 只剩 `c`）
+ *     → 查 `a__b` 未命中 → 放行一个真的被停用的工具（fail-open）。歧义时「偏向停用表里有的
+ *     那个服务器」才是守卫该有的 fail-closed 方向。
+ *   * 显示侧问的是「这个键该显示成哪个服务器下的哪个工具」，依据是**全部已知的真实服务器名**
+ *     ——补丁文件里的 `serverName`（权威、与切分结果无关）+ 停用表键 + 已知工具缓存键，
+ *     集合 = 三者并集（见 `serverNameCandidates`）。补丁那份必须在内：另外两份都是插件自己
+ *     写出来的（勾选键 / 上次切分的产物），单靠它们会在「首次遇到含 `__` 的名字」时切错，
+ *     而错键一旦进集合就会**锁死**错误结论（不自愈）。
+ *
+ * 两者在「服务器名含 `__`」时仍可能给出不同答案 —— 这是 `__` 当分隔符的固有歧义，靠集合
+ * 无法根除；根除要从入口拒绝含 `__` 的 serverName（契约层收紧，本轮明确不做）。`certain`
+ * 就是给这件事留的出口。
+ *
+ * 候选里取**最长**的那个（短候选会把 tool 截断成 `b__c`）—— 真实服务器名比「按分隔符猜」可信，
+ * 这也是 0.16.7 那版守卫选「最长已知前缀」的同一个理由。
+ * @param fullName - 形如 `mcp__<server>__<tool>` 的工具全名。
+ * @param serverNames - 候选 serverName 集合（见上；传空集合等于只走兜底）。
+ * @returns 切分结果；不是 MCP 工具名、或切不出非空 server/tool 时返回 null。
+ */
+export function splitMcpToolName(fullName, serverNames) {
+    const name = String(fullName == null ? '' : fullName);
+    if (!name.startsWith(MCP_TOOL_PREFIX))
+        return null;
+    const rest = name.slice(MCP_TOOL_PREFIX.length);
+    let matched = null;
+    if (serverNames) {
+        for (const candidate of serverNames) {
+            if (typeof candidate !== 'string' || candidate === '')
+                continue;
+            // tool 必须非空，否则 `mcp__a__` 会被切出空 tool
+            if (rest.length <= candidate.length + 2)
+                continue;
+            if (!rest.startsWith(candidate + '__'))
+                continue;
+            if (matched === null || candidate.length > matched.length)
+                matched = candidate;
+        }
+    }
+    if (matched !== null)
+        return { key: matched + '/' + rest.slice(matched.length + 2), server: matched, tool: rest.slice(matched.length + 2), certain: true };
+    // 一个候选都没命中 → 按最后一个 `__` 兜底（显示侧原先的口径），并如实标注「不确定」。
+    // 守卫侧不需要特别处理：猜出来的 server 不在停用表里，查表结果与「没有候选命中」一致。
+    const i = rest.lastIndexOf('__');
+    if (i <= 0)
+        return null;
+    const server = rest.slice(0, i);
+    const tool = rest.slice(i + 2);
+    return server && tool ? { key: server + '/' + tool, server, tool, certain: false } : null;
+}
+/**
+ * 显示侧切分的候选 serverName 集合：若干张「serverName → 任意」的表取键并集，
+ * 或直接给一份名字清单（`Iterable<string>`）。
+ *
+ * 为什么要这个函数：显示侧有多个调用点（`mcpmList` / `serverKnownTools` / 场景档案的
+ * `toolStates`），各自手写一遍 `Object.keys(...)` 迟早又会分叉 —— 而「集合不同」正是切分
+ * 结论不同的原因之一。集合的来源必须是**同一批**：补丁文件里的真实 serverName（唯一与切分
+ * 结果无关的来源）+ 停用表 + 已知工具缓存。前两者是插件自己写出来的，单靠它们会**循环论证**
+ * （见 `configuredServerNames` 的文档）。
+ */
+export function serverNameCandidates(...sources) {
+    const out = new Set();
+    for (const source of sources) {
+        if (!source || typeof source !== 'object')
+            continue;
+        // 名字清单（数组 / Set）优先按可迭代处理；`Record` 不可迭代，走下面的键枚举。
+        if (typeof source[Symbol.iterator] === 'function') {
+            for (const name of source)
+                if (typeof name === 'string' && name)
+                    out.add(name);
+            continue;
+        }
+        for (const name of Object.keys(source))
+            if (name)
+                out.add(name);
+    }
+    return out;
+}
+/**
+ * 候选 serverName 里有没有「`__` 说不清」的形状 —— N2 的判据（2026-09-30 审查）。
+ *
+ * 为什么要有它：`splitMcpToolName` 能在一批名字里选出**最长**的那个，但"选对"这件事本身
+ * 无法自证 —— 名字一旦含 `__`，「server 是 `a`、tool 是 `b__c`」与「server 是 `a__b`、tool 是
+ * `c`」在全名上完全同形。宿主自己的解析口径（取第一个 `__`）与展示口径（取最后一个）也不一致，
+ * 所以这不是"谁写错了"，是分隔符选得不合适。既不能改（改 serverName 校验会把存量服务器从
+ * "能管"变成"管不了"，见计划 §4 未决 1），那就**出声**：这两种形状一出现就上报，让用户知道
+ * 界面上的勾选可能落不到停用表里那条键上。
+ *
+ * **判据必须一条都不误报** —— 与 `looksLikeMcpPrefixDrift` 同一条纪律：没有这两种形状时
+ * 必须返回空，否则这条上报会变成每台机器都亮的噪声，等于没有。
+ * 名字不含 `__` 时，切分结果与"取第一个 `__`"、"取最后一个 `__`"三者一致，歧义不存在。
+ */
+export function ambiguousServerNames(names) {
+    const all = [...new Set(names)].filter((n) => typeof n === 'string' && n !== '');
+    const withSeparator = all.filter((n) => n.includes('__')).sort();
+    const prefixPairs = [];
+    for (const short of all) {
+        for (const long of all) {
+            // `short` 是 `long` 的 `__` 前缀：`mcp__<short>__<long.slice(...)>` 与
+            // `mcp__<long>__<剩下的>` 同形。`all` 已去重，所以每对只会出现一次。
+            if (short !== long && long.startsWith(short + '__'))
+                prefixPairs.push([short, long]);
+        }
+    }
+    prefixPairs.sort((a, b) => (a[0] + ' ' + a[1] < b[0] + ' ' + b[1] ? -1 : a[0] + ' ' + a[1] > b[0] + ' ' + b[1] ? 1 : 0));
+    return { withSeparator, prefixPairs };
+}
 /** `ensurePaths()` 的档案探测顺序（先 web 后 headless）；都不在才退到「任意带 patch 的档案」。 */
 export const PROFILE_CANDIDATES = ['web', 'headless'];
 /** 探测不到任何档案时的兜底目录名（历史上的默认档案）。 */

package/lib/http-api.js

@@ -0,0 +1,229 @@
+import { noteRuntime } from './compat/runtime-notes.js';
+import { recordOpAudit } from './audit-log.js';
+import { isReadCall } from './op-registry.js';
+import { TOKEN_CODE_BAD, TOKEN_MSG, fenceRejection, secretOpRejection } from './http-fence.js';
+export function installHttpApi(deps) {
+    // ---------- HTTP API route (UI half), registered defensively ----------
+    if (deps.webServer) {
+        // Cap request bodies (88 MiB): skill-upload carries Base64 folder/ZIP
+        // payloads (64 MiB of raw content). Reachability is decided by
+        // fenceRejection() below — the host's Host/Origin + browser-session fence
+        // (or a correct explicit token). `config.maxBodyBytes` overrides the cap
+        // (tests use a small value).
+        const configuredMaxBody = Number(deps.config?.maxBodyBytes);
+        // 默认 88 MiB：够塞下一份带多张大附件（图片 / PDF）的技能或记忆打包体，又不至于让
+        // 一个失控的客户端把进程内存吃光。`config.maxBodyBytes` 可覆盖（测试用小值）。
+        const DEFAULT_MAX_BODY_BYTES = 88 * 1024 * 1024;
+        const MAX_BODY = Number.isFinite(configuredMaxBody) && configuredMaxBody > 0 ? configuredMaxBody : DEFAULT_MAX_BODY_BYTES;
+        const readBody = (req) => new Promise((resolve, reject) => {
+            // 先看 content-length：注定超限的请求在**读第一个字节之前**就拒掉。以前只能边收边数，
+            // 一个 5 GB 的上传会先让我们缓冲满 88 MiB 才回错。读取流照旧 drain（一个字节都不留），
+            // 否则响应写完后服务端会直接拆连接，客户端可能在上传中途拿到网络错误而不是下面这句 JSON。
+            // 错误消息必须含 `body too large` —— 后面的 catch 靠这个子串分流。
+            const declared = Number(req.headers && req.headers['content-length']);
+            if (Number.isFinite(declared) && declared > MAX_BODY) {
+                const drain = req.resume;
+                if (typeof drain === 'function')
+                    drain.call(req);
+                reject(new Error('request body too large'));
+                return;
+            }
+            // Accumulate Buffers and decode ONCE at the end: decoding each chunk
+            // separately corrupts multi-byte UTF-8 characters that straddle a
+            // chunk boundary (e.g. long Chinese skill bodies).
+            const chunks = [];
+            let size = 0;
+            req.on('data', (c) => {
+                const buf = Buffer.isBuffer(c) ? c : Buffer.from(String(c));
+                size += buf.length;
+                if (size > MAX_BODY) {
+                    reject(new Error('request body too large'));
+                    return;
+                }
+                chunks.push(buf);
+            });
+            req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+            req.on('error', reject);
+        });
+        // 宿主 BrowserAuth 栅栏。宿主的鉴权**只包在它自己注册的路由上**——dsh-host-webserver
+        // 没有全局中间件，既定约定是每个注册方自己调 connection.requestRejection(req)：
+        // 它先做 Host/Origin 栅栏（Host 必须是回环或 deployment 派生的 LAN IP 字面量，
+        // 这是 DNS rebinding 唯一伪造不了的头），再叠加 browser-session cookie 鉴权。
+        // 本插件此前只查公开常量 x-dsh-plugin 与自比对（Origin.host === Host）的 "同源"，
+        // 两者都挡不住 rebind 后的网页或本机任意进程 —— 等于没鉴权。现在优先走宿主栅栏。
+        const connection = (() => {
+            try {
+                return deps.ctx.get('connection');
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        try {
+            // ctx.effect wires the route's disposer into this plugin's scope, so an
+            // unload (HMR removal, disable, update) unregisters the route — the
+            // documented cleanup contract (webServer.register does not auto-scope).
+            deps.ctx.effect(() => deps.webServer.register({
+                kind: 'exact',
+                path: '/dsh-plugin-tool-management/api',
+                handler: async (req, res) => {
+                    // 鉴权顺序：POST-only → 插件门禁头（防误触，不是凭证）→ 宿主栅栏
+                    // （Host/Origin + browser-session cookie）→ 可选访问令牌。令牌是本地工具与
+                    // LAN 部署的逃生门：**令牌正确即视为已授权**，可越过浏览器鉴权。
+                    //
+                    // 「未配置令牌时」别读成"仍有门禁"：下面的写 op 判据是
+                    // `if (TOKEN && WRITE_OPS.has(op))` —— `TOKEN === ''` 时整条短路，79 个写 op
+                    // 只剩 `fenceRejection` 一道。而它自身有两种形态：宿主栅栏在场时含 cookie 鉴权；
+                    // 栅栏缺席或抛错时退回本地判定，**只查回环 Host 与（若给了）Origin 自比对**，
+                    // 没有 cookie 那一层 —— 本机任意进程都能调写 op。所以准确说法是：
+                    // 未配置令牌时不再有「**无栅栏**放行」的缺口，但进程级边界只有配了令牌才有。
+                    const hdr = (name) => {
+                        const v = req.headers?.[name];
+                        return Array.isArray(v) ? v[0] ?? '' : v ?? '';
+                    };
+                    if (String(req.method || 'POST').toUpperCase() !== 'POST') {
+                        res.writeHead(405, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: 'method not allowed' }));
+                        return;
+                    }
+                    if (hdr('x-dsh-plugin') !== 'dsh-plugin-tool-management') {
+                        res.writeHead(403, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: 'missing plugin gate header' }));
+                        return;
+                    }
+                    // 「本次带的这串对不对」比的是**存量**令牌：关掉令牌功能之后仍然要凭它才能开回来、
+                    // 换掉、或看明文（要求 9）。
+                    const tokenAccepted = deps.CONFIG_TOKEN !== '' && deps.tokenMatches(hdr('x-dsh-token'));
+                    // 验过就置闩（本次进程一次即可）。`agent/pre-step` 的令牌门禁读的就是它 ——
+                    // 那一边看不到请求头，只能由这里告诉它"这台机器已经有人验过令牌了"。
+                    if (tokenAccepted)
+                        deps.markAccepted();
+                    if (!tokenAccepted) {
+                        const fence = fenceRejection(req, connection);
+                        if (fence) {
+                            res.writeHead(fence.status, { 'content-type': 'application/json' });
+                            res.end(JSON.stringify({ ok: false, error: fence.error }));
+                            return;
+                        }
+                    }
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                    try {
+                        let payload = {};
+                        try {
+                            payload = JSON.parse((await readBody(req)) || '{}');
+                        }
+                        catch (e) {
+                            if (String(e?.message).includes('body too large')) {
+                                res.end(JSON.stringify({ ok: false, error: '请求体过大' }));
+                                return;
+                            }
+                            /* otherwise fall through with {} */
+                        }
+                        const op = String(payload.op || '');
+                        // 敏感 op（会吐明文密钥与完整配置）：**配了令牌就必须带对的**，没配令牌则不设防
+                        // （判定与理由见 http-fence.ts 的 secretOpRejection —— 用户裁定 2026-09-19：
+                        // 没配令牌时那道门没有出路，用户无从填一个不存在的令牌）。
+                        // 之前这里只查"有没有 Origin 头"，而 token 为空时它形同虚设 —— 任何能
+                        // 打开 GUI 的浏览器都拿得到全部密钥原文。
+                        if (deps.SENSITIVE_OPS.has(op)) {
+                            // 明文门禁看的是**存量**令牌（CONFIG_TOKEN 而不是生效值 TOKEN）：关掉令牌
+                            // 功能之后仍然"要凭存量令牌才给明文"—— 那条路是通的（填对就能看），
+                            // 与"从来没配过"不同。
+                            const gate = secretOpRejection({ tokenConfigured: deps.CONFIG_TOKEN !== '', tokenAccepted });
+                            if (gate) {
+                                res.end(JSON.stringify({ ok: false, error: gate.error, code: gate.code }));
+                                return;
+                            }
+                        }
+                        // 「读改写」两态 op（`inject-settings` / `tool-table` / `scene-settings` /
+                        // `mcpm-settings`）：同一个名字既读又写，于是整条 op 被列进 WRITE_OPS —— 读侧也
+                        // 一起被拦，界面表现是"没填令牌时整块设置消失、填了还要刷新才出现"（2026-09-19
+                        // 用户报的）。判据是**这次调用要不要写**，不是 op 名在不在名单里。
+                        // 判据本身在登记表（`writeWhen`），这里不再手写一份 —— 手写那份只认 `set:true`，
+                        // 于是 `tool-table` 的 `presetSave` / `presetDelete` 被当成读放行，配了令牌也能
+                        // 只凭宿主栅栏改侧车（审查 F2，0.17.0 修）。
+                        const readOnlyCall = isReadCall(op, payload.args);
+                        if (deps.TOKEN && deps.WRITE_OPS.has(op) && !readOnlyCall && !deps.tokenMatches(hdr('x-dsh-token'))) {
+                            // 文案与明文门禁同源（http-fence.ts），code 也统一 —— 界面据此在最右侧挂
+                            // 「去填令牌」跳转按钮。这条错误会出现在**任意**页面，而入口只有一个。
+                            res.end(JSON.stringify({ ok: false, code: TOKEN_CODE_BAD, error: TOKEN_MSG }));
+                            return;
+                        }
+                        // 令牌状态（只读，**不需要**令牌本身）：回答"宿主配没配"、"本次带的这串对不对"、
+                        // "配置文件里的改动是不是还没重启生效"、"本次进程的标识"。就地回答而不是进 handlers 表：
+                        // 前者的答案来自本次请求头与进程状态，而后者的 handlers 只拿得到 args。
+                        // 不返回令牌、也不返回它的任何片段 —— 泄给同源页面等于把最后一道门交出去。
+                        if (op === 'token-status') {
+                            const state = await deps.tokenConfigState();
+                            res.end(JSON.stringify({
+                                ok: true,
+                                // 「宿主配置了令牌」= 配置里**有**值（关掉也算有：随时能开回来）。
+                                hostConfigured: deps.CONFIG_TOKEN !== '',
+                                // 当前进程里令牌功能是开还是关（关掉 = 写操作不要求令牌）。
+                                disabled: deps.TOKEN_DISABLED,
+                                // 「当前进程里令牌**在生效**」= 写操作要不要令牌。关掉或没配都是 false。
+                                // 界面据此判断"填令牌"这件事有没有意义（没生效时填了也没人验，还会把
+                                // 一句无处可填的提示挂在屏幕上 —— 用户 2026-09-19 报的就是这个）。
+                                active: deps.TOKEN !== '',
+                                accepted: tokenAccepted,
+                                bootId: deps.BOOT_ID,
+                                configHasToken: state.configHasToken,
+                                configDisabled: state.configDisabled,
+                                configFound: state.found,
+                                pendingRestart: state.pendingRestart,
+                            }));
+                            return;
+                        }
+                        // 设置 / 关闭令牌：同样就地处理（理由见 tokenConfigure 的注释 —— 也正因为不进
+                        // handlers，模型侧没有任何工具能间接关掉它）。
+                        if (op === 'token-configure') {
+                            res.end(JSON.stringify(deps.withPatchWarnings(await deps.tokenConfigure(payload.args || {}, tokenAccepted))));
+                            return;
+                        }
+                        // 「清除令牌」的配套：把「本次启动已验过」的闩重新挂上。没有它，解锁一次之后
+                        // 清除令牌 + 强刷新，浏览器里已无令牌，闩却挂着 —— pre-step 门禁读闩
+                        // （tokenGateActive），整个启动期都放行对话（2026-09-19 用户实测的漏洞）。
+                        // 不要求凭证：它只会收紧（要求重新验令牌），给不了任何人任何权限；同样不进
+                        // handlers —— 模型不该有能力拨这颗闩。
+                        if (op === 'token-unaccept') {
+                            deps.unmarkAccepted();
+                            res.end(JSON.stringify({ ok: true }));
+                            return;
+                        }
+                        const fn = deps.handlers[op];
+                        if (!fn) {
+                            res.end(JSON.stringify({ ok: false, error: '未知操作: ' + op }));
+                            return;
+                        }
+                        const result = await fn(payload.args || {});
+                        // 「最近改动」流水：来源 = 面板（这条 HTTP 路由是界面唯一的入口）。
+                        // 「这次算不算写」的判据在 recordOpAudit 里（与写门禁同源：登记表的 `writeWhen`）
+                        // —— 不在这里再传一次 `readOnlyCall`，两处各判一次迟早会分家。
+                        recordOpAudit(op, payload.args || {}, 'panel', result);
+                        res.end(JSON.stringify(deps.withPatchWarnings(result === undefined ? { ok: true } : result)));
+                    }
+                    catch (e) {
+                        res.end(JSON.stringify({ ok: false, error: deps.message(e) }));
+                    }
+                },
+            }), 'dsh-plugin-tool-management: api route');
+        }
+        catch (e) {
+            // A registration failure must never take down the whole entry: log and continue.
+            console.error('[dsh-plugin-tool-management] webServer route registration failed:', deps.message(e));
+            // 结构性弱点（2026-09-30 审查 §5 F4）：compat-status **本身就走这条路由**，所以路由没注册上
+            // 时兼容页也拿不到这条降级行 —— 面板是**整页失联**，不是"少一行"。这里至少把它写进运行期
+            // 上报通道（日志里必然有一条，进程内可查），并在 README 里写明"面板空白先看宿主日志"。
+            // 之所以不是"必然可见"的告警：可见的通道就是这条路由，它自己挂了就没得显示。
+            noteRuntime({
+                id: 'web-server-route',
+                label: 'HTTP 路由注册',
+                kind: 'write',
+                fallback: 'inform-only',
+                detail: '向宿主 webServer 注册 API 路由失败（' + deps.message(e) + '）：插件面板与全部 HTTP op 不可用（兼容页也走这条路由，所以它也打不开）。宿主日志里有同一条记录；模型工具不受影响。',
+                detailKey: 'web-server-route.register-failed',
+                params: { reason: deps.message(e) },
+            });
+        }
+    }
+}

package/lib/hub.js

@@ -45,6 +45,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from '
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, join } from 'node:path';
 import { resolveDshHome } from './skills/core.js';
+import { isSameOrDescendant } from './paths.js';
 /** hub 根目录名（`$DSH_HOME` 下）。 */
 export const HUB_DIR = 'tool-management';
 /** hub 根绝对路径。 */
@@ -91,7 +92,10 @@ const ROOT_FILE_MOVES = [
 ];
 /** 宿主 patch 的备份名（`cordis.patch.yml.bak-<时间戳>`）。 */
 export function isPatchBackupName(name) {
-    return /^cordis\.patch\.yml\.bak-\d{8}-\d{6}$/.test(basename(name));
+    // 两代时间戳都认（0.17.0 起加了毫秒与进程内序号，见 index.ts 的 backupStamp）。
+    // 这里只用于「把散落在 $DSH_HOME / profiles 下的旧备份搬进 hub/backups」—— 新格式备份
+    // 本来就直写 hub/backups，但两处谓词保持同一口径，免得将来手工搬进来一份就漏掉。
+    return /^cordis\.patch\.yml\.bak-\d{8}-\d{6}(?:\d{6})?$/.test(basename(name));
 }
 /**
  * 布局迁移（同步、幂等、只搬不删、绝不覆盖）。**必须在任何读盘之前调用一次**：
@@ -241,6 +245,8 @@ const LEGACY_TRASH_KINDS = {
     prompts: ['agents-md'],
     subagents: ['agents'],
     scenes: [],
+    // 0.18.0 才有的域，没有旧名字要认。
+    'quick-prompts': [],
 };
 /** 某一类回收站的根目录：`hub/trash/<kind>-trash`。 */
 export function trashKindDir(kind) {
@@ -297,10 +303,21 @@ export async function moveToTrash(kind, name, moves, data) {
     const id = newTrashId();
     const dir = join(trashKindDir(kind), id);
     const done = [];
+    // 入口先过一遍谓词（原先只有恢复侧 `moveOutOfTrash` 校验，删除侧不看）：`dest` 最终会写进
+    // manifest 的 `files[]`，恢复时按它搬回来 —— 入口放一个非法名进去，等于把失败推给
+    // "将来某一天点恢复"（场景回收站那条链就是这么坏掉的）。现在当场拒绝、什么都不搬，
+    // 由调用方如实报错（审查 P0-2 / P2-14）。
+    for (const move of moves) {
+        if (!isValidTrashPayloadPath(move.dest))
+            return { ok: false, error: `负载名非法，未搬动任何文件：${move.dest}` };
+    }
     try {
         await mkdir(dir, { recursive: true });
         for (const move of moves) {
             const to = join(dir, move.dest);
+            // 嵌套负载（`bundle1/bundle1.md`）的父目录不存在时 `rename` 必然失败 —— 那本来不是错，
+            // 但接着靠 `cp` 的隐式建父目录兜底是不可依赖的跨平台行为。显式建出来。
+            await mkdir(dirname(to), { recursive: true });
             try {
                 await rename(move.from, to);
             }
@@ -309,6 +326,9 @@ export async function moveToTrash(kind, name, moves, data) {
                 await cp(move.from, to, { recursive: true });
                 await rm(move.from, { recursive: true, force: true });
             }
+            // 后置断言（与恢复侧同一道）：谓词已挡掉 `..`，这里防的是"条目目录里恰好有个链接"。
+            if (!isSameOrDescendant(dir, to))
+                throw new Error(`负载越出条目目录：${move.dest}`);
             done.push({ from: move.from, to });
         }
         const manifest = {
@@ -372,20 +392,42 @@ export async function readTrashEntry(kind, id) {
     return await readManifest(kind, id);
 }
 /**
- * 条目里的一个负载名是不是"就在这个条目目录里"。
+ * 条目里的一个负载名是不是"一条**安全的相对路径**"（可以含 `/`）。
+ *
+ * 为什么允许 `/`（2026-09-30，审查 P0-2）：场景回收站的负载**天然是目录树** —— 一个场景目录
+ * 里的记忆可能是 `<场景>/<名>.md`，也可能是 bundle 形态 `<场景>/<名>/<名>.md` 或任意子目录。
+ * 原来这里对任何含 `/` 的名字一律返回 false，于是「含嵌套记忆的场景」删除能成功（`moveToTrash`
+ * 侧靠 `cp` 兜底）、恢复**必然失败**，且失败后场景目录已非空 → 再也恢复不了。
+ *
+ * 判据（与 `paths.ts` 的单段校验同源，只是放宽到多段）：
+ *   - 只认 `/` 作分隔符（反斜杠在 Windows 上等价，留着只会让判据分叉）；
+ *   - 拒绝对路径（前导 `/` `\` 或盘符）与 `..` / `.` / 空段 —— 这是**路径穿越**那一类；
+ *   - 每段拒绝控制字符、Windows 非法字符 `<>:"|?*`、首尾空白与尾点（Windows 会静默规整它们，
+ *     于是"写进去的名字"与"读出来的名字"不再是同一个）；
+ *   - 条目根下的 `manifest.json` 是清单，不许当负载。
  *
- * 为什么 id 与场景名都有谓词、这里还得多一道：`manifest.json` 的 `files[]` 是**磁盘上的数据**，
- * 它跟 id 不一样 —— id 只由本模块生成（`isValidTrashId` 严格白名单），而 files 可能来自
- * 用户手改、别的进程、或一份被塞进来的恶意档案包。不校验就 `join(dir, dest)` 等于给了
- * "任意相对路径读源 + 任意绝对目录建目标"的能力（`mkdir(dirname(to))` 会顺手把目录建出来）。
+ * 仍然拒绝 `.` 开头的段吗？**不**（旧谓词拒绝）。理由：`..` 与 `.` 这两个才是穿越，靠精确判据
+ * 挡住即可；而 `.DS_Store` 这类隐藏文件可能真的躺在用户的场景目录里，一刀切会让「删除这个场景」
+ * 从"能用但恢复不了"变成"直接删不掉" —— 那是把问题换个地方，不是修好它。
  */
-export function isValidTrashPayloadName(dest) {
+export function isValidTrashPayloadPath(dest) {
     const text = String(dest ?? '');
-    if (!text || text.startsWith('.') || text.includes('\0'))
+    if (!text || text.includes('\0'))
         return false;
-    if (/[\\/]/.test(text))
+    if (text.startsWith('/') || text.startsWith('\\') || /^[A-Za-z]:/.test(text))
         return false;
-    if (text === 'manifest.json')
+    if (text.includes('\\'))
+        return false;
+    const parts = text.split('/');
+    for (const part of parts) {
+        if (part === '' || part === '.' || part === '..')
+            return false;
+        if (/[<>:"|?*\u0000-\u001f]/.test(part))
+            return false;
+        if (part.endsWith(' ') || part.endsWith('.'))
+            return false;
+    }
+    if (parts.length === 1 && parts[0] === 'manifest.json')
         return false;
     return true;
 }
@@ -397,9 +439,40 @@ export async function moveOutOfTrash(kind, id, dest, to) {
     const dir = trashEntryPath(kind, id);
     if (dir === null)
         throw new Error(`回收站条目 id 非法：${id}`);
-    if (!isValidTrashPayloadName(dest))
+    if (!isValidTrashPayloadPath(dest))
         throw new Error(`回收站负载名非法：${dest}`);
     const from = join(dir, dest);
+    // 后置断言：谓词已经挡掉了 `..`，这一条挡的是「条目目录里恰好有个指向别处的链接」——
+    // 那种情况下 `join` 看着在条目内，实际会从条目外取源。
+    if (!isSameOrDescendant(dir, from))
+        throw new Error(`回收站负载越出条目目录：${dest}`);
+    await mkdir(dirname(to), { recursive: true });
+    try {
+        await rename(from, to);
+    }
+    catch {
+        await cp(from, to, { recursive: true });
+        await rm(from, { recursive: true, force: true });
+    }
+}
+/**
+ * 把一个文件/目录搬**进已存在的条目**（`moveOutOfTrash` 的反向补充，专给回滚用）。
+ *
+ * 为什么需要它：恢复是逐个负载搬的，中途失败时必须把**已经搬出去的那几个**放回条目里，
+ * 否则它们留在目标目录里 —— 而恢复的下一次尝试会撞「目标目录已有内容」的检查，
+ * 这个条目就再也恢复不了了（场景回收站那条链正是这么坏掉的，审查 P0-2）。
+ * 谓词与后置断言与 `moveOutOfTrash` 完全一致（同一道闸，两个方向）。
+ * @throws 条目 id 或负载名非法时抛错（调用方按"回滚失败"处理）。
+ */
+export async function moveIntoTrash(kind, id, from, dest) {
+    const dir = trashEntryPath(kind, id);
+    if (dir === null)
+        throw new Error(`回收站条目 id 非法：${id}`);
+    if (!isValidTrashPayloadPath(dest))
+        throw new Error(`回收站负载名非法：${dest}`);
+    const to = join(dir, dest);
+    if (!isSameOrDescendant(dir, to))
+        throw new Error(`回收站负载越出条目目录：${dest}`);
     await mkdir(dirname(to), { recursive: true });
     try {
         await rename(from, to);

package/lib/imports/parsers.js

@@ -45,33 +45,58 @@ function flushTurn(current, turns) {
     if (text)
         turns.push({ role: current.role, text });
 }
+/** 嗅探时最多看几行（见 `sniffFormat`）。 */
+const SNIFF_LINES = 5;
 /**
- * Detect the transcript format. Extension wins; content sniffing only applies
- * when the name carries no recognized extension.
+ * 按**内容**嗅探转录格式。只看前若干条非空行，不读全篇。
+ *
+ * 为什么不是「只看第一行」：Claude Code 的转录稿常在正文前带 `summary` / `system` 行，
+ * 那些行也是 JSON 但 `type` 不是 user/assistant；只看第一行会把它们判成 generic。
+ * 只扫前 `SNIFF_LINES` 行是为了压低误报 —— 一份 Markdown 正文里偶然粘了一段
+ * `{"role":"user"}` 的 API 载荷，不该让整份稿子按 JSONL 解析。
  * @returns {'jsonl' | 'markdown' | 'generic'}
  */
-export function detectFormat(fileName, content) {
-    const name = String(fileName || '').toLowerCase();
-    if (/\.jsonl$/.test(name))
-        return 'jsonl';
-    if (/\.(md|markdown)$/.test(name))
-        return 'markdown';
-    if (/\.txt$/.test(name))
-        return 'generic';
-    const first = String(content || '').split(/\r?\n/).map((s) => s.trim()).find((s) => s) || '';
-    if (first.startsWith('{')) {
+function sniffFormat(content) {
+    const lines = String(content || '')
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter((s) => s);
+    for (const line of lines.slice(0, SNIFF_LINES)) {
+        if (!line.startsWith('{'))
+            continue;
         try {
             // JSON 值实际形状未知；若为对象，type/role 字段由下方运行时比较判定
-            const obj = JSON.parse(first);
-            if (obj && typeof obj === 'object' && (obj.type === 'user' || obj.type === 'assistant' || obj.role === 'user' || obj.role === 'assistant'))
+            const obj = JSON.parse(line);
+            if (obj && typeof obj === 'object' && !Array.isArray(obj) &&
+                (obj.type === 'user' || obj.type === 'assistant' || obj.role === 'user' || obj.role === 'assistant'))
                 return 'jsonl';
         }
-        catch (e) { /* not JSONL after all */ }
+        catch (e) { /* 这一行不是 JSON，继续往下看 */ }
     }
+    const first = lines[0] || '';
     if (HEADING_RE.test(first) || BOLD_PREFIX_RE.test(first))
         return 'markdown';
     return 'generic';
 }
+/**
+ * Detect the transcript format. Extension wins; content sniffing applies
+ * when the name carries no recognized extension **or is `.txt`**.
+ *
+ * `.txt` 走嗅探，不是无条件 generic（2026-09-30 审查 F12）：`.txt` 恰恰是**最常被改名**的
+ * 扩展名 —— Claude Code / Cursor 的 JSONL、Markdown 转录稿都可能被存成 `transcript.txt`
+ *（客户端拿不到文件名时自己就默认这个名字）。原来无条件判 generic，于是整份对话被折成
+ * **一条 user 消息**、分轮结构全失、零警告，op 还回 `{ok:true,count:1}`。
+ * `.jsonl` / `.md` 仍按扩展名直判（那两种名字下内容必然是同一种，嗅探没有收益）。
+ * @returns {'jsonl' | 'markdown' | 'generic'}
+ */
+export function detectFormat(fileName, content) {
+    const name = String(fileName || '').toLowerCase();
+    if (/\.jsonl$/.test(name))
+        return 'jsonl';
+    if (/\.(md|markdown)$/.test(name))
+        return 'markdown';
+    return sniffFormat(content);
+}
 /**
  * Parse a Claude Code / Cursor style JSONL transcript.
  * Recognizes `{type:'user'|'assistant', message:{role,content}}` (Claude Code)