dsh-plugin-tool-management 0.16.6 → 0.18.0

package/lib/mcp/patch-yaml.js

@@ -4,7 +4,8 @@
 // 行级块编辑（removeEntryAll / removeMarked / appendBlock / spliceRanges）。
 // 纯字符串运算，不碰 ctx / 文件系统 —— 读写盘由调用方负责。
 import { MCP_CLIENT_MODULE } from '../host-names.js';
-import { maskedKeysIn } from './secret-guard.js';
+import { isMaskedUrl, maskedKeysIn } from './secret-guard.js';
+import { readToggleEntry } from './override-blocks.js';
 // ---------- YAML generation ----------
 function yq(v) { return typeof v === 'string' ? JSON.stringify(v) : String(v); }
 function yplain(v) { return /^[A-Za-z0-9_.:@%+=/-]+$/.test(v) ? v : yq(v); }
@@ -44,20 +45,33 @@ export function buildInsertBlock(row) {
                 lines.push('          ' + yq(k) + ': ' + yq(env[k]));
         }
     }
-    if (row.toolCallTimeoutMs)
+    // 超时值只在**能解析成有限数、且非 0** 时才写这一行（2026-09-30 审查 P2-13）。
+    // 此前是 `if (row.toolCallTimeoutMs)`：手写补丁里这个键被读成字符串（`unquote` 只认纯数字），
+    // 于是 `"30s"` / `"abc"` 这类值会走 `Number()` → `NaN` 落盘，补丁里出现一个**不是数字**的
+    // `toolCallTimeoutMs` —— 宿主读到的要么是字符串、要么是 YAML 里的字符串 "NaN"，两种都不是
+    // 超时毫秒数，而界面显示的是"已配置"。认不出来就不写这一行（键缺失 = 用宿主默认值）。
+    // `0` 同样不写：界面上"没填"读出来就是 0，写成 `toolCallTimeoutMs: 0` 会让每次工具调用立刻超时。
+    if (row.toolCallTimeoutMs && Number.isFinite(Number(row.toolCallTimeoutMs))) {
         lines.push('        toolCallTimeoutMs: ' + Number(row.toolCallTimeoutMs));
+    }
     // 结构性兜底：这里是所有 MCP 写路径的**唯一** YAML 出口。打码值到这一步还没被拦下，
     // 说明某个调用点漏过了 ./secret-guard.js —— 那是代码缺陷，宁可整次写入失败，
     // 也不能把 `••••••` 写进补丁文件（真密钥一旦被覆盖就找不回来了：本机 2026-09-18
     // `TAVILY_API_KEY` 就是这样丢的）。所以这里**抛错**而不是静默剔除。
     //
-    // 覆盖范围的边界（别读成"所有字段都查了"）：断言只查 env / headers 的整串 `•` 形态。
-    // URL 的打码是另一套（查询串换成 `<redacted>`），由调用方经 `resolveMaskedUrl` 收敛，
-    // 不在这里 —— 它需要"没有原值就拒绝"这种带上下文的裁决，不是一句断言能表达的。
+    // 两种形态都查（2026-09-30 审查 F4 补上第二种）：env / headers 的整串 `•`，
+    // 以及 URL 的 userinfo / 查询串 / 片段哨兵（`isMaskedUrl`）。此前只有前者，
+    // 注释自己写着"URL 的打码是另一套……不在这里"—— 于是 `mcpmAdd` 与 `mcpmImport`
+    // 两条写路径都没有 `resolveMaskedUrl`，打码 URL 会原样落盘，**且不产生任何 warning**。
+    // 各调用点仍应自己做「有旧值就顶替、没有就拒绝/跳过」的裁决（那需要上下文），
+    // 这里的断言只是"漏了就吵"的最后一道。
     const leaked = [...maskedKeysIn(row.env), ...maskedKeysIn(row.headers)];
     if (leaked.length) {
         throw new Error('拒绝写入：' + leaked.join('、') + ' 的值仍是打码占位符（调用方应先经 resolveMaskedKv 收敛）');
     }
