cx-viewer 1.0.2 → 1.0.4

package/src/utils/sessionMerge.js

@@ -0,0 +1,290 @@
+// Wire format 协议详见 docs/WIRE_FORMAT.md（服务端 entry 形态 / 关键字段 / 已知特殊窗口）
+import { isPostClearCheckpoint, getMainAgentSessionKey } from './clearCheckpoint.js';
+
+/**
+ * 计算消息的轻量内容指纹，用于「反向锚点」对齐：以 `newMessages[0]` 的 fp 为锚，
+ * 从 `curMsgs` 末尾向头部反向扫，配合多块连续等价校验决定 append / no-op / rebuild。
+ *
+ * 关键点：
+ *  - tool_use / tool_result 用 API 强保证唯一的 id 作主键，永不碰撞。
+ *  - text / thinking 用 `length + first32 + last32` 三元组——比单纯 `slice(0, 64)`
+ *    抗碰撞强得多（同前缀 `<system-reminder>...` / `<command-name>/...` 不会再误命中），
+ *    但仍只触一次字符串切片，比哈希便宜。
+ *  - 保持纯函数 / 同步 / 无副作用——`mergeMainAgentSessions` 在流式热路径每条 SSE 都会调用。
+ */
+export function messageFingerprint(msg) {
+  // 异常隔离：用户提供的 msg.content 可能含恶意 getter（`{ get text() { throw } }`），
+  // 整段 try-catch 让单条 entry 异常不级联污染整个流式合并路径。返回空串作"匿名 fp"，
+  // 调用方 findReverseAnchor 看到 !fp0 || endsWith('|empty') 会拒当锚点，安全 fallback。
+  try {
+    if (!msg || !msg.role) return '';
+    const c = msg.content;
+    if (typeof c === 'string') return `${msg.role}|s|${c.length}|${c.slice(0, 32)}|${c.slice(-32)}`;
+    if (!Array.isArray(c) || c.length === 0) return `${msg.role}|empty`;
+    const blocks = c.map((b) => {
+      if (!b || typeof b !== 'object') return 'unknown';
+      if (b.type === 'tool_use') return `tu:${b.id || ''}:${b.name || ''}:${valueFingerprint(b.input)}`;
+      if (b.type === 'tool_result') return `tr:${b.tool_use_id || ''}:${b.is_error ? 1 : 0}:${valueFingerprint(b.content)}`;
+      if (b.type === 'text') {
+        const t = b.text || '';
+        return `t:${t.length}:${t.slice(0, 32)}:${t.slice(-32)}`;
+      }
+      if (b.type === 'thinking') {
+        const t = b.thinking || '';
+        return `th:${t.length}:${t.slice(0, 32)}:${t.slice(-32)}`;
+      }
+      return `${b.type || 'unknown'}:${valueFingerprint(b)}`;
+    });
+    return `${msg.role}|${blocks.join(';')}`;
+  } catch {
+    return '';
+  }
+}
+
+function valueFingerprint(value) {
+  try {
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    if (!text) return '';
+    return `${text.length}:${text.slice(0, 32)}:${text.slice(-32)}`;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 反向锚点搜索：在 `curMsgs` 中从末尾向头部找一个位置 p，使得
+ * `newMessages[0..L]` 的 fp 与 `curMsgs[p..p+L]` 的 fp **逐条**等价，
+ * 其中 L = min(newLen, curLen - p)。返回最右（即最贴近末尾）的命中。
+ *
+ * 设计选择：
+ *  - 反向扫起点为 `curLen - 1`，因为流式 / Plan Mode 窗口的真锚点几乎都贴近末尾，
+ *    反向首个 fp0 命中即真锚点的概率最高，避免命中靠前的 fp 碰撞误锚点。
+ *  - 多块连续等价校验：fp 加固后单条碰撞已罕见，多块连续碰撞概率近 0。
+ *  - 复杂度：单候选 O(L)，最坏 O(curLen·newLen)，典型 K<200。
+ *  - **fp 双向缓存**：newFps + curFpsCache 都缓存，让反向扫多候选场景下同一 curMsgs[p]
+ *    只算一次 fp（perf-security review P2，长 session 5000+/s SSE 路径节省 ~50% fp 调用）。
+ *
+ * @param {Array} newMsgs - 新消息数组
+ * @param {Array} curMsgs - 累积消息数组
+ * @param {Array<string>} [newFps] - 预计算的 newMsgs fp 数组缓存
+ * @param {Array<string>} [sharedCurFpsCache] - 调用方共享的 curMsgs fp 懒缓存（anchor miss 后
+ *   等长分支的对位比较可复用，避免对同一 curMsgs 重算 fp）
+ * @returns {{anchorIdx: number, overlapLen: number} | null}
+ */
+function findReverseAnchor(newMsgs, curMsgs, newFps, sharedCurFpsCache) {
+  const newLen = newMsgs.length;
+  const curLen = curMsgs ? curMsgs.length : 0;
+  if (newLen === 0 || curLen === 0) return null;
+  const fp0 = newFps ? newFps[0] : messageFingerprint(newMsgs[0]);
+  // 空内容 fp 不当锚点：role|empty 在 curMsgs 多处可能命中（连续多条空 content 消息），
+  // 反向扫到第一个 role|empty 会误锚到错误位置，导致 overlapLen 计算偏差。
+  // 若 newMsgs[0..N-1] 是"newMsgs[0] 空 + 后续有效"的混合序列：放弃以 newMsgs[0] 为锚点，
+  // 由调用方 fallback 路径（newLen<curLen → rebuild / newLen===curLen → 等长内容感知 /
+  // newLen>curLen → push tail）兜底；这条防线保的是"全 empty 新序列误复用旧 curMsgs 末尾"。
+  if (!fp0 || fp0.endsWith('|empty')) return null;
+  // curMsgs fp 懒缓存：sparse Array 仅记录被访问过的位置，避免上来就 map 整段长 session
+  // （curLen 可能 > 5000，但实际访问命中的 p 通常 < 50 个）。
+  const curFpsCache = sharedCurFpsCache || new Array(curLen);
+  const curFpAt = (idx) => {
+    let v = curFpsCache[idx];
+    if (v === undefined) {
+      v = messageFingerprint(curMsgs[idx]);
+      curFpsCache[idx] = v;
+    }
+    return v;
+  };
+  for (let p = curLen - 1; p >= 0; p--) {
+    if (curFpAt(p) !== fp0) continue;
+    const overlapLen = Math.min(newLen, curLen - p);
+    let ok = true;
+    for (let i = 1; i < overlapLen; i++) {
+      // 边界安全：i < overlapLen ≤ newLen ≤ newFps.length，必不越界（newFps 在调用处
+      // 用 newMessages.map 整体生成）。这里 newFps 仅作命中加速缓存，传入与否语义等价。
+      const newFpI = newFps ? newFps[i] : messageFingerprint(newMsgs[i]);
+      if (newFpI !== curFpAt(p + i)) {
+        ok = false; break;
+      }
+    }
+    if (ok) return { anchorIdx: p, overlapLen };
+    // 验证失败（fp 加固后罕见）→ 继续向左找下一候选；curFpsCache 让重叠候选区域复用 fp。
+  }
+  return null;
+}
+
+/**
+ * merge 入口守卫（KEEP IN SYNC: server/lib/delta-reconstructor.js 标记写入点）：
+ * 重建层标记的脏条目不得进入 mainAgentSessions 合并——
+ *  - `_staleReorder`：完成序倒置的乱序条目（内容已被更新条目取代）；
+ *  - `_reconstructBroken`：重建结果与 _totalMessageCount 不符且无法修复（拼接会翻倍/错位）；
+ *  - 批量路径额外跳过 `inProgress`：孤立占位条目的 body.input 是裸 delta 切片
+ *    （批量 reconstructEntries 不为 inProgress 重建全量），merge 会触发 rebuild 截断。
+ *    SSE 实时路径不拦 inProgress——watcher 增量重建器已为其拼出全量 input，
+ *    无 live-port 配置下"提问气泡请求时即显示"依赖这一行为。
+ * AppBase 的 SSE 与批量两个 merge 入口、以及单测共用此谓词，防三处逻辑漂移。
+ *
+ * @param {object} entry
+ * @param {object} [options]
+ * @param {boolean} [options.batch=false] - 批量（强刷/历史加载）路径
+ * @returns {boolean} true = 该条目不应参与 session 合并
+ */
+export function isMergeBlockedEntry(entry, options = {}) {
+  if (!entry) return true;
+  if (entry._staleReorder || entry._reconstructBroken) return true;
+  if (options.batch && entry.inProgress) return true;
+  return false;
+}
+
+/**
+ * 增量合并 mainAgent sessions。
+ *
+ * 核心算法：反向锚点对齐。以 `newMessages[0]` 为锚点，从 `lastSession.messages` 末尾
+ * 反向扫；命中后多块连续 fp 等价校验。三种结果：
+ *  - 命中且 overlapLen === newLen：流式 no-op / suffix subset，messages 引用稳定（保 WeakMap 缓存）。
+ *  - 命中且 overlapLen <  newLen：push `newMessages[overlapLen..]`，引用稳定。
+ *  - 未命中：newLen<curLen → rebuild（/compact summary）；newLen===curLen → 整段 append（Plan Mode 全新片段）；
+ *           newLen>curLen → 严格前缀扩展语义（push tail），fp 加固后真正存在重叠的窗口必被 anchor 命中。
+ *
+ * 顶部守卫（isPostClearCheckpoint / userId / transient filter）维持 1.6.245 行为不变。
+ *
+ * @param {Array} prevSessions
+ * @param {object} entry
+ * @param {object} [options]
+ * @param {boolean} [options.skipTransientFilter=false] - SSE 实时追加路径设为 true。
+ * @returns {Array}
+ */
+export function mergeMainAgentSessions(prevSessions, entry, options = {}) {
+  const newMessages = entry.body.input;
+  const newResponse = entry.response;
+  const userId = entry.body.metadata?.user_id || null;
+  const sessionKey = getMainAgentSessionKey(entry);
+
+  const entryTimestamp = entry.timestamp || null;
+
+  if (prevSessions.length === 0) {
+    return [{ userId, sessionKey, messages: newMessages, response: newResponse, entryTimestamp }];
+  }
+
+  const lastSession = prevSessions[prevSessions.length - 1];
+  const differentSessionKey = !!(sessionKey && lastSession.sessionKey && sessionKey !== lastSession.sessionKey);
+
+  const prevMsgCount = lastSession.messages ? lastSession.messages.length : 0;
+  const isNewConversation = prevMsgCount > 0 && newMessages.length < prevMsgCount * 0.5 && (prevMsgCount - newMessages.length) > 4;
+  const sameUser = userId !== null && userId === lastSession.userId;
+
+  // /clear 后的首个 checkpoint：始终是新会话起点。
+  // 同 device 下 sameUser 永远 true，否则会被下面的 same-session 分支吞掉；
+  // 也不能被 transient 过滤掉（即便 newMessages.length === 1）。
+  if (isPostClearCheckpoint(entry, prevMsgCount)) {
+    for (let i = 0; i < newMessages.length; i++) {
+      if (!newMessages[i]._timestamp) newMessages[i]._timestamp = entryTimestamp;
+    }
+    return [...prevSessions, { userId, sessionKey, messages: newMessages, response: newResponse, entryTimestamp }];
+  }
+
+  if (differentSessionKey) {
+    for (let i = 0; i < newMessages.length; i++) {
+      if (!newMessages[i]._timestamp) newMessages[i]._timestamp = entryTimestamp;
+    }
+    return [...prevSessions, { userId, sessionKey, messages: newMessages, response: newResponse, entryTimestamp }];
+  }
+
+  if (!options.skipTransientFilter && isNewConversation && newMessages.length <= 4 && prevMsgCount > 4) {
+    return prevSessions;
+  }
+
+  if (sameUser || (userId === lastSession.userId && !isNewConversation)) {
+    const curLen = prevMsgCount;
+    const newLen = newMessages.length;
+    if (!lastSession.messages) lastSession.messages = [];
+
+    // Stateful Codex projection detected an equal-length streaming update of
+    // the final assistant message (commonly partial → finalized tool args).
+    // Batch reload does not run AppBase's live in-place helper, so consume the
+    // signal here as well instead of treating the changed fingerprint as a new
+    // Plan-style window and appending a duplicate transcript.
+    if (entry._inPlaceReplaceDetected === true && newLen === curLen && newLen >= 2) {
+      const replacement = newMessages[newLen - 1];
+      if (!replacement._timestamp) replacement._timestamp = entryTimestamp;
+      lastSession.messages = [...lastSession.messages.slice(0, -1), replacement];
+      lastSession.response = newResponse;
+      lastSession.entryTimestamp = entryTimestamp;
+      if (sessionKey && !lastSession.sessionKey) lastSession.sessionKey = sessionKey;
+      return [...prevSessions];
+    }
+
+    // fp 缓存：预算 newMessages 的 fp 数组一次，传给 findReverseAnchor 避免多块连续校验
+    // 时反复调用 messageFingerprint（流式 5000+ 次/秒 SSE 路径节省 25-100ms 累计延迟）。
+    // curFpsCache 与 findReverseAnchor 共享：anchor miss 时等长分支的对位比较直接复用
+    // 反向扫已经算过的 curMsgs fp，零重复计算。
+    const newFps = newLen > 0 ? newMessages.map(messageFingerprint) : null;
+    const curFpsCache = new Array(curLen);
+    const anchor = findReverseAnchor(newMessages, lastSession.messages, newFps, curFpsCache);
+
+    if (anchor) {
+      const tailStart = anchor.overlapLen;
+      // tailStart === newLen：流式 no-op / suffix subset，messages 引用不动。
+      if (tailStart < newLen) {
+        for (let i = tailStart; i < newLen; i++) {
+          if (!newMessages[i]._timestamp) newMessages[i]._timestamp = entryTimestamp;
+          lastSession.messages.push(newMessages[i]);
+        }
+      }
+    } else if (newLen < curLen) {
+      // /compact summary 等真重建：替换 messages 引用。
+      for (let i = 0; i < newLen; i++) {
+        if (!newMessages[i]._timestamp) newMessages[i]._timestamp = entryTimestamp;
+      }
+      lastSession.messages = newMessages;
+    } else if (newLen === curLen) {
+      // 等长且 anchor 未命中：两种形态必须区分（docs/WIRE_FORMAT.md §3.1 / §3.7）——
+      // (a) Plan Mode 全新短窗口：内容与累积历史无关，整段 append 保留历史；
+      // (b) 同会话近似拷贝：末位原地替换 / 中段编辑，但服务端信号缺失（完成序倒置让无信号
+      //     的 stale checkpoint 后落盘、或旧日志无信号）。此形态整段 append 会让对话翻倍
+      //     （mainAgent 整段重复 bug 的翻倍终点），必须替换。
+      let aligned = 0;
+      // 严格多数（非简单 plurality）：对位 fp 相等数 ≥ floor(N/2)+1 才判近似拷贝→替换。
+      // 近似拷贝逐位几乎全等；Plan Mode 新窗口对位相等 ≈ 0。取严格多数是替换误判的
+      // 安全边界——N=2→需 2 条全等、N=3→2、N=4→3；宁可对"一半相同"的模糊形态保守
+      // append（残余形态：末位短暂陈旧），也不冒错杀新窗口历史的风险。调阈值前先想清
+      // 反例：近拷贝带 1 条中段编辑（N=2 时 1/2 不足多数 → append → 翻倍回归）。
+      const STRICT_MAJORITY = Math.floor(newLen / 2) + 1;
+      for (let i = 0; i < newLen && aligned < STRICT_MAJORITY; i++) {
+        let cfp = curFpsCache[i];
+        if (cfp === undefined) {
+          cfp = messageFingerprint(lastSession.messages[i]);
+          curFpsCache[i] = cfp;
+        }
+        if (newFps[i] === cfp) aligned++;
+      }
+      if (aligned >= STRICT_MAJORITY) {
+        // 近似拷贝 → 整段替换（等价于无信号版 in-place replace）。
+        // 引用更换会使 ChatView WeakMap 渲染缓存失效一次性重渲染，预期内。
+        for (let i = 0; i < newLen; i++) {
+          if (!newMessages[i]._timestamp) newMessages[i]._timestamp = entryTimestamp;
+        }
+        lastSession.messages = newMessages;
+      } else {
+        // Plan Mode 2-msg 全替换窗口，整段 append。
+        for (let i = 0; i < newLen; i++) {
+          if (!newMessages[i]._timestamp) newMessages[i]._timestamp = entryTimestamp;
+          lastSession.messages.push(newMessages[i]);
+        }
+      }
+    } else {
+      // newLen > curLen 且 anchor (单点 newMsgs[0]) 未命中：保守回退至"严格前缀扩展"语义——
+      // 只 push newMessages[curLen..]。fp 加固后真正存在重叠的窗口必被 anchor 命中走上面分支；
+      // 这里 anchor 未命中意味着确实无重叠（罕见，仅艺测/再快照场景），保留旧推 tail 行为防回归。
+      for (let i = curLen; i < newLen; i++) {
+        if (!newMessages[i]._timestamp) newMessages[i]._timestamp = entryTimestamp;
+        lastSession.messages.push(newMessages[i]);
+      }
+    }
+
+    lastSession.response = newResponse;
+    lastSession.entryTimestamp = entryTimestamp;
+    if (sessionKey && !lastSession.sessionKey) lastSession.sessionKey = sessionKey;
+    return [...prevSessions];
+  } else {
+    return [...prevSessions, { userId, sessionKey, messages: newMessages, response: newResponse, entryTimestamp }];
+  }
+}

package/src/utils/skillModalController.js

@@ -0,0 +1,111 @@
+// Skill 管理弹窗的「开关 / 永久删除」共享控制器。
+// AppHeader 与 Mobile 是同形态的类组件（同样的 state._skillsModal / state._fsSkills、
+// this.setState、this.reloadFsSkills()），原本各持一份逐字相同的 handler，极易漂移
+// （评审已发现 Mobile 漏了一条镜像注释）。这里抽成以组件实例为 host 的纯函数，两端只留一行委派。
+// ImSkillsModal 是函数组件 + IM 端点 + _tr 文案，状态形态不同，刻意不并入。
+import { message } from 'antd';
+import { apiUrl } from './apiUrl';
+import { t } from '../i18n';
+import { skillKey, skillOrderKey } from './skillsParser';
+
+// 把 reload 的权威结果按当前显示顺序（skillOrderKey 保位）合并回 _skillsModal.skills。
+// skillOrderKey 只取 source+name（开关/删除都不改它），所以行原地不动；modal 没见过的新条目排末尾。
+export function mergePreservingOrder(prevSkills, resultSkills) {
+  const orderMap = new Map(prevSkills.map((s, i) => [skillOrderKey(s), i]));
+  return [...resultSkills].sort((a, b) => {
+    const ai = orderMap.get(skillOrderKey(a));
+    const bi = orderMap.get(skillOrderKey(b));
+    if (ai === undefined && bi === undefined) return 0;
+    if (ai === undefined) return 1;
+    if (bi === undefined) return -1;
+    return ai - bi;
+  });
+}
+
+// 切换 skill 启用状态：乐观翻 Switch + 失败回滚 + reload 保位对齐。
+export async function handleSkillToggle(host, skill) {
+  const key = skillKey(skill);
+  if (host.state._skillsModal?.toggling?.has(key)) return;
+  const enable = !skill.enabled;
+  // 用 skillKey（含 path）匹配——同名同 source 的重复两份路径不同，只翻被点那行，不牵连孪生。
+  const flipEnabled = (target) => (s) => (skillKey(s) === key) ? { ...s, enabled: target } : s;
+  host.setState(prev => {
+    const next = new Set(prev._skillsModal.toggling); next.add(key);
+    return { _skillsModal: { ...prev._skillsModal, toggling: next, skills: prev._skillsModal.skills.map(flipEnabled(enable)) } };
+  });
+  try {
+    const r = await fetch(apiUrl('/api/skills/toggle'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ source: skill.source, name: skill.name, path: skill.path, enabled: skill.enabled, enable }),
+    });
+    const data = await r.json();
+    if (!r.ok) {
+      host.setState(prev => ({ _skillsModal: { ...prev._skillsModal, skills: prev._skillsModal.skills.map(flipEnabled(!enable)) } }));
+      if (data.code === 'DUPLICATE') message.error(t('ui.skillToggleDuplicate', { name: skill.name }));
+      else message.error(t('ui.skillToggleFailed', { reason: data.error || 'unknown' }));
+      return;
+    }
+    // 乐观翻 _fsSkills（popover chip 源）里这条的 enabled——reload 失败也能立即反映用户动作；
+    // reload 成功会用权威数据覆盖。
+    host.setState(prev => ({
+      _fsSkills: Array.isArray(prev._fsSkills)
+        ? prev._fsSkills.map(s => (skillKey(s) === key) ? { ...s, enabled: enable } : s)
+        : prev._fsSkills,
+    }));
+    const result = await host.reloadFsSkills();
+    if (result.ok) {
+      host.setState(prev => ({ _skillsModal: { ...prev._skillsModal, skills: mergePreservingOrder(prev._skillsModal.skills, result.skills) } }));
+    }
+  } catch (e) {
+    host.setState(prev => ({ _skillsModal: { ...prev._skillsModal, skills: prev._skillsModal.skills.map(flipEnabled(!enable)) } }));
+    message.error(t('ui.skillToggleFailed', { reason: e.message }));
+  } finally {
+    host.setState(prev => {
+      const next = new Set(prev._skillsModal.toggling); next.delete(key);
+      return { _skillsModal: { ...prev._skillsModal, toggling: next } };
+    });
+  }
+}
+
+// 永久删除单个 skill：成功后乐观移除该行 + reload 保位对齐。
+// reload 合并回 _skillsModal.skills 很关键：否则删掉「重复对」其中一份后，存活那行仍带旧
+// duplicate ⚠ 徽标，要等关弹窗重开才消失（listSkills 重算后该标记自然清掉）。
+export async function handleSkillDelete(host, skill) {
+  const key = skillKey(skill);
+  // 复用 toggling Set 作「该行操作进行中」标记：防二次确认后的连点重入，
+  // 并让 SkillsManagerModal 在删除期间给删除按钮转圈 + 禁用同行 Switch（与 toggle 一致的忙态反馈）。
+  if (host.state._skillsModal?.toggling?.has(key)) return;
+  host.setState(prev => {
+    const next = new Set(prev._skillsModal.toggling); next.add(key);
+    return { _skillsModal: { ...prev._skillsModal, toggling: next } };
+  });
+  try {
+    const r = await fetch(apiUrl('/api/skills/delete'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ source: skill.source, name: skill.name, path: skill.path, enabled: skill.enabled }),
+    });
+    const data = await r.json().catch(() => ({}));
+    if (!r.ok) {
+      message.error(t('ui.skillDeleteFailed', { reason: data.error || 'unknown' }));
+      return;
+    }
+    message.success(t('ui.skillDeleteSuccess', { name: skill.name }));
+    host.setState(prev => ({
+      _skillsModal: { ...prev._skillsModal, skills: (prev._skillsModal.skills || []).filter(s => skillKey(s) !== key) },
+      _fsSkills: Array.isArray(prev._fsSkills) ? prev._fsSkills.filter(s => skillKey(s) !== key) : prev._fsSkills,
+    }));
+    const result = await host.reloadFsSkills();
+    if (result.ok) {
+      host.setState(prev => ({ _skillsModal: { ...prev._skillsModal, skills: mergePreservingOrder(prev._skillsModal.skills, result.skills) } }));
+    }
+  } catch (e) {
+    message.error(t('ui.skillDeleteFailed', { reason: e.message }));
+  } finally {
+    host.setState(prev => {
+      const next = new Set(prev._skillsModal.toggling); next.delete(key);
+      return { _skillsModal: { ...prev._skillsModal, toggling: next } };
+    });
+  }
+}

