Helios AI 助手平台 · 简历关键词速查

• 你能说清楚为什么选 SSE 不选 WebSocket 吗？
• "事件并发乱序"具体是什么情况？你怎么保证事件顺序？
• "流式事件状态机"是怎么设计的？有哪些状态和转换？
• "Tool Call 审批与中断恢复"是什么场景？技术上怎么实现？
• 你说"线上渲染问题清零"，之前有什么问题？

┌──────────────────────────────────────────────────────────────────────────────────────┐
│                              用户操作触发 SSE 请求                                  │
└─────────────────────────────────────┬────────────────────────────────────────────────┘
                                      │
    ┌──────────────┬──────────────────┼──────────────────┬─────────────────┐
    ▼              ▼                  ▼                  ▼                 ▼
  新建对话     已有对话追加       已有对话追加       重新生成回答    MCP 审批继续
  + 首条消息   (非 Agentic)      (Agentic 模式)
  创建thread+run  新建 Run          继续已有 Run

═══ API 端点路由（两套 API 并存，运行时按 mode 切换）═════════════════════════════════════

┌───── Responses API (新) ────────────────────┬───── Threads/Runs API (老) ──────────────┐
│ 条件: USE_RESPONSES_API=true + agent/act   │ 条件: 其余情况                          │
│                                            │                                         │
│ 新建:                                      │ 新建:                                    │
│  POST /api/conversations                   │  POST /api/threads                       │
│    /responses?stream=true                  │    /runs?stream=true                     │
│                                            │                                         │
│ 追加(非Agentic + Agentic 共用):             │ 追加(非Agentic):                         │
│  POST /api/conversations                   │  POST /api/threads/{id}                  │
│    /{id}/responses/continue?stream=true    │    /runs?stream=true                     │
│                                            │                                         │
│                                            │ 追加(Agentic):                           │
│                                            │  POST /api/threads/{id}                  │
│                                            │    /runs/continue?stream=true            │
│                                            │                                         │
│ 审批继续:                                  │ 审批继续:                                │
│  POST /api/conversations                   │  POST /api/threads/{id}                  │
│    /{id}/responses/continue?stream=true    │    /runs/{rid}/continue?stream=true      │
│  payload: { approve, auto_approve }        │  payload: { approve, auto_approve }      │
├────────────────────────────────────────────┴─────────────────────────────────────────┤
│ 重新生成(共用): POST /api/threads/{id}/messages/{mid}/regenerate?stream=true         │
└─────────────────────────────────────┬────────────────────────────────────────────────┘
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────────────┐
│  SSE 连接建立（sse.js POST）                                                      │
│  请求体: { assistant_id, messages, mode, attachment_file_ids, ... }                │
│  响应: Content-Type: text/event-stream                                            │
└─────────────────────────────────────┬────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────────────┐
│  StreamQueue（串行异步队列）                                                       │
│  所有事件回调 → queue.addToQueue(handler) → 串行 await 执行                       │
│  timeout = 1ms（让出事件循环，给浏览器渲染机会）                                    │
└───────────────────┬─────────────────────────────────────────┬────────────────────────┘
                    │                                         │
  ┌─────────────────▼──────────────────────┐   ┌──────────────▼──────────────────────────────┐
  │ Responses API 事件处理                  │   │ 老 API (Threads/Runs) 事件处理              │
  │ setupResponsesEventListeners            │   │ setupAllEventListeners                     │
  │                                        │   │                                             │
  │ 阶段1: 连接                             │   │ 消息生命周期:                              │
  │   response.created                     │   │   thread.message.created                    │
  │   response.in_progress                 │   │   thread.message.delta                      │
  │                                        │   │   thread.message.completed                  │
  │ 阶段2: 流式输出                         │   │                                             │
  │   output_item.added ← [type路由]      │   │ Thread & Run:                              │
  │   output_text.delta                    │   │   thread.completed                          │
  │   output_text.done                     │   │   thread.run.completed                      │
  │   content_part.added / done            │   │                                             │
  │   mcp_call_arguments.delta / done      │   │ Agentic 1.0:                               │
  │   mcp_call.in_progress                 │   │   tool.message.initialized                  │
  │   mcp_call.completed                   │   │   tool.router.in_progress / completed       │
  │   mcp_call.failed                      │   │   tool.output.start / completed             │
  │                                        │   │   reasoning.evaluation.start / completed    │
  │ 阶段3: 结束                             │   │                                             │
  │   output_item.done                     │   │ Agentic 2.0:                               │
  │   response.completed                   │   │   tool_call.intent                          │
  │   done → 关闭连接                      │   │   tool_call.approval  → MCP审批             │
  │                                        │   │   tool_call.in_progress                     │
  │                                        │   │   tool_call.completed                       │
  │                                        │   │   thread.message.notification               │
  │                                        │   │                                             │
  │                                        │   │ 其他:                                      │
  │                                        │   │   assistant.router.completed                │
  │                                        │   │   support_case_details.completed            │
  │                                        │   │   done → 关闭连接                          │
  └──────────────────┬─────────────────────┘   └─────────────────────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────────────────────────────────────────┐
