cc-viewer 1.6.348 → 1.7.1

package/src/utils/voicePackPlayer.js

@@ -0,0 +1,233 @@
+// Singleton voice-pack playback for ApprovalModal / AppBase / Mobile.
+//
+// Responsibilities:
+//   1. Resolve event → URL based on per-event binding ('default' | <uuid> | null).
+//   2. Serialise playback through one shared <Audio> element (no overlap when
+//      multiple lifecycle events fire simultaneously —).
+//   3. Honor a per-event cooldown so noisy events (turnEnd) don't spam the user.
+//   4. Survive autoplay-policy block: play() rejection falls back to Web Audio
+//      chime so the user still gets *some* signal even before they've interacted.
+//   5. Keep a separate Audio element for Settings preview so previews don't
+//      compete with live event playback.
+//
+// Pure module state — one queue per browsing context. Multi-tab Electron each
+// have their own module instance (different webContents = different module);
+// that's fine: each tab unlocks its own audio independently per browser policy.
+
+import { apiUrl } from './apiUrl.js';
+import { BUNDLED_PACK_IDS } from '../../server/lib/voice-pack-events.js';
+
+// Mirror BUNDLED_PACK_IDS into a Set for O(1) lookup in the hot URL-building
+// path. Frozen array ↔ Set conversion at module load is fine; the source list
+// is itself frozen so the Set can't drift.
+const BUNDLED_PACK_ID_SET = new Set(BUNDLED_PACK_IDS);
+
+let mainAudio = null;
+let previewAudio = null;
+const queue = [];
+let playing = false;
+let unlocked = false;
+const lastFireAt = new Map(); // eventKey → ts
+const lastDedupeKey = new Map(); // eventKey → caller-supplied dedupe key
+
+function urlForBinding(eventKey, binding) {
+  const head = '/api/voice-pack/audio';
+  // Bundled packs route as /<packId>/<eventKey>; user uploads as /<uuid>.
+  // null / undefined binding falls back to 'default' so the chime-fallback layer
+  // still gets a real URL to attempt (404 → chime is handled in startPlay).
+  // The Set check (not equality with 'default') is critical — without it,
+  // binding='sanguo' would route to /api/voice-pack/audio/sanguo (no event
+  // suffix), hit the uuid branch, fail isValidId, and 404 → silent chime.
+  const packId = (!binding) ? 'default' : binding;
+  const path = BUNDLED_PACK_ID_SET.has(packId)
+    ? `${head}/${packId}/${encodeURIComponent(eventKey)}`
+    : `${head}/${encodeURIComponent(binding)}`;
+  // apiUrl injects the ?token=... LAN auth query when present — same path other API calls use.
+  return apiUrl(path);
+}
+
+function getMainAudio() {
+  if (mainAudio) return mainAudio;
+  mainAudio = new Audio();
+  mainAudio.preload = 'auto';
+  mainAudio.addEventListener('ended', advanceQueue);
+  // 'error' also drains so a 404 / decode failure doesn't deadlock the queue.
+  mainAudio.addEventListener('error', () => { playChimeFallback(); advanceQueue(); });
+  return mainAudio;
+}
+
+let _webAudioCtx = null;
+// Two-tone chime — exported so ApprovalModal can also use it for the legacy
+// `soundEnabled` path. Single Web Audio context lives here (was duplicated
+// across player + ApprovalModal until they were deduped here).
+export function playChimeFallback() {
+  try {
+    const Ctx = window.AudioContext || window.webkitAudioContext;
+    if (!Ctx) return;
+    if (!_webAudioCtx) _webAudioCtx = new Ctx();
+    const ctx = _webAudioCtx;
+    const now = ctx.currentTime;
+    const osc = ctx.createOscillator();
+    const gain = ctx.createGain();
+    osc.type = 'sine';
+    osc.frequency.setValueAtTime(660, now);
+    osc.frequency.linearRampToValueAtTime(880, now + 0.18);
+    gain.gain.setValueAtTime(0, now);
+    gain.gain.linearRampToValueAtTime(0.18, now + 0.02);
+    gain.gain.exponentialRampToValueAtTime(0.0001, now + 0.24);
+    osc.connect(gain).connect(ctx.destination);
+    osc.start(now);
+    osc.stop(now + 0.26);
+  } catch { /* ignore */ }
+}
+
+function advanceQueue() {
+  playing = false;
+  const next = queue.shift();
+  if (next) startPlay(next);
+}
+
+function startPlay({ url, volume }) {
+  const audio = getMainAudio();
+  playing = true;
+  try {
+    audio.src = url;
+    audio.volume = Math.max(0, Math.min(1, volume));
+    const p = audio.play();
+    if (p && typeof p.catch === 'function') {
+      p.catch(() => {
+        // Autoplay blocked OR audio 404 — fire chime so user is at least notified,
+        // and immediately drain so we don't sit on a poisoned queue.
+        playChimeFallback();
+        advanceQueue();
+      });
+    }
+  } catch {
+    playChimeFallback();
+    advanceQueue();
+  }
+}
+
+// Per-event cooldown (review: kept as a module constant, not user-configurable.
+// The previous prefs.cooldownMs override was phantom config — neither persisted
+// nor exposed in Settings — so it was removed to avoid half-built
+// flexibility users couldn't actually use).
+// SUNSET-MARKER: ccv-turn-end-debounce
+// Frontend caller-side cooldown，作为 server 端 trailing debounce 漏掉时的兜底二保险
+// （SSE 重连重发、server 罕见广播失序等）。**与 server `CCV_TURN_END_DEBOUNCE_MS`
+// 自动对齐**：AppBase.jsx 监听 SSE `server_config` 事件并调 `setTurnEndCooldownMs` 注入
+// server 实际生效的 debounce 值，无需运维手工同步两边常量。
+const COOLDOWN_MS = {
+  turnEnd: 10_000,
+};
+
+/**
+ * Update the turnEnd caller-side cooldown at runtime — called by AppBase on
+ * receipt of `server_config` SSE event. Keeps frontend in sync with the server's
+ * `CCV_TURN_END_DEBOUNCE_MS` env override without redeploy.
+ * Mirrors server clamp [100, 60000] so a malformed/tampered server_config payload
+ * (n=0 disables cooldown → voice spam) can't kill the二保险.
+ */
+export function setTurnEndCooldownMs(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n) || n < 100 || n > 60_000) {
+    try { console.warn(`[voicePack] setTurnEndCooldownMs(${ms}) out of [100,60000]; keeping`, COOLDOWN_MS.turnEnd); } catch {}
+    return;
+  }
+  COOLDOWN_MS.turnEnd = n;
+}
+
+// Main entry point.
+//   eventKey:  'planApproval' | 'askQuestion' | 'turnEnd'
+//   prefs:     prefs.approvalModal.voicePack — { enabled, volume, events: { ... } }
+//   opts.dedupeKey:  optional string; second call with same key for same event is ignored
+export function playEvent(eventKey, prefs, opts = {}) {
+  if (typeof window === 'undefined') return false;
+  if (!prefs || prefs.enabled !== true) return false;
+  const binding = prefs.events && prefs.events[eventKey];
+  if (binding === null || binding === undefined) return false; // event disabled
+
+  // Per-event cooldown (constants only — no prefs override; see COOLDOWN_MS).
+  const cooldown = COOLDOWN_MS[eventKey] || 0;
+  if (cooldown > 0) {
+    const last = lastFireAt.get(eventKey) || 0;
+    if (Date.now() - last < cooldown) return false;
+  }
+
+  // Caller-side dedupe (e.g. same approval modal kind re-rendering shouldn't
+  // refire). Per-event key isolation so concurrent kinds don't suppress each other.
+  if (opts.dedupeKey) {
+    if (lastDedupeKey.get(eventKey) === opts.dedupeKey) return false;
+    lastDedupeKey.set(eventKey, opts.dedupeKey);
+  }
+
+  lastFireAt.set(eventKey, Date.now());
+  const url = urlForBinding(eventKey, binding);
+  const volume = typeof prefs.volume === 'number' ? Math.max(0, Math.min(1, prefs.volume)) : 0.3;
+
+  if (playing) {
+    queue.push({ url, volume });
+  } else {
+    startPlay({ url, volume });
+  }
+  return true;
+}
+
+// Settings preview — independent of the live queue, so previewing while a
+// real event is playing doesn't either kill the live audio or wait behind it.
+export function previewEvent(eventKey, prefs) {
+  if (typeof window === 'undefined') return Promise.resolve();
+  if (!previewAudio) previewAudio = new Audio();
+  try {
+    previewAudio.pause();
+    previewAudio.currentTime = 0;
+  } catch { /* ignore */ }
+  const binding = (prefs?.events && prefs.events[eventKey]) || 'default';
+  previewAudio.src = urlForBinding(eventKey, binding);
+  previewAudio.volume = typeof prefs?.volume === 'number' ? Math.max(0, Math.min(1, prefs.volume)) : 0.3;
+  const p = previewAudio.play();
+  if (p && typeof p.catch === 'function') {
+    return p.catch(() => { playChimeFallback(); });
+  }
+  return Promise.resolve();
+}
+
+export function stopPreview() {
+  if (previewAudio) {
+    try { previewAudio.pause(); previewAudio.currentTime = 0; } catch { /* ignore */ }
+  }
+}
+
+// Call from a click / keypress handler (Settings open is a good spot) to satisfy
+// Chrome/Safari/Firefox autoplay policy. Plays a silent 1-sample WAV so the
+// audio element is "blessed" for programmatic playback for the rest of the tab's life.
+export function unlockAudio() {
+  if (unlocked) return Promise.resolve(true);
+  if (typeof window === 'undefined') return Promise.resolve(false);
+  try {
+    const audio = getMainAudio();
+    audio.volume = 0;
+    audio.src = 'data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=';
+    const p = audio.play();
+    if (p && typeof p.then === 'function') {
+      return p.then(() => { unlocked = true; return true; }).catch(() => false);
+    }
+    unlocked = true;
+    return Promise.resolve(true);
+  } catch { return Promise.resolve(false); }
+}
+
+// Test hook — reset module state between unit tests. **Do not call from app code.**
+// Exported as a named function so an "unused exports" linter can see it's referenced
+// by test/voice-pack-player.test.js (— without this, a future cleanup pass
+// could mistake it for dead code).
+export function _resetForTests() {
+  mainAudio = null;
+  previewAudio = null;
+  queue.length = 0;
+  playing = false;
+  unlocked = false;
+  lastFireAt.clear();
+  lastDedupeKey.clear();
+  _webAudioCtx = null;
+}

