cc-viewer 1.6.348 → 1.7.1

package/src/utils/readResultPool.js

@@ -0,0 +1,106 @@
+/**
+ * Read tool_result content intern pool.
+ *
+ * 1.6.237 后实测：同一 .jsx 文件被 87 个 SubAgent / 父 user message 各持一份完整副本（30MB+ 重复）。
+ * 对 Read 工具的 resultText 做 content-addressed dedup，让相同内容共享同一字符串引用。
+ * hash 仅用 length + 前 64 / 后 64 字符避免大字符串 O(n) hash；当 length > 512
+ * 再加采中段 64 字符（共三段 192 字节），令仅中段不同的长串也能区分；碰撞概率极低。
+ *
+ * 抽到独立模块（无外部依赖）便于 node --test 直接 import，避免被
+ * toolResultBuilder.js 的传递依赖（./helpers 无 .js 后缀）污染。
+ */
+
+// 容量上限设计：1000 vs entry-slim.js 的 _toolsPool/_systemPool 上限 200，差异源自流量域不同。
+// tools/system 是 entry-level 配置数组，全 session 命中分布稳定，实测 pool size <5（200 极宽松）；
+// readResultPool 池化的是 tool_result 字符串（v4 派生层 + v5 raw payload），
+// 单 session 唯一字符串数量与 tool 调用次数同阶（v4 实测 4400 calls / pool size 363）。
+// B 项加入 raw payload 后预期再 +20-40%，1000 留 ~30% 余量；超阈值由 _poolEvictions 暴露。
+const _MAX_READ_POOL_SIZE = 1000;
+const _MIN_DEDUP_LEN = 256;
+const _SIG_MID_THRESHOLD = 512;
+const _readResultPool = new Map();
+let _poolEvictions = 0;
+
+// v5: sig 增加 mid-slice（当 length > 512）。对齐 entry-slim.js _systemSig 的边界增强模式。
+// B 项把 raw payload tool_result block.content 也接入此 pool（含 Bash tab-padded / log 类
+// 长度+前后缀重合的结构化输出），暴露面变大。length+first 64+last 64 在该场景对碰撞抗性
+// 不足，加 mid-64 后要求"长度+三段共 192 字节"全匹配才视为同串。
+function _readResultSig(s) {
+  if (s.length > _SIG_MID_THRESHOLD) {
+    const midIdx = Math.floor(s.length / 2);
+    return s.length + ':' + s.slice(0, 64) + ':' + s.slice(midIdx, midIdx + 64) + ':' + s.slice(-64);
+  }
+  return s.length + ':' + s.slice(0, 64) + ':' + s.slice(-64);
+}
+
+/**
+ * 把 Read 工具的 resultText 替换为 pool 中的共享引用（命中时）或注册新值。
+ * 短字符串（< 256）跳过 dedup（不值得 sig 开销）。
+ *
+ * @param {string} s - resultText 原文
+ * @returns {string} 池化后的字符串引用
+ */
+export function internReadResult(s) {
+  if (typeof s !== 'string' || s.length < _MIN_DEDUP_LEN) return s;
+  const sig = _readResultSig(s);
+  const pooled = _readResultPool.get(sig);
+  if (pooled !== undefined) return pooled;
+  if (_readResultPool.size >= _MAX_READ_POOL_SIZE) {
+    _readResultPool.delete(_readResultPool.keys().next().value);
+    _poolEvictions++;
+  }
+  _readResultPool.set(sig, s);
+  return s;
+}
+
+/** 测试辅助：清空 Read intern pool 和 eviction counter。 */
+export function _resetReadPoolForTest() {
+  _readResultPool.clear();
+  _poolEvictions = 0;
+}
+
+/** 测试辅助：观察 pool 当前 size。 */
+export function _getReadPoolSizeForTest() {
+  return _readResultPool.size;
+}
+
+/** 诊断：FIFO 淘汰累计次数。典型 session <50；>200 提示 _MAX_READ_POOL_SIZE 需上调。 */
+export function _getReadPoolEvictionsForTest() {
+  return _poolEvictions;
+}
+
+/**
+ * 通用版：Read 之外的所有 tool_result（Bash/Grep/Glob/MCP/...）也走同一 pool。
+ * 算法与 internReadResult 完全相同（同 _readResultSig + 同 _readResultPool），
+ * 名字区分只是语义上的扩展，便于 toolResultBuilder.js 默认全 intern。
+ *
+ * @param {string} s - tool_result 的 resultText 原文
+ * @returns {string} 池化后的字符串引用
+ */
+export function internToolResult(s) {
+  return internReadResult(s);
+}
+
+/**
+ * 命中-aware 变体：仅在 pool 已有相同 sig 时返回共享 ref，否则注册并返回 null。
+ *
+ * 设计动机：JS string `===` 是值比较，调用方拿到 internReadResult 的返回值无法判断"这是
+ * pool 命中（应替换 block.content 节省内存）"还是"刚注册（保持原 ref 即可）"。
+ * 此函数把命中信号显式上抛——`null` = 未命中或短结果（无需替换），非 null = 命中（应替换）。
+ * v5 entry-slim.js 的 lazy-clone 路径依赖这个信号决定是否触发 messages 浅克隆。
+ *
+ * @param {string} s - tool_result 内容原文
+ * @returns {string|null} 命中时返回 pool 共享 ref；未命中（已注册）或短结果（< 256）返回 null
+ */
+export function internToolResultIfPooled(s) {
+  if (typeof s !== 'string' || s.length < _MIN_DEDUP_LEN) return null;
+  const sig = _readResultSig(s);
+  const pooled = _readResultPool.get(sig);
+  if (pooled !== undefined) return pooled;
+  if (_readResultPool.size >= _MAX_READ_POOL_SIZE) {
+    _readResultPool.delete(_readResultPool.keys().next().value);
+    _poolEvictions++;
+  }
+  _readResultPool.set(sig, s);
+  return null;
+}

