diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..e02ee52c --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,10 @@ +{ + "permissions": { + "allow": [ + "PowerShell(uv --version)", + "PowerShell(netstat -ano)", + "PowerShell(Get-NetTCPConnection -LocalPort 8001 -ErrorAction SilentlyContinue)", + "PowerShell(Get-Process -Id 20560 -ErrorAction SilentlyContinue | Select-Object Id,ProcessName,Path,StartTime; try { \\(Invoke-WebRequest -Uri \"http://127.0.0.1:8001/health\" -UseBasicParsing -TimeoutSec 5\\).Content } catch { \"health check failed: $_\" })" + ] + } +} diff --git a/.gitignore b/.gitignore index 532043d8..f6b1fff3 100644 --- a/.gitignore +++ b/.gitignore @@ -5,8 +5,10 @@ frontend-web/.vscode/ # Claude Code local-only settings (per-user permissions, not shared) .claude/settings.local.json -# Local runtime logs and pid files -.runtime/ +# Local runtime logs and pid files +.runtime/ +logs/ +offline-backend-20260512/backend/logs/ # Frontend local/runtime artifacts frontend-web/.env diff --git a/frontend-web/docs/roundtable-step2-sandbox-progress.md b/frontend-web/docs/roundtable-step2-sandbox-progress.md new file mode 100644 index 00000000..d3fd7fed --- /dev/null +++ b/frontend-web/docs/roundtable-step2-sandbox-progress.md @@ -0,0 +1,207 @@ +# 圆桌 Step 2 沙箱预览 · 开发进度 + +> 最后更新：2026-05-27 +> 关联文档：`multi-agent-frontend-dev.md`（总览）、`multi-agent-backend-dev.md`（后端）、`multi-agent-api.md`（接口） +> 对照参考：主聊天 `/page/workspace/chats/:threadId`（`ChatBox` + `ArtifactsProvider` + `message-group.tsx`） + +--- + +## 1. 目标 + +在 Step 2「多智能体圆桌研讨」中，当子智能体调用 `write_file` / `str_replace` / `present_files` 时，**行为与主聊天一致**： + +| 能力 | 主聊天 | Step 2 目标 | +|------|--------|-------------| +| `write_file` 流式期间自动打开右侧沙箱 | ✅ | ✅ 虚拟 URL | +| 步骤卡里点击文件路径打开沙箱 | ✅ | ✅ | +| 消息下方文件卡片（`present_files`）点击打开 | ✅ | ✅ `PresentFilesRow` | +| 沙箱打开时收起 workspace 左侧栏 | ✅（`ArtifactsProvider.select`） | ✅ Step 2 左栏联动 | +| 60/40 对话 \| 产物预览分栏 | ✅ `ChatBox` | ✅ `Step2SandboxLayout` | +| 流式 MD 从 tool_call.args.content 预览 | ✅ 虚拟 URL + stub messages | ✅ `seatStubMessages`（双通道：`onPhaseChange` + `onUpstreamFrame`） | +| 落盘后 HTTP 拉取真实文件 | ✅ artifacts API | ✅ `present_files` 卡片走 HTTP | +| 草稿 reload 后历史文件可预览 | ✅ | ✅ `seatStubMessages` 一并入草稿 | + +--- + +## 2. 已完成 + +### 2.1 Step 2 布局调整 + +| 项 | 状态 | 说明 | +|----|------|------| +| 推理模型下拉 | ✅ | 从右侧栏迁至 Step 2 顶栏「多智能体圆桌会商中心」右侧 | +| 意图理解 | ✅ | 移至左侧栏顶部，支持展开/收起；收起时仅显示「目标」 | +| 任务概览 | ✅ | 放在「人工参与」下方 | +| 右侧栏 Step 2/3 隐藏 | ✅ | `RightSidebar` 仅在 `currentStep === 1` 渲染 | +| 左侧栏整体收起 | ✅ | 宽度 56px；展开按钮在顶部；研讨中角色 ring + ping 动画 | +| 沙箱打开 → 左栏收起 | ✅ | `Step2SandboxSidebarSync` 监听 `useArtifacts().open` | + +**主要文件**：`RoundtablePlanningPage.tsx`（`step2SidebarExpanded`、`LeftSidebar`、`Step2SandboxSidebarSync`） + +### 2.2 沙箱基础设施（Phase 1） + +| 项 | 状态 | 说明 | +|----|------|------| +| 路由包 `ChatRuntime` | ✅ | `WorkspaceRoutes.tsx` → `roundtable/planning` 外包 `ArtifactsProvider` | +| 60/40 分栏壳 | ✅ | `Step2SandboxLayout.tsx`，对齐 `chat-box.tsx` | +| `ArtifactFileDetail` / `ArtifactFileList` | ✅ | 嵌在右栏 ResizablePanel | +| `ThreadContext` stub | ✅ | 最小 `BaseStream` stub，供 `useArtifactContent` 工作 | + +### 2.3 沙箱打开逻辑（Phase 2） + +| 项 | 状态 | 说明 | +|----|------|------| +| `write_file` 自动打开 | ✅ | `handleArtifactToolPhase` 在 `tool_calling` + 完整 `args.path` 时触发 | +| 步骤卡点击打开 | ✅ | `MessageStepsCard` → `openArtifactFromStep` | +| 虚拟 URL 机制 | ✅ | `write-file:?message_id=...&tool_call_id=...`（对齐主聊天） | +| Stub messages 注入 | ✅ | `seatStubMessages` + `upsertSeatToolCall` → `loadArtifactContentFromToolCall` | +| 重置清理 | ✅ | `resetStep2State` 清空 artifacts / stub / deselect | +| `present_files` 步骤点击 | ✅ | 走真实路径 `openArtifactPreview`（HTTP API） | + +### 2.4 上游帧兜底注入（Phase 3） + +| 项 | 状态 | 说明 | +|----|------|------| +| `onPhaseChange` 主通道 | ✅ | `tool_calling` 阶段每帧把完整 `args` 喂进 stub；首次出现 `path` 即触发自动打开 | +| `onUpstreamFrame` 兜底通道 | ✅ | `handleUpstreamFrame` 扫描 messages-tuple 帧的 `tool_calls[]`，对 `write_file`/`str_replace` 持续 upsert `args.content`；覆盖 phase 已切走但 tool_calls 又回包的边界 | +| 双通道幂等 | ✅ | `upsertSeatToolCall` 按 `(toolName, path)` 去重，两个通道并发写入安全 | + +### 2.5 `present_files` 文件卡（Phase 4） + +| 项 | 状态 | 说明 | +|----|------|------| +| 气泡下方文件卡行 | ✅ | `Step2Message` → `collectPresentedFiles` → `PresentFilesRow` | +| 卡片样式 | ✅ | 文件名 + 扩展名徽章（FILE_EXT_LABELS），最小宽度 30/最大 50（hover 边框亮色） | +| 点击 → HTTP 预览 | ✅ | `openArtifactPreview(agentThreadId, path)`，与步骤卡 `present_files` 走同一通道 | +| 席位 thread 缺失保护 | ✅ | 没有 `agentThreadId` 时 disabled + tooltip | +| 同气泡多次 present_files | ✅ | `filepaths` 顺序去重，全部聚合到一行卡片 | + +### 2.6 草稿持久化（Phase 5） + +| 项 | 状态 | 说明 | +|----|------|------| +| `seatStubMessages` 进 `Step2Snapshot` | ✅ | `useStep2Orchestration.ts` Step2Snapshot 新增字段 | +| `seatStubMessages` 进 `DraftStep2Snapshot` | ✅ | `drafts.ts` 加 optional 字段，老草稿 reload 时回退到 `{}` | +| `hydrateFromDraft` 还原 stub | ✅ | 同步写 `seatStubMessagesRef` + state，加载草稿后点击历史 write_file 步骤可直接预览 | +| `getStep2Snapshot` 透出 stub | ✅ | `RoundtablePlanningPage.tsx` 给 `useDraftPersistence` 的 getter 加上该字段 | + +**主要文件**： + +``` +frontend-web/src/pages/WorkspaceRoutes.tsx +frontend-web/src/roundtable-planning/hooks/useStep2Orchestration.ts +frontend-web/src/roundtable-planning/components/Step2SandboxLayout.tsx +frontend-web/src/roundtable-planning/components/Step2Panel.tsx +frontend-web/src/roundtable-planning/components/MessageStepsCard.tsx +frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx +frontend-web/src/roundtable-planning/utils/drafts.ts +``` + +### 2.7 与主聊天对齐的核心数据流 + +``` +special seat SSE (streamMultiAgent) + ├── onPhaseChange("tool_calling", "write_file", args) + │ ↓ + │ upsertSeatToolCall(seatThreadId, "write_file", args) + │ → seatStubMessages[seatThreadId] = [{ type:"ai", tool_calls:[{ id, name, args }] }] + │ ↓ + │ buildWriteFileVirtualUrl(path, messageId, toolCallId) + │ → "write-file:/mnt/user-data/outputs/foo.md?message_id=...&tool_call_id=..." + │ ↓ + │ openSeatVirtualArtifact(seatThreadId, virtualUrl, auto=true) + │ → selectArtifact(virtualUrl) + setArtifactsOpen(true) + │ + └── onUpstreamFrame(frame) ← 兜底通道 + ↓ + handleUpstreamFrame —— 持续 upsert tool_calls 里完整的 args（不打开沙箱） + +Step2SandboxLayout + ThreadContext.thread.messages = seatStubMessages[activeThreadId] + ArtifactFileDetail(filepath=virtualUrl, threadId=seatThreadId) + ↓ + useArtifactContent → loadArtifactContentFromToolCall + → 从 thread.messages 读 tool_call.args.content（不发 HTTP） +``` + +**为何不用真实 path 直接预览**：流式期间文件可能尚未落盘，直接调 `/api/threads/:id/artifacts/...` 会返回 `404 {"detail":"Not Found"}`。主聊天同样用虚拟 URL 绕过此问题。 + +--- + +## 3. 未完成 / 待验证 + +### 3.1 功能缺口（按优先级） + +| 优先级 | 项 | 状态 | 说明 | +|--------|----|------|------| +| P0 | 端到端回归 | ⚠️ 待验证 | 虚拟 URL + 双通道 + 文件卡 + 草稿持久化全链路尚未在浏览器里跑一遍 | +| P2 | `str_replace` 流式编辑预览 | ❌ | 主聊天 `applyPendingTextEdit` 依赖完整 message 链；stub 未模拟 tool result / 多轮 str_replace 累加 | +| P2 | 沙箱 `artifacts[]` 列表与虚拟 URL 混排 | ❌ | 虚拟 URL 不写入 `setArtifacts([])`；多文件切换、文件名下拉体验未完全对齐主聊天 | +| P3 | Step 3 与沙箱衔接 | ❌ | Step 3 仍用 `HighFidelityReport` + `listSessionArtifacts`；与 Step 2 沙箱选中态无联动 | +| P3 | 文档同步 | ❌ | `multi-agent-frontend-dev.md` 仍描述旧布局（右侧栏模型选择器等），需更新 § 布局 + 沙箱章节 | + +### 3.2 已知风险 / 边界 + +1. **打开时机**：仅在 SSE 进入 `tool_calling` 且 `tool_calls[0].args` 为完整对象时触发自动打开（`multi-agent.ts` 刻意忽略 `tool_call_chunks` 的拼接 args）。若模型只发 chunks、迟迟不发完整 tool_calls，自动打开会延迟到 args 完整那一帧——与主聊天一致。 +2. **多 write_file 同气泡**：`upsertSeatToolCall` 按 `(toolName, path)` 幂等；同 path 多次 write 会更新 args，不会新建多条 stub tool_call。 +3. **leader 席位**：当前仅 special 流绑定 `agentThreadId` 并接 `onUpstreamFrame`；总控若直接 write_file，需单独接 thread id 与帧回调。 +4. **`present_files` 文件大小**：流式期间 backend 尚未给出真实大小；卡片只显示扩展名徽章，不显示 size。落盘后用户点开走 HTTP API 自然能看到完整内容。 +5. **调试日志**：控制台 `[roundtable-sandbox]` 前缀；生产环境可考虑加 `window.__ROUNDTABLE_SANDBOX_DEBUG__` 门控。 + +--- + +## 4. 分阶段计划（原始规划 vs 现状） + +| 阶段 | 内容 | 状态 | +|------|------|------| +| Phase 1 | `ChatRuntime` + 分栏壳 + 侧栏联动 | ✅ 完成 | +| Phase 2 | `write_file` 自动/点击打开 + 虚拟 URL 预览 | ✅ 完成 | +| Phase 3 | `onUpstreamFrame` 注入完整 LangGraph messages | ✅ 完成（双通道兜底） | +| Phase 4 | `present_files` 卡片 + Step 3 文件区衔接 | ⚠️ 卡片完成；Step 3 衔接遗留 | +| Phase 5 | 草稿 stub 持久化 + 文档更新 | ✅ stub 完成；本文档同步更新 | + +--- + +## 5. 测试清单 + +在 `/page/workspace/roundtable/planning` Step 2 下逐项勾选： + +- [ ] 子智能体 `write_file` 进入 `tool_calling` 后，右侧沙箱 **自动** 打开（约 100ms 延迟，对齐主聊天） +- [ ] 沙箱标题为文件名（如 `sample-paper.md`），**不是** `{"detail":"Not Found"}` +- [ ] 流式期间 MD 内容随 `args.content` 更新（双通道：phase 切换帧 + 兜底帧） +- [ ] 点击 ChainOfThought 步骤「写入文件」/ 路径 chip → 手动打开同一文件 +- [ ] `present_files` 后气泡下方出现文件卡（带扩展名徽章），点击 → HTTP 预览 +- [ ] 沙箱打开时左侧「意图理解」栏 **自动收起** +- [ ] 关闭沙箱（X）后对话区恢复全宽 +- [ ] 「新建任务」后 artifacts / 沙箱 / `seatStubMessages` 全部清空 +- [ ] 「保存草稿」→「加载草稿」后，点击历史 `write_file` 步骤可立即预览（stub 已还原） +- [ ] 与主聊天 `/page/workspace/chats/:threadId` 对比：同一 write_file 行为一致 + +**调试**：DevTools Console 过滤 `[roundtable-sandbox]` 或 `[stream:special:...]`。 + +--- + +## 6. 关键代码索引 + +| 用途 | 路径 | +|------|------| +| 主聊天 write_file 虚拟 URL + 自动打开 | `src/components/workspace/messages/message-group.tsx` | +| 主聊天 `RichFileCard`（present_files） | `src/components/workspace/messages/message-list-item.tsx` | +| 主聊天 60/40 分栏 | `src/components/workspace/chats/chat-box.tsx` | +| 虚拟 URL 内容加载 | `src/core/artifacts/loader.ts` → `loadArtifactContentFromToolCall` | +| Artifacts 上下文 | `src/components/workspace/artifacts/context.tsx` | +| Step 2 编排 + 沙箱状态 + 草稿快照 | `src/roundtable-planning/hooks/useStep2Orchestration.ts` | +| Step 2 沙箱布局 | `src/roundtable-planning/components/Step2SandboxLayout.tsx` | +| Step 2 文件卡 + 步骤渲染 | `src/roundtable-planning/components/Step2Panel.tsx` | +| SSE phase 推断 + `onUpstreamFrame` | `src/roundtable-planning/api/multi-agent.ts` → `setPhase` | +| 主页面侧栏 + 联动 | `src/roundtable-planning/pages/RoundtablePlanningPage.tsx` | +| 草稿持久化 | `src/roundtable-planning/utils/drafts.ts`、`hooks/useDraftPersistence.ts` | + +--- + +## 7. 下一步建议（给接续开发者） + +1. **先跑通 P0 测试清单**，确认 Phase 3/4/5 改造后无回归；重点观察双通道并发写入 stub 时 args 是否被旧帧覆盖（理论上 LangGraph 完整 tool_calls 是单调累积的，应该没问题）。 +2. **Phase 4 收尾**：把 Step 3 的 `listSessionArtifacts` / `HighFidelityReport` 接进沙箱选中态——Step 3 进入时复用 Step 2 的 `ArtifactsProvider`，让用户在 Step 3 也能预览 Step 2 留下的产物。 +3. **Phase 2 边界**：`str_replace` 多轮编辑的 stub 模拟（追加 tool result 消息让 `applyPendingTextEdit` 能 replay edit 序列），优先级低。 +4. **更新** `multi-agent-frontend-dev.md`：Step 2 布局、沙箱架构、`seatStubMessages` 数据流，避免与本文档重复——可在总览文档加一节「见 `roundtable-step2-sandbox-progress.md`」。 diff --git a/frontend-web/docs/前端开发.md b/frontend-web/docs/前端开发.md new file mode 100644 index 00000000..502f4bb8 --- /dev/null +++ b/frontend-web/docs/前端开发.md @@ -0,0 +1,1165 @@ +# 前端开发文档（frontend-web） + +> 本文档面向参与 `frontend-web/` 开发的工程师，覆盖工程结构、技术栈、环境与启动、路由与页面、状态体系、与后端 LangGraph 的实时流式交互、上传/产物（Artifacts）、模型与设置、鉴权、主题与国际化、构建与发布等所有关键开发点，力求从零到一帮助新成员快速上手。 + +--- + +## 1. 概览 + +- 项目名：`deer-flow-frontend-vite`（package.json） +- 类型：单页应用（SPA），React 19 + TypeScript 5 + Vite 6 +- 包管理器：pnpm（`packageManager: pnpm@10.26.2`） +- 路由：`react-router-dom` v7（采用 HashRouter） +- 状态：TanStack Query（服务端状态）+ React Context（流式会话/Artifacts/Subtasks/PromptInput）+ `localStorage`/`sessionStorage`（用户偏好与流式恢复） +- UI 体系：TailwindCSS v4 + Radix UI 原语 + shadcn 风格自封装（`src/components/ui/`）+ TDesign（少量页面）+ Lucide 图标 +- LLM 流式交互：[`@langchain/langgraph-sdk`](https://www.npmjs.com/package/@langchain/langgraph-sdk)，与后端 Gateway 上的 LangGraph 运行时（默认 `lead_agent`）建立 SSE 连接 +- 渲染：`react-markdown` + `streamdown` + `rehype-*` + `shiki/react-syntax-highlighter` + `katex` +- 富文本：`@tiptap/*`（用于 Open Canvas 写作） +- 编辑器：`@uiw/react-codemirror`（代码片段编辑） +- 流程图：`@xyflow/react`（节点连线类组件） + +> 这是一个由 Next.js 历史代码迁移而来的 Vite 工程：保留 `next/link`、`next/navigation`、`use client` 等遗留写法，并通过 [src/shims/](src/shims/) 提供运行时兼容。新开发中可以继续按 Next.js 习惯写 `useRouter()/useParams()/usePathname()`，由 shim 转译为 react-router 实现。 + +--- + +## 2. 目录结构 + +``` +frontend-web/ +├─ index.html 入口模板（含黑/白主题快速注入脚本） +├─ vite.config.ts Vite 配置（alias + sourceIdentifier 插件） +├─ tsconfig.json TS 编译选项 +├─ postcss.config.js PostCSS + tailwindcss v4 +├─ .env / .env.development / .env.production 后端地址等环境变量 +├─ docs/ 前端文档（本目录） +└─ src/ + ├─ main.tsx React 入口（StrictMode + 全局样式） + ├─ App.tsx 根组件：HashRouter + 顶层 Provider 嵌套 + ├─ env.ts 读 import.meta.env（兼容旧 NEXT_PUBLIC_ 命名） + ├─ styles/globals.css 全局 + Tailwind 入口 + ├─ shims/ next/link、next/navigation 的 react-router 适配 + ├─ pages/ 路由页面（HashRouter 下的所有 Route 元素） + │ ├─ PageRoutes.tsx /page/* 一级布局：左侧 PageSidebar + Header + │ ├─ WorkspaceRoutes.tsx /page/workspace/* 二级路由（聊天/Agents/Skills/Memory/Admin…） + │ ├─ StrategyRoutes.tsx /page/strategy/* 策略页 + │ ├─ RoundtableRoutes.tsx /page/roundtable/* + │ ├─ ChatPage.tsx 主聊天页（绑定 lead_agent） + │ ├─ AgentChatPage.tsx 基于自定义 Agent 的会话 + │ ├─ ScheduledTasksPage.tsx 定时任务 + │ ├─ ScheduledTaskRunDetailPage.tsx + │ ├─ PublicSharePage.tsx 免登录分享只读 + │ ├─ PublicScheduledTaskPage.tsx + │ ├─ LoginPage.tsx 用户名直登（开发/内网用） + │ └─ ... + ├─ core/ 「领域核心」: API 客户端、领域 hooks、类型 + │ ├─ api/ langgraph-sdk client + 鉴权 fetch + │ ├─ auth/ 访问令牌存取（localStorage） + │ ├─ config/ 后端/LangGraph URL 解析 + │ ├─ threads/ 会话流（核心 useThreadStream） + │ ├─ uploads/ 线程上传/校验/解析 + │ ├─ settings/ 本地偏好与线程级模型覆盖 + │ ├─ tasks/ 子任务 SubtaskContext + │ ├─ models/ 可用模型 + 用量开关 + │ ├─ agents/ 自定义 Agent CRUD + 选择器 + │ ├─ skills/、memory/、tags/ 其他领域 + │ ├─ scheduled-tasks/ 定时任务 + │ ├─ artifacts/ 产物（代码/文档）读取 + │ ├─ recommended-questions/、notifications/、admin/、curator/、tool-metrics/、llm-metrics/ + │ ├─ note/ 轻应用（笔记）API（独立后端 VITE_NOTE_API_BASE_URL） + │ ├─ i18n/ 语言上下文、词条、检测 + │ ├─ rehype/、streamdown/、tools/、messages/、page-layout/、route-base.tsx + │ └─ utils/ uuid、json、files、markdown、datetime + ├─ contexts/ 全局 React 上下文（Chat/Theme） + ├─ components/ + │ ├─ ui/ shadcn 风格基础组件（button、dialog、sidebar、resizable…） + │ ├─ ai-elements/ AI 业务组件（prompt-input、conversation、message、plan、reasoning…） + │ ├─ workspace/ 工作台模块（chats、messages、artifacts、settings、admin、agents…） + │ ├─ landing/ 营销页（Landing） + │ ├─ query-client-provider.tsx TanStack Query 容器 + │ └─ theme-provider.tsx next-themes 容器 + ├─ open-canvas/ 开放画布/AI 写作（独立路由：/page/canvas/*） + ├─ roundtable-planning/ 圆桌规划（独立路由：/page/roundtable/*） + ├─ strategy-components/ 策略相关组件 + Header + ├─ hooks/ 通用工具 hooks（debounce、async、localStorage…） + └─ lib/ 通用工具：cn、desensitize、ime +``` + +--- + +## 3. 启动、构建、脚本 + +### 3.1 NPM Scripts（[package.json](../package.json)） + +| 脚本 | 命令 | 说明 | +|---|---|---| +| `pnpm dev` | `vite` | 启动开发服务器（默认端口 5173；项目实际通过仓库根脚本统一为 5174） | +| `pnpm build` | `node --max-old-space-size=8192 vite build` | 生产构建（提升 Node 内存阈值，避免大型依赖 OOM） | +| `pnpm preview` | `vite preview` | 本地预览 dist 构建产物 | +| `pnpm typecheck` | `tsc --noEmit` | 仅做 TS 类型检查，不输出文件 | + +### 3.2 仓库根脚本 + +`scripts/start-frontend.sh`（与后端联动）会自动注入 `VITE_BACKEND_BASE_URL=http://127.0.0.1:8001` 与 `VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api`，并将日志/PID 写入 `.runtime/`。详细命令见根目录 [CLAUDE.md](../../CLAUDE.md)： + +```bash +./scripts/start-all.sh # 同时启动 backend + frontend +./scripts/stop-all.sh +./scripts/restart-all.sh +./scripts/status.sh +``` + +### 3.3 Vite 别名（[vite.config.ts](../vite.config.ts)） + +| 别名 | 真实路径 | +|---|---| +| `@/` | `src/` | +| `@vite/` | `src/` | +| `@/env` | `src/env.ts` | +| `next/link` | `src/shims/next-link.tsx` | +| `next/navigation` | `src/shims/next-navigation.ts` | + +工程同时配置了 `vite-plugin-source-identifier`：构建产物会带源文件标记，便于线上排错对应到源文件。 + +`base: "./"` 表示打包后使用相对路径，方便部署到任意子路径或本地 file:// 调试。 + +### 3.4 浏览器与构建目标 + +- TS `target: ES2022`、`module: ESNext`、`moduleResolution: Bundler` +- `useDefineForClassFields: true`、`isolatedModules: true`、`jsx: react-jsx` +- 严格模式开启，但 `noImplicitAny: false` + +--- + +## 4. 环境变量 + +入口在 [src/env.ts](../src/env.ts)，所有公共变量使用 `VITE_` 前缀，运行时通过 `import.meta.env` 读取。出于兼容旧 Next.js 代码，导出的对象保留 `NEXT_PUBLIC_` 命名： + +```ts +env.NEXT_PUBLIC_BACKEND_BASE_URL // VITE_BACKEND_BASE_URL +env.NEXT_PUBLIC_LANGGRAPH_BASE_URL // VITE_LANGGRAPH_BASE_URL +env.NEXT_PUBLIC_CANVAS_LANGGRAPH_BASE_URL // 画布独立 LangGraph（可选，默认回退主地址） +env.NEXT_PUBLIC_NOTE_API_BASE_URL // 轻应用「笔记」API +env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY // 静态演示模式（禁用上传/发送） +env.GITHUB_OAUTH_TOKEN // 备用：landing 中拉取仓库信息 +``` + +`.env` 文件加载优先级（Vite 标准）： + +``` +.env.development.local > .env.development > .env (开发) +.env.production.local > .env.production > .env (生产) +``` + +个人本机覆盖请使用 `.env.development.local`（已 gitignore）。 + +`getBackendBaseURL()` / `getLangGraphBaseURL()` / `getCanvasLangGraphBaseURL()` 均在 [src/core/config/index.ts](../src/core/config/index.ts) 中，会基于当前 `window.location.origin` 兜底为同源 `/api/langgraph`。 + +--- + +## 5. 渲染入口与 Provider 体系 + +### 5.1 启动栈 + +``` +ReactDOM.createRoot(#root) +└─ + └─ + └─ + └─ + ├─ // next-themes，attribute=class，存储键 "strategy-theme" + │ ├─ // 语言上下文（locale） + │ │ └─ // 自定义主题（与 next-themes 协作） + │ │ └─ // QA 历史（localStorage: qa-chat-history） + │ │ └─ // TanStack Query + │ │ └─ ... +``` + +`index.html` 头部内联了一段脚本，会在 React 启动前根据 `localStorage["strategy-theme"]` 决定是否给 `` 添加 `dark` 类，避免暗色主题闪烁。 + +### 5.2 路由 + +外层（[App.tsx](../src/App.tsx)）： + +``` +/ -> Redirect to /login +/login LoginPage +/login/:username LoginPage（按用户名直登） +/landing LandingPage +/share/:shareCode PublicSharePage（免登录只读） +/public/scheduled-tasks/:taskId PublicScheduledTaskPage（免登录） +/page/* PageRoutes（含侧边栏与 Header） +* NotFoundPage +``` + +`/page/*` 内（[PageRoutes.tsx](../src/pages/PageRoutes.tsx)）： + +``` +/page/workspace/* -> WorkspaceRoutes（默认） +/page/strategy/* -> StrategyRoutes +/page/canvas/* -> open-canvas/routes/OpenCanvasRoutes +/page/roundtable/* -> RoundtableRoutes +``` + +`/page/workspace/*`（[WorkspaceRoutes.tsx](../src/pages/WorkspaceRoutes.tsx)）： + +``` +chats -> Navigate to chats/new +chats/:thread_id -> +agents -> AgentsPage +agents/new -> NewAgentPage +agents/:agent_id/chats/:thread_id -> AgentChatPage +skills -> SkillsPage +skills/evolution -> SkillEvolutionPage +memory -> MemoryPage +ai-writing -> AIWritingPage（来自 open-canvas） +roundtable/planning -> RoundtablePlanningPage +scheduled/tasks -> ScheduledTasksPage +scheduled/runs/:run_id -> ScheduledTaskRunDetailPage +admin -> AdminUserHubPage (system_role=admin) +admin/scheduled-tasks -> AdminScheduledTasksPage (admin) +admin/tags -> TagsPage (admin) +settings/recommended-questions (admin) +settings/prompt-prefix (admin) +settings/llm-metrics (admin) +``` + +`WorkspaceRoutes` 通过 `` 提供基址上下文，让兼容自 Next.js 的 `useRouter().push("/page/workspace/...")` 在不同的二级路由下都能映射到正确的 base。 + +> **重要约定**：使用 HashRouter，URL 形如 `/#/page/workspace/chats/new`。这是为了便于在静态文件部署（包括打包后 `file://`）下使用。新建一条聊天时，前端会用 `history.replaceState(...)` 直接改写 hash，而不让 router 重渲染整棵子树 —— 这一点在 [ChatPage.tsx:75-79](../src/pages/ChatPage.tsx#L75-L79) 中体现，依赖了 `useThreadChat()` 的特殊兜底逻辑（避免 useParams 把 `new` 误判为真实 thread_id）。 + +### 5.3 Workspace 双层布局 + +- `` 提供 `` + `` + `` + `` + ``，并通过 CSS 变量 `--page-sidebar-width` 把内层侧栏紧贴外层 PageSidebar。 +- 对于「聊天类」路由 (`chats/:thread_id`、`agents/.../chats/:thread_id`)，额外包一层 ``： + +```tsx + + + + {children} + + + +``` + +这三个上下文只在聊天会话内生效，避免污染列表/管理类页面。 + +--- + +## 6. 鉴权 + +### 6.1 登录流程 + +[src/pages/LoginPage.tsx](../src/pages/LoginPage.tsx) 通过 `loginByUsername(username)` 直接向后端发起登录（默认 `guest`），返回结构存在 [src/core/auth/index.ts](../src/core/auth/index.ts)： + +```ts +interface LoginByUsernameResponse { + access_token: string; + token_type: string; // 默认 "Bearer" + expires_in: number; + user_id: string; + email: string; + system_role: string; // "admin" 控制管理员菜单 + needs_setup: boolean; + created: boolean; +} +``` + +存储键：`localStorage["deerflow.auth"]`。 + +工具方法： +- `getStoredAuth()` / `setStoredAuth(auth)` / `clearStoredAuth()` +- `getAccessToken()` —— 返回 token 字符串 +- `getAuthorizationHeaderValue()` —— 返回 `"Bearer xxx"`，缺失时 undefined + +### 6.2 鉴权注入 + +所有出站请求都通过两条路径之一注入 Token： + +1. **裸 fetch** —— 使用 [src/core/api/fetch-client.ts](../src/core/api/fetch-client.ts) 提供的 `apiFetch(input, init)`，自动在 headers 上加 `Authorization`。 +2. **LangGraph SDK** —— [src/core/api/api-client.ts](../src/core/api/api-client.ts) 在 `new LangGraphClient` 的 `onRequest` 钩子里塞 `Authorization`，并对 `runs.stream / runs.joinStream` 做 `sanitizeRunStreamOptions` 包装（见 `core/api/stream-mode.ts`），确保流式参数合法。 + +> **务必使用 `apiFetch` 而不是裸 `fetch`**，否则鉴权头不会带上，私有接口会 401。 + +### 6.3 路由级守护 + +WorkspaceRoutes 内的 `/admin/*` 与 `/settings/*` 路由在元素层面做了判定： + +```tsx +getStoredAuth()?.system_role === "admin" + ? ... + : +``` + +非管理员被静默重定向到聊天页。 + +--- + +## 7. 与后端的通信 + +### 7.1 三种入口 + +| 通道 | 函数/客户端 | 用途 | +|---|---|---| +| LangGraph SDK | `getAPIClient(isMock?)` | LangGraph runtime：`threads.search/get/update/delete`，`runs.stream/joinStream` | +| HTTP fetch | `apiFetch(url, init)` | Gateway 业务接口（Agents/Memory/Skills/Tags/Uploads/Scheduled-tasks…） | +| 独立服务 | `getNoteApiBaseURL()` | 轻应用「笔记」服务 | + +### 7.2 LangGraph 客户端缓存 + +`getAPIClient(isMock?)` 通过模块级 `Map` 进行客户端实例缓存（`default` / `mock`），避免重复构造。 + +### 7.3 流式聊天的核心：`useThreadStream` + +定义于 [src/core/threads/hooks.ts](../src/core/threads/hooks.ts)。这是「整套前端的心脏」，所有聊天页都基于它： + +```ts +const [thread, sendMessage, isUploading] = useThreadStream({ + threadId, + context, // LocalSettings["context"] + isMock, + assistantId: "lead_agent", + onStart(threadId) { /* 第一次创建会话时回调，用于改写 URL */ }, + onFinish(state) { /* 流式收束，浏览器后台时弹通知 */ }, + onToolEnd(evt) { /* 工具调用结束钩子 */ }, +}); +``` + +关键能力： + +1. **断线重连**：通过 `sessionStorage["lg:stream:"]` 存储正在进行的 run_id，刷新页面后 SDK 自动 `joinStream` 续接。`normalizeStoredRunId()` 容错处理历史 URL/带 query 的情况。 +2. **乐观更新**：发送即在本地 messages 后追加临时 `human` 消息；当文件正在上传时还追加占位 `ai` 消息（"uploadingFiles"）；服务端有响应（messages 数量增加）后自动清空。 +3. **首条消息特例**：仅当线程已持久化时立即触发 `onStart`；新会话需要等到 SDK `onCreated(meta.thread_id)`，确保 URL 同步用的是真正的服务端 thread_id。 +4. **Context 装配**：每次提交时把 `thinking_enabled / is_plan_mode / subagent_enabled / reasoning_effort / memory_injection_enabled / thread_id` 等基于「四种 mode」推导： + +| mode | thinking_enabled | is_plan_mode | subagent_enabled | reasoning_effort | +|---|---|---|---|---| +| `flash` | false | false | false | undefined | +| `thinking` | true | false | false | low | +| `pro` | true | true | false | medium | +| `ultra` | true | true | true | high | + +5. **附件上传**：先 `uploadFiles(threadId, files)` 上传到 Gateway `/api/threads/:threadId/uploads`，然后将 `path/filename/size` 写入 `messages[0].additional_kwargs.files`，与 lead_agent 后端约定一致。 +6. **TanStack Query 失效**：流式完成或新建会话时调用 `queryClient.invalidateQueries({ queryKey: ["threads", "search"] })`，让侧边栏「最近会话」自动刷新。 +7. **错误降级**：`onError` 弹 sonner toast；`getStreamErrorMessage(error)` 兜底解析对象/嵌套字段。 + +### 7.4 重要回调事件 + +| SDK 事件 | 处理 | +|---|---| +| `onCreated(meta)` | 新线程创建：触发 `onStart`、把 agent_id 写入 thread metadata（非 mock） | +| `onLangChainEvent` | 监听 `on_tool_end` 并外抛 `onToolEnd` | +| `onUpdateEvent` | 若 `update.title` 出现，则更新 TanStack Query 缓存里的 thread 标题 | +| `onCustomEvent` | `task_running`：更新 SubtaskContext；`llm_retry`：弹 toast 提示 | +| `onError` | 清空乐观消息，弹 toast | +| `onFinish` | 触发外部 `onFinish` + 刷新 threads.search | + +### 7.5 其他领域 hook 约定 + +所有领域目录（`agents/`、`skills/`、`memory/`、`tags/`、`scheduled-tasks/`、`notifications/`、`admin/`、`curator/`、`llm-metrics/`、`tool-metrics/`、`system-settings/`、`thread-shares/`、`recommended-questions/`）遵循统一模板： + +``` +core// + ├─ api.ts 底层调用（fetch + apiFetch） + ├─ hooks.ts useQuery/useMutation 包装 + ├─ types.ts 接口类型 + └─ index.ts re-export +``` + +写新领域时也按此模板维持一致。 + +--- + +## 8. 全局状态与本地存储 + +### 8.1 React Context（运行时状态） + +| Context | 文件 | 作用域 | 状态 | +|---|---|---|---| +| `ChatContext` | [contexts/ChatContext.tsx](../src/contexts/ChatContext.tsx) | App 顶层 | 通用 QA 消息历史（localStorage: `qa-chat-history`） | +| `ThemeContext` | `contexts/ThemeContext.tsx` | App 顶层 | 主题，与 next-themes 协作 | +| `I18nContext` | [core/i18n/context.tsx](../src/core/i18n/context.tsx) | App 顶层 | 当前语言（Cookie: `locale`） | +| `SubtaskContext` | [core/tasks/context.tsx](../src/core/tasks/context.tsx) | ChatRuntime | 子任务最新 message | +| `ArtifactsContext` | [components/workspace/artifacts/context.tsx](../src/components/workspace/artifacts/context.tsx) | ChatRuntime | 当前会话产物列表与选中 | +| `PromptInputContext` | [components/ai-elements/prompt-input.tsx](../src/components/ai-elements/prompt-input.tsx) | ChatRuntime | 输入框附件/状态 | +| `RouteBaseContext` | [core/route-base.tsx](../src/core/route-base.tsx) | Workspace/Strategy/Roundtable | 给 `useRouter` shim 提供 base prefix | +| `ThreadContext` | `components/workspace/messages/context.ts` | 每个聊天页内 | 共享 `thread` 与 `isMock` 给 MessageList 等子组件 | + +### 8.2 LocalSettings（用户偏好） + +[core/settings/local.ts](../src/core/settings/local.ts) + [core/settings/store.ts](../src/core/settings/store.ts) + [core/settings/hooks.ts](../src/core/settings/hooks.ts)： + +```ts +LocalSettings = { + notification: { enabled: boolean }, + display: { streamSpeedMeterEnabled: boolean }, + context: { + model_name?: string, + mode?: "flash" | "thinking" | "pro" | "ultra", + reasoning_effort?: "minimal"|"low"|"medium"|"high", + writing_mode?: boolean, + memory_injection_enabled?: boolean, + agent_id?: string, + } +} +``` + +- 持久化：`localStorage["deerflow.local-settings"]` +- 线程级模型覆盖：`localStorage["deerflow.thread-model."]`，通过 `useThreadSettings(threadId)` 自动合并 +- 实现：自定义的「订阅 + storage 事件」store，借助 `useSyncExternalStore` 让多标签页/多组件同步 + +### 8.3 sessionStorage + +| Key | 写入位置 | 说明 | +|---|---|---| +| `lg:stream:` | useThreadStream（SDK 内部） | 当前 run_id，用于 reconnect | +| `pendingAgentMessage` | ChatPage 提交时（含 agentId） | 跳转 AgentChatPage 后续发首条消息 | + +--- + +## 9. 组件层次 + +### 9.1 `src/components/ui/` + +shadcn 风格的「无业务」基础组件：`button`、`badge`、`avatar`、`card`、`carousel`、`command`、`dialog`、`dropdown-menu`、`hover-card`、`input`、`input-group`、`item`、`progress`、`resizable`、`scroll-area`、`select`、`separator`、`sidebar`、`skeleton`、`sonner`、`switch`、`tabs`、`textarea`、`toggle`、`toggle-group`、`tooltip` 等。 + +特色组件： +- `aurora-text` / `flickering-grid` / `magic-bento` / `spotlight-card` / `shine-border` / `confetti-button` —— Landing 视觉效果 +- `terminal` —— 终端样式 +- `number-ticker` / `word-rotate` —— 动画文本（基于 `motion`） + +### 9.2 `src/components/ai-elements/` + +AI 业务可复用组件，是聊天页的「乐高」： + +| 组件 | 用途 | +|---|---| +| `prompt-input` | 输入区域容器、附件、提交按钮、模式选择 | +| `conversation` | 消息流容器（自动滚动到底，依赖 `use-stick-to-bottom`） | +| `message` / `message-content` | 消息气泡 | +| `reasoning` | 折叠的「思考」区段 | +| `plan` | Plan-Mode 任务计划 | +| `chain-of-thought` | 步骤链路 | +| `task` | 单步任务展示 | +| `checkpoint` | 流程节点 | +| `sources` | 来源引用列表 | +| `suggestion` | 建议追问/快捷动作 | +| `code-block` | 代码块（shiki/syntax highlighter） | +| `model-selector` | 模型下拉 | +| `web-preview` / `image` | 网页/图片预览 | +| `canvas` / `node` / `edge` / `controls` | xyflow 流程图原语 | +| `loader` / `shimmer` / `toolbar` / `panel` / `queue` | 辅助 UI | +| `open-in-chat` | 「在聊天中打开」入口 | + +### 9.3 `src/components/workspace/` + +工作台模块，承载 90% 业务页面： + +``` +workspace/ +├─ workspace-sidebar.tsx 右栏导航 +├─ workspace-header.tsx 顶部 +├─ workspace-nav-menu.tsx +├─ workspace-nav-chat-list.tsx 最近会话 +├─ workspace-container.tsx 业务包裹器 +├─ command-palette.tsx ⌘K +├─ thread-title.tsx +├─ welcome.tsx / agent-welcome.tsx +├─ todo-list.tsx +├─ token-usage-indicator.tsx +├─ streaming-indicator.tsx +├─ input-box.tsx 基于 PromptInput 的实际输入框（模式、Agent、附件） +├─ export-trigger.tsx 导出会话 docx/md +├─ thread-share-dialogs.tsx 创建/管理只读分享链接 +├─ recent-chat-list.tsx / recent-writing-list.tsx +├─ chats/ +│ ├─ chat-box.tsx 左右双栏 (聊天 + Artifacts)，react-resizable-panels +│ ├─ use-thread-chat.ts 解析 :thread_id（new -> uuid） +│ └─ use-chat-mode.ts 特定 mode hook +├─ messages/ +│ ├─ message-list.tsx 渲染所有消息、groupMessages +│ ├─ message-group.tsx +│ ├─ message-list-item.tsx +│ ├─ markdown-content.tsx react-markdown + rehype-katex + rehype-raw + remark-gfm + remark-math +│ ├─ subtask-card.tsx +│ ├─ message-token-usage.tsx +│ ├─ use-message-metrics.ts +│ ├─ download-word-button.tsx +│ ├─ context.ts ThreadContext +│ └─ skeleton.tsx +├─ artifacts/ +│ ├─ context.tsx ArtifactsContext + Provider +│ ├─ artifact-file-list.tsx +│ ├─ artifact-file-detail.tsx +│ └─ artifact-trigger.tsx 顶部「打开 Artifacts」按钮 +├─ citations/ 引用链接渲染 +├─ settings/ 设置弹窗与子页（appearance/account/skill/memory/tool/about） +├─ admin/ 管理员页（user-management / tag-management / admin-user-hub / tool-metrics / memory） +├─ agents/ Agent gallery、selector、manage dialog +├─ skills/ skill-detail-dialog、skill-evolution-panel +├─ scheduled-tasks/ schedule-builder +├─ tags/ tag-picker-dialog、tag-chip、tag-search-bar、tag-colors +└─ ... +``` + +### 9.4 `src/open-canvas/` + +AI 写作 / 画布编辑器（基于 `@tiptap/*`）： + +- `routes/OpenCanvasRoutes.tsx` 二级路由 +- `pages/`：CanvasHomePage / CanvasThreadPage / AIWritingPage / ArticleTypesConfigPage +- `editor/TiptapEditor.tsx` + `TiptapExtensions.ts` + `AiHighlightExtension.ts` +- `contexts/`：Canvas 自有的 Stream/Thread/Graph/UI Context（与主聊天页解耦） +- `hooks/`：`useCanvasStream`、`useCanvasArtifact`、`useCanvasThread`、`useWritingRewrite`、`useDocumentOutline` 等 +- `api/`：自己封装 `/canvas/runs` `/canvas/threads` `/rewrite` `/writing-export` `/ai-writing-sessions` +- 独立 LangGraph 服务地址通过 `VITE_CANVAS_LANGGRAPH_BASE_URL` 配置；未配置则与主聊天同源（仅 assistantId 不同） + +### 9.5 `src/roundtable-planning/` + +圆桌规划页（多 Agent 协同生成方案）： + +- `pages/RoundtablePlanningPage.tsx` 主页 +- `components/`：Step1/Step2/Step3 面板、MessageBubble、PersonaDrawer、HighFidelityReport、RecommendAgentsDialog +- `hooks/`：`useStep1Intent`、`useStep2Orchestration`、`useAutoScroll`、`useDraftPersistence` +- `api/`：intent / multi-agent / recommend +- `lib/`：clarification 规则、reasoning 工具、step-display +- 自带 `styles/roundtable-planning.css` + +### 9.6 `src/strategy-components/` + +策略类页面（含 QA 中心 / Agent QA / Collaborative QA / MopeChat），其中部分仍保留 `.jsx` 旧文件。新增功能优先迁移到 `.tsx`。 + +--- + +## 10. 样式与主题 + +### 10.1 TailwindCSS v4 + +- `postcss.config.js` 引入 `@tailwindcss/postcss` +- 入口样式：[src/styles/globals.css](../src/styles/globals.css) +- 配合 `tw-animate-css` 提供常用动效 +- `cn(...)` 工具（[src/lib/utils.ts](../src/lib/utils.ts)）= `twMerge(clsx(...))`，是合并 className 的「事实标准」 + +### 10.2 主题 + +- 顶层用 [next-themes](https://github.com/pacocoursey/next-themes)，`attribute="class"`，`storageKey="strategy-theme"`，默认 `light`，`/landing` 强制 light +- 自定义 `ThemeProvider`（`contexts/ThemeContext.tsx`）暴露 `theme` 给少量组件做白底 sidebar 等微调（见 [workspace-sidebar.tsx:27](../src/components/workspace/workspace-sidebar.tsx#L27)） +- `index.html` 早期注入脚本读取 storage，避免 FOUC + +### 10.3 暗色样式 + +- `.dark` 类位于 ``，Tailwind v4 通过 `darkMode: class`（约定）匹配 + +--- + +## 11. 国际化（i18n） + +[src/core/i18n/](../src/core/i18n/)： + +- `locale.ts` 提供 `detectLocale()`，按 navigator 推断 +- `translations.ts` / `locales/index.ts` 汇总词条 +- `context.tsx` 暴露 `I18nProvider` + `useI18nContext()` +- `hooks.ts` 提供 `useI18n()`，返回 `{ t, locale, setLocale }` +- 切换语言写 Cookie（`locale=xxx`），下次访问加载对应词条 + +业务里固定写法： + +```tsx +const { t } = useI18n(); +return {t.common.loading}; +``` + +--- + +## 12. 路由层的 Next.js 兼容 + +[src/shims/next-navigation.ts](../src/shims/next-navigation.ts) 通过 react-router-dom 实现了： + +- `useRouter()`：`push/replace/back/forward/refresh/prefetch`（其中 push/replace 会将旧 base `/page/workspace` 替换成 `RouteBaseContext` 值） +- `usePathname()`：`useLocation().pathname` +- `useParams()`：原样转发 +- `useSearchParams()`：只返回 `searchParams`（注意：**不是 tuple**，与 Next.js 习惯一致） + +[src/shims/next-link.tsx](../src/shims/next-link.tsx) 把 `` 桥接到 ``/``。 + +> 新代码可继续使用 `next/link`、`next/navigation`，但请避免依赖 SSR/数据获取等 Next.js 高阶特性。 + +--- + +## 13. 渲染与 Markdown + +[src/components/workspace/messages/markdown-content.tsx](../src/components/workspace/messages/markdown-content.tsx) 使用 `react-markdown` + 以下插件： + +- `remark-gfm` —— GFM 表格、删除线 +- `remark-math` + `rehype-katex` —— 数学公式 +- `rehype-raw` —— 渲染内嵌 HTML +- [core/rehype](../src/core/rehype/index.ts) 中的 `useRehypeSplitWordsIntoSpans()`：流式追加时按词包 ``，配合 CSS 渐入动画 +- [core/streamdown](../src/core/streamdown/index.ts) —— 流式 Markdown 解析（`streamdown` 包） +- 代码块用 `shiki`（高亮）+ `react-syntax-highlighter`（兜底） + +引用渲染：[components/workspace/citations/citation-link.tsx](../src/components/workspace/citations/citation-link.tsx) 和 `artifact-link.tsx` 将 `[[uuid]]` 风格引用转成可悬浮的链接卡片。 + +--- + +## 14. 上传与产物（Artifacts） + +### 14.1 上传 + +- `uploadFiles(threadId, files)`：POST 到 `/api/threads/:threadId/uploads`（FormData，`files` 字段重复多份） +- 大小/类型/数量校验：[core/uploads/file-validation.ts](../src/core/uploads/file-validation.ts) +- PromptInput 附件解析：[core/uploads/prompt-input-files.ts](../src/core/uploads/prompt-input-files.ts) 提供 `promptInputFilePartToFile()`，把组件 UI Part 转为 `File` +- 失败容错：`useThreadStream` 中若有任意 file 转换失败，会抛出 toast 并清掉乐观消息 + +### 14.2 产物 + +- 服务端在 `thread.values.artifacts: string[]` 里报路径 +- `ArtifactsProvider`（[components/workspace/artifacts/context.tsx](../src/components/workspace/artifacts/context.tsx)）做三层状态：所有产物、选中产物、面板开关 +- `ChatBox` 用 `react-resizable-panels` 拉出右侧 40% 面板，展示 `ArtifactFileList` / `ArtifactFileDetail` +- 选中 Markdown 产物时，「写作模式」会把 `writing_artifact_path` 注入 context（[ChatPage.tsx:157-159](../src/pages/ChatPage.tsx#L157-L159)），后端 PromptPrefix/Writing 中间件会接管 + +--- + +## 15. 模型/模式/Token 用量 + +### 15.1 useModels + +[core/models/hooks.ts](../src/core/models/hooks.ts)： + +```ts +const { models, tokenUsageEnabled, isLoading } = useModels(); +``` + +- `loadModels()` 调 Gateway `/api/models`（具体见 `core/models/api.ts`） +- `tokenUsageEnabled` 控制顶部 `` 是否显示 + +### 15.2 模式 (mode) + +`flash | thinking | pro | ultra` 四档（见 §7.3 表），由 `` 中的 mode 切换器修改 `LocalSettings.context.mode`。`ModeHoverGuide` 提供悬浮说明。 + +### 15.3 Token 用量 + +- 顶部全局：[components/workspace/token-usage-indicator.tsx](../src/components/workspace/token-usage-indicator.tsx) 累计当前线程 +- 单条消息：[components/workspace/messages/message-token-usage.tsx](../src/components/workspace/messages/message-token-usage.tsx) + `use-message-metrics.ts`，依赖 `tokenlens` 包 + +--- + +## 16. 通知、快捷键、命令面板 + +- 浏览器通知：[core/notification/hooks.ts](../src/core/notification/hooks.ts) 提供 `useNotification().showNotification(title, opts)`，在 `document.hidden || !hasFocus()` 时调用 +- 全局快捷键：[hooks/use-global-shortcuts.ts](../src/hooks/use-global-shortcuts.ts)，统一注册到 `window keydown`，过滤掉 input/textarea/contentEditable，但 `⌘K` 例外（用于唤起命令面板） +- 命令面板：[components/workspace/command-palette.tsx](../src/components/workspace/command-palette.tsx)（基于 `cmdk`） + +--- + +## 17. 定时任务、分享 + +### 17.1 定时任务 + +- [core/scheduled-tasks/](../src/core/scheduled-tasks/) 提供 cron / one-shot 任务的 CRUD 与运行历史 +- [components/workspace/scheduled-tasks/schedule-builder.tsx](../src/components/workspace/scheduled-tasks/schedule-builder.tsx) 是创建/编辑 UI +- 详情页 `ScheduledTaskRunDetailPage` 复用 MessageList 渲染历史一次运行 +- `markdown-docx.ts` 用 `docx` 包导出 Word + +### 17.2 只读分享 + +- 创建分享：[components/workspace/thread-share-dialogs.tsx](../src/components/workspace/thread-share-dialogs.tsx) + `core/thread-shares/` +- 只读页 `PublicSharePage`（路由 `/share/:shareCode`）/ `PublicScheduledTaskPage`（`/public/scheduled-tasks/:taskId`），不需要登录 +- 后端会用 share token 做权限校验，前端通过 `apiFetch` 自动带 + +--- + +## 18. 调试与测试 + +### 18.1 类型检查 + +```bash +pnpm typecheck +``` + +工程没有内置 ESLint/Prettier 配置（依赖 IDE/CI），但有少量 `// eslint-disable-next-line react-hooks/exhaustive-deps` 注释提示 dependencies 故意省略。 + +### 18.2 Mock 模式 + +URL 加 `?mock=true` 时，`useThreadChat()` 设 `isMock=true`，`getAPIClient(true)` 使用 `mock` 客户端，`getLangGraphBaseURL(true)` 回退到 `${origin}/mock/api`，便于离线复现 UI（需要后端或本地 mock server 配合）。 + +### 18.3 演示模式 + +`VITE_STATIC_WEBSITE_ONLY=true` 时： + +- 输入框 disabled，提示「演示模式不可用」 +- 自动展开 Artifacts 面板并选中第一个产物 +- 用于把构建产物嵌入营销页 / 静态主页 + +### 18.4 在浏览器调试 SSE + +LangGraph SDK 走标准 SSE。开发期通过 Chrome DevTools `Network -> EventSource` 可以直接查看 frames。失败原因（如 422）可在 sonner toast 看到 `getStreamErrorMessage()` 的解析结果。 + +--- + +## 19. 常见开发任务指南 + +### 19.1 新增一个聊天页内的子组件 + +1. 在 `src/components/workspace/` 下建目录与 `index.ts` +2. 通过 `useThread()`（来自 `messages/context.ts`）拿到当前 `thread` +3. 业务展示用 `` / `` 现有组件，避免自行 Markdown 解析 +4. 若依赖产物，使用 `useArtifacts()` + +### 19.2 新增一个 LangGraph Assistant（自定义 Agent） + +1. 后端注册新的 graph +2. 前端 `core/agents/api.ts` 增 CRUD 接口；`hooks.ts` 增 `useAgents/useAgent/useCreateAgent` +3. 路由：复用 `AgentChatPage`，URL `/page/workspace/agents/:agent_id/chats/:thread_id` +4. 提交时只需把 `assistantId` 传给 `useThreadStream`（参考 AgentChatPage 中传 `agent_id` 给后端 graph 的方式） + +### 19.3 新增一个领域 API + +1. 在 `core//` 建 `api.ts/hooks.ts/types.ts/index.ts` +2. `api.ts` 函数全部使用 `apiFetch(`${getBackendBaseURL()}/api/...`)` +3. `hooks.ts` 用 `useQuery({ queryKey: ["", ...] })` / `useMutation({ onSuccess: () => invalidateQueries })` +4. 在使用方 import `useXxx` 即可 + +### 19.4 新增一个全局快捷键 + +```tsx +useGlobalShortcuts([ + { key: "k", meta: true, action: openCommandPalette }, + { key: "/", meta: false, shift: true, action: showHelp }, +]); +``` + +### 19.5 修改本地偏好 + +```tsx +const [settings, setSettings] = useLocalSettings(); +setSettings("display", { streamSpeedMeterEnabled: false }); +``` + +线程级： + +```tsx +const [settings, setSettings] = useThreadSettings(threadId); +setSettings("context", { model_name: "gpt-5" }); // 仅当前线程 +``` + +### 19.6 新增 i18n 词条 + +1. 在 [core/i18n/translations.ts](../src/core/i18n/translations.ts) 与 `locales/` 下补充 +2. `useI18n().t.xxx.yyy` 使用 +3. 不要硬编码中英文文案到组件里 + +--- + +## 20. 性能与稳定性约定 + +- **TanStack Query**：键统一以「领域 + 操作 + params」组合（如 `["threads", "search", params]`、`["agents", id]`）；mutate 之后 invalidate；写时支持 `setQueriesData` 立即生效更新缓存（参考 `useDeleteThread`/`useRenameThread`） +- **流式断线续连**：保持 `useThreadStream` 的 `reconnectOnMount` 启用（已默认）；切换线程时会 reset `runMetadataStorageRef` 以确保不串 +- **乐观更新**：发送 message 立即出现 human 气泡，避免空白等待；附件场景额外提供 uploadingFiles 占位 +- **避免重复发送**：`sendInFlightRef` 在 `useThreadStream` 里做单飞锁 +- **不阻塞主线程**：长文 markdown 拆词、渲染时分批；`use-stick-to-bottom` 自动暂停跟随 +- **大依赖懒加载**：建议对低频路由（如 `Open Canvas`、`RoundtablePlanning`）使用 `React.lazy` + `Suspense`（当前已大致按模块切分，文件级可继续优化） +- **构建内存**：`pnpm build` 已 `--max-old-space-size=8192`，新增大依赖请关注 dist 体积与构建时长 + +--- + +## 21. 部署 + +- 默认构建产物 `dist/`，因 `base: "./"` 可直接置于任何静态文件路径 +- HashRouter 不需要后端 fallback，但建议把所有未匹配请求回退到 `index.html`，便于直接访问深链 +- 后端地址通过环境变量在 build-time 注入（Vite 把 `VITE_*` 内联到 bundle 中），不同环境请构建不同产物或使用窗口注入的方式 +- 内网部署时常配合 Nginx 反代 `/api -> 后端 Gateway`、`/api/langgraph -> LangGraph Server`，让前端使用同源相对路径无需额外 CORS + +--- + +## 22. 已知历史包袱与注意事项 + +1. **HashRouter + replaceState**：新建线程时 `history.replaceState` 直接改写 hash，不再触发 router 渲染。若以后改用 BrowserRouter，需要重写此处（参考 [ChatPage.tsx:75-79](../src/pages/ChatPage.tsx#L75-L79) 与 [chats/use-thread-chat.ts](../src/components/workspace/chats/use-thread-chat.ts) 的兜底） +2. **`"use client"` 指令**：迁移自 Next.js，在 Vite 中无意义但保留可读性，新文件可省略 +3. **Next.js shim**：尽量使用 `useRouteNavigate()`（[core/route-base.tsx](../src/core/route-base.tsx)）代替原始的 `useRouter().push("/page/workspace/...")`，因为后者依赖 base 替换，与你所在的路由模块强相关 +4. **混合 jsx/tsx**：`strategy-components/**` 内仍有 `.jsx`，新增请直接用 `.tsx` 并补全类型 +5. **TDesign**：仅在少量页面被使用，避免与 shadcn UI 风格混用；优先复用 `components/ui/` +6. **Open Canvas / Roundtable**：各自有独立的 Stream/Thread Context 与 API；不要直接在它们里复用主聊天的 `useThreadStream`，反之亦然 +7. **生产模式默认是 light，但 `index.html` 早期脚本默认 dark**：如果改默认主题，要同时改 [App.tsx:29](../src/App.tsx#L29) 的 `defaultTheme` 和 [index.html](../index.html) 的脚本 + +--- + +## 23. 速查表 + +| 我想… | 去哪里看 / 怎么写 | +|---|---| +| 改后端地址 | `.env.development[.local]` 中的 `VITE_BACKEND_BASE_URL` / `VITE_LANGGRAPH_BASE_URL` | +| 新增路由 | `pages/WorkspaceRoutes.tsx`（工作台）或 `pages/PageRoutes.tsx`（一级） | +| 发起 GET/POST | `apiFetch(`${getBackendBaseURL()}/api/...`, { method, body })` | +| 发起 SSE 聊天 | `useThreadStream({ threadId, context, ... })` | +| 跨标签同步偏好 | `useLocalSettings()` / `useThreadSettings(threadId)` | +| 弹 toast | `import { toast } from "sonner"; toast.success("done")` | +| 弹浏览器通知 | `useNotification().showNotification(title, { body })` | +| 国际化 | `const { t } = useI18n(); t.common.loading` | +| 合并 className | `cn("base", cond && "x-y")` | +| 获取登录态 | `getStoredAuth()` / `getAccessToken()` | +| 命令面板 | `⌘K` 唤起 `` | + +--- + +## 24. 后续建议 + +- **统一目录命名**：`workspace/messages/`、`workspace/artifacts/`、`workspace/chats/` 现都用 kebab-case 文件夹 + kebab-case 文件名；建议在新增文件时延续此约定 +- **抽离配置常量**：与服务端契约相关的硬编码（如 `assistantId = "lead_agent"`）建议集中到 `core/config/` +- **测试**：当前缺单测；优先为 `core/threads/hooks.ts` 的 `normalizeStoredRunId` 等纯函数补 vitest +- **包体积**：landing 视觉特效（`ogl`、`gsap`、`canvas-confetti`、`embla-carousel`）较重，可考虑路由级 code-split +- **lint/format**：建议引入 ESLint + Prettier + lint-staged，统一团队风格 + +--- + +## 25. 页面清单（Page Catalog） + +> 本节按一级路径分组，列出 [src/pages/](../src/pages/)、[src/open-canvas/pages/](../src/open-canvas/pages/) 与 [src/roundtable-planning/pages/](../src/roundtable-planning/pages/) 下的每一个页面：**做什么** + **挂载在哪里** + **关键依赖与组件**。 + +### 25.1 顶层路由（无 `/page` 前缀） + +#### LandingPage —— `/landing` + +- 文件：[LandingPage.tsx](../src/pages/LandingPage.tsx) +- 作用：营销/介绍主页，深色背景；与登录后的工作台无关 +- 强制 `light` 主题被 [App.tsx:23](../src/App.tsx#L23) 关掉，单独使用 `bg-[#0a0a0a]` +- 包含组件： + - [Header](../src/components/landing/header.tsx)、[Footer](../src/components/landing/footer.tsx) + - [Hero](../src/components/landing/hero.tsx) —— 首屏 Slogan + CTA + - [CaseStudySection](../src/components/landing/sections/case-study-section.tsx) —— 案例 + - [SkillsSection](../src/components/landing/sections/skills-section.tsx) + [ProgressiveSkillsAnimation](../src/components/landing/progressive-skills-animation.tsx) + - [SandboxSection](../src/components/landing/sections/sandbox-section.tsx) + [Terminal](../src/components/ui/terminal.tsx) + - [WhatsNewSection](../src/components/landing/sections/whats-new-section.tsx) + [PostList](../src/components/landing/post-list.tsx) + - [CommunitySection](../src/components/landing/sections/community-section.tsx) +- 视觉特效依赖：`aurora-text`、`flickering-grid`、`magic-bento`、`spotlight-card`、`shine-border`、`confetti-button`、`number-ticker`、`word-rotate`、`gsap`、`ogl`、`canvas-confetti`、`embla-carousel` + +#### LoginPage —— `/login`、`/login/:username` + +- 文件：[LoginPage.tsx](../src/pages/LoginPage.tsx) +- 作用：以用户名直登（默认 `guest`），从 query 解析 `pageSidebarEnabled` 偏好，登录成功后写入 `localStorage["deerflow.auth"]` 并跳到 `/page/workspace/chats/new` +- 关键依赖：[loginByUsername](../src/core/auth/api.ts)、[setStoredAuth](../src/core/auth/index.ts)、[persistSidebarEnabled](../src/core/page-layout/sidebar-enabled.ts) +- UI：极简卡片（Tailwind），仅在 `error` 时显示失败原因 + +#### PublicSharePage —— `/share/:shareCode` + +- 文件：[PublicSharePage.tsx](../src/pages/PublicSharePage.tsx) +- 作用：通过分享码免登录查看一段会话快照（含产物面板） +- 数据：[getPublicShareSnapshot](../src/core/thread-shares/api.ts) +- 内部布局：自建左右双栏（不依赖 WorkspaceLayout） + - 左：[MessageList](../src/components/workspace/messages/message-list.tsx) + - 右：[ArtifactFileDetail](../src/components/workspace/artifacts/artifact-file-detail.tsx)（点击文件后才显示） +- 自带 `` + `` + ``，用快照模拟 `BaseStream` + +#### PublicScheduledTaskPage —— `/public/scheduled-tasks/:taskId` + +- 文件：[PublicScheduledTaskPage.tsx](../src/pages/PublicScheduledTaskPage.tsx) +- 作用：免登录查看「已发布」的定时任务详情、最近运行结果、可下载文件 +- 包含组件：`Card`、`Tabs`、`Dialog`、`Tooltip`、`Badge`、[MarkdownContent](../src/components/workspace/messages/markdown-content.tsx)、[downloadMarkdownAsDocx](../src/core/scheduled-tasks/markdown-docx.ts) + +#### NotFoundPage —— `*` + +- 文件：[NotFoundPage.tsx](../src/pages/NotFoundPage.tsx) +- 作用：404 兜底，给一个 "Open workspace" 链接回到 `/page/workspace/chats/new` + +### 25.2 `/page/workspace/*`（工作台主区） + +> 所有页面外层套 ``（侧栏 + 内容区）。聊天类页面再多一层 ``（SubtasksProvider/ArtifactsProvider/PromptInputProvider）。 + +#### ChatsPage —— `/page/workspace/chats` + +- 文件：[ChatsPage.tsx](../src/pages/ChatsPage.tsx) +- 作用：会话列表与搜索；可触发「导入聊天记录」对话框 +- 数据：[useThreads()](../src/core/threads/hooks.ts) —— 过滤掉 `thread_type === "scheduler"` +- 包含组件： + - [WorkspaceContainer/Header/Body](../src/components/workspace/workspace-container.tsx) + - `Input`（搜索）、`Button`、`ScrollArea`、`Link` + - [ImportConversationsDialog](../src/components/workspace/thread-share-dialogs.tsx) +- 工具：`titleOfThread`、`usePathOfThread`、`formatTimeAgo`、`desensitize` + +#### ChatPage —— `/page/workspace/chats/:thread_id` + +- 文件：[ChatPage.tsx](../src/pages/ChatPage.tsx) +- 作用：主聊天页（绑定 `assistantId="lead_agent"`），支持新会话与已有会话；首条消息时若选中了 Agent，会跳转到 AgentChatPage +- Hook：[useThreadStream](../src/core/threads/hooks.ts)、[useThreadChat](../src/components/workspace/chats/use-thread-chat.ts)、[useThreadSettings](../src/core/settings/hooks.ts)、[useModels](../src/core/models/hooks.ts)、[useArtifacts](../src/components/workspace/artifacts/context.tsx)、[usePromptPrefixSettings](../src/core/system-settings/hooks.ts) +- 主要组件： + - [ChatBox](../src/components/workspace/chats/chat-box.tsx)（左聊天 / 右产物 双栏） + - [MessageList](../src/components/workspace/messages/message-list.tsx) + - [InputBox](../src/components/workspace/input-box.tsx) + [AgentSelector](../src/components/workspace/agents/agent-selector.tsx) + - [ThreadTitle](../src/components/workspace/thread-title.tsx) + - [TodoList](../src/components/workspace/todo-list.tsx) + - [TokenUsageIndicator](../src/components/workspace/token-usage-indicator.tsx) + - [ExportTrigger](../src/components/workspace/export-trigger.tsx)、[ArtifactTrigger](../src/components/workspace/artifacts/artifact-trigger.tsx) + - [Welcome](../src/components/workspace/welcome.tsx)（落地态欢迎） + +#### AgentChatPage —— `/page/workspace/agents/:agent_id/chats/:thread_id` + +- 文件：[AgentChatPage.tsx](../src/pages/AgentChatPage.tsx) +- 作用：与自定义 Agent 对话。`assistantId=agent_id`，context 注入 `agent_id`。会消费 `sessionStorage["pendingAgentMessage"]` 来自动发送 ChatPage 转交的首条消息 +- Hook：与 ChatPage 类似，但额外 `useAgent(agent_id)` +- 关键组件：与 ChatPage 同一套；顶栏额外渲染 Agent 名称 Badge；落地态使用 [AgentWelcome](../src/components/workspace/agent-welcome.tsx) + +#### AgentsPage —— `/page/workspace/agents` + +- 文件：[AgentsPage.tsx](../src/pages/AgentsPage.tsx)（薄壳，直接渲染 [AgentGallery](../src/components/workspace/agents/agent-gallery.tsx)） +- 作用：Agent 画廊；含分类、标签、特色、搜索、最近使用 +- 子组件：[AgentCard](../src/components/workspace/agents/agent-card.tsx)、[AgentManageDialog](../src/components/workspace/agents/agent-manage-dialog.tsx)、[TagSearchBar](../src/components/workspace/tags/tag-search-bar.tsx)、[TagPickerDialog](../src/components/workspace/tags/tag-picker-dialog.tsx)、[TagChipList](../src/components/workspace/tags/tag-chip.tsx) + +#### NewAgentPage —— `/page/workspace/agents/new` + +- 文件：[NewAgentPage.tsx](../src/pages/NewAgentPage.tsx) +- 作用：以「对话」的方式引导用户创建 Agent —— 复用 lead_agent 的 `is_bootstrap=true` 模式 + `SetupAgentApprovalMiddleware` 中拦截的 `setup_agent` 工具调用，让 LLM 给出 setup_agent 调用并由用户点「批准」最终落库 +- Hook：[useThreadStream](../src/core/threads/hooks.ts) + [useSkills](../src/core/skills/hooks.ts) + [useModels](../src/core/models/hooks.ts) + [checkAgentName/createAgent/updateAgent](../src/core/agents/api.ts) +- 组件： + - 左：表单（名称/描述/灵魂 prompt/模型/技能多选） + - 右：`` + ``（带 SetupAgentApprovalPayload 审批 UI） + - [SkillDetailDialog](../src/components/workspace/skills/skill-detail-dialog.tsx) + - 包了 `` + `` 与 ChatPage 同源 + +#### ScheduledTasksPage —— `/page/workspace/scheduled/tasks` + +- 文件：[ScheduledTasksPage.tsx](../src/pages/ScheduledTasksPage.tsx) +- 作用：当前用户的定时任务列表 + Cron 配置 + 已发布任务/可订阅、运行历史快览 +- Hook：[useScheduledTasks](../src/core/scheduled-tasks/hooks.ts)、`useScheduledTaskRuns`、`useScheduledTaskActions`、`usePublishedScheduledTasks`、`useScheduledTaskDeliveryProfile`、[useAgents](../src/core/agents/index.ts) +- 关键组件： + - [WorkspaceContainer/Header/Body](../src/components/workspace/workspace-container.tsx) + - [ScheduleBuilder](../src/components/workspace/scheduled-tasks/schedule-builder.tsx) + `buildCron/parseCron` + - [TagChipList](../src/components/workspace/tags/tag-chip.tsx) + [TagPickerDialog](../src/components/workspace/tags/tag-picker-dialog.tsx) + [TagSearchBar](../src/components/workspace/tags/tag-search-bar.tsx) + - `Card / Dialog / Tabs / Select / Switch / Textarea / Badge / Button` + +#### ScheduledTaskRunDetailPage —— `/page/workspace/scheduled/runs/:run_id` + +- 文件：[ScheduledTaskRunDetailPage.tsx](../src/pages/ScheduledTaskRunDetailPage.tsx) +- 作用：单次定时任务运行的详情；展示消息时间线、产物文件、状态、可重命名/删除/导出 docx +- Hook：[useScheduledTaskRun](../src/core/scheduled-tasks/hooks.ts)、`useScheduledTaskRunMessages`、`useScheduledTaskActions`、`getScheduledTaskRunFileContent`、`updateScheduledTaskRunFile`、`downloadScheduledTaskRunFile` +- 组件：`Tabs`、`Card`、[MarkdownContent](../src/components/workspace/messages/markdown-content.tsx)、`Textarea`（编辑结果文件） + +#### ScheduledChatPage（未在路由中显式注册，但留作入口跳转） + +- 文件：[ScheduledChatPage.tsx](../src/pages/ScheduledChatPage.tsx) +- 作用：从 `useSchedulerThread()` 拿到「调度器助手」线程 id 后立即 `Navigate` 到 `/page/workspace/chats/`，相当于一个智能跳板 +- 组件：[WorkspaceContainer/Body](../src/components/workspace/workspace-container.tsx) + Loading 提示文案 + +#### SkillsPage —— `/page/workspace/skills` + +- 文件：[SkillsPage.tsx](../src/pages/SkillsPage.tsx)（薄壳）→ [SkillSettingsPage](../src/components/workspace/settings/skill-settings-page.tsx) +- 作用：技能开关 + MCP Server 编辑入口 +- 子组件：[McpServerEditDialog](../src/components/workspace/settings/mcp-server-edit-dialog.tsx)、[SkillStateSheet](../src/components/workspace/settings/skill-state-sheet.tsx) + +#### SkillEvolutionPage —— `/page/workspace/skills/evolution` + +- 文件：[SkillEvolutionPage.tsx](../src/pages/SkillEvolutionPage.tsx)（薄壳）→ [SkillEvolutionPanel](../src/components/workspace/skills/skill-evolution-panel.tsx) +- 作用：技能演化（实验/进化曲线）展示 + +#### MemoryPage —— `/page/workspace/memory` + +- 文件：[MemoryPage.tsx](../src/pages/MemoryPage.tsx)（薄壳）→ [MemorySettingsPage](../src/components/workspace/settings/memory-settings-page.tsx) +- 作用：当前用户的记忆桶（事实/偏好/项目笔记）管理 +- 依赖 [core/memory/api.ts](../src/core/memory/api.ts) + `hooks.ts` + +#### AIWritingPage —— `/page/workspace/ai-writing` + +- 文件：[open-canvas/pages/AIWritingPage.tsx](../src/open-canvas/pages/AIWritingPage.tsx)（带 `hideAdvancedFields`） +- 作用：AI 写作主界面（左草稿/中聊天/右时间线），WorkspaceLayout 内嵌入 +- 见 §25.4 详解 + +#### RoundtablePlanningPage —— `/page/workspace/roundtable/planning` + +- 文件：[roundtable-planning/pages/RoundtablePlanningPage.tsx](../src/roundtable-planning/pages/RoundtablePlanningPage.tsx) +- 作用：圆桌规划三步流程（任务理解 → 编排 → 高保真报告） +- 见 §25.5 详解 + +### 25.3 管理员页（`/page/workspace/admin/*` 与 `settings/*`） + +> 路由元素层做了 `getStoredAuth()?.system_role === "admin"` 判断，非管理员被重定向到 `chats/new`。 + +#### AdminUserHubPage —— `/page/workspace/admin` + +- 文件：[AdminUserHubPage.tsx](../src/pages/AdminUserHubPage.tsx)（薄壳）→ [AdminUserHub](../src/components/workspace/admin/admin-user-hub.tsx) +- 作用：统一的「用户中心」聚合页（用户列表、活动、记忆查看），替代旧的多分支管理路由 +- 旧路径 `admin/users` / `admin/user-activity` / `admin/memory` 均 `Navigate` 到此页 + +#### AdminScheduledTasksPage —— `/page/workspace/admin/scheduled-tasks` + +- 文件：[AdminScheduledTasksPage.tsx](../src/pages/AdminScheduledTasksPage.tsx) +- 作用：全平台定时任务总览、暂停/恢复/编辑/删除/导出 +- Hook：[useAllScheduledTasks](../src/core/scheduled-tasks/hooks.ts)、`useAdminScheduledTaskActions`、`useAdminScheduledTaskRuns` +- 组件：[WorkspaceContainer/Header/Body](../src/components/workspace/workspace-container.tsx)、[ScheduleBuilder](../src/components/workspace/scheduled-tasks/schedule-builder.tsx)、`Card`、`Dialog`、`Badge`、`Input`、`Textarea` + +#### AdminUserActivityPage（路由已并入 AdminUserHub，但文件保留） + +- 文件：[AdminUserActivityPage.tsx](../src/pages/AdminUserActivityPage.tsx) +- 作用：按用户钻取其线程与消息（独立窗口模式） +- Hook：[useAllUsers](../src/core/auth/hooks.ts)、[useUserMemory / useUserThreadMessages / useUserThreads](../src/core/admin/hooks.ts) +- 组件：`Tabs`、`Input`、`ScrollArea`、`Badge`、左右两栏布局 + +#### AdminMemoryPage（已并入 Hub） + +- 文件：[AdminMemoryPage.tsx](../src/pages/AdminMemoryPage.tsx)（薄壳）→ [admin-memory-page.tsx](../src/components/workspace/admin/admin-memory-page.tsx) + +#### UsersPage（已并入 Hub） + +- 文件：[UsersPage.tsx](../src/pages/UsersPage.tsx)（薄壳）→ [UserManagementPage](../src/components/workspace/admin/user-management-page.tsx) +- 作用：账号管理（系统角色变更、密码重置等） + +#### TagsPage —— `/page/workspace/admin/tags` + +- 文件：[TagsPage.tsx](../src/pages/TagsPage.tsx)（薄壳）→ [TagManagementPage](../src/components/workspace/admin/tag-management-page.tsx) +- 作用：全局标签 CRUD（颜色、可见性、排序） + +#### LlmMetricsPage —— `/page/workspace/settings/llm-metrics` + +- 文件：[LlmMetricsPage.tsx](../src/pages/LlmMetricsPage.tsx) +- 作用：LLM 调用计量与工具计量 +- Hook：[useLlmMetrics](../src/core/llm-metrics/hooks.ts)、`downloadLlmMetricsExcel` +- 组件：`Tabs`、`Input`、`Select`、`Badge`、[ToolMetricsPanel](../src/components/workspace/admin/tool-metrics-panel.tsx) + +#### RecommendedQuestionsPage —— `/page/workspace/settings/recommended-questions` + +- 文件：[RecommendedQuestionsPage.tsx](../src/pages/RecommendedQuestionsPage.tsx) +- 作用：管理欢迎页/新会话落地的「推荐问题」（增删改、拖拽排序） +- Hook：[useRecommendedQuestions / useCreateRecommendedQuestion / useUpdateRecommendedQuestion / useDeleteRecommendedQuestion / useReorderRecommendedQuestions](../src/core/recommended-questions/hooks.ts) +- 组件：`Dialog`、`Input`、`Textarea`、`Button` + 自定义拖拽（HTML5 DnD） + +#### PromptPrefixSettingsPage —— `/page/workspace/settings/prompt-prefix` + +- 文件：[PromptPrefixSettingsPage.tsx](../src/pages/PromptPrefixSettingsPage.tsx) +- 作用：全局「前缀模式」开关、开关名称、prompt 内容；用户在新会话首轮可勾选附加该 prefix +- Hook：[usePromptPrefixSettings / useUpdatePromptPrefixSettings](../src/core/system-settings/hooks.ts) +- 组件：`Switch`、`Input`、`Textarea`、`Button` + +### 25.4 `/page/canvas/*`（开放画布 / AI 写作） + +> 由 [OpenCanvasRoutes.tsx](../src/open-canvas/routes/OpenCanvasRoutes.tsx) 注册，不在 WorkspaceLayout 内（直接挂在 PageRoutes 内容区）。 + +#### CanvasHomePage —— `/page/canvas` + +- 文件：[open-canvas/pages/CanvasHomePage.tsx](../src/open-canvas/pages/CanvasHomePage.tsx) +- 作用：画布首页，选择「新建文本文档」或「新建代码」→ 调 [createCanvasThread](../src/open-canvas/api/threads.ts) → 跳转到 `:thread_id` +- 组件：`Button` + Lucide 图标（`FileText/Code2/Sparkles/PenLine`） + +#### CanvasThreadPage —— `/page/canvas/:thread_id` + +- 文件：[open-canvas/pages/CanvasThreadPage.tsx](../src/open-canvas/pages/CanvasThreadPage.tsx) +- 作用：画布工作区，左右分栏：聊天 + 富文本/代码编辑 +- Provider 栈：[CanvasThreadProvider](../src/open-canvas/contexts/CanvasThreadContext.tsx) → [CanvasGraphProvider](../src/open-canvas/contexts/CanvasGraphContext.tsx) → [CanvasUIProvider](../src/open-canvas/contexts/CanvasUIContext.tsx) +- 子组件：[CanvasShell](../src/open-canvas/components/layout/CanvasShell.tsx) + - [CanvasHeader](../src/open-canvas/components/layout/CanvasHeader.tsx) + - [CanvasResizableLayout](../src/open-canvas/components/layout/CanvasResizableLayout.tsx) + - [CanvasChatPanel](../src/open-canvas/components/chat/CanvasChatPanel.tsx) + - [CanvasArtifactPanel](../src/open-canvas/components/artifact/CanvasArtifactPanel.tsx) + 各 renderer： + - [TextArtifactRenderer](../src/open-canvas/components/artifact/TextArtifactRenderer.tsx) + - [CodeArtifactRenderer](../src/open-canvas/components/artifact/CodeArtifactRenderer.tsx) + - [TiptapEditor](../src/open-canvas/editor/TiptapEditor.tsx) + [WritingBubbleMenu](../src/open-canvas/components/artifact/WritingBubbleMenu.tsx) / [WritingParagraphMenu](../src/open-canvas/components/artifact/WritingParagraphMenu.tsx) / [WritingAiMenu](../src/open-canvas/components/artifact/WritingAiMenu.tsx) / [WritingToolbar](../src/open-canvas/components/artifact/WritingToolbar.tsx) / [WritingRewritePreview](../src/open-canvas/components/artifact/WritingRewritePreview.tsx) + - [CanvasQuickActionBar](../src/open-canvas/components/artifact/CanvasQuickActionBar.tsx) / [CanvasArtifactVersionNav](../src/open-canvas/components/artifact/CanvasArtifactVersionNav.tsx) / [CanvasEmptyState](../src/open-canvas/components/artifact/CanvasEmptyState.tsx) + - [CanvasModelSelector](../src/open-canvas/components/selectors/CanvasModelSelector.tsx) +- Hook：[useCanvasStream](../src/open-canvas/hooks/useCanvasStream.ts)、`useCanvasArtifact`、`useCanvasThread`、`useCanvasQuickActions`、`useCanvasSelection`、`useWritingEditor`、`useDocumentOutline`、`useWritingRewrite` +- 与主聊天的隔离：使用 Canvas 自有的 LangGraph base URL（可选）、独立 thread/run API、独立编辑器扩展（[AiHighlightExtension](../src/open-canvas/editor/AiHighlightExtension.ts)） + +#### AIWritingPage —— `/page/canvas/ai-writing` 与 `/page/workspace/ai-writing` + +- 文件：[open-canvas/pages/AIWritingPage.tsx](../src/open-canvas/pages/AIWritingPage.tsx) +- 作用：受控的「AI 写作流程」 —— 启动写作 → SSE 进度 → 用户干预（intervention）→ 继续 → 评审 → 导出 docx +- 子组件： + - [AIWritingPageHeader](../src/open-canvas/components/ai-writing/AIWritingPageHeader.tsx) + - [AIWritingForm](../src/open-canvas/components/ai-writing/AIWritingForm.tsx) + - [AIWritingDraftPanel](../src/open-canvas/components/ai-writing/AIWritingDraftPanel.tsx) + [AIWritingPanel](../src/open-canvas/components/ai-writing/AIWritingPanel.tsx) + - [AIWritingTimeline](../src/open-canvas/components/ai-writing/AIWritingTimeline.tsx) + [TimelineStep](../src/open-canvas/components/ai-writing/TimelineStep.tsx) + - [AIWritingHistoryDropdown](../src/open-canvas/components/ai-writing/AIWritingHistoryDropdown.tsx) + [AIWritingHistoryView](../src/open-canvas/components/ai-writing/AIWritingHistoryView.tsx) + - [IntentStreamingView](../src/open-canvas/components/ai-writing/IntentStreamingView.tsx) / [IntentResultCard](../src/open-canvas/components/ai-writing/IntentResultCard.tsx) + - [OutlineStreamingView](../src/open-canvas/components/ai-writing/OutlineStreamingView.tsx) / [OutlineCard](../src/open-canvas/components/ai-writing/OutlineCard.tsx) / [OutlineSection](../src/open-canvas/components/ai-writing/OutlineSection.tsx) + - [DraftStreamingView](../src/open-canvas/components/ai-writing/DraftStreamingView.tsx) + - [ReviewStreamingView](../src/open-canvas/components/ai-writing/ReviewStreamingView.tsx) / [ReviewCard](../src/open-canvas/components/ai-writing/ReviewCard.tsx) / [ScoreBar](../src/open-canvas/components/ai-writing/ScoreBar.tsx) / [IssueList](../src/open-canvas/components/ai-writing/IssueList.tsx) + - [InterventionCard](../src/open-canvas/components/ai-writing/InterventionCard.tsx) / [CompletedInterventionCard](../src/open-canvas/components/ai-writing/CompletedInterventionCard.tsx) / [RevisionSummaryCard](../src/open-canvas/components/ai-writing/RevisionSummaryCard.tsx) + - [MaterialsToolbar](../src/open-canvas/components/ai-writing/MaterialsToolbar.tsx) / [MaterialsCard](../src/open-canvas/components/ai-writing/MaterialsCard.tsx) / [MaterialItem](../src/open-canvas/components/ai-writing/MaterialItem.tsx) + - [DraftOutlineSidebar](../src/open-canvas/components/artifact/DraftOutlineSidebar.tsx) / [WritingSkeletonCard](../src/open-canvas/components/ai-writing/WritingSkeletonCard.tsx) / [CollapseTransition](../src/open-canvas/components/ai-writing/CollapseTransition.tsx) +- Hook：[useAIWritingSessions](../src/open-canvas/hooks/useAIWritingSessions.ts)、[useAIWritingStream](../src/open-canvas/hooks/useAIWritingStream.ts)、[useArticleTypes](../src/open-canvas/hooks/useArticleTypes.ts)、[useWritingRewrite](../src/open-canvas/hooks/useWritingRewrite.ts)、[useDocumentOutline](../src/open-canvas/hooks/useDocumentOutline.ts) +- API：[ai-writing-sessions.ts](../src/open-canvas/api/ai-writing-sessions.ts)、[rewrite.ts](../src/open-canvas/api/rewrite.ts)、[writing-export.ts](../src/open-canvas/api/writing-export.ts)、[ai-writing-article-types.ts](../src/open-canvas/api/ai-writing-article-types.ts) +- 文件头有大段 Docker 内网部署排错指南（transcript 500 / resume 400 / 会话丢失），新成员部署前请先读 + +#### ArticleTypesConfigPage —— `/page/canvas/article-types` + +- 文件：[open-canvas/pages/ArticleTypesConfigPage.tsx](../src/open-canvas/pages/ArticleTypesConfigPage.tsx) +- 作用：AI 写作「文章类型」配置（标题/描述/默认 prompt 等） +- Hook：[useArticleTypes](../src/open-canvas/hooks/useArticleTypes.ts) +- 组件：`Button`、`Separator`、`Dialog` + 自定义 input/textarea 样式常量 + +### 25.5 `/page/roundtable/*`（圆桌规划） + +#### RoundtablePlanningPage —— `/page/roundtable/planning` + +- 文件：[roundtable-planning/pages/RoundtablePlanningPage.tsx](../src/roundtable-planning/pages/RoundtablePlanningPage.tsx) +- 作用：三步式多 Agent 圆桌规划（任务理解 → 编排 → 高保真报告） +- Hook： + - [useStep1Intent](../src/roundtable-planning/hooks/useStep1Intent.ts) —— 任务理解、INTENT_READY、澄清卡 + - [useStep2Orchestration](../src/roundtable-planning/hooks/useStep2Orchestration.ts) —— 编排循环、对话流、Persona 覆盖、澄清回复 + - [useDraftPersistence](../src/roundtable-planning/hooks/useDraftPersistence.ts) —— 本地草稿（自动保存/手动/加载/重命名/删除） + - [useAutoScroll](../src/roundtable-planning/hooks/useAutoScroll.ts) +- 组件： + - [Step1Panel](../src/roundtable-planning/components/Step1Panel.tsx) / [Step2Panel](../src/roundtable-planning/components/Step2Panel.tsx) / [Step3Panel](../src/roundtable-planning/components/Step3Panel.tsx) + - [PersonaDrawer](../src/roundtable-planning/components/PersonaDrawer.tsx) + - [Avatars](../src/roundtable-planning/components/Avatars.tsx)（含 BUILTIN_AGENT_META） + - [MessageBubble](../src/roundtable-planning/components/MessageBubble.tsx) / [MessageStepsCard](../src/roundtable-planning/components/MessageStepsCard.tsx) + - [IntentClarificationCard](../src/roundtable-planning/components/IntentClarificationCard.tsx) + - [RecommendAgentsDialog](../src/roundtable-planning/components/RecommendAgentsDialog.tsx) + - [HighFidelityReport](../src/roundtable-planning/components/HighFidelityReport.tsx) —— Step3 报告呈现 + - [ArtifactPreviewModal](../src/roundtable-planning/components/ArtifactPreviewModal.tsx) + - [ScrollToBottomButton](../src/roundtable-planning/components/ScrollToBottomButton.tsx) +- API：[intent.ts](../src/roundtable-planning/api/intent.ts) / [multi-agent.ts](../src/roundtable-planning/api/multi-agent.ts) / [recommend.ts](../src/roundtable-planning/api/recommend.ts) +- 工具：[clarification.ts](../src/roundtable-planning/lib/clarification.ts)、[step-display.tsx](../src/roundtable-planning/lib/step-display.tsx)、[reasoning.ts](../src/roundtable-planning/lib/reasoning.ts)、[roundtable-constants.ts](../src/roundtable-planning/lib/roundtable-constants.ts)、[drafts.ts](../src/roundtable-planning/utils/drafts.ts) +- 注意（来自文件头注释）： + 1. special 顺序派活，**不要**改回 `Promise.all` + 2. `step1InitGenRef / step2InitRef` 闸门用于规避 StrictMode 双 mount 副作用 + 3. 离开 Step 2 不销毁 threadIds，允许返回继续看 + 4. 草稿自动保存仅在 1→2、2→3 前进时触发 + 5. Persona 抽屉改的 model 不立即重启编排，下一轮才生效 + 6. 默认 `availableModels[0].name`，Persona 覆盖更高优先级 + +### 25.6 `/page/strategy/*`（策略路由） + +> [StrategyRoutes.tsx](../src/pages/StrategyRoutes.tsx) 复用了 WorkspaceRoutes 内大多数页面，**不带** WorkspaceLayout/PageSidebar，由 SidebarProvider 单独维持。`` 让 `useRouter` 跳转保持在策略前缀下。 + +- `qa/general` → [GeneralQA](../src/strategy-components/components/qa/GeneralQA.tsx)（综合问答中心） + - 子模块：[AgentQA](../src/strategy-components/components/qa/AgentQA.tsx)、[CollaborativeQA](../src/strategy-components/components/qa/CollaborativeQA.tsx)、[MopeChat](../src/strategy-components/components/qa/MopeChat.tsx)、[QA](../src/strategy-components/components/qa/QA.tsx)、[QACenterPage](../src/strategy-components/components/qa/QACenterPage.tsx)、[QACommon](../src/strategy-components/components/qa/QACommon.tsx)、[QALayout](../src/strategy-components/components/qa/QALayout.tsx)、[QATypeSwitch](../src/strategy-components/components/qa/QATypeSwitch.tsx)、[Template6BEditor](../src/strategy-components/components/qa/Template6BEditor.tsx)、[TemplateEditor](../src/strategy-components/components/qa/TemplateEditor.tsx)、[GeneralQAConfigSidebar](../src/strategy-components/components/qa/GeneralQAConfigSidebar.tsx)、[GeneralQAHeader](../src/strategy-components/components/qa/GeneralQAHeader.tsx) + - 子组件：[AgentCard](../src/strategy-components/components/qa/components/AgentCard.tsx)、[ConfigPanel](../src/strategy-components/components/qa/components/ConfigPanel.tsx)、[FinalReport](../src/strategy-components/components/qa/components/FinalReport.tsx)、[MarkdownContent](../src/strategy-components/components/qa/components/MarkdownContent.tsx)、[ProgressSidebar](../src/strategy-components/components/qa/components/ProgressSidebar.tsx)、[ScenarioConfigPage](../src/strategy-components/components/qa/components/ScenarioConfigPage.tsx)、[Sidebar](../src/strategy-components/components/qa/components/Sidebar.tsx)、[Timeline](../src/strategy-components/components/qa/components/Timeline.tsx) +- `light-app/new-note` → [LightAppNewNotePage.tsx](../src/pages/LightAppNewNotePage.tsx) + - 作用：轻应用「新建笔记」入口；调用独立的笔记服务 `VITE_NOTE_API_BASE_URL`，使用 [useNoteAuth](../src/hooks/useNoteAuth.ts) 完成笔记服务自有的鉴权 + - API：[createSearchSpace](../src/core/note/api.ts) +- `light-app/notes` → [LightAppNoteListPage.tsx](../src/pages/LightAppNoteListPage.tsx) + - 作用：笔记列表，支持网格/列表视图切换 + - API：[listSearchSpaces](../src/core/note/api.ts) +- `light-app/note-qa` → [LightAppNoteQAPage.tsx](../src/pages/LightAppNoteQAPage.tsx) + - 作用：基于笔记的提问入口（UI 雏形，详细问答尚在开发） +- 其余路径（chats / agents / skills / memory / scheduled / settings / admin）**直接复用** WorkspaceRoutes 中的页面文件，仅 base 不同 + +### 25.7 路由与页面对照速查 + +| 一级路径 | 进入路由文件 | 主要页面文件 | +|---|---|---| +| `/login`、`/login/:username` | App.tsx | LoginPage.tsx | +| `/landing` | App.tsx | LandingPage.tsx | +| `/share/:shareCode` | App.tsx | PublicSharePage.tsx | +| `/public/scheduled-tasks/:taskId` | App.tsx | PublicScheduledTaskPage.tsx | +| `/page/workspace/*` | PageRoutes.tsx → WorkspaceRoutes.tsx | ChatsPage / ChatPage / AgentsPage / NewAgentPage / AgentChatPage / SkillsPage / SkillEvolutionPage / MemoryPage / ScheduledTasksPage / ScheduledTaskRunDetailPage / AdminUserHubPage / AdminScheduledTasksPage / TagsPage / RecommendedQuestionsPage / PromptPrefixSettingsPage / LlmMetricsPage | +| `/page/strategy/*` | PageRoutes.tsx → StrategyRoutes.tsx | GeneralQA + LightApp* + 复用 Workspace 页面 | +| `/page/canvas/*` | PageRoutes.tsx → open-canvas/routes/OpenCanvasRoutes.tsx | CanvasHomePage / CanvasThreadPage / AIWritingPage / ArticleTypesConfigPage | +| `/page/roundtable/*` | PageRoutes.tsx → RoundtableRoutes.tsx | RoundtablePlanningPage | +| `*` | App.tsx | NotFoundPage | + +### 25.8 "薄壳页面"与"重逻辑页面" + +| 页面 | 类型 | 真正实现位置 | +|---|---|---| +| AgentsPage | 薄壳 | components/workspace/agents/agent-gallery.tsx | +| AdminUserHubPage | 薄壳 | components/workspace/admin/admin-user-hub.tsx | +| AdminMemoryPage | 薄壳 | components/workspace/admin/admin-memory-page.tsx | +| UsersPage | 薄壳 | components/workspace/admin/user-management-page.tsx | +| TagsPage | 薄壳 | components/workspace/admin/tag-management-page.tsx | +| SkillsPage | 薄壳 | components/workspace/settings/skill-settings-page.tsx | +| SkillEvolutionPage | 薄壳 | components/workspace/skills/skill-evolution-panel.tsx | +| MemoryPage | 薄壳 | components/workspace/settings/memory-settings-page.tsx | +| 其余 | 重逻辑 | 直接在 pages/ 内实现 | + +> 维护建议：薄壳页面只负责 layout/insets，业务逻辑请始终下沉到 `components/workspace//` 下方便复用与测试。 + +--- + +> 本文档与代码同步演进。若发现内容与实现不符，请优先以代码为准并更新本文。 diff --git a/frontend-web/src/App.tsx b/frontend-web/src/App.tsx index 155c3f64..ea03c986 100644 --- a/frontend-web/src/App.tsx +++ b/frontend-web/src/App.tsx @@ -3,6 +3,7 @@ import { Navigate, Route, Routes } from "react-router-dom"; import { ThemeProvider as NextThemesProvider } from "next-themes"; import { QueryClientProvider } from "@/components/query-client-provider"; +import { AuthSyncWatcher } from "@/core/auth/sync"; import { I18nProvider } from "@/core/i18n/context"; import { detectLocale } from "@/core/i18n/locale"; import { ChatProvider } from "@/contexts/ChatContext"; @@ -31,13 +32,18 @@ function AppProviders({ children }: { children: React.ReactNode }) { disableTransitionOnChange forcedTheme={forcedTheme} > - - - - {children} - - - + {/* QueryClientProvider must wrap ThemeProvider because the custom + ThemeProvider reads the admin-configured default via useQuery. */} + + + + + + {children} + + + + ); } diff --git a/frontend-web/src/components/page-sidebar.tsx b/frontend-web/src/components/page-sidebar.tsx index b4e32a8f..810e9e74 100644 --- a/frontend-web/src/components/page-sidebar.tsx +++ b/frontend-web/src/components/page-sidebar.tsx @@ -26,6 +26,7 @@ import { ListTodo, MessageSquareCode, MessageSquarePlus, + ShieldCheck, Network, NotebookPen, Plus, @@ -175,7 +176,7 @@ const menuItems: MenuItem[] = [ { id: "mgmt-memory", label: "记忆管理", icon: Brain, path: "/page/strategy/memory" }, { id: "mgmt-tasks", - label: "任务管理", + label: "定时任务", icon: ListChecks, path: "/page/strategy/scheduled/tasks", }, @@ -193,6 +194,13 @@ const menuItems: MenuItem[] = [ path: "/page/strategy/settings/prompt-prefix", adminOnly: true, }, + { + id: "mgmt-private-square", + label: "私密广场配置", + icon: ShieldCheck, + path: "/page/strategy/settings/private-square", + adminOnly: true, + }, { id: "mgmt-llm-metrics", label: "大模型调用统计", diff --git a/frontend-web/src/components/workspace/agents/agent-card.tsx b/frontend-web/src/components/workspace/agents/agent-card.tsx index 0842da4e..704ebd87 100644 --- a/frontend-web/src/components/workspace/agents/agent-card.tsx +++ b/frontend-web/src/components/workspace/agents/agent-card.tsx @@ -6,6 +6,7 @@ import { InfoIcon, LockIcon, MessageSquareIcon, + ShieldIcon, SparklesIcon, SquarePenIcon, TagsIcon, @@ -42,6 +43,7 @@ import { TagPickerDialog } from "@/components/workspace/tags/tag-picker-dialog"; import { useDeleteAgent, useSetAgentFeatured, + useSetAgentPrivate, useUpdateAgent, } from "@/core/agents"; import type { Agent } from "@/core/agents"; @@ -61,6 +63,7 @@ export function AgentCard({ agent }: AgentCardProps) { const deleteAgent = useDeleteAgent(); const updateAgent = useUpdateAgent(); const setFeatured = useSetAgentFeatured(); + const setPrivate = useSetAgentPrivate(); const { skills, isLoading: isSkillsLoading } = useSkills(); const [deleteOpen, setDeleteOpen] = useState(false); const [editOpen, setEditOpen] = useState(false); @@ -69,6 +72,7 @@ export function AgentCard({ agent }: AgentCardProps) { const [editDescription, setEditDescription] = useState(agent.description ?? ""); const [editSoul, setEditSoul] = useState(agent.soul ?? ""); const [editPublished, setEditPublished] = useState(agent.published); + const [editIsPrivate, setEditIsPrivate] = useState(agent.is_private); const [selectedSkills, setSelectedSkills] = useState( agent.skills ?? [], ); @@ -81,11 +85,12 @@ export function AgentCard({ agent }: AgentCardProps) { const isOwned = !isBuiltin && agent.user_id !== null && agent.user_id === currentUserId; const isFromOthers = !isBuiltin && !isOwned; - // System admins are allowed to edit and delete built-in agents. + // System admins are allowed to edit and delete any agent (built-in or owned + // by another user) so the admin console can manage the full catalog. // Publish-toggle stays owner-only — built-ins are inherently visible to // everyone so toggling published is moot. - const canEdit = isOwned || (isBuiltin && isAdmin); - const canDelete = isOwned || (isBuiltin && isAdmin); + const canEdit = isOwned || isAdmin; + const canDelete = isOwned || isAdmin; useEffect(() => { if (!editOpen) { @@ -95,9 +100,11 @@ export function AgentCard({ agent }: AgentCardProps) { setEditDescription(agent.description ?? ""); setEditSoul(agent.soul ?? ""); setEditPublished(agent.published); + setEditIsPrivate(agent.is_private); setSelectedSkills(agent.skills ?? []); }, [ agent.description, + agent.is_private, agent.name, agent.published, agent.skills, @@ -125,6 +132,10 @@ export function AgentCard({ agent }: AgentCardProps) { toast.error(t.agents.nameStepInvalidError ?? "名称不能为空"); return; } + if (editIsPrivate && editPublished) { + toast.warning("私密广场与公开发布互斥，请只勾选其一"); + return; + } try { await updateAgent.mutateAsync({ id: agent.id, @@ -132,7 +143,10 @@ export function AgentCard({ agent }: AgentCardProps) { name: trimmedName, description: editDescription, soul: editSoul, - published: editPublished, + // Private agents cannot also be published — force the value the + // backend will see, regardless of any stale state in editPublished. + published: editIsPrivate ? false : editPublished, + is_private: editIsPrivate, skills: selectedSkills, }, }); @@ -144,6 +158,13 @@ export function AgentCard({ agent }: AgentCardProps) { } async function handleTogglePublished() { + // Private and public squares are mutually exclusive — a private agent + // can't simultaneously be published to everyone. Block the toggle + // instead of silently moving the agent between squares. + if (!agent.published && agent.is_private) { + toast.warning("该智能体已加入私密广场，不可发布"); + return; + } try { await updateAgent.mutateAsync({ id: agent.id, @@ -155,6 +176,27 @@ export function AgentCard({ agent }: AgentCardProps) { } } + async function handleTogglePrivate() { + const turningOn = !agent.is_private; + try { + if (isOwned) { + // Owners can re-categorize their own agents through the normal update + // endpoint — keeps publish/private edits in one transaction. + await updateAgent.mutateAsync({ + id: agent.id, + request: { is_private: turningOn }, + }); + } else { + // Admins can move any agent (built-in or other users') via the + // dedicated admin endpoint. + await setPrivate.mutateAsync({ id: agent.id, isPrivate: turningOn }); + } + toast.success(turningOn ? "已加入私密广场" : "已移出私密广场"); + } catch (err) { + toast.error(err instanceof Error ? err.message : String(err)); + } + } + async function handleToggleFeatured() { // One-click on/off — ordering is handled by the dedicated 管理 Agent 列表 // dialog. Featured agents get appended to the end on add (Date.now() is a @@ -229,7 +271,7 @@ export function AgentCard({ agent }: AgentCardProps) { 来自他人 )} - {isOwned && agent.published && ( + {isOwned && agent.published && !agent.is_private && ( )} + {agent.is_private && ( + + + 私密 + + )} {agent.featured_order != null && ( )} - - + {(canEdit || canDelete || isOwned || isAdmin) && ( -
+
{isAdmin && ( + )} {canEdit && ( @@ -467,12 +537,41 @@ export function AgentCard({ agent }: AgentCardProps) {

公开发布

- 打开后,该智能体对所有用户可见。 + {editIsPrivate + ? "已加入私密广场，不可发布；请先关闭私密广场。" + : "打开后,该智能体对所有用户可见。"}

{ + if (editIsPrivate) { + toast.warning("该智能体已加入私密广场，不可发布"); + return; + } + setEditPublished(v); + }} + /> +
+
+
+

加入私密广场

+

+ 打开后,该智能体仅在私密广场显示,需输入密码才能查看;与「公开发布」互斥。 +

+
+ { + setEditIsPrivate(v); + if (v) { + // Mutual-exclusion: switching the agent into the private + // square automatically clears the public-publish flag so + // the user can't end up with a half-and-half state. + setEditPublished(false); + } + }} />
diff --git a/frontend-web/src/components/workspace/agents/agent-gallery.tsx b/frontend-web/src/components/workspace/agents/agent-gallery.tsx index cdce912f..10001772 100644 --- a/frontend-web/src/components/workspace/agents/agent-gallery.tsx +++ b/frontend-web/src/components/workspace/agents/agent-gallery.tsx @@ -1,44 +1,138 @@ "use client"; -import { BotIcon, PlusIcon } from "lucide-react"; +import { BotIcon, LockIcon, PlusIcon, ShieldIcon } from "lucide-react"; import { useRouter } from "next/navigation"; -import { useMemo, useState } from "react"; +import { useEffect, useMemo, useState } from "react"; +import { toast } from "sonner"; import { Button } from "@/components/ui/button"; +import { Input } from "@/components/ui/input"; import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"; import { TagSearchBar } from "@/components/workspace/tags/tag-search-bar"; -import { useAgents } from "@/core/agents"; +import { useAgents, usePrivateAgents } from "@/core/agents"; +import type { Agent } from "@/core/agents"; import { getStoredAuth } from "@/core/auth"; import { useI18n } from "@/core/i18n/hooks"; +import { usePrivateSquareStatus } from "@/core/system-settings/hooks"; +import { desensitize } from "@/lib/desensitize"; import { AgentCard } from "./agent-card"; +// Within a single tab the verified password is kept in sessionStorage so a +// refresh / route navigation does not re-prompt. Cleared on tab close, so the +// password never persists beyond the browsing session. +const PRIVATE_SQUARE_PASSWORD_KEY = "deer-flow.private-square-password"; + export function AgentGallery() { const { t } = useI18n(); const router = useRouter(); - const [activeTab, setActiveTab] = useState<"all" | "mine">("mine"); + const [activeTab, setActiveTab] = useState<"all" | "mine" | "private">( + "mine", + ); const [search, setSearch] = useState(""); const [tagIds, setTagIds] = useState([]); - // Name + tag filtering is resolved server-side via the /api/agents query. - const { agents, isLoading } = useAgents({ search, tagIds }); + // Tag filtering stays server-side; name search must run on the *desensitized* + // form because that's what the user sees on the card. If we sent the search + // string to the backend it would compare against the raw stored name and + // miss every desensitized hit (e.g. typing "TS分析" wouldn't match the + // stored "态势分析"). + const { agents, isLoading } = useAgents({ tagIds }); + + const needle = search.trim().toLowerCase(); + const matchesSearch = (a: Agent) => + !needle || desensitize(a.name).toLowerCase().includes(needle); const storedAuth = useMemo(() => getStoredAuth(), []); const currentUserId = storedAuth?.user_id ?? null; + const { data: privateStatus } = usePrivateSquareStatus(); + const privateFeatureAvailable = !!privateStatus?.enabled; + const privateFeatureUsable = + privateFeatureAvailable && !!privateStatus?.password_set; + + const [privatePassword, setPrivatePassword] = useState(() => { + if (typeof window === "undefined") return null; + return window.sessionStorage.getItem(PRIVATE_SQUARE_PASSWORD_KEY); + }); + const [passwordInput, setPasswordInput] = useState(""); + + const { + agents: privateAgents, + isLoading: isPrivateLoading, + error: privateError, + } = usePrivateAgents(privatePassword); + + // If the server reports the stored password no longer works (likely the + // admin rotated it), drop it from session storage and re-prompt. + useEffect(() => { + if (privatePassword && privateError) { + window.sessionStorage.removeItem(PRIVATE_SQUARE_PASSWORD_KEY); + setPrivatePassword(null); + toast.error("私密广场密码已失效，请重新输入"); + } + }, [privateError, privatePassword]); + + // The "广场" tab must never surface private-square agents, even to their + // own owner — moving an agent into the private square is supposed to hide + // it from the public square entirely. (The backend listing endpoint + // already filters them out for non-owners; this extra clause covers the + // owner's own private agents, which still come back in the unified list + // because owners always see their own.) const allAgents = useMemo( - () => agents.filter((a) => a.builtin || a.published), - [agents], + () => + agents.filter( + (a) => (a.builtin || a.published) && !a.is_private && matchesSearch(a), + ), + // matchesSearch closes over `needle`; depending on `search` is sufficient + // and avoids re-running on every render via the function reference. + // eslint-disable-next-line react-hooks/exhaustive-deps + [agents, search], ); const myAgents = useMemo( - () => agents.filter((a) => a.user_id !== null && a.user_id === currentUserId), - [agents, currentUserId], + () => + agents.filter( + (a) => + a.user_id !== null && + a.user_id === currentUserId && + matchesSearch(a), + ), + // eslint-disable-next-line react-hooks/exhaustive-deps + [agents, currentUserId, search], ); + const filteredPrivateAgents = useMemo(() => { + const wanted = new Set(tagIds); + return privateAgents.filter((a) => { + if (!matchesSearch(a)) return false; + if (wanted.size > 0) { + if (!(a.tags ?? []).some((tg) => wanted.has(tg.id))) return false; + } + return true; + }); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [privateAgents, search, tagIds]); + const handleNewAgent = () => { router.push("/page/workspace/agents/new"); }; + const handleSubmitPassword = () => { + const trimmed = passwordInput.trim(); + if (!trimmed) { + toast.error("请输入密码"); + return; + } + window.sessionStorage.setItem(PRIVATE_SQUARE_PASSWORD_KEY, trimmed); + setPrivatePassword(trimmed); + setPasswordInput(""); + }; + + const handleLockPrivate = () => { + window.sessionStorage.removeItem(PRIVATE_SQUARE_PASSWORD_KEY); + setPrivatePassword(null); + }; + const renderGrid = (list: typeof agents) => (
{list.map((agent) => ( @@ -65,6 +159,78 @@ export function AgentGallery() {
); + const renderPrivateTab = () => { + if (!privateFeatureAvailable) { + return ( +
+
+ +
+

私密广场尚未开启

+

+ 请管理员前往「综合管理 → 私密广场配置」开启该功能并设置密码。 +

+
+ ); + } + + if (!privateFeatureUsable) { + return ( +
+
+ +
+

私密广场未配置密码

+

+ 请管理员在私密广场配置页设置一个访问密码。 +

+
+ ); + } + + if (!privatePassword) { + return ( +
+
+ +
+
+

私密广场

+

+ 请输入访问密码，验证通过后才能查看其中的智能体。 +

+
+
+ setPasswordInput(e.target.value)} + onKeyDown={(e) => { + if (e.key === "Enter") handleSubmitPassword(); + }} + /> + +
+
+ ); + } + + if (isPrivateLoading) { + return ( +
+ {t.common.loading} +
+ ); + } + + if (filteredPrivateAgents.length === 0) { + return renderEmpty("私密广场暂时还没有智能体。"); + } + + return renderGrid(filteredPrivateAgents); + }; + return (
{/* Page header */} @@ -84,14 +250,35 @@ export function AgentGallery() { {/* Tabs */} setActiveTab(v as "all" | "mine")} + onValueChange={(v) => + setActiveTab(v as "all" | "mine" | "private") + } className="flex flex-1 flex-col overflow-hidden" >
- - 我的 - 广场 - +
+ + 我的 + 广场 + {privateFeatureAvailable && ( + + + 私密广场 + + )} + + {activeTab === "private" && privatePassword && ( + + )} +
+ + {privateFeatureAvailable && ( + + {renderPrivateTab()} + + )}
); diff --git a/frontend-web/src/components/workspace/agents/agent-manage-dialog.tsx b/frontend-web/src/components/workspace/agents/agent-manage-dialog.tsx index fab434ed..03231c51 100644 --- a/frontend-web/src/components/workspace/agents/agent-manage-dialog.tsx +++ b/frontend-web/src/components/workspace/agents/agent-manage-dialog.tsx @@ -61,7 +61,12 @@ export function AgentManageDialog({ const candidates = useMemo(() => { const existing = new Set(agents.map((a) => a.id)); - return allAgents.filter((a) => a.published && !existing.has(a.id)); + // Private-square agents are hidden from the homepage selector even if + // they're published — the backend ``list_featured`` filter would drop + // them again on the way out, so offering them here is just confusing. + return allAgents.filter( + (a) => a.published && !a.is_private && !existing.has(a.id), + ); }, [agents, allAgents]); const busy = setFeaturedMutation.isPending || reorderMutation.isPending; diff --git a/frontend-web/src/components/workspace/chats/chat-box.tsx b/frontend-web/src/components/workspace/chats/chat-box.tsx index dec47e42..20b6e434 100644 --- a/frontend-web/src/components/workspace/chats/chat-box.tsx +++ b/frontend-web/src/components/workspace/chats/chat-box.tsx @@ -1,183 +1,605 @@ -import { FilesIcon, XIcon } from "lucide-react"; -import { usePathname } from "next/navigation"; -import { useEffect, useMemo, useRef, useState } from "react"; -import type { GroupImperativeHandle } from "react-resizable-panels"; - -import { ConversationEmptyState } from "@/components/ai-elements/conversation"; -import { Button } from "@/components/ui/button"; -import { - ResizableHandle, - ResizablePanel, - ResizablePanelGroup, -} from "@/components/ui/resizable"; -import { env } from "@/env"; -import { cn } from "@/lib/utils"; - -import { - ArtifactFileDetail, - ArtifactFileList, - useArtifacts, -} from "../artifacts"; -import { useThread } from "../messages/context"; - -const CLOSE_MODE = { chat: 100, artifacts: 0 }; -const OPEN_MODE = { chat: 60, artifacts: 40 }; - -const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({ - children, - threadId, -}) => { - const { thread } = useThread(); - const pathname = usePathname(); - const threadIdRef = useRef(threadId); - const layoutRef = useRef(null); - - const { - artifacts, - open: artifactsOpen, - setOpen: setArtifactsOpen, - setArtifacts, - select: selectArtifact, - deselect, - selectedArtifact, - } = useArtifacts(); - - const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true); - useEffect(() => { - if (threadIdRef.current !== threadId) { - threadIdRef.current = threadId; - deselect(); - } - - // Update artifacts from the current thread - setArtifacts(thread.values.artifacts); - - // DO NOT automatically deselect the artifact when switching threads, because the artifacts auto discovering is not work now. - // if ( - // selectedArtifact && - // !thread.values.artifacts?.includes(selectedArtifact) - // ) { - // deselect(); - // } - - if ( - env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" && - autoSelectFirstArtifact - ) { - if (thread?.values?.artifacts?.length > 0) { - setAutoSelectFirstArtifact(false); - selectArtifact(thread.values.artifacts[0]!); - } - } - }, [ - threadId, - autoSelectFirstArtifact, - deselect, - selectArtifact, - selectedArtifact, - setArtifacts, - thread.values.artifacts, - ]); - - const artifactPanelOpen = useMemo(() => { - if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true") { - return artifactsOpen && artifacts?.length > 0; - } - return artifactsOpen; - }, [artifactsOpen, artifacts]); - - const resizableIdBase = useMemo(() => { - const raw = pathname - .replace(/[^a-zA-Z0-9_-]+/g, "-") - .replace(/^-+|-+$/g, ""); - return raw.length > 0 ? raw : `thread-${threadId}`; - }, [pathname, threadId]); - - useEffect(() => { - if (layoutRef.current) { - if (artifactPanelOpen) { - layoutRef.current.setLayout(OPEN_MODE); - } else { - layoutRef.current.setLayout(CLOSE_MODE); - } - } - }, [artifactPanelOpen]); - - return ( - - - {children} - - - -
- {selectedArtifact ? ( - - ) : ( -
-
- -
- {thread.values.artifacts?.length === 0 ? ( - } - title="No artifact selected" - description="Select an artifact to view its details" - /> - ) : ( -
-
-

Artifacts

-
-
- -
-
- )} -
- )} -
- - - ); -}; - -export { ChatBox }; +import type { Message } from "@langchain/langgraph-sdk"; +import { FilesIcon, XIcon } from "lucide-react"; +import { usePathname } from "next/navigation"; +import { useEffect, useMemo, useRef, useState } from "react"; +import type { GroupImperativeHandle } from "react-resizable-panels"; + +import { ConversationEmptyState } from "@/components/ai-elements/conversation"; +import { Button } from "@/components/ui/button"; +import { + ResizableHandle, + ResizablePanel, + ResizablePanelGroup, +} from "@/components/ui/resizable"; +import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"; +import { apiFetch } from "@/core/api"; +import { getBackendBaseURL } from "@/core/config"; +import { isThreadRagModeLocked, useLocalSettings } from "@/core/settings"; +import { useSkills } from "@/core/skills/hooks"; +import { + buildSkillDisplayMap, + collectRuntimeDisplaySources, +} from "@/core/skill-display/runtime"; +import { env } from "@/env"; +import { cn } from "@/lib/utils"; + +import { + ArtifactFileDetail, + ArtifactFileList, + useArtifacts, +} from "../artifacts"; +import { useThread } from "../messages/context"; +import { SkillDisplaySources } from "../skill-display-sources"; + +const CLOSE_MODE = { chat: 100, artifacts: 0 }; +const OPEN_MODE = { chat: 60, artifacts: 40 }; +const SHOW_REFERENCE_EVENT = "workspace:show-reference"; + +type BackendReferenceSource = Parameters[0]["sources"][number]; + +type BackendReferenceBatch = { + id: string; + assistant_message_id?: string; + sources: BackendReferenceSource[]; +}; + +function logReferenceDebug( + event: string, + threadId: string, + payload: Record, +) { + console.info(`[RAG引用调试] ${event}`, payload); + void apiFetch(`${getBackendBaseURL()}/api/threads/reference-debug-log`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + event, + thread_id: threadId, + payload, + }), + }).catch(() => { + // Debug logging must never affect the chat flow. + }); +} + +const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({ + children, + threadId, +}) => { + const { thread } = useThread(); + const pathname = usePathname(); + const threadIdRef = useRef(threadId); + const artifactsCountRef = useRef(0); + const layoutRef = useRef(null); + const latestReferenceBatchIdRef = useRef(null); + const manualReferenceBatchRef = useRef(false); + const referenceDebugSignatureRef = useRef(""); + const [sideTab, setSideTab] = useState("document"); + const [referencesOpen, setReferencesOpen] = useState(true); + const [activeReferenceBatchId, setActiveReferenceBatchId] = useState(null); + const [pinnedReferenceId, setPinnedReferenceId] = useState(null); + const [backendReferenceBatches, setBackendReferenceBatches] = useState([]); + const [settings] = useLocalSettings(); + const ragModeEnabled = + settings.display.ragModeEnabled || isThreadRagModeLocked(threadId); + const { skills } = useSkills(); + + const { + artifacts, + open: artifactsOpen, + setOpen: setArtifactsOpen, + setArtifacts, + select: selectArtifact, + deselect, + selectedArtifact, + } = useArtifacts(); + + const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true); + const skillDisplayMap = useMemo( + () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()), + [ragModeEnabled, skills], + ); + const fallbackReferenceBatches = useMemo(() => { + if (!ragModeEnabled) { + return []; + } + return buildTurnReferenceBatches( + thread.values.messages ?? [], + skillDisplayMap, + thread.isLoading, + ); + }, [ragModeEnabled, skillDisplayMap, thread.isLoading, thread.values.messages]); + useEffect(() => { + if (!ragModeEnabled) { + setBackendReferenceBatches([]); + return; + } + if (thread.isLoading) { + return; + } + const controller = new AbortController(); + logReferenceDebug("开始拉取后端参考文献", threadId, { + messageCount: thread.values.messages?.length ?? 0, + }); + apiFetch( + `${getBackendBaseURL()}/api/threads/${encodeURIComponent(threadId)}/reference-batches`, + { signal: controller.signal }, + ) + .then(async (response) => { + if (!response.ok) { + throw new Error(`Failed to load reference batches: ${response.status}`); + } + return (await response.json()) as { batches?: BackendReferenceBatch[] }; + }) + .then((data) => { + const batches = data.batches ?? []; + logReferenceDebug("后端参考文献返回", threadId, { + batchCount: batches.length, + sourceCounts: batches.map((batch) => batch.sources?.length ?? 0), + batchIds: batches.map((batch) => batch.id), + }); + setBackendReferenceBatches(batches); + }) + .catch((error) => { + if (!controller.signal.aborted) { + console.warn("Failed to load backend reference batches", error); + } + }); + return () => controller.abort(); + }, [ragModeEnabled, thread.isLoading, threadId, thread.values.messages]); + const referenceBatches = + backendReferenceBatches.length > 0 + ? backendReferenceBatches + : fallbackReferenceBatches; + useEffect(() => { + if (!ragModeEnabled) { + return; + } + const signature = JSON.stringify({ + backend: backendReferenceBatches.map((batch) => batch.sources?.length ?? 0), + fallback: fallbackReferenceBatches.map((batch) => batch.sources?.length ?? 0), + final: referenceBatches.map((batch) => batch.sources?.length ?? 0), + }); + if (referenceDebugSignatureRef.current === signature) { + return; + } + referenceDebugSignatureRef.current = signature; + logReferenceDebug("前端参考文献来源选择", threadId, { + using: backendReferenceBatches.length > 0 ? "后端接口" : "前端兜底", + backendBatchCount: backendReferenceBatches.length, + backendSourceCounts: backendReferenceBatches.map((batch) => batch.sources?.length ?? 0), + fallbackBatchCount: fallbackReferenceBatches.length, + fallbackSourceCounts: fallbackReferenceBatches.map((batch) => batch.sources?.length ?? 0), + finalBatchCount: referenceBatches.length, + finalSourceCounts: referenceBatches.map((batch) => batch.sources?.length ?? 0), + }); + }, [backendReferenceBatches, fallbackReferenceBatches, ragModeEnabled, referenceBatches, threadId]); + const latestReferenceBatch = + referenceBatches.length > 0 + ? referenceBatches[referenceBatches.length - 1]! + : null; + const activeReferenceBatch = + referenceBatches.find((batch) => batch.id === activeReferenceBatchId) ?? + latestReferenceBatch; + const referenceSources = activeReferenceBatch?.sources ?? []; + const hasCitationReferences = referenceSources.length > 0; + useEffect(() => { + if (hasCitationReferences) { + setReferencesOpen(true); + } + }, [hasCitationReferences]); + useEffect(() => { + if (!latestReferenceBatch) { + setActiveReferenceBatchId(null); + latestReferenceBatchIdRef.current = null; + manualReferenceBatchRef.current = false; + return; + } + const previousLatestId = latestReferenceBatchIdRef.current; + latestReferenceBatchIdRef.current = latestReferenceBatch.id; + setActiveReferenceBatchId((current) => + current && + referenceBatches.some((batch) => batch.id === current) && + manualReferenceBatchRef.current && + current !== previousLatestId + ? current + : latestReferenceBatch.id, + ); + }, [latestReferenceBatch?.id, referenceBatches]); + useEffect(() => { + const handleShowReference = (event: Event) => { + const detail = (event as CustomEvent<{ batchId?: string; referenceId?: string }>).detail; + if (detail?.batchId) { + manualReferenceBatchRef.current = true; + setActiveReferenceBatchId(detail.batchId); + } + setPinnedReferenceId(null); + window.setTimeout(() => { + setPinnedReferenceId(detail?.referenceId ?? null); + }, 0); + setReferencesOpen(true); + setSideTab("references"); + }; + window.addEventListener(SHOW_REFERENCE_EVENT, handleShowReference); + return () => { + window.removeEventListener(SHOW_REFERENCE_EVENT, handleShowReference); + }; + }, []); + useEffect(() => { + if (threadIdRef.current !== threadId) { + threadIdRef.current = threadId; + artifactsCountRef.current = 0; + deselect(); + setReferencesOpen(false); + setActiveReferenceBatchId(null); + setPinnedReferenceId(null); + setBackendReferenceBatches([]); + latestReferenceBatchIdRef.current = null; + manualReferenceBatchRef.current = false; + referenceDebugSignatureRef.current = ""; + } + + // Update artifacts from the current thread + const nextArtifacts = thread.values.artifacts ?? []; + const hadArtifacts = artifactsCountRef.current > 0; + const hasNewArtifact = nextArtifacts.length > artifactsCountRef.current; + artifactsCountRef.current = nextArtifacts.length; + setArtifacts(nextArtifacts); + if ((hasNewArtifact || (!hadArtifacts && nextArtifacts.length > 0)) && !selectedArtifact) { + selectArtifact(nextArtifacts[nextArtifacts.length - 1]!); + setArtifactsOpen(true); + setSideTab("document"); + } + + // DO NOT automatically deselect the artifact when switching threads, because the artifacts auto discovering is not work now. + // if ( + // selectedArtifact && + // !thread.values.artifacts?.includes(selectedArtifact) + // ) { + // deselect(); + // } + + if ( + env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" && + autoSelectFirstArtifact + ) { + if (thread?.values?.artifacts?.length > 0) { + setAutoSelectFirstArtifact(false); + selectArtifact(thread.values.artifacts[0]!); + } + } + }, [ + threadId, + autoSelectFirstArtifact, + deselect, + selectArtifact, + selectedArtifact, + setArtifacts, + thread.values.artifacts, + ]); + + const artifactPanelOpen = useMemo(() => { + if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true") { + return artifactsOpen && artifacts?.length > 0; + } + return artifactsOpen; + }, [artifactsOpen, artifacts]); + const sidePanelOpen = artifactPanelOpen || (hasCitationReferences && referencesOpen); + const showTabs = !!selectedArtifact && hasCitationReferences; + + useEffect(() => { + if (selectedArtifact) { + setSideTab("document"); + } else if (hasCitationReferences) { + setSideTab("references"); + } + }, [hasCitationReferences, selectedArtifact]); + + const resizableIdBase = useMemo(() => { + const raw = pathname + .replace(/[^a-zA-Z0-9_-]+/g, "-") + .replace(/^-+|-+$/g, ""); + return raw.length > 0 ? raw : `thread-${threadId}`; + }, [pathname, threadId]); + + useEffect(() => { + if (layoutRef.current) { + if (sidePanelOpen) { + layoutRef.current.setLayout(OPEN_MODE); + } else { + layoutRef.current.setLayout(CLOSE_MODE); + } + } + }, [sidePanelOpen]); + + return ( + + + {children} + + + +
+ {showTabs ? ( + +
+ + 文档 + 参考文献 + + +
+ + + + + + + + ) : selectedArtifact ? ( + + ) : hasCitationReferences ? ( +
+
+ +
+ +
+ ) : ( +
+
+ +
+ {thread.values.artifacts?.length === 0 ? ( + } + title="No artifact selected" + description="Select an artifact to view its details" + /> + ) : ( +
+
+

Artifacts

+
+
+ +
+
+ )} +
+ )} +
+ + + ); +}; + +function ReferencePanel({ + highlightedReferenceId, + sources, +}: { + highlightedReferenceId?: string | null; + sources: Parameters[0]["sources"]; +}) { + const orderedSources = useMemo(() => { + if (!highlightedReferenceId) { + return sources; + } + const index = Number(highlightedReferenceId); + if (!Number.isFinite(index)) { + return sources; + } + const selected = sources.find((source) => source.index === index); + if (!selected) { + return sources; + } + return [selected, ...sources.filter((source) => source.index !== index)]; + }, [highlightedReferenceId, sources]); + + return ( +
+
+
+

+ 参考文献 +

+ + {sources.length} 条 + +
+

+ 点击编号或卡片可查看引用详情。 +

+
+
+ +
+
+ ); +} + +function findPreviousHumanMessageId( + messages: Message[], + beforeMessageId?: string, +): string | undefined { + const beforeIndex = + beforeMessageId === undefined + ? messages.length + : messages.findIndex((message) => message.id === beforeMessageId); + const end = beforeIndex < 0 ? messages.length : beforeIndex; + for (let index = end - 1; index >= 0; index--) { + const message = messages[index]; + if (message?.type === "human") { + return message.id; + } + } + return undefined; +} + +function buildTurnReferenceBatches( + messages: Message[], + skillDisplayMap: ReturnType, + isLoading: boolean, +): BackendReferenceBatch[] { + const batches: BackendReferenceBatch[] = []; + for (let index = 0; index < messages.length; index++) { + const human = messages[index]; + if (human?.type !== "human" || !human.id) { + continue; + } + const nextHumanIndex = findNextHumanIndex(messages, index + 1); + if (nextHumanIndex === -1 && isLoading) { + continue; + } + const endIndex = nextHumanIndex === -1 ? messages.length : nextHumanIndex; + const assistant = findLastAssistantAnswer(messages, index + 1, endIndex); + if (!assistant?.id) { + continue; + } + const sources = collectRuntimeDisplaySources(messages, skillDisplayMap, { + afterMessageId: human.id, + beforeMessageId: + nextHumanIndex === -1 ? undefined : messages[nextHumanIndex]?.id, + includeBeforeMessage: false, + includeModes: ["citation"], + }).filter((source) => source.mode === "citation"); + if (sources.length > 0) { + batches.push({ + id: assistant.id, + assistant_message_id: assistant.id, + sources, + }); + } + } + return batches; +} + +function findNextHumanIndex(messages: Message[], start: number): number { + for (let index = start; index < messages.length; index++) { + if (messages[index]?.type === "human") { + return index; + } + } + return -1; +} + +function findLastAssistantAnswer( + messages: Message[], + start: number, + end: number, +): Message | null { + for (let index = end - 1; index >= start; index--) { + const message = messages[index]; + if ( + message?.type === "ai" && + message.id && + hasAssistantAnswerContent(message) && + !hasAssistantToolCalls(message) + ) { + return message; + } + } + return null; +} + +function hasAssistantAnswerContent(message: Message): boolean { + const content = message.content; + if (typeof content === "string") { + return content.trim().length > 0; + } + if (!Array.isArray(content)) { + return false; + } + return content.some((part) => { + if (!part || typeof part !== "object") { + return false; + } + const block = part as Record; + return block.type === "text" && typeof block.text === "string" && block.text.trim().length > 0; + }); +} + +function hasAssistantToolCalls(message: Message): boolean { + const direct = (message as { tool_calls?: unknown }).tool_calls; + if (Array.isArray(direct) && direct.length > 0) { + return true; + } + const chunks = (message as { tool_call_chunks?: unknown }).tool_call_chunks; + if (Array.isArray(chunks) && chunks.length > 0) { + return true; + } + const kwargs = (message as { additional_kwargs?: Record }).additional_kwargs; + const extra = kwargs?.tool_calls; + return Array.isArray(extra) && extra.length > 0; +} + +export { ChatBox }; diff --git a/frontend-web/src/components/workspace/chats/use-thread-chat.ts b/frontend-web/src/components/workspace/chats/use-thread-chat.ts index 54145f96..9bfaada8 100644 --- a/frontend-web/src/components/workspace/chats/use-thread-chat.ts +++ b/frontend-web/src/components/workspace/chats/use-thread-chat.ts @@ -2,12 +2,19 @@ import { useParams, usePathname, useSearchParams } from "next/navigation"; import { useEffect, useState } from "react"; +import { useLocation } from "react-router-dom"; import { uuid } from "@/core/utils/uuid"; export function useThreadChat() { const { thread_id: threadIdFromPath } = useParams<{ thread_id: string }>(); const pathname = usePathname(); + // ``location.key`` is regenerated on every react-router navigation, even when + // the resolved pathname is identical. We depend on it so that clicking + // "新对话" while already at /chats/new still triggers a fresh thread reset + // (otherwise navigate-to-same-path is silently a no-op and the in-flight + // conversation would persist on screen). + const locationKey = useLocation().key; const searchParams = useSearchParams(); const [threadId, setThreadId] = useState(() => { @@ -37,7 +44,7 @@ export function useThreadChat() { } setIsNewThread(false); setThreadId(threadIdFromPath); - }, [pathname, threadIdFromPath]); + }, [pathname, threadIdFromPath, locationKey]); const isMock = searchParams.get("mock") === "true"; return { threadId, setThreadId, isNewThread, setIsNewThread, isMock }; } diff --git a/frontend-web/src/components/workspace/citations/citation-link.tsx b/frontend-web/src/components/workspace/citations/citation-link.tsx index aecc71a8..438cbc99 100644 --- a/frontend-web/src/components/workspace/citations/citation-link.tsx +++ b/frontend-web/src/components/workspace/citations/citation-link.tsx @@ -1,82 +1,77 @@ -import { ExternalLinkIcon } from "lucide-react"; -import type { ComponentProps } from "react"; - -import { Badge } from "@/components/ui/badge"; -import { - HoverCard, - HoverCardContent, - HoverCardTrigger, -} from "@/components/ui/hover-card"; -import { cn } from "@/lib/utils"; - -export function CitationLink({ - href, - children, - ...props -}: ComponentProps<"a">) { - const domain = extractDomain(href ?? ""); - - // Priority: children > domain - const childrenText = - typeof children === "string" - ? children.replace(/^citation:\s*/i, "") - : null; - const isGenericText = childrenText === "Source" || childrenText === "来源"; - const displayText = (!isGenericText && childrenText) ?? domain; - - return ( - - - e.stopPropagation()} - {...props} - > - - {displayText} - - - - - -
-
- {displayText && ( -

- {displayText} -

- )} - {href && ( -

- {href} -

- )} -
- - Visit source - - -
- - - ); -} - -function extractDomain(url: string): string { - try { - return new URL(url).hostname.replace(/^www\./i, ""); - } catch { - return url; - } -} +import type { ComponentProps } from "react"; + +import { cn } from "@/lib/utils"; + +const SHOW_REFERENCE_EVENT = "workspace:show-reference"; + +export function CitationLink({ + href, + children, + className, + ...props +}: ComponentProps<"a">) { + const childrenText = normalizeCitationText(children); + const displayText = childrenText ?? ""; + const referenceId = href?.startsWith("#reference-") + ? href.slice("#reference-".length) + : null; + + if (referenceId) { + const badgeLabel = displayText.replace(/^\[|\]$/g, "") || referenceId; + return ( + { + event.preventDefault(); + const batchId = + event.currentTarget.closest("[data-reference-batch-id]") + ?.dataset.referenceBatchId; + window.dispatchEvent( + new CustomEvent(SHOW_REFERENCE_EVENT, { + detail: { batchId, referenceId }, + }), + ); + const scroll = () => { + const target = document.getElementById(`reference-${referenceId}`); + target?.scrollIntoView({ behavior: "smooth", block: "center" }); + }; + window.setTimeout(scroll, 240); + }} + {...props} + > + {badgeLabel} + + ); + } + + return ( + + {displayText || children} + + ); +} + +function normalizeCitationText(children: ComponentProps<"a">["children"]) { + if (typeof children !== "string") { + return null; + } + let text = children.trim(); + while (/^citation:\s*/i.test(text)) { + text = text.replace(/^citation:\s*/i, ""); + } + return text; +} diff --git a/frontend-web/src/components/workspace/input-box.tsx b/frontend-web/src/components/workspace/input-box.tsx index 986c5423..966268fd 100644 --- a/frontend-web/src/components/workspace/input-box.tsx +++ b/frontend-web/src/components/workspace/input-box.tsx @@ -3,6 +3,7 @@ import type { ChatStatus } from "ai"; import { BrainCircuitIcon, + BookMarkedIcon, CheckIcon, FileTextIcon, GraduationCapIcon, @@ -86,6 +87,11 @@ import { } from "../ui/dropdown-menu"; import { useRecommendedQuestions } from "@/core/recommended-questions/hooks"; +import { + isThreadRagModeLocked, + lockThreadRagMode, + useLocalSettings, +} from "@/core/settings"; import { useThread } from "./messages/context"; @@ -177,6 +183,7 @@ export function InputBox({ }; }) { const { t } = useI18n(); + const [localSettings, setLocalSettings] = useLocalSettings(); const searchParams = useSearchParams(); const [modelDialogOpen, setModelDialogOpen] = useState(false); const { models } = useModels(); @@ -297,6 +304,15 @@ export function InputBox({ }); }, [context, memoryInjectionEnabled, onContextChange]); + const ragModeLocked = isThreadRagModeLocked(threadId); + const ragModeEnabled = localSettings.display.ragModeEnabled || ragModeLocked; + const handleRagModeToggle = useCallback(() => { + if (ragModeLocked) { + return; + } + setLocalSettings("display", { ragModeEnabled: !ragModeEnabled }); + }, [ragModeEnabled, ragModeLocked, setLocalSettings]); + const handleSubmit = useCallback( async (message: PromptInputMessage) => { if (status === "streaming") { @@ -308,9 +324,12 @@ export function InputBox({ } setFollowups([]); setFollowupsHidden(false); - setFollowupsLoading(false); - - // Guard against submitting before the initial model auto-selection + setFollowupsLoading(false); + if (ragModeEnabled) { + lockThreadRagMode(threadId); + } + + // Guard against submitting before the initial model auto-selection // effect has flushed thread settings to storage/state. if (resolvedModelName && context.model_name !== resolvedModelName) { onContextChange?.({ @@ -332,11 +351,13 @@ export function InputBox({ onContextChange, onSubmit, onStop, - resolvedModelName, - selectedModel?.supports_thinking, - status, - ], - ); + resolvedModelName, + ragModeEnabled, + selectedModel?.supports_thinking, + status, + threadId, + ], + ); const requestFormSubmit = useCallback(() => { const form = promptRootRef.current?.querySelector("form"); @@ -622,6 +643,33 @@ export function InputBox({ 记忆 + + + {ragModeEnabled && ( + + )} + + 参考文献 + + { return { - a: (props: AnchorHTMLAttributes) => { - if (typeof props.children === "string") { - const match = /^citation:(.+)$/.exec(props.children); - if (match) { + a: (props: AnchorHTMLAttributes) => { + if (props.href?.startsWith("#reference-")) { + return ; + } + if (typeof props.children === "string") { + const match = /^citation:(.+)$/.exec(props.children); + if (match) { const [, text] = match; return {text}; } diff --git a/frontend-web/src/components/workspace/messages/message-group.tsx b/frontend-web/src/components/workspace/messages/message-group.tsx index 40f5348d..d354373d 100644 --- a/frontend-web/src/components/workspace/messages/message-group.tsx +++ b/frontend-web/src/components/workspace/messages/message-group.tsx @@ -47,6 +47,17 @@ import { findToolCallResult, } from "@/core/messages/utils"; import { useRehypeSplitWordsIntoSpans } from "@/core/rehype"; +import { useLocalSettings } from "@/core/settings"; +import { useSkills } from "@/core/skills/hooks"; +import { + buildSkillDisplayMap, + findDisplayConfigForTool, + isDisplaySamplePayload, + normalizeDefaultDisplaySources, + shouldUseDefaultCitationMode, + type RuntimeDisplaySource, +} from "@/core/skill-display/runtime"; +import { normalizeDisplaySources } from "@/core/skill-display/display-adapter"; import { extractTitleFromMarkdown } from "@/core/utils/markdown"; import { env } from "@/env"; import { cn } from "@/lib/utils"; @@ -54,6 +65,7 @@ import { cn } from "@/lib/utils"; import { useArtifactsOptional } from "../artifacts"; import { FlipDisplay } from "../flip-display"; import { Tooltip } from "../tooltip"; +import { SourceCard } from "../skill-display-sources"; import { MarkdownContent } from "./markdown-content"; @@ -74,6 +86,12 @@ export function MessageGroup({ env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true", ); const steps = useMemo(() => convertToSteps(messages), [messages]); + const [settings] = useLocalSettings(); + const { skills } = useSkills(); + const skillDisplayMap = useMemo( + () => (settings.display.ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()), + [settings.display.ragModeEnabled, skills], + ); const lastToolCallStep = useMemo(() => { const filteredSteps = steps.filter((step) => step.type === "toolCall"); return filteredSteps[filteredSteps.length - 1]; @@ -142,7 +160,13 @@ export function MessageGroup({ } > ) : ( - + ), )} {lastToolCallStep && ( @@ -152,6 +176,8 @@ export function MessageGroup({ {...lastToolCallStep} isLast={true} isLoading={isLoading} + skillDisplayMap={skillDisplayMap} + ragModeEnabled={settings.display.ragModeEnabled} /> )} @@ -209,6 +235,8 @@ function ToolCall({ result, isLast = false, isLoading = false, + skillDisplayMap = new Map(), + ragModeEnabled = false, }: { id?: string; messageId?: string; @@ -217,11 +245,56 @@ function ToolCall({ result?: string | Record; isLast?: boolean; isLoading?: boolean; + skillDisplayMap?: ReturnType; + ragModeEnabled?: boolean; }) { const { t } = useI18n(); const artifacts = useArtifactsOptional(); + const displayMatch = + result !== undefined && isDisplaySamplePayload(result) + ? null + : (findDisplayConfigForTool(name, skillDisplayMap, args) ?? + null); + const displayItems = + displayMatch && result !== undefined + ? normalizeDisplaySources(result, displayMatch.display).map((item, index) => ({ + ...item, + index: index + 1, + skillName: displayMatch.skillName, + mode: displayMatch.display.mode, + })) + : []; + if (displayItems.length > 0) { + return ( + + + + ); + } + const searchItems = normalizeSearchResults(result); + if (ragModeEnabled && shouldUseDefaultCitationMode(name, result, args) && searchItems.length > 0) { + const defaultItems = normalizeDefaultDisplaySources(result).map((item, index) => ({ + ...item, + index: index + 1, + skillName: name, + mode: "citation" as const, + })); + return ( + + + + ); + } if (name === "web_search" || searchItems.length > 0) { const query = resolveSearchQuery(args, result); let label: React.ReactNode = t.toolCalls.searchForRelatedInfo; @@ -544,6 +617,28 @@ function WebSearchResultsList({ results }: { results: SearchResultItem[] }) { ); } +function DisplayResultsList({ results }: { results: RuntimeDisplaySource[] }) { + const [open, setOpen] = useState(false); + return ( + + + + {results.length} 条真实返回结果 + + + {results.map((item) => ( + + ))} + + + ); +} + function SearchResultCard({ item }: { item: SearchResultItem }) { const [open, setOpen] = useState(false); const content = item.snippet ?? item.content; diff --git a/frontend-web/src/components/workspace/messages/message-list-item.tsx b/frontend-web/src/components/workspace/messages/message-list-item.tsx index d61f8a90..950ed302 100644 --- a/frontend-web/src/components/workspace/messages/message-list-item.tsx +++ b/frontend-web/src/components/workspace/messages/message-list-item.tsx @@ -36,15 +36,20 @@ import { type FileInMessage, } from "@/core/messages/utils"; import { useRehypeSplitWordsIntoSpans } from "@/core/rehype"; +import { + applyInlineCitations, + type RuntimeDisplaySource, +} from "@/core/skill-display/runtime"; import { humanMessagePlugins } from "@/core/streamdown"; import { desensitize } from "@/lib/desensitize"; import { cn } from "@/lib/utils"; +import { CitationLink } from "../citations/citation-link"; import { CopyButton } from "../copy-button"; - +import { SkillDisplayBlock } from "../skill-display-block"; import { ThreadContext } from "./context"; import { DownloadWordButton } from "./download-word-button"; -import { MarkdownContent } from "./markdown-content"; +import { MarkdownContent, type MarkdownContentProps } from "./markdown-content"; import { MessageTokenUsage } from "./message-token-usage"; /** @@ -76,6 +81,7 @@ export function MessageListItem({ isLoading, threadId, tokenUsageEnabled = false, + displaySources = [], extraRehypePlugins, }: { className?: string; @@ -83,6 +89,7 @@ export function MessageListItem({ isLoading?: boolean; threadId: string; tokenUsageEnabled?: boolean; + displaySources?: RuntimeDisplaySource[]; extraRehypePlugins?: ReturnType; }) { const isHuman = message.type === "human"; @@ -101,6 +108,7 @@ export function MessageListItem({ isLoading={isLoading} threadId={threadId} tokenUsageEnabled={tokenUsageEnabled} + displaySources={displaySources} extraRehypePlugins={extraRehypePlugins} /> {!isLoading && ( @@ -162,6 +170,7 @@ function MessageContent_({ isLoading = false, threadId, tokenUsageEnabled = false, + displaySources = [], extraRehypePlugins, }: { className?: string; @@ -169,6 +178,7 @@ function MessageContent_({ isLoading?: boolean; threadId: string; tokenUsageEnabled?: boolean; + displaySources?: RuntimeDisplaySource[]; extraRehypePlugins?: ReturnType; }) { const baseRehypePlugins = useRehypeSplitWordsIntoSpans(isLoading); @@ -184,6 +194,12 @@ function MessageContent_({ ), a: ({ href, ...props }: AnchorHTMLAttributes) => { + if (href?.startsWith("#reference-")) { + return ; + } + if (typeof props.children === "string" && /^citation:/i.test(props.children)) { + return ; + } if (href?.startsWith("/mnt/")) { const url = resolveArtifact(href); return ( @@ -220,8 +236,8 @@ function MessageContent_({ if (isHuman) { return rawContent ? stripArtifactTag(stripUploadedFilesTag(rawContent)) : ""; } - return rawContent ?? ""; - }, [rawContent, isHuman]); + return applyInlineCitations(rawContent ?? "", displaySources); + }, [rawContent, isHuman, displaySources]); const filesList = files && files.length > 0 ? ( @@ -287,13 +303,15 @@ function MessageContent_({ return ( {filesList} - +
+ +
splitSkillDisplayPlaceholders(content, displaySources), + [content, displaySources], + ); + const fallbackBlocks = useMemo(() => { + return groupDisplaySources(displaySources).filter( + (group) => group.mode !== "citation" && !placedKeys.has(group.key), + ); + }, [displaySources, placedKeys]); + + return ( + <> + {parts.map((part, index) => + part.type === "markdown" ? ( + + ) : ( + + ), + )} + {fallbackBlocks.map((group) => ( + + ))} + + ); +} + +type DisplayPart = + | { type: "markdown"; content: string } + | { + type: "display"; + key: string; + mode: RuntimeDisplaySource["mode"]; + sources: RuntimeDisplaySource[]; + }; + +function splitSkillDisplayPlaceholders( + content: string, + displaySources: RuntimeDisplaySource[], +): { parts: DisplayPart[]; placedKeys: Set } { + const pattern = /]*?)\/>/g; + const parts: DisplayPart[] = []; + const placedKeys = new Set(); + let cursor = 0; + for (const match of content.matchAll(pattern)) { + const start = match.index ?? 0; + const before = content.slice(cursor, start); + if (before.trim()) { + parts.push({ type: "markdown", content: before }); + } + const attrs = parseDisplayAttrs(match[1] ?? ""); + const group = findDisplayGroup(displaySources, attrs.tool, attrs.mode); + if (group) { + parts.push({ + type: "display", + key: group.key, + mode: group.mode, + sources: group.sources, + }); + placedKeys.add(group.key); + } + cursor = start + match[0].length; + } + const rest = content.slice(cursor); + if (rest.trim() || parts.length === 0) { + parts.push({ type: "markdown", content: rest }); + } + return { parts, placedKeys }; +} + +function parseDisplayAttrs(raw: string): { tool?: string; mode?: RuntimeDisplaySource["mode"] } { + const attrs: Record = {}; + for (const match of raw.matchAll(/([a-zA-Z][\w-]*)="([^"]*)"/g)) { + attrs[match[1]!] = match[2]!; + } + return { + tool: attrs.tool || attrs.skill || attrs.name, + mode: attrs.mode as RuntimeDisplaySource["mode"] | undefined, + }; +} + +function findDisplayGroup( + sources: RuntimeDisplaySource[], + tool?: string, + mode?: RuntimeDisplaySource["mode"], +) { + return groupDisplaySources(sources).find((group) => { + if (mode && group.mode !== mode) { + return false; + } + if (!tool) { + return true; + } + const left = normalizeName(group.skillName); + const right = normalizeName(tool); + return left === right || left.includes(right) || right.includes(left); + }); +} + +function groupDisplaySources(sources: RuntimeDisplaySource[]) { + const groups = new Map< + string, + { + key: string; + skillName: string; + mode: RuntimeDisplaySource["mode"]; + sources: RuntimeDisplaySource[]; + } + >(); + for (const source of sources) { + const key = `${source.skillName}:${source.mode}`; + const group = + groups.get(key) ?? + { + key, + skillName: source.skillName, + mode: source.mode, + sources: [], + }; + group.sources.push(source); + groups.set(key, group); + } + return [...groups.values()]; +} + +function normalizeName(name: string) { + return name.toLowerCase().replace(/[^a-z0-9]+/g, ""); +} diff --git a/frontend-web/src/components/workspace/messages/message-list.tsx b/frontend-web/src/components/workspace/messages/message-list.tsx index ce10ffb2..7b0a9a7a 100644 --- a/frontend-web/src/components/workspace/messages/message-list.tsx +++ b/frontend-web/src/components/workspace/messages/message-list.tsx @@ -1,3 +1,4 @@ +import type { Message } from "@langchain/langgraph-sdk"; import type { BaseStream } from "@langchain/langgraph-sdk/react"; import { CheckIcon, SendIcon, XIcon } from "lucide-react"; import { useCallback, useMemo, useState } from "react"; @@ -20,6 +21,12 @@ import { hasToolCalls, } from "@/core/messages/utils"; import { useRehypeSplitWordsIntoSpans } from "@/core/rehype"; +import { isThreadRagModeLocked, useLocalSettings } from "@/core/settings"; +import { useSkills } from "@/core/skills/hooks"; +import { + buildSkillDisplayMap, + collectRuntimeDisplaySources, +} from "@/core/skill-display/runtime"; import type { Subtask } from "@/core/tasks"; import { useUpdateSubtask } from "@/core/tasks/context"; import type { AgentThreadState } from "@/core/threads"; @@ -63,7 +70,6 @@ export function MessageList({ onSetupAgentApprove?: (payload: SetupAgentApprovalPayload) => void | Promise; onSetupAgentReject?: (payload: SetupAgentApprovalPayload) => void | Promise; }) { - const { t } = useI18n(); const baseRehypePlugins = useRehypeSplitWordsIntoSpans(thread.isLoading); const rehypePlugins = useMemo( () => (extraRehypePlugins?.length ? [...baseRehypePlugins, ...extraRehypePlugins] : baseRehypePlugins), @@ -71,6 +77,14 @@ export function MessageList({ ); const updateSubtask = useUpdateSubtask(); const messages = thread.messages; + const [settings] = useLocalSettings(); + const ragModeEnabled = + settings.display.ragModeEnabled || isThreadRagModeLocked(threadId); + const { skills } = useSkills(); + const skillDisplayMap = useMemo( + () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()), + [ragModeEnabled, skills], + ); // Track which clarification messages are still awaiting an answer. // Pending = clarification tool messages that appear after the last human message @@ -190,6 +204,16 @@ export function MessageList({ {groupMessages(messages, (group) => { if (group.type === "human" || group.type === "assistant") { return group.messages.map((msg) => { + const displaySources = + ragModeEnabled && + group.type === "assistant" && + msg.type === "ai" + ? collectRuntimeDisplaySources(messages, skillDisplayMap, { + afterMessageId: findPreviousHumanMessageId(messages, msg.id), + beforeMessageId: msg.id, + includeBeforeMessage: true, + }) + : []; return ( ); @@ -442,6 +467,24 @@ export type SetupAgentApprovalPayload = { skills?: string[]; }; +function findPreviousHumanMessageId( + messages: Message[], + beforeMessageId?: string, +): string | undefined { + const beforeIndex = + beforeMessageId === undefined + ? messages.length + : messages.findIndex((message) => message.id === beforeMessageId); + const end = beforeIndex < 0 ? messages.length : beforeIndex; + for (let index = end - 1; index >= 0; index--) { + const message = messages[index]; + if (message?.type === "human") { + return message.id; + } + } + return undefined; +} + function getSetupAgentApprovalPayload( message: unknown, ): SetupAgentApprovalPayload | null { diff --git a/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx b/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx index 77c548a1..5970d17e 100644 --- a/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx +++ b/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx @@ -2,9 +2,11 @@ import { MoonIcon, SunIcon } from "lucide-react"; import { useMemo, type ComponentType, type SVGProps } from "react"; +import { toast } from "sonner"; import { useTheme } from "@/contexts/ThemeContext"; +import { Button } from "@/components/ui/button"; import { Select, SelectContent, @@ -14,9 +16,17 @@ import { } from "@/components/ui/select"; import { Separator } from "@/components/ui/separator"; import { Switch } from "@/components/ui/switch"; +import { Textarea } from "@/components/ui/textarea"; +import { getStoredAuth } from "@/core/auth"; import { enUS, isLocale, zhCN, type Locale } from "@/core/i18n"; import { useI18n } from "@/core/i18n/hooks"; import { useLocalSettings } from "@/core/settings"; +import { + useAppearanceSettings, + useCitationDisplaySettings, + useUpdateAppearanceSettings, + useUpdateCitationDisplaySettings, +} from "@/core/system-settings/hooks"; import { cn } from "@/lib/utils"; import { SettingsSection } from "./settings-section"; @@ -31,6 +41,28 @@ export function AppearanceSettingsPage() { const { theme, setTheme } = useTheme(); const currentTheme = theme; const [settings, setSettings] = useLocalSettings(); + const isAdmin = getStoredAuth()?.system_role === "admin"; + const { data: appearance } = useAppearanceSettings(); + const updateAppearance = useUpdateAppearanceSettings(); + const { data: citationDisplay } = useCitationDisplaySettings(); + const updateCitationDisplay = useUpdateCitationDisplaySettings(); + const globalDefault = appearance?.default_theme ?? "light"; + const cleanupWords = + citationDisplay?.cleanup_words ?? settings.display.citationCleanupWords ?? []; + + const handleSetGlobalDefault = async (value: "light" | "dark") => { + if (value === globalDefault) return; + try { + await updateAppearance.mutateAsync({ default_theme: value }); + toast.success( + value === "light" + ? "已将系统默认主题设置为浅色" + : "已将系统默认主题设置为深色", + ); + } catch (e) { + toast.error(e instanceof Error ? e.message : "保存失败"); + } + }; const themeOptions = useMemo( () => [ @@ -76,6 +108,43 @@ export function AppearanceSettingsPage() {
+ {isAdmin && ( + <> + + +
+ + +

+ 当前系统默认： + {globalDefault === "light" ? "浅色" : "深色"} +

+
+ + + )} + +
+
+
RAG 引用模式
+

+ 开启后，已配置展示适配的技能结果会在问答中渲染为编号引用或列表，并支持点击跳转。 +

+
+ + setSettings("display", { ragModeEnabled: checked }) + } + aria-label="RAG 引用模式" + /> +
+ {isAdmin && ( +
+
+
参考文献去除词
+

+ 管理员配置。每行一个词或短句，参考文献卡片和详情弹框会自动移除这些广告词、导航词或免责声明。 +

+
+