│  output_item.added 的 metadata.type 子路由（Responses API 核心分发）               │
│                                                                                    │
│  thread.saved          → 保存 Thread 数据（id, metadata）                          │
│  message               → 创建消息容器，逐字追加文本，触发智能滚动                  │
│  thinking              → 显示"正在思考"折叠区                                      │
│  mcp_approval_request  → MCP 审批请求（生成 use_mcp 内联消息）                     │
│  mcp_call              → MCP 工具调用（支持并行，每个调用独立消息）                 │
│  followup              → 追问问题（含可选项 options）                                │
│  internal_tool         → 内部工具（write_to_file / todo_write）                     │
│  token_usage           → Token 用量统计                                             │
│  mistake_limit         → 错误次数限制通知                                           │
│  max_requests          → 最大请求数限制通知                                         │
└──────────────────────────┬───────────────────────────────────────────────────────────┘
                           │
                           │ 当 type=mcp_approval_request 或老API的 tool_call.approval
                           ▼
              ┌──────────────────────────────────┐
              │ MCP Tool Call 审批流              │
              │                                  │
              │ mcp_call_arguments.delta / done  │
              │ mcp_call.in_progress             │
              │   ↓                              │
              │ isToolAutoApproved()?            │
              │   ├─ YES → 自动批准              │
              │   └─ NO  → 内联审批等待用户      │
              │            用户选择:              │
              │            once / thread / global │
              │   ↓                              │
              │ continueSSERun(approve)           │
              │   ↓                              │
              │ 新 SSE 连接从 checkpoint          │
              │ 继续推送后续事件                  │
              └──────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────────────────────┐
│  done 事件处理（收尾）                                                            │
│                                                                                    │
│  1. sendAnswerReadyNotification() — 浏览器通知（不入队，立即执行）                  │
│  2. 执行 deferredFunctions（延迟回调：更新文件计数等）                              │
│  3. archiveCurrentMessage() — 归档到历史列表                                       │
│  4. checkAutoApproveAfterStreaming() — 检查 pending MCP → 可能触发新一轮 SSE       │
│  5. eventSource.close() — 关闭 SSE 连接                                           │
│  6. resolve(message) — Promise resolve，释放调用方                                 │
└──────────────────────────────────┬───────────────────────────────────────────────────┘
                                   │
                                   ▼
┌──────────────────────────────────────────────────────────────────────────────────────┐
│  流结束后的接口请求（requestWithLatestMessage 收尾阶段）                           │
│                                                                                    │
│  GET /api/assistants/{id}          ← 条件触发（有缓存），获取 Assistant 信息        │
│  PATCH /api/threads/{id}/summary   ← 仅新对话，调用后端生成标题                     │
│  GET /api/threads/{id}             ← 必定触发，拉取最新 Thread 数据                │
└──────────────────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────────────────────┐
│  中断恢复：用户重新进入对话                                                       │
│                                                                                    │
│  GET /api/threads/{id}/messages  ← 加载历史消息                                    │
│    ↓                                                                               │
│  checkForPendingToolCalls(lastMessage)                                             │
│    ├─ run_step_name='tool_inputs' → Agentic 1.0 pending                            │
│    └─ subtype='use_mcp' + approval_status='pending' → Agentic 2.0 pending          │
│    ↓                                                                               │
│  isToolAutoApproved() → 查 Global(API) → 查 Thread(localStorage)                   │
│    ├─ YES → 自动批准 → continueSSERun → 新 SSE 流                                  │
│    └─ NO  → 展示审批 UI（内联）等待用户操作                                         │
└──────────────────────────────────────────────────────────────────────────────────────┘