package/src/utils/refreshCachedItemProp.js

@@ -0,0 +1,30 @@
+import React from 'react';
+
+/**
+ * 刷新缓存的 assistant ChatMessage element 上随 ChatView `_sessionItemCache` FULL HIT 而冻结的
+ * 过期 map prop。仅对「持有指定 toolName 的 tool_use」的 element 做 cloneElement 注入 nextMap，
+ * 其余原样返回；prevMap===nextMap 时返回原数组（零分配）。
+ *
+ * 背景：FULL HIT 路径直接返回 `sc.items` 时 React reconciler 看到完全相同的 element 引用就跳过
+ * diff，ChatMessage SCU 根本不会被调用，元素创建时冻结的旧 map（planApprovalMap / askAnswerMap）
+ * 永不刷新——导致 ExitPlanMode 审批后卡片不切「已批准」、AskUserQuestion 答完后仍显示 pending。
+ * 本函数合并自原 refreshPlanApprovalCache / refreshAskAnswerCache 两个孪生模块。
+ *
+ * @param {Array} items - 缓存的 ChatMessage React element 数组
+ * @param {object} prevMap - 上一轮存入 cache 时的 map 引用
+ * @param {object} nextMap - 本轮派生的 map 引用
+ * @param {string} toolName - 触发刷新的 tool_use 名（'ExitPlanMode' / 'AskUserQuestion'）
+ * @param {string} propName - 要刷新的 prop 名（'planApprovalMap' / 'askAnswerMap'）
+ * @returns {Array} 引用全等时为 items；否则为新数组（仅命中者被 cloneElement）
+ */
+export function refreshCachedItemProp(items, prevMap, nextMap, toolName, propName) {
+  if (prevMap === nextMap) return items;
+  let dirty = false;
+  const out = items.map(m => {
+    if (!m || !m.props || m.props.role !== 'assistant' || !Array.isArray(m.props.content)) return m;
+    if (!m.props.content.some(b => b.type === 'tool_use' && b.name === toolName)) return m;
+    dirty = true;
+    return React.cloneElement(m, { [propName]: nextMap });
+  });
+  return dirty ? out : items;
+}

package/src/utils/requestType.js