package/src/utils/webSearchGrouping.js

@@ -0,0 +1,111 @@
+/**
+ * Web search rendering helpers.
+ *
+ * Anthropic 的 server-side web_search 工具在 assistant message 的 content 数组里
+ * 直接放两个兄弟块：server_tool_use（搜索发起）+ web_search_tool_result（结果）。
+ * 紧随其后的 text 块（含带 citations 的）是模型基于结果生成的综合回复。
+ *
+ * 本文件提供：
+ *   - extractWebSearchGroups(content): 识别 [server_tool_use, web_search_tool_result, ...synthesis text]
+ *     子序列，返回 groups + content 全局 index 的 consumedIndices Set。
+ *   - safeHref(url): URL 协议白名单（仅 http/https），防 javascript:/data:/file:// 协议 XSS。
+ *   - getHostname(url): try/catch 包装的 new URL(url).hostname。
+ *
+ * 设计上故意做成纯 JS（无 React/CSS 依赖），让 Node test runner 能直接 import。
+ */
+
+export function extractWebSearchGroups(content) {
+  const groups = [];
+  const consumedIndices = new Set();
+
+  if (!Array.isArray(content) || content.length === 0) {
+    return { groups, consumedIndices };
+  }
+
+  for (let i = 0; i < content.length; i++) {
+    const block = content[i];
+    if (!block || typeof block !== 'object') continue;
+
+    if (block.type === 'server_tool_use') {
+      let resultIdx = -1;
+      for (let j = i + 1; j < content.length; j++) {
+        const b = content[j];
+        if (!b || typeof b !== 'object') continue;
+        if (b.type === 'thinking') continue;
+        if (b.type === 'web_search_tool_result' && b.tool_use_id === block.id) {
+          resultIdx = j;
+        }
+        break;
+      }
+
+      if (resultIdx === -1) {
+        groups.push({
+          serverToolUseIndex: i,
+          serverToolUse: block,
+          webSearchResultIndex: -1,
+          webSearchResult: null,
+          synthesisTextIndices: [],
+        });
+        consumedIndices.add(i);
+        continue;
+      }
+
+      const synthesisIndices = [];
+      for (let k = resultIdx + 1; k < content.length; k++) {
+        const b = content[k];
+        if (!b || typeof b !== 'object') break;
+        if (b.type === 'text') {
+          synthesisIndices.push(k);
+          continue;
+        }
+        if (b.type === 'thinking') break;
+        if (b.type === 'tool_use' || b.type === 'server_tool_use') break;
+        break;
+      }
+
+      groups.push({
+        serverToolUseIndex: i,
+        serverToolUse: block,
+        webSearchResultIndex: resultIdx,
+        webSearchResult: content[resultIdx],
+        synthesisTextIndices: synthesisIndices,
+      });
+      consumedIndices.add(i);
+      consumedIndices.add(resultIdx);
+      for (const k of synthesisIndices) consumedIndices.add(k);
+    } else if (block.type === 'web_search_tool_result') {
+      if (consumedIndices.has(i)) continue;
+      groups.push({
+        serverToolUseIndex: -1,
+        serverToolUse: null,
+        webSearchResultIndex: i,
+        webSearchResult: block,
+        synthesisTextIndices: [],
+      });
+      consumedIndices.add(i);
+    }
+  }
+
+  return { groups, consumedIndices };
+}
+
+const SAFE_PROTOCOLS = new Set(['http:', 'https:']);
+
+export function safeHref(url) {
+  if (typeof url !== 'string' || !url) return null;
+  try {
+    const u = new URL(url);
+    return SAFE_PROTOCOLS.has(u.protocol) ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+export function getHostname(url) {
+  if (typeof url !== 'string' || !url) return '';
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return url.length > 40 ? url.slice(0, 40) + '…' : url;
+  }
+}

package/src/utils/workflowFormat.js

@@ -0,0 +1,52 @@
+/**
+ * Workflow 面板共享格式化工具（WorkflowPanel 与 WorkflowLiveHud 共用，纯函数无 CSS 依赖）。
+ */
+
+export const TERMINAL_STATES = new Set(['done', 'completed', 'failed', 'error', 'cancelled', 'skipped']);
+
+// 工作流状态 → i18n key（缺失时调用方回退到原始 status 字符串）。
+export const STATUS_KEYS = {
+  running: 'ui.workflow.status.running',
+  finishing: 'ui.workflow.status.finishing',
+  completed: 'ui.workflow.status.completed',
+  failed: 'ui.workflow.status.failed',
+  paused: 'ui.workflow.status.paused',
+  cancelled: 'ui.workflow.status.cancelled',
+};
+
+export function fmtDuration(ms) {
+  if (typeof ms !== 'number' || ms < 0) return '';
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rem = s % 60;
+  return rem ? `${m}m ${rem}s` : `${m}m`;
+}
+
+export function fmtTokens(n) {
+  if (typeof n !== 'number' || n <= 0) return '0';
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(n);
+}
+
+export function isRunning(state) {
+  return !TERMINAL_STATES.has(state);
+}
+
+export function stateGlyph(state) {
+  if (state === 'done' || state === 'completed') return '✓';
+  if (state === 'failed' || state === 'error') return '✗';
+  if (state === 'queued') return '○';
+  return '●';
+}
+
+// 甘特完成条按阶段着色：柔和、明暗主题皆可读的循环色相调色板。
+// 失败/运行中/排队仍走语义色（红/主色脉冲/灰），不取这里的值。
+const PHASE_HUES = [206, 265, 150, 32, 322, 188, 96, 0];
+
+export function phaseColor(phaseIndex) {
+  const n = PHASE_HUES.length;
+  const i = typeof phaseIndex === 'number' && phaseIndex >= 0 ? phaseIndex : 0;
+  const h = PHASE_HUES[i % n];
+  return `hsl(${h}, 48%, 50%)`;
+}

package/src/utils/workflowRuns.js

@@ -0,0 +1,118 @@
+/**
+ * 从当前会话的 requests 提取所有 Workflow(UltraCode)run。
+ *
+ * 数据源:tool_result 块在 requests[i].body.messages 的 **user 轮**(与 toolResultBuilder.js
+ * 的全局索引扫描同源,见其 role==='user' 分支)。每个 Workflow 工具的后台启动返回文本
+ * 原生携带 Task ID / Run ID / Transcript dir 路径(含 sessionId),由 parseWorkflowFromText 解析,
+ * 无需服务端 _ccvWorkflow 注入——历史日志(含旧日志)同样可枚举。
+ *
+ * 镜像 teamSessionParser.js 的 extractTeamSessions 模式:纯函数、无副作用,便于 node --test 直接 import。
+ */
+
+import { extractToolResultText, parseWorkflowFromText } from './toolResultCore.js';
+
+const SUMMARY_RE = /Summary:\s*(.+)/;
+
+/**
+ * 枚举 requests 里的全部 workflow run,按 taskId 主键去重(回填缺失的 runId/sessionId),
+ * 按最早出现时间倒序(最新在前)。
+ *
+ * @param {Array} requests - ChatView 的 requests 数组(每项含 timestamp 与 body.messages)
+ * @returns {Array<{ runId: string|null, taskId: string|null, sessionId: string|null,
+ *                    resultText: string, timestamp: any, summary: string|null }>}
+ */
+export function extractWorkflowRuns(requests) {
+  if (!Array.isArray(requests)) return [];
+
+  // 以「逻辑 run 键」聚合:taskId 优先(launch 文本必有、1:1 对应一次 run),
+  // 缺失才退回 runId。合并同键时回填先到条目缺失的字段,避免「仅 taskId」与
+  // 「taskId+runId」因键漂移而漏去重。
+  const byKey = new Map();
+
+  // tool_use_id → 工具名。仅认 Workflow 工具产生的 tool_result——否则其它工具
+  // (Read/Bash/Write 等)若回显含 "Workflow launched in background"/"Run ID:" 字面量的
+  // 源码或日志,会被 parseWorkflowFromText 误判为一次真实启动(自引用误检)。
+  // 与 ToolResultView 渲染内联面板前判 toolName==='Workflow' 同源,扫法对齐 toolResultBuilder。
+  const toolNameById = buildToolUseNameMap(requests);
+
+  for (const req of requests) {
+    const msgs = req?.body?.messages;
+    if (!Array.isArray(msgs)) continue;
+    for (const m of msgs) {
+      if (m?.role !== 'user' || !Array.isArray(m.content)) continue;
+      for (const block of m.content) {
+        if (block?.type !== 'tool_result') continue;
+        if (toolNameById.get(block.tool_use_id) !== 'Workflow') continue;
+        const txt = extractToolResultText(block);
+        const wf = parseWorkflowFromText(txt);
+        if (!wf) continue;
+
+        const key = wf.taskId || wf.runId;
+        if (!key) continue;
+        const summary = (txt.match(SUMMARY_RE) || [])[1]?.trim() || null;
+
+        const existing = byKey.get(key);
+        if (!existing) {
+          byKey.set(key, {
+            runId: wf.runId,
+            taskId: wf.taskId,
+            sessionId: wf.sessionId,
+            resultText: txt,
+            timestamp: req?.timestamp ?? null,
+            summary,
+          });
+        } else {
+          // 回填缺失字段(取任一非空);timestamp 保留最早出现的一条。
+          if (!existing.runId && wf.runId) existing.runId = wf.runId;
+          if (!existing.taskId && wf.taskId) existing.taskId = wf.taskId;
+          if (!existing.sessionId && wf.sessionId) existing.sessionId = wf.sessionId;
+          if (!existing.summary && summary) existing.summary = summary;
+          if (isEarlier(req?.timestamp, existing.timestamp)) {
+            existing.timestamp = req.timestamp;
+            existing.resultText = txt;
+          }
+        }
+      }
+    }
+  }
+
+  // 最新在前:timestamp 降序;无 timestamp 的排末尾。
+  return Array.from(byKey.values()).sort((a, b) => tsValue(b.timestamp) - tsValue(a.timestamp));
+}
+
+/**
+ * 扫 assistant 轮(body.messages)与当前轮 response(response.body.content)的 tool_use,
+ * 建 id → name 映射。tool_result 凭 tool_use_id 反查工具名,只放行 Workflow。
+ */
+function buildToolUseNameMap(requests) {
+  const map = new Map();
+  for (const req of requests) {
+    const msgs = req?.body?.messages;
+    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) map.set(b.id, b.name);
+          }
+        }
+      }
+    }
+    const respContent = req?.response?.body?.content;
+    if (Array.isArray(respContent)) {
+      for (const b of respContent) {
+        if (b?.type === 'tool_use' && b.id) map.set(b.id, b.name);
+      }
+    }
+  }
+  return map;
+}
+
+function tsValue(ts) {
+  if (ts == null) return -Infinity;
+  const n = typeof ts === 'number' ? ts : Date.parse(ts);
+  return Number.isNaN(n) ? -Infinity : n;
+}
+
+function isEarlier(candidate, current) {
+  return tsValue(candidate) < tsValue(current);
+}