SSE 流式接口（两套 API 并存）

流结束后请求

其他接口

Responses API 事件（setupResponsesEventListeners）

output_item.added 的 metadata.type 子路由

老 API (Threads/Runs) 事件（setupAllEventListeners）

• 标记 是 的事件通过 StreamQueue 串行处理，保证有序；标记 否 的事件直接同步处理（无状态变更或仅做日志）
• done 中的 sendAnswerReadyNotification 不入队直接执行 — 因为浏览器后台标签会节流定时器，通知必须立即发
• 两套事件体系完全独立，运行时根据 USE_RESPONSES_API + agenticMode 选择其一

class StreamQueue {
  constructor(timeout = 1) {
    this.queue = [];
    this.isProcessing = false;
    this.timeout = timeout;
  }

  push(asyncFn) {
    this.queue.push(asyncFn);
    if (!this.isProcessing) {
      this.isProcessing = true;
      setTimeout(() => this.processQueue(), 10);
    }
  }

  async processQueue() {
    while (this.queue.length > 0) {
      const fn = this.queue.shift();
      if (fn) await fn();
      await new Promise(r => setTimeout(r, this.timeout));
    }
    this.isProcessing = false;
  }
}

• 关键设计：timeout 设 1ms，目的不是节流，而是让出事件循环让 UI 有机会渲染，避免大量 DOM 更新积压导致卡顿
• 初始 10ms 延迟是为了让第一批事件先入队再开始处理，避免频繁启停

let currentIdentifier = '';

onDelta(event) {
  const identifier = getMessageIdentifier(event.metadata);
  // content_block_ulid ?? run_step_uuid

  if (currentIdentifier && currentIdentifier !== identifier) {
    queue.addToQueue(async () => {
      archiveCurrentMessage();  // 消息 A 定稿 → 推入 messageList
    });
  }
  currentIdentifier = identifier;

  queue.addToQueue(async () => {
    appendDelta(event.delta);   // delta 追加到新的 currentMessage
  });
}

• 为什么用 ULID 而不是自增序号？ ULID 天然含时间戳且全局唯一，后端多个 agent step 并行生成时不需要全局计数器协调
• 这两层配合：StreamQueue 保证 handler 串行执行，ULID 保证每个 delta 归属到正确的消息

// 1. 连接建立
response.created → response.in_progress  // 状态: THINKING

// 2. 输出项创建（按 type 路由）
response.output_item.added
  → type=message    → 创建消息容器，开始逐字渲染
  → type=thinking   → 显示"正在思考"折叠区
  → type=mcp_call   → 进入 MCP 审批流
  → type=internal_tool → 显示内部工具调用

// 3. 文本流式输出
response.output_text.delta  → 追加文本 + 触发滚动
response.output_text.done   → 文本完成

// 4. 输出项完成
response.output_item.done   → 归档消息到历史列表

// 5. 流结束
done → 发送通知 → 执行 deferred 回调 → 关闭连接

// 第 1 级：MCP Server Manager（管理员）
// 在 MCP 管理后台配置每个 Tool 的 execution_mode
tool_execution_mode: 'autonomous' | 'approval'
// autonomous = 自动执行（低风险工具，如查天气）
// approval   = 需要审批（高风险工具，如发邮件、删数据）

// 第 2 级：Assistant Manager（助手管理员）
// 在 Assistant 配置中管理该助手调用某个 MCP Tool 时是否自动 approve

// 第 3 级：用户自己的审批偏好（前端实现重点）
type ApprovalScope = 'once' | 'thread' | 'global'
// once   → 仅本次（不记忆）
// thread → 本次对话内记忆（localStorage）
// global → 所有对话记忆（API 持久化）