@@ -0,0 +1,208 @@
+/**
+ * 请求类型分类工具
+ * classifyRequest(req, nextReq?) 返回 { type, subType }
+ * type: 'MainAgent' | 'SubAgent' | 'Teammate' | 'Count' | 'Preflight' | 'Plan' | 'Synthetic'
+ *
+ * Synthetic: Claude Code CLI 在主会话里合成的内部工具查询
+ * （idle 返回 recap / 会话标题生成 / 压缩摘要等），HTTP 层 role=user 但并非用户手输。
+ * subType: 'Recap' | 'Title' | 'Compact' | 'Topic' | 'Summary'
+ */
+// SYNTHETIC_PROMPTS 已抬到 contentFilter.js，让 isSystemText 也能共用（ChatView 字符串分支过滤）。
+// requestType.js 继续维护 getSyntheticSubType —— 走的是"last user message + isMainAgent 门槛"的更强
+// 形式判断（用于 RequestList 打 Synthetic tag）；isSystemText 走的是"纯文本起首匹配"（用于对话流隐藏）。
+// Extensioned import: this module chain (requestType → contentFilter →
+// teammateDetector) is shared with the server (wire-v3 typeTag computation in
+// server/lib/v2/meta-rows.js) — Node ESM requires explicit extensions.
+import { isMainAgent, isTeammate, getSystemText, extractTeammateName, SYNTHETIC_PROMPTS } from './contentFilter.js';
+
+function getMessageText(msg) {
+  const c = msg?.content;
+  if (typeof c === 'string') return c;
+  if (Array.isArray(c)) {
+    for (const block of c) {
+      if (block?.type === 'text' && block.text) return block.text;
+    }
+  }
+  return '';
+}
+
+function getSubAgentSubType(req) {
+  const body = req.body || {};
+  const sysText = getSystemText(body);
+
+  if (/Extract any file paths/i.test(sysText)) return 'Bash';
+  if (/process Bash commands/i.test(sysText)) return 'Bash';
+  if (/command execution specialist/i.test(sysText)) return 'Bash';
+  if (/file search specialist/i.test(sysText)) return 'Search';
+  if (/planning specialist/i.test(sysText)) return 'Plan';
+  if (/general-purpose agent/i.test(sysText)) return 'General';
+  if (/security monitor/i.test(sysText)) return 'Advisor';
+  if (/performing a web search/i.test(sysText)) return 'WebSearch';
+
+  const msgs = body.messages || [];
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    if (msgs[i].role !== 'user') continue;
+    const text = getMessageText(msgs[i]);
+    if (/^Command:/m.test(text)) return 'Bash';
+    break;
+  }
+
+  return null;
+}
+
+/**
+ * 判断请求是否为 Claude Code 内部合成的工具查询。
+ * 必须同时满足：(1) 来自主会话（isMainAgent 通过），(2) 最后一条 user message 的起首
+ * 命中 SYNTHETIC_PROMPTS 白名单。返回匹配的 subType 或 null。
+ *
+ * 为什么不用"消息数短"作为启发式：拦截日志里 teammate 消息 / tool_result
+ * 也常出现 messages.length <= 3，会把它们误判为 Synthetic。白名单精确度更高，
+ * 代价是 Claude Code 新增合成类型需要手工加 pattern。
+ */
+function getSyntheticSubType(req) {
+  if (!isMainAgent(req)) return null;
+  const msgs = req.body?.messages || [];
+  if (!msgs.length) return null;
+  const last = msgs[msgs.length - 1];
+  if (!last || last.role !== 'user') return null;
+  const text = getMessageText(last).trim();
+  if (!text) return null;
+  for (const { subType, pattern } of SYNTHETIC_PROMPTS) {
+    if (pattern.test(text)) return subType;
+  }
+  return null;
+}
+
+function isCountRequest(req) {
+  const msgs = req.body?.messages;
+  if (!Array.isArray(msgs) || msgs.length !== 1) return false;
+  const msg = msgs[0];
+  return msg.role === 'user' && msg.content === 'count';
+}
+
+function isQuotaCheck(req) {
+  const body = req.body || {};
+  if (body.max_tokens !== 1) return false;
+  if (body.system) return false;
+  if (Array.isArray(body.tools) && body.tools.length > 0) return false;
+  const msgs = body.messages;
+  if (!Array.isArray(msgs) || msgs.length !== 1) return false;
+  return msgs[0].role === 'user' && msgs[0].content === 'quota';
+}
+
+/**
+ * Preflight 判断：
+ * 1. tools 为空或不存在
+ * 2. messages 仅一条 user message
+ * 3. system 包含 Claude Code 特征
+ * 4. 下一条请求的 messages 中包含本条 message 的文本（前80字符匹配）
+ */
+function isPreflightRequest(req, nextReq) {
+  const body = req.body || {};
+  const tools = body.tools;
+  const msgs = body.messages || [];
+
+  // 条件1: tools 为空
+  if (Array.isArray(tools) && tools.length > 0) return false;
+
+  // 条件2: 仅一条 message
+  if (msgs.length !== 1 || msgs[0].role !== 'user') return false;
+
+  const text = getMessageText(msgs[0]);
+  if (!text) return false;
+
+  // 排除 count 请求
+  if (text.trim() === 'count') return false;
+
+  // 排除工具类请求（Bash 命令、安全策略检查、系统通知等）
+  const trimmed = text.trim();
+  if (/^Command:/m.test(text) || /^<policy_spec>/i.test(trimmed) || /^<task-notification>/i.test(trimmed)) return false;
+
+  // 条件3: system 包含 Claude Code 特征，但排除 Bash 处理器
+  const sysText = getSystemText(body);
+  if (!sysText.includes('Claude Code')) return false;
+  if (/process Bash commands/i.test(sysText)) return false;
+  if (/Extract any file paths/i.test(sysText)) return false;
+
+  // 条件4: 下一条请求的 messages 中包含本条文本
+  if (nextReq) {
+    const nextMsgs = nextReq.body?.messages || [];
+    const sig = text.slice(0, 80);
+    const found = nextMsgs.some(m => {
+      const c = m?.content;
+      if (typeof c === 'string') return c.includes(sig);
+      if (Array.isArray(c)) {
+        return c.some(block => block?.type === 'text' && block.text && block.text.includes(sig));
+      }
+      return false;
+    });
+    if (found) return true;
+  }
+
+  return false;
+}
+
+/**
+ * 分类请求
+ * @param {object} req - 当前请求
+ * @param {object} [nextReq] - 下一条请求（用于 Preflight 判断）
+ */
+export function classifyRequest(req, nextReq) {
+  // Teammate 子进程的请求优先识别（收敛于 contentFilter.isTeammate）
+  if (isTeammate(req)) {
+    if (req.teammate) return { type: 'Teammate', subType: req.teammate };
+    if (req._cachedTeammateName === undefined) {
+      req._cachedTeammateName = extractTeammateName(req.body) || null;
+    }
+    return { type: 'Teammate', subType: req._cachedTeammateName };
+  }
+
+  // Synthetic 检查要在 MainAgent 之前——这类请求 mainAgent=true，
+  // 不拦截就会被当作普通主会话轮次，用户看不出是 Claude Code 合成的。
+  const syntheticSub = getSyntheticSubType(req);
+  if (syntheticSub) {
+    return { type: 'Synthetic', subType: syntheticSub };
+  }
+
+  if (isMainAgent(req)) {
+    return { type: 'MainAgent', subType: null };
+  }
+
+  if (req.isCountTokens || isCountRequest(req)) {
+    return { type: 'Count', subType: null };
+  }
+
+  if (isQuotaCheck(req)) {
+    return { type: 'Count', subType: 'Quota' };
+  }
+
+  if (isPreflightRequest(req, nextReq)) {
+    // Preflight 内容以 "Implement the following plan:" 开头 → Plan:Prompt
+    const text = getMessageText((req.body?.messages || [])[0]);
+    if (/Implement the following plan:/i.test(text.trim())) {
+      return { type: 'Plan', subType: 'Prompt' };
+    }
+    return { type: 'Preflight', subType: null };
+  }
+
+  const subType = getSubAgentSubType(req);
+  return { type: 'SubAgent', subType };
+}
+
+// Tag 显示文本
+export function formatRequestTag(type, subType) {
+  if (type === 'Teammate' && subType) return `Teammate:${subType}`;
+  if (type === 'Plan' && subType) return `Plan:${subType}`;
+  if (type === 'SubAgent' && subType) return `SubAgent:${subType}`;
+  if (type === 'Synthetic' && subType) return `Synthetic:${subType}`;
+  if (type === 'Count' && subType) return `Count:${subType}`;
+  return type;
+}
+
+// Teammate label: "Teammate: name(model-short)" or "Teammate: name"
+export function formatTeammateLabel(name, model) {
+  const displayName = name || 'X';
+  if (!model) return `Teammate: ${displayName}`;
+  const short = model.replace(/^claude-/i, '').replace(/-\d{8}$/, '');
+  return `Teammate: ${displayName}(${short})`;
+}