+    if (row.transport === 'streamable-http' && isMaskedUrl(row.url)) {
+        throw new Error('拒绝写入：url 仍是打码形态（' + String(row.url) + '）—— 调用方应先经 resolveMaskedUrl 收敛（有旧值顶替、没有则拒绝或跳过）');
+    }
     return lines.join('\n');
 }
 export function buildDisableBlock(id, disabled) {
@@ -133,8 +147,16 @@ function parseEntry(lines) {
                 entry.id = unquote(kv.value);
             else if (kv.key === 'name')
                 entry.name = unquote(kv.value);
-            else if (kv.key === 'disabled')
-                entry.disabled = kv.value === 'true';
+            else if (kv.key === 'disabled') {
+                // 只认**字面量** true / false（2026-09-30 审查 P2-6）：`!!js` 这类读不出来的写法
+                // 此前被算成**显式 false**，于是"读不出来"与"明确启用"混成同一个值 —— 覆盖块会拿它
+                // 去改写当前生效值（`parseRows` 的 `entry.disabled !== undefined` 那道闸因此失效）。
+                // 读不出来就保持 `undefined` = 不表态，让生效值维持原样。
+                if (kv.value === 'true')
+                    entry.disabled = true;
+                else if (kv.value === 'false')
+                    entry.disabled = false;
+            }
             continue;
         }
         if (indent <= configIndent) {
@@ -164,6 +186,68 @@ function parseEntry(lines) {
     }
     return entry;
 }
+/** 按顶层 `- ` 切块：每个块从一行 `- ` 开始，到下一个 `- ` 之前。首块之前的内容丢弃。 */
+function splitTopBlocks(lines) {
+    const blocks = [];
+    let current = null;
+    for (const line of lines) {
+        if (/^- /.test(line)) {
+            if (current !== null)
+                blocks.push(current);
+            current = line;
+        }
+        else if (current !== null) {
+            current += '\n' + line;
+        }
+    }
+    if (current !== null)
+        blocks.push(current);
+    return blocks;
+}
+/** 一个 `- insert:` 块里的子条目（按 `    - ` 4 空格缩进切）。 */
+function splitInsertChildren(blockText) {
+    const parts = blockText.split('\n');
+    const children = [];
+    let j = 0;
+    while (j < parts.length) {
+        if (/^    - /.test(parts[j])) {
+            const lines = [parts[j]];
+            j++;
+            while (j < parts.length && !/^    - /.test(parts[j])) {
+                lines.push(parts[j]);
+                j++;
+            }
+            children.push(lines);
+        }
+        else
+            j++;
+    }
+    return children;
+}
+/**
+ * 文件里**所有** insert 子条目的 id（**不限 loader 名**）。
+ *
+ * 为什么不能复用 `parseRows`：它只收 `name === MCP_CLIENT_MODULE` 的行（本插件只管 MCP），
+ * 而「两条同 id 的 insert 会让插件组装失败、**DSH 起不来**」这个约束对**任何** loader 都成立。
+ * 只统计 MCP 行的话，导入一条非 MCP loader 就能撞出第二条同 id 条目而守卫看不见
+ * （2026-09-30 审查 P1-5）。
+ *
+ * 只收 **insert 子条目**，不收顶层覆盖块：覆盖块的 id 本来就应该与某个 insert 相同，
+ * 那是正常用法而非重复。
+ */
+export function insertEntryIds(content) {
+    const out = [];
+    for (const blockText of splitTopBlocks(content.split(/\r?\n/))) {
+        if (!/^- insert:/.test(blockText.split('\n')[0]))
+            continue;
+        for (const childLines of splitInsertChildren(blockText)) {
+            const entry = parseEntry(childLines);
+            if (entry.id)
+                out.push(entry.id);
+        }
+    }
+    return out;
+}
 export function parseRows(content) {
     const lines = content.split(/\r?\n/);
     const managedIds = new Set();
@@ -175,38 +259,11 @@ export function parseRows(content) {
             managedIds.add(m[1].trim());
     }
     const rows = [];
-    const blocks = [];
-    let current = null;
-    for (const line of lines) {
-        if (/^- /.test(line)) {
-            current = { text: line };
-            blocks.push(current);
-        }
-        else if (current) {
-            current.text += '\n' + line;
-        }
-    }
-    for (const block of blocks) {
-        const head = block.text.split('\n')[0];
+    for (const blockText of splitTopBlocks(lines)) {
+        const head = blockText.split('\n')[0];
         if (/^- insert:/.test(head)) {
-            const parts = block.text.split('\n');
-            const children = [];
-            let j = 0;
-            while (j < parts.length) {
-                if (/^    - /.test(parts[j])) {
-                    const child = { lines: [parts[j]] };
-                    j++;
-                    while (j < parts.length && !/^    - /.test(parts[j])) {
-                        child.lines.push(parts[j]);
-                        j++;
-                    }
-                    children.push(child);
-                }
-                else
-                    j++;
-            }
-            for (const child of children) {
-                const entry = parseEntry(child.lines);
+            for (const childLines of splitInsertChildren(blockText)) {
+                const entry = parseEntry(childLines);
                 if (entry && entry.name === MCP_CLIENT_MODULE) {
                     rows.push({ id: entry.id, name: entry.name, disabled: entry.disabled, config: entry.config, managed: managedIds.has(entry.id) });
                 }
@@ -217,7 +274,7 @@ export function parseRows(content) {
             // `@deepseek-ai/dsh-app-boot` 的 applyEntryPatches 只给此刻已入索引的 id 打补丁
             //（insert 是插入时立即入索引），命中不到就 warn + skip。所以写在 insert 之前的
             // 覆盖块在宿主侧是 no-op —— 这里同样丢弃，界面才和生效值一致。
-            const entry = parseEntry(block.text.split('\n'));
+            const entry = parseEntry(blockText.split('\n'));
             if (entry && entry.name === MCP_CLIENT_MODULE && entry.disabled !== undefined) {
                 const row = rows.find((r) => r.id === entry.id);
                 if (row)
@@ -229,8 +286,111 @@ export function parseRows(content) {
 }
 // ---------- line-based block editing ----------
 export function splitLines(content) { return content.split(/\r?\n/); }
+/** 映射键（裸 / 双引号 / 单引号三种写法）。 */
+const YAML_KEY_PART = String.raw `(?:[^#\s][^:]*|"[^"]*"|'[^']*')`;
+/** 节点属性：锚点 `&a` 与标签 `!tag` / `!!js` / `!<verbatim>`，可多个、可任意顺序。 */
+const YAML_NODE_PROPS = String.raw `(?:[&!]\S+\s+)*`;
+/**
+ * 块标量头部的指示符，**两种顺序都合法**（YAML 规范 `c-b-block-header`）：
+ *   `( 缩进指示符 截断指示符 ) | ( 截断指示符 缩进指示符 )`
+ * 缩进指示符是 `[1-9]`，截断指示符是 `[+-]`。所以 `|2-` 与 `|-2` 都算。
+ */
+const YAML_BLOCK_INDICATOR = String.raw `[|>](?:\d[+-]?|[+-]\d?)?`;
+/**
+ * 一条**块标量头部**行：映射值（`key: <属性> <指示符>`）或序列项（`- <属性> <指示符>`）。
+ *
+ * 为什么必须认全（2026-09-30 审查 F6）：判据此前是 `key:\s*[|>][+-]?\d*`，它只认裸 `script: |`
+ * 这一种。于是 `script: !!js |`（CHANGELOG 与注释**点名**要覆盖的那个形态）、`script: &a |`、
+ * `script: |2-` 全都落进"不在块标量里"，`joinLines` 照旧把它们内部的 3+ 连续空行折成 1 行 ——
+ * 补丁照旧能读、表达式照旧能 eval，**只是算出来的值变了**。方向恰好是改写用户手写的内容。
+ */
+const BLOCK_SCALAR_HEADER_RE = new RegExp(`^(\\s*)(?:${YAML_KEY_PART}\\s*:|-(?=\\s|$))\\s*${YAML_NODE_PROPS}${YAML_BLOCK_INDICATOR}\\s*(?:#.*)?$`);
+/**
+ * 「像块标量头部、但上面那条严格判据认不出来」的行。
+ *
+ * 认不出的形状一律**整体不折叠**（函数头注释里的第二道闸）：折叠的代价是"少一次排版归一化"
+ * （文件里可能积空行，肉眼可见、可再折叠），而误判的代价是**静默改写用户手写的表达式** ——
+ * 两者不对称，所以认不出时选保守的那一边。
+ *
+ * 为什么不会误伤本插件自己生成的行：`buildInsertBlock` 的标量值一律走 `JSON.stringify`
+ * （行尾必是 `"`），数字与布尔没有 `|` / `>`。所以只有**人手写**的形状才可能命中这条。
+ */
+const SUSPICIOUS_BLOCK_HEADER_RE = new RegExp(`^\\s*(?:${YAML_KEY_PART}\\s*:|-(?=\\s|$)).*[|>]\\s*(?:#.*)?$`);
+/**
+ * 标出「哪些行在**块标量**（`key: |` / `key: >`）里」。
+ *
+ * 为什么折叠空行前必须知道这件事（2026-09-30 审查 P2-7）：`joinLines` 每次行级编辑
+ * （任何一次 MCP 增 / 改 / 删 / 启停）都会把整份文件里 3+ 连续换行折成 1 个空行 —— 那是为了
+ * 不让反复增删在文件里积出越来越长的空行。但块标量的**内容就是换行与缩进**，它内部的空行
+ * 属于内容本身：折掉一次等于改写了用户手写的表达式（`!!js |`），而补丁照旧能读、表达式
+ * 照旧能 eval —— 只是算出来的值变了，**静默**改掉一个用户写的东西。
+ *
+ * 两道闸：
+ *   ① 严格判据（`BLOCK_SCALAR_HEADER_RE`）按 YAML 规范认头：属性（tag / anchor）+ 指示符，
+ *      两种指示符顺序都算；块体是之后所有**空行**或**缩进深于头行**的行，遇到第一个非空且
+ *      缩进不深于头行的行即结束。
+ *   ② 文件里只要出现**一条**认不出的疑似块标量头（`SUSPICIOUS_BLOCK_HEADER_RE`），
+ *      整份文件都不折叠 —— 宁可少一次排版归一化，也不猜着改写内容。
+ */
+function blockScalarLineMask(lines) {
+    const inScalar = new Array(lines.length).fill(false);
+    let i = 0;
+    while (i < lines.length) {
+        const m = BLOCK_SCALAR_HEADER_RE.exec(lines[i]);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const keyIndent = m[1].length;
+        let j = i + 1;
+        while (j < lines.length) {
+            const line = lines[j];
+            if (line.trim() === '') {
+                inScalar[j] = true;
+                j++;
+                continue;
+            }
+            const indent = line.match(/^\s*/)[0].length;
+            if (indent <= keyIndent)
+                break;
+            inScalar[j] = true;
+            j++;
+        }
+        i = Math.max(j, i + 1);
+    }
+    // 第二道闸：认不出的疑似块标量头 → 整体不折叠（全部标成"受保护"）。
+    for (const line of lines) {
+        if (SUSPICIOUS_BLOCK_HEADER_RE.test(line) && !BLOCK_SCALAR_HEADER_RE.test(line)) {
+            return new Array(lines.length).fill(true);
+        }
+    }
+    return inScalar;
+}
 function joinLines(lines) {
-    let res = lines.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '').replace(/\n*$/, '\n');
+    // 折叠**跳过块标量内部的行**：那些空行是内容，不是排版（见 blockScalarLineMask 的注释）。
+    const protectedLine = blockScalarLineMask(lines);
+    const folded = [];
+    let blanks = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (protectedLine[i]) {
+            blanks = 0;
+            folded.push(lines[i]);
+            continue;
+        }
+        if (lines[i].trim() === '') {
+            blanks++;
+            // 最多留 1 个空行 —— 与改动前 `/\n{3,}/ → /\n\n/` 的力度一致。
+            if (blanks <= 1)
+                folded.push(lines[i]);
+            continue;
+        }
+        blanks = 0;
+        folded.push(lines[i]);
+    }
+    // 尾部若正处在块标量里，就不做「补一个换行」的归一化（那也会动到内容）；只去首部空行。
+    const tailProtected = lines.length > 0 && protectedLine[lines.length - 1];
+    let res = folded.join('\n').replace(/^\n+/, '');
+    res = tailProtected ? res : res.replace(/\n*$/, '\n');
     if (!res.trim()) {
         res = '[]\n';
     }
@@ -318,6 +478,13 @@ function bareOverrideRanges(lines, id) {
         let end = i + 1;
         while (end < n && !/^- /.test(lines[end]))
             end++;
+        // 只删**纯块**（2026-09-30 审查 P2-6）：`mcpm-edit` / `mcpm-remove` 原来把同 id 的顶层
+        // 覆盖块**一律**删掉，而用户完全可能在里面手写 `config`（补丁是按 **loader id** 生效的，
+        // 别的模块名写同一个 id 时改的仍是那个条目，手写 config 因此是合法且有用的）。删掉它
+        // 就是静默丢掉用户手写的配置。判据与 `override-blocks.ts` 的 `readToggleEntry().pure`
+        // **同源**（认不出的写法一律判非纯 → 保留，保守方向是对的）。
+        if (!readToggleEntry(lines.slice(i, end)).pure)
+            continue;
         ranges.push([i, end]);
     }
     return ranges;

package/lib/mcp/secret-guard.js

@@ -7,11 +7,17 @@
 // （本机 `TAVILY_API_KEY` 就是这样变成 `••••••` 的）。
 //
 // URL 是**第二种形态**，别把它漏掉（2026-09-19 审计 T-23）：`maskUrlQuery` 不产出 `••••••`，
-// 而是把整个查询串换成 `<redacted>`（经 URL 序列化后是 `?<redacted>` 的百分号编码）。
+// 而是把承载凭据的那几段换成 `<redacted>` 哨兵（经 URL 序列化后是 `%3Credacted%3E`）。
 // 打码值判据只认整串 `•` 时它永远命中不了，于是 `mcpmEdit` 会把 `?<redacted>` 当成真 URL
 // 写回补丁 —— 一次普通「编辑保存」即把 URL 里的凭据**永久**改成占位串。所以本模块同时
 // 提供 `isMaskedUrl` / `resolveMaskedUrl`，与下面的 env / headers 判据并列。
 //
+// 「那几段」= **userinfo / 查询串 / 片段**三处（2026-09-30 审查 F5）：`new URL()` 把 userinfo
+// 与 fragment 存在 `username/password` 与 `hash` 里，`toString()` 原样带出。只换 `search`
+// 的话，`https://user:pass@host/mcp`（Basic-Auth 形态）与 `https://host/mcp#access_token=…`
+// 会整条原样返回 —— 而这两条路正是免令牌出口（`mcpm-list` / `mcpm-inspect` / 模型工具 /
+// 快照导出）。路径与主机**不动**：它们是该服务的身份，算进来会把真 URL 误判成打码值。
+//
 // 判据为什么可以这么硬：打码值只可能表示"用户没改这一项"，绝不可能表示"用户想把它设成这个"。
 // 所以三道闸的方向都是「往旧值收」：
 //   ① 有旧真值   → 用旧真值顶替（用户意图 = 不改这一项）；
@@ -45,14 +51,57 @@ export function maskedKeysIn(map) {
         return [];
     return Object.keys(map).filter((key) => isMaskedValue(map[key]));
 }
-/** `maskUrlQuery` 写进查询串的哨兵（去掉 `?` 之后那一段）。 */
+/**
+ * 单个值的打码形态（env / headers 那一类键值对）。
+ *
+ * 为什么提到本模块（2026-09-30，审查 P0-4）：这个函数原先私有在 `mcp/manager.ts`，而整机迁移
+ * 的导出侧（`ops/snapshot.ts`）自己另写了一份「所有键一律打成 `••••••`」的版本 —— 同一件事
+ * 两套口径，于是 `$VAR` / `!!js` 这类**间接引用**在两条出口上的命运不同。本模块是两条打码
+ * 形态（占位符 / URL）的唯一口径，键值对这条也归这里。
+ *
+ * `$VAR` 与 `!!js` 是**间接引用**而不是密钥，原样保留：把它们打成 `••••••` 再导回来，目标机
+ * 既顶替不出真值（它没有这一项）、也没有原值可回退，`resolveMaskedKv` 只能把这个键丢掉 ——
+ * 一次普通迁移就毁掉了配置里的间接引用。
+ */
+export function maskSecretValue(value) {
+    const text = String(value == null ? '' : value);
+    if (text === '')
+        return '';
+    if (text.startsWith('$'))
+        return text;
+    if (/^!!js\s/.test(text))
+        return text;
+    return MASK_PLACEHOLDER;
+}
+/** `maskUrlQuery` 写进 URL 各段的哨兵（userinfo / 查询串 / 片段共用同一个字面值）。 */
 const URL_REDACTED_QUERY = '<redacted>';
 /**
- * 一个 URL 的查询串是不是被 `maskUrlQuery` 打过码。
+ * 一段（userinfo / 查询串 / 片段）是不是哨兵。
  *
- * 只判**查询串**：路径与主机是该服务的身份，打码不会碰它们，把它们算进来会把真 URL 误判成
- * 打码值（判错的方向是丢掉真配置）。经 `new URL()` 一过，`<` `>` 会被百分号编码，
- * 所以比较前先解码 —— 手写补丁里直接写了 `?<redacted>` 也能认出来。
+ * `<` `>` 会被 URL 序列化百分号编码（`%3Credacted%3E`），所以比较前先解码 ——
+ * 手写补丁里直接写 `<redacted>` 也要认出来。`decodeURIComponent` 对残缺的 `%` 会抛，
+ * 那种输入不是哨兵。
+ */
+function isRedactedPart(part) {
+    if (part === URL_REDACTED_QUERY)
+        return true;
+    try {
+        return decodeURIComponent(part) === URL_REDACTED_QUERY;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 一个 URL 的**任一凭据段**是不是被 `maskUrlQuery` 打过码。
+ *
+ * 判据只覆盖 userinfo / 查询串 / 片段这三处：路径与主机是该服务的身份，打码不会碰它们，
+ * 把它们算进来会把真 URL 误判成打码值（判错的方向是丢掉真配置）。
+ *
+ * 为什么三处各自独立判、命中一处即算（2026-09-30 审查 F5）：`resolveMaskedUrl` 的语义是
+ * "这条 URL 是打码形态 ⇒ 不能写回盘"。只判查询串的话，`https://user:pass@host/mcp`
+ * （userinfo 承载 Basic 凭据，MCP 托管服务真实存在的形态）与 `...#access_token=…`
+ * 都会被判成真值原样落盘 —— 一次普通「编辑保存」即把凭据永久换成占位串。
  */
 export function isMaskedUrl(value) {
     const text = String(value == null ? '' : value).trim();
@@ -60,22 +109,68 @@ export function isMaskedUrl(value) {
         return false;
     try {
         const parsed = new URL(text);
-        if (!parsed.search)
-            return false;
-        const query = parsed.search.replace(/^\?/, '');
-        return query === URL_REDACTED_QUERY || decodeURIComponent(query) === URL_REDACTED_QUERY;
+        if (isRedactedPart(parsed.username) || isRedactedPart(parsed.password))
+            return true;
+        if (parsed.search && isRedactedPart(parsed.search.replace(/^\?/, '')))
+            return true;
+        if (parsed.hash && isRedactedPart(parsed.hash.replace(/^#/, '')))
+            return true;
+        return false;
     }
     catch {
+        // 非绝对 URL（`new URL` 抛错）走字符串判据，与下面 `maskUrlQuery` 的兜底分支配对 ——
+        // 少了这一半，兜底打码出来的相对 URL 在回写时认不出是打码值，会被当成用户新填的地址写回补丁。
+        const userinfo = /^(?:[a-zA-Z][\w+.-]*:)?\/\/([^/?#]*)@/.exec(text);
+        if (userinfo && isRedactedPart(userinfo[1]))
+            return true;
+        const at = text.indexOf('?');
+        if (at >= 0) {
+            const hashAt = text.indexOf('#', at);
+            if (isRedactedPart(text.slice(at + 1, hashAt < 0 ? undefined : hashAt)))
+                return true;
+        }
+        const hashAt = text.indexOf('#');
+        if (hashAt >= 0 && isRedactedPart(text.slice(hashAt + 1)))
+            return true;
         return false;
     }
 }
 /**
- * 把 URL 的查询串换成 `<redacted>` 哨兵 —— 打码的**产出**侧，与上面的 `isMaskedUrl` 配对。
+ * 字符串级兜底打码（`new URL` 认不下的相对地址 / 协议相对地址）：
+ * 按 `[scheme:][//userinfo@host]/path[?query][#fragment]` 的形状，把 userinfo / 查询串 /
+ * 片段三处各换成哨兵，路径与主机原样保留（它们是该服务的身份）。
+ */
+function maskUrlPartsByString(url) {
+    // ① userinfo：`scheme://` 或 `//` 之后、第一个 `/ ? #` 之前若有 `@`，把 `@` 之前那段换掉。
+    //    正则里的 `[^/?#]*` 越不过路径分隔符，所以路径里的 `@`（`/user@example.com`）不会误伤。
+    let out = url.replace(/^((?:[a-zA-Z][\w+.-]*:)?\/\/)([^/?#]*@)/, `$1${URL_REDACTED_QUERY}@`);
+    // ② 查询串：第一个 `?` 到 `#` 之前整段换哨兵。
+    const at = out.indexOf('?');
+    if (at >= 0) {
+        const hashAt = out.indexOf('#', at);
+        out = out.slice(0, at + 1) + URL_REDACTED_QUERY + (hashAt < 0 ? '' : out.slice(hashAt));
+    }
+    // ③ 片段：第一个 `#` 之后整段换哨兵。
+    const hashAt = out.indexOf('#');
+    if (hashAt >= 0)
+        out = out.slice(0, hashAt + 1) + URL_REDACTED_QUERY;
+    return out;
+}
+/**
+ * 把 URL 里承载凭据的三段（userinfo / 查询串 / 片段）换成 `<redacted>` 哨兵
+ * —— 打码的**产出**侧，与上面的 `isMaskedUrl` 配对。
  *
- * 放在这里而不是 manager.ts 里：本模块是这两条打码形态的唯一口径，而使用方已经有两个
- * ——MCP 列表视图（`mcpmRowsWithNotes`），以及模型调 `mcp_manager_save` 时的确认卡
- * （卡里要回显"新 URL"，但用户批准的是「跑这个地址」，查询串里的凭据不该明文进卡片）。
- * 两处各写一份的话，改了一处就会漂成两种打码形态，而 `isMaskedUrl` 只认其中一种。
+ * 放在这里而不是 manager.ts 里：本模块是这两条打码形态的唯一口径，而使用方已经有三个
+ * ——MCP 列表视图（`mcpmRowsWithNotes`）、模型调 `mcp_manager_save` 时的确认卡
+ * （卡里要回显"新 URL"，但用户批准的是「跑这个地址」，查询串里的凭据不该明文进卡片）、
+ * 以及整机迁移的导出（`ops/snapshot.ts`，那份目录是要拷去 U 盘 / 另一台机器的）。
+ * 各处各写一份的话，改了一处就会漂成几种打码形态，而 `isMaskedUrl` 只认其中一种。
+ *
+ * 为什么是**三段**而不是只有查询串（2026-09-30 审查 F5）：`new URL()` 把 userinfo 与
+ * fragment 存在 `username/password` 与 `hash` 里，`toString()` 会原样带出 ——
+ * 只替换 `search` 的话，`https://user:pass@host/mcp` 与 `https://host/mcp#access_token=…`
+ * 会**整条原样返回**（后者连 `?` 都没有），而这两条路正是免令牌出口
+ * （`mcpm-list` / `mcpm-inspect` / 模型工具 / 快照导出）。Basic-Auth 形态的凭据就此明文可见。
  */
 export function maskUrlQuery(url) {
     if (!url)
@@ -84,10 +179,21 @@ export function maskUrlQuery(url) {
         const parsed = new URL(url);
         if (parsed.search)
             parsed.search = '?' + URL_REDACTED_QUERY;
+        // userinfo 与片段分别置哨兵。`password = ''` 是为了不留下 `user:<redacted>@` 这种半截形态
+        // —— 有 userinfo 时两段一起换，读回去就是一个整体。
+        if (parsed.username || parsed.password) {
+            parsed.username = URL_REDACTED_QUERY;
+            parsed.password = '';
+        }
+        if (parsed.hash)
+            parsed.hash = '#' + URL_REDACTED_QUERY;
         return parsed.toString();
     }
     catch {
-        return url;
+        // 不是绝对 URL（`new URL` 抛错）—— 原来这里是 `return url`，即**完全不打码**。
+        // 但凭据照样可以挂在这种地址上（`/api?token=…`、`//host/mcp?api_key=…`），而这条函数的
+        // 调用方里有「要拷去另一台机器」的导出侧：原样返回等于承诺打码却留明文。
+        return maskUrlPartsByString(url);
     }
 }
 /**