dsh-plugin-tool-management 0.9.1 → 0.11.0

package/lib/mcp/override-blocks.js

@@ -46,9 +46,9 @@ export function scanBlockRanges(lines) {
 /**
  * 读一个覆盖块三件事：id、disabled、是不是"纯块"。
  *
- * 只看**顶层/一层缩进**的锚定写法（`- id:`、`name:`、`disabled:`）：生成器写出来的
- * 就是这几行，而 config 里的同名键缩进更深 —— 万一手工把 `disabled` 藏进 config，
- * 这里会判成"非纯块"（保留不删），保守方向是对的。
+ * 只认**精确列位**的写法（顶层 `- id:`，生成器的 2 空格 `name:` / `disabled:`）：
+ * config 里的同名键缩进更深，正则不匹配，于是落入下面的 `pure = false` ——
+ * 手工把 `disabled` 藏进 config 的块会被判成"非纯块"（保留不删），保守方向是对的。
  *
  * 不筛 `name:` —— 补丁是按 **loader id** 生效的，别的模块名写同一个 id 时改的仍是
  * 那个条目；真正决定"能不能删"的是 pure 与 decider 两条规则，不是名字。
@@ -66,9 +66,9 @@ export function readToggleEntry(lines) {
             id = head[1];
             continue;
         }
-        if (/^\s{2,}name:\s*\S+\s*$/.test(line))
+        if (/^ {2}name:\s*\S+\s*$/.test(line))
             continue;
-        const flag = line.match(/^\s{2,}disabled:\s*(true|false)\s*$/);
+        const flag = line.match(/^ {2}disabled:\s*(true|false)\s*$/);
         if (flag) {
             disabled = flag[1] === 'true';
             continue;
@@ -101,8 +101,17 @@ export function scanOverrideBlocks(content) {
 /**
  * **insert 行自带的** 启停基准（`- insert:` 里每个子条目的 `disabled`，缺失 = 启用）。
  *
+ * 子条目键只认 6 空格列位（生成器 `    - id:` 之下的 `      disabled:`）—— config 内嵌的
+ * 同名键缩进更深，匹配不上，该 id 就按"基准未知"处理（调用方只删被 decider 盖住的块，
+ * 绝不删 decider），少删不会错删。
+ *
  * 这是收敛判定的唯一合法基准来源：绝不能用 `parseRows()` 那种"合并覆盖块之后的生效值"，
  * 因为生效值就等于最后一条覆盖块的值，"覆盖块的值 == 基准"会恒成立，decider 会被全删。
+ *
+ * 「无 `disabled` 键」与「有键但值读不出来」是**两件事**（本仓自己的 loader 行就写着
+ * `disabled: !!js "..."`，那个值是启动期算出来的）：前者 = 基准未知（不删 decider），
+ * 后者同样 = 基准未知。把它们都记成 `false` 会让"基准已知"成立，于是 decider 被当 no-op
+ * 删掉 —— 在 `!!js` 那条上就是**按启动期的值做了一次启停翻转判断**（审计 C-15）。
  */
 export function insertBaseRows(content) {
     const lines = content.split(/\r?\n/);
@@ -124,7 +133,7 @@ export function insertBaseRows(content) {
             }
             if (!id)
                 continue;
-            const flag = line.match(/^\s+disabled:\s*(true|false)\s*$/);
+            const flag = line.match(/^ {6}disabled:\s*(true|false)\s*$/);
             if (flag)
                 disabled = flag[1] === 'true';
         }
@@ -163,12 +172,14 @@ export function planOverrideCompaction(content, otherFileContents = []) {
             byId.set(block.id, [block]);
     }
     const baseOf = new Map();
+    // 只有**读得出 true/false** 才算基准已知；`disabled` 缺失或值不可解析（`!!js`）一律不记。
     for (const row of insertBaseRows(content))
-        baseOf.set(row.id, row.disabled === true);
+        if (row.disabled !== undefined)
+            baseOf.set(row.id, row.disabled);
     for (const other of otherFileContents) {
         for (const row of insertBaseRows(other))
-            if (!baseOf.has(row.id))
-                baseOf.set(row.id, row.disabled === true);
+            if (!baseOf.has(row.id) && row.disabled !== undefined)
+                baseOf.set(row.id, row.disabled);
     }
     const ranges = [];
     const ids = {};

package/lib/mcp/patch-yaml.js

@@ -0,0 +1,351 @@
+// cordis.patch.yml 的「受管 loader 行」读写层 —— 2026-09-19 从 index.ts 的 apply 闭包
+// 原样抽出（07 审查五档问题 3：巨型单文件）。这里是所有 MCP 写路径的**唯一** YAML 出口：
+// 生成（buildInsertBlock / buildDisableBlock）、解析（parseRows，供界面读生效值）、
+// 行级块编辑（removeEntryAll / removeMarked / appendBlock / spliceRanges）。
+// 纯字符串运算，不碰 ctx / 文件系统 —— 读写盘由调用方负责。
+import { MCP_CLIENT_MODULE } from '../host-names.js';
+import { maskedKeysIn } from './secret-guard.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); }
+export function buildInsertBlock(row) {
+    const lines = [
+        '# dsh-plugin-tool-management:server:' + row.id,
+        '- insert:',
+        '    - id: ' + yplain(row.id),
+        "      name: '" + MCP_CLIENT_MODULE + "'",
+        '      config:',
+        '        serverName: ' + yq(row.serverName),
+        '        transport: ' + yq(row.transport),
+    ];
+    if (row.transport === 'streamable-http') {
+        lines.push('        url: ' + yq(row.url || ''));
+        const headers = row.headers || {};
+        const hk = Object.keys(headers);
+        if (hk.length) {
+            lines.push('        headers:');
+            for (const k of hk)
+                lines.push('          ' + yq(k) + ': ' + yq(headers[k]));
+        }
+    }
+    else {
+        lines.push('        command: ' + yq(row.command || ''));
+        const args = row.args || [];
+        if (args.length) {
+            lines.push('        args:');
+            for (const a of args)
+                lines.push('          - ' + yq(a));
+        }
+        const env = row.env || {};
+        const ek = Object.keys(env);
+        if (ek.length) {
+            lines.push('        env:');
+            for (const k of ek)
+                lines.push('          ' + yq(k) + ': ' + yq(env[k]));
+        }
+    }
+    if (row.toolCallTimeoutMs)
+        lines.push('        toolCallTimeoutMs: ' + Number(row.toolCallTimeoutMs));
+    // 结构性兜底：这里是所有 MCP 写路径的**唯一** YAML 出口。打码值到这一步还没被拦下，
+    // 说明某个调用点漏过了 ./secret-guard.js —— 那是代码缺陷，宁可整次写入失败，
+    // 也不能把 `••••••` 写进补丁文件（真密钥一旦被覆盖就找不回来了：本机 2026-09-18
+    // `TAVILY_API_KEY` 就是这样丢的）。所以这里**抛错**而不是静默剔除。
+    //
+    // 覆盖范围的边界（别读成"所有字段都查了"）：断言只查 env / headers 的整串 `•` 形态。
+    // URL 的打码是另一套（查询串换成 `<redacted>`），由调用方经 `resolveMaskedUrl` 收敛，
+    // 不在这里 —— 它需要"没有原值就拒绝"这种带上下文的裁决，不是一句断言能表达的。
+    const leaked = [...maskedKeysIn(row.env), ...maskedKeysIn(row.headers)];
+    if (leaked.length) {
+        throw new Error('拒绝写入：' + leaked.join('、') + ' 的值仍是打码占位符（调用方应先经 resolveMaskedKv 收敛）');
+    }
+    return lines.join('\n');
+}
+export function buildDisableBlock(id, disabled) {
+    return [
+        '# dsh-plugin-tool-management:' + (disabled ? 'disable' : 'enable') + ':' + id,
+        '- id: ' + yplain(id),
+        "  name: '" + MCP_CLIENT_MODULE + "'",
+        '  disabled: ' + (disabled ? 'true' : 'false'),
+    ].join('\n');
+}
+// ---------- YAML parsing (mini parser) ----------
+// Known limitation: this hand-rolled parser assumes the exact indentation
+// style that buildInsertBlock emits (config at 6 spaces, children at 8,
+// nested maps/lists at 10+). Hand-edited patch files using different
+// indentation may parse incorrectly — DSH itself only cares about the
+// effective YAML it reads, and this parser exists purely for the UI.
+function splitKV(text) {
+    const m = text.match(/^("(?:\\.|[^"])*"|'[^']*'|[^:]+?)\s*:\s*(.*)$/);
+    if (!m)
+        return null;
+    return { key: unquote(m[1]), value: m[2] };
+}
+function unquote(v) {
+    if (v === undefined || v === null)
+        return v;
+    const s = String(v).trim();
+    if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+        try {
+            return JSON.parse(s);
+        }
+        catch (e) {
+            return s.slice(1, -1);
+        }
+    }
+    if (s.length >= 2 && s.startsWith("'") && s.endsWith("'"))
+        return s.slice(1, -1).replace(/''/g, "'");
+    if (/^\[.*\]$/.test(s))
+        return s.slice(1, -1).split(',').map((x) => unquote(x.trim())).filter((x) => x !== '');
+    if (s === 'true')
+        return true;
+    if (s === 'false')
+        return false;
+    if (/^-?\d+$/.test(s))
+        return Number(s);
+    return s;
+}
+function parseEntry(lines) {
+    const entry = { config: {} };
+    let inConfig = false;
+    let configIndent = 0;
+    let nested = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const indent = line.match(/^\s*/)[0].length;
+        let t = trimmed;
+        if (t.startsWith('- '))
+            t = t.slice(2).trim();
+        const kv = splitKV(t);
+        if (!kv) {
+            if (inConfig && nested && nested.type === 'list')
+                nested.current.push(unquote(t));
+            continue;
+        }
+        if (!inConfig) {
+            if (kv.key === 'config' && kv.value === '') {
+                inConfig = true;
+                configIndent = indent;
+                continue;
+            }
+            if (kv.key === 'id')
+                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';
+            continue;
+        }
+        if (indent <= configIndent) {
+            inConfig = false;
+            nested = null;
+            continue;
+        }
+        if (kv.value === '' && (kv.key === 'headers' || kv.key === 'env')) {
+            nested = { key: kv.key, indent, type: 'map', current: {} };
+            entry.config[kv.key] = nested.current;
+            continue;
+        }
+        if (kv.value === '' && kv.key === 'args') {
+            nested = { key: kv.key, indent, type: 'list', current: [] };
+            entry.config[kv.key] = nested.current;
+            continue;
+        }
+        if (nested && indent > nested.indent) {
+            if (nested.type === 'map')
+                nested.current[kv.key] = unquote(kv.value);
+            else if (nested.type === 'list')
+                nested.current.push(unquote(kv.value));
+            continue;
+        }
+        nested = null;
+        entry.config[kv.key] = unquote(kv.value);
+    }
+    return entry;
+}
+export function parseRows(content) {
+    const lines = content.split(/\r?\n/);
+    const managedIds = new Set();
+    for (const line of lines) {
+        // Markers written by either this plugin or the template upstream count
+        // as managed (coexistence: both can edit the same patch file).
+        const m = line.match(/^# (?:dsh-plugin-tool-management|dsh-mcp-manager):server:(.+)$/);
+        if (m)
+            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];
+        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);
+                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) });
+                }
+            }
+        }
+        else {
+            // 覆盖块按**文件顺序**生效，不是"收集后统一回填"：官方
+            // `@deepseek-ai/dsh-app-boot` 的 applyEntryPatches 只给此刻已入索引的 id 打补丁
+            //（insert 是插入时立即入索引），命中不到就 warn + skip。所以写在 insert 之前的
+            // 覆盖块在宿主侧是 no-op —— 这里同样丢弃，界面才和生效值一致。
+            const entry = parseEntry(block.text.split('\n'));
+            if (entry && entry.name === MCP_CLIENT_MODULE && entry.disabled !== undefined) {
+                const row = rows.find((r) => r.id === entry.id);
+                if (row)
+                    row.disabled = entry.disabled;
+            }
+        }
+    }
+    return { rows };
+}
+// ---------- line-based block editing ----------
+export function splitLines(content) { return content.split(/\r?\n/); }
+function joinLines(lines) {
+    let res = lines.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '').replace(/\n*$/, '\n');
+    if (!res.trim()) {
+        res = '[]\n';
+    }
+    else if (!/^- /m.test(res) && !/^\[\]\s*$/m.test(res)) {
+        // A patch file must stay a top-level YAML array: after removing the last
+        // entry, emit [] so loadOptionalPatches never throws on a comments-only file.
+        res = res.replace(/\n*$/, '\n[]\n');
+    }
+    return res;
+}
+function escRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function markerRanges(lines, id, ops) {
+    const n = lines.length;
+    // Match this plugin's markers AND the template upstream's
+    // (`# dsh-mcp-manager:server|disable|enable:<id>`) so an entry written by
+    // either manager can be located and cleaned up without orphan blocks —
+    // the two plugins are designed to coexist.
+    const re = new RegExp('^# (?:dsh-plugin-tool-management|dsh-mcp-manager):(' + ops + '):' + escRe(id) + '$');
+    const ranges = [];
+    for (let i = 0; i < n; i++) {
+        if (!re.test(lines[i]))
+            continue;
+        let j = i + 1;
+        while (j < n && !/^- /.test(lines[j]))
+            j++;
+        let end = j;
+        if (j < n && /^- /.test(lines[j])) {
+            let k = j + 1;
+            while (k < n && !/^- /.test(lines[k]))
+                k++;
+            end = k;
+        }
+        ranges.push([i, end]);
+    }
+    return ranges;
+}
+/**
+ * 命中 id 的 `- insert:` 区间。
+ *
+ * 一个 `- insert:` 下**可以挂多个子条目**（`parseRows` 就是这么读的：它按 `    - `
+ * 切子条目逐个解析）。此前只要块内有任一子条目命中就返回**整块**，于是
+ * `mcpm-edit` / `mcpm-remove` 会顺手删掉同块兄弟服务器 —— 插件自己写的是"一块一条"，
+ * 出事的都是手工编辑出来的多子条目块，而那正是最需要保住的形状（用户的手写意图）。
+ *
+ * 所以按子条目粒度切：只删命中的那一条，兄弟留下；整块只剩这一条时连 `- insert:`
+ * 一起删，不留一个空壳块（`- insert:` 下没有子条目在 YAML 里是 null，宿主会跳过）。
+ */
+function insertBlockRange(lines, id) {
+    const n = lines.length;
+    const entryRe = new RegExp('^\\s*- id: ' + escRe(id) + '\\s*$');
+    for (let i = 0; i < n; i++) {
+        if (!/^- insert:/.test(lines[i]))
+            continue;
+        let end = i + 1;
+        while (end < n && !/^- /.test(lines[end]))
+            end++;
+        const starts = [];
+        for (let k = i + 1; k < end; k++)
+            if (/^ {4}- /.test(lines[k]))
+                starts.push(k);
+        // 切不出子条目（缩进不是生成器那套的手写块）：退回"整块"，与改动前一致 ——
+        // 认不出形状时宁可照旧删整块，也好过认不出就跳过、让 edit 追加出一条重复条目。
+        if (!starts.length) {
+            if (lines.slice(i, end).some((l) => entryRe.test(l)))
+                return [i, end];
+            continue;
+        }
+        for (let s = 0; s < starts.length; s++) {
+            const from = starts[s];
+            const to = s + 1 < starts.length ? starts[s + 1] : end;
+            if (!lines.slice(from, to).some((l) => entryRe.test(l)))
+                continue;
+            return starts.length === 1 ? [i, end] : [from, to];
+        }
+    }
+    return null;
+}
+function bareOverrideRanges(lines, id) {
+    const n = lines.length;
+    const re = new RegExp('^- id: ' + escRe(id) + '\\s*$');
+    const ranges = [];
+    for (let i = 0; i < n; i++) {
+        if (!re.test(lines[i]))
+            continue;
+        let end = i + 1;
+        while (end < n && !/^- /.test(lines[end]))
+            end++;
+        ranges.push([i, end]);
+    }
+    return ranges;
+}
+export function spliceRanges(lines, ranges) {
+    const remove = new Set();
+    for (const r of ranges)
+        for (let i = r[0]; i < r[1]; i++)
+            remove.add(i);
+    return joinLines(lines.filter((_, i) => !remove.has(i)));
+}
+export function removeEntryAll(content, id) {
+    const lines = splitLines(content);
+    const ranges = markerRanges(lines, id, 'server|disable|enable');
+    const ib = insertBlockRange(lines, id);
+    if (ib)
+        ranges.push(ib);
+    ranges.push(...bareOverrideRanges(lines, id));
+    return spliceRanges(lines, ranges);
+}
+export function removeMarked(content, id, op) {
+    return spliceRanges(splitLines(content), markerRanges(splitLines(content), id, op));
+}
+export function appendBlock(content, block) {
+    let c = content;
+    if (/^\[\]\s*$/m.test(c))
+        c = c.replace(/^\[\]\s*$/m, block + '\n');
+    else
+        c = c.replace(/\s*$/, '\n' + block + '\n');
+    return c;
+}

