dsh-config-manager 0.1.78 → 0.1.80

package/src/core/mcp-connector-store.ts

@@ -0,0 +1,516 @@
+/**
+ * MCP 连接器存储（`storages/mcp_connector.json`）的读写与脱敏（mcp 分区的第二个数据源）。
+ *
+ * 为什么需要它：DSH 的 MCP 有两条完全不同的落地路径 ——
+ *  ① 组合 patch 里的 `dsh-mcp-client` 行（官方 `dsh-mcp-client` 配置面，mcp 分区一直只认它）；
+ *  ② `dsh-mcp-connector` 插件的连接器（用户实际用的是这条，存在 storage domain
+ *     `mcp_connector` 的 `connections` 表里，落盘 = `$DSH_HOME/storages/mcp_connector.json`）。
+ * 只认 ① 的结果是：用户配了 4 个 MCP 服务器，导出选择器里 MCP 分区恒为「0 个 / 26 B」。
+ *
+ * 安全边界（与连接器插件 docs/CONFIG-BACKUP.md 同精神，但按「备份要能还原」调整粒度）：
+ *  - **绝不导出** grants / tool_catalog / snapshots 等其它表（含 OAuth Token、动态客户端密钥）；
+ *  - Bearer Token / API Key 值、名字像凭据的 Header/env 值、命中强 secret 形状的值 → `<REDACTED:REENTER>`；
+ *  - 绝对命令与本地 cwd → `<REDACTED:LOCAL_VALUE>`；
+ *  - URL 只脱掉 userinfo 与「名字/值像凭据」的查询参数，端点本身保留（整条替换会让备份无法还原）；
+ *  - 非敏感值原样保留（`Accept: application/json`、`-y`、包名这类），否则备份回来的连接全都不能用。
+ *
+ * 导入纪律：只要还有占位符，就**不写**这条连接（写进去等于给用户一个起不来的 Server），
+ * 而是产出「需重填凭据」计划项。
+ */
+import { matchSecretValuePattern } from '../security/secret-scanner.ts';
+
+/** 连接器存储文件（$DSH_HOME 相对路径；也是快照/回滚的文件类 ref） */
+export const MCP_CONNECTOR_STORE_REL = 'storages/mcp_connector.json';
+
+/** 需要用户重填的凭据占位符（与连接器插件同名同形，便于用户/文档互认） */
+export const REDACTED_VALUE = '<REDACTED:REENTER>';
+
+/** 本机专属值占位符（绝对命令、cwd、userinfo） */
+export const REDACTED_LOCAL_VALUE = '<REDACTED:LOCAL_VALUE>';
+
+/** 本项目导出的连接器块标识（与连接器插件自己的 dsh-mcp-connector.redacted 区分：我们的还带 key/connectorId） */
+export const MCP_CONNECTOR_EXPORT_FORMAT = 'dsh-config-manager.mcp-connector';
+export const MCP_CONNECTOR_EXPORT_VERSION = 1;
+
+/** storage domain 里的一条连接记录（只保留本模块用到的字段，其余字段原样透传） */
+export interface ConnectorRecord {
+  key: string;
+  connectorId: string;
+  kind: 'oauth' | 'manual' | 'json';
+  name: string;
+  serverKey?: string;
+  serverName: string;
+  transport: 'streamable-http' | 'sse' | 'stdio';
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  allowInsecurePrivateNetwork?: boolean;
+  headers?: Record<string, string>;
+  auth?: {
+    mode: 'oauth' | 'bearer' | 'api-key';
+    bearerToken?: string;
+    apiKeyHeader?: string;
+    apiKeyValue?: string;
+    grantKey?: string;
+  };
+  enabled?: boolean;
+  injectionMode?: 'always' | 'session';
+  createdAt?: number;
+  updatedAt?: number;
+  [key: string]: unknown;
+}
+
+/** 导出的连接（脱敏后；redactedFields 列出被替换的字段，导入侧据此判「需重填」） */
+export interface ConnectorExportEntry {
+  key: string;
+  connectorId: string;
+  kind: 'oauth' | 'manual' | 'json';
+  name: string;
+  serverKey?: string;
+  serverName: string;
+  transport: 'streamable-http' | 'sse' | 'stdio';
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  allowInsecurePrivateNetwork?: boolean;
+  headers?: Record<string, string>;
+  authMode?: 'oauth' | 'bearer' | 'api-key' | 'none';
+  bearerToken?: string;
+  apiKeyHeader?: string;
+  apiKeyValue?: string;
+  injectionMode?: 'always' | 'session';
+  enabled: boolean;
+  redactedFields?: string[];
+}
+
+/** OAuth 连接只导出「引用」：Token 与动态客户端密钥永不进备份，导入侧提示从市场重新授权 */
+export interface ConnectorOauthRef {
+  key: string;
+  connectorId: string;
+  serverKey?: string;
+  name: string;
+  serverName: string;
+  enabled: boolean;
+  injectionMode?: 'always' | 'session';
+  action: 'reconnect-oauth';
+}
+
+/** mcp 分区里连接器来源的整块载荷 */
+export interface McpConnectorExport {
+  format: typeof MCP_CONNECTOR_EXPORT_FORMAT;
+  version: typeof MCP_CONNECTOR_EXPORT_VERSION;
+  exportedAt: string;
+  connections: ConnectorExportEntry[];
+  oauthConnections: ConnectorOauthRef[];
+}
+
+/** 名字像凭据的键（Header / env / 查询参数 / CLI flag）——命中即脱敏，不看值形状 */
+const SECRETISH_NAME = /(authorization|auth-token|token|api[-_]?key|apikey|secret|password|passwd|pwd|cookie|credential|private[-_]?key|access[-_]?key|session[-_]?key|bearer|signature|sig)/i;
+
+function isSecretishName(name: string): boolean {
+  return SECRETISH_NAME.test(name);
+}
+
+function isPlaceholder(value: string): boolean {
+  return value === REDACTED_VALUE || value === REDACTED_LOCAL_VALUE;
+}
+
+/** 单个值是否需要脱敏（名字启发 + 强形状命中） */
+function needsRedaction(value: string, name?: string): boolean {
+  if (value === '') return false;
+  if (name !== undefined && isSecretishName(name)) return true;
+  return matchSecretValuePattern(value) !== null;
+}
+
+/** Header / env 一类的键值表：保留键名（用户重填时要知道填哪个），逐个决定值 */
+function redactValueMap(input: Record<string, string> | undefined): { map?: Record<string, string>; redacted: boolean } {
+  if (input === undefined) return { redacted: false };
+  const keys = Object.keys(input).sort();
+  if (keys.length === 0) return { map: {}, redacted: false };
+  let redacted = false;
+  const map: Record<string, string> = {};
+  for (const key of keys) {
+    const raw = input[key];
+    const value = typeof raw === 'string' ? raw : String(raw ?? '');
+    if (needsRedaction(value, key)) {
+      map[key] = REDACTED_VALUE;
+      redacted = true;
+    } else {
+      map[key] = value;
+    }
+  }
+  return { map, redacted };
+}
+
+/** stdio 参数：只脱掉看起来是密钥的参数（含 `--token=xxx` 与「flag 后紧跟值」两种形态），其余保留 */
+export function redactArgs(args: readonly string[] | undefined): { args?: string[]; redacted: boolean } {
+  if (args === undefined) return { redacted: false };
+  let redacted = false;
+  const out: string[] = [];
+  let prevSecretFlag = false;
+  for (const raw of args) {
+    const arg = typeof raw === 'string' ? raw : String(raw ?? '');
+    const eq = arg.indexOf('=');
+    if (arg.startsWith('-') && eq > 0) {
+      const flag = arg.slice(0, eq);
+      const value = arg.slice(eq + 1);
+      if (isSecretishName(flag) || needsRedaction(value)) {
+        out.push(`${flag}=${REDACTED_VALUE}`);
+        redacted = true;
+        prevSecretFlag = false;
+        continue;
+      }
+      prevSecretFlag = isSecretishName(flag);
+      out.push(arg);
+      continue;
+    }
+    if (prevSecretFlag || needsRedaction(arg)) {
+      out.push(REDACTED_VALUE);
+      redacted = true;
+      prevSecretFlag = false;
+      continue;
+    }
+    prevSecretFlag = arg.startsWith('-') && isSecretishName(arg);
+    out.push(arg);
+  }
+  return { args: out, redacted };
+}
+
+/** 命令：裸命令名（npx / uvx / node）保留；带路径的（绝对路径、盘符、相对目录）替换为本机值占位符 */
+export function redactCommand(command: string | undefined): { command?: string; redacted: boolean } {
+  if (command === undefined || command === '') return { redacted: false };
+  if (/^[A-Za-z0-9_.@+-]+$/.test(command)) return { command, redacted: false };
+  return { command: REDACTED_LOCAL_VALUE, redacted: true };
+}
+
+/** URL：userinfo 整条替换；查询参数逐项脱敏（端点本体必须保住，否则备份无法还原） */
+export function redactUrl(url: string | undefined): { url?: string; redacted: boolean } {
+  if (url === undefined || url === '') return { redacted: false };
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { url: REDACTED_VALUE, redacted: true };
+  }
+  if (parsed.username !== '' || parsed.password !== '') return { url: REDACTED_VALUE, redacted: true };
+  let redacted = false;
+  if (parsed.search !== '') {
+    const params = [...parsed.searchParams.entries()];
+    parsed.search = '';
+    for (const [name, value] of params) {
+      if (needsRedaction(value, name)) {
+        parsed.searchParams.append(name, REDACTED_VALUE);
+        redacted = true;
+      } else {
+        parsed.searchParams.append(name, value);
+      }
+    }
+  }
+  if (parsed.hash !== '' && needsRedaction(parsed.hash.replace(/^#/, ''))) {
+    parsed.hash = '';
+    return { url: parsed.toString(), redacted: true };
+  }
+  return { url: redacted ? parsed.toString() : url, redacted };
+}
+
+/** 一条连接记录 → 可携带的脱敏条目（永不返回 Token / 密钥明文） */
+export function exportConnectorRecord(record: ConnectorRecord): ConnectorExportEntry {
+  const redactedFields: string[] = [];
+  const entry: ConnectorExportEntry = {
+    key: record.key,
+    connectorId: record.connectorId,
+    kind: record.kind,
+    name: record.name,
+    serverName: record.serverName,
+    transport: record.transport,
+    enabled: record.enabled !== false,
+  };
+  if (record.serverKey !== undefined) entry.serverKey = record.serverKey;
+  if (record.injectionMode !== undefined) entry.injectionMode = record.injectionMode;
+
+  if (record.transport === 'stdio') {
+    const command = redactCommand(record.command);
+    if (command.command !== undefined) entry.command = command.command;
+    if (command.redacted) redactedFields.push('command');
+    const args = redactArgs(record.args);
+    if (args.args !== undefined) entry.args = args.args;
+    if (args.redacted) redactedFields.push('args');
+    const env = redactValueMap(record.env);
+    if (env.map !== undefined) entry.env = env.map;
+    if (env.redacted) redactedFields.push('env');
+    if (record.cwd !== undefined && record.cwd !== '') {
+      entry.cwd = REDACTED_LOCAL_VALUE;
+      redactedFields.push('cwd');
+    }
+  } else {
+    const url = redactUrl(record.url);
+    if (url.url !== undefined) entry.url = url.url;
+    if (url.redacted) redactedFields.push('url');
+    if (record.allowInsecurePrivateNetwork === true) entry.allowInsecurePrivateNetwork = true;
+    const headers = redactValueMap(record.headers);
+    if (headers.map !== undefined) entry.headers = headers.map;
+    if (headers.redacted) redactedFields.push('headers');
+  }
+
+  const mode = record.auth?.mode;
+  if (mode === 'bearer') {
+    entry.authMode = 'bearer';
+    entry.bearerToken = REDACTED_VALUE;
+    redactedFields.push('bearerToken');
+  } else if (mode === 'api-key') {
+    entry.authMode = 'api-key';
+    entry.apiKeyHeader = record.auth?.apiKeyHeader ?? 'X-Api-Key';
+    entry.apiKeyValue = REDACTED_VALUE;
+    redactedFields.push('apiKeyValue');
+  } else if (mode === 'oauth') {
+    entry.authMode = 'oauth';
+  } else {
+    entry.authMode = 'none';
+  }
+
+  if (redactedFields.length > 0) entry.redactedFields = redactedFields;
+  return entry;
+}
+
+/** 全部连接 → 导出块（OAuth 只留引用；按 key 排序，便于 diff 与稳定哈希） */
+export function exportConnectorBlock(records: readonly ConnectorRecord[], exportedAt = new Date().toISOString()): McpConnectorExport {
+  const sorted = [...records].sort((a, b) => a.key.localeCompare(b.key));
+  return {
+    format: MCP_CONNECTOR_EXPORT_FORMAT,
+    version: MCP_CONNECTOR_EXPORT_VERSION,
+    exportedAt,
+    connections: sorted.filter((r) => r.auth?.mode !== 'oauth').map((r) => exportConnectorRecord(r)),
+    oauthConnections: sorted
+      .filter((r) => r.auth?.mode === 'oauth')
+      .map((r) => ({
+        key: r.key,
+        connectorId: r.connectorId,
+        ...(r.serverKey !== undefined ? { serverKey: r.serverKey } : {}),
+        name: r.name,
+        serverName: r.serverName,
+        enabled: r.enabled !== false,
+        ...(r.injectionMode !== undefined ? { injectionMode: r.injectionMode } : {}),
+        action: 'reconnect-oauth' as const,
+      })),
+  };
+}
+
+/** 列出「还有占位符」的字段路径（导入前判「需重填凭据」） */
+export function unresolvedRedactions(value: unknown, path = '$', output: string[] = []): string[] {
+  if (typeof value === 'string') {
+    if (isPlaceholder(value)) output.push(path);
+    return output;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => unresolvedRedactions(item, `${path}[${index}]`, output));
+    return output;
+  }
+  if (value !== null && typeof value === 'object') {
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      unresolvedRedactions(item, `${path}.${key}`, output);
+    }
+  }
+  return output;
+}
+
+/** 导出条目里「需要用户重填」的字段（占位符路径 + redactedFields 并集，供计划项 detail 用） */
+export function refillFieldsOf(entry: ConnectorExportEntry): string[] {
+  const fields = new Set<string>(entry.redactedFields ?? []);
+  for (const p of unresolvedRedactions(entry)) {
+    const trimmed = p.startsWith('$.') ? p.slice(2) : p;
+    if (trimmed !== '') fields.add(trimmed);
+  }
+  return [...fields].sort();
+}
+
+/** 连接器存储文件的解析结果 */
+export interface ConnectorStoreRead {
+  /** 文件存在且解析成功 */
+  parsed: boolean;
+  /** 文件是否存在（ENOENT → false；其余错误 → true + 解析失败） */
+  exists: boolean;
+  connections: ConnectorRecord[];
+  /** 解析失败原因（读到了但形态不对 → 绝不当作空表覆盖） */
+  error?: string;
+  /** 原始 JSON（保留其它表，写回时只替换 connections） */
+  raw?: Record<string, unknown>;
+}
+
+function asRecordArray(value: unknown): ConnectorRecord[] {
+  if (value === null || typeof value !== 'object') return [];
+  const out: ConnectorRecord[] = [];
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    if (item === null || typeof item !== 'object') continue;
+    const rec = item as Record<string, unknown>;
+    const serverName = typeof rec['serverName'] === 'string' ? rec['serverName'] : '';
+    if (serverName === '') continue;
+    out.push({
+      ...(rec as ConnectorRecord),
+      key: typeof rec['key'] === 'string' && rec['key'] !== '' ? rec['key'] : key,
+      serverName,
+    });
+  }
+  return out;
+}
+
+/** 解析连接器存储文本（绝不对「读到了但解析不了」当空表） */
+export function parseConnectorStore(text: string): ConnectorStoreRead {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return { parsed: false, exists: true, connections: [], error: err instanceof Error ? err.message : String(err) };
+  }
+  if (raw === null || typeof raw !== 'object') {
+    return { parsed: false, exists: true, connections: [], error: 'root is not an object' };
+  }
+  const root = raw as Record<string, unknown>;
+  const tables = root['tables'];
+  if (tables === null || typeof tables !== 'object') {
+    return { parsed: false, exists: true, connections: [], error: 'tables is not an object' };
+  }
+  const connections = asRecordArray((tables as Record<string, unknown>)['connections']);
+  return { parsed: true, exists: true, connections, raw: root };
+}
+
+/** 读连接器存储（ENOENT → 空表 + exists:false；其余错误原样上报） */
+export async function readConnectorStore(
+  fs: { readFile(rel: string): Promise<Uint8Array>; exists(rel: string): Promise<boolean> },
+): Promise<ConnectorStoreRead> {
+  if (!(await fs.exists(MCP_CONNECTOR_STORE_REL))) {
+    // 没装连接器是正常形态：空表但**可写**（导入时要在目标机新建这个文件）
+    return { parsed: true, exists: false, connections: [] };
+  }
+  const bytes = await fs.readFile(MCP_CONNECTOR_STORE_REL);
+  const text = new TextDecoder().decode(bytes);
+  return parseConnectorStore(text);
+}
+
+/** 连接身份：优先 key，其次 (connectorId, serverName) */
+export function connectorIdentity(entry: { key?: string; connectorId?: string; serverName: string }): string {
+  if (typeof entry.key === 'string' && entry.key !== '') return `key:${entry.key}`;
+  return `name:${entry.connectorId ?? ''}/${entry.serverName}`;
+}
+
+/**
+ * 在目标连接里找同一身份的记录：**只认 (connectorId, serverName)**。
+ *
+ * 为什么不先按 key 认：key 是存储主键，但「同 key 不同连接」在手工改过/旧版本里是可能的；
+ * 按 key 命中就当成同一条会**覆盖掉一条无关连接**。身份相同 → 复用既有 key（幂等）；
+ * 身份不同 → 交给 pickConnectorKey 挑一个不冲突的新 key。
+ */
+export function findConnectorRecord(records: readonly ConnectorRecord[], entry: ConnectorExportEntry): ConnectorRecord | undefined {
+  return records.find((r) => r.connectorId === entry.connectorId && r.serverName === entry.serverName);
+}
+
+/**
+ * 比较用形态：**两侧都过一遍脱敏**再去掉易变字段。
+ *
+ * 为什么导出条目也要重新脱敏：条目里可能已被用户重填成真值（明文），而目标机记录里的
+ * 同名字段也是明文——但如果只脱一侧，明文与占位符一比就永远 Conflict（导入一次就再也 Skip 不了）。
+ * 两侧统一过 exportConnectorRecord ⇒ 明文都被换成同一个占位符，同一条连接天然相等。
+ */
+export function comparableConnector(record: ConnectorRecord | ConnectorExportEntry): Record<string, unknown> {
+  const isEntry = (record as ConnectorExportEntry).authMode !== undefined;
+  const asRecord = isEntry
+    ? buildConnectorRecord(record as ConnectorExportEntry, { key: (record as ConnectorExportEntry).key, now: 0 })
+    : (record as ConnectorRecord);
+  const { key: _key, redactedFields: _rf, ...rest } = exportConnectorRecord(asRecord);
+  return rest as Record<string, unknown>;
+}
+
+/** 把脱敏条目还原成可写入 storage domain 的记录（占位符必须为空才不会破坏目标机） */
+export function buildConnectorRecord(
+  entry: ConnectorExportEntry,
+  options: { existing?: ConnectorRecord; key: string; now: number },
+): ConnectorRecord {
+  const { existing, key, now } = options;
+  const record: ConnectorRecord = {
+    ...(existing ?? {}),
+    key,
+    connectorId: entry.connectorId,
+    kind: entry.kind,
+    name: entry.name,
+    serverName: entry.serverName,
+    transport: entry.transport,
+    enabled: entry.enabled !== false,
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+  };
+  if (entry.serverKey !== undefined) record.serverKey = entry.serverKey;
+  if (entry.injectionMode !== undefined) record.injectionMode = entry.injectionMode;
+
+  if (entry.transport === 'stdio') {
+    if (entry.command !== undefined) record.command = entry.command;
+    if (entry.args !== undefined) record.args = [...entry.args];
+    if (entry.env !== undefined) record.env = { ...entry.env };
+    if (entry.cwd !== undefined) record.cwd = entry.cwd;
+    delete record.url;
+    delete record.headers;
+  } else {
+    if (entry.url !== undefined) record.url = entry.url;
+    if (entry.headers !== undefined) record.headers = { ...entry.headers };
+    if (entry.allowInsecurePrivateNetwork === true) record.allowInsecurePrivateNetwork = true;
+    else delete record.allowInsecurePrivateNetwork;
+    delete record.command;
+    delete record.args;
+    delete record.env;
+    delete record.cwd;
+  }
+
+  if (entry.authMode === 'bearer') {
+    record.auth = { mode: 'bearer', ...(entry.bearerToken !== undefined ? { bearerToken: entry.bearerToken } : {}) };
+  } else if (entry.authMode === 'api-key') {
+    record.auth = {
+      mode: 'api-key',
+      apiKeyHeader: entry.apiKeyHeader ?? 'X-Api-Key',
+      ...(entry.apiKeyValue !== undefined ? { apiKeyValue: entry.apiKeyValue } : {}),
+    };
+  } else if (entry.authMode === 'oauth') {
+    record.auth = { ...(existing?.auth ?? { mode: 'oauth' }) };
+  } else if (existing?.auth !== undefined) {
+    record.auth = { ...existing.auth };
+  }
+  return record;
+}
+
+/** 目标机里生成一个不与既有记录冲突的 key（同身份 → 复用既有 key） */
+export function pickConnectorKey(records: readonly ConnectorRecord[], entry: ConnectorExportEntry): string {
+  const existing = findConnectorRecord(records, entry);
+  if (existing !== undefined) return existing.key;
+  // key 被一条**无关**连接占着 → 加后缀，绝不覆盖别人的连接
+  if (!records.some((r) => r.key === entry.key)) return entry.key;
+  let suffix = 2;
+  while (records.some((r) => r.key === `${entry.key}-${suffix}`)) suffix += 1;
+  return `${entry.key}-${suffix}`;
+}
+
+/**
+ * 把一条（已脱敏、无占位符的）连接合并进存储 JSON 文本，返回新文本。
+ *
+ * 只替换 `tables.connections[`key`]`，其它表与未知字段逐字保留（grants/tool_catalog 等绝不重写）。
+ */
+export function mergeConnectorIntoStoreText(
+  read: ConnectorStoreRead,
+  record: ConnectorRecord,
+): string {
+  const root: Record<string, unknown> = read.raw !== undefined ? { ...read.raw } : {};
+  if (root['unit'] === undefined || root['unit'] === null || typeof root['unit'] !== 'object') {
+    root['unit'] = { name: 'mcp_connector', version: 1 };
+  }
+  if (!('global' in root)) root['global'] = null;
+  const tables: Record<string, unknown> = root['tables'] !== undefined && root['tables'] !== null && typeof root['tables'] === 'object'
+    ? { ...(root['tables'] as Record<string, unknown>) }
+    : {};
+  const connections: Record<string, unknown> = tables['connections'] !== undefined && tables['connections'] !== null && typeof tables['connections'] === 'object'
+    ? { ...(tables['connections'] as Record<string, unknown>) }
+    : {};
+  connections[record.key] = record;
+  tables['connections'] = connections;
+  root['tables'] = tables;
+  return `${JSON.stringify(root, null, 2)}\n`;
+}