package/src/utils/resizeCalc.js

@@ -0,0 +1,21 @@
+// 拖拽 resize 的纯几何计算 —— 把 startX/Y/curX/curY/startW/startH 换成 clamp 后的 {w, h}。
+// 单测可独立验证 4 个 clamp 边界 + 任意方向(dirX/dirY ∈ {-1, +1}),不依赖 DOM/React。
+//
+// 方向参数语义:
+//   dirX = -1 →  鼠标往左拉时 w 变大(handle 在左侧,例:左上 / 左下)
+//   dirX = +1 →  鼠标往右拉时 w 变大(handle 在右侧,例:右上 / 右下)
+//   dirY 同理(-1 = handle 在上侧)
+//
+// 调用方需保证 clamp 区间合法(min ≤ max);若不合法则 max 取胜(避 NaN)。
+export function calcResizedSize({ startX, startY, curX, curY, startW, startH, dirX, dirY, clamp }) {
+  const dx = (curX - startX) * dirX;
+  const dy = (curY - startY) * dirY;
+  let w = startW + dx;
+  let h = startH + dy;
+  const { minW, maxW, minH, maxH } = clamp || {};
+  if (typeof minW === 'number' && w < minW) w = minW;
+  if (typeof maxW === 'number' && w > maxW) w = maxW;
+  if (typeof minH === 'number' && h < minH) h = minH;
+  if (typeof maxH === 'number' && h > maxH) h = maxH;
+  return { w: Math.round(w), h: Math.round(h) };
+}

