dsh-config-manager 0.1.0

package/lib/security/secret-scanner.js

@@ -0,0 +1,253 @@
+/**
+ * 敏感字段扫描器（规范 §6 / 设计 §7.2 / core `SecretScanner` 契约的强化实现）。
+ *
+ * 定位：`ctx.settings.describe({redactSecrets:true})` 已剥离 DSH 已知秘密（设计 §7.2），
+ * 本扫描器是**第二道防线**，兜底插件自定义字段、MCP headers、patch config、文件类分区文本。
+ *
+ * 判定策略（两级，避免误伤/漏报）：
+ *  - 字段名：规范化（小写、去 `_-. ` 分隔符）后做「精确命中 / 敏感后缀 / 敏感前缀」三级匹配；
+ *    只剥离**字符串叶值**（对象/数组整体递归，不整块剥离——保证 `credentials: [...]` 状态数组存活）。
+ *  - 引用豁免：`apiKeyEnv` 等「只存引用名」字段、以及形如 `DEEPSEEK_API_KEY` 的全大写环境变量名
+ *    （`isEnvVarName`）一律保留——值是名字不是秘密。
+ *  - 值形状启发式（规范 §6「不能只根据固定字段判断」）：字段名未命中但值长得像 secret
+ *    （sk- / JWT / AKIA / GitHub PAT / PEM 私钥 / Bearer）也剥离；高熵 base64 默认关（误伤率高）。
+ *
+ * 实现不变量：返回 sanitized 为**全新对象**（不改原数据）；迭代式显式栈（防爆栈）+ 深度上限；
+ * 命中记录只含路径与字段名，**值永不外泄**。
+ */
+import { JsonDepthError } from "../utils/json.js";
+/** 剥离占位（与 core defaultSecretScanner 语义一致：空串 = 需补录提示） */
+export const REDACTED_PLACEHOLDER = '';
+/**
+ * 敏感字段名单（规范化名：小写、无分隔符）。
+ * 覆盖规范 §6 原始清单 + 设计 §7.2 + core logger 名单，并保持克制以防误伤
+ * （不收录 `key`/`session` 等过宽子串——`sessionIds`/`monkey` 不得中招）。
+ */
+export const DEFAULT_SECRET_FIELD_NAMES = [
+    // 规范 §6 原文
+    'password', 'passwd', 'token', 'accesstoken', 'refreshtoken',
+    'apikey', 'secret', 'credential', 'authorization', 'cookie',
+    'privatekey', 'clientsecret',
+    // 设计 §7.2 / core logger 扩充
+    'pwd', 'passphrase', 'authtoken', 'sessionkey', 'apisecret',
+    'authheader', 'bearer', 'webhooksecret',
+];
+/** 引用字段（值只是「名字」而非秘密）：规范化精确命中即豁免 */
+export const DEFAULT_REFERENCE_FIELDS = [
+    'apikeyenv', 'apikeyname', 'apikeyref',
+    'tokenenv', 'accesstokenenv', 'refreshtokenenv',
+    'clientsecretenv', 'passwordenv', 'secretref', 'credentialref',
+];
+/** 敏感后缀（规范化后以这些结尾 → 命中；`key` 故意不收，避免 monkey/whiskey 误伤） */
+const SENSITIVE_SUFFIXES = ['token', 'secret', 'password', 'passwd', 'credential'];
+/** 敏感前缀（规范化后以这些开头 → 命中；token/secret 等过宽词不收入） */
+const SENSITIVE_PREFIXES = [
+    'apikey', 'accesstoken', 'refreshtoken', 'authtoken',
+    'clientsecret', 'privatekey', 'authorization', 'authheader',
+    'webhooksecret', 'apisecret',
+];
+export const SECRET_VALUE_PATTERNS = [
+    { name: 'openai-style-key', re: /sk-[A-Za-z0-9_-]{8,}/ },
+    { name: 'jwt', re: /eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/ },
+    { name: 'aws-access-key', re: /AKIA[0-9A-Z]{16}/ },
+    { name: 'github-token', re: /gh[pousr]_[A-Za-z0-9]{20,}/ },
+    { name: 'github-pat', re: /github_pat_[A-Za-z0-9_]{20,}/ },
+    { name: 'pem-private-key', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |ENCRYPTED )?PRIVATE KEY-----/ },
+    { name: 'bearer-token', re: /Bearer [A-Za-z0-9._~+/=-]{8,}/ },
+];
+/** 规范化字段名：小写 + 去 `_-. ` 分隔符（用于名单匹配） */
+export function normalizeFieldName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/** 是否为「环境变量名」形态（全大写下划线，如 DEEPSEEK_API_KEY）→ 视为引用名 */
+export function isEnvVarName(value) {
+    return /^[A-Z][A-Z0-9_]{2,}$/.test(value);
+}
+/** 字段名是否命中敏感名单（规范化后精确 / 敏感后缀 / 敏感前缀） */
+export function isSensitiveFieldName(field, extra = []) {
+    const norm = normalizeFieldName(field);
+    if (norm === '')
+        return false;
+    if ([...DEFAULT_SECRET_FIELD_NAMES, ...extra].includes(norm))
+        return true;
+    if (SENSITIVE_SUFFIXES.some((s) => norm.endsWith(s) && norm.length > s.length))
+        return true;
+    return SENSITIVE_PREFIXES.some((p) => norm.startsWith(p));
+}
+/** 是否为引用字段（值只是名字，不剥离） */
+export function isReferenceField(field, extra = []) {
+    const norm = normalizeFieldName(field);
+    return [...DEFAULT_REFERENCE_FIELDS, ...extra].includes(norm);
+}
+/** 值是否命中强模式 secret 形状（返回命中模式名；未命中返回 null） */
+export function matchSecretValuePattern(value) {
+    for (const p of SECRET_VALUE_PATTERNS) {
+        if (p.re.test(value))
+            return p.name;
+    }
+    return null;
+}
+/** 高熵启发式：长 base64/hex 串且 Shannon 熵高（默认关） */
+function isHighEntropySecret(value) {
+    if (!/^[A-Za-z0-9+/=_-]{32,}$/.test(value))
+        return false;
+    if (/^[A-Za-z0-9_-]+$/.test(value) && !/[0-9]/.test(value))
+        return false; // 纯单词串（如文件名）
+    const counts = new Map();
+    for (const ch of value)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let entropy = 0;
+    for (const n of counts.values()) {
+        const p = n / value.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy > 4.2;
+}
+/** 判定单个「字段名 + 字符串值」：strip | keep（含引用豁免与值形状）
+ * 顺序：值形状优先（AKIA 等全大写 secret 形状不能被 env 名豁免误放）→ 引用字段 → env 名 → 字段名。 */
+function judgeFieldValue(field, value, opts) {
+    if (value === '')
+        return false;
+    if (opts.valuePatterns && matchSecretValuePattern(value) !== null)
+        return true;
+    if (isReferenceField(field, opts.extraReferenceFields))
+        return false;
+    if (isEnvVarName(value))
+        return false; // 值是 env 变量名 → 引用
+    if (isSensitiveFieldName(field, opts.extraFieldNames))
+        return true;
+    if (opts.highEntropy && isHighEntropySecret(value))
+        return true;
+    return false;
+}
+/** 递归扫描 + 剥离（纯函数，不改原数据；深度保护；返回清洗后数据与命中清单） */
+export function scanAndRedact(data, opts = {}) {
+    const maxDepth = opts.maxDepth ?? 64;
+    const cfg = {
+        extraFieldNames: opts.extraFieldNames ?? [],
+        extraReferenceFields: opts.extraReferenceFields ?? [],
+        valuePatterns: opts.valuePatterns ?? true,
+        highEntropy: opts.highEntropy ?? false,
+    };
+    const hits = [];
+    if (data === null || typeof data !== 'object')
+        return { sanitized: data, hits };
+    if (data instanceof Uint8Array)
+        return { sanitized: data, hits };
+    const rootOut = Array.isArray(data) ? [] : {};
+    const stack = [{ src: data, dst: rootOut, path: '', depth: 1 }];
+    const visited = new WeakSet();
+    visited.add(data);
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        const { src, dst, path, depth } = frame;
+        if (depth > maxDepth)
+            throw new JsonDepthError(`扫描深度 ${depth} 超过上限 ${maxDepth}`);
+        if (src instanceof Uint8Array)
+            continue;
+        if (Array.isArray(src)) {
+            const outArr = dst;
+            for (let i = 0; i < src.length; i++) {
+                const v = src[i];
+                const childPath = `${path}[${i}]`;
+                if (v !== null && typeof v === 'object' && !(v instanceof Uint8Array)) {
+                    if (visited.has(v))
+                        throw new Error(`检测到循环引用，无法扫描（路径 ${childPath}）`);
+                    visited.add(v);
+                    const childOut = Array.isArray(v) ? [] : {};
+                    outArr.push(childOut);
+                    stack.push({ src: v, dst: childOut, path: childPath, depth: depth + 1 });
+                }
+                else {
+                    outArr.push(v);
+                }
+            }
+            continue;
+        }
+        const outObj = dst;
+        for (const [k, v] of Object.entries(src)) {
+            const childPath = path === '' ? k : `${path}.${k}`;
+            if (typeof v === 'string') {
+                if (judgeFieldValue(k, v, cfg)) {
+                    hits.push({ path: childPath, field: k });
+                    outObj[k] = REDACTED_PLACEHOLDER;
+                }
+                else {
+                    outObj[k] = v;
+                }
+                continue;
+            }
+            if (v !== null && typeof v === 'object' && !(v instanceof Uint8Array)) {
+                if (visited.has(v))
+                    throw new Error(`检测到循环引用，无法扫描（路径 ${childPath}）`);
+                visited.add(v);
+                const childOut = Array.isArray(v) ? [] : {};
+                outObj[k] = childOut;
+                stack.push({ src: v, dst: childOut, path: childPath, depth: depth + 1 });
+            }
+            else {
+                outObj[k] = v;
+            }
+        }
+    }
+    return { sanitized: rootOut, hits };
+}
+/* ---------------- 文本级扫描（scanText，文件类分区内容用） ---------------- */
+const FIELD_VALUE_RE = [
+    // "field": "value"（JSON 形态，保留引号）
+    { re: /"([A-Za-z0-9_.\-]+)"\s*:\s*"([^"]*)"/g, json: true },
+    // field=value
+    { re: /([A-Za-z0-9_.\-]+)\s*=\s*([^\s,;]+)/g, json: false },
+    // field: value
+    { re: /([A-Za-z0-9_.\-]+)\s*:\s*([^\s,;}]+)/g, json: false },
+];
+/** 文本级扫描：逐行找「敏感字段名 = 值」与「值形状」命中（只报告，不修改文本） */
+export function scanText(text, opts = {}) {
+    const hits = [];
+    const extra = opts.extraFieldNames ?? [];
+    const valuePatterns = opts.valuePatterns ?? true;
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const linePath = `line:${i + 1}`;
+        // 字段名形态
+        for (const { re, json } of FIELD_VALUE_RE) {
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(line)) !== null) {
+                const field = m[1];
+                const value = m[2];
+                if (!isSensitiveFieldName(field, extra))
+                    continue;
+                if (json) {
+                    // JSON 形态下引号内值才报告（引用名豁免由调用方结合场景决定，这里保守报告）
+                    hits.push({ path: linePath, field });
+                    continue;
+                }
+                if (isEnvVarName(value))
+                    continue; // 引用名不报告
+                hits.push({ path: linePath, field });
+            }
+        }
+        // 值形状（字段名无关）
+        if (valuePatterns) {
+            const trimmed = line.trim();
+            const name = matchSecretValuePattern(trimmed);
+            if (name !== null)
+                hits.push({ path: linePath, field: `(${name})` });
+        }
+    }
+    return hits;
+}
+/** 强化版 SecretScanner（对齐 core SecretScanner 契约，可注入 Exporter.scanner） */
+export function createSecretScanner(opts = {}) {
+    return {
+        scanAndRedact(data) {
+            return scanAndRedact(data, opts);
+        },
+        scanText(text) {
+            return scanText(text, opts);
+        },
+    };
+}
+//# sourceMappingURL=secret-scanner.js.map