package/src/core/messages-core.ts

@@ -111,6 +111,8 @@ export const zh = {
   'core.recovery.needsAttentionNoRetry': 'recovery decision 为 needs-attention，无法 retry',
   'core.recovery.dismissFailed': 'dismiss 失败',
   'core.recovery.lockNotStale': '未判定为 stale，已拒绝回收',
+  'core.recovery.opInFlight': '该操作仍在进行中（state={state}），请等它结束后再处理',
+  'core.recovery.liveHint': '有 {count} 个操作正在正常执行中',
   // ---------- restore ----------
   'core.restore.pathEscaped': '路径越界: {rel}',
   'core.restore.symlinkCriticalFile': 'symlink 化关键文件: {rel}',
@@ -423,6 +425,8 @@ export const en: Record<keyof typeof zh, string> = {
   'core.recovery.needsAttentionNoRetry': 'the recovery decision is needs-attention; cannot retry',
   'core.recovery.dismissFailed': 'dismiss failed',
   'core.recovery.lockNotStale': 'Not determined to be stale; recovery was refused',
+  'core.recovery.opInFlight': 'This operation is still running (state={state}); wait for it to finish',
+  'core.recovery.liveHint': '{count} operation(s) are currently running normally',
   // ---------- restore ----------
   'core.restore.pathEscaped': 'Path escapes the allowed root: {rel}',
   'core.restore.symlinkCriticalFile': 'Critical file is a symlink: {rel}',

package/src/core/messages.ts

@@ -255,6 +255,17 @@ export const zh = {
   'adapter.mcpCreate': '创建 MCP server {serverName}',
   'adapter.mcpSame': 'MCP server {serverName} 已一致',
   'adapter.mcpDiff': 'MCP server {serverName} 与目标不同',
+  'adapter.mcpConnectorReadFailed': '无法读取 MCP 连接器存储（{reason}），本次备份不含连接器配置',
+  'adapter.mcpConnectorTargetUnreadable': '目标机的 MCP 连接器存储无法解析（{reason}），已跳过连接器导入，原文件未改动',
+  'adapter.mcpConnectorNeedsRefill': 'MCP 连接器「{name}」含需重填的凭据，未导入',
+  'adapter.mcpConnectorCreate': '新增 MCP 连接器「{name}」',
+  'adapter.mcpConnectorSame': 'MCP 连接器「{name}」已存在且一致',
+  'adapter.mcpConnectorDiff': 'MCP 连接器「{name}」与目标机不同',
+  'adapter.mcpConnectorDuplicateName': 'server「{serverName}」同时来自 patch 行与连接器，两份都会保留（不合并）',
+  'adapter.mcpConnectorOauth': 'OAuth 连接器「{name}」需在市场中重新授权',
+  'adapter.mcpConnectorMissing': '备份中找不到 MCP 连接器「{name}」',
+  'adapter.mcpConnectorWritten': '已写入 MCP 连接器「{name}」，重启 DSH 后生效',
+  'adapter.mcpConnectorInvalid': 'MCP 连接器条目缺少 key 或 serverName',
   'adapter.pwCreate': '写入 pnpm-workspace.yaml（插件构建白名单/冷静期配置）',
   'adapter.pwUpdate': '更新 pnpm-workspace.yaml（插件构建白名单/冷静期配置）',
   'adapter.pluginInstall': '安装插件 {name}@{version}',
@@ -264,6 +275,9 @@ export const zh = {
   'adapter.pluginBundleMember': '（bundle 成员，经聚合包安装）',
   'adapter.pluginInstallOk': '插件 {name} 已安装{suffix}',
   'adapter.pluginUpdateTriggered': '插件 {name} 已触发更新（npm 最新版）{suffix}',
+  'adapter.pluginInstalledAtVersion': '插件 {name} 已安装到 {version}{suffix}',
+  'adapter.pluginVersionMismatch': '插件 {name} 安装后版本为 {actual}，与备份记录的 {expected} 不一致（该版本可能已从 npm 撤版）；可手动执行：{command}',
+  'adapter.skillBundledSkipped': '技能 {name} 由插件内置提供（bundled），备份里的副本不完整，已跳过；升级对应插件即可获得最新版本',
   'adapter.pluginRestartSuffix': '，重启 dsh 后生效',
   'adapter.pluginHostBundleDeclare': '声明插件层 {name}（由 DSH 自带提供，不安装）',
   'adapter.pluginHostBundleSame': '插件层 {name} 已在目标机声明（由 DSH 自带提供）',
@@ -409,6 +423,15 @@ export const zh = {
   'sync.workdirNotConfigured': '尚未配置 git 仓库地址，无法重建工作副本。',
   'sync.workdirRelinked': '工作副本的 origin 已重指向当前仓库地址（工作树与本地提交未改动）。',
   'sync.workdirRecloned': '工作副本已重新克隆（原有本地提交已丢弃，远端快照已同步回本地副本）。',
+  // issue #104：换仓库/远端历史被重写后「采纳远端历史」（adopt）的可操作文案。
+  // 注意：既有键（含上面的 historyDiverged / workdirModeInvalid）有冻结指纹，只许追加、不许改值。
+  'sync.git.adoptDirty': '工作副本 {dir} 里有未提交的改动：请先提交或撤销这些改动，再采纳远端历史（否则冲突会把你的改动卡住）。',
+  'sync.git.adoptDetached': '工作副本 {dir} 当前不在任何分支上（detached HEAD），无法采纳远端历史。请先切回一个分支（git switch <分支名>）后重试。',
+  'sync.git.adoptNoRemoteBranch': '远端没有名为 {branch} 的分支（远端现有：{heads}），未做任何合并。请先把仓库地址/分支改对，或改用「重新克隆工作副本」。',
+  'sync.git.adoptNotSyncRepo': '远端仓库顶层出现了快照布局以外的内容（{entries}）：它看起来不是本插件的同步仓库，已拒绝合并（不会把别的仓库内容搬进工作副本）。',
+  'sync.git.adoptMergeConflict': '合并远端 {branch} 时发生冲突：已撤销这次合并（merge --abort），工作副本回到操作前的状态。请手工解决冲突后重试，或改用「重新克隆工作副本」。',
+  'sync.workdirModeInvalidFull': '重建工作副本的模式非法: {mode}（只允许 relink（重指向地址）、adopt（采纳远端历史）或 reclone（重新克隆））',
+
   'sync.git.cmdFailed': 'git {args} 失败 (exit {code}): {err}',
   // 推送认证（真机：公开仓库拉取可匿名成功、推送必失败，git 原文只说「Invalid username or token」）
   'sync.git.pushTokenRequired': '推送需要访问令牌：远端是 http(s) 仓库，但本机没有可用的令牌（拉取公开仓库可以匿名完成，推送必须认证）。请在「同步 → 通道配置」里登录 GitHub 或填入访问令牌后重试。',
@@ -715,6 +738,17 @@ export const en: Record<keyof typeof zh, string> = {
   'adapter.mcpCreate': 'Create MCP server {serverName}',
   'adapter.mcpSame': 'MCP server {serverName} is already identical',
   'adapter.mcpDiff': 'MCP server {serverName} differs from the target',
+  'adapter.mcpConnectorReadFailed': 'Could not read the MCP connector store ({reason}); this backup has no connector config',
+  'adapter.mcpConnectorTargetUnreadable': 'The target MCP connector store cannot be parsed ({reason}); connector import skipped and the file left untouched',
+  'adapter.mcpConnectorNeedsRefill': 'MCP connector "{name}" contains credentials that must be re-entered; not imported',
+  'adapter.mcpConnectorCreate': 'Add MCP connector "{name}"',
+  'adapter.mcpConnectorSame': 'MCP connector "{name}" already exists and matches',
+  'adapter.mcpConnectorDiff': 'MCP connector "{name}" differs from the target',
+  'adapter.mcpConnectorDuplicateName': 'Server "{serverName}" comes from both a patch line and a connector; both are kept (never merged)',
+  'adapter.mcpConnectorOauth': 'OAuth connector "{name}" must be re-authorized in the marketplace',
+  'adapter.mcpConnectorMissing': 'MCP connector "{name}" not found in the backup',
+  'adapter.mcpConnectorWritten': 'MCP connector "{name}" written; takes effect after restarting DSH',
+  'adapter.mcpConnectorInvalid': 'MCP connector entry is missing key or serverName',
   'adapter.pwCreate': 'Write pnpm-workspace.yaml (plugin build whitelist / release-age settings)',
   'adapter.pwUpdate': 'Update pnpm-workspace.yaml (plugin build whitelist / release-age settings)',
   'adapter.pluginInstall': 'Install plugin {name}@{version}',
@@ -724,6 +758,9 @@ export const en: Record<keyof typeof zh, string> = {
   'adapter.pluginBundleMember': ' (bundle member, installed via the aggregate package)',
   'adapter.pluginInstallOk': 'Plugin {name} installed{suffix}',
   'adapter.pluginUpdateTriggered': 'Plugin {name} update triggered (npm latest){suffix}',
+  'adapter.pluginInstalledAtVersion': 'Plugin {name} installed at {version}{suffix}',
+  'adapter.pluginVersionMismatch': 'Plugin {name} is at {actual} after install, not the backed-up {expected} (that version may have been unpublished); run manually: {command}',
+  'adapter.skillBundledSkipped': 'Skill {name} is provided by a plugin (bundled); the copy in the backup is incomplete and was skipped; update that plugin to get the latest version',
   'adapter.pluginRestartSuffix': '; takes effect after restarting dsh',
   'adapter.pluginHostBundleDeclare': 'Declare plugin layer {name} (provided by DSH itself; not installed)',
   'adapter.pluginHostBundleSame': 'Plugin layer {name} is already declared on the target (provided by DSH itself)',
@@ -869,6 +906,15 @@ export const en: Record<keyof typeof zh, string> = {
   'sync.workdirNotConfigured': 'No git repository address is configured, so the working copy cannot be rebuilt.',
   'sync.workdirRelinked': 'The working copy origin now points at the configured repository address (working tree and local commits untouched).',
   'sync.workdirRecloned': 'The working copy was cloned again (local commits were discarded; remote snapshots are back in the local copy).',
+  // issue #104: actionable text for adopting remote history (adopt) after a repository swap / rewritten history.
+  // Existing keys (including historyDiverged / workdirModeInvalid above) have frozen fingerprints: append only.
+  'sync.git.adoptDirty': 'The working copy {dir} has uncommitted changes: commit or discard them before adopting the remote history (otherwise a conflict would trap your changes).',
+  'sync.git.adoptDetached': 'The working copy {dir} is not on any branch (detached HEAD), so the remote history cannot be adopted. Switch back to a branch (git switch <branch>) and retry.',
+  'sync.git.adoptNoRemoteBranch': 'The remote has no branch named {branch} (remote branches: {heads}); nothing was merged. Fix the repository address/branch first, or use "clone the working copy again".',
+  'sync.git.adoptNotSyncRepo': 'The remote repository root contains entries outside the snapshot layout ({entries}): it does not look like this plugin\'s sync repository, so the merge was refused (another repository\'s content is never pulled into the working copy).',
+  'sync.git.adoptMergeConflict': 'Merging remote {branch} produced conflicts: the merge was aborted (merge --abort) and the working copy is back to its previous state. Resolve the conflicts manually and retry, or use "clone the working copy again".',
+  'sync.workdirModeInvalidFull': 'Invalid working-copy rebuild mode: {mode} (only relink (re-point the address), adopt (merge the remote history) or reclone (clone again) are allowed).',
+
   'sync.git.cmdFailed': 'git {args} failed (exit {code}): {err}',
   'sync.git.pushTokenRequired': 'Push requires an access token, but none is available on this machine (public repositories can be fetched anonymously; pushing always needs authentication). Sign in to GitHub or paste an access token under Sync → Channel configuration, then retry.',
   'sync.git.pushAuthFailed': 'Push authentication failed: {err}. Check that the token is valid and has write access to this repository (password authentication is disabled by the remote); a successful pull does not prove the token works — public repositories can be fetched anonymously. Sign in again or replace the token under Sync → Channel configuration.',

package/src/core/phase3-host.ts

@@ -577,6 +577,15 @@ export class Phase3Recovery {
       }
       await this.store.update(opId, (j) => {
         let next = j;
+        // ext step 必须随 op 成功一起结算：此前 :556 写入的 `status:'planned'` 永远不会被更新，
+        // ⇒ 一条 COMMITTED 的 journal 里躺着「计划做、没做过」的步骤。后果有两个：
+        //  ① 审计不可信（recovery 面板把 external step 的 planned 当「未执行的意图」转发给用户）；
+        //  ② issue #87 的 `selfProvableResidual` 用「所有 step 都是 planned 且 appliedAt 为空」来
+        //     证明「副作用从未开始」—— 成功 op 落在 completed/ 不参与判定，但同一形状一旦被别的
+        //     路径读到就会被误读成「残留」。结算成 done + appliedAt 后形状语义唯一。
+        if (next.steps.ext !== undefined) {
+          next = { ...next, steps: { ...next.steps, ext: { ...next.steps.ext, status: 'done', appliedAt: new Date().toISOString() } } };
+        }
         if (next.state === 'SNAPSHOT_CREATED') next = transitionJournalState(next, 'APPLYING');
         if (next.state === 'APPLYING') next = transitionJournalState(next, 'VALIDATING');
         next = transitionJournalState(next, 'COMMITTED');
@@ -596,7 +605,15 @@ export class Phase3Recovery {
       } else {
         const j = await this.store.loadActive(opId);
         if (j !== null && !isTerminalState(j.state)) {
-          await this.store.update(opId, (cur) => transitionJournalState(cur, 'NEEDS_ATTENTION')).catch(() => undefined);
+          await this.store.update(opId, (cur) => {
+            // 失败时 ext step 不能停在 planned：planned 的含义是「还没开始」，而外部操作已经
+            // 尝试过了（可能半途炸掉）。落成 attention 让 journal 自己说明「外部步骤结论未知」，
+            // 而不是留给读取方去猜。appliedAt 保持 null（没有可证明的完成时刻）。
+            const withStep = cur.steps.ext !== undefined && cur.steps.ext.status === 'planned'
+              ? { ...cur, steps: { ...cur.steps, ext: { ...cur.steps.ext, status: 'attention' as const } } }
+              : cur;
+            return transitionJournalState(withStep, 'NEEDS_ATTENTION');
+          }).catch(() => undefined);
         }
       }
       throw err;