cx-viewer 1.0.3 → 1.0.4

package/src/utils/toolResultBuilder.js

@@ -0,0 +1,312 @@
+/**
+ * Incremental tool result state builder.
+ * Processes assistant tool_use and user tool_result blocks into lookup maps.
+ *
+ * NOTE: The primary wire input is the viewer's Codex projection. Historical
+ * server_tool_use/web_search_tool_result blocks remain a read-only compatibility
+ * path and are rendered directly by ChatMessage.
+ */
+
+import { t } from '../i18n';
+import { buildSingleToolResultCore } from './toolResultCore.js';
+import { isAskToolName, isPlanToolName } from './toolNameAliases.js';
+
+// --- WeakMap cache for tool result state ---
+
+const _toolResultCache = new WeakMap();
+
+// 稳定引用,避免 `req.body?.input || []` 每次构造新 `[]` 字面量打穿 WeakMap 缓存
+// (subAgentEntries 扫描在每次 requests-change 时跑,缓存命中是热路径性能假设)。
+const EMPTY_MESSAGES = Object.freeze([]);
+
+export function getToolResultCache(messages) {
+  return _toolResultCache.get(messages) || null;
+}
+
+export function setToolResultCache(messages, state) {
+  _toolResultCache.set(messages, state);
+}
+
+
+// --- State builder ---
+
+export function createEmptyToolState() {
+  return {
+    toolUseMap: {},
+    toolResultMap: {},
+    readContentMap: {},
+    editSnapshotMap: {},
+    askAnswerMap: {},
+    planApprovalMap: {},
+    latestPlanContent: null,
+    latestPlanFilePath: null,
+    _fileState: {},
+    _editOrder: [],
+  };
+}
+
+/**
+ * i18n 包装:在 toolResultCore 的 buildSingleToolResultCore 基础上附加本地化 label。
+ * 生产路径调用此函数;test 直接调 core 以避开 i18n 依赖。
+ */
+export function buildSingleToolResult(block, matchedTool) {
+  const core = buildSingleToolResultCore(block, matchedTool);
+  let label = t('ui.toolReturn');
+  if (matchedTool) {
+    if (matchedTool.name === 'spawn_agent' && matchedTool.input) {
+      const task = matchedTool.input.task_name || matchedTool.input.name || 'agent';
+      label = `SubAgent: ${task}`;
+    } else if (matchedTool.name === 'Task' && matchedTool.input) {
+      // Read-only compatibility for pre-Codex cx-viewer logs.
+      const st = matchedTool.input.subagent_type || '';
+      const desc = matchedTool.input.description || '';
+      label = `SubAgent: ${st}${desc ? ' — ' + desc : ''}`;
+    } else {
+      label = t('ui.toolReturnNamed', { name: matchedTool.name });
+    }
+  }
+  return { label, ...core };
+}
+
+/**
+ * 全局聚合所有 requests 的 tool_result 块,按 tool_use_id 索引。
+ *
+ * 设计动机:并行 SubAgent / Teammate 的请求在日志中互相穿插,K+1 不一定是同一 agent
+ * 的下一个 turn。两遍扫描建立"id → result"全局索引,渲染时 O(1) 查询,免去运行时配对。
+ *
+ * Pass 1: 全量构建 toolUseMap(供 label / toolName / toolInput 解析)
+ *   - body.input 里 role=assistant 的 tool_use 块
+ *   - response.body.content 里的 tool_use 块(末轮)
+ * Pass 2: 提取所有 tool_result 块写入索引(role=user 消息的 content[])
+ *
+ * Codex call_id is the authoritative correlation key.
+ */
+export function buildGlobalToolResultIndex(requests) {
+  const state = createEmptyGlobalIndexState();
+  appendToGlobalToolResultIndex(state, requests, 0);
+  return state.index;
+}
+
+// 同一 session 内并发持有的 base64 image 上限:更早入索引的 entry 一旦超过此数,
+// 其 images 字段被改成 oversized 占位,释放 base64 字节(单图 2MB × N = 几十 MB
+// 常驻内存的隐患)。32 张覆盖大多数实际会话;若超过,旧图回退为占位,新图保留。
+const MAX_LIVE_IMAGE_ENTRIES = 32;
+
+/**
+ * 增量索引 state:供 ChatView / TeamModal 在 requests 增量到达时复用,避免每次全量扫描。
+ *   index           : { [tool_use_id]: entry } (出参,共享给调用方)
+ *   _useMap         : 已扫到的 tool_use 块 (Pass 1 累积,Pass 2 查 label)
+ *   _imageEntryIds  : FIFO 队列,跟踪持有 base64 image 的 entry id,超 MAX 时驱逐最早
+ */
+export function createEmptyGlobalIndexState() {
+  return { index: {}, _useMap: {}, _imageEntryIds: [] };
+}
+
+// 把超出 LRU 上限的最早 image entry 降级为 oversized 占位,释放 base64 字符串。
+function _enforceImageBudget(state) {
+  const { index, _imageEntryIds } = state;
+  while (_imageEntryIds.length > MAX_LIVE_IMAGE_ENTRIES) {
+    const evictId = _imageEntryIds.shift();
+    const entry = index[evictId];
+    if (!entry || !Array.isArray(entry.images)) continue;
+    entry.images = entry.images.map(img => (
+      img && img.src && !img.oversized
+        ? { oversized: true, mediaType: img.mediaType, sizeBytes: img.src.length }
+        : img
+    ));
+  }
+}
+
+/**
+ * 增量追加:扫描 requests[startIndex..] 并把新发现的 tool_use / tool_result 累积到 state。
+ * 仅写入新出现的 id(`!(id in index)`),原条目幂等,可重复调用同一切片不会引入副作用。
+ */
+export function appendToGlobalToolResultIndex(state, requests, startIndex) {
+  if (!Array.isArray(requests)) return;
+  const { index, _useMap, _imageEntryIds } = state;
+  for (let i = startIndex; i < requests.length; i++) {
+    const r = requests[i];
+    if (!r) continue;
+    const msgs = r.body?.input;
+    if (Array.isArray(msgs)) {
+      for (const m of msgs) {
+        if (m?.role === 'assistant' && Array.isArray(m.content)) {
+          for (const b of m.content) {
+            if (b?.type === 'tool_use' && b.id) _useMap[b.id] = b;
+          }
+        }
+      }
+    }
+    const respContent = r.response?.body?.content;
+    if (Array.isArray(respContent)) {
+      for (const b of respContent) {
+        if (b?.type === 'tool_use' && b.id) _useMap[b.id] = b;
+      }
+    }
+  }
+  for (let i = startIndex; i < requests.length; i++) {
+    const r = requests[i];
+    const msgs = r?.body?.input;
+    if (!Array.isArray(msgs)) continue;
+    for (const m of msgs) {
+      if (m?.role !== 'user' || !Array.isArray(m.content)) continue;
+      for (const b of m.content) {
+        if (b?.type === 'tool_result' && b.tool_use_id && !(b.tool_use_id in index)) {
+          const entry = buildSingleToolResult(b, _useMap[b.tool_use_id]);
+          index[b.tool_use_id] = entry;
+          if (Array.isArray(entry.images) && entry.images.some(img => img && img.src)) {
+            _imageEntryIds.push(b.tool_use_id);
+          }
+        }
+      }
+    }
+  }
+  _enforceImageBudget(state);
+}
+
+/**
+ * SubAgent / Teammate 渲染入口:组合本地 cachedBuildToolResultMap 与全局索引。
+ * globalIndex 由调用方一次性构建(buildGlobalToolResultIndex),所有 entry 共享,
+ * 渲染查询 O(1)。
+ *
+ * 补偿仅覆盖 toolResultMap;readContentMap / editSnapshotMap / latestPlanContent
+ * 等辅助 map 不在补偿范围内 —— SubAgent 卡片只渲染 response.content 块，文件快照
+ * 等高级展开由 mainAgent 路径消费,与 SubAgent 解耦。
+ */
+export function buildSubAgentResultMap(req, globalIndex) {
+  const localState = cachedBuildToolResultMap(req?.body?.input || EMPTY_MESSAGES);
+  const respContent = req?.response?.body?.content;
+  if (!Array.isArray(respContent) || !globalIndex) {
+    return localState.toolResultMap;
+  }
+  // filled lazy-alloc 为 null sentinel:无补偿时返回原引用,避免下游 ChatMessage memo 抖动。
+  let filled = null;
+  for (const b of respContent) {
+    if (b?.type === 'tool_use' && b.id && !localState.toolResultMap[b.id] && globalIndex[b.id]) {
+      if (!filled) filled = {};
+      filled[b.id] = globalIndex[b.id];
+    }
+  }
+  if (!filled) return localState.toolResultMap;
+  return { ...localState.toolResultMap, ...filled };
+}
+
+export function appendToolResultMap(state, messages, startIndex) {
+  const { toolUseMap, toolResultMap, askAnswerMap, planApprovalMap } = state;
+  for (let i = startIndex; i < messages.length; i++) {
+    const msg = messages[i];
+    if (msg.role === 'assistant' && Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block.type === 'tool_use') {
+          let parsed = block;
+          if (typeof block.input === 'string') {
+            try {
+              const cleaned = block.input.replace(/^\[object Object\]/, '');
+              parsed = { ...block, input: JSON.parse(cleaned) };
+            } catch {}
+          }
+          toolUseMap[parsed.id] = parsed;
+          // Plan tools can carry plan + planFilePath directly.
+          // 不依赖前置文件编辑，是 multi-agent-room 等无前置场景的核心数据源
+          if (isPlanToolName(parsed.name) && parsed.input && typeof parsed.input === 'object') {
+            if (typeof parsed.input.plan === 'string' && parsed.input.plan.trim()) {
+              state.latestPlanContent = parsed.input.plan;
+              state._planDirty = (state._planDirty || 0) + 1;
+            }
+            if (typeof parsed.input.planFilePath === 'string' && parsed.input.planFilePath) {
+              state.latestPlanFilePath = parsed.input.planFilePath;
+            }
+          }
+        }
+      }
+    } else if (msg.role === 'user' && Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block.type === 'tool_result') {
+          const matchedTool = toolUseMap[block.tool_use_id];
+          const entry = buildSingleToolResult(block, matchedTool);
+          const { resultText, isPermissionDenied, isUltraplan } = entry;
+          toolResultMap[block.tool_use_id] = entry;
+          if (matchedTool && isAskToolName(matchedTool.name)) {
+            const parsed = parseAskAnswerText(resultText);
+            // 被拒绝的 request_user_input：分 cancelled / rejected 两类——
+            //   - cancelled：cx-viewer 主动取消（Cancel 按钮 / 输入框打字打断）。
+            //     ask-bridge.js / sdk-manager.js 注入 reason 时统一加 [cx-viewer:cancel] 前缀
+            //     作为协议级 sentinel，前缀匹配比模糊文案匹配稳定（SDK 升级换文案不影响）。
+            //   - rejected：schema 校验失败 / hook deny 等"未触达"语义。
+            //   ChatMessage 用这两个 sentinel 区分渲染（cancelled 显式带 __cancelReason__ 灰态）。
+            if (Object.keys(parsed).length === 0 && isPermissionDenied) {
+              const looksCancelled = /\[cx-viewer:cancel\]/.test(resultText);
+              if (looksCancelled) {
+                // 截掉 [cx-viewer:cancel] 前缀只显示用户可读 reason，再 slice 200 防超长
+                const cleanedReason = resultText.replace(/^\s*\[cx-viewer:cancel\]\s*/, '').slice(0, 200);
+                askAnswerMap[block.tool_use_id] = { __cancelled__: true, __cancelReason__: cleanedReason };
+              } else {
+                askAnswerMap[block.tool_use_id] = { __rejected__: true };
+              }
+            } else {
+              askAnswerMap[block.tool_use_id] = parsed;
+            }
+            state._askDirty = (state._askDirty || 0) + 1;
+          }
+          if (matchedTool && isPlanToolName(matchedTool.name)) {
+            if (isPermissionDenied) {
+              const userSaid = resultText.match(/the user said:\s*([\s\S]*)/i);
+              planApprovalMap[block.tool_use_id] = {
+                status: isUltraplan ? 'ultraplan' : 'rejected',
+                feedback: userSaid ? userSaid[1].trim() : '',
+              };
+            } else {
+              planApprovalMap[block.tool_use_id] = parsePlanApproval(resultText);
+            }
+            state._planDirty = (state._planDirty || 0) + 1;
+            // Plan 审批完成（approved/rejected）后无条件重置 latestPlanContent / latestPlanFilePath，
+            // 防止下一个 plan 周期显示旧内容。已审批卡片的 V2 plan 渲染由 ChatMessage 的
+            // approval.planContent || inp.plan || planFileContents 兜底链承担，不依赖 latestPlanContent。
+            state.latestPlanContent = null;
+            state.latestPlanFilePath = null;
+          }
+        }
+      }
+    }
+  }
+}
+
+export function buildToolResultMap(messages) {
+  const state = createEmptyToolState();
+  appendToolResultMap(state, messages, 0);
+  return state;
+}
+
+export function cachedBuildToolResultMap(messages) {
+  let cached = _toolResultCache.get(messages);
+  if (!cached) {
+    cached = buildToolResultMap(messages);
+    _toolResultCache.set(messages, cached);
+  }
+  return cached;
+}
+
+/** 从 request_user_input tool_result 文本中提取答案 map */
+export function parseAskAnswerText(text) {
+  const answers = {};
+  const re = /"([^"]+)"="([^"]*)"/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    answers[m[1]] = m[2];
+  }
+  return answers;
+}
+
+/** 从 plan tool_result 文本中解析审批状态和计划内容 */
+export function parsePlanApproval(text) {
+  if (!text) return { status: 'pending' };
+  if (/User has approved/i.test(text)) {
+    const planMatch = text.match(/##\s*Approved Plan:\s*\n([\s\S]*)/i);
+    return { status: 'approved', planContent: planMatch ? planMatch[1].trim() : '' };
+  }
+  if (/User rejected/i.test(text)) {
+    const feedbackMatch = text.match(/feedback:\s*(.+)/i) || text.match(/User rejected[^:]*:\s*(.+)/i);
+    return { status: 'rejected', feedback: feedbackMatch ? feedbackMatch[1].trim() : '' };
+  }
+  return { status: 'pending' };
+}

package/src/utils/toolResultClassifier.js

@@ -0,0 +1,16 @@
+// 孤儿 tool_use：assistant 调工具但 schema/Zod safeParse 在 PreToolUse hook 之前就抛了
+// InputValidationError——cx-viewer 看到 jsonl 里有 tool_use 块但底层 CLI 从未 spawn hook，
+// 用户既无法答也无法干预。区分于 isPermissionDenied（用户主动拒）：前者根因在 model schema
+// 与 runtime validator 不一致，后者是用户语义否决。
+//
+// 单独成文件让 Node test runner 可直接 import（toolResultBuilder.js 通过 helpers.js 拉了
+// SVG asset import，在 jsdom-less 环境无法加载）。
+export function classifyToolResultError(resultText, isError) {
+  const isPermissionDenied = isError && resultText
+    && /doesn't want to proceed|Permission.*denied|rejected.*tool use|interrupted by user for tool use/i.test(resultText);
+  const isInputValidationError = isError && resultText
+    && /InputValidationError|<tool_use_error>/i.test(resultText)
+    && !isPermissionDenied;
+  const isUltraplan = isPermissionDenied && resultText && /ultraplan/i.test(resultText);
+  return { isPermissionDenied, isInputValidationError, isUltraplan };
+}

package/src/utils/toolResultCore.js

@@ -0,0 +1,161 @@
+/**
+ * tool_result entry 的纯 JS 核心,无 i18n / SVG 依赖。
+ * 拆出独立模块是为了让 node --test 可直接 import(避开 helpers.js → SVG 的 vite-only 链)。
+ * 生产路径仍在 toolResultBuilder.js 通过 buildSingleToolResult 包装,补 i18n label。
+ */
+
+import { internToolResult } from './readResultPool.js';
+import { classifyToolResultError } from './toolResultClassifier.js';
+
+export function extractToolResultText(toolResult) {
+  if (!toolResult.content) return String(toolResult.content ?? '');
+  if (typeof toolResult.content === 'string') return toolResult.content;
+  if (Array.isArray(toolResult.content)) {
+    return toolResult.content
+      .filter(b => b.type === 'text')
+      .map(b => b.text)
+      .join('\n');
+  }
+  return JSON.stringify(toolResult.content);
+}
+
+// 白名单防恶意 JSONL 拼任意 MIME(svg+xml 在某些浏览器可嵌入脚本;text/html 应被
+// <img> 拒绝但日志污染仍可避免)。
+const SAFE_IMAGE_MIME = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+
+// base64 字符串长度上限(2MB ≈ 1.5MB 原图)。超限不渲染 <img>,降级为文字提示,
+// 避免每次 Popover 重渲染都构造几 MB src 字符串导致 React diff / 浏览器解码卡顿。
+const MAX_IMAGE_BASE64_LEN = 2 * 1024 * 1024;
+
+/**
+ * 提取 tool_result 内嵌的 image 块为可直接渲染的 src 列表(或大图占位)。
+ * Tool results for image files / screenshots may return `{type:'image', source: {type:'base64', media_type, data}}`,
+ * 也可能是 `{type:'url', url}`。
+ *
+ * 安全/性能:
+ *   - media_type 必须在白名单内,否则跳过
+ *   - base64 超过 MAX_IMAGE_BASE64_LEN 时,返回 { oversized: true, sizeBytes } 让 UI 降级显示
+ */
+export function extractToolResultImages(toolResult) {
+  if (!toolResult || !Array.isArray(toolResult.content)) return [];
+  const out = [];
+  for (const b of toolResult.content) {
+    if (!b || b.type !== 'image' || !b.source) continue;
+    const s = b.source;
+    if (s.type === 'base64' && typeof s.data === 'string' && s.data.length > 0 && typeof s.media_type === 'string') {
+      if (!SAFE_IMAGE_MIME.has(s.media_type)) continue;
+      if (s.data.length > MAX_IMAGE_BASE64_LEN) {
+        out.push({ oversized: true, mediaType: s.media_type, sizeBytes: Math.floor(s.data.length * 0.75) });
+        continue;
+      }
+      out.push({ src: `data:${s.media_type};base64,${s.data}`, mediaType: s.media_type });
+    } else if (s.type === 'url' && typeof s.url === 'string' && /^https?:\/\//.test(s.url)) {
+      out.push({ src: s.url, mediaType: 'image/url' });
+    }
+  }
+  return out;
+}
+
+// Workflow tool_result 文本固定以此句开头（后台启动即时返回，完成走单独的 task-notification）。
+const WF_LAUNCH_MARKER = 'Workflow launched in background';
+const WF_TASK_ID_RE = /Task ID:\s*([A-Za-z0-9_-]+)/;
+const WF_RUN_ID_RE = /Run ID:\s*(wf_[A-Za-z0-9_-]+)/;
+// Transcript dir / Script file 路径段：…/projects/<cwd 编码>/<sessionId(UUID)>/…
+const WF_SESSION_RE = /\/projects\/[^/\s]+\/([0-9a-fA-F-]{36})\//;
+
+/**
+ * 从 Workflow tool_result 原始文本解析定位线索。命中返回 { runId, taskId, sessionId }，
+ * 否则返回 null。sessionId 为全局唯一 UUID，足以让服务端 /api/workflow-journal 定位 journal
+ * 目录，无需 project hint。
+ *
+ * @param {string} txt - tool_result resultText 原文
+ * @returns {{ runId: string|null, taskId: string|null, sessionId: string|null } | null}
+ */
+export function parseWorkflowFromText(txt) {
+  if (typeof txt !== 'string' || txt.indexOf(WF_LAUNCH_MARKER) === -1) return null;
+  const taskId = (txt.match(WF_TASK_ID_RE) || [])[1] || null;
+  const runId = (txt.match(WF_RUN_ID_RE) || [])[1] || null;
+  const sessionId = (txt.match(WF_SESSION_RE) || [])[1] || null;
+  if (!runId && !taskId) return null;
+  return { runId, taskId, sessionId };
+}
+
+export function buildSingleToolResultCore(block, matchedTool) {
+  let toolName = null;
+  let toolInput = null;
+  if (matchedTool) {
+    toolName = matchedTool.name;
+    toolInput = matchedTool.input;
+  }
+  let resultText = extractToolResultText(block);
+  resultText = internToolResult(resultText);
+  const isError = !!block.is_error;
+  const { isPermissionDenied, isInputValidationError, isUltraplan } = classifyToolResultError(resultText, isError);
+  const images = extractToolResultImages(block);
+  // Workflow 工具：直接从原始 tool_result 文本解析 { runId, taskId, sessionId } 线索定位
+  // 并拉取 workflow run journal 渲染面板。线索原生存在于 wire 文本（"Workflow launched in
+  // background. Task ID: … / Run ID: wf_… / Transcript dir: …/projects/<cwd>/<sessionId>/…"），
+  // 不依赖服务端注入——历史日志（含未经 enrich 的旧日志）同样可识别。
+  // 回退：兼容旧路径已注入的 block._cxvWorkflow（服务端 enrich-workflow，仍用于 live）。
+  // 文本解析命中时补回 _cxvWorkflow 携带的 project（解析线索里没有），用于 journal 定位的精确消歧。
+  const parsedWf = parseWorkflowFromText(resultText);
+  const cxvWf = (block._cxvWorkflow && typeof block._cxvWorkflow === 'object') ? block._cxvWorkflow : null;
+  const workflow = parsedWf
+    ? { ...parsedWf, project: cxvWf?.project || null }
+    : cxvWf;
+  return { toolName, toolInput, resultText, isError, isPermissionDenied, isInputValidationError, isUltraplan, images, workflow };
+}
+
+const ANSI_ESCAPE = /\x1b\[[0-9;]*[A-Za-z]/g;
+
+/**
+ * 紧凑模式 Popover 浮窗的 tool_result 预览:从 toolResultMap entry 生成截断文本。
+ *
+ * 返回 null 的场景(由 caller skip 渲染预览块):
+ *   - entry 不存在 / resultText 为空
+ *   - isPermissionDenied / isInputValidationError(外部已有红 badge,避免双显示)
+ *
+ * 工具特定清洗:
+ *   - shell_command:strip ANSI 转义(`\x1b[31mERROR\x1b[0m` → `ERROR`)
+ *
+ * 截断策略:行数上限 maxLines(默认 50,留够内容让 CSS max-height + overflow:auto 触发
+ * 滚动),每行字符上限 maxChars(默认 500,防止超长单行撑爆 popover)。
+ */
+export function compactResultPreview(entry, opts = {}) {
+  if (!entry || typeof entry !== 'object') return null;
+  if (entry.isPermissionDenied || entry.isInputValidationError) return null;
+
+  // 图片优先:图片文件 / 截图等场景,images 数组非空则返回图片预览(text 可同时存在,作为辅助文本)
+  const images = Array.isArray(entry.images) ? entry.images : null;
+  const hasImages = images && images.length > 0;
+
+  const raw = entry.resultText;
+  const hasText = typeof raw === 'string' && raw.length > 0;
+  if (!hasImages && !hasText) return null;
+
+  const maxLines = opts.maxLines || 50;
+  const maxChars = opts.maxChars || 500;
+
+  let text = null;
+  if (hasText) {
+    let cleaned = raw;
+    if (entry.toolName === 'shell_command') {
+      cleaned = cleaned.replace(ANSI_ESCAPE, '');
+    }
+    const lines = cleaned.split('\n');
+    const totalLines = lines.length;
+    const slice = lines.slice(0, maxLines);
+    const out = [];
+    for (let i = 0; i < slice.length; i++) {
+      let line = slice[i];
+      if (line.length > maxChars) line = line.slice(0, maxChars) + '…';
+      out.push(line);
+    }
+    text = out.join('\n');
+    if (totalLines > maxLines) text = text + '\n…';
+    if (text.trim().length === 0) text = null;
+  }
+
+  if (!hasImages && !text) return null;
+  return { text, images: hasImages ? images : null };
+}

package/src/utils/toolsDiff.js

@@ -0,0 +1,44 @@
+/**
+ * Tools diff —— 计算「当前请求 tools」相对「上一条 MainAgent 请求 tools」的新增/移除。
+ *
+ * 用于 ContextTab 的 tools 变化可视化(tools_search 等场景下 tools 列表逐请求变化)。
+ * 抽成纯函数:① 让渲染逻辑变短;② 统一 added/removed 的统计口径(均按唯一 name 计数,
+ * 不再 added 按数组、removed 按集合导致重名时口径不一致);③ 可独立单测。
+ *
+ * 约定:tool 按 name 比对(无 name 的 tool 不参与 diff);prevTools 非数组(无上一条 /
+ * 当前请求非 MainAgent)时视为「无可比对基线」,hasPrev=false、不产生任何 added/removed。
+ *
+ * @param {Array|undefined|null} prevTools 上一条请求的 tools 数组(可空)
+ * @param {Array|undefined|null} curTools  当前请求的 tools 数组
+ * @returns {{
+ *   hasPrev: boolean,            // 是否存在可比对基线
+ *   isAdded: (name: string) => boolean, // 某 name 是否为相对上一条新增
+ *   addedNames: string[],        // 新增的唯一 name 列表
+ *   removedNames: string[],      // 移除的唯一 name 列表(上一条有、当前没有)
+ *   addedCount: number,          // = addedNames.length
+ *   removedCount: number,        // = removedNames.length
+ *   changed: boolean,            // 是否有任何新增或移除
+ * }}
+ */
+export function computeToolsDiff(prevTools, curTools) {
+  const prevNameSet = Array.isArray(prevTools)
+    ? new Set(prevTools.map(t => t?.name).filter(Boolean))
+    : null;
+  const curNameSet = new Set(
+    (Array.isArray(curTools) ? curTools : []).map(t => t?.name).filter(Boolean),
+  );
+
+  const addedNames = prevNameSet ? [...curNameSet].filter(n => !prevNameSet.has(n)) : [];
+  const removedNames = prevNameSet ? [...prevNameSet].filter(n => !curNameSet.has(n)) : [];
+
+  return {
+    hasPrev: prevNameSet != null,
+    // 仅对有 name 且存在基线的 tool 判新增;无 name 无法按名比对,一律不标记
+    isAdded: (name) => prevNameSet != null && !!name && !prevNameSet.has(name),
+    addedNames,
+    removedNames,
+    addedCount: addedNames.length,
+    removedCount: removedNames.length,
+    changed: addedNames.length > 0 || removedNames.length > 0,
+  };
+}

package/src/utils/toolsXmlFormatter.js

@@ -0,0 +1,3 @@
+// Thin re-export: canonical implementation lives in server/lib/tools-xml-formatter.js
+// (no React deps, shared by browser and server-side callers).
+export { formatToolAsXml, formatToolsAsXml } from '../../server/lib/tools-xml-formatter.js';

package/src/utils/ultraplanController.js

@@ -0,0 +1,109 @@
+// UltraPlan 纯逻辑控制器（从 ChatView / TerminalPanel 各自抽出的重复方法收口为一份）。
+//
+// 依赖注入的纯逻辑类，不依赖 antd / React / DOM 之外的东西，可直接在 node:test 下 import。
+// host 适配器把宿主组件的 state / props / 上传 / 提示 / 关闭编辑器桥接进来；宿主的 6 个
+// ultraplan 方法退化为一行委托。state 仍留在宿主 component.state，行为不变。
+//
+// host 接口：
+//   getState()            → 宿主 this.state（读 ultraplanFiles / customUltraplanExperts / ultraplanVariant）
+//   setState(updater)     → 转发宿主 this.setState，原样透传对象式与 functional updater
+//   onUpdatePreferences(p) → 包 this.props.onUpdatePreferences?.(p)（props 无该回调则不调）
+//   uploadFile(file)      → 包 uploadFileAndGetPath(file)（注入以避免 import TerminalPanel 形成循环依赖）
+//   messageError(msg)     → 包 antd message.error(msg)（注入以保持本模块 antd-free）
+//   closeEditor()         → 包宿主各自的 closeCustomUltraplanEditor()（两边写不同 state 字段，故留宿主）
+
+import { visibleExpertKeys } from './ultraplanExperts.js';
+
+export class UltraplanController {
+  constructor(host) {
+    this.host = host;
+  }
+
+  handleUpload = () => {
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.onchange = async (e) => {
+      const file = e.target.files?.[0];
+      if (!file) return;
+      try {
+        const path = await this.host.uploadFile(file);
+        this.host.setState(prev => ({
+          ultraplanFiles: [...prev.ultraplanFiles, { name: file.name, path }],
+        }));
+      } catch (err) {
+        console.error('Ultraplan upload failed:', err);
+        this.host.messageError(err?.message || 'Upload failed');
+      }
+    };
+    input.click();
+  };
+
+  handlePaste = async (e) => {
+    const items = e.clipboardData?.items;
+    if (!items) return;
+    for (const item of items) {
+      if (item.type.startsWith('image/')) {
+        e.preventDefault();
+        const file = item.getAsFile();
+        if (!file) return;
+        try {
+          const path = await this.host.uploadFile(file);
+          const name = file.name || `paste-${Date.now()}.png`;
+          this.host.setState(prev => ({
+            ultraplanFiles: [...prev.ultraplanFiles, { name, path }],
+          }));
+        } catch (err) {
+          console.error('Ultraplan paste upload failed:', err);
+          this.host.messageError(err?.message || 'Upload failed');
+        }
+        return;
+      }
+    }
+  };
+
+  handleRemoveFile = (idx) => {
+    this.host.setState(prev => ({
+      ultraplanFiles: prev.ultraplanFiles.filter((_, i) => i !== idx),
+    }));
+  };
+
+  persistExperts = (experts) => {
+    this.host.setState({ customUltraplanExperts: experts });
+    this.host.onUpdatePreferences({ customUltraplanExperts: experts });
+  };
+
+  saveExpert = (item) => {
+    const existing = this.host.getState().customUltraplanExperts;
+    const idx = existing.findIndex(e => e.id === item.id);
+    const next = idx >= 0
+      ? existing.map(e => (e.id === item.id ? item : e))
+      : [...existing, item];
+    this.persistExperts(next);
+    this.host.closeEditor();
+  };
+
+  deleteExpert = (id) => {
+    const st = this.host.getState();
+    const next = st.customUltraplanExperts.filter(e => e.id !== id);
+    this.persistExperts(next);
+    // 如果当前选中的就是被删的，回退到首个可见专家（无可见则 codeExpert）
+    if (st.ultraplanVariant === 'custom:' + id) {
+      const visible = visibleExpertKeys(next, st.ultraplanExpertOrder, st.ultraplanExpertHidden);
+      this.host.setState({ ultraplanVariant: visible[0] || 'codeExpert' });
+    }
+    this.host.closeEditor();
+  };
+
+  // 「管理专家」弹窗的显隐 / 排序落盘：写 state + 同步 preferences（多端/刷新一致）。
+  // 若当前选中变体因隐藏而不再可见，回退到首个可见键（无可见则 codeExpert）。
+  persistExpertLayout = ({ order, hidden }) => {
+    const st = this.host.getState();
+    const patch = { ultraplanExpertOrder: order, ultraplanExpertHidden: hidden };
+    const visible = visibleExpertKeys(st.customUltraplanExperts, order, hidden);
+    if (!visible.includes(st.ultraplanVariant)) {
+      patch.ultraplanVariant = visible[0] || 'codeExpert';
+    }
+    this.host.setState(patch);
+    this.host.onUpdatePreferences({ ultraplanExpertOrder: order, ultraplanExpertHidden: hidden });
+  };
+}