function isToolAutoApproved(toolName, serverName, threadId) {
  // 先查 Global（API 持久化） — 用户级别
  if (UserPreferenceStore.isToolGloballyApproved(toolName, serverName)) {
    return true;  // 用户曾选"所有对话都自动批准"
  }
  // 再查 Thread（localStorage） — 对话级别
  const threadPrefs = loadThreadApprovalPreferences();
  const threadTools = threadPrefs.threads[threadId]?.[serverName];
  if (threadTools?.includes(toolName)) {
    return true;  // 用户曾在这个对话里选"本次对话自动批准"
  }
  return false;  // 需要弹窗让用户手动确认
}

function saveApprovalPreference(scope, toolName, serverName, threadId) {
  if (scope === 'once') return;
  if (scope === 'global') {
    UserPreferenceStore.addGlobalToolApproval(toolName, serverName); // API 持久化
  } else if (scope === 'thread') {
    // 写 localStorage → 当前对话内有效
    const prefs = loadThreadApprovalPreferences();
    prefs.threads[threadId][serverName].push(toolName);
    localStorage.setItem('tool_approval_thread_preferences', JSON.stringify(prefs));
  }
}

• Thread 级别用 localStorage：单次对话偏好不走 API，刷新后仍在、关浏览器自然失效
• Global 级别用 API：需跨设备同步，用户的持久设置

async function fetchMessageData() {
  const responseData = await loadMessages(threadId);

  // 检测 pending Tool Call
  checkForPendingToolCalls(responseData, context);
  // Agentic 1.0: lastMessage.metadata.tool_calls → run_step_name='tool_inputs'
  // Agentic 2.0: lastMessage.subtype='use_mcp' + approval_status='pending'

  // 先尝试自动批准（复用已保存的偏好）
  if (pendingToolCalls().length > 0) {
    await checkAndAutoApproveToolCallV1(context, isToolAutoApproved);
  }
  await checkAndAutoApproveMcpMessages(responseData, context, isToolAutoApproved);
  // 不能自动批准 → 弹窗 / 内联审批 UI
}

• 恢复后先查偏好，命中就自动批准不弹窗 → 用户体验连续
• Agentic 1.0 用 Dialog 弹窗，Agentic 2.0 用消息内联审批

• SSE：单向推送、HTTP 协议、自动重连、适合 LLM 输出
• WebSocket：双向全双工、需要协议升级、适合即时通信/协作编辑
• 长轮询：兼容性最好但效率最低，每次都要新建请求
• 我们选 SSE 因为不需要客户端实时发消息，且公司网关对 WebSocket 有额外限制

• 可以但不推荐。设 0 等于 setTimeout(fn, 0)，虽然也让出了事件循环，但在高频事件场景下 DOM 更新会堆积
• 设 1ms 给浏览器微小的渲染窗口，肉眼不可见但能避免"白屏后一次性出现大段文字"的体验问题

• 优先级从高到低：MCP Server Manager > Assistant Manager > 用户偏好
• 如果 Server Manager 设了 approval（必须审批），即使用户偏好是自动批准，后端也会要求前端走审批流程（tool_execution_mode: 'approval'）
• 用户偏好只在后端已经允许自动执行的前提下才生效 — 本质是用户在「允许自动」范围内的个人记忆

• sessionStorage 在标签页关闭后就清空了，但用户可能刷新页面后继续同一个对话
• localStorage 持久化，刷新后偏好还在。以 threadId + serverName + toolName 为 key 结构化存储
• 不用 API 是因为 Thread 级别偏好是临时性的，没必要走网络请求增加延迟

• Global 偏好从 API 加载，永不过期（除非用户主动移除）
• Thread 偏好在 localStorage 中，浏览器不清缓存就一直在
• 如果都不匹配（比如换了浏览器），就走正常的弹窗审批流程 — 降级到手动确认是最安全的默认行为

• 服务端的 LLM 调用是异步的，前端断开不影响服务端完成生成
• 刷新后重新加载页面，从 API 拉取历史消息（包括已完成或部分完成的回答）
• 如果回答尚未完成，页面会显示"生成中"状态，但不会再建立新的 SSE 连接（避免重复生成）
• 如果有 pending 的 Tool Call，会通过中断恢复机制检测到并弹窗

• 什么叫"智能"？和普通自动滚动有什么区别？
• 怎么判断用户是在阅读还是在等新内容？
• 为什么用 IntersectionObserver 而不是 scroll 事件？