package/src/utils/workflowStore.js

@@ -0,0 +1,94 @@
+/**
+ * Workflow live store
+ *
+ * 轻量模块级发布订阅，承接服务端 SSE `workflow_update` 事件，按 runId（及 taskId 别名）
+ * 分发给对应的 WorkflowPanel。避免 AppBase→ChatView→ChatMessage→ToolResultView→Panel
+ * 深层 prop 穿线。
+ *
+ * - publish(payload): AppBase 收到 workflow_update 时调用，payload = { runId, taskId, data, ... }。
+ * - subscribe(key, cb): WorkflowPanel 按自身 runId 或 taskId 订阅，返回退订函数。
+ * - getLatest(key): 取已缓存的最新 journal（panel 挂载时若已先到事件可即时用）。
+ */
+
+const _subs = new Map();          // key(runId|taskId) → Set<cb>
+const _latest = new Map();        // key → normalized journal data
+const _authoritative = new Set(); // keys that已收到 live===false 的权威完成快照
+
+// 「活跃工作流」追踪：供右下角悬浮 HUD 常驻展示运行中的工作流。
+const _active = new Map();         // runId → 最新 data（仅运行中/收尾中）
+const _activeSubs = new Set();     // Set<cb(list)>
+
+function _emit(key, data) {
+  const set = _subs.get(key);
+  if (!set) return;
+  for (const cb of set) {
+    try { cb(data); } catch {}
+  }
+}
+
+function _emitActive() {
+  const list = [..._active.values()];
+  for (const cb of _activeSubs) {
+    try { cb(list); } catch {}
+  }
+}
+
+function _isActive(data) {
+  return data.live === true || data.status === 'running' || data.status === 'finishing';
+}
+
+export function publish(payload) {
+  if (!payload || typeof payload !== 'object') return;
+  const data = payload.data;
+  if (!data || typeof data !== 'object') return;
+  const keys = [];
+  if (payload.runId) keys.push(payload.runId);
+  if (data.runId && data.runId !== payload.runId) keys.push(data.runId);
+  if (payload.taskId) keys.push(payload.taskId);
+  if (data.taskId && data.taskId !== payload.taskId) keys.push(data.taskId);
+  // 权威完成快照（live!==true）一旦到达即锁定该 key：忽略其后乱序到达的运行中逐帧，
+  // 否则尾随的 live 帧会把面板从「已完成」回退成「运行中」。
+  const isLive = data.live === true;
+  for (const k of keys) {
+    if (isLive && _authoritative.has(k)) continue;
+    if (!isLive) _authoritative.add(k);
+    _latest.set(k, data);
+    _emit(k, data);
+  }
+
+  // 维护活跃工作流集合（按 canonical runId 去重，避免 taskId 重复计数）
+  const rk = data.runId || payload.runId;
+  if (rk && !(isLive && _authoritative.has(rk))) {
+    if (_isActive(data)) { _active.set(rk, data); _emitActive(); }
+    else if (_active.delete(rk)) { _emitActive(); }
+  }
+}
+
+/** 订阅活跃（运行中/收尾中）工作流列表变化；立即不回调，调用 getActiveWorkflows 取初值。 */
+export function subscribeActive(cb) {
+  if (typeof cb !== 'function') return () => {};
+  _activeSubs.add(cb);
+  return () => { _activeSubs.delete(cb); };
+}
+
+/** 取当前活跃工作流列表（最新 data 数组）。 */
+export function getActiveWorkflows() {
+  return [..._active.values()];
+}
+
+export function subscribe(key, cb) {
+  if (!key || typeof cb !== 'function') return () => {};
+  let set = _subs.get(key);
+  if (!set) { set = new Set(); _subs.set(key, set); }
+  set.add(cb);
+  return () => {
+    const s = _subs.get(key);
+    if (!s) return;
+    s.delete(cb);
+    if (s.size === 0) _subs.delete(key);
+  };
+}
+
+export function getLatest(key) {
+  return key ? (_latest.get(key) || null) : null;
+}