package/lib/mcp/secret-guard.js

@@ -0,0 +1,145 @@
+// 打码值不得入库 —— env / headers 与 URL 查询串两条形态的唯一口径。
+//
+// 为什么需要它（2026-09-18，本机真实事故）：MCP 列表默认把 env / headers 里的凭据打码成
+// `••••••`，而「编辑」弹窗的密钥框**预填的就是这个打码值** —— 界面拿到的行本身就是打码的
+// （列表视图走 `mcpmRowsWithNotes(false)`）。于是"打开编辑 → 改个别的字段 → 保存"这条
+// 最普通的操作，会把打码值当成真值写回补丁文件，**真密钥永久丢失、且无法找回**
+// （本机 `TAVILY_API_KEY` 就是这样变成 `••••••` 的）。
+//
+// URL 是**第二种形态**，别把它漏掉（2026-09-19 审计 T-23）：`maskUrlQuery` 不产出 `••••••`，
+// 而是把整个查询串换成 `<redacted>`（经 URL 序列化后是 `?<redacted>` 的百分号编码）。
+// 打码值判据只认整串 `•` 时它永远命中不了，于是 `mcpmEdit` 会把 `?<redacted>` 当成真 URL
+// 写回补丁 —— 一次普通「编辑保存」即把 URL 里的凭据**永久**改成占位串。所以本模块同时
+// 提供 `isMaskedUrl` / `resolveMaskedUrl`，与下面的 env / headers 判据并列。
+//
+// 判据为什么可以这么硬：打码值只可能表示"用户没改这一项"，绝不可能表示"用户想把它设成这个"。
+// 所以三道闸的方向都是「往旧值收」：
+//   ① 有旧真值   → 用旧真值顶替（用户意图 = 不改这一项）；
+//   ② 没有旧真值 → **丢弃该键**（宁可少一个键，也不写一个假值进补丁）；
+//   ③ 旧值本身已是打码值 → 额外报 `alreadyBroken`，界面据此提示"原值已丢失，请重新填写"。
+//
+// 为什么是"顶替 + warning"而不是"报错拒绝"：拒绝会让每一次编辑都失败（预填的本来就是打码值），
+// 而用户的意图显然是改别的字段。顶替才是对意图的如实翻译；**报错只留给最后一道结构性兜底**
+// （`buildInsertBlock` 出口的 `maskedKeysIn` 断言）—— 那里一旦命中就说明某个调用点漏过了本模块，
+// 属于代码缺陷，必须吵。
+//
+// 与界面侧的关系：取消打码（点「显示密钥」+ 对的访问令牌）走 `mcpm-reveal`，那条路上
+// 拿到的是**真值**，本模块不参与；本模块只处理"表单里出现打码值"这一种输入。
+/** 打码占位符的字面值。宿主 `maskSecretValue()` 产出的就是它，两处必须同源。 */
+export const MASK_PLACEHOLDER = '••••••';
+/**
+ * 一个值是不是打码占位符。
+ *
+ * 只认「去空白后全是 `•`」：`maskSecretValue` 是**整值替换**（不保留前缀），所以这条规则
+ * 既不需要知道原值长度，也不会把真值误判进来 —— 真密钥恰好整串都是 `•` 的概率不存在。
+ * 这正是"统一为整值替换"而不是"保留前 4 个字符"的理由：后者的判据得写成 `.+?\*{4}$`，
+ * 真值以 `****` 结尾时就会误判成打码值，判错的方向是**丢掉真密钥**。
+ */
+export function isMaskedValue(value) {
+    const text = String(value == null ? '' : value).trim();
+    return text.length > 0 && /^•+$/.test(text);
+}
+/** `map` 里值是打码占位符的键（原序）。空/非对象一律当"没有"。 */
+export function maskedKeysIn(map) {
+    if (!map || typeof map !== 'object')
+        return [];
+    return Object.keys(map).filter((key) => isMaskedValue(map[key]));
+}
+/** `maskUrlQuery` 写进查询串的哨兵（去掉 `?` 之后那一段）。 */
+const URL_REDACTED_QUERY = '<redacted>';
+/**
+ * 一个 URL 的查询串是不是被 `maskUrlQuery` 打过码。
+ *
+ * 只判**查询串**：路径与主机是该服务的身份，打码不会碰它们，把它们算进来会把真 URL 误判成
+ * 打码值（判错的方向是丢掉真配置）。经 `new URL()` 一过，`<` `>` 会被百分号编码，
+ * 所以比较前先解码 —— 手写补丁里直接写了 `?<redacted>` 也能认出来。
+ */
+export function isMaskedUrl(value) {
+    const text = String(value == null ? '' : value).trim();
+    if (!text)
+        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;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 把表单来的 URL 收敛成"可以安全写盘"的一个（与 `resolveMaskedKv` 同方向：往旧值收）。
+ *
+ * 为什么"没有旧值"时不学 env / headers 那样丢弃键：URL 不是可选的键值对 —— 丢掉查询串
+ * 等于写下一个**能连上但鉴权失败**的地址，界面与用户都会以为配置还完好。宁可整次保存失败
+ * 并让用户重填，也不留一个假的可写值。
+ *
+ * @param incoming - 表单里的 URL。
+ * @param current - 该条目**在补丁文件里的旧 URL**；新增条目传 `null`。
+ */
+export function resolveMaskedUrl(incoming, current) {
+    const value = String(incoming == null ? '' : incoming).trim();
+    if (!isMaskedUrl(value))
+        return { value, restored: false, unrecoverable: false };
+    const previous = String(current == null ? '' : current).trim();
+    if (previous && !isMaskedUrl(previous))
+        return { value: previous, restored: true, unrecoverable: false };
+    return { value, restored: false, unrecoverable: true };
+}
+/**
+ * 把表单来的键值对收敛成"可以安全写盘"的一份。
+ *
+ * @param incoming - 表单解析出来的映射（可能整体为空）。
+ * @param current - 该条目**在补丁文件里的旧值**；新增条目传 `null`。
+ * @returns 收敛后的映射 + 三类命中键，供调用方回一条 warning。
+ */
+export function resolveMaskedKv(incoming, current) {
+    const out = {};
+    const restored = [];
+    const dropped = [];
+    const alreadyBroken = [];
+    const incomingMap = incoming && typeof incoming === 'object' ? incoming : {};
+    const currentMap = current && typeof current === 'object' ? current : {};
+    for (const key of Object.keys(incomingMap)) {
+        const value = String(incomingMap[key]);
+        if (!isMaskedValue(value)) {
+            out[key] = value;
+            continue;
+        }
+        const previous = currentMap[key];
+        // 旧值存在且不是打码值 ⇒ 只有一种可能：表单里的是打码值，用户的意图是「不改」。
+        if (previous != null && previous !== '' && !isMaskedValue(previous)) {
+            out[key] = String(previous);
+            restored.push(key);
+            continue;
+        }
+        dropped.push(key);
+        if (previous != null && isMaskedValue(previous))
+            alreadyBroken.push(key);
+    }
+    return { value: out, restored, dropped, alreadyBroken };
+}
+/**
+ * 把命中情况拼成一句给用户看的中文说明；没命中返回 `''`。
+ *
+ * 措辞刻意区分三件事：`alreadyBroken` 是**已经发生的损失**（要重填），`restored` 是
+ * **本次没造成损失**（值保持原样），`dropped` 是**本次丢弃了输入**（表单里凭空出现的打码值）。
+ * 三者混成一句的话，用户无法判断自己要不要动手。
+ */
+export function describeMaskedOutcome(outcome) {
+    const parts = [];
+    if (outcome.alreadyBroken.length) {
+        parts.push('这些密钥在补丁文件里已经是打码占位符，真实值已丢失，请重新填写：' + outcome.alreadyBroken.join('、'));
+    }
+    if (outcome.restored.length) {
+        parts.push('这些密钥未改动，已保留原值：' + outcome.restored.join('、'));
+    }
+    if (outcome.dropped.length > outcome.alreadyBroken.length) {
+        const plain = outcome.dropped.filter((key) => !outcome.alreadyBroken.includes(key));
+        if (plain.length)
+            parts.push('这些键的值是打码占位符且没有原值可保留，已跳过：' + plain.join('、'));
+    }
+    return parts.join('；');
+}