package/lib/security/secret-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-scanner.js","sourceRoot":"","sources":["../../src/security/secret-scanner.ts"],"names":[],"mappings":"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"}

package/lib/security/zip-security.d.ts

@@ -0,0 +1,27 @@
+import { ZipArchive, type ZipSafetyLimits } from '../utils/zip.ts';
+export { isPathSafe } from '../utils/paths.ts';
+/** 可执行文件扩展名黑名单（§19.6：只警告，本插件不执行任何脚本） */
+export declare const EXECUTABLE_EXTENSIONS: Set<string>;
+/** 条目名是否疑似可执行文件（按扩展名） */
+export declare function isExecutableName(name: string): boolean;
+/**
+ * 强化版 ZIP 解析：在 core 全部安全校验（条目名/条目数/压缩体积）之上，
+ * 增加 symlink 拒绝与重复条目名拒绝。返回 core `ZipArchive`（解压校验完全复用）。
+ */
+export declare function parseZipHardened(buf: Uint8Array, limits?: ZipSafetyLimits): ZipArchive;
+/** 工厂：带默认限额的强化解析器（对齐 ImporterOptions.parseZipOverride 签名） */
+export declare function createHardenedZipParser(defaultLimits?: ZipSafetyLimits): (buf: Uint8Array, limits?: ZipSafetyLimits) => ZipArchive;
+export interface SafeExtractResult {
+    /** 已解压条目的 ZIP 相对路径（正斜杠） */
+    files: string[];
+    /** 非阻塞告警（可执行文件条目等） */
+    warnings: string[];
+}
+/**
+ * 安全解压到受控目录（对齐 core safeExtract 语义 + 强化）：
+ *  - 条目名/限额/symlink/重复名检查（parseZipHardened）；
+ *  - 逐条 CRC32/尺寸/预算校验（ZipArchive.readEntry）；
+ *  - 解压后 lstat 复查「全部产物必须是普通文件」（防符号链接/非常规写入）；
+ *  - 任何异常 → 中止并**完整清理** destDir 后抛出（不残留部分落盘）。
+ */
+export declare function safeExtractHardened(zipPath: string, destDir: string, limits?: ZipSafetyLimits): Promise<SafeExtractResult>;