package/src/utils/skillsParser.js

@@ -0,0 +1,116 @@
+// Codex 硬编码的 builtin skill 名单（本地无文件、不可禁用）。
+// 与 server/lib/skills-api.js 的 BUILTIN_NAMES 保持一致；前端用于 popover chip 过滤。
+export const BUILTIN_SKILL_NAMES = new Set([
+  'update-config', 'keybindings-help', 'simplify', 'fewer-permission-prompts',
+  'loop', 'schedule', 'codex-api', 'init', 'review', 'security-review',
+]);
+
+// 把 /api/skills 返回的 skill 对象映射到 Codex system-reminder 里的显示名。
+// 插件 skill: `<pluginShort>:<skillDir>`；其它源用裸名。pluginName 形如 `short@marketplace`。
+export function skillToDisplayName(s) {
+  if (!s || typeof s.name !== 'string') return '';
+  if (s.source === 'plugin' && typeof s.pluginName === 'string' && s.pluginName.includes('@')) {
+    const short = s.pluginName.split('@')[0];
+    if (short) return `${short}:${s.name}`;
+  }
+  return s.name;
+}
+
+// Skill 的稳定唯一标识——用于开关弹窗的 toggling Set key、乐观更新匹配、reload 排序 orderMap、
+// 以及 React 渲染 key。可切换 skill（user/project）用其磁盘 path：同名两份分别住在 skills/ 与
+// skills-skip/，路径天然不同，避免「同名同 source」共用 key 导致两行串台（一起转圈/一起翻转）。
+// builtin（path:null）回落 source-name（名字唯一），仍稳定，供只读 chip 的排序兜底。
+export function skillKey(s) {
+  return (s && s.path) ? s.path : `${s?.source}-${s?.name}`;
+}
+
+// 跨「开关」稳定的标识——只用 source+name（开关把 skill 在 skills/ ↔ skills-skip/ 间搬，path 会变，
+// 但 source/name 不变）。专用于「toggle 后保位」：开关一个 skill 后它在列表里原地不动，不会因为 path
+// 变了而被 orderMap 当成新条目甩到末尾。与 skillKey（含 path、用于重复态去重）刻意不同。
+export function skillOrderKey(s) {
+  return `${s?.source}-${s?.name}`;
+}
+
+// 弹窗「默认排序」——仅在打开面板时套用（开关期间不重排，避免抖动让用户找不到 skill）。
+// 规则：项目级(project) 排在用户级(user) 之前，其余源其后；同源按名字 localeCompare 保证确定性
+// （彻底消除每次刷新 readdir 顺序漂移导致的乱序）。返回新数组，不改入参。
+const SKILL_SOURCE_RANK = { project: 0, user: 1, plugin: 2, builtin: 3 };
+export function sortSkillsDefault(skills) {
+  if (!Array.isArray(skills)) return [];
+  return [...skills].sort((a, b) => {
+    const ra = SKILL_SOURCE_RANK[a?.source] ?? 9;
+    const rb = SKILL_SOURCE_RANK[b?.source] ?? 9;
+    if (ra !== rb) return ra - rb;
+    return String(a?.name || '').localeCompare(String(b?.name || ''));
+  });
+}
+
+// 把 /api/skills 的权威结果与历史 system-reminder 解析结果合并为「当前在用」chip 列表。
+// - fsSkills=null  → 返回 null，由调用方回退到历史解析
+// - 只保留 enabled=true 且非 builtin 的条目
+// - description 优先 fs（SKILL.md frontmatter），缺失时回退历史 system-reminder 的 desc，再缺则空串
+// - 按显示名去重（user/project 同名只保留最后一条；plugin 因为带前缀天然不冲突）
+export function mergeActiveSkills(fsSkills, historicalSkills) {
+  if (!Array.isArray(fsSkills)) return null;
+  const descMap = new Map((historicalSkills || []).map(s => [s.name, s.description]));
+  const out = new Map();
+  for (const s of fsSkills) {
+    if (!s || !s.enabled || s.source === 'builtin') continue;
+    const name = skillToDisplayName(s);
+    if (!name || BUILTIN_SKILL_NAMES.has(name)) continue;
+    out.set(name, { name, description: s.description || descMap.get(name) || '' });
+  }
+  return [...out.values()];
+}
+
+// 从 <system-reminder> 内部文本里抽出 skills 列表。
+// 识别 header 句 "skills are available for use with the Skill tool" 后，按行扫描
+// `- <name>: <desc>` 格式；name 内允许冒号（plugin:foo / skill-creator:skill-creator
+// 都按原样保留），按首个 ': '（冒号+空格）切分。description 可跨多行，遇空行 / 下一个 `- `
+// flush；遇非 dash 非续行非空文本视为列表结束。
+//
+// 纯函数，无传递依赖 —— 可直接被 node --test 导入（避免 src/utils/contentFilter.js
+// 里缺 .js 后缀的 import 引起的 Node ESM resolver 失败）。
+export function parseLoadedSkills(innerText) {
+  if (typeof innerText !== 'string') return [];
+  const headerIdx = innerText.indexOf('skills are available for use with the Skill tool');
+  if (headerIdx < 0) return [];
+  const lineStart = innerText.indexOf('\n', headerIdx);
+  if (lineStart < 0) return [];
+  const tail = innerText.slice(lineStart + 1);
+  const lines = tail.split(/\r?\n/);
+  const skills = [];
+  let current = null;
+  const flush = () => {
+    if (current && current.name) skills.push(current);
+    current = null;
+  };
+  for (const line of lines) {
+    if (/^-\s+/.test(line)) {
+      flush();
+      const rest = line.replace(/^-\s+/, '');
+      const colonSpaceIdx = rest.indexOf(': ');
+      if (colonSpaceIdx > 0) {
+        current = {
+          name: rest.slice(0, colonSpaceIdx).trim(),
+          description: rest.slice(colonSpaceIdx + 2).trim(),
+        };
+      } else {
+        const name = rest.replace(/:\s*$/, '').trim();
+        current = { name, description: '' };
+      }
+    } else if (current && line.trim()) {
+      // 续行：保留换行符。弹窗用 white-space: pre-wrap 渲染，
+      // 让多段落 description（如 test-spec-designer 的触发场景/关键词）保持可读的结构。
+      current.description = current.description
+        ? current.description + '\n' + line.trim()
+        : line.trim();
+    } else if (!line.trim()) {
+      flush();
+    } else {
+      break;
+    }
+  }
+  flush();
+  return skills;
+}

