前端架构

frontend/src/
├── main.tsx                      # React 19 入口（Admin SPA）
├── App.tsx                       # ConfigProvider + AuthProvider + ThemeProvider + StreamProvider + Router
├── router/index.tsx              # BrowserRouter + 三层 ErrorBoundary
├── layouts/AppLayout.tsx         # 主布局（侧栏 + 内容区 + 文件面板触发）
│
├── stores/
│   ├── authContext.tsx           # 认证状态
│   ├── streamContext.tsx         # SSE 流状态（admin 用）
│   ├── fileWorkspaceContext.tsx  # 文件面板状态
│   └── themeContext.tsx          # 多主题切换 + Antd ThemeConfig
│
├── services/api.ts               # 统一 API 客户端
│
├── types/index.ts                # 共享类型（Message / MessageBlock / Subagent / etc.）
│
├── styles/
│   ├── global.css                # 全局样式 / 滚动条 / markdown
│   ├── themes.css                # 多主题 CSS 变量定义
│   └── theme.ts                  # 后备 JS 常量（实际以 CSS 变量为准）
│
├── utils/
│   ├── csvParse.ts               # CSV/TSV 状态机解析
│   ├── fileKind.ts               # 扩展名 → kind 分类
│   └── timezone.ts               # 时区工具
│
├── pages/
│   ├── Login.tsx                 # 品牌分栏登录/注册
│   ├── AdminServices/index.tsx   # Service 管理（4 Tab）
│   ├── Scheduler/index.tsx       # 定时任务（Admin / Service 双 Tab）
│   ├── WeChat/index.tsx          # Admin WeChat 接入
│   ├── Settings/
│   │   ├── index.tsx             # SettingsLayout（侧栏菜单）
│   │   ├── PromptPage.tsx        # System Prompt + Memory & Soul + 能力提示词
│   │   ├── SubagentPage.tsx
│   │   ├── PackagesPage.tsx      # per-user venv
│   │   ├── InboxPage.tsx
│   │   └── GeneralPage.tsx       # API Keys + 时区 + 主题 + Advanced 开关 + BatchRunner 内嵌
│   └── Chat/
│       ├── index.tsx             # 主聊天页
│       ├── chat.module.css       # CSS Modules（--jf-* 变量）
│       ├── markdown.ts           # 唯一渲染管线（含 <<FILE:>> 处理）
│       ├── useSmartScroll.ts     # 智能滚动 hook
│       ├── types.ts              # StreamBlock 联合类型
│       └── components/
│           ├── ThinkingBlock.tsx
│           ├── ToolIndicator.tsx
│           ├── SubagentCard.tsx
│           ├── StreamingMessage.tsx
│           ├── MessageBubble.tsx
│           ├── ApprovalCard.tsx
│           ├── ImageAttachment.tsx
│           ├── VoiceInput.tsx
│           └── PlanTracker.tsx
│
├── components/
│   ├── FilePanel.tsx
│   ├── FilePreview.tsx           # 多类型文件查看器
│   ├── FileTreePicker.tsx        # 可访问文件/脚本图形选择器
│   ├── HeaderControls.tsx
│   ├── LogoLoading.tsx
│   ├── SplitToggle.tsx
│   ├── ApiKeyWarning.tsx         # 无 LLM Key 时引导 Modal
│   ├── ErrorBoundary.tsx         # 全仓唯一 class 组件
│   └── modals/
│       ├── BatchRunner.tsx       # 内嵌于 GeneralPage
│       ├── SoulSettings.tsx
│       ├── SubagentManager.tsx
│       ├── SystemPromptEditor.tsx
│       └── UserProfileEditor.tsx
│
└── service-chat/                 # Vite 第二入口（Consumer 端）
    ├── main.tsx
    ├── ServiceChatApp.tsx
    ├── ServiceToolBadge.tsx      # 友好工具状态条（替代 admin 的 ToolIndicator）
    ├── streamHandler.ts          # 轻量 SSE handler（无 HITL/subagent）
    ├── serviceApi.ts             # Consumer 端 API（与 services/api.ts 解耦）
    └── serviceChat.module.css

<BrowserRouter>
  <Routes>
    <Route path="/login" element={<PublicRoute><Login/></PublicRoute>} />
    <Route element={
      <ErrorBoundary scope="app-layout">
        <ProtectedRoute><AppLayout/></ProtectedRoute>
      </ErrorBoundary>
    }>
      <Route path="/" element={
        <ErrorBoundary scope="chat"><ChatPage/></ErrorBoundary>
      } />
      <Route path="/settings" element={
        <ErrorBoundary scope="settings"><SettingsLayout/></ErrorBoundary>
      }>
        <Route index element={<Navigate to="/settings/prompt" replace/>} />
        <Route path="prompt" element={<PromptPage/>} />
        <Route path="subagents" element={<SubagentPage/>} />
        <Route path="packages" element={<PackagesPage/>} />
        <Route path="batch" element={<Navigate to="/settings/general" replace/>} />
        <Route path="services" element={<AdminServicesPage/>} />
        <Route path="scheduler" element={<SchedulerPage/>} />
        <Route path="wechat" element={<WeChatPage/>} />
        <Route path="inbox" element={<InboxPage/>} />
        <Route path="general" element={<GeneralPage/>} />
      </Route>
    </Route>
    <Route path="*" element={<Navigate to="/" replace/>} />
  </Routes>
</BrowserRouter>

async function request<T>(method: string, path: string, body?: unknown): Promise<T>

type SSEEvent =
  | { type: 'token'; content: string }
  | { type: 'thinking'; content: string }
  | { type: 'tool_call'; name: string; args: string }
  | { type: 'tool_call_chunk'; args_delta: string }
  | { type: 'tool_result'; name: string; content: string }
  | { type: 'subagent_call'; name: string; task: string }
  | { type: 'subagent_call_chunk'; args_delta: string }
  | { type: 'subagent_start'; name: string }
  | { type: 'subagent_token'; content: string; agent: string }
  | { type: 'subagent_thinking'; content: string; agent: string }
  | { type: 'subagent_tool_call'; name: string; args: string; agent: string }
  | { type: 'subagent_tool_chunk'; args_delta: string }
  | { type: 'subagent_tool_result'; name: string; content: string; agent: string }
  | { type: 'subagent_end'; name: string; result: string }
  | { type: 'interrupt'; actions: unknown[]; configs: unknown[] }
  | { type: 'done' }
  | { type: 'error'; content: string }

SSE 回调 → useRef 直接修改 blocks 数组（避免每 token setState）
        → requestAnimationFrame 节流刷新（~60fps）
        → 批量更新到 React state
        → StreamingMessage (React.memo) 避免不必要重渲染

ChatPage (pages/Chat/index.tsx)
├── 对话列表（createPortal → #sider-slot）
├── 消息区域
│   ├── MessageBubble（历史消息）
│   │   └── BlocksRenderer（msg.blocks 优先 → fallback 旧逻辑）
│   ├── StreamingMessage（流式消息容器，React.memo）
│   │   ├── ThinkingBlock（折叠/展开）
│   │   ├── ToolIndicator（工具调用，可展开 args/result）
│   │   └── SubagentCard（子代理 timeline 渲染）
│   └── ApprovalCard（HITL 审批：文件 diff / Plan 编辑）
├── 输入区
│   ├── ImageAttachment（粘贴/拖拽/文件选择）
│   ├── VoiceInput（toggle 模式：单击开始 → 单击停止 → 自动转写）
│   ├── 能力开关 / Plan Mode / 模型选择器
│   └── 发送/Stop 按钮
└── useSmartScroll（用户上滚暂停吸底，回底部恢复）