function useScrollManager() {
  const [shouldStickToBottom, setShouldStickToBottom] = createSignal(true);
  const shouldShowScrollButton = () => !shouldStickToBottom();

  // === 层 1: IntersectionObserver — 检测是否在底部 ===
  const observer = new IntersectionObserver(
    entries => {
      if (entries[0].isIntersecting) {
        setShouldStickToBottom(true); // 看到底部哨兵 → 恢复自动滚
      }
    },
    { rootMargin: '0px 0px 100px 0px' } // 提前 100px 触发
  );
  observer.observe(bottomSentinel); // 底部 1px 高的隐藏 div

  // === 层 2: wheel 事件 — 检测手动向上滚 ===
  container.addEventListener('wheel', (e) => {
    if (e.deltaY < 0) {
      setShouldStickToBottom(false); // 向上滚 → 停止自动滚
    }
  }, { passive: true });

  // === 层 3: ResizeObserver — 容器高度变化时跟随 ===
  const resizeObserver = new ResizeObserver(() => {
    if (shouldStickToBottom()) {
      scrollToBottom(); // 内容增长时保持在底部
    }
  });
  resizeObserver.observe(scrollContainer);

  function scrollToBottom() {
    // 双 rAF：等当前帧渲染完 + 下一帧布局完成再滚
    requestAnimationFrame(() => {
      requestAnimationFrame(() => {
        window.scrollTo({ top: document.body.scrollHeight });
        container.scrollTo?.({ top: container.scrollHeight });
      });
    });
  }

  return { shouldShowScrollButton, scrollToBottom, bindBottomSentinel };
}

• scroll 事件触发非常频繁（每帧都触发），需要节流，且读取 scrollTop、scrollHeight 会触发强制同步布局（layout thrashing）
• IntersectionObserver 是浏览器原生优化的，在合成层（compositor）做判断，不阻塞主线程，性能好很多
• wheel 事件只在用户主动滚轮时触发，比 scroll 事件更精确地表达"用户意图"

• 流式渲染时，DOM 变化（文本追加）和容器尺寸变化（高度增长）是两回事。MutationObserver 能检测 DOM 变化，但拿到的时候布局可能还没更新
• ResizeObserver 在布局计算之后触发，这时 scrollHeight 已经是最新值，适合做滚动跟随
• 实际上 ResizeObserver + IntersectionObserver 搭配就够了，不需要 MutationObserver

• 当前用 wheel 事件检测桌面端滚轮。移动端可以补充 touchstart + touchmove 检测手势方向
• 不过这个项目是企业内部 B 端平台，主要在桌面端使用，所以优先级没那么高

• Monaco Editor 是什么？为什么不用更轻量的方案（CodeMirror / highlight.js）？
• Monaco 和 Astro ClientRouter 有什么冲突？你怎么解决的？
• 这么重的编辑器怎么做性能优化？

// 需要全量刷新的路由（含 Monaco 的页面）
const FULL_REFRESH_ROUTES = [
  '/assistant_management', // Monaco 用于 System Prompt 编辑
  '/thread',               // Monaco 用于代码块渲染
  '/document_management',  // Monaco 用于文档内容
  '/',                     // 首页（聊天页）
];

function navigateWithRefresh(url, forceRefresh = false) {
  const path = new URL(url, location.origin).pathname;
  const needsRefresh = forceRefresh ||
    FULL_REFRESH_ROUTES.some(route =>
      route === '/' ? path === '/' : path.startsWith(route)
    );

  if (needsRefresh) {
    window.location.href = url; // 全量刷新，完整销毁 + 重建
  } else {
    navigate(url); // Astro ClientRouter 客户端导航
  }
}

• 侧边栏链接同时加 data-astro-reload（Astro 原生属性）作为兜底
• 非 Monaco 页面之间仍然用 ClientRouter 做快速切换，不是全站降级

① Lazy 加载 — 按需下载，不阻塞首屏

const MonacoEditor = lazy(async () => {
  await import('@/library/monaco');        // 初始化 Worker
  const { MonacoEditor } = await import('solid-monaco');
  return { default: MonacoEditor };
});

// 使用时包 Suspense
}>
  