package/src/utils/slashCommandLabels.js

@@ -0,0 +1,80 @@
+import { t } from '../i18n.js';
+
+// 命令清单与 Codex CLI upstream 公开 slash 命令对齐;upstream 增删命令时
+// 需手动同步本表 + src/i18n.js 的 "ui.slashCommand.*" 翻译块。未在表中的命令
+// (含用户自定义 ~/.codex/commands/*.md)→ 返回 null → 调用方回落到原文渲染。
+// 命令大小写敏感(与 CLI 保持一致),exact-match 不做大小写规约。
+// 翻译歧义点见 src/i18n.js "ui.slashCommand.*" 块顶部注释(单一信息源)。
+const COMMAND_KEYS = Object.freeze({
+  '/clear': 'ui.slashCommand.clear',
+  '/compact': 'ui.slashCommand.compact',
+  '/theme': 'ui.slashCommand.theme',
+  '/cost': 'ui.slashCommand.cost',
+  '/usage': 'ui.slashCommand.usage',
+  '/context': 'ui.slashCommand.context',
+  '/model': 'ui.slashCommand.model',
+  '/effort': 'ui.slashCommand.effort',
+  '/login': 'ui.slashCommand.login',
+  '/logout': 'ui.slashCommand.logout',
+  '/status': 'ui.slashCommand.status',
+  '/help': 'ui.slashCommand.help',
+  '/init': 'ui.slashCommand.init',
+  '/agents': 'ui.slashCommand.agents',
+  '/config': 'ui.slashCommand.config',
+  '/memory': 'ui.slashCommand.memory',
+  '/permissions': 'ui.slashCommand.permissions',
+  '/hooks': 'ui.slashCommand.hooks',
+  '/plugins': 'ui.slashCommand.plugins',
+  '/release-notes': 'ui.slashCommand.releaseNotes',
+  '/upgrade': 'ui.slashCommand.upgrade',
+  '/bug': 'ui.slashCommand.bug',
+  '/doctor': 'ui.slashCommand.doctor',
+  '/mcp': 'ui.slashCommand.mcp',
+  '/vim': 'ui.slashCommand.vim',
+  '/export': 'ui.slashCommand.export',
+  '/pr-comments': 'ui.slashCommand.prComments',
+  '/review': 'ui.slashCommand.review',
+  '/security-review': 'ui.slashCommand.securityReview',
+  '/ide': 'ui.slashCommand.ide',
+  '/resume': 'ui.slashCommand.resume',
+  '/terminal-setup': 'ui.slashCommand.terminalSetup',
+  '/migrate-installer': 'ui.slashCommand.migrateInstaller',
+});
+
+// 裸命令名(如 "/model")+ 可选参数(如 "/model opus")。
+// 参数前只允许 ASCII 空格/制表符 — 避免 U+2028/U+2029 等异常空白被
+// 当成参数分隔符绕过多行守卫。
+const COMMAND_PATTERN = /^(\/[a-z][a-z0-9-]*)([ \t]+.*)?$/;
+// 拒任意 Unicode 换行(LF / CR / U+2028 LINE SEP / U+2029 PARAGRAPH SEP)。
+const ANY_LINEBREAK = new RegExp('[\\n\\r\\u2028\\u2029]');
+// bidi-control(U+202A LRE / U+202B RLE / U+202C PDF / U+202D LRO / U+202E RLO /
+// U+2066 LRI / U+2067 RLI / U+2068 FSI / U+2069 PDI):进入气泡文本会翻转剩余
+// 字符视觉方向,撕裂气泡/相邻消息布局。在拼接 rest 前 strip 掉。
+const BIDI_CONTROL = new RegExp('[\\u202A-\\u202E\\u2066-\\u2069]', 'g');
+
+// 内部 matcher:返回 { cmd, rest } 或 null。两个 export 共享同一套校验逻辑,
+// 不引入第二份 regex 路径。
+function matchCommand(text) {
+  if (typeof text !== 'string') return null;
+  if (ANY_LINEBREAK.test(text)) return null;
+  const trimmed = text.trim();
+  const match = COMMAND_PATTERN.exec(trimmed);
+  if (!match) return null;
+  const cmd = match[1];
+  if (!COMMAND_KEYS[cmd]) return null;
+  return { cmd, rest: (match[2] || '').replace(BIDI_CONTROL, '') };
+}
+
+export function getSlashCommandLabel(text) {
+  const m = matchCommand(text);
+  if (!m) return null;
+  const label = t(COMMAND_KEYS[m.cmd]);
+  return m.rest ? `${label}${m.rest}` : label;
+}
+
+// 返回裸命令(如 "/model"),用于 Tooltip 等次要展示位,避免参数(可能含
+// /login <token> 等敏感数据)在 hover/title 处被泄漏。
+export function getSlashCommandTooltip(text) {
+  const m = matchCommand(text);
+  return m ? m.cmd : null;
+}