package/src/utils/resolveLocalized.js

@@ -0,0 +1,17 @@
+// 把「纯字符串 或 {lang: str} 本地化对象」解析成当前语言下的字符串。
+// 用于 ultraAgents 预设专家的 title / description：服务端原样下发本地化对象，
+// 前端按 getLang() 解析，语言切换无需重新请求。(content 是单语言字符串，不走本处。)
+//
+// 回退顺序：精确语言 → 去区域后的主语言(zh-TW→zh, pt-BR→pt) → en → zh → 首个非空字符串值。
+// 异常输入（数组 / 数字 / null / 空对象 / 全空串对象）一律安全返回 ''，绝不抛错。
+export function resolveLocalized(field, lang) {
+  if (typeof field === 'string') return field;
+  if (!field || typeof field !== 'object' || Array.isArray(field)) return '';
+  const pick = (k) => (typeof field[k] === 'string' && field[k].trim() ? field[k] : null);
+  const base = typeof lang === 'string' ? lang.split('-')[0] : '';
+  return pick(lang)
+    || pick(base)
+    || pick('en')
+    || pick('zh')
+    || (Object.values(field).find(v => typeof v === 'string' && v.trim()) || '');
+}

package/src/utils/searchApi.js

@@ -0,0 +1,47 @@
+import { apiUrl } from './apiUrl';
+import { reportSwallowed } from './errorReport';
+
+/**
+ * Search the project codebase for `params.query`.
+ * @param {object} params { query, caseSensitive, wholeWord, regex, includeGlobs, excludeGlobs }
+ * @param {AbortSignal} [signal] abort a superseded / cancelled search
+ * @returns {Promise<{results, truncated, engine, filesScanned, error?}>}
+ * @throws on network failure or non-OK status (except 400 invalid_regex, surfaced as {error})
+ */
+export async function searchCode(params, signal) {
+  const res = await fetch(apiUrl('/api/search'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(params),
+    signal,
+  });
+  if (res.status === 400) {
+    // invalid_regex is an expected, user-facing outcome — return it as data, not a throw.
+    const data = await res.json().catch(() => ({ error: 'error' }));
+    return { results: [], truncated: false, engine: 'none', filesScanned: 0, error: data.error || 'error' };
+  }
+  if (!res.ok) throw new Error(`search failed: ${res.status}`);
+  return res.json();
+}
+
+/**
+ * Replace matches across files (or dry-run to count).
+ * @param {object} params { query, caseSensitive, wholeWord, regex, includeGlobs, excludeGlobs,
+ *                          replacement, scope:'all'|'file'|'match', file?, line?, col?, expectText?,
+ *                          skipPaths?, dryRun? }
+ * @returns {Promise<{changed, skipped, total, error?}>}
+ */
+export async function replaceInFiles(params, signal) {
+  const res = await fetch(apiUrl('/api/search-replace'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(params),
+    signal,
+  });
+  if (res.status === 400) {
+    const data = await res.json().catch(() => ({ error: 'error' }));
+    return { changed: [], skipped: [], total: 0, error: data.error || 'error' };
+  }
+  if (!res.ok) throw new Error(`replace failed: ${res.status}`);
+  return res.json();
+}