package/lib/security/zip-security.js

@@ -0,0 +1,154 @@
+/**
+ * ZIP 解压安全（规范 §19 / 设计 §9 / core utils/zip.ts 的强化层）。
+ *
+ * 分工（避免与 core 重复）：
+ * - core `utils/zip.ts` 已实现：条目名 isPathSafe、条目数/压缩体积/解压体积/单条/压缩比限额、
+ *   CRC32 与尺寸校验、ZipArchive.readEntry 预算、safeExtract 基础解压。
+ * - 本模块在其上强化 core 未覆盖的攻击面：
+ *   1. **symlink 条目拒绝**：解析中央目录 external attrs 的 Unix mode（S_IFLNK 0xA000）→ 拒绝；
+ *   2. **重复条目名拒绝**：同名条目（含目录/文件互撞）→ 拒绝（防读取歧义攻击）；
+ *   3. **安全解压强化**：解压后逐条 lstat 复查「必须是普通文件」，任何异常 → 中止并**完整清理**目标目录；
+ *   4. **可执行文件告警**：扩展名黑名单 → warnings（本插件从不执行 ZIP 内文件）。
+ *
+ * 与 core 注入点对齐：`parseZipHardened` / `createHardenedZipParser` 满足
+ * `ImporterOptions.parseZipOverride` 签名 `(buf, limits?) => ZipArchive`。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isPathSafe, isSameOrChild } from "../utils/paths.js";
+import { DEFAULT_ZIP_SAFETY_LIMITS, ZipArchive, ZipSafetyError, } from "../utils/zip.js";
+export { isPathSafe } from "../utils/paths.js";
+/* ---------------- 常量 ---------------- */
+const EOCD_SIG = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+const CENTRAL_SIG = 0x02014b50;
+/** Unix 文件类型掩码（external attrs 高 16 位） */
+const S_IFMT = 0xf000;
+/** 符号链接 */
+const S_IFLNK = 0xa000;
+/** 可执行文件扩展名黑名单（§19.6：只警告，本插件不执行任何脚本） */
+export const EXECUTABLE_EXTENSIONS = new Set([
+    '.exe', '.bat', '.cmd', '.sh', '.ps1', '.dll', '.so', '.dylib', '.bin', '.jar',
+]);
+/** 条目名是否疑似可执行文件（按扩展名） */
+export function isExecutableName(name) {
+    const ext = name.slice(name.lastIndexOf('.')).toLowerCase();
+    return EXECUTABLE_EXTENSIONS.has(ext);
+}
+/* ---------------- 强化解析（parseZipOverride 注入点） ---------------- */
+/**
+ * 强化版 ZIP 解析：在 core 全部安全校验（条目名/条目数/压缩体积）之上，
+ * 增加 symlink 拒绝与重复条目名拒绝。返回 core `ZipArchive`（解压校验完全复用）。
+ */
+export function parseZipHardened(buf, limits = {}) {
+    const merged = { ...DEFAULT_ZIP_SAFETY_LIMITS, ...limits };
+    const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+    if (b.length < 22)
+        throw new ZipSafetyError('不是合法的 ZIP 文件（体积过小）');
+    const eocdIdx = b.lastIndexOf(EOCD_SIG);
+    if (eocdIdx < 0 || eocdIdx + 22 > b.length) {
+        throw new ZipSafetyError('不是合法的 ZIP 文件（缺少中央目录结束记录）');
+    }
+    const totalEntries = b.readUInt16LE(eocdIdx + 10);
+    const cdSize = b.readUInt32LE(eocdIdx + 12);
+    const cdOffset = b.readUInt32LE(eocdIdx + 16);
+    if (cdOffset + cdSize > b.length)
+        throw new ZipSafetyError('中央目录越界（ZIP 损坏）');
+    if (totalEntries > merged.maxEntries) {
+        throw new ZipSafetyError(`ZIP 条目数 ${totalEntries} 超过上限 ${merged.maxEntries}`);
+    }
+    const metas = [];
+    const seenNames = new Set();
+    let pos = cdOffset;
+    let compressedTotal = 0;
+    for (let i = 0; i < totalEntries; i++) {
+        if (pos + 46 > cdOffset + cdSize)
+            throw new ZipSafetyError('中央目录条目越界（ZIP 损坏）');
+        if (b.readUInt32LE(pos) !== CENTRAL_SIG)
+            throw new ZipSafetyError('中央目录签名损坏');
+        const method = b.readUInt16LE(pos + 10);
+        const crc = b.readUInt32LE(pos + 16);
+        const compSize = b.readUInt32LE(pos + 20);
+        const uncompSize = b.readUInt32LE(pos + 24);
+        const nameLen = b.readUInt16LE(pos + 28);
+        const extraLen = b.readUInt16LE(pos + 30);
+        const commentLen = b.readUInt16LE(pos + 32);
+        const externalAttrs = b.readUInt32LE(pos + 38);
+        const localOffset = b.readUInt32LE(pos + 42);
+        const name = b.subarray(pos + 46, pos + 46 + nameLen).toString('utf8');
+        // —— 强化检查 ——
+        if (!isPathSafe(name))
+            throw new ZipSafetyError(`ZIP 条目名不安全: ${name}`);
+        if (seenNames.has(name))
+            throw new ZipSafetyError(`ZIP 条目名重复: ${name}`);
+        seenNames.add(name);
+        const mode = (externalAttrs >>> 16) & S_IFMT;
+        if (mode === S_IFLNK) {
+            throw new ZipSafetyError(`ZIP 含符号链接条目，已拒绝: ${name}`);
+        }
+        if (localOffset + 30 > b.length) {
+            throw new ZipSafetyError(`条目 "${name}" 本地文件头越界`);
+        }
+        compressedTotal += compSize;
+        if (compressedTotal > merged.maxCompressedBytes) {
+            throw new ZipSafetyError('ZIP 压缩数据总量超过上限');
+        }
+        metas.push({
+            name,
+            method,
+            compressedSize: compSize,
+            uncompressedSize: uncompSize,
+            crc32: crc,
+            isDirectory: name.endsWith('/'),
+            localOffset,
+        });
+        pos += 46 + nameLen + extraLen + commentLen;
+    }
+    return new ZipArchive(b, metas, merged);
+}
+/** 工厂：带默认限额的强化解析器（对齐 ImporterOptions.parseZipOverride 签名） */
+export function createHardenedZipParser(defaultLimits) {
+    return (buf, limits) => parseZipHardened(buf, { ...defaultLimits, ...limits });
+}
+/**
+ * 安全解压到受控目录（对齐 core safeExtract 语义 + 强化）：
+ *  - 条目名/限额/symlink/重复名检查（parseZipHardened）；
+ *  - 逐条 CRC32/尺寸/预算校验（ZipArchive.readEntry）；
+ *  - 解压后 lstat 复查「全部产物必须是普通文件」（防符号链接/非常规写入）；
+ *  - 任何异常 → 中止并**完整清理** destDir 后抛出（不残留部分落盘）。
+ */
+export async function safeExtractHardened(zipPath, destDir, limits = {}) {
+    const data = await fs.readFile(zipPath);
+    const archive = parseZipHardened(data, limits);
+    const extracted = [];
+    const warnings = [];
+    try {
+        for (const meta of archive.entries()) {
+            if (meta.isDirectory)
+                continue;
+            const target = path.join(destDir, ...meta.name.split('/'));
+            if (!isSameOrChild(target, destDir)) {
+                throw new ZipSafetyError(`解压目标越界: ${meta.name}`);
+            }
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, archive.readEntry(meta.name));
+            extracted.push(meta.name);
+            if (isExecutableName(meta.name)) {
+                warnings.push(`条目 "${meta.name}" 是潜在可执行文件，本插件不会执行它`);
+            }
+        }
+        // 解压后复查：全部产物必须是普通文件（防 symlink 逃逸 / 非常规写入）
+        for (const rel of extracted) {
+            const p = path.join(destDir, ...rel.split('/'));
+            const st = await fs.lstat(p);
+            if (!st.isFile()) {
+                throw new ZipSafetyError(`解压产物不是普通文件: ${rel}`);
+            }
+        }
+        return { files: extracted, warnings };
+    }
+    catch (err) {
+        await fs.rm(destDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+//# sourceMappingURL=zip-security.js.map

package/lib/security/zip-security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip-security.js","sourceRoot":"","sources":["../../src/security/zip-security.ts"],"names":[],"mappings":"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"}

package/lib/ui/conflict-view.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 冲突决策收集（规范 §11，m6-ui）。
+ *
+ * 输入：ImportPlan.items 中的 Conflict 项（目标存在且不同）。
+ * 输出：逐项决策 Keep Current / Use Imported / Review，转为 core ImportDecisions.resolutions。
+ *
+ * 纯逻辑：只收集用户选择，不触碰 core；未决（review/未选）项在预览时如实展示。
+ */
+import type { ImportPlan, ItemResolution, PlanItem } from '../core/types.ts';
+import type { ConflictViewItem } from './types.ts';
+export declare class ConflictCollector {
+    private readonly plan;
+    private readonly decisions;
+    constructor(plan: ImportPlan);
+    /** 需要用户决策的冲突项（kind === 'Conflict'） */
+    get conflicts(): PlanItem[];
+    /** 设置某项决策；未出现在冲突列表中的 id 忽略并返回 false */
+    resolve(itemId: string, resolution: ItemResolution): boolean;
+    /** 单项当前决策（未决策返回 null） */
+    decisionOf(itemId: string): ItemResolution | null;
+    /** 仍未解决（review 或未决策）的冲突项 */
+    unresolved(): PlanItem[];
+    get hasUnresolved(): boolean;
+    /** 转 core 决策表（供 createImportPlan / executeImportPlan 使用） */
+    toResolutions(): Record<string, ItemResolution>;
+    /** 构造视图项列表（React 绑定用）：含当前/导入摘要占位 */
+    viewItems(): ConflictViewItem[];
+}

package/lib/ui/conflict-view.js

@@ -0,0 +1,49 @@
+export class ConflictCollector {
+    plan;
+    decisions = new Map();
+    constructor(plan) {
+        this.plan = plan;
+    }
+    /** 需要用户决策的冲突项（kind === 'Conflict'） */
+    get conflicts() {
+        return this.plan.items.filter((i) => i.kind === 'Conflict');
+    }
+    /** 设置某项决策；未出现在冲突列表中的 id 忽略并返回 false */
+    resolve(itemId, resolution) {
+        if (!this.conflicts.some((i) => i.id === itemId))
+            return false;
+        this.decisions.set(itemId, resolution);
+        return true;
+    }
+    /** 单项当前决策（未决策返回 null） */
+    decisionOf(itemId) {
+        return this.decisions.get(itemId) ?? null;
+    }
+    /** 仍未解决（review 或未决策）的冲突项 */
+    unresolved() {
+        return this.conflicts.filter((i) => {
+            const d = this.decisions.get(i.id);
+            return d === undefined || d === 'review';
+        });
+    }
+    get hasUnresolved() {
+        return this.unresolved().length > 0;
+    }
+    /** 转 core 决策表（供 createImportPlan / executeImportPlan 使用） */
+    toResolutions() {
+        const out = {};
+        for (const [id, res] of this.decisions)
+            out[id] = res;
+        return out;
+    }
+    /** 构造视图项列表（React 绑定用）：含当前/导入摘要占位 */
+    viewItems() {
+        return this.conflicts.map((item) => ({
+            item,
+            currentSummary: item.detail?.split('\n')[0],
+            importedSummary: undefined,
+            resolution: this.decisionOf(item.id),
+        }));
+    }
+}
+//# sourceMappingURL=conflict-view.js.map

package/lib/ui/conflict-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-view.js","sourceRoot":"","sources":["../../src/ui/conflict-view.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,iBAAiB;IACX,IAAI,CAAa;IACjB,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE/D,YAAY,IAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,sCAAsC;IACtC,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IAC9D,CAAC;IAED,uCAAuC;IACvC,OAAO,CAAC,MAAc,EAAE,UAA0B;QAChD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC;QAC/D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,yBAAyB;IACzB,UAAU,CAAC,MAAc;QACvB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;IAC5C,CAAC;IAED,4BAA4B;IAC5B,UAAU;QACR,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACjC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACnC,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,QAAQ,CAAC;QAC3C,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,4DAA4D;IAC5D,aAAa;QACX,MAAM,GAAG,GAAmC,EAAE,CAAC;QAC/C,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS;YAAE,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;QACtD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,oCAAoC;IACpC,SAAS;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACnC,IAAI;YACJ,cAAc,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC3C,eAAe,EAAE,SAAS;YAC1B,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;SACrC,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/lib/ui/errors.d.ts

@@ -0,0 +1,17 @@
+/** 可操作错误（UI 渲染为 Reason / Suggested action 两段） */
+export interface ActionableError {
+    title: string;
+    reason: string;
+    suggestedAction?: string;
+    /** 相关项（如 MCP 服务器名 / 插件包名）；可空 */
+    item?: string;
+    /** 是否可重试（true 显示重试按钮） */
+    retryable: boolean;
+}
+/** 将任意错误转换为可操作错误（消息已脱敏，不泄漏 Secret） */
+export declare function toActionableError(err: unknown, opts?: {
+    item?: string;
+    fallbackTitle?: string;
+}): ActionableError;
+/** 格式化为用户可读的多行文本（Reason / Suggested action） */
+export declare function formatActionableError(e: ActionableError): string;

package/lib/ui/errors.js

@@ -0,0 +1,76 @@
+/**
+ * 可操作错误模型（规范 §23，m6-ui）。
+ *
+ * 绝不只有 "Something went wrong."：
+ *  - 解析错误 → Reason + Suggested action（可操作）；
+ *  - 输出前强制脱敏（redact），Secret 永不进入 UI/日志。
+ */
+import { redact } from "../security/redaction.js";
+const ERROR_RULES = [
+    {
+        match: (m) => /SETTINGS_CONFLICT|revision.*conflict/i.test(m),
+        title: '配置已被并发修改',
+        suggestedAction: '目标 DSH 的该配置在导入期间被其他进程修改，为避免覆盖请重新导出或手动核对后再试。',
+        retryable: true,
+    },
+    {
+        match: (m) => /ImportNotConfirmed|未确认/i.test(m),
+        title: '导入未确认',
+        suggestedAction: '请在预览页确认导入内容后重试。',
+        retryable: true,
+    },
+    {
+        match: (m) => /backup integrity|完整性校验失败|checksum/i.test(m),
+        title: '备份完整性校验失败',
+        suggestedAction: '备份文件可能已损坏或被篡改，请重新导出备份后再试。',
+        retryable: false,
+    },
+    {
+        match: (m) => /schema.*(不支持|超出)|无法导入|Unsupported/i.test(m),
+        title: '备份格式版本不受支持',
+        suggestedAction: '请升级 DSH Config Manager 或使用相同版本的备份文件。',
+        retryable: false,
+    },
+    {
+        match: (m) => /ENOENT|not found|无法读取|不存在/i.test(m),
+        title: '文件或路径不存在',
+        suggestedAction: '请检查文件路径是否正确、文件是否已被移动或删除。',
+        retryable: true,
+    },
+    {
+        match: (m) => /EACCES|permission|权限/i.test(m),
+        title: '权限不足',
+        suggestedAction: '请检查目标目录的读写权限后重试。',
+        retryable: true,
+    },
+    {
+        match: (m) => /install.*(plugin|插件)|needsRestart|重启/i.test(m),
+        title: '插件安装需要重启生效',
+        suggestedAction: '导入已完成，插件将在重启 DSH 后生效；请在 DSH Desktop 中重启服务。',
+        retryable: false,
+    },
+];
+/** 将任意错误转换为可操作错误（消息已脱敏，不泄漏 Secret） */
+export function toActionableError(err, opts) {
+    const raw = err instanceof Error ? err.message : String(err ?? '未知错误');
+    const message = redact(raw);
+    const rule = ERROR_RULES.find((r) => r.match(message));
+    return {
+        title: rule?.title ?? opts?.fallbackTitle ?? '操作失败',
+        reason: message,
+        suggestedAction: rule?.suggestedAction,
+        item: opts?.item !== undefined ? redact(opts.item) : undefined,
+        retryable: rule?.retryable ?? true,
+    };
+}
+/** 格式化为用户可读的多行文本（Reason / Suggested action） */
+export function formatActionableError(e) {
+    const lines = [e.title];
+    lines.push(`Reason: ${e.reason}`);
+    if (e.suggestedAction)
+        lines.push(`Suggested action: ${e.suggestedAction}`);
+    if (e.item)
+        lines.push(`Item: ${e.item}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=errors.js.map

package/lib/ui/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/ui/errors.ts"],"names":[],"mappings":"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"}