• 效果：首屏 JS 零 Monaco 代码；只有用户打开编辑器（或展开代码块）时才触发下载
• 原理：lazy() 内部就是 import()，Vite 会把它拆成独立 chunk，首次加载时才 fetch

② manualChunks — 独立分包，利用浏览器缓存

// astro.config.mjs → vite.build.rollupOptions
output: {
  manualChunks: {
    monaco: ['monaco-editor']  // ~2.5MB 独立 chunk
  }
}

• 效果：Monaco 代码打成一个独立 chunk（monaco.[hash].js），不混入主 bundle
• 好处：主 bundle 体积不膨胀；Monaco 更新频率低，chunk hash 基本不变 → 用户多次访问命中浏览器缓存
• 不配的话 Rollup 可能把 Monaco 拆散到多个 chunk 或混入公共包，缓存失效率高

③ Worker ESM 配置 — Worker 自包含打包

// Worker 注册（src/library/monaco.ts）
import EditorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';
import JsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker';
import TsWorker from 'monaco-editor/esm/vs/language/typescript/ts.worker?worker';

// SSR 守卫：服务端渲染时不执行
if (typeof window !== 'undefined') {
  window.MonacoEnvironment = {
    getWorker(_moduleId, label) {
      if (label === 'typescript' || label === 'javascript') return new TsWorker();
      if (label === 'json') return new JsonWorker();
      return new EditorWorker();
    }
  };
}

// Vite 配置（astro.config.mjs）
vite: {
  ssr: { noExternal: ['monaco-editor'] },  // SSR 阶段不外部化，避免 Node resolve 路径问题
  optimizeDeps: {
    include: ['monaco-editor'],            // 预构建核心，dev 启动更快
    exclude: [/* Worker 文件排除预构建 */]  // Worker 必须走 ?worker 单独打包
  },
  worker: { format: 'es' }                 // Worker 输出 ESM 格式
}

• Worker ESM 是什么：传统 Worker 用 IIFE 格式，不支持 import/export；设成 format: 'es' 后 Vite 以 ES Module 格式输出 Worker → Worker 内部的依赖全部 bundle 成一个自包含文件
• 为什么 exclude Worker：optimizeDeps 会把依赖预构建到 node_modules/.vite；Worker 需要走 ?worker 插件单独打包，预构建会破坏这个流程导致 Worker 加载失败
• SSR 守卫：typeof window !== 'undefined' 防止服务端执行 Worker 代码（Node 无 Worker 构造函数）

• lazy() 是框架层面的概念（React 的 React.lazy、Solid 的 lazy），专门用于组件级代码分割，配合 Suspense 管理加载状态
• import() 是语言层面的动态导入，返回 Promise，可以用在任何地方
• lazy 内部就是调用 import()，但额外处理了组件的生命周期和 fallback 渲染

• Vite 的 optimizeDeps 会把依赖预构建成 ESM bundle，放到 node_modules/.vite
• Worker 文件需要通过 ?worker 后缀走 Vite 的 Worker 插件单独打包成独立文件
• 如果 Worker 文件也被 optimizeDeps 预构建，会破坏 ?worker 的处理流程，导致 Worker 无法正确加载

• 有轻微影响（白屏闪烁），但可以接受：一是这些页面本身就需要加载大量资源（Monaco），二是用户切换页面的频率不高
• 做了 loading 态过渡：导航时先展示全局 loading indicator，减少白屏感知
• 大多数交互（对话、滚动）发生在同一页面内，不涉及路由切换

• 竞态问题具体是什么表现？
• 为什么防抖不够，还要用 AbortController？
• 你怎么做到"一行代码接入"的？

async function fetchDataWithAbort(config, state, abortRef) {
  try {
    state.setLoading(true);

    // 1. 取消上一个请求
    if (abortRef.current) {
      abortRef.current.abort('Request aborted');
    }

    // 2. 构建 URL（支持 queryParams 自动拼接）
    let url = config.url;
    if (config.queryParams) {
      url += '?' + new URLSearchParams(config.queryParams).toString();
    }

    // 3. 创建新的 AbortController
    abortRef.current = new AbortController();

    // 4. 发起请求，携带 signal
    const response = await fetch(url, {
      method: config.method || 'GET',
      headers: { 'Content-Type': 'application/json', ...config.headers },
      body: config.body ? JSON.stringify(config.body) : undefined,
      signal: abortRef.current.signal
    });

    if (response.ok) {
      const data = await response.json();
      // 自动处理分页数据和普通数据
      if (data.items && state.setTableData) {
        state.setTableData(data.items);
        state.setPrevPage?.(data.previous_page || null);
        state.setNextPage?.(data.next_page || null);
      } else if (state.setData) {
        state.setData(data);
      }
      return data;
    }
  } catch (error) {
    // AbortError 静默处理，不是真正的错误
    if (error.name === 'AbortError') return null;
    throw error;
  } finally {
    state.setLoading(false);
  }
}

• 不能。abort() 只是在浏览器端终止了 HTTP 连接，服务端可能还在执行
• 对于普通 API（搜索、列表），服务端执行很快，取消的价值主要是：避免过时响应覆盖 UI，而不是节省服务端资源
• 对于 SSE 流式连接，abort 会关闭连接，服务端通过检测连接断开可以提前终止 LLM 调用（如果 LLM API 支持的话）

• 也可以，比如 React Query 内部就是用 query key 来管理。但那需要在响应回来后做判断和丢弃
• AbortController 更直接：直接取消请求，不浪费带宽，catch 里静默处理就行
• 两种方案可以结合使用：abort 取消请求 + ID 做兜底校验

• 我们的 SSE 用的是 sse.js 库（非标准 EventSource），它接受一个 AbortSignal
• 用户点"停止生成"时调用 abort()，sse.js 内部关闭连接
• 同时用 StreamQueue 确保已入队的事件处理完毕后再清理状态，避免半渲染的消息残留

• 什么是脏检查？你覆盖了哪些场景？
• 有哪些边界情况需要特殊处理？
• 和 React 受控表单的思路有什么不同？

// 场景 1: 关闭浏览器标签 / 刷新页面
createEffect(() => {
  const handleBeforeUnload = (e) => {
    if (isDirty()) {
      e.preventDefault();
      return 'You have unsaved changes.';
    }
  };
  window.addEventListener('beforeunload', handleBeforeUnload);
  onCleanup(() => window.removeEventListener('beforeunload', handleBeforeUnload));
});

// 场景 2: ESC 键（最复杂 — 需要避开 Monaco 编辑器）
const handleEscKey = (e) => {
  if (e.key !== 'Escape' || submitting()) return;

  // ⚠️ 如果焦点在 Monaco 编辑器内，不处理
  // （Monaco 用 ESC 关闭自动补全/右键菜单等）
  if (e.target.closest('.monaco-editor')) return;

  // ⚠️ 如果有嵌套 Dialog 打开，不处理（让内层先响应）
  if (document.querySelectorAll('[role="dialog"]').length > 1) return;

  e.preventDefault();
  handleEscKeyAction();
};

// 场景 3: 点击"取消"按钮
const handleCancelEdit = () => {
  if (isDirty()) {
    showConfirmModal('Discard changes?', { onConfirm: resetForm });
  } else {
    resetForm();
  }
};

// 场景 4: 切换 Tab（Basic → Advanced → Tools...）
onChange={(e, newTab) => {
  if (mode() === DIALOG_MODE_EDIT && isDirty()) {
    showConfirmModal('Discard changes?', {
      onConfirm: () => { resetForm(); setActiveTab(newTab); }
    });
  } else {
    setActiveTab(newTab);
  }
}};

// 场景 5: 点击 Dialog 关闭按钮 / 点击遮罩
const handleClose = () => {
  if (mode() === DIALOG_MODE_EDIT && isDirty()) {
    showConfirmModal('Discard changes?', { onConfirm: props.handleCancel });
  } else {
    props.handleCancel();
  }
};

function hasMonacoPopupVisible() {
  // 自动补全
  const suggest = document.querySelector('.monaco-editor .suggest-widget');
  if (suggest && !suggest.classList.contains('hidden') && isVisible(suggest))
    return true;

  // 右键菜单（挂在 body 上，不在 .monaco-editor 内）
  const contextMenu = document.querySelector('.monaco-menu-container');
  if (contextMenu && isVisible(contextMenu)) return true;

  // 参数提示
  const hints = document.querySelector('.monaco-editor .parameter-hints-widget');
  if (hints && !hints.classList.contains('hidden') && isVisible(hints))
    return true;

  // 搜索/替换
  const findWidget = document.querySelector('.monaco-editor .find-widget');
  if (findWidget && findWidget.classList.contains('visible') && isVisible(findWidget))
    return true;

  return false;
}

• 这个函数检测了 5 种 Monaco 内部弹出层，确保不误关
• isVisible() 检查 display/visibility/opacity 三种隐藏方式，因为 Monaco 用不同方式隐藏不同弹出层

• Chrome 等现代浏览器不允许自定义 beforeunload 弹窗文案（只能显示浏览器默认提示），这是为了防止恶意网站阻止用户离开
• 手机浏览器（尤其 iOS Safari）可能不触发 beforeunload
• 对于这个 B 端项目来说，用户在桌面端 Chrome 上使用，兼容性足够

• React 中做脏检查的标准方案：受控组件（每个 input 的 onChange 更新 state）+ 和初始值对比生成 isDirty + React Router 的 useBlocker 拦截路由
• Solid.js 中没有 useBlocker，但 Solid 的 Signal 是细粒度响应式，不需要受控组件那套。表单字段直接绑定到 signal，变化自动追踪
• Astro ClientRouter 下用 beforeunload + data-astro-reload 覆盖路由跳转场景

• 部分 Tab（工具配置、权限管理）确实是自动保存的（每次操作立即调 API）
• 但 Basic/Advanced 等核心配置有跨字段校验（比如名称 + identifier 联动），不适合逐字段自动保存
• 而且 System Prompt 经常几百行，用户可能改了一半想撤回。"手动保存"给了用户 undo 的机会

• Sourcemap 错位是什么表现？怎么定位到是插件的问题？
• UnoCSS 和 SSR 有什么兼容问题？
• 这些问题说明你对构建工具有多深的理解？

function suidNoTransform() {
  const base = suidPlugin();
  return {
    ...base,
    name: base.name + '-no-transform',
    transform(code, id) {
      // NO_SUID=1 时跳过 transform，保持 sourcemap 完整
      if (process.env.NO_SUID === '1') return null;
      return base.transform?.call(this, code, id);
    }
  };
}

// 使用
vite: {
  plugins: [suidNoTransform()],
  build: { sourcemap: isDevelopment }
}

• 保留 SUID 的 config、ssr 等其他 hook，只覆写 transform
• 生产构建不受影响（NO_SUID 默认不设），调试时按需开启

// 这些 class 构建时能被扫描到 ✅


// 这些 class 构建时看不到完整字符串 ❌
const spacing = isCompact ? 'space-y-4' : 'space-y-12';

// UnoCSS 只看到变量名 spacing，不知道要生成 space-y-12 的样式

• Vite 基于 Rollup 的插件体系。每个插件的 transform hook 接收代码，返回 { code, map }
• 多个插件的 transform 像管道一样串联，每个环节的 sourcemap 链接起来形成 sourcemap chain
• 如果某个插件修改了代码但返回 null（没有 map），chain 就断了，后续所有的源码映射都会偏移
• SUID 插件的 bug 就是：它修改了代码但没返回正确的 sourcemap

• 理念相同：都是原子化 CSS，按需生成
• 引擎不同：Tailwind 基于 PostCSS，UnoCSS 是纯正则匹配引擎，速度快 5-100x
• 扩展性：UnoCSS 的 preset 系统更灵活，可以自定义规则、shortcuts、transformers
• Attributify：UnoCSS 支持属性化写法 <div text="sm gray" />，Tailwind 不原生支持
• 这个项目选 UnoCSS 主要因为 Astro 生态推荐 + 构建速度快 + 自定义规则能力强

• 传统 SSR（Next.js/Nuxt）：整个页面是一个大组件树，服务端渲染后客户端要全量 hydrate
• Astro Islands：页面默认是纯静态 HTML，只有标记了交互的组件（island）才会 hydrate。其他部分零 JS
• 好处是初始 JS 量极小，但交互复杂的页面（如我们的聊天页）其实 island 占比很大，此时和传统 SPA 差异不大
• Astro 5 + ClientRouter 可以把它当 SPA 用，只是静态部分零 JS 开销