package/src/utils/searchReplace.js

@@ -0,0 +1,51 @@
+// Client mirror of the server's replace primitives (server/lib/code-replace.js +
+// buildQueryRegExp/looksCatastrophic in code-search.js). Kept byte-for-byte equivalent so the
+// inline replace preview equals exactly what the server writes, and so single-match targeting
+// uses the SAME (node/JS) match positions the server will — never a ripgrep-derived submatch
+// offset that could disagree. Parity is pinned by test/search-replace-preview.test.js.
+
+export function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function buildQueryRegExp({ query, regex, wholeWord, caseSensitive }) {
+  let pattern = regex ? query : escapeRegExp(query);
+  if (wholeWord) pattern = `\\b(?:${pattern})\\b`;
+  const flags = 'g' + (caseSensitive ? '' : 'i');
+  return new RegExp(pattern, flags);
+}
+
+export function looksCatastrophic(pattern) {
+  return /\([^()]*[+*}][^()]*\)\s*[+*]/.test(pattern)
+    || /\([^()]*[+*][^()]*\)\{\d/.test(pattern);
+}
+
+/** Non-global clone (for native $-expansion of a single match). */
+export function noGlobal(reG) {
+  return new RegExp(reG.source, reG.flags.replace('g', ''));
+}
+
+/** regex → native JS $-substitution; literal → verbatim (no $ interpretation). */
+export function applyMatch(matchedText, reNoG, regex, replacement) {
+  if (!regex) return replacement;
+  return matchedText.replace(reNoG, replacement);
+}
+
+/**
+ * For a clicked match, recover the node-engine match position on the line so the server can
+ * re-verify it. Finds the JS-regex match covering `submatchStart`; returns its index + text.
+ * @returns {{col:number, expectText:string}|null}
+ */
+export function computeMatchTarget(lineText, submatchStart, reG) {
+  reG.lastIndex = 0;
+  let m;
+  let fallback = null;
+  while ((m = reG.exec(lineText)) !== null) {
+    if (m[0] === '') { reG.lastIndex++; continue; }
+    if (m.index === submatchStart) { reG.lastIndex = 0; return { col: m.index, expectText: m[0] }; }
+    if (m.index <= submatchStart && submatchStart < m.index + m[0].length) fallback = { col: m.index, expectText: m[0] };
+    if (m.index > submatchStart) break;
+  }
+  reG.lastIndex = 0;
+  return fallback;
+}

package/src/utils/seqResourceLoaders.js

@@ -0,0 +1,79 @@
+// 三态加载 + seq 防污 共用实现（class 组件用）。
+// 三态契约：state[key] === null  → 未加载（loading）
+//          state[key] === false → 加载失败
+//          state[key] === <data> → 加载成功
+// 组件 instance 上必须存在 `_<name>Seq` 计数字段（constructor 初始化为 0）。
+// workspace 切换时 componentDidUpdate 应 `++this._<name>Seq` 失效在途请求。
+//
+// ─── 抽取边界（有意为之，请勿扩张）────────────────────────────────────────────
+// 这里**只覆盖 lazy-load 静默路径**：组件首次挂载/workspace 切换时自动 fire，失败
+// 落 false 让上游 chip / popover 进入空态。
+// 用户主动触发的 refresh（带 toast、loading spinner、错误 message）刻意保留在
+// AppHeader.jsx (handleRefreshMemory) / Mobile.jsx 各自的 inline 实现里，原因：
+//   1) 主动 refresh 需要 caller 决定 toast 文案、loading 视觉、错误反馈策略；
+//      若硬塞进 loader 内部，loader 必须 import message → 反向耦合 antd UI 层。
+//   2) loadMemoryDetail / loadClaudeMdDetail 也是用户点击驱动，含「成功后跳详情面板」
+//      副作用，同样不属于"加载即更新 state"语义，留 caller 自管更清晰。
+// 即：本文件 = 静默路径，inline = 用户触发路径。两者并存是设计选择，不是抽取漏。
+// ────────────────────────────────────────────────────────────────────────────
+
+import { apiUrl } from './apiUrl.js';
+
+async function _seqGuardedFetch(component, seqProp, url) {
+  const seq = ++component[seqProp];
+  let r;
+  try {
+    r = await fetch(url);
+  } catch (e) {
+    if (seq !== component[seqProp]) return { stale: true };
+    return { stale: false, ok: false, error: e, errorKind: 'network' };
+  }
+  try {
+    const data = await r.json();
+    if (seq !== component[seqProp]) return { stale: true };
+    return { stale: false, ok: r.ok, status: r.status, data };
+  } catch (e) {
+    if (seq !== component[seqProp]) return { stale: true };
+    return { stale: false, ok: false, error: e, errorKind: 'parse', status: r.status };
+  }
+}
+
+// 拉取项目文件系统 skills。
+// 失败时若 _fsSkills 已是数组（前次成功结果）→ 保留不 clobber，
+// 避免 popover chip 从乐观态回退到历史空态。
+// 返回 { ok: true, skills } / { ok: false, reason: 'local_log'|'stale'|'http:NNN'|'network'|'parse'|<server msg> }
+export async function loadFsSkills(component, { isLocalLog } = {}) {
+  if (isLocalLog) return { ok: false, reason: 'local_log' };
+  const res = await _seqGuardedFetch(component, '_fsSkillsSeq', apiUrl('/api/skills'));
+  if (res.stale) return { ok: false, reason: 'stale' };
+  if (res.error) {
+    component.setState(prev => ({ _fsSkills: Array.isArray(prev._fsSkills) ? prev._fsSkills : false }));
+    return { ok: false, reason: res.errorKind || res.error.message || 'network' };
+  }
+  if (!res.ok || !res.data?.ok || !Array.isArray(res.data?.skills)) {
+    const reason = (res.data && res.data.error) || `http:${res.status}`;
+    component.setState(prev => ({ _fsSkills: Array.isArray(prev._fsSkills) ? prev._fsSkills : false }));
+    return { ok: false, reason };
+  }
+  component.setState({ _fsSkills: res.data.skills });
+  return { ok: true, skills: res.data.skills };
+}
+
+// 拉取项目入口 MEMORY.md。lazy-load 失败静默回退 false；用户主动刷新走 handleRefreshMemory（带 toast）。
+export async function loadProjectMemory(component) {
+  const res = await _seqGuardedFetch(component, '_memorySeq', apiUrl('/api/project-memory'));
+  if (res.stale) return;
+  if (res.error || !res.ok) { component.setState({ _memory: false }); return; }
+  component.setState({ _memory: res.data });
+}
+
+// 拉取 CLAUDE.md 候选清单。三态：null/false/[]/[{id,scope,tail,...}]。
+export async function loadClaudeMdList(component) {
+  const res = await _seqGuardedFetch(component, '_claudeMdSeq', apiUrl('/api/claude-md'));
+  if (res.stale) return;
+  if (res.error || !res.ok || !Array.isArray(res.data?.entries)) {
+    component.setState({ _claudeMd: false });
+    return;
+  }
+  component.setState({ _claudeMd: res.data.entries });
+}