代码提交

feat: 岗位会商命令幂等与圆桌后台作业租约调度

See merge request knowledge-base-bj/deerflow-code!22

.codex-server-diagnose.py

@@ -0,0 +1,20 @@
+import os
+
+import paramiko
+
+
+client = paramiko.SSHClient()
+client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+client.connect(
+    "119.254.86.251",
+    port=22322,
+    username="root",
+    password=os.environ["TARGET_SSH_PASSWORD"],
+    timeout=15,
+    auth_timeout=15,
+    banner_timeout=15,
+)
+_, stdout, stderr = client.exec_command(os.environ["TARGET_SSH_COMMAND"], timeout=30)
+print(stdout.read().decode(errors="replace"), end="")
+print(stderr.read().decode(errors="replace"), end="")
+client.close()

.dockerignore

@@ -0,0 +1,35 @@
+# Never send source-control history, local dependencies, runtime state, or
+# credentials to the Docker daemon.  The offline images are built from the
+# repository root by deploy/1panel-offline/Dockerfile.*.
+.git
+.runtime
+.history
+tmp
+dist
+
+# Credentials and environment-specific configuration are supplied at runtime
+# through the offline delivery package, never copied into an image layer.
+**/.env
+**/.env.*
+offline-backend-20260512/backend/.deer-flow
+offline-backend-20260512/backend/logs
+offline-backend-20260512/backend/docker-data
+offline-backend-20260512/backend/dist
+offline-backend-20260512/backend/wheelhouse
+offline-backend-20260512/backend/offline-wheels
+offline-backend-20260512/backend/.venv
+offline-backend-20260512/backend/.pytest_cache
+offline-backend-20260512/backend/.ruff_cache
+
+# Reproducibly install frontend dependencies inside the image instead.
+frontend-web/node_modules
+frontend-web/dist
+frontend-web/.vite
+frontend-web/.offline-pack-build
+frontend-web/.offline-extract-test
+frontend-web/node_modules-offline-*.tar.gz
+
+# Editor and operating-system metadata.
+**/__pycache__
+**/*.py[cod]
+**/.DS_Store

.gitignore

@@ -1,5 +1,9 @@
 # Workspace/editor
-.vscode/
+.vscode/*
+!.vscode/launch.json
+!.vscode/tasks.json
+!.vscode/extensions.json
+!.vscode/settings.json
 frontend-web/.vscode/
 node_modules/
 # Claude Code local-only settings (per-user permissions, not shared)
@@ -53,6 +57,7 @@ offline-backend-20260505/bundle/stop_backend.sh
 
 # offline-backend-20260512 runtime artifacts (large files, local config, data)
 offline-backend-20260512/.env.example
+offline-backend-20260512/.env
 offline-backend-20260512/DEPLOY_BACKEND_OFFLINE_ZH.md
 offline-backend-20260512/SHA256SUMS
 offline-backend-20260512/config.yaml.example
@@ -64,6 +69,8 @@ offline-backend-20260512/wheelhouse/
 offline-backend-20260512/backend/.deer-flow/data/*.db
 offline-backend-20260512/backend/.deer-flow/data/*.db-*
 offline-backend-20260512/backend/.deer-flow/*
+offline-backend-20260512/backend/.env
+offline-backend-20260512/backend/.env.local
 offline-backend-20260512/start_backend.sh
 offline-backend-20260512/stop_backend.sh
 offline-backend-20260512/check_backend.sh
@@ -81,6 +88,11 @@ skills/
 hermes-agent-main/
 .gitignore
 offline-backend-20260512/backend/tests/*
+!offline-backend-20260512/backend/tests/test_llmwiki_weknora.py
+!offline-backend-20260512/backend/tests/test_health_auth_bypass.py
+# Keep the model configuration regression coverage versioned even though
+# this deployment repository otherwise ignores newly added backend tests.
+!offline-backend-20260512/backend/tests/test_model_management.py
 deploy
 .history
 
@@ -95,6 +107,10 @@ frontend-web/.offline-pack-build/
 frontend-web/.offline-extract-test/
 frontend-web-node_modules-offline-*.tar.gz
 
+# Local dependency caches and backend scratch archives
+/.pnpm-store/
+/offline-backend-20260512/backend/backend*.zip
+
 .codegraph
 codegraph.mdc
 

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "ms-python.debugpy"
+  ]
+}

.vscode/launch.json

@@ -0,0 +1,66 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "DeerFlow: Backend FastAPI (8001)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "uvicorn",
+      "args": [
+        "app.gateway.app:app",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8001"
+      ],
+      "cwd": "${workspaceFolder}/offline-backend-20260512/backend",
+      "python": "${workspaceFolder}/offline-backend-20260512/backend/.venv/Scripts/python.exe",
+      "envFile": "${workspaceFolder}/offline-backend-20260512/.env",
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}/offline-backend-20260512/backend;${workspaceFolder}/offline-backend-20260512/backend/.deer-flow/python-vendor",
+        "GATEWAY_CORS_ORIGINS": "http://localhost:5174,http://127.0.0.1:5174,http://localhost:8080,http://127.0.0.1:8080",
+        "UV_LINK_MODE": "copy",
+        "WEKNORA_ADMIN_PASSWORD": "1qaz@WSX"
+      },
+      "console": "integratedTerminal",
+      "redirectOutput": true,
+      "justMyCode": false,
+      "subProcess": true
+    },
+    {
+      "name": "DeerFlow: Frontend Vite (5174)",
+      "type": "node-terminal",
+      "request": "launch",
+      "command": "npm.cmd run dev -- --host 0.0.0.0 --port 5174",
+      "cwd": "${workspaceFolder}/frontend-web",
+      "env": {
+        "VITE_BACKEND_BASE_URL": "http://127.0.0.1:8001",
+        "VITE_LANGGRAPH_BASE_URL": "http://127.0.0.1:8001/api"
+      },
+      "serverReadyAction": {
+        "pattern": "Local:\\s+(https?://[^\\s]+)",
+        "uriFormat": "%s",
+        "action": "openExternally"
+      }
+    },
+    {
+      "name": "DeerFlow: Open Frontend in Chrome",
+      "type": "node-terminal",
+      "request": "launch",
+      "preLaunchTask": "DeerFlow: Start Full Stack and Wait",
+      "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"Start-Process 'http://127.0.0.1:5174/'\"",
+      "cwd": "${workspaceFolder}"
+    }
+  ],
+  "compounds": [
+    {
+      "name": "DeerFlow: Full Stack (Backend + Frontend)",
+      "preLaunchTask": "DeerFlow: Stop Full Stack",
+      "configurations": [
+        "DeerFlow: Backend FastAPI (8001)",
+        "DeerFlow: Frontend Vite (5174)"
+      ],
+      "stopAll": true
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/offline-backend-20260512/backend/.venv/Scripts/python.exe",
+  "python.terminal.activateEnvironment": true,
+  "typescript.tsdk": "frontend-web/node_modules/typescript/lib",
+  "npm.packageManager": "npm"
+}

.vscode/tasks.json

@@ -0,0 +1,152 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "DeerFlow: Start Full Stack and Wait",
+      "type": "process",
+      "command": "powershell.exe",
+      "args": [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        "${workspaceFolder}/scripts/start-all-and-wait-frontend.ps1"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow: Start Full Stack",
+      "type": "process",
+      "command": "powershell.exe",
+      "args": [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        "${workspaceFolder}/scripts/start-all.ps1"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow: Stop Full Stack",
+      "type": "process",
+      "command": "powershell.exe",
+      "args": [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        "${workspaceFolder}/scripts/stop-all.ps1"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow: Status",
+      "type": "process",
+      "command": "powershell.exe",
+      "args": [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        "${workspaceFolder}/scripts/status.ps1"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow: Check Local Dev Environment",
+      "type": "shell",
+      "command": "$backendPython = '${workspaceFolder}\\offline-backend-20260512\\backend\\.venv\\Scripts\\python.exe'; if (-not (Test-Path -LiteralPath $backendPython)) { throw 'Backend virtual environment is missing. Run uv sync in offline-backend-20260512/backend first.' }; & $backendPython -c \"import uvicorn; print('Backend Python OK')\"; npm --prefix '${workspaceFolder}\\frontend-web' exec vite -- --version",
+      "options": {
+        "shell": {
+          "executable": "powershell.exe",
+          "args": [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command"
+          ]
+        }
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow: Install Frontend Dependencies",
+      "type": "process",
+      "command": "npm",
+      "args": [
+        "ci",
+        "--no-audit",
+        "--no-fund"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}/frontend-web"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow: Frontend Typecheck",
+      "type": "process",
+      "command": "npm",
+      "args": [
+        "run",
+        "typecheck"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}/frontend-web"
+      },
+      "problemMatcher": "$tsc"
+    },
+    {
+      "label": "DeerFlow: Frontend Build",
+      "type": "process",
+      "command": "npm",
+      "args": [
+        "run",
+        "build"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}/frontend-web"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow: Backend Tests",
+      "type": "process",
+      "command": "${workspaceFolder}/offline-backend-20260512/backend/.venv/Scripts/python.exe",
+      "args": [
+        "-m",
+        "pytest",
+        "tests/",
+        "-v"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}/offline-backend-20260512/backend",
+        "env": {
+          "PYTHONPATH": ".",
+          "WEKNORA_ADMIN_PASSWORD": "1qaz@WSX"
+        }
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow: WeKnora Backend Tests",
+      "type": "process",
+      "command": "${workspaceFolder}/offline-backend-20260512/backend/.venv/Scripts/python.exe",
+      "args": [
+        "-m",
+        "pytest",
+        "tests/test_llmwiki_weknora.py",
+        "-v"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}/offline-backend-20260512/backend",
+        "env": {
+          "PYTHONPATH": ".",
+          "WEKNORA_ADMIN_PASSWORD": "1qaz@WSX"
+        }
+      },
+      "problemMatcher": []
+    }
+  ]
+}

.zcode/plans/plan-sess_bc89c1c7-ec32-43b9-886f-70fa2ae83a13.md

@@ -0,0 +1,61 @@
+# 深度研究第三轮：检索稳定性修复 + 参考文献确定性 + 页面对齐 AI 写作改造
+
+## A. 两个 bug 的排查结论与修复
+
+### A1. 第二次检索「网络波动」——确认是真问题（DDG 限流 + 错误语义混淆 + 零重试）
+
+**排查结论**（用户判断"确实是网络波动"基本正确，但代码层面放大了它）：
+- 「网络波动」文案不存在于任何代码中——是收集员 LLM 看到 `{"error": "No results found"}` 信封后自己编的解释
+- 真实根因：DDG html 端点对同 IP 快速连续请求限流（403/429 挑战页）→ `DDGSException` → `ddg_search/tools.py::_search_text` 把异常吞成 `[]` → 上层把「被限流」和「真没结果」混成同一个错误信封；工具层完全没有重试
+
+**修复**（`packages/harness/deerflow/community/ddg_search/tools.py`）：
+1. `_search_text` 对异常加 2 次重试 + 指数退避（约 1.5s / 3s + 抖动）
+2. 错误信封区分场景：真无结果 → `no results`；多次尝试仍失败 → `web search failed after N attempts (rate limited or network), 换一组检索词稍后重试`——让模型不再瞎猜「网络波动」
+3. 收集员 SOUL.md 行为准则加一条（同步改种子资产 + 已安装副本 `.deer-flow/agents/deep-research-collector/`）：搜索返回 error 信封时先换检索词重试一轮，而不是直接告知用户网络异常
+
+### A2. 参考文献缺失——代码确有隐患（当前是模型自发行为，时有时无）
+
+**排查结论**：后端没有任何「参考来源」追加逻辑；四个 runner 的报告 prompt 只要求内联 `[N]` 引用。出现过的参考列表是模型看到上下文头 `[N] 标题（URL）` 后**自发**补写的——弱模型下不可靠，与"信息够不够"无必然关系。
+
+**修复**（prompt 指示 + 确定性兜底双保险）：
+1. 四个 runner（basic / detailed / deep / multi_agent）的报告 prompt 各加一条：报告最后附「## 参考来源」，按 `[N] 标题. URL` 列出正文实际引用过的来源
+2. `basic.py` 新增共享函数 `ensure_reference_section(report, context_list, materials)`：报告缺少参考小节时，解析正文引用的 `[N]` 编号，按压缩上下文顺序生成编号列表追加（无编号时列全部来源，封顶 20 条；已有参考小节则不重复追加）。在各 runner 最终 `write_text("report.md", ...)` 前调用（约 7 个调用点，跳过零材料 fallback）
+3. 新增测试 `tests/test_deep_research_references.py`：helper 单测（正常追加/编号映射/不重复追加/无 URL 来源）+ runner 集成断言
+
+## B. 页面改造（核心需求）：左列复用 AI 写作对话形态，右列改真沙箱
+
+### B1. 左列 = AI 写作式对话收集面板（仿 WritingSetupChat）
+
+- **空状态欢迎屏**（无消息时隐藏头部，展示欢迎卡片，WritingWelcome 式）+ 有消息后 `MessageList`（沿用现有绑 collector 线程的接线）+ 首 token 前「正在整理…」占位条
+- **输入框换成白卡片 PromptInput 套件**（与 AI 写作完全同款组件）：卡片内一行「当前对话模型」Select（沿用 ModelNameSelect）+ 高级配置入口；下方 PromptInputTextarea + PromptInputFooter + PromptInputSubmit（`status` ready/streaming，流式中变停止按钮）。经典模式入口保留在高级配置对话框
+- **配置卡片进对话流**（对标 AI 写作「识别出意图后出现表单」）：
+  - `message-list.tsx` 最小扩展（约 15 行）：新增分组 `assistant:research-approval`（识别 `additional_kwargs.setup_research_approval`）+ 可选 prop `researchApprovalSlot?: ReactNode`；不传 slot 或无该载荷时零行为变化——普通对话/AI 写作完全不受影响
+  - workbench：收集回合结束（awaiting_report，即"意图识别完成"）时向 `displayThread` 尾部注入一条虚拟 ai 消息（WritingSetupChat 的 displayThread 同款手法），slot 传现有 `ReportConfigCard` → 卡片作为助手下一轮出现在对话流里
+- 写作进度卡、完成卡、摘要气泡、追问列表保留在列表下方卡片区（报告正文移到右侧沙箱）
+
+### B2. 右列 = 工作区真沙箱（Step2SandboxLayout 的 stub 线程模式）
+
+- 新建 `deep-research/ResearchSandboxPanel.tsx`（约 100 行，含关闭/重开）+ `useReportSandbox.ts` hook（仿 `useStep3Report` 的 stub 机制）：
+  - threadStub：`messages = [{type:'ai', tool_calls:[{name:'write_file', args:{path:'/mnt/user-data/outputs/report.md', content: <流式报告>}}]}]`，`isLoading = job 运行中 && phase !== 'summarizing'`
+  - `report_delta` 首帧 → `openArtifact(write-file: 虚拟URL)` 自动展开右栏；`run.report` 每帧 upsert stub（带防抹空守卫）；刷新/切换会话用 `session.reportMarkdown` 重建
+  - `ArtifactFileDetail` 自带能力全部免费获得：**流式期 code 视图自动滚底 → 报告写完 isLoading 翻 false 自动切 preview + 脉冲提示**（正是「生成完直接切预览」）、Streamdown 渲染的 Markdown（比现在的好看）、另存 Word/复制/下载、默认走展示层脱敏
+- 布局：ResizablePanelGroup chat 60 / sandbox 40（对齐 ChatBox/圆桌），沙箱可关闭、头部按钮重开
+- **删除自定义 `ResearchSandbox` 组件**；legacy 会话与经典模式共用同一右栏（`run.report` 数据源相同，行为一致）
+- 已知小限制（可接受）：报告配图模式下沙箱内图片可能无法经 artifacts API 解析（配图默认关闭；真需要时后续把产物落 thread artifacts）
+
+### B3. 验证
+
+- 后端：`PYTHONPATH=. uv run --no-sync pytest tests/ -k deep_research -q --ignore=tests/test_notification_templates.py` 全绿 + ruff；改完配置/SOUL 后 touch 触发 dev 服务重载
+- 前端：`pnpm typecheck` 零新增错误（基线 51）
+- 手动走查：连续两次检索不再误报、弱模型报告末尾必带参考来源、页面全流程（欢迎屏 → 对话收集 → 流内配置卡 → 沙箱流式 → 自动预览 → 摘要/追问）
+
+## 涉及文件
+
+**后端**：`community/ddg_search/tools.py`、`deep_research/runners/{basic,detailed,deep,multi_agent}.py`、收集员 SOUL.md（种子 + 已安装副本）、`tests/test_deep_research_references.py`（新）
+**前端**：`components/workspace/messages/message-list.tsx`（可选 slot 分组）、`pages/deep-research/DeepResearchWorkbench.tsx`（大改）、`pages/deep-research/ResearchSandboxPanel.tsx`（新）、`pages/deep-research/useReportSandbox.ts`（新）
+
+## 明确不动
+
+- AI 写作 / 普通对话现有组件行为（message-list.tsx 仅加可选分组，缺省零变化）
+- 报告写作管线的写作逻辑本身（prompt 加一条要求 + 末尾确定性追加参考小节，均为附加式）
+- 深度研究后端会话/任务/事件模型（本轮不动）

AGENTS.md

@@ -82,6 +82,7 @@ The frontend (`frontend-web/`) is a React 19 + Vite SPA:
 - **AI 写作·对话版（对话驱动写作台）**: a **parallel new entry** beside the classic AI-writing page (classic page/routes untouched) — route `/page/canvas/ai-writing-chat`, sidebar 「问答管理 → 课题研究(对话版)」. Page `open-canvas/pages/AIWritingChatPage.tsx` reuses the engine (`AIWritingContext` + `useStream` + `AIWritingDraftPanel`); **idle keeps the classic setup layout** (`WritingSetupChat` + collapsible form) and switches to the chat workbench once writing starts; left panel `components/ai-writing-chat/WritingChatPanel.tsx` = **unified chronological feed** (`ChatFlowTimeline.tsx`, chat bubbles anchor-interleaved into the progress timeline so triggered events render below the user's message) + button-only intervention cards (`ChatInterventionCards.tsx`, inline textareas removed) + bottom unified smart composer. Intent resolution: frontend fast path + `POST /api/ai-writing/sessions/{id}/intent` → `deerflow/agents/ai_writing/intent_router.py` (per-pause action whitelist, high-cost confidence gates, payload cleaning); supports QA bypass, clarify follow-ups, control intents, and material-stage auto re-search + pending-intent resume. Tests `tests/test_ai_writing_intent.py`; plan doc `frontend-web/docs/ai-writing-对话驱动写作台-实现方案.md`.
 - **轻应用中心 (Light App Center)**: a sibling of 任务管理 in the sidebar with two pages — 应用管理 (admin registers `window_open` or `iframe` mini-apps with a route-param builder: login params resolved from `localStorage.userInfo`, theme params literal) and 应用列表 (card grid of `window_open` apps, `window.open` launch). `iframe` apps are mounted under a chosen parent menu (XK/PG/TY/综合管理) and **dynamically injected into the sidebar** by `core/page-layout/use-sidebar-menu.ts` (`useSidebarMenuItems`), opening in the `LightAppIframeView` host. Client + React Query hooks in `strategy-components/api/light-apps.ts`; URL builder/constants in `strategy-components/lib/light-app.ts`. Backend: `/api/light-apps` (global/shared, admin-gated writes).
 - **菜单管理 (Menu Management, admin-only)**: an **overlay** over the static sidebar menu — `MenuManagementPage` (`pages/MenuManagementPage.tsx`, route `/page/strategy/admin/menu-management`, opened from the admin-only 「菜单管理」 item in the **bottom-left settings dropdown** of `components/page-sidebar.tsx`). Admins rename / 停用·启用 / reorder (↑↓ or @dnd-kit drag) / re-parent (horizontal drag **or** the edit dialog's 「移动到」parent selector) any node across 一级/二级/三级, **including injected iframe light-app nodes** (`light-app-<appId>`). The static tree (`core/page-layout/sidebar-menu.ts`) stays the source of icons/routes; only per-node deltas (`label`/`disabled`/`parentId`/`sortOrder`) persist to the backend. Merge logic in `core/page-layout/menu-overrides.ts` (`applyMenuOverrides`, applied in `use-sidebar-menu.ts` after light-app injection, before role filter; disabling a node hides its whole subtree) — strict **3-level cap** (`wouldExceedDepth`). Client `strategy-components/api/menu-overrides.ts`. Backend: `/api/menu-overrides` (global/shared; open read, admin atomic replace-all).
+- **舆情分析智能体（前端虚拟智能体）**: 智能体管理页新增「舆情分析」类型 tab，固定一张虚拟智能体卡片（名称/简介可编辑，存 localStorage）。对话页 `pages/SentimentAgentChatPage.tsx`（路由 `agents/sentiment-analysis/chats/:thread_id`）复用普通问答布局 + `MessageList`，**输入框只有发送按钮**；问答直连外部 AG-UI 网关（POST SSE），不经过 LangGraph，会话仅存 sessionStorage。接口地址 + Basic Auth 在 `runtime-config.js` 配置（`VITE_SENTIMENT_AGENT_API_URL` / `_AUTH_USERNAME` / `_AUTH_PASSWORD`），核心模块 `src/core/sentiment-agent/`。
 - **敏感词管理 (Sensitive Word Management)**: configures the **展示层脱敏映射** (原始词 → 替换词). **Gated on the username `lqq`** (not the admin role) — `getAccountDisplayName().toLowerCase() === "lqq"` (username = email `@` prefix, else `user_id`, same as the profile page); the dropdown entry, the route guard, and the page-level guard all use this check. `src/lib/desensitize.ts` ships a frozen seed map `SEED_DESENSITIZE_MAP` (the deployment seed) plus a live mutable `DESENSITIZE_MAP` (initialized from the seed so `desensitize()` works before any fetch). `DesensitizeWordsLoader` (mounted in `App.tsx` `AppProviders`) fetches `/api/sensitive-words` on startup and, if non-empty, calls `replaceDesensitizeMap(...)` to make the backend config the source of truth (empty/failed → keep seed). Page `SensitiveWordsPage.tsx` (route `/page/strategy/admin/sensitive-words`, opened from the 「敏感词管理」 item in the **bottom-left settings dropdown** of `components/page-sidebar.tsx`, present in **both** full + collapsed sidebar modes) lists/adds/edits/启停/deletes words and saves the **whole set atomically** (replace-all); a 「导入种子词」 button merges any missing `SEED_DESENSITIZE_MAP` entries into the editor. Client + hooks in `strategy-components/api/sensitive-words.ts` (`wordsToMap` folds enabled rows into the runtime map). Backend: `/api/sensitive-words` (global/shared; open read, write allowed for admin **or** the `lqq` account), mirroring 菜单管理's store shape. **侧边栏 + 导航栏 menu labels are desensitized** at the data source: `useSidebarMenuItems`/`useActiveThirdLevel` (`core/page-layout/use-sidebar-menu.ts`) map every node's `label` through a desensitizer built **directly from the `/api/sensitive-words` query** (`makeDesensitizer(wordsToMap(words))`, falling back to the global seed `desensitize` while empty) — this sidesteps the `replaceDesensitizeMap` effect-timing race. Only `label` is rewritten; `path`/`id`/`icon` are untouched so routing/highlight are unaffected. All nav surfaces (`page-sidebar.tsx`, `page-sidebar-dark.tsx`, `page-sidebar-v1.tsx`, `strategy-components/Header.tsx`, `PageRoutes.tsx`) consume this hook and are covered; `MenuManagementPage` uses the raw tree so admins still edit real labels.
 - **技能地址管理 (Skill Address Management, admin-only)**: 扫描运行中的技能（`skills/{public,custom}` 下所有 `.md`/`.py`）里的 **http(s) URL 与 IP/IP:端口**，按唯一地址聚合全部出现位置（跨 .md/.py），支持**批量替换**（如把 UAT 地址一次性改成生产）。主体抽成可复用组件 `SkillAddressesPanel`（`pages/SkillAddressesPage.tsx` 导出，默认导出 `SkillAddressesPage` 仍保留旧路由 `/page/strategy/admin/skill-addresses` 作直链回退），**作为「技能地址管理」标签页嵌入管理员「技能管理」页 `pages/AdminSkillsPage.tsx`**（该页加 Tabs：「技能列表」+「技能地址管理」；入口在「设置和更多」下拉的「技能管理」`workspace-nav-menu.tsx` → `/page/workspace/admin/skills`，不再单列于 `components/page-sidebar.tsx` 左下角设置下拉）：打开自动扫描并带**进度条**（扫描逐技能 / 应用逐文件 X/N，应对 150+ 技能），URL/IP 类型过滤 + 搜索 + 「片段批量套用」（如所有 `uat.4.cn` → `prod.4.cn`）、每地址「替换为」输入框（可展开看 `file:line` 片段）、内联**预览**、**应用**、**多关键词检索**（空格分隔全部命中），以及**修改记录**面板——每次应用生成一条记录（显示时间/改了哪些地址 from→to/文件数/处数），可**针对单次记录回退**（二次确认）。client + NDJSON 流式解析在 `strategy-components/api/skill-addresses.ts`。后端 `/api/skill-addresses`（**仅管理员**）：所有文件 IO 走 `asyncio.to_thread` 不阻塞事件循环；`GET /scan`(+`/scan/stream`)、`POST /preview`、`POST /apply`(+`/apply/stream`)、`GET /backups`、`POST /rollback/{id}`；**子串安全替换**（基于 token span，不会误伤子串）、`expected_total` 乐观锁（409）、写前自动磁盘备份到 `{skills_root}/.address-edits/`（同时写一份 `{id}.manifest.json` 记录本次替换明细，供修改记录展示）、应用后刷新技能系统提示缓存。纯引擎 `deerflow/skills/address_scan.py`，router `app/gateway/routers/skill_addresses.py`，tests `tests/test_skill_addresses.py`。范围仅运行中技能，不动 `deploy/minimal/skills/`。
 - **按钮管理 (Task Button Management, admin-only)**: configures the **可配置跳转按钮** rendered in the left task panel of the task deep-link workspaces (rwfx / 3qfx / xdfx, see `TaskFxWorkspace`). Each button = `{business, label, linkType, target, appendTaskId, idParam, idKind, enabled, sortOrder}`; `linkType` is `url` (外链 `window.open`, optional append of `?{idParam}={id}` — **`idParam` is the editable query-param name**, e.g. `id`/`task_id`), `business` (内部切换到另一业务, reuses `resolveTaskDeeplinkTarget`, always task id), or `purpose` (弹出当前任务的「任务目的」表格 via the shared `TaskPurposeDialog`, no target — configurable for any page incl. xdfx). **`idKind` (`task`/`action`) only matters for xdfx**: its deep-link `?taskId=` is an 行动id and the 任务id is resolved at login (`fetchTaskIdFromAction`) — `TaskContext` now also stashes the raw `actionId`, so a url button can append either (default `task`). Page `TaskButtonsPage.tsx` (route `/page/strategy/admin/task-buttons`, **admin-gated**, entry「按钮管理」in the bottom-left settings dropdown of `components/page-sidebar.tsx`, both full + collapsed modes) has per-business tabs, edits name/type/target/启停/排序/增删, saves the **whole set atomically** (replace-all), plus 「导入默认」 to merge code-seed defaults. **Seed/fallback** (like 敏感词管理): only when the whole table is empty (fresh deploy, never saved) do the workspace + page fall back to `defaultTaskButtons(cfg)` — rwfx's url buttons (编辑/下一步/3q详情) built from the **live** `/api/public/config/task-deeplink` plus cross-business switch buttons for **all three** businesses (each switches to the other two — rwfx→三情/行动, 3qfx→任务/行动, xdfx→任务/三情). Once saved, the store is the sole source of truth. The old hardcoded jump buttons were migrated out: `TaskFxWorkspace` no longer hardcodes 切换到三情分析, `TaskActionsPanel` keeps only the non-jump 清除记录, and `TaskPurposePanel` dropped its 3q详情 button (now configurable) **and defaults the 目的树 table to collapsed** (chevron toggle). Helpers `core/auth/task-buttons.ts` (`TaskButton`, `defaultTaskButtons`, `resolveTaskButtons`, `buttonsForBusiness`, `runTaskButton`), client+hooks `strategy-components/api/task-buttons.ts`. Backend: `/api/task-buttons` (global/shared; open read, admin replace-all), store `deerflow.persistence.task_buttons` (table `task_buttons`, auto-created by `create_all`), wired `app.state.task_button_store`. Tests: `tests/test_task_buttons.py`.

frontend-web/docs/position-roundtable-sandbox/README.md

@@ -0,0 +1,15 @@
+# 岗位会商沙箱文档
+
+本目录存放**岗位会商文件预览沙箱**的对接与排障说明，独立于 `src/position-roundtable/docs/`，避免与模块内其它文档互相覆盖。
+
+| 文档 | 说明 |
+| --- | --- |
+| [沙箱打开关闭与步骤条.md](./沙箱打开关闭与步骤条.md) | **详细版**：打开/关闭完整时序、步骤条关系、对接接口字段说明、必守规则、历史 bug 根因、排障手册、自测清单、接线示例与代码索引 |
+
+模块总览仍见：`frontend-web/src/position-roundtable/README.md`。
+
+建议读法：
+
+- **从零对接新页面**：正文第 3、5、6、7、8、12、15、16 节  
+- **线上排障**：第 13、14 节  
+- **只要一页纸**：文末「附录 A」

frontend-web/docs/position-roundtable-sandbox/沙箱打开关闭与步骤条.md

@@ -0,0 +1,988 @@
+# 岗位会商 · 沙箱打开 / 关闭与步骤条（详细对接与排障指南）
+
+> **文档位置**：`frontend-web/docs/position-roundtable-sandbox/`  
+> **读者**：下次重做或对接岗位会商页面的同事；线上「沙箱不实时 / 卡死 / 第二次不刷新」时的排障同学。  
+> **最后依据**：当前仓库 `PositionRoundtablePage` + `PositionNodeChat` 实现（含临时名打开、外部 store、前沿节流、按 tool-call 重挂）。
+
+---
+
+## 目录
+
+1. [文档用途与读法](#1-文档用途与读法)
+2. [背景：为什么岗位会商要单独做沙箱](#2-背景为什么岗位会商要单独做沙箱)
+3. [用户可见的正确行为（验收标准）](#3-用户可见的正确行为验收标准)
+4. [整体架构与数据流](#4-整体架构与数据流)
+5. [职责划分：谁拥有什么状态](#5-职责划分谁拥有什么状态)
+6. [对接接口详解](#6-对接接口详解)
+7. [打开沙箱的完整步骤](#7-打开沙箱的完整步骤)
+8. [关闭沙箱的完整步骤](#8-关闭沙箱的完整步骤)
+9. [步骤条与沙箱的关系](#9-步骤条与沙箱的关系)
+10. [流式内容如何进入沙箱（性能关键）](#10-流式内容如何进入沙箱性能关键)
+11. [与普通对话页的对照](#11-与普通对话页的对照)
+12. [重做页面时的必守规则](#12-重做页面时的必守规则)
+13. [历史问题与根因（务必读）](#13-历史问题与根因务必读)
+14. [排障手册（按症状）](#14-排障手册按症状)
+15. [对接自测清单](#15-对接自测清单)
+16. [最小接线示例](#16-最小接线示例)
+17. [关键代码索引](#17-关键代码索引)
+18. [术语表](#18-术语表)
+
+---
+
+## 1. 文档用途与读法
+
+### 1.1 这份文档解决什么问题
+
+岗位会商右侧「文件预览沙箱」看起来像普通对话页的产物预览，但实现路径完全不同。历史上这块反复出过：
+
+- 沙箱不实时打开，要等全文写完才弹；
+- 打开了但内容冻住，生成完才一口气灌进去；
+- 整页卡顿，连消息列表文字都不实时；
+- 同轮「重新生成」第二次写入时，步骤条变了，沙箱却不动；
+- 第一次正常，关掉后再问就不实时。
+
+这些 bug **特别容易在「重做页面 / 换布局 / 自己重写开沙箱逻辑」时复现**。本文把正确对接方式、时序、接口、禁区和排障步骤写全，方便下一位同事直接按文档接线，而不是再靠猜。
+
+### 1.2 建议读法
+
+| 你的目标 | 先读哪些章节 |
+| --- | --- |
+| 从零接一个新页面壳 | 第 3、5、6、7、8、12、15、16 节 |
+| 只改对话子组件探测逻辑 | 第 7、9、12、13 节 |
+| 线上排障 | 第 13、14 节，必要时回看第 10 节 |
+| 理解为什么不能用页面 state | 第 2、10、13 节 |
+
+### 1.3 对照代码（以仓库为准）
+
+| 角色 | 路径 |
+| --- | --- |
+| 页面壳（唯一沙箱宿主） | `frontend-web/src/position-roundtable/pages/PositionRoundtablePage.tsx` |
+| 节点对话（探测 write_file、上报预览） | `frontend-web/src/position-roundtable/components/PositionNodeChat.tsx` |
+| 收口对话 | `frontend-web/src/position-roundtable/components/PositionBuiltinAgentChat.tsx` |
+| 预览 UI（共享组件，勿分叉逻辑） | `frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx` |
+| 流式正文读取 | `frontend-web/src/core/artifacts/loader.ts` → `loadArtifactContentFromToolCall` |
+| 普通对话页对照（步骤条自动开） | `frontend-web/src/components/workspace/messages/message-group.tsx` |
+| 模块总览 | `frontend-web/src/position-roundtable/README.md` |
+
+---
+
+## 2. 背景：为什么岗位会商要单独做沙箱
+
+### 2.1 普通对话页怎么开沙箱
+
+普通对话页（`ChatPage`）大致是：
+
+```text
+ArtifactsProvider（页面级）
+  └─ ChatBox / MessageList
+       └─ message-group 渲染 write_file 步骤
+            └─ 发现 path 且 autoOpen → artifacts.select + setOpen(true)
+  └─ 右侧 ArtifactFileDetail 读同一套 ThreadContext
+```
+
+要点：
+
+- 对话和预览共享同一套 `ThreadContext`（同一个 `useThreadStream`）。
+- 步骤条组件自己就能触发打开。
+- 流式 `content` 本来就在当前 React 树的 thread 里，不需要「把 thread 镜像到别的地方」。
+
+### 2.2 岗位会商为什么不能照搬
+
+岗位会商页面同时有：
+
+- 左侧任务 / 意图 / 流程图；
+- 中间某个节点的对话（`PositionNodeChat`）；
+- 右侧配置抽屉；
+- **以及一个页面级单例沙箱**，它是对话区的**兄弟节点**，不在 `PositionNodeChat` 的 ThreadContext 里面。
+
+因此：
+
+1. 沙箱拿不到节点对话内部的 `thread`，除非节点主动上报；
+2. 若把每次流式 thread 写进**页面级 `useState`**，整页（任务卡、意图、流程图、对话）都会按流式频率重渲染，主线程会被打爆；
+3. 页面必须自己决定「开 / 关 / 抑制自动再开 / 切节点时清理」，不能让多个子组件各自 `setOpen`。
+
+所以岗位会商采用：
+
+```text
+对话子组件探测 + 上报
+  → 页面壳统一打开唯一 ArtifactFileDetail
+  → 流式 thread 走外部 store，只让沙箱子树订阅
+```
+
+### 2.3 和「多智能体会商 Step2 沙箱」的区别
+
+仓库里还有 `frontend-web/docs/roundtable-step2-sandbox-progress.md`，那是另一套圆桌 Step2 沙箱进度文档，**不是**岗位会商这条链路。对接岗位会商时以本文为准。
+
+---
+
+## 3. 用户可见的正确行为（验收标准）
+
+重做或对接完成后，下列行为必须全部成立（用户感知对齐普通对话页）：
+
+| # | 行为 | 说明 |
+| --- | --- | --- |
+| A | 步骤条刚出现「写入文件」时，沙箱应已打开 | **不必等**步骤条上出现文件名 |
+| B | 沙箱源码边写边滚；消息列表也实时出字 | 不能整页卡死、不能「生成完一口气刷」 |
+| C | content 先于 path 时：先临时名打开，path 到了再改名 | 不闪屏、不重挂 |
+| D | 同轮第二次同路径 `write_file`（重新生成） | 沙箱清空并重新流式 |
+| E | 整轮结束后自动切 Markdown 预览 | 「正在生成，完成后自动预览」消失 |
+| F | 用户手动关闭后，同一次写入不再自动弹 | 下一轮新写入仍可自动开 |
+| G | 切岗位 / 切节点 / 新会话 / 切历史 | 沙箱关掉且不串内容 |
+
+**不要误判的正常现象：**
+
+- 流式期间沙箱停在「源码 / 编辑」视图，结束后才切「预览」——这是 `ArtifactFileDetail` 对 markdown/html 的既定行为，与普通对话页相同，**不是**打开时机 bug。
+- 步骤条长时间显示「写入文件」、没有路径，但沙箱已经打开并在滚动——content-first 模型下这是**预期**。
+
+---
+
+## 4. 整体架构与数据流
+
+```text
+┌──────────────────────────────────────────────────────────────────────────┐
+│ PositionRoundtablePage（页面壳）                                           │
+│                                                                          │
+│  state: sandboxArtifact | null                                           │
+│  ref:   sandboxArtifactRef / closedSandboxKeyRef / latestSnapshotRef     │
+│  store: createSandboxThreadStore()   ←── 禁止改成 useState               │
+│                                                                          │
+│  handlePreviewArtifact(artifact)  ←──────────────────────────────────┐   │
+│  handleNodeThreadSnapshot(...)    ←───────────────────────────────┐  │   │
+│  closeSandbox()                                                   │  │   │
+│                                                                   │  │   │
+│  {sandboxOpen && (                                                │  │   │
+│     SandboxThreadProvider(store)                                  │  │   │
+│       └─ ArtifactFileDetail key=sandboxCloseKey(...)              │  │   │
+│  )}                                                               │  │   │
+└───────────────────────────────────────────────────────────────────│──│───┘
+                                                                    │  │
+┌───────────────────────────────────────────────────────────────────│──│───┐
+│ PositionNodeChat / PositionBuiltinAgentChat                         │  │   │
+│                                                                   │  │   │
+│  useThreadStream → thread.messages / thread.isLoading             │  │   │
+│       │                                                           │  │   │
+│       ├─ MessageList → 步骤条（只展示 tool call）                   │  │   │
+│       │                                                           │  │   │
+│       ├─ latestStreamingWriteFile(messages)                       │  │   │
+│       │     → onPreviewArtifact({..., auto:true}) ───────────────────┘   │
+│       │                                                                  │
+│       └─ useEffect → onThreadSnapshot({threadId, thread}) ───────────────┘
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+一句话：
+
+- **谁打开**：对话子组件决定「该不该开、开哪次交付」；  
+- **谁真正开面板**：页面壳；  
+- **内容怎么更新**：子组件持续上报 thread 快照 → 页面壳 store → 只有沙箱子树重渲染。
+
+---
+
+## 5. 职责划分：谁拥有什么状态
+
+### 5.1 页面壳必须拥有
+
+| 状态 / 能力 | 为什么必须在页面壳 |
+| --- | --- |
+| `sandboxArtifact` | 唯一预览目标；切节点时要清 |
+| `closedSandboxKeyRef` | 用户关过后的抑制；跨子组件生命周期 |
+| `sandboxThreadStore` | 流式内容通道；不能进大页面 state |
+| `closeSandbox()` | 切岗位 / 切节点 / 新会话统一入口 |
+| 唯一 `ArtifactFileDetail` | 避免双实例、关闭失效、深度异常 |
+
+### 5.2 对话子组件必须拥有
+
+| 状态 / 能力 | 作用 |
+| --- | --- |
+| `autoPreviewRunArmedRef`（armed） | 只有本轮用户发送后才允许自动开 |
+| `autoPreviewBaselineCallKeysRef`（baseline） | 忽略发送前已有的历史 write_file |
+| `activeWriteFilePreviewRef` | 记录当前打开的 previewKey / path / toolCallId |
+| `autoPreviewedArtifactKeyRef` | 同一次 identity 去重，避免每 chunk 重复上报 |
+| `latestStreamingWriteFile` | 从 streaming messages 探测可预览的 write |
+| `onThreadSnapshot` 上报 | 把 thread 喂给页面壳 |
+
+### 5.3 明确禁止
+
+1. 在 `PositionNodeChat` 内再挂一套 `ArtifactFileDetail`。  
+2. 让步骤条组件直接 `setOpen(true)` 作为岗位会商主路径（对照普通页可以，岗位会商不行）。  
+3. 把 `onThreadSnapshot` 落到 `PositionRoundtablePage` 的 `useState`。  
+4. 用「整个 threadId」做关闭抑制。  
+5. 用「path 相同」复用 `previewKey`。
+
+---
+
+## 6. 对接接口详解
+
+### 6.1 `PositionArtifactPreview`
+
+```ts
+type PositionArtifactPreview = {
+  threadId: string;          // 必填：LangGraph thread id
+  path: string;              // 必填：真实路径，或 write-file: 虚拟 URL，或临时文件名路径
+  name: string;              // 展示名（文件名）
+  mimeType: string | null;   // 如 text/markdown；帮助预览语言判断
+  previewKey?: string;       // 强烈建议：一次交付身份，推荐 `${messageId}:${toolCallId}`
+  auto?: boolean;            // true = 流式自动打开；缺省/false = 用户点击打开
+};
+```
+
+字段说明：
+
+| 字段 | 详细含义 |
+| --- | --- |
+| `threadId` | 沙箱用来匹配 `onThreadSnapshot` 的线程；也对关闭抑制键有贡献 |
+| `path` | 传给 `ArtifactFileDetail.filepath`。流式阶段通常是 `write-file:...` 虚拟 URL；落盘后的手动打开可以是真实 artifacts 路径 |
+| `name` | UI 展示用；临时名阶段可能是 `未命名文件.md` |
+| `mimeType` | 当 path 还不稳定时，帮助把语言判成 markdown/html，避免落成 TEXT |
+| `previewKey` | **一次交付的身份**。同一次 tool call 的 path 升级要保持不变；新的 tool call 必须变 |
+| `auto` | 自动打开才走关闭抑制；手动打开应清抑制 |
+
+### 6.2 `onPreviewArtifact(artifact)` —— 对话 → 页面
+
+页面壳 `handlePreviewArtifact` 当前逻辑顺序：
+
+1. 校验 `threadId`、`path`，缺则 toast 并 return。  
+2. 计算 `artifactKey = sandboxCloseKey(artifact)`。  
+3. 若 `artifact.auto === true` 且 `closedSandboxKeyRef.current === artifactKey` → **抑制，直接 return**。  
+4. 清 `closedSandboxKeyRef`（手动打开或新的自动打开）。  
+5. `ArtifactsContext.select(path, true)` + `setOpen(true)`。  
+6. 判断是否同一预览 / 是否仅 path upgrade：  
+   - `isSamePreview`：threadId + path + previewKey 全同 → 不重复 setState。  
+   - `isPathUpgrade`：previewKey 相同、path 不同 → 更新 artifact，**不要**再折叠右侧抽屉。  
+7. 若不是 same preview：  
+   - `setSandboxArtifact(artifact)`；  
+   - **同步** `sandboxArtifactRef.current = artifact`（关键！flush 会立刻读 ref）；  
+   - `sandboxSnapshotAppliedAtRef.current = 0`（允许立刻推首帧内容）。  
+8. 若 store 里已有别的 thread 快照，先 `publish(null)`。  
+9. 若 `latestNodeThreadSnapshotRef` 的 threadId 匹配，立刻 `queueSandboxThreadSnapshot`。  
+10. 非 path upgrade 时 `setRightPanelOpen(false)`。
+
+`sandboxCloseKey`：
+
+```ts
+if (artifact.previewKey) {
+  return `${artifact.threadId}:write:${artifact.previewKey}`;
+}
+return `${artifact.threadId}:${normalizePreviewArtifactPath(artifact.path)}`;
+```
+
+`ArtifactFileDetail` 的 React `key` 必须用这个 key：  
+**新 previewKey → 组件重挂 → 视觉上「清空再生成」。**
+
+### 6.3 `onThreadSnapshot({ threadId, thread })` —— 对话 → 页面
+
+每次 `thread` 引用变化（消息 chunk 到达）子组件都会调：
+
+```ts
+onThreadSnapshot?.({ threadId: activeThreadId, thread });
+```
+
+页面壳应：
+
+1. 计算 `signature = sandboxThreadSignature(thread)`（用 isLoading、messages 长度、最近 write_file 的 path/content 长度/尾部等拼签名，用于去重）。  
+2. 写入 `latestNodeThreadSnapshotRef`（即使沙箱还没开，打开瞬间也要用）。  
+3. 若当前没有打开的沙箱，或打开的沙箱 threadId 不一致 → **只更新 ref，不 publish**。  
+4. 若一致 → `queueSandboxThreadSnapshot`（前沿节流后 `store.publish`）。
+
+### 6.4 虚拟 URL 与正文读取
+
+流式阶段 path 形如：
+
+```text
+write-file:${sourcePath}?message_id=${messageId}&tool_call_id=${toolCallId}&language=markdown
+```
+
+`loadArtifactContentFromToolCall`：
+
+1. 解析 URL 的 `message_id`、`tool_call_id`；  
+2. 在 `thread.messages` 里找对应 AI message 的 tool call；  
+3. 返回 `toolCall.args.content`。
+
+结论：
+
+- 沙箱跟的是 **tool call 身份**，不是磁盘文件是否已经写完；  
+- 没有真实 path 也能显示正文；  
+- 临时文件名只影响展示名和语言猜测。
+
+### 6.5 对话子组件 → 页面壳的其它相关回调
+
+| 回调 | 用途 |
+| --- | --- |
+| `onPreviewArtifact` | 打开 / 更新沙箱 |
+| `onThreadSnapshot` | 推送流式 thread |
+| 页面壳 `closeSandbox` 传给 `ArtifactFileDetail.onClose` | 用户点关闭 |
+
+手动从流程图 / 产物列表打开时，也可以直接调 `handlePreviewArtifact`（通常不带 `auto`，或不带 previewKey）。
+
+---
+
+## 7. 打开沙箱的完整步骤
+
+### 7.1 武装（arm）：只有「本轮用户提交」才允许自动开
+
+在 `PositionNodeChat.handleSubmit` 真正 `sendMessage` 之前：
+
+```text
+activeWriteFilePreviewRef = null
+autoPreviewBaselineCallKeysRef = writeFileCallKeys(thread.messages)  // 历史 write 的 messageId:toolCallId
+autoPreviewRunArmedRef = true
+→ sendMessage(...)
+```
+
+发送失败要把 `armed` 设回 `false`。
+
+为什么要 baseline？
+
+线程里往往已经有上几次问答写过的 `write_file`。如果只看「messages 里有没有 write_file」，一提问就会把旧文件再打开一次。baseline 的含义是：**只有这次提交之后新出现的 tool call 才能自动开沙箱**。
+
+### 7.2 探测 `write_file`：不要等完整 path
+
+`write_file` 参数是一整段 JSON 流，**键顺序由模型决定**。
+
+| 模型吐参顺序 | 步骤条表现 | 错误做法的后果 |
+| --- | --- | --- |
+| path / description 先到，再 content | 很快显示描述和文件名 | 普通对话页常见；等 path 也能开 |
+| **content 先到，最后才 path** | 长时间只有「写入文件」，文件名很晚才出现 | 若硬等完整 path，沙箱会晚几十秒甚至一分钟 |
+
+岗位会商报告类 agent **经常是第二种**。
+
+`latestStreamingWriteFile` 规则：
+
+1. 倒序扫描 AI messages 的 `tool_calls`；  
+2. 工具名是 `write_file` 或 `str_replace`；  
+3. **有完整扩展名的 path**（`hasCompleteArtifactExtension`）→ 用真实路径；  
+4. **尚无可用 path，但 `write_file` 的 content 已有非空字符** → 临时文件名：  
+   - 正文头像 HTML → `未命名文件.html`  
+   - 否则 → `未命名文件.md`  
+5. `str_replace` 必须等真实 path（它改已有文件）；  
+6. 组装：  
+   - `key = messageId:toolCallId`  
+   - `path = write-file:虚拟URL`（write_file）或真实 path（str_replace）  
+   - `mimeType`：markdown 则 `text/markdown`
+
+为什么扩展名必须完整？
+
+流式 path 会经历 `/a/b/report.m` → `/a/b/report.md`。若在 `.m` 时就当真实文件打开，预览语言可能被永久判成 TEXT。
+
+### 7.3 上报 effect 的四个门闩
+
+自动上报 `onPreviewArtifact` 前必须同时满足：
+
+1. `thread.isLoading === true`  
+2. 探测到 streaming artifact，且其 key **不在** baseline  
+3. 已有 `previewThreadId`  
+4. `autoPreviewRunArmedRef === true`
+
+然后处理 previewKey：
+
+```text
+若与 activePreview 是同一次 tool call（含 tool-start 前缀兼容）
+  → 复用旧 previewKey   // 用于临时名 → 真实 path
+否则
+  → previewKey = 新的 messageId:toolCallId
+```
+
+去重键：
+
+```text
+`${previewThreadId}:${previewKey}:${sourcePath}`
+```
+
+把 `sourcePath` 算进去，是为了：**同 previewKey 下临时名变成真实 path 时，还要再报一次**（path upgrade），但不会每来一个 content chunk 都报。
+
+### 7.4 线程绑定竞态（不要误 disarm）
+
+首轮对话常出现：
+
+1. 用户发送（本地 draft threadId / 稍后 SDK 创建真实 id）；  
+2. 流已经开始、armed=true；  
+3. 会话 API 把 `node.threadId` 从 `null` 写成真实 id。
+
+这是「本节点绑定自己的新线程」，**不是**切节点。若绑定 effect 无脑清空 armed / baseline，首轮会永远开不了沙箱。
+
+正确：识别 `isOwnThreadBinding`（同 nodeKey、旧 threadId 为空、新 threadId 等于当前 boundThreadId）时 **直接 return，不清 armed**。
+
+### 7.5 path upgrade（改名）≠ 第二次交付
+
+同一次 tool call：
+
+```text
+T1  content 到达 → path=未命名文件.md, previewKey=msg:tc1 → 打开
+T2  真实 path 到达 → path=/mnt/.../报告.md, previewKey=msg:tc1 → 只改名
+```
+
+页面壳看到相同 previewKey、不同 path → `isPathUpgrade`：
+
+- 更新 `sandboxArtifact`；  
+- **不**重挂（React key 仍基于 previewKey）；  
+- **不**再折叠右侧抽屉。
+
+### 7.6 同路径二次写入（重新生成）
+
+同一次问答里模型可能：
+
+```text
+1) write_file → 步骤条「写入文件」→ 打开沙箱
+2) 再 write_file 同 path，description=「重新生成优化版…」
+```
+
+这是**两次 tool call**，必须两个 previewKey。  
+若错误地「path 相同就复用 previewKey」：
+
+- 步骤条出现第二条；  
+- 沙箱 React key 不变；  
+- 用户看到「重新生成了，但沙箱没变化」。
+
+正确：身份只看 tool call。
+
+### 7.7 时序总图（content-first）
+
+```text
+T0    用户发送 → armed=true，拍 baseline
+T1    步骤条出现「写入文件」（尚无 path）
+T1+   args.content 首字符到达 → 临时名打开沙箱，源码开始滚动
+      … store 约每 160ms 推一次 thread 快照 …
+T2    args.path 拼完整（含 .md）→ path upgrade，标题改真实文件名（不重挂）
+T3    write 结束 / isLoading=false → 自动切 Markdown 预览
+```
+
+### 7.8 时序总图（同轮二次写入）
+
+```text
+T1  write_file#1 → previewKey=msg:tc1 → 打开沙箱 A
+T2  #1 结束（可能短暂切预览）
+T3  write_file#2（同 path，新 description）→ previewKey=msg:tc2
+    → key 变 → 组件重挂清空 → 跟 #2 重新流式
+```
+
+---
+
+## 8. 关闭沙箱的完整步骤
+
+### 8.1 用户手动关闭
+
+`closeSandbox()` 应做：
+
+1. `closedSandboxKeyRef = sandboxCloseKey(current)` —— 抑制**这一次**自动再开；  
+2. 关闭 `ArtifactsContext.open`（若开着）；  
+3. 清节流定时器、pending 快照；  
+4. `sandboxSnapshotAppliedAtRef = 0`；  
+5. `sandboxArtifactRef = null` + `setSandboxArtifact(null)`；  
+6. `sandboxThreadStore.publish(null)`。
+
+抑制与 path upgrade 的关系：
+
+- 关掉临时名面板后，同一次 tool call 升级真实 path **仍被抑制**（同一 previewKey）——符合「用户不要看这次」；  
+- 下一次新的 `write_file`（新 previewKey）**可以**再自动开。
+
+### 8.2 场景切换时强制关闭
+
+以下操作应先调用 `closeSandbox()`，避免串台：
+
+- 切岗位；  
+- 切节点；  
+- 切收口阶段；  
+- 新建会话；  
+- 切换历史会话。
+
+是否写入 `closedSandboxKeyRef` 可按产品决定；至少必须清面板和 store。
+
+### 8.3 错误的抑制粒度（历史坑）
+
+若做成「关过一次就整个 thread 不再自动开」：
+
+- 第一次实时开正常；  
+- 用户关掉；  
+- 再问一次 → 同 thread 被永久抑制 → 看起来像「第二次不实时 / 要等生成完」。
+
+正确粒度：**单次交付的 `sandboxCloseKey`（含 previewKey）**。
+
+---
+
+## 9. 步骤条与沙箱的关系
+
+### 9.1 步骤条从哪来
+
+步骤条由 `MessageList` → `message-group.tsx` 渲染 tool call：
+
+- 标题：优先 `args.description`；没有则 i18n 兜底「写入文件」；  
+- 子行：有 `args.path` 才显示路径；  
+- 普通对话页还会在「有 path + autoOpen」时自己 `select/setOpen`。
+
+岗位会商里，步骤条**仍然只负责展示**；打开沙箱走 `onPreviewArtifact`，不要让两套逻辑抢。
+
+### 9.2 对照表
+
+| 你看到的步骤条 | 含义 | 沙箱应处于 |
+| --- | --- | --- |
+| 仅「写入文件」，无路径 | tool call 已开始；path/description 可能还没流到 | **应已打开**（临时名），源码在滚 |
+| 「写入文件」+ 路径 | path 已可用 | 已打开；若刚从临时名升级则只改名 |
+| 带自定义 description 的标题 + 路径 | 模型给了 description | 同上 |
+| 第二条「重新生成…」+ 同路径 | 新的 write_file（新 toolCallId） | **应重挂**并重新流式 |
+| 顶部「正在生成，完成后自动预览」 | 仍在 code 视图 | 正常，等 isLoading 结束切预览 |
+| 生成结束，出现文件卡片 / present_files | 工具结果已落 | 通常已是预览模式；可手动再点开 |
+
+### 9.3 常见误解
+
+**误解 1：**「步骤条出现文件名 = 打开沙箱的正确时机」  
+→ 错。那是 path 到达的时机。content-first 时正确打开时机更早：content 首字节 / 工具调用已开始。
+
+**误解 2：**「步骤条还在写『写入文件』，沙箱却开了，是 bug」  
+→ 通常不是。两边数据源相同，但沙箱允许无 path 打开，步骤条标题可能还没 description。
+
+**误解 3：**「等生成完从编辑切预览 = 沙箱打开晚了」  
+→ 错。那是 `ArtifactFileDetail` 的 viewMode 策略。
+
+---
+
+## 10. 流式内容如何进入沙箱（性能关键）
+
+### 10.1 为什么不能用页面 `useState` 存线程快照
+
+错误写法：
+
+```ts
+setSandboxThreadSnapshot(snapshot) // 页面级 useState
+```
+
+后果：
+
+- 消息 chunk 约每 30ms 一次，节流后仍约 6 次/秒；  
+- 每次都重渲染整页：任务卡、意图结果、流程图、节点对话……；  
+- 主线程占满 → 消息列表停绘、沙箱冻住；  
+- 纯尾随 `setTimeout(160)` 会被饿死，十几秒不 flush。
+
+这同时解释了两个历史现象：
+
+1. 「沙箱打开了但内容不更新」；  
+2. 「修完节流后整页更卡、消息也不实时」——因为节流终于开始真正 setState 了。
+
+### 10.2 正确做法：外部 store + 子树订阅
+
+```ts
+createSandboxThreadStore()
+  subscribe / getSnapshot / publish
+
+SandboxThreadProvider
+  useSyncExternalStore(store.subscribe, store.getSnapshot)
+  → ThreadContext.Provider value={{ thread, isMock:false }}
+  → ArtifactFileDetail
+```
+
+页面壳本身**不**因 snapshot 变化而重渲染；只有 Provider 及其子树重渲染。
+
+### 10.3 节流必须是前沿（leading-edge）
+
+`SANDBOX_SNAPSHOT_MIN_INTERVAL_MS = 160`：
+
+```text
+queue(snapshot):
+  pending = snapshot
+  if 距上次 publish >= 160ms:
+      立刻 flush（同步 publish）
+  else:
+      若没有在途 timer，则 setTimeout(剩余时间) 做补尾
+flush:
+  清 timer
+  校验 pending.threadId === sandboxArtifactRef.threadId
+  publish(pending)
+```
+
+**不要**改回：
+
+```ts
+if (timer != null) return;
+timer = setTimeout(flush, 160);
+```
+
+那是纯尾随；忙主线程下会假死。
+
+### 10.4 signature 去重
+
+`sandboxThreadSignature` 用最近 write_file 的 path、content 长度、content 尾 32 字等拼签名。  
+store.publish 时若 threadId+signature 未变，则不通知订阅者，减少无效渲染。
+
+### 10.5 打开瞬间的首帧
+
+`handlePreviewArtifact` 里往往会立刻 `queueSandboxThreadSnapshot(latestSnapshot)`。  
+此时 React 的 `setSandboxArtifact` 可能还没提交，若 flush 只读旧的 `sandboxArtifactRef`，会因 threadId 不匹配把首帧丢掉。
+
+所以打开新预览时必须：
+
+```ts
+sandboxArtifactRef.current = artifact; // 同步
+sandboxSnapshotAppliedAtRef.current = 0;
+```
+
+---
+
+## 11. 与普通对话页的对照
+
+| 点 | 普通对话页 | 岗位会商 |
+| --- | --- | --- |
+| 谁触发打开 | `message-group` 内 `artifacts.select` | 子组件 `onPreviewArtifact` → 页面壳 |
+| 是否要求 path | 是（有 path 才自动开） | 否（write_file + content 可临时名开） |
+| thread 从哪来 | 同树 ThreadContext | `onThreadSnapshot` + 外部 store |
+| 关闭抑制 | 主要靠 ArtifactsContext / 用户操作 | `closedSandboxKeyRef` 按 previewKey |
+| 同 path 重写 | 依赖新的 tool call / 选择逻辑 | **必须**新 previewKey 以重挂 |
+| 结束后切预览 | ArtifactFileDetail 同一套 | 同一套 |
+
+对齐目标是**用户感知一致**，不是代码路径完全相同。
+
+普通对话页自动开的核心条件（对照用）：
+
+```ts
+artifacts && isLoading && isLast && autoOpen && autoSelect && path && !result
+```
+
+它也要求 path，所以 content-first 时普通页同样会偏晚——只是很多主聊天示例 agent 先吐 path，观感更好。岗位会商报告 agent 更常 content-first，所以必须做临时名提前开。
+
+---
+
+## 12. 重做页面时的必守规则
+
+按优先级：
+
+1. **流式 thread 快照禁止进页面级 `useState`** → 用 store + `useSyncExternalStore`。  
+2. **节流用前沿 + 补尾**，不要纯尾随 timer。  
+3. **不要等完整 path 才开**；`write_file` + content 即可临时名打开。  
+4. **扩展名完整前不要把 path 当最终 path**。  
+5. **previewKey 按 tool call，不按 path**。  
+6. **打开时同步写 `sandboxArtifactRef`，并重置节流时间戳**。  
+7. **主路径扫描 `thread.messages`，不要只靠 `onToolStart`**。  
+8. **path upgrade 保持 previewKey，不要当第二次交付**。  
+9. **关闭抑制按 sandboxCloseKey，不要按整 thread**。  
+10. **沙箱单例在页面壳；子组件只上报**。  
+11. **本节点 threadId 回写不要 disarm**。  
+12. **「结束后才切预览」不要当打开 bug 去「修」掉共享组件**，除非产品明确要求边生成边渲染 Markdown（需单独评估性能）。
+
+---
+
+## 13. 历史问题与根因（务必读）
+
+下面每个都在真实联调里出现过。重做时若踩中，优先回来对照。
+
+### 13.1 沙箱要等文件名出来才开（晚几十秒）
+
+**现象：** 步骤条早就「写入文件」，沙箱很晚才开；普通对话页对比显得「实时」。  
+
+**根因：** 探测逻辑硬等完整 `path`；而该 agent 先流 `content`、最后才流 `path`。  
+
+**修复：** content 首批字符即可用临时名打开；path 到了再 upgrade。
+
+### 13.2 沙箱打开了，内容冻住，生成完才灌满
+
+**现象：** 面板开了，但里面一直是空/旧内容；日志里 queue 很多，flush 很少。  
+
+**根因：** 纯尾随 160ms 定时器在忙主线程下被饿死。  
+
+**修复：** 前沿节流——到期就在流回调里同步 flush。
+
+### 13.3 修完「内容更新」后，整页卡顿、消息也不实时
+
+**现象：** 沙箱开始更新了，但页面更卡，消息列表也「攒到最后刷」。  
+
+**根因：** flush 走的是页面 `useState`，每 160ms 整页重渲染。以前 timer 饿死时反而「不卡」。  
+
+**修复：** 快照改外部 store，只让沙箱子树订阅。
+
+### 13.4 第二次「重新生成」步骤有了，沙箱不变
+
+**现象：** 同轮第二条二条 write 步骤，沙箱仍显示第一次完整结果。  
+
+**根因：** 用「path 相同」复用了第一次 previewKey，React key 不变，组件不重挂。  
+
+**修复：** previewKey 只按 tool call；同 path 新 call 必须新 key。
+
+### 13.5 第一次实时，关掉后再问就不实时
+
+**现象：** 关过沙箱后，下一轮要等生成完才开，或不开。  
+
+**根因：** 抑制绑在整个 threadId，或把 path upgrade / 新 call 误判成同一次。  
+
+**修复：** 抑制键 = `sandboxCloseKey(previewKey)`；仅抑制那一次交付。
+
+### 13.6 首轮永远不开
+
+**现象：** 新建节点第一次提问，armed 后很快又不满足条件。  
+
+**根因：** `node.threadId` 从 null 回写真实 id 时，绑定 effect 误 disarm。  
+
+**修复：** `isOwnThreadBinding` 时不清 armed。
+
+### 13.7 预览变成纯文本
+
+**现象：** 明明是 md，却按 TEXT 打开。  
+
+**根因：** 在 `.m` 阶段就当完整 path；或临时名没有 `.md` / 没传 language、mimeType；或 path 带空格。  
+
+**修复：** `hasCompleteArtifactExtension`；临时名带扩展名；URL 加 `language=markdown`；path trim。
+
+### 13.8 依赖 onToolStart，线上偶发不开
+
+**现象：** 本地偶发正常，联调经常不开。  
+
+**根因：** 后端 StreamBridge / worker 可能过滤 tools/events 类 stream mode。  
+
+**修复：** 主路径必须是 messages 里渐进出现的 `tool_calls`；onToolStart 只能当补充。
+
+---
+
+## 14. 排障手册（按症状）
+
+排障时建议先看 Chrome Performance / React 重渲染是否整页抖，再看消息里 tool_calls 的 args 是 path-first 还是 content-first。
+
+### 14.1 沙箱开得很晚
+
+检查顺序：
+
+1. `latestStreamingWriteFile` 是否仍要求完整 path？  
+2. armed 是否被 threadId 回写清掉？  
+3. 是否命中 `closedSandboxKey`？  
+4. 新 call 是否被 baseline 当成历史？  
+5. `previewThreadId` 是否为空（线程还没绑上）？
+
+### 14.2 打开了但内容空白 / 冻住
+
+1. 快照是否进了页面 useState？  
+2. 节流是否纯尾随？  
+3. `SandboxThreadProvider` 是否拿到带 messages 的 thread？  
+4. 虚拟 URL 的 message_id / tool_call_id 是否对得上？  
+5. 打开时 `sandboxArtifactRef` 是否同步？（首帧是否被 drop）  
+6. signature 是否因实现错误一直不变，导致 publish 被去重？
+
+### 14.3 整页卡、消息列表也不实时
+
+1. 搜页面壳是否还有 `setSandboxThreadSnapshot` / 类似大对象 state。  
+2. 是否在每 chunk `console.debug` 打大对象（DevTools 打开时更卡）。  
+3. 是否错误地让页面壳订阅了 store（页面壳不应 `useSyncExternalStore` 这份 store；只有 Provider 订）。
+
+### 14.4 重新生成不刷新
+
+1. 第二次 write 的 toolCallId 是否变了？  
+2. previewKey 是否仍用 path 复用？  
+3. `ArtifactFileDetail` 的 `key=` 是否基于 sandboxCloseKey/previewKey？
+
+### 14.5 关后再问异常
+
+1. 打印 `closedSandboxKeyRef` 与新 artifact 的 sandboxCloseKey。  
+2. 确认新一轮 send 时 armed/baseline 已重置。  
+3. 确认抑制不是整 thread。
+
+### 14.6 语言 / 预览模式不对
+
+1. 看打开时的 path / mimeType / language 查询参数。  
+2. 确认不是在扩展名不完整时打开。  
+3. 确认「源码→预览」发生在 isLoading false 之后（属正常）。
+
+---
+
+## 15. 对接自测清单
+
+重做页面后至少跑完：
+
+### 功能
+
+- [ ] 首轮：步骤条「写入文件」出现时，沙箱是否已开并开始出字？  
+- [ ] content-first agent：无文件名阶段是否也能开？  
+- [ ] path 到达后：是否只改名、不整页闪、不重挂？  
+- [ ] 同轮第二次同路径 write：是否清空并重新流式？  
+- [ ] 结束后是否自动切 Markdown 预览？  
+- [ ] 手动点步骤条路径 / 产物卡片：能否打开正确文件？  
+
+### 关闭与抑制
+
+- [ ] 流式中手动关闭：本次是否不再自动弹？  
+- [ ] 关闭后再发一轮新问题：是否仍可自动开？  
+- [ ] path upgrade 是否不会绕过「用户刚关闭」的抑制？  
+
+### 场景切换
+
+- [ ] 切节点：沙箱关闭，旧内容不残留。  
+- [ ] 切岗位：同上。  
+- [ ] 新建会话 / 切历史：同上。  
+
+### 性能
+
+- [ ] 流式中消息列表是否实时出字？  
+- [ ] 页面是否明显掉帧 / 卡死？  
+- [ ] React DevTools 中，大页面壳是否在每 160ms 整页 update？（不应）
+
+---
+
+## 16. 最小接线示例
+
+### 16.1 页面壳（示意）
+
+```tsx
+const [sandboxArtifact, setSandboxArtifact] = useState<PositionArtifactPreview | null>(null);
+const sandboxArtifactRef = useRef<PositionArtifactPreview | null>(null);
+const closedSandboxKeyRef = useRef<string | null>(null);
+const latestNodeThreadSnapshotRef = useRef<SandboxThreadSnapshot | null>(null);
+const store = useMemo(createSandboxThreadStore, []);
+// pending + timer + appliedAt 用于前沿节流（见 PositionRoundtablePage）
+
+function handlePreviewArtifact(artifact: PositionArtifactPreview) {
+  if (!artifact.threadId || !artifact.path) return;
+  const key = sandboxCloseKey(artifact);
+  if (artifact.auto && closedSandboxKeyRef.current === key) return;
+  closedSandboxKeyRef.current = null;
+
+  artifactsCtx?.select(artifact.path, true);
+  artifactsCtx?.setOpen(true);
+
+  const prev = sandboxArtifactRef.current;
+  const isSame =
+    prev?.threadId === artifact.threadId &&
+    prev.path === artifact.path &&
+    prev.previewKey === artifact.previewKey;
+  const isPathUpgrade =
+    !isSame &&
+    Boolean(artifact.previewKey) &&
+    prev?.threadId === artifact.threadId &&
+    prev.previewKey === artifact.previewKey;
+
+  if (!isSame) {
+    sandboxArtifactRef.current = artifact; // 必须同步
+    setSandboxArtifact(artifact);
+    sandboxSnapshotAppliedAtRef.current = 0;
+  }
+
+  if (store.getSnapshot()?.threadId !== artifact.threadId) {
+    store.publish(null);
+  }
+  const latest = latestNodeThreadSnapshotRef.current;
+  if (latest?.threadId === artifact.threadId) {
+    queueSandboxThreadSnapshot(latest);
+  }
+  if (!isPathUpgrade) setRightPanelOpen(false);
+}
+
+function handleNodeThreadSnapshot(snapshot: { threadId: string; thread: BaseStream<AgentThreadState> }) {
+  const next = { ...snapshot, signature: sandboxThreadSignature(snapshot.thread) };
+  latestNodeThreadSnapshotRef.current = next;
+  if (sandboxArtifactRef.current?.threadId !== snapshot.threadId) return;
+  queueSandboxThreadSnapshot(next);
+}
+
+function closeSandbox() {
+  if (sandboxArtifactRef.current) {
+    closedSandboxKeyRef.current = sandboxCloseKey(sandboxArtifactRef.current);
+  }
+  // clear timer / pending / appliedAt
+  sandboxArtifactRef.current = null;
+  setSandboxArtifact(null);
+  store.publish(null);
+  artifactsCtx?.setOpen(false);
+}
+
+// 渲染
+{sandboxArtifact && (
+  <SandboxThreadProvider
+    store={store}
+    threadId={sandboxArtifact.threadId}
+    fallbackThread={stub}
+  >
+    <ArtifactFileDetail
+      key={sandboxCloseKey(sandboxArtifact)}
+      filepath={sandboxArtifact.path}
+      threadId={sandboxArtifact.threadId}
+      mimeType={sandboxArtifact.mimeType}
+      onClose={closeSandbox}
+      allowVirtualMarkdownEdit
+    />
+  </SandboxThreadProvider>
+)}
+```
+
+### 16.2 对话子组件（示意）
+
+```tsx
+// send 前
+activeWriteFilePreviewRef.current = null;
+autoPreviewBaselineCallKeysRef.current = writeFileCallKeys(thread.messages);
+autoPreviewRunArmedRef.current = true;
+await sendMessage(...);
+
+// 探测
+const streaming = thread.isLoading ? latestStreamingWriteFile(thread.messages) : null;
+const next =
+  streaming && !autoPreviewBaselineCallKeysRef.current.has(streaming.key)
+    ? streaming
+    : null;
+
+useEffect(() => {
+  if (!thread.isLoading || !next || !previewThreadId || !autoPreviewRunArmedRef.current) return;
+
+  // previewKey：同 tool call 复用，否则用 next.key
+  // artifactKey = threadId:previewKey:sourcePath 去重
+  onPreviewArtifact?.({
+    threadId: previewThreadId,
+    path: next.path,
+    name: next.name,
+    mimeType: next.mimeType,
+    previewKey,
+    auto: true,
+  });
+}, [next, previewThreadId, thread.isLoading, onPreviewArtifact]);
+
+useEffect(() => {
+  onThreadSnapshot?.({ threadId: activeThreadId, thread });
+}, [activeThreadId, thread, onThreadSnapshot]);
+```
+
+**强烈建议：** 探测 / armed / baseline / 临时名逻辑直接复用或抽取自 `PositionNodeChat`，不要从零重写。
+
+---
+
+## 17. 关键代码索引
+
+| 主题 | 位置 |
+| --- | --- |
+| 临时名 / 完整扩展名 / latestStreamingWriteFile | `PositionNodeChat.tsx` 中 `provisionalWriteFilePath`、`hasCompleteArtifactExtension`、`latestStreamingWriteFile` |
+| armed / baseline / 上报 effect | `PositionNodeChat.tsx` `handleSubmit` + streaming preview `useEffect` |
+| 同 tool call 判断 / 二次写入重挂 | 同上，`isSameToolCall` / `previewKey` |
+| 线程绑定保护 | `PositionNodeChat.tsx` node binding `useEffect` 中 `isOwnThreadBinding` |
+| sandboxCloseKey / store / 前沿节流 | `PositionRoundtablePage.tsx` `sandboxCloseKey`、`createSandboxThreadStore`、`queueSandboxThreadSnapshot` |
+| 打开 / path upgrade / 抑制 | `PositionRoundtablePage.tsx` `handlePreviewArtifact` |
+| 关闭 | `PositionRoundtablePage.tsx` `closeSandbox` |
+| 虚拟 URL 读 content | `core/artifacts/loader.ts` `loadArtifactContentFromToolCall` |
+| 源码/预览切换 | `artifact-file-detail.tsx` 中 `viewMode` + `thread.isLoading` |
+| 普通页步骤条自动开 | `message-group.tsx` `write_file` 分支 |
+
+相关提交（背景）：
+
+- `fix(frontend): 岗位会商沙箱在 write_file 流式阶段实时打开并刷新`  
+  — 临时名打开、外部 store、前沿节流  
+- `fix(frontend): 同路径二次 write_file 时重挂岗位会商沙箱`  
+  — previewKey 按 tool call，禁止按 path 复用  
+
+---
+
+## 18. 术语表
+
+| 术语 | 含义 |
+| --- | --- |
+| armed | 本轮用户发送后，允许自动打开沙箱的开关 |
+| baseline | send 前已有的 write tool call 集合，用于忽略历史产物 |
+| previewKey | 一次交付的稳定身份，推荐 `messageId:toolCallId` |
+| sandboxCloseKey | 关闭抑制键，同时用作 `ArtifactFileDetail` 的 React key |
+| provisional path / 临时名 | 尚无真实 path 时的 `未命名文件.md` / `.html` |
+| path upgrade | 同 previewKey 下临时名升级为真实 path |
+| sandboxThreadStore | 流式线程外部 store，避免整页重渲染 |
+| write-file: URL | 用 message_id + tool_call_id 定位流式 content 的虚拟路径 |
+| leading-edge throttle / 前沿节流 | 到期立即在回调里 publish，而不是只挂尾随 timer |
+| content-first / path-first | 模型流式 JSON 参数时 content 与 path 哪个先到 |
+| isOwnThreadBinding | 本节点把自己的新 threadId 写回 props，不是切节点 |
+
+---
+
+## 附录 A：给对接同学的一页纸摘要
+
+1. 页面壳只挂一个沙箱；子组件只调用 `onPreviewArtifact` / `onThreadSnapshot`。  
+2. 自动打开时机 ≈ 步骤条出现「写入文件」时，而不是出现文件名时。  
+3. `write_file` 可以没有 path：临时名打开，path 到了再改名。  
+4. 流式 thread 进外部 store，进页面 state 会卡死。  
+5. 节流要前沿；previewKey 看 tool call；关闭抑制看 sandboxCloseKey。  
+6. 同路径重新生成 = 新 previewKey = 沙箱重挂。  
+7. 出问题先对照第 13、14 节，再看代码索引第 17 节。

frontend-web/docs/沙箱统一写作管线-实现方案.md

@@ -0,0 +1,822 @@
+# 沙箱统一写作管线：可实现开发方案
+
+> 状态：设计稿；本文件只定义实施方案，不包含本轮业务代码改动。  
+> 覆盖范围：普通沙箱 Markdown、深度研究 `report.md`、现有 Markdown 编辑器的选区/段落改写。
+
+## 1. 目标与结论
+
+目标不是再增加一个“AI 写作页面”，而是将现有的四类能力统一为一个安全、可流式、可追溯的**文档改写管线**：
+
+1. Markdown 编辑器选区改写；
+2. Markdown 编辑器段落改写；
+3. 深度研究报告的局部候选改写；
+4. 沙箱中 Markdown 文件的全文改写。
+
+该管线负责固定原文版本、构造上下文、逐 token 输出、校验 Markdown、生成可核验 diff、按策略提交，以及在全文覆盖时保存可撤销版本。
+
+结论：需求可行，现有工程已有足够的复用基础：
+
+- `frontend-web/src/open-canvas/components/artifact/MarkdownAiEditor.tsx` 已具备局部改写弹窗与人工“替换/插入/重试/追问”交互。
+- `frontend-web/src/open-canvas/hooks/useWritingRewrite.ts` 与 `frontend-web/src/open-canvas/api/rewrite.ts` 已具备 SSE 文本流消费。
+- `offline-backend-20260512/backend/app/gateway/routers/writing.py` 已具备模型流式读取实现。
+- `offline-backend-20260512/backend/app/gateway/routers/deep_research.py` 已具备报告哈希、候选内容和用户确认应用机制。
+- `frontend-web/src/components/workspace/messages/message-list.tsx`、`MessageGroup.tsx` 已可承载普通对话的工具步骤条、流式消息和文件卡片。
+- `frontend-web/src/pages/deep-research/DeepResearchWorkbench.tsx` 已经通过虚拟消息把研究进度接入普通 `MessageList`。
+
+因此应该复用这些基础，建设一个执行内核；不能为全文改写另建独立聊天列表或独立写作流。
+
+## 2. 产品边界与交互策略
+
+### 2.1 支持范围
+
+第一版仅对 `.md`、`.markdown` 文件显示“AI 全文改写”按钮。
+
+不支持 PDF、DOCX、HTML、图片和二进制文件；不在改写过程中发起新的联网搜索；超大文件不静默截断后覆盖，而是提示用户选择章节改写。
+
+### 2.2 范围、模式和提交策略
+
+| 入口 | 文本范围 | 管线模式 | 提交策略 | 展示位置 |
+| --- | --- | --- | --- | --- |
+| 编辑器气泡菜单 | 当前选区 | `selection` | `preview_only` | 现有改写预览弹窗 |
+| 编辑器段落菜单 | 当前段落 | `paragraph` | `preview_only` | 现有改写预览弹窗 |
+| 深度研究“改写第一段/章节” | 被解析出的报告片段 | `report_section` | `manual_apply` | 普通消息列表候选稿 + 确认卡 |
+| 文件右上角“AI 全文改写” | 当前完整 Markdown | `document` | `auto_commit_after_validation` | 普通消息列表步骤条 + 右侧沙箱 |
+
+统一内核中的枚举：
+
+~~~python
+class RewriteMode(str, Enum):
+    SELECTION = "selection"
+    PARAGRAPH = "paragraph"
+    REPORT_SECTION = "report_section"
+    DOCUMENT = "document"
+
+class CommitPolicy(str, Enum):
+    PREVIEW_ONLY = "preview_only"
+    MANUAL_APPLY = "manual_apply"
+    AUTO_COMMIT_AFTER_VALIDATION = "auto_commit_after_validation"
+~~~
+
+这三类策略必须严格区分：
+
+- `preview_only`：只生成候选，前端编辑器确认后才改本地 TipTap 文档；不写真实沙箱文件。
+- `manual_apply`：后端保留基准哈希和候选片段，用户点确认后才将该片段应用进研究报告。
+- `auto_commit_after_validation`：全文生成完成并校验通过后，后端进行一次带哈希校验的原子覆盖；同时保存可撤销版本。
+
+### 2.3 局部编辑器：保持当前体验
+
+现有文件：
+
+- `frontend-web/src/open-canvas/components/artifact/MarkdownAiEditor.tsx`
+- `frontend-web/src/open-canvas/hooks/useWritingRewrite.ts`
+- `frontend-web/src/open-canvas/api/rewrite.ts`
+- `offline-backend-20260512/backend/app/gateway/routers/writing.py`
+
+局部改写仍然是：
+
+1. 选中文字或打开段落菜单；
+2. 选择润色、扩写、缩写、改写等动作；
+3. 在现有弹窗中流式出现候选；
+4. 用户手动选择替换、插入、重试或继续追问。
+
+不要让局部改写每次都往普通消息列表插完整步骤条，否则频繁编辑会淹没聊天历史。它只共享底层管线，不共享全文改写的消息展示方式。
+
+需要补充本地版本保护：发起请求时保存当前完整编辑器文本哈希、选区 `from/to` 和选区文本；用户点击“替换原文”前再次检查该范围仍匹配。若用户已修改原文，提示“原文已变化，请重新生成候选稿”，禁止将过期候选替换到错误位置。
+
+### 2.4 右上角“AI 全文改写”
+
+宿主文件：
+
+- `frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx`
+
+新增独立图标按钮，位置在右上角文件操作区，靠近保存、复制、下载一类操作。它**不能**替代页面中间当前 Sparkles 编辑模式：
+
+| 控件 | 职责 |
+| --- | --- |
+| 中部 Sparkles/编辑模式 | 打开 `MarkdownAiEditor`，处理选区和段落 |
+| 新增右上角 AI 全文改写 | 对整个 Markdown 发起后台全文重写任务 |
+
+建议显示条件：
+
+~~~ts
+const canUseFullDocumentRewrite =
+  isMarkdownFile &&
+  canEditArtifact &&
+  !isSkillFile &&
+  !isMock &&
+  !useWriteFileStreaming &&
+  !hasLocalEdits;
+~~~
+
+若 `hasLocalEdits` 为真，按钮置灰并提示“请先保存当前修改后再进行全文改写”。后端全文任务从真实文件读取快照，不能在用户本地还有未保存修改时读取旧版本并最终覆盖新修改。
+
+用户体验：
+
+1. 点击按钮，打开简洁配置弹窗。
+2. 弹窗显示文件名、原文字数；用户填写改写要求、选择模型、选择风格。
+3. 点击开始，左侧普通消息列表创建一组步骤条。
+4. 右侧沙箱自动切到源码视图，先显示“正在准备临时草稿，原文件尚未修改”。
+5. 新 Markdown 从空临时草稿开始逐 token 写入右侧代码区域。
+6. 校验通过后，后端原子替换真实内容；前端再同步真实 Artifact 缓存。
+7. 左侧保留最终对比总结、查看 diff 按钮和撤销按钮。
+
+任务进行中，同一个文件的保存、直接编辑、局部编辑和再次全文改写必须禁用；其他文件不受影响。
+
+### 2.5 深度研究报告的约束
+
+普通 Markdown 和深度研究报告使用同一管线，但不能使用同一上下文策略：
+
+| 能力 | 普通沙箱 Markdown | 深度研究 report.md |
+| --- | --- | --- |
+| 输入上下文 | 原文 + 用户指令 | 原文 + 当前会话已选资料 |
+| 联网 | 不联网 | 不联网 |
+| 事实约束 | 不新增无依据事实 | 只能引用已选资料，禁止编造 |
+| 引用校验 | 可选 | 必须校验来源 ID 白名单 |
+| 最终存储 | Artifact 文件 | 研究 session 的 `report_markdown` |
+| 局部改写 | 编辑器确认 | 现有确认卡片 |
+
+深度研究右侧的 `report.md` 是由 `ResearchSandboxPanel.tsx` 以虚拟 `write_file` 方式展示的；它不能当作普通磁盘 Artifact 直接写入。全文任务必须通过研究 session 更新 `report_markdown`，并使 `report_html` 缓存失效。
+
+## 3. 总体架构
+
+~~~mermaid
+flowchart LR
+  A["MarkdownAiEditor<br/>选区 / 段落"] --> P
+  B["ArtifactFileDetail<br/>AI 全文改写"] --> P
+  C["DeepResearch<br/>局部 / 全文"] --> P
+
+  P["Document Rewrite Pipeline<br/>冻结版本 → 构造上下文 → 流式生成<br/>校验 → 差异总结 → 按策略提交"]
+
+  P --> I["InlineDocumentSource"]
+  P --> F["ArtifactDocumentSource"]
+  P --> R["DeepResearchReportSource"]
+
+  P --> E["可恢复 SSE 事件 / Job"]
+  E --> L["普通 MessageList"]
+  E --> S["右侧沙箱临时草稿"]
+  P --> V["内容哈希、版本快照、原子提交"]
+~~~
+
+设计原则：
+
+1. 纯执行内核不依赖 FastAPI、路由、用户身份或操作系统路径。
+2. 鉴权、线程路径解析、研究 session 获取只在 `app` 层的来源适配器中完成。
+3. 完整文档任务使用持久化后台 Job；局部弹窗可维持单次 SSE，避免过度持久化。
+4. 全文流式过程中只写临时草稿；真实内容只在最终 compare-and-swap 成功时改变。
+
+不要直接把现有完整“AI 写作 Agent”塞进改写按钮。那个流程适合从主题写新文章，可能包含大纲、资料和章节生命周期；本需求是严格以当前文档为基准改写。第一版复用它的流式视觉表达和消息列表能力，但使用专门的文档改写执行内核。
+
+## 4. 后端模块设计
+
+### 4.1 目录与职责
+
+建议新增：
+
+~~~text
+offline-backend-20260512/backend/
+├─ packages/harness/deerflow/
+│  ├─ document_rewrite/
+│  │  ├─ __init__.py
+│  │  ├─ models.py                 # 请求、事件、校验、差异领域模型
+│  │  ├─ ports.py                  # Source / Model / Store 协议
+│  │  ├─ pipeline.py               # 统一编排，不导入 app.*
+│  │  ├─ prompt_builder.py          # 普通与深度研究提示词
+│  │  ├─ validation.py              # Markdown / 引用 / 截断检查
+│  │  └─ diff_summary.py            # 字数、标题、块、引用差异
+│  └─ persistence/
+│     └─ document_rewrites/
+│        ├─ base.py
+│        ├─ model.py
+│        └─ sql.py
+├─ app/gateway/
+│  ├─ routers/document_rewrites.py
+│  ├─ document_rewrite_sources.py
+│  └─ document_rewrite_executor.py
+└─ packages/harness/deerflow/persistence/migrations/versions/
+   └─ <next_revision>_document_rewrites.py
+~~~
+
+`packages/harness/deerflow/document_rewrite` 不能导入 `app.*`，以符合项目 harness→app import firewall。`app/gateway/document_rewrite_sources.py` 负责把已鉴权的 Artifact/研究会话包装成内核端口。
+
+### 4.2 来源端口
+
+~~~python
+class DocumentSource(Protocol):
+    async def read_snapshot(self) -> DocumentSnapshot: ...
+    async def read_current_hash(self) -> str: ...
+    async def commit_if_unchanged(
+        self,
+        *,
+        expected_hash: str,
+        content: str,
+        metadata: CommitMetadata,
+    ) -> CommitResult: ...
+    async def restore_if_unchanged(
+        self,
+        *,
+        expected_hash: str,
+        content: str,
+    ) -> CommitResult: ...
+~~~
+
+三种实现：
+
+| 适配器 | 使用场景 | 读取方式 | 提交方式 |
+| --- | --- | --- | --- |
+| `InlineDocumentSource` | 选区/段落候选 | 前端编辑器快照 | 不提交 |
+| `ArtifactDocumentSource` | 普通 Markdown | 复用 Artifact 权限与虚拟路径解析 | 同目录临时文件 + `os.replace` |
+| `DeepResearchReportSource` | 研究报告 | session `report_markdown` + 已选来源 | 数据库哈希条件更新 |
+
+`ArtifactDocumentSource` 必须复用 `app/gateway/routers/artifacts.py` 中已有的线程访问校验、虚拟路径解析逻辑，绝不允许请求体传入任意本机绝对路径。
+
+### 4.3 持久化 Job、事件和版本
+
+全文改写使用持久化 Job，参考 `app/gateway/deep_research_job_executor.py` 的后台任务、租约、取消监听和事件重放模式。
+
+#### document_rewrite_jobs
+
+| 字段 | 作用 |
+| --- | --- |
+| `id` | `drw_xxx` Job ID |
+| `user_id` | 发起人 |
+| `source_kind` | `artifact` / `deep_research_report` |
+| `thread_id`、`artifact_path` | 普通文件来源 |
+| `research_session_id` | 研究报告来源 |
+| `presentation_thread_id` | 普通消息列表归属 |
+| `mode`、`commit_policy` | 范围和提交语义 |
+| `instruction`、`style`、`model_name` | 用户配置 |
+| `base_sha256` | 原文冻结哈希 |
+| `draft_content`、`draft_sha256` | 临时流式草稿 |
+| `status`、`stage` | 生命周期 |
+| `validation_json`、`diff_summary_json` | 可展示结果 |
+| `committed_sha256` | 成功提交后的哈希 |
+| `error_message`、时间字段 | 错误、审计、取消 |
+
+#### document_rewrite_events
+
+至少包含 `job_id`、`seq`、`event_type`、`stage`、`payload_json`、`created_at`。`seq` 用于断线重连时通过 `after_seq` 重放。
+
+不必将每个 token 单独入库：每 250ms 或每积累 4KB 持久化一次 `draft_content`；状态转换、警告、完成、冲突、取消必须立即写事件。重连时先发送最新草稿快照，再发送快照序号后的增量事件。
+
+#### document_rewrite_versions
+
+保存真实全文覆盖前的原文版本，字段包含 `job_id`、`source_identity`、`version_no`、`content`、`sha256`、`reason`、`created_at`。初版每个文档保留最近 20 个版本即可。
+
+索引要求：
+
+- `(user_id, presentation_thread_id, created_at DESC)`：恢复历史消息。
+- 真实来源标识 + 活跃状态：防止同一文档并行两个全文改写。
+
+### 4.4 Job 状态机
+
+~~~mermaid
+stateDiagram-v2
+  [*] --> queued
+  queued --> snapshotting
+  snapshotting --> generating
+  generating --> validating
+  validating --> comparing
+  comparing --> committing
+  committing --> completed
+  completed --> reverted
+
+  queued --> cancelled
+  generating --> cancelled
+  snapshotting --> failed
+  generating --> failed
+  validating --> failed
+  committing --> conflict
+  committing --> failed
+~~~
+
+状态约束：
+
+- 同一真实文档只允许一个活跃 Job。
+- 生成期间取消、异常、断线，真实文档绝不能变化。
+- 提交前重新读取当前哈希；与 `base_sha256` 不一致时进入 `conflict`，草稿保留但不覆盖。
+
+### 4.5 API 与 SSE 契约
+
+创建全文任务：
+
+~~~http
+POST /api/document-rewrites
+Content-Type: application/json
+~~~
+
+普通 Artifact 请求：
+
+~~~json
+{
+  "source": {
+    "kind": "artifact",
+    "thread_id": "thread_xxx",
+    "path": "/mnt/user-data/outputs/report.md"
+  },
+  "presentation_thread_id": "thread_xxx",
+  "mode": "document",
+  "instruction": "统一为正式行业分析语气，减少重复，不新增外部事实",
+  "style": "formal_analysis",
+  "model_name": "system_default"
+}
+~~~
+
+深度研究请求：
+
+~~~json
+{
+  "source": {
+    "kind": "deep_research_report",
+    "session_id": "drs_xxx"
+  },
+  "presentation_thread_id": "collector_thread_xxx",
+  "mode": "document",
+  "instruction": "重新组织全文逻辑，保留全部可用引用",
+  "style": "formal_analysis",
+  "model_name": "system_default"
+}
+~~~
+
+其他接口：
+
+~~~text
+GET  /api/document-rewrites/{job_id}
+GET  /api/document-rewrites/{job_id}/stream?after_seq=42
+POST /api/document-rewrites/{job_id}/cancel
+POST /api/document-rewrites/{job_id}/undo
+GET  /api/document-rewrites?presentation_thread_id={thread_id}
+~~~
+
+SSE 事件：
+
+| 事件 | 关键数据 | 前端动作 |
+| --- | --- | --- |
+| `job_started` | 文件名、模式 | 建立步骤条 |
+| `snapshot_fixed` | 原文字数、哈希 | 完成“固定原文版本” |
+| `requirements_resolved` | 模型、风格、要求 | 完成“理解改写要求” |
+| `rewrite_delta` | `delta`、累计字符数 | 追加右侧临时草稿 |
+| `validation_started` | 校验项 | 进入校验步骤 |
+| `validation_completed` | passed、warnings | 显示校验结果 |
+| `comparison_ready` | `DiffSummary` | 渲染总结数据 |
+| `commit_started` | 无 | 显示安全替换中 |
+| `committed` | 最终哈希、版本 ID | 刷新真实文件缓存 |
+| `completed` | 完整结果 | 固化历史步骤条 |
+| `conflict` / `error` / `cancelled` | 原因 | 恢复原文显示，不保存草稿 |
+
+局部改写兼容方案：
+
+- `POST /api/writing/rewrite` 的请求和 SSE 格式先不变。
+- `writing.py` 内部逐步把 prompt、模型流、基础 Markdown 校验下沉给统一管线的 `preview_only` 分支。
+- 深度研究 `/sessions/{id}/rewrite/stream` 和确认候选接口也先保持 URL、前端行为不变，再内部复用 `manual_apply` 分支。
+
+这样可以先交付全文改写，不会一次性破坏已有编辑器和深度研究流程。
+
+### 4.6 模型、提示词与校验
+
+管线只依赖一个流式模型端口：
+
+~~~python
+class StreamingRewriteModel(Protocol):
+    async def stream_text(
+        self,
+        *,
+        messages: list[BaseMessage],
+        model_name: str | None,
+    ) -> AsyncIterator[TextChunk]: ...
+~~~
+
+第一版可以有两个 adapter：
+
+- 普通文档复用 `writing.py` 的 chat model `astream`；
+- 深度研究复用 `deep_research.py` 使用的 `DeerFlowCompletionBackend.stream_complete`。
+
+先统一编排，不强制立即统一所有模型配置实现。
+
+普通 Markdown 系统约束：
+
+~~~text
+仅根据原文与用户要求改写，不联网，不补充未给出的事实。
+保留有效链接、代码块、表格、标题语义和用户明确要求保留的内容。
+只输出完整 Markdown 正文；不得输出解释、前缀或“改写如下”。
+~~~
+
+深度研究额外约束：
+
+~~~text
+不得联网。事实、数字、结论和引用只能来自当前 session 已选资料。
+只允许使用给出的 source_id；资料不足时保持谨慎表述，禁止自行补全。
+~~~
+
+校验规则：
+
+| 类别 | 硬失败 | 告警但允许完成 |
+| --- | --- | --- |
+| 正文 | 空文档、仅空白、无可见内容 | 改写后与原文完全一致 |
+| Markdown | 未闭合围栏、明确截断 | 标题层级跳级、章节数明显减少 |
+| 深度研究来源 | 未选来源 ID、非法引用 | 引用数量下降、可能需核验的数字断言 |
+
+## 5. 安全提交、对比与撤销
+
+### 5.1 临时草稿不等于真实文件
+
+用户视觉上看到“先清空再逐 token 写入”，但真实文件的处理必须是：
+
+1. 读取原文并保存内容哈希、版本快照。
+2. 右侧只展示内存/Job 中的 `draft_content`。
+3. 生成完成后做校验和 diff。
+4. 提交前再次读取真实来源，并比较 `SHA-256`。
+5. 哈希一致才原子替换；否则进入冲突，不覆盖。
+
+普通 Artifact 使用同目录临时文件、刷盘和 `os.replace`；深度研究通过数据库事务内的“旧哈希条件更新”提交。任何失败、取消或断流都保留真实原文。
+
+### 5.2 撤销
+
+撤销流程：
+
+1. 读取该 Job 的 `before_full_rewrite` 快照。
+2. 确认当前真实内容哈希仍等于该 Job 的 `committed_sha256`。
+3. 若用户在改写后又手工编辑，返回冲突，不盲目覆盖。
+4. 先保存当前内容为 `before_undo` 版本。
+5. 原子恢复旧版本，Job 状态改为 `reverted`，消息列表卡片同步显示“已撤销”。
+
+### 5.3 结构化 DiffSummary
+
+后端产出结构化差异，前端仅渲染，避免生成空泛结论：
+
+~~~ts
+type DiffSummary = {
+  sourceDisplayName: string;
+  instruction: string;
+  modelName: string;
+  originalCharCount: number;
+  rewrittenCharCount: number;
+  charChangeRatio: number;
+  changedBlockCount: number;
+  headings: {
+    added: string[];
+    removed: string[];
+    reordered: string[];
+    levelWarnings: string[];
+  };
+  citations?: {
+    beforeCount: number;
+    afterCount: number;
+    retainedCount: number;
+    removedIds: string[];
+    invalidIds: string[];
+  };
+  requestedOptimizations: string[];
+  validationWarnings: string[];
+};
+~~~
+
+推荐总结展示：
+
+~~~text
+已完成《新能源汽车市场分析报告》的整体改写。
+
+- 改写范围：全文；要求为“统一正式分析语气、减少重复”；模型：默认模型。
+- 数量变化：原文 8,260 字，改写后 8,110 字，减少 1.8%；调整 14 个内容块。
+- 结构变化：标题层级保持不变；未新增或删除一级标题。
+- 已执行的优化：按要求合并重复表述、统一语气、调整段落衔接。
+- 保留情况：保留 35 条已选来源引用，未新增外部来源。
+- 风险提示：无。
+
+[查看前后对比] [撤销到改写前版本]
+~~~
+
+“已执行的优化”仅来自用户要求和可计算的结构差异；不能无依据宣称“文章更专业、更严谨”。
+
+## 6. 前端实现设计
+
+### 6.1 新增模块
+
+~~~text
+frontend-web/src/core/document-rewrite/
+├─ types.ts
+├─ api.ts
+├─ sse.ts
+├─ use-document-rewrite-job.ts
+├─ document-rewrite-provider.tsx
+└─ document-rewrite-presentation.ts
+
+frontend-web/src/components/workspace/document-rewrite/
+├─ DocumentRewriteDialog.tsx
+├─ DocumentRewriteProgressStep.tsx
+├─ DocumentRewriteSummaryCard.tsx
+└─ DocumentDiffDialog.tsx
+~~~
+
+职责：
+
+| 模块 | 职责 |
+| --- | --- |
+| `api.ts` | 创建、查询、取消、撤销 Job |
+| `sse.ts` | SSE 解析、`after_seq` 重连 |
+| `use-document-rewrite-job.ts` | Job 状态、草稿、rAF 合并 token |
+| Provider | 同时向文件面板与消息列表提供同一任务状态 |
+| `DocumentRewriteDialog` | 改写要求、模型、风格配置 |
+| ProgressStep | 普通消息列表内的五步步骤条 |
+| SummaryCard | 结构化总结、diff、撤销动作 |
+| DiffDialog | 原文与改写后双栏/行级对比 |
+
+模型选择使用项目已有的 `tdesign-react` 选择组件，放在全文改写配置弹窗中；局部编辑器保留当前模型传递方式，后续再统一选择器。
+
+### 6.2 流式平滑：每帧合并 delta
+
+不能因为 SSE 是 token 流就每 token 调一次 `setState`。应当网络层完整读取、渲染层按动画帧合并：
+
+~~~ts
+const pendingDeltaRef = useRef("");
+const frameRef = useRef<number | null>(null);
+
+function onRewriteDelta(delta: string) {
+  pendingDeltaRef.current += delta;
+  if (frameRef.current !== null) return;
+
+  frameRef.current = requestAnimationFrame(() => {
+    const pending = pendingDeltaRef.current;
+    pendingDeltaRef.current = "";
+    frameRef.current = null;
+    setDraftContent((previous) => previous + pending);
+  });
+}
+~~~
+
+完成、失败、取消前必须 flush 最后一段缓存。右侧代码编辑器只消费 `draftContent`；真实 Artifact 查询缓存直到 `committed` 事件才更新。
+
+### 6.3 ArtifactFileDetail 改造
+
+在 `artifact-file-detail.tsx` 增加：
+
+~~~ts
+type DocumentRewriteTarget =
+  | {
+      kind: "artifact";
+      threadId: string;
+      path: string;
+      presentationThreadId: string;
+    }
+  | {
+      kind: "deep_research_report";
+      sessionId: string;
+      presentationThreadId: string;
+    };
+~~~
+
+改造步骤：
+
+1. 加入右上角全文改写图标按钮和 `DocumentRewriteDialog`。
+2. 有活跃任务时强制 `viewMode = "code"`。
+3. 内容优先级为：`activeRewrite.draftContent ?? draftContent ?? artifactContent`。
+4. 活跃任务中代码只读，禁用保存、局部编辑和重复全文改写。
+5. 收到 `committed` 后用现有 `useUpdateArtifactContent` 或等价 Query cache 更新，使真实文件立即同步。
+6. 收到 `conflict/error/cancelled` 时废弃临时草稿显示，回到真实文件内容。
+
+### 6.4 ResearchSandboxPanel 接入
+
+相关文件：
+
+- `frontend-web/src/pages/deep-research/ResearchSandboxPanel.tsx`
+- `frontend-web/src/pages/deep-research/useReportSandbox.ts`
+- `frontend-web/src/pages/deep-research/DeepResearchWorkbench.tsx`
+
+改造：
+
+1. `ResearchSandboxPanel` 为虚拟 `report.md` 传入 `kind: "deep_research_report"` target。
+2. `useReportSandbox` 接受 `externalDraftOverride`：
+
+~~~ts
+const visibleReport = activeDocumentRewrite?.isActive
+  ? activeDocumentRewrite.draftContent
+  : reportMarkdown;
+~~~
+
+3. 流式期间只显示临时草稿，不提前写 session 报告。
+4. `committed` 后刷新/替换 session 的 `report_markdown`；失败后恢复旧报告。
+5. 当前“改写第一段 → 候选消息 → 确认应用”逻辑继续保留，不因全文改写而改变。
+
+### 6.5 普通消息列表接入
+
+复用：
+
+- `frontend-web/src/components/workspace/messages/message-list.tsx`
+- `frontend-web/src/components/workspace/messages/MessageGroup.tsx`
+- `DeepResearchWorkbench.tsx` 中的虚拟消息注入模式。
+
+`DocumentRewritePresentationProvider` 按 `presentation_thread_id` 读取 Job 历史并投影为：
+
+1. 用户消息：“AI 全文改写《xxx.md》”；
+2. AI 工具调用：`document_rewrite_progress`；
+3. AI 富消息：`document_rewrite_summary`。
+
+`MessageGroup.tsx` 增加 `document_rewrite_progress` 分支，渲染 `DocumentRewriteProgressStep`。最终摘要渲染 `DocumentRewriteSummaryCard`，其内含“查看前后对比”和“撤销”。
+
+全文步骤固定为：
+
+| 步骤 | 展示内容 |
+| --- | --- |
+| 固定原文版本 | 文件名、原文字数、快照已保存 |
+| 理解改写要求 | 改写目标、模型、风格 |
+| 流式重写 Markdown | 正在写入右侧 xxx.md、累计字数 |
+| 校验文档 | 非空、标题、围栏、截断；报告还含来源检查 |
+| 对比原文并生成说明 | 差异、风险、撤销入口 |
+
+步骤条必须在完成后保留，不能因为流结束被隐藏。
+
+## 7. 核心执行伪代码
+
+~~~python
+async def run_document_rewrite(job_id: str) -> None:
+    job = await jobs.acquire_lease(job_id)
+    source = source_factory.create(job)  # 已完成鉴权的来源适配器
+
+    await emit("snapshotting")
+    snapshot = await source.read_snapshot()
+    base_hash = sha256(snapshot.content)
+    await jobs.freeze_snapshot(job_id, snapshot, base_hash)
+    await emit("snapshot_fixed", char_count=count_chars(snapshot.content))
+
+    messages = prompt_builder.build(
+        mode=job.mode,
+        source_kind=job.source_kind,
+        original=snapshot.content,
+        instruction=job.instruction,
+        style=job.style,
+        research_sources=snapshot.allowed_sources,
+    )
+    await emit("requirements_resolved", ...)
+
+    draft = ""
+    async for chunk in model.stream_text(messages=messages, model_name=job.model_name):
+        if await jobs.cancel_requested(job_id):
+            await jobs.mark_cancelled(job_id)
+            await emit("cancelled")
+            return
+        draft += chunk.text
+        await jobs.append_draft_periodically(job_id, draft)
+        await emit("rewrite_delta", delta=chunk.text)
+
+    await emit("validation_started")
+    validation = validate_markdown(
+        draft,
+        source_kind=job.source_kind,
+        allowed_citations=snapshot.allowed_citation_ids,
+    )
+    if validation.has_fatal_error:
+        await jobs.mark_failed(job_id, validation.message)
+        await emit("error", ...)
+        return
+    await emit("validation_completed", ...)
+
+    diff = build_diff_summary(snapshot.content, draft, validation)
+    await jobs.save_diff(job_id, diff)
+    await emit("comparison_ready", diff)
+
+    if job.commit_policy != AUTO_COMMIT_AFTER_VALIDATION:
+        await jobs.mark_candidate_ready(job_id)
+        return
+
+    await emit("commit_started")
+    await versions.save_before_rewrite(job, snapshot)
+    result = await source.commit_if_unchanged(
+        expected_hash=base_hash,
+        content=draft,
+        metadata=CommitMetadata(job_id=job_id),
+    )
+    if not result.ok:
+        await jobs.mark_conflict(job_id)
+        await emit("conflict", ...)
+        return
+
+    await jobs.mark_completed(job_id, result.sha256)
+    await emit("committed", ...)
+    await emit("completed", diff)
+~~~
+
+## 8. 实施顺序
+
+### 阶段 A：后端内核与安全基础
+
+1. 新增领域模型、来源端口、校验、确定性 diff。
+2. 新增 Job、事件、版本数据表与 migration。
+3. 参考深度研究 executor 完成后台任务、取消、SSE 重放。
+4. 实现普通 Artifact 读取、哈希比较、原子提交和撤销 API。
+5. 编写接口测试。
+
+验收：可以通过 API 对普通 Markdown 创建全文任务；取消、失败、冲突均不改原文件；成功后可撤销。
+
+### 阶段 B：普通沙箱全文 UI
+
+1. 新增 `core/document-rewrite` 前端状态、SSE、rAF hook。
+2. 改 `ArtifactFileDetail`：右上角按钮、配置弹窗、临时草稿、禁用态。
+3. 接入普通 `MessageList` 的步骤条、总结卡、diff 和撤销。
+4. 支持刷新后恢复 Job 状态与已完成历史。
+
+验收：右侧可平滑逐 token 写入；完成后替换真实 Markdown；左侧步骤和总结保留；撤销成功恢复。
+
+### 阶段 C：深度研究接入
+
+1. 实现 `DeepResearchReportSource`。
+2. 由 `ResearchSandboxPanel` 传入报告 target。
+3. `useReportSandbox` 支持外部临时草稿。
+4. 对深度研究添加引用白名单校验。
+5. 保持现有报告局部候选确认卡不变，再逐步下沉公共 prompt/校验逻辑。
+
+验收：报告全文改写不触发联网搜索，不允许新来源；局部报告改写依然先确认再应用。
+
+### 阶段 D：局部改写内核迁移
+
+1. 保持 `/api/writing/rewrite` 契约不变。
+2. 将 `writing.py` 转为 `InlineDocumentSource + preview_only` 的兼容 facade。
+3. 给 `useWritingRewrite` 增加原文快照失效检查。
+4. 回归替换、插入、重试、继续追问。
+
+## 9. 测试与验收
+
+建议新增后端测试：
+
+~~~text
+offline-backend-20260512/backend/tests/
+├─ test_document_rewrite_pipeline.py
+├─ test_document_rewrite_api.py
+├─ test_document_rewrite_versions.py
+└─ test_document_rewrite_deep_research.py
+~~~
+
+必须覆盖：
+
+- Job 状态、SSE 顺序和断线恢复；
+- 空输出、围栏不闭合、截断、非法深度研究引用；
+- 同一文件并发任务；
+- 提交前手工修改导致的冲突；
+- 取消/异常不改真实文件；
+- 正常撤销、撤销前手工编辑导致的冲突；
+- 旧 `/api/writing/rewrite`、深度研究 `/rewrite/stream` 兼容回归。
+
+前端必须覆盖：
+
+- 多个 delta 在一帧合并，最终内容不丢失；
+- `committed` 前 Artifact 缓存不被临时草稿污染；
+- 失败/取消/冲突后右侧恢复原文；
+- 活跃任务禁用同文件编辑、保存、重复改写；
+- 刷新后历史步骤条与总结仍存在；
+- 深度研究虚拟 `report.md` 可用全文改写；
+- 局部编辑器原文变化后不能应用过期候选。
+
+执行基线：
+
+~~~powershell
+cd offline-backend-20260512/backend
+$env:PYTHONPATH = "."
+uv run --no-sync pytest tests/test_document_rewrite_pipeline.py -v
+uv run --no-sync pytest tests/test_document_rewrite_api.py -v
+uv run --no-sync ruff check app packages/harness
+
+cd ../../frontend-web
+pnpm typecheck
+pnpm build
+~~~
+
+## 10. 风险控制
+
+| 风险 | 控制措施 |
+| --- | --- |
+| 用户误以为真实文件已经清空 | 明确显示“临时草稿，原文件尚未修改” |
+| 流式显示仍然卡顿 | 网络完整读取 + `requestAnimationFrame` 合并渲染 |
+| 改写中用户手动编辑 | `SHA-256` compare-and-swap，冲突即拒绝覆盖 |
+| 输出 Markdown 不完整 | 非空、围栏、截断和标题检查 |
+| 深度研究幻觉 | 来源白名单、禁止联网、引用 ID 校验 |
+| 文档过大 | 第一版拒绝并提示按章节改写，不隐式截断 |
+| 局部编辑污染聊天历史 | 局部只在编辑器弹窗展示，不创建完整步骤条 |
+| 历史记录只存在浏览器内存 | 全文 Job/Event/Diff 持久化，按展示线程恢复 |
+
+## 11. 复用点清单
+
+| 现有实现 | 在新方案中的用途 |
+| --- | --- |
+| `MarkdownAiEditor.tsx` | 保留局部编辑菜单、预览弹窗、确认动作 |
+| `useWritingRewrite.ts` | 保留局部流控制，增加快照失效保护 |
+| `open-canvas/api/rewrite.ts` | 保持兼容，逐步接入统一内核 |
+| `routers/writing.py` | 复用当前模型流式读取，抽取 prompt/流逻辑 |
+| `routers/deep_research.py` | 复用报告来源、哈希候选、来源约束 |
+| `deep_research_job_executor.py` | 复用后台 Job、取消、事件重放模式 |
+| `artifact-file-detail.tsx` | 复用沙箱文件操作、代码/预览、缓存同步 |
+| `useUpdateArtifactContent` | 完成后更新普通 Artifact 缓存 |
+| `ResearchSandboxPanel.tsx` | 复用研究报告的右侧沙箱宿主 |
+| `useReportSandbox.ts` | 加入临时草稿覆盖显示 |
+| `MessageList.tsx / MessageGroup.tsx` | 复用普通消息步骤条、总结消息、文件卡片能力 |
+| `DeepResearchWorkbench.tsx` | 复用向普通消息列表投影过程事件的模式 |
+
+## 12. 完成定义
+
+完成后应满足：
+
+1. 局部编辑依旧是编辑器弹窗中的人工确认操作。
+2. 全文改写在普通消息列表展示完整且不隐藏的步骤条。
+3. 右侧沙箱可平滑地逐 token 展示临时 Markdown 草稿。
+4. 任何中断、取消、校验失败和冲突都不损坏真实文件。
+5. 完成后用户可以看到量化差异、结构变化、来源保留和风险提示。
+6. 普通 Markdown 与深度研究报告都可全文改写，但研究报告绝不绕过已选来源约束。
+7. 每一次真实全文覆盖都有版本快照，并且能够安全撤销。
+

frontend-web/public/runtime-config.js

@@ -99,7 +99,7 @@ window.__CM_RUNTIME_CONFIG__ = {
   VITE_AIPI_KNOWES_URL: "http://ch1.b.uat.4.cn/knowes",
 
   // MaxKey 鉴权地址：onlineTicket 换 token 使用。
-  VITE_AUTH_BASE_URL: "https://auth.y.sit.4.cn",
+  VITE_AUTH_BASE_URL: "https://auth.y.uat.4.cn",
 
   // PG 中任务 iframe 地址。
   VITE_AIPI_PGLINKTO_URL: "https://pg.b.uat.4.cn",
@@ -132,4 +132,18 @@ window.__CM_RUNTIME_CONFIG__ = {
 
   // GitHub OAuth Token；不使用 GitHub 相关能力时留空。
   VITE_GITHUB_OAUTH_TOKEN: "",
+
+  // 是否在智能体管理页显示「舆情分析」类型："true" 显示，"false" 隐藏。
+  // 关闭后，该智能体的专用对话地址也会自动跳回智能体管理页。
+  VITE_SENTIMENT_AGENT_VISIBLE: "true",
+
+  // 舆情分析智能体：外部流式问答接口地址（POST，SSE 流式返回）。
+  // 留空时该智能体对话页会提示未配置。
+  VITE_SENTIMENT_AGENT_API_URL: "https://gw.y.sit.4.cn/alg/stream/report-agent",
+
+  // 舆情分析智能体：请求头 Authorization Basic Auth 用户名。
+  VITE_SENTIMENT_AGENT_AUTH_USERNAME: "1054841959975223296",
+
+  // 舆情分析智能体：请求头 Authorization Basic Auth 密码。
+  VITE_SENTIMENT_AGENT_AUTH_PASSWORD: "LzqqMTUxMTIwMjQxNjQ2MjY5MDUduC",
 };

frontend-web/src/assets/position-roundtable/add-task.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><defs><style>.a{fill:#fff;opacity:0;}.b{fill:none;stroke:#fff;stroke-linecap:round;stroke-linejoin:round;}</style></defs><rect class="a" width="16" height="16"/><path class="b" d="M24.036,10l-.012,9.333" transform="translate(-16.016 -6.667)"/><path class="b" d="M10,24h9.333" transform="translate(-6.667 -16)"/></svg>

frontend-web/src/assets/position-roundtable/agent-config-logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="36" height="36" viewBox="0 0 36 36"><defs><style>.a,.d{fill:#fff;}.a{opacity:0;}.b{fill:#da2331;}.c{fill:#0a54cf;}.e{fill:#1677ff;}.f{fill:#1e2433;}.g{fill:#10d6ff;}.h{fill:#ff8181;}.i{fill:none;stroke:#10d6ff;stroke-linecap:round;stroke-linejoin:round;}.j{filter:url(#d);}.k{filter:url(#a);}</style><filter id="a"><feOffset dx="4" input="SourceAlpha"/><feGaussianBlur stdDeviation="1" result="b"/><feFlood flood-opacity="0.161" result="c"/><feComposite operator="out" in="SourceGraphic" in2="b"/><feComposite operator="in" in="c"/><feComposite operator="in" in2="SourceGraphic"/></filter><filter id="d"><feOffset dx="-4" input="SourceAlpha"/><feGaussianBlur stdDeviation="1" result="e"/><feFlood flood-opacity="0.161" result="f"/><feComposite operator="out" in="SourceGraphic" in2="e"/><feComposite operator="in" in="f"/><feComposite operator="in" in2="SourceGraphic"/></filter></defs><g transform="translate(0 -1)"><rect class="a" width="36" height="36" transform="translate(0 1)"/><path class="b" d="M23.5,14.75a1.5,1.5,0,0,1-1.5-1.5V9.5a1.5,1.5,0,1,1,3,0v3.75A1.5,1.5,0,0,1,23.5,14.75Z" transform="translate(-5.5 -1)"/><g data-type="innerShadowGroup"><path class="c" d="M-2-2H1C3.206-2,5-.532,5,1.273V3.727C5,5.532,3.206,7,1,7H-2Z" transform="translate(28.66 19.541)"/><g class="k" transform="matrix(1, 0, 0, 1, 0, 1)"><path class="d" d="M-2-2H1C3.206-2,5-.532,5,1.273V3.727C5,5.532,3.206,7,1,7H-2Z" transform="translate(28.66 18.54)"/></g></g><g data-type="innerShadowGroup"><path class="c" d="M5-2H2C-.206-2-2-.532-2,1.273V3.727C-2,5.532-.206,7,2,7H5Z" transform="translate(4.34 19.541)"/><g class="j" transform="matrix(1, 0, 0, 1, 0, 1)"><path class="d" d="M5-2H2C-.206-2-2-.532-2,1.273V3.727C-2,5.532-.206,7,2,7H5Z" transform="translate(4.34 18.54)"/></g></g><path class="e" d="M5.5-2H16a7.508,7.508,0,0,1,7.5,7.5V13A7.508,7.508,0,0,1,16,20.5H5.5A7.508,7.508,0,0,1-2,13V5.5A7.508,7.508,0,0,1,5.5-2Z" transform="translate(7.25 13.5)"/><path class="f" d="M5.25,0h9A5.25,5.25,0,0,1,19.5,5.25V7.5a5.25,5.25,0,0,1-5.25,5.25h-9A5.25,5.25,0,0,1,0,7.5V5.25A5.25,5.25,0,0,1,5.25,0Z" transform="translate(8.25 15.25)"/><circle class="g" cx="1.5" cy="1.5" r="1.5" transform="translate(21 19)"/><circle class="g" cx="1.5" cy="1.5" r="1.5" transform="translate(12 19)"/><path class="d" d="M24,10v3.75" transform="translate(-6 -1.5)"/><circle class="h" cx="3" cy="3" r="3" transform="translate(15 4)"/><path class="i" d="M44,28.667a3.367,3.367,0,0,0,1.922.412,2.841,2.841,0,0,0,1.828-.412" transform="translate(-27.875 -5.017)"/></g></svg>

frontend-web/src/assets/position-roundtable/ask-question.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96"><defs><style>.a{fill:#fff;opacity:0;}.b,.c{fill:none;stroke:#006efe;stroke-width:6px;}.b{stroke-linecap:round;stroke-linejoin:round;}</style></defs><g transform="translate(0 1)"><rect class="a" width="96" height="96" transform="translate(0 -1)"/><path class="b" d="M47,67H38L18,77V67H4V7H84V29" transform="translate(4 8)"/><circle class="c" cx="12" cy="12" r="12" transform="translate(56 45)"/><path class="b" d="M39,32l10,8" transform="translate(39 33)"/><path class="b" d="M12,15H24" transform="translate(12 16)"/><path class="b" d="M12,21H36" transform="translate(12 22)"/></g></svg>

frontend-web/src/assets/position-roundtable/collapse-panel.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="13" height="11" viewBox="0 0 13 11"><defs><style>.a{stroke:rgba(0,0,0,0);stroke-miterlimit:10;fill:url(#a);}</style><linearGradient id="a" x1="0.277" y1="0.03" x2="0.725" y2="1.083" gradientUnits="objectBoundingBox"><stop offset="0" stop-color="#92eeff"/><stop offset="1" stop-color="#00c7ff"/></linearGradient></defs><path class="a" d="M1,10A1,1,0,1,1,1,8H6a1,1,0,0,1,0,2Zm9.8-.482L7.848,7.361A.445.445,0,0,1,7.661,7a.46.46,0,0,1,.187-.366L10.8,4.481a.45.45,0,0,1,.716.365V9.152a.44.44,0,0,1-.131.317.445.445,0,0,1-.322.136A.454.454,0,0,1,10.8,9.518ZM1,6A1,1,0,1,1,1,4H6A1,1,0,0,1,6,6ZM1,2A1,1,0,1,1,1,0H11a1,1,0,1,1,0,2Z" transform="translate(0.5 0.5)"/></svg>

frontend-web/src/assets/position-roundtable/double-arrow-decoration.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="13" height="11" viewBox="0 0 13 11"><defs><style>.a{fill:url(#a);}.b{fill:url(#b);}</style><linearGradient id="a" x1="0.023" x2="1" y2="1" gradientUnits="objectBoundingBox"><stop offset="0" stop-color="#92eeff" stop-opacity="0.302"/><stop offset="1" stop-color="#00c7ff" stop-opacity="0.302"/></linearGradient><linearGradient id="b" x1="0.023" x2="1" y2="1" gradientUnits="objectBoundingBox"><stop offset="0" stop-color="#92eeff"/><stop offset="1" stop-color="#00c7ff"/></linearGradient></defs><path class="a" d="M5.5,0,11,8H0Z" transform="translate(13) rotate(90)"/><path class="b" d="M5.5,0,11,8H0Z" transform="translate(8) rotate(90)"/></svg>

frontend-web/src/assets/position-roundtable/edit-task.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><defs><style>.a{fill:#fff;opacity:0;}.b,.c{fill:none;stroke:#fff;stroke-linejoin:round;}.b{stroke-linecap:round;}</style></defs><g transform="translate(-1)"><rect class="a" width="16" height="16" transform="translate(1)"/><path class="b" d="M7,42H19" transform="translate(-4 -28)"/><path class="b" d="M0,0H3" transform="translate(9.848 3.848) rotate(45)"/><path class="c" d="M11,12.907v2.427h2.439l6.894-6.9L17.9,6Z" transform="translate(-6.667 -4)"/></g></svg>

frontend-web/src/assets/position-roundtable/more-task.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><defs><style>.a{fill:#fff;opacity:0;}.b{fill:rgba(255,255,255,0.8);}</style></defs><rect class="a" width="16" height="16"/><path class="b" d="M10,1.5A1.5,1.5,0,1,1,11.5,3,1.5,1.5,0,0,1,10,1.5Zm-5,0A1.5,1.5,0,1,1,6.5,3,1.5,1.5,0,0,1,5,1.5Zm-5,0A1.5,1.5,0,1,1,1.5,3,1.5,1.5,0,0,1,0,1.5Z" transform="translate(1.498 6.5)"/></svg>

frontend-web/src/assets/position-roundtable/search-task.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><defs><style>.a{fill:#fff;opacity:0;}.b{fill:rgba(85,166,254,0.6);}</style></defs><rect class="a" width="16" height="16"/><path class="b" d="M12.715,13.421,9.588,10.294a5.841,5.841,0,1,1,.707-.707l3.128,3.128a.5.5,0,0,1-.708.706ZM1,5.833A4.833,4.833,0,1,0,5.834,1,4.838,4.838,0,0,0,1,5.833Z" transform="translate(1.334 1.216)"/></svg>

frontend-web/src/assets/position-roundtable/send-message.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><defs><style>.a{fill:#fff;}</style></defs><path class="a" d="M14.488.053.824,4.256a1.167,1.167,0,0,0-.285,2.1L4.576,8.936a1.167,1.167,0,0,0,1.382-.092L11,4.593A.292.292,0,0,1,11.408,5L7.156,10.043a1.167,1.167,0,0,0-.091,1.382l2.58,4.036a1.168,1.168,0,0,0,2.1-.286l4.2-13.663A1.167,1.167,0,0,0,14.488.053Z" transform="translate(0)"/></svg>

frontend-web/src/assets/position-roundtable/upload-file.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16.131" height="16" viewBox="0 0 16.131 16"><defs><style>.a{fill:#fff;opacity:0;}.b{fill:none;stroke:#97edff;stroke-linecap:round;stroke-linejoin:round;}</style></defs><rect class="a" width="16" height="16"/><path class="b" d="M6,30V34.12H18.361V30" transform="translate(-2.73 -19.994)"/><path class="b" d="M21.181,9.09,18.09,6,15,9.09" transform="translate(-8.64 -4.235)"/><path class="b" d="M23.992,14.241V6" transform="translate(-14.544 -4.235)"/></svg>

frontend-web/src/assets/position-roundtable/时间.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><defs><style>.a{fill:#fff;opacity:0;}.b,.c{fill:none;stroke:#346fb1;stroke-linejoin:round;}.c{stroke-linecap:round;}</style></defs><rect class="a" width="16" height="16"/><path class="b" d="M10.667,17.333A6.667,6.667,0,1,0,4,10.667,6.667,6.667,0,0,0,10.667,17.333Z" transform="translate(-2.667 -2.667)"/><path class="c" d="M24.008,12v4l2.826,2.826" transform="translate(-16.005 -8)"/></svg>

frontend-web/src/assets/position-roundtable/标签1.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="95.001" height="26" viewBox="0 0 95.001 26"><defs><style>.a{fill:rgba(212,120,0,0.5);}</style></defs><path class="a" d="M250.146,407.92h91l-11.4,18.235c-2.679,4.26-5.243,7.5-11.211,7.765H246.146v-22A4,4,0,0,1,250.146,407.92Z" transform="translate(-246.146 -407.92)"/></svg>

frontend-web/src/assets/position-roundtable/标签2.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="95.001" height="26" viewBox="0 0 95.001 26"><defs><style>.a{fill:rgba(207,19,34,0.5);}</style></defs><path class="a" d="M250.146,407.92h91l-11.4,18.235c-2.679,4.26-5.243,7.5-11.211,7.765H246.146v-22A4,4,0,0,1,250.146,407.92Z" transform="translate(-246.146 -407.92)"/></svg>

frontend-web/src/assets/position-roundtable/标签3.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="95.001" height="26" viewBox="0 0 95.001 26"><defs><style>.a{fill:rgba(29,171,123,0.5);}</style></defs><path class="a" d="M250.146,407.92h91l-11.4,18.235c-2.679,4.26-5.243,7.5-11.211,7.765H246.146v-22A4,4,0,0,1,250.146,407.92Z" transform="translate(-246.146 -407.92)"/></svg>

frontend-web/src/assets/position-roundtable/标签4.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="95.001" height="26" viewBox="0 0 95.001 26"><defs><style>.a{fill:rgba(132,85,230,0.5);}</style></defs><path class="a" d="M250.146,407.92h91l-11.4,18.235c-2.679,4.26-5.243,7.5-11.211,7.765H246.146v-22A4,4,0,0,1,250.146,407.92Z" transform="translate(-246.146 -407.92)"/></svg>

frontend-web/src/assets/position-roundtable/标签5.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="95.001" height="26" viewBox="0 0 95.001 26"><defs><style>.a{fill:rgba(201,181,0,0.5);}</style></defs><path class="a" d="M250.146,407.92h91l-11.4,18.235c-2.679,4.26-5.243,7.5-11.211,7.765H246.146v-22A4,4,0,0,1,250.146,407.92Z" transform="translate(-246.146 -407.92)"/></svg>

frontend-web/src/assets/position-roundtable/标签6.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="95.001" height="26" viewBox="0 0 95.001 26"><defs><style>.a{fill:rgba(69,195,243,0.5);}</style></defs><path class="a" d="M250.146,407.92h91l-11.4,18.235c-2.679,4.26-5.243,7.5-11.211,7.765H246.146v-22A4,4,0,0,1,250.146,407.92Z" transform="translate(-246.146 -407.92)"/></svg>

frontend-web/src/assets/position-roundtable/责任岗位.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><defs><style>.a{fill:#fff;opacity:0;}.b{fill:none;stroke:#346fb1;stroke-linecap:round;stroke-linejoin:round;}</style></defs><g transform="translate(0 -2)"><rect class="a" width="16" height="16" transform="translate(0 2)"/><path class="b" d="M17.333,8H4V18H9l1.667,1.667L12.333,18h5Z" transform="translate(-2.667 -3.667)"/><circle class="b" cx="1.667" cy="1.667" r="1.667" transform="translate(6.333 6.333)"/><path class="b" d="M21,26.667A2.848,2.848,0,0,0,18,24a2.848,2.848,0,0,0-3,2.667" transform="translate(-10 -14.333)"/></g></svg>

frontend-web/src/components/page-sdebar.css

@@ -607,6 +607,27 @@ html.lightyellow .light-topnav-item--active::after {
 }
 
 /* ── 侧边栏：二级图标卡片列（96px）+ 右侧三级列（展开时整体变宽，带过渡）──────── */
+/* Runtime themes use their configurable header gradient rather than the
+   red/blue banner artwork. Navigation copy follows an automatically chosen
+   contrasting foreground so both pale and deep brand colours remain legible. */
+html[data-custom-theme="true"] .light-topnav-item,
+html[data-custom-theme="true"] .top-submenu-item {
+    color: var(--navigation-foreground);
+}
+
+html[data-custom-theme="true"] .light-topnav-item:hover,
+html[data-custom-theme="true"] .light-topnav-item--active,
+html[data-custom-theme="true"] .light-topnav-item--active:hover,
+html[data-custom-theme="true"] .top-submenu-item:hover,
+html[data-custom-theme="true"] .top-submenu-item--active {
+    color: var(--navigation-foreground);
+    text-shadow: none;
+}
+
+html[data-custom-theme="true"] .light-topnav-item--active::after {
+    background: var(--navigation-foreground);
+}
+
 .light-sidebar {
     position: fixed;
     left: 0;

frontend-web/src/components/page-sidebar.tsx

@@ -2,6 +2,7 @@ import { useEffect, useState } from "react";
 import { useNavigate, useLocation } from "react-router-dom";
 import {
   Bell,
+  Cpu,
   ChevronLeft,
   ChevronRight,
   ChevronsUpDown,
@@ -10,6 +11,7 @@ import {
   Gauge,
   ListTree,
   MousePointerClick,
+  BriefcaseBusiness,
   Settings,
   ShieldAlert,
   ShieldCheck,
@@ -235,6 +237,14 @@ function SecondaryNavSidebar({ headerHidden }: { headerHidden: boolean }) {
                       按钮管理
                     </DropdownMenuItem>
                   )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/strategy/admin/position-roles")}
+                    >
+                      <BriefcaseBusiness className="size-4" />
+                      岗位角色配置
+                    </DropdownMenuItem>
+                  )}
                   {isAdmin && (
                     <DropdownMenuItem
                       onClick={() => navigate("/page/strategy/admin/login-whitelist")}
@@ -243,6 +253,14 @@ function SecondaryNavSidebar({ headerHidden }: { headerHidden: boolean }) {
                       白名单管理
                     </DropdownMenuItem>
                   )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/workspace/admin/models")}
+                    >
+                      <Cpu className="size-4" />
+                      模型配置
+                    </DropdownMenuItem>
+                  )}
                   {isAdmin && (
                     <DropdownMenuItem
                       onClick={() => navigate("/page/strategy/settings/model-concurrency")}
@@ -540,6 +558,18 @@ function LegacyAccordionSidebar({
                   按钮管理
                 </DropdownMenuItem>
               )}
+              {isAdmin && (
+                <DropdownMenuItem onClick={() => navigate("/page/strategy/admin/position-roles")}>
+                  <BriefcaseBusiness className="size-4" />
+                  岗位角色配置
+                </DropdownMenuItem>
+              )}
+              {isAdmin && (
+                <DropdownMenuItem onClick={() => navigate("/page/workspace/admin/models")}>
+                  <Cpu className="size-4" />
+                  模型配置
+                </DropdownMenuItem>
+              )}
               {isAdmin && (
                 <DropdownMenuItem onClick={() => navigate("/page/strategy/admin/login-whitelist")}>
                   <ShieldCheck className="size-4" />

frontend-web/src/components/wiki/WikiHeader.tsx

@@ -8,6 +8,7 @@ import {
   SlidersHorizontal,
   Upload,
 } from "lucide-react";
+import type { ReactNode } from "react";
 
 import { cn } from "@/lib/utils";
 
@@ -18,7 +19,7 @@ function HeaderButton({
   variant = "outline",
   className,
 }: {
-  icon: React.ReactNode;
+  icon: ReactNode;
   label: string;
   onClick: () => void;
   variant?: "outline" | "primary";
@@ -52,6 +53,7 @@ export function WikiHeader({
   onCreate,
   onManageFolders,
   onManageTemplates,
+  extraActions,
 }: {
   onToggleSidebar: () => void;
   onImportFile: () => void;
@@ -61,6 +63,7 @@ export function WikiHeader({
   onCreate: () => void;
   onManageFolders: () => void;
   onManageTemplates: () => void;
+  extraActions?: ReactNode;
 }) {
   return (
     <header className="flex h-14 shrink-0 items-center justify-between border-b border-slate-100 bg-white px-4 sm:px-6 dark:border-slate-800 dark:bg-slate-900">
@@ -79,6 +82,7 @@ export function WikiHeader({
       </div>
 
       <div className="flex items-center gap-2">
+        {extraActions}
         <HeaderButton
           icon={<Upload className="size-4" />}
           label="导入文件"

frontend-web/src/components/workspace/agents/agent-detail-panel.tsx

@@ -3,6 +3,7 @@
 import {
   BotIcon,
   CheckIcon,
+  DatabaseIcon,
   GlobeIcon,
   InfoIcon,
   Loader2Icon,
@@ -43,6 +44,7 @@ import {
 import { Switch } from "@/components/ui/switch";
 import { Textarea } from "@/components/ui/textarea";
 import { AgentQuestionEditor } from "@/components/workspace/agents/agent-question-editor";
+import { LlmWikiKnowledgeSelector } from "@/components/workspace/llmwiki-knowledge-selector";
 import { AgentRecentChats } from "@/components/workspace/agents/agent-recent-chats";
 import { useArtifactsOptional } from "@/components/workspace/artifacts";
 import { EnabledSkillList } from "@/components/workspace/agents/enabled-skill-list";
@@ -80,6 +82,7 @@ interface AgentDraft {
   templateName: string;
   /** 会商席位「技能识别强化」开关。 */
   seatSkillDirective: boolean;
+  knowledgeBaseIds: string[];
 }
 
 function draftFromAgent(agent: Agent): AgentDraft {
@@ -93,6 +96,7 @@ function draftFromAgent(agent: Agent): AgentDraft {
     featured: agent.featured_order != null,
     templateName: agent.template_name ?? "",
     seatSkillDirective: agent.seat_skill_directive ?? false,
+    knowledgeBaseIds: agent.llmwiki_knowledge_base_ids ?? [],
   };
 }
 
@@ -100,15 +104,17 @@ function Section({
   icon,
   title,
   extra,
+  className,
   children,
 }: {
   icon?: ReactNode;
   title: string;
   extra?: ReactNode;
+  className?: string;
   children: ReactNode;
 }) {
   return (
-    <section className="bg-card/60 rounded-xl border p-4">
+    <section className={cn("bg-card/60 rounded-xl border p-4", className)}>
       <div className="mb-3 flex items-center justify-between gap-2">
         <h4 className="text-foreground flex items-center gap-1.5 text-sm font-semibold">
           {icon}
@@ -139,6 +145,15 @@ export function AgentDetailPanel({
   defaultCollapsed,
   showRecentChats,
   compactAppearanceActions,
+  avatarSrc,
+  positionName,
+  skillsIcon,
+  skillsTitle,
+  showCommonQuestions = false,
+  panelTitle,
+  embedded,
+  hideStatusBadges = false,
+  editIcon,
 }: {
   agent: Agent | null | undefined;
   agentName: string;
@@ -150,6 +165,19 @@ export function AgentDetailPanel({
   showRecentChats?: boolean;
   /** 简洁模式下挂在右上角收起/展开按钮左侧的外观控件。 */
   compactAppearanceActions?: ReactNode;
+  avatarSrc?: string;
+  positionName?: string;
+  skillsIcon?: ReactNode;
+  skillsTitle?: string;
+  showCommonQuestions?: boolean;
+  /** Overrides the standard panel heading for an embedded consumer. */
+  panelTitle?: string;
+  /** Renders one fixed panel instead of the responsive collapsible rail. */
+  embedded?: boolean;
+  /** Keeps deployment/status badges out of an embedded product surface. */
+  hideStatusBadges?: boolean;
+  /** Optional icon used by the compact embedded edit action. */
+  editIcon?: ReactNode;
 }) {
   const router = useRouter();
   const [collapsed, setCollapsed] = useState(defaultCollapsed ?? false);
@@ -310,6 +338,11 @@ export function AgentDetailPanel({
       request.template_name = draft.templateName.trim();
     if (draft.seatSkillDirective !== (agent.seat_skill_directive ?? false))
       request.seat_skill_directive = draft.seatSkillDirective;
+    if (
+      JSON.stringify(draft.knowledgeBaseIds) !==
+      JSON.stringify(agent.llmwiki_knowledge_base_ids ?? [])
+    )
+      request.llmwiki_knowledge_base_ids = draft.knowledgeBaseIds;
     if (nextPublished !== agent.published) request.published = nextPublished;
     if (JSON.stringify(draft.skills) !== JSON.stringify(agent.skills ?? []))
       request.skills = draft.skills;
@@ -472,11 +505,25 @@ export function AgentDetailPanel({
       </div>
     ) : (
       <div className="flex items-center gap-1">
+        {embedded ? (
+          <Tooltip content="编辑智能体">
+            <Button
+              type="button"
+              size="icon-sm"
+              variant="ghost"
+              onClick={beginEdit}
+              aria-label="编辑智能体"
+            >
+              {editIcon ?? <SquarePenIcon className="size-3.5" />}
+            </Button>
+          </Tooltip>
+        ) : (
           <Button size="sm" variant="outline" onClick={beginEdit}>
             <SquarePenIcon className="size-3.5" />
             编辑
           </Button>
-        {canTogglePublish && (
+        )}
+        {!embedded && canTogglePublish && (
           <Tooltip content={agent?.published ? "下架" : "发布"}>
             <Button
               size="icon-sm"
@@ -493,6 +540,7 @@ export function AgentDetailPanel({
             </Button>
           </Tooltip>
         )}
+        {!embedded && (
           <Tooltip content="删除智能体">
             <Button
               size="icon-sm"
@@ -504,6 +552,7 @@ export function AgentDetailPanel({
               <Trash2Icon className="size-3.5" />
             </Button>
           </Tooltip>
+        )}
       </div>
     )
   ) : null;
@@ -521,7 +570,11 @@ export function AgentDetailPanel({
       <section className="bg-card/60 rounded-xl border p-4">
         <div className="flex items-start gap-3">
           <div className="agent-avatar bg-primary/10 ring-primary/15 flex size-12 shrink-0 items-center justify-center rounded-2xl ring-1">
+            {avatarSrc ? (
+              <img src={avatarSrc} alt="" aria-hidden="true" className="size-9" />
+            ) : (
               <BotIcon className="text-primary size-6" />
+            )}
           </div>
           <div className="min-w-0 flex-1 space-y-1.5">
             {editing && draft ? (
@@ -541,9 +594,16 @@ export function AgentDetailPanel({
                 {displayName}
               </div>
             )}
+            {!editing && positionName && (
+              <div className="position-agent-role text-sm">
+                岗位：{desensitize(positionName)}
+              </div>
+            )}
+            {!hideStatusBadges && (
               <div className="flex flex-wrap items-center gap-1">
                 {statusBadges}
               </div>
+            )}
             {!editing && agent.owner_username && !agent.builtin && (
               <div className="text-muted-foreground flex items-center gap-1 text-xs">
                 <UserRoundIcon className="size-3 shrink-0" />
@@ -579,6 +639,13 @@ export function AgentDetailPanel({
           </div>
         )}
 
+        {!editing && (agent.llmwiki_knowledge_base_ids?.length ?? 0) > 0 && (
+          <div className="text-muted-foreground mt-2 flex items-center gap-1 text-xs">
+            <DatabaseIcon className="size-3 shrink-0" />
+            LLMWiki 知识库：{agent.llmwiki_knowledge_base_ids?.length ?? 0} 个
+          </div>
+        )}
+
         {/* Publish / featured toggles — only meaningful in edit mode. */}
         {editing && draft && (
           <div className="mt-3 space-y-2">
@@ -596,6 +663,14 @@ export function AgentDetailPanel({
                 配置后，对话生成的 Markdown 文件可一键发布到知识入库接口。
               </p>
             </div>
+            <LlmWikiKnowledgeSelector
+              source="all"
+              value={draft.knowledgeBaseIds}
+              onChange={(knowledgeBaseIds) =>
+                setDraft({ ...draft, knowledgeBaseIds })
+              }
+              variant="panel"
+            />
             <div className="bg-background/60 flex items-center justify-between rounded-lg border px-3 py-2">
               <div className="pr-3">
                 <p className="text-sm font-medium">会商技能识别强化</p>
@@ -646,7 +721,7 @@ export function AgentDetailPanel({
 
 
       {/* ── 常用问题 ───────────────────────────────────────────────────── */}
-      {(editing || questions.length > 0 || canEdit) && (
+      {(showCommonQuestions || editing || questions.length > 0 || canEdit) && (
         <Section
           icon={<MessageCircleQuestionIcon className="size-3.5" />}
           title="常用问题"
@@ -787,8 +862,9 @@ export function AgentDetailPanel({
 
       {/* ── 技能管理 ───────────────────────────────────────────────────── */}
       <Section
-        icon={<SparklesIcon className="size-3.5" />}
+        icon={skillsIcon ?? <SparklesIcon className="size-3.5" />}
-        title={`已启用技能 ${skillNamesShown.length} 个`}
+        title={skillsTitle ?? `已启用技能 ${skillNamesShown.length} 个`}
+        className="position-roundtable-skills-section"
         extra={
           editing ? (
             <Button
@@ -830,7 +906,9 @@ export function AgentDetailPanel({
   const panelChrome = (collapseButton: ReactNode) => (
     <>
       <div className="flex h-12 shrink-0 items-center justify-between border-b px-4">
-        <span className="shrink-0 whitespace-nowrap text-sm font-semibold">智能体信息</span>
+        <span className="shrink-0 whitespace-nowrap text-sm font-semibold">
+          {panelTitle ?? "智能体信息"}
+        </span>
         <div className="flex min-w-0 items-center gap-1">
           {headerActions}
           {compactAppearanceActions}
@@ -844,7 +922,11 @@ export function AgentDetailPanel({
   return (
     <>
       {/* ── Desktop (lg+): inline aside, collapsible to a rail ───────────── */}
-      {collapsed ? (
+      {embedded ? (
+        <aside className="bg-card/40 flex h-full w-full min-w-0 shrink-0 flex-col border-l">
+          {panelChrome(null)}
+        </aside>
+      ) : collapsed ? (
         <div className="hidden shrink-0 items-start border-l px-2 pt-3 lg:flex">
           <div className="flex items-center gap-1">
             {compactAppearanceActions}
@@ -877,6 +959,8 @@ export function AgentDetailPanel({
         </aside>
       )}
 
+      {!embedded && (
+        <>
           {/* ── Narrow screens (<lg): rail trigger + drawer with the same body ── */}
           <div className="flex shrink-0 flex-col items-center border-l pt-3 lg:hidden">
             <Tooltip content="智能体信息">
@@ -901,6 +985,8 @@ export function AgentDetailPanel({
               <div className="min-h-0 flex-1 overflow-y-auto">{body}</div>
             </SheetContent>
           </Sheet>
+        </>
+      )}
 
       {/* ── Secondary surfaces ───────────────────────────────────────────── */}
       <SkillPickerSheet

frontend-web/src/components/workspace/agents/agent-gallery.tsx

@@ -16,9 +16,11 @@ import { getStoredAuth } from "@/core/auth";
 import { useAgentsPaginated, usePrivateAgentsPaginated } from "@/core/agents";
 import type { Agent, AgentSort } from "@/core/agents";
 import { useI18n } from "@/core/i18n/hooks";
+import { isSentimentAgentVisible } from "@/core/sentiment-agent/config";
 import { usePrivateSquareStatus, usePublishSquares, useViewMode } from "@/core/system-settings/hooks";
 
 import { AgentCard } from "./agent-card";
+import { SentimentAgentCard } from "./sentiment-agent-card";
 
 const PAGE_SIZE = 12;
 
@@ -30,6 +32,7 @@ const PRIVATE_SQUARE_PASSWORD_KEY = "deer-flow.private-square-password";
 export function AgentGallery() {
   const { t } = useI18n();
   const router = useRouter();
+  const sentimentAgentVisible = isSentimentAgentVisible();
   // 「内置智能体」筛选仅管理员可见（后端 scope=builtin 也做了 admin 闸门兜底）。
   const isAdmin = getStoredAuth()?.system_role === "admin";
   const [viewMode, setViewMode] = useViewMode("agent");
@@ -41,6 +44,9 @@ export function AgentGallery() {
   // Each configured publish square (发布广场) becomes its own browse tab; the
   // backend always returns at least one (the built-in default).
   const squareTabs = publishSquares?.squares ?? [];
+  // 默认广场固定排在「我的」之后；舆情分析是依附在默认广场后的前端虚拟类型，
+  // 其余自定义广场继续保持后端给出的顺序。
+  const [defaultSquare, ...additionalSquares] = squareTabs;
   // Publisher filter: click a card's 发布者 to keep only that user's agents.
   // {id} is the owner user_id (server filter), {label} the desensitized name.
   const [publisher, setPublisher] = useState<{ id: string; label: string } | null>(
@@ -70,6 +76,7 @@ export function AgentGallery() {
       activeTab !== "mine" &&
       activeTab !== "private" &&
       activeTab !== "builtin" &&
+      activeTab !== "sentiment" &&
       squareTabs.length > 0 &&
       !squareTabs.some((sq) => sq.id === activeTab)
     ) {
@@ -90,9 +97,13 @@ export function AgentGallery() {
 
   // Only the active tab fetches. "广场" maps to the server "square" scope
   // (built-in/published, never private), "我的" to "mine" (owned + favorited),
-  // "内置" to "builtin" (admin-only, user_id IS NULL).
+  // "内置" to "builtin" (admin-only, user_id IS NULL). 「舆情分析」是前端虚拟
+  // 类型，不查后端列表。
   const isSquareTab =
-    activeTab !== "mine" && activeTab !== "private" && activeTab !== "builtin";
+    activeTab !== "mine" &&
+    activeTab !== "private" &&
+    activeTab !== "builtin" &&
+    activeTab !== "sentiment";
   const mainScope =
     activeTab === "mine"
       ? "mine"
@@ -112,7 +123,7 @@ export function AgentGallery() {
     sort,
     page: mainPage,
     pageSize: PAGE_SIZE,
-    enabled: activeTab !== "private",
+    enabled: activeTab !== "private" && activeTab !== "sentiment",
     owner: publisher?.id,
     // Each square tab fetches only that square's agents.
     square: isSquareTab ? activeTab : undefined,
@@ -148,9 +159,16 @@ export function AgentGallery() {
   // password has been verified. Until then we show the gate (or the lock
   // prompt) and hide the keyword/tag search bar — there is no list to filter.
   const privateUnlocked = privateFeatureUsable && !!privatePassword;
-  const showSearchBar = activeTab !== "private" || privateUnlocked;
+  const showSearchBar =
+    activeTab !== "sentiment" &&
+    (activeTab !== "private" || privateUnlocked);
 
-  const activeTotal = activeTab === "private" ? privateTotal : mainTotal;
+  const activeTotal =
+    activeTab === "sentiment"
+      ? 1
+      : activeTab === "private"
+        ? privateTotal
+        : mainTotal;
   const setTabPage = (tab: string, page: number) =>
     setPages((prev) => ({ ...prev, [tab]: page }));
 
@@ -398,7 +416,22 @@ export function AgentGallery() {
           <div className="flex items-center justify-between gap-3">
             <TabsList className="w-auto max-w-full flex-wrap justify-start self-start">
               <TabsTrigger value="mine">我的</TabsTrigger>
-              {squareTabs.map((sq) => (
+              {defaultSquare && (
+                <TabsTrigger
+                  key={defaultSquare.id}
+                  value={defaultSquare.id}
+                  title={defaultSquare.description || defaultSquare.name}
+                >
+                  {defaultSquare.name}
+                </TabsTrigger>
+              )}
+              {sentimentAgentVisible && (
+                /* 舆情分析：前端虚拟类型，直连外部舆情问答接口。 */
+                <TabsTrigger value="sentiment" title="舆情分析智能体（外部接口对接）">
+                  舆情分析
+                </TabsTrigger>
+              )}
+              {additionalSquares.map((sq) => (
                 <TabsTrigger key={sq.id} value={sq.id} title={sq.description || sq.name}>
                   {sq.name}
                 </TabsTrigger>
@@ -512,6 +545,25 @@ export function AgentGallery() {
           })}
         </TabsContent>
 
+        {/* 舆情分析类型：固定一张虚拟智能体卡片（名称/简介可编辑），
+            接口地址与鉴权在 runtime-config.js 配置。 */}
+        {sentimentAgentVisible && (
+          <TabsContent
+            value="sentiment"
+            className="flex-1 overflow-y-auto p-6 mt-0"
+          >
+            {viewMode === "list" ? (
+              <div className="flex flex-col gap-2">
+                <SentimentAgentCard layout="list" />
+              </div>
+            ) : (
+              <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+                <SentimentAgentCard />
+              </div>
+            )}
+          </TabsContent>
+        )}
+
         {isAdmin && (
           <TabsContent value="builtin" className="flex-1 overflow-y-auto p-6 mt-0">
             {renderListBody({

frontend-web/src/components/workspace/agents/sentiment-agent-card.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+import { BotIcon, MessageSquareIcon, Radio, SquarePenIcon } from "lucide-react";
+import { useRouter } from "next/navigation";
+import { useEffect, useState } from "react";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { SENTIMENT_AGENT_ID } from "@/core/sentiment-agent/config";
+import { readSentimentAgentProfile } from "@/core/sentiment-agent/profile";
+import { desensitize } from "@/lib/desensitize";
+import { cn } from "@/lib/utils";
+
+import { SentimentAgentProfileDialog } from "./sentiment-agent-profile-dialog";
+
+/**
+ * 「舆情分析」类型下的虚拟智能体卡片：只存在于前端（不落库 /api/agents），
+ * 对话直连外部 AG-UI 网关。名称 / 简介可编辑（localStorage），
+ * 视觉与普通智能体卡片保持一致（网格 / 列表两种布局）。
+ */
+export function SentimentAgentCard({
+  layout = "grid",
+  className,
+}: {
+  layout?: "grid" | "list";
+  className?: string;
+}) {
+  const router = useRouter();
+  const [profile, setProfile] = useState(() => readSentimentAgentProfile());
+  const [editOpen, setEditOpen] = useState(false);
+
+  // 编辑弹窗也可能挂在对话页，保存后广播事件，这里即时刷新卡片。
+  useEffect(() => {
+    const onChange = () => setProfile(readSentimentAgentProfile());
+    window.addEventListener("sentiment-agent-profile-changed", onChange);
+    return () =>
+      window.removeEventListener("sentiment-agent-profile-changed", onChange);
+  }, []);
+
+  const handleChat = () => {
+    router.push(`/page/workspace/agents/${SENTIMENT_AGENT_ID}/chats/new`);
+  };
+
+  const editButton = (
+    <Button
+      size="icon"
+      variant="ghost"
+      className="h-8 w-8 shrink-0"
+      onClick={() => setEditOpen(true)}
+      title="编辑名称与简介"
+      aria-label="编辑名称与简介"
+    >
+      <SquarePenIcon className="h-3.5 w-3.5" />
+    </Button>
+  );
+
+  const chatButton = (
+    <Button
+      size="sm"
+      className={cn(layout === "list" ? "shrink-0" : "w-full")}
+      onClick={handleChat}
+    >
+      <MessageSquareIcon className="mr-1.5 h-3.5 w-3.5" />
+      对话
+    </Button>
+  );
+
+  const badge = (
+    <Badge variant="secondary" className="gap-1 text-xs">
+      <Radio className="size-3" />
+      舆情分析
+    </Badge>
+  );
+
+  const dialog = (
+    <SentimentAgentProfileDialog
+      open={editOpen}
+      onOpenChange={setEditOpen}
+    />
+  );
+
+  if (layout === "list") {
+    return (
+      <div
+        className={cn(
+          "group flex min-w-0 items-center gap-3 rounded-lg border p-2.5 transition-shadow hover:shadow-sm dark:border-[#213D5E] dark:bg-[#02244C]",
+          className,
+        )}
+      >
+        <div className="agent-avatar bg-primary/10 text-primary flex h-9 w-9 shrink-0 items-center justify-center rounded-lg">
+          <BotIcon className="h-5 w-5" />
+        </div>
+        <div className="min-w-0 flex-1 overflow-hidden">
+          <div className="flex min-w-0 items-center gap-2">
+            <span
+              className="min-w-0 truncate text-sm font-medium"
+              title={desensitize(profile.name)}
+            >
+              {desensitize(profile.name)}
+            </span>
+            {badge}
+          </div>
+          <p className="text-muted-foreground mt-0.5 truncate text-xs">
+            {desensitize(profile.description)}
+          </p>
+        </div>
+        <div className="flex shrink-0 items-center gap-1">
+          {editButton}
+          {chatButton}
+        </div>
+        {dialog}
+      </div>
+    );
+  }
+
+  return (
+    <Card
+      className={cn(
+        "group flex min-w-0 flex-col transition-shadow hover:shadow-md",
+        className,
+      )}
+    >
+      <CardHeader className="min-w-0 pb-2">
+        <div className="flex min-w-0 items-start justify-between gap-2">
+          <div className="flex min-w-0 flex-1 items-center gap-2 overflow-hidden">
+            <div className="agent-avatar bg-primary/10 text-primary flex h-9 w-9 shrink-0 items-center justify-center rounded-lg">
+              <BotIcon className="h-5 w-5" />
+            </div>
+            <div className="min-w-0 flex-1 overflow-hidden">
+              <CardTitle
+                className="block w-full min-w-0 overflow-hidden text-base text-ellipsis whitespace-nowrap"
+                title={desensitize(profile.name)}
+              >
+                {desensitize(profile.name)}
+              </CardTitle>
+              <div className="mt-0.5">{badge}</div>
+            </div>
+          </div>
+          <div className="flex shrink-0 items-center justify-end gap-1">
+            {editButton}
+          </div>
+        </div>
+        <CardDescription className="mt-2 line-clamp-2 text-sm">
+          {desensitize(profile.description)}
+        </CardDescription>
+      </CardHeader>
+      <CardFooter className="mt-auto flex flex-col items-stretch gap-2 pt-2">
+        {chatButton}
+      </CardFooter>
+      {dialog}
+    </Card>
+  );
+}

frontend-web/src/components/workspace/agents/sentiment-agent-profile-dialog.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  DEFAULT_SENTIMENT_AGENT_PROFILE,
+  type SentimentAgentProfile,
+  readSentimentAgentProfile,
+  saveSentimentAgentProfile,
+} from "@/core/sentiment-agent/profile";
+
+/**
+ * 舆情分析智能体的「编辑信息」弹窗：修改名称 / 简介并保存到 localStorage。
+ * 智能体管理页的卡片和对话页顶栏共用。
+ */
+export function SentimentAgentProfileDialog({
+  open,
+  onOpenChange,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const [name, setName] = useState("");
+  const [description, setDescription] = useState("");
+
+  useEffect(() => {
+    if (!open) return;
+    const profile = readSentimentAgentProfile();
+    setName(profile.name);
+    setDescription(profile.description);
+  }, [open]);
+
+  const handleSave = () => {
+    const next: SentimentAgentProfile = {
+      name: name.trim() || DEFAULT_SENTIMENT_AGENT_PROFILE.name,
+      description:
+        description.trim() || DEFAULT_SENTIMENT_AGENT_PROFILE.description,
+    };
+    saveSentimentAgentProfile(next);
+    toast.success("舆情分析智能体信息已更新");
+    onOpenChange(false);
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-[480px]">
+        <DialogHeader>
+          <DialogTitle>编辑舆情分析智能体</DialogTitle>
+        </DialogHeader>
+        <div className="flex flex-col gap-4 py-2">
+          <div className="flex flex-col gap-2">
+            <label htmlFor="sentiment-agent-name" className="text-sm font-medium">
+              名称
+            </label>
+            <Input
+              id="sentiment-agent-name"
+              value={name}
+              maxLength={50}
+              onChange={(e) => setName(e.target.value)}
+              placeholder="智能体名称"
+            />
+          </div>
+          <div className="flex flex-col gap-2">
+            <label
+              htmlFor="sentiment-agent-description"
+              className="text-sm font-medium"
+            >
+              简介
+            </label>
+            <Textarea
+              id="sentiment-agent-description"
+              value={description}
+              maxLength={300}
+              onChange={(e) => setDescription(e.target.value)}
+              placeholder="智能体简介（展示在卡片与对话页）"
+              className="min-h-[96px] resize-none"
+            />
+          </div>
+          <p className="text-muted-foreground text-xs">
+            仅修改本浏览器展示的名称与简介；接口地址与鉴权请在部署目录的
+            runtime-config.js 中配置。
+          </p>
+        </div>
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>
+            取消
+          </Button>
+          <Button onClick={handleSave}>保存</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend-web/src/components/workspace/appearance-controls.tsx

@@ -26,7 +26,7 @@ import { buildLightAppUrl } from "@/strategy-components/lib/light-app";
  *   - "banner-dark" / "banner-light"：Header 落在主题 banner 上（白字 / 浅色 hover）。
  *   - "content"：简洁模式聊天页浅底顶栏，走 foreground / muted-foreground。
  */
-export type AppearanceControlTone = "banner-dark" | "banner-light" | "content";
+export type AppearanceControlTone = "banner-dark" | "banner-light" | "banner-custom" | "content";
 
 // 换肤色板：红色=红白主题(light)，蓝色=浅蓝主题(lightblue)，冰川蓝=柔和浅蓝主题(iceblue)，浅黄色=柔和黄主题(lightyellow)，深蓝色=深色主题(dark)
 export const THEME_SWATCHES: { id: ThemeType; label: string; color: string }[] = [
@@ -43,6 +43,8 @@ const triggerToneClass = (tone: AppearanceControlTone) =>
     ? "text-slate-400 hover:bg-slate-800/50 hover:text-slate-400"
     : tone === "banner-light"
       ? "text-white hover:bg-[var(--brand-950)] hover:text-white active:bg-[#8a0618]"
+      : tone === "banner-custom"
+        ? "text-[var(--navigation-foreground)] hover:bg-white/20 hover:text-[var(--navigation-foreground)] active:bg-white/30"
       : "text-muted-foreground hover:bg-muted hover:text-foreground";
 
 export function CompactShortcutButtons({ tone }: { tone: AppearanceControlTone }) {

frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx

@@ -15,6 +15,7 @@ import {
   UploadCloudIcon,
   XIcon,
 } from "lucide-react";
+import { useQueryClient } from "@tanstack/react-query";
 import { useParams } from "next/navigation";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { AnchorHTMLAttributes, HTMLAttributes, ReactNode } from "react";
@@ -29,6 +30,7 @@ import {
   ArtifactHeader,
   ArtifactTitle,
 } from "@/components/ai-elements/artifact";
+import { DocumentRewriteDialog } from "@/components/workspace/artifacts/document-rewrite-dialog";
 import { Select, SelectItem } from "@/components/ui/select";
 import {
   SelectContent,
@@ -39,10 +41,21 @@ import {
 import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
 import { CodeEditor } from "@/components/workspace/code-editor";
 import { MarkdownAiEditor } from "@/open-canvas/components/artifact/MarkdownAiEditor";
+import { useDocumentRewrite } from "@/open-canvas/hooks/useDocumentRewrite";
+import {
+  listDurableDocumentRewrites,
+  streamDurableDocumentRewriteJob,
+  type DocumentRewriteSummary,
+  type DocumentRewriteStreamEvent,
+} from "@/open-canvas/api/rewrite";
 import { publishArtifactToKnowledge } from "@/core/agents/api";
 import { useAgent } from "@/core/agents/hooks";
 import { apiFetch } from "@/core/api";
 import { copyTextToClipboard } from "@/core/clipboard";
+import {
+  DOCUMENT_REWRITE_UNDONE_EVENT,
+  useDocumentRewritePresentation,
+} from "@/core/document-rewrite/context";
 import {
   downloadArtifactFile,
 } from "@/core/artifacts/download";
@@ -86,6 +99,15 @@ import { SkillInstallDialog } from "./skill-install-dialog";
 
 const SANDBOX_RESUME_EVENT = "workspace:sandbox-resume-autoscroll";
 
+async function sha256Content(content: string): Promise<string | undefined> {
+  if (!globalThis.crypto?.subtle) return undefined;
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(content),
+  );
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
 function extractTextFromChildren(children: ReactNode): string {
   if (typeof children === "string" || typeof children === "number") return String(children);
   if (Array.isArray(children)) return children.map(extractTextFromChildren).join("");
@@ -123,14 +145,18 @@ export function ArtifactFileDetail({
   className,
   filepath: filepathFromProps,
   threadId,
+  mimeType = null,
   onClose,
   allowVirtualMarkdownEdit = false,
   disableDesensitize = false,
   hideFileName = false,
+  onDownloadClick,
 }: {
   className?: string;
   filepath: string;
   threadId: string;
+  /** Server/tool supplied type wins over path guessing when available. */
+  mimeType?: string | null;
   /** 覆盖默认关闭行为（仅 setOpen(false)）；圆桌 Step3 文件预览用于退出沙箱模式。 */
   onClose?: () => void;
   /**
@@ -146,6 +172,12 @@ export function ArtifactFileDetail({
    */
   disableDesensitize?: boolean;
   hideFileName?: boolean;
+  /**
+   * 覆盖默认下载行为：传入后点击「下载」按钮不再走内置的各格式下载，而是回调宿主
+   * （深度研究沙箱用它弹「Markdown / Word」格式选择弹窗），并隐藏工具栏中重复的
+   * 「另存为 Word」。默认不传 —— 其它调用方行为不变。
+   */
+  onDownloadClick?: () => void;
 }) {
   const { t } = useI18n();
   const { artifacts, setOpen, select } = useArtifacts();
@@ -153,12 +185,36 @@ export function ArtifactFileDetail({
   const isWriteFileVirtual = useMemo(() => {
     return filepathFromProps.startsWith("write-file:");
   }, [filepathFromProps]);
+  // A streamed tool call can be opened before the path has been normalized by
+  // the artifacts API. Keep the format supplied by the writer so Markdown is
+  // rendered as Markdown instead of falling back to a TEXT source preview.
+  const writeFileLanguageHint = useMemo(() => {
+    if (!isWriteFileVirtual) return null;
+    try {
+      const language = new URL(filepathFromProps).searchParams.get("language");
+      return language === "markdown" || language === "html" || language === "mermaid"
+        ? language
+        : null;
+    } catch {
+      return null;
+    }
+  }, [filepathFromProps, isWriteFileVirtual]);
+  const mimeLanguageHint = useMemo(() => {
+    const normalized = mimeType?.toLowerCase().trim() ?? "";
+    if (normalized.includes("markdown")) return "markdown";
+    if (normalized.includes("html")) return "html";
+    if (normalized.includes("mermaid")) return "mermaid";
+    if (normalized.startsWith("text/")) return "text";
+    return null;
+  }, [mimeType]);
   const filepath = useMemo(() => {
     if (isWriteFileVirtual) {
       const url = new URL(filepathFromProps);
-      return decodeURIComponent(url.pathname);
+      return decodeURIComponent(url.pathname).trim();
     }
-    return filepathFromProps;
+    // Tool arguments may contain harmless surrounding whitespace. Passing it
+    // into extension detection turns `report.md ` into a generic TEXT file.
+    return filepathFromProps.trim();
   }, [filepathFromProps, isWriteFileVirtual]);
   const isSkillFile = useMemo(() => {
     return filepath.endsWith(".skill");
@@ -188,15 +244,20 @@ export function ArtifactFileDetail({
   }, [filepath, isWriteFileVirtual, editVirtualMarkdown]);
   const { isCodeFile, language } = useMemo(() => {
     if (useWriteFileStreaming) {
-      let nextLanguage = checkCodeFile(filepath).language;
+      let nextLanguage =
+        mimeLanguageHint ?? writeFileLanguageHint ?? checkCodeFile(filepath).language;
       nextLanguage ??= "text";
       return { isCodeFile: true, language: nextLanguage };
     }
     if (isSkillFile) {
       return { isCodeFile: true, language: "markdown" };
     }
-    return checkCodeFile(filepath);
+    const detected = checkCodeFile(filepath);
-  }, [filepath, useWriteFileStreaming, isSkillFile]);
+    if (mimeLanguageHint) {
+      return { isCodeFile: true as const, language: mimeLanguageHint };
+    }
+    return detected;
+  }, [filepath, useWriteFileStreaming, isSkillFile, mimeLanguageHint, writeFileLanguageHint]);
   const isSupportPreview = useMemo(() => {
     return (
       language === "html" ||
@@ -209,7 +270,8 @@ export function ArtifactFileDetail({
     // editVirtualMarkdown：用解码后的真实路径走 artifacts API（而非 write-file 虚拟
     // URL），这样保存后 useUpdateArtifactContent 写入的查询缓存才能命中，编辑内容
     // 不会被旧的内存 stub 值覆盖回退。
-    filepath: editVirtualMarkdown ? filepath : filepathFromProps,
+    filepath:
+      editVirtualMarkdown || !isWriteFileVirtual ? filepath : filepathFromProps,
     enabled: isCodeFile && !useWriteFileStreaming,
   });
 
@@ -224,10 +286,26 @@ export function ArtifactFileDetail({
   const canUseAiEditor = canEditArtifact;
   const [draftContent, setDraftContent] = useState("");
   const [hasLocalEdits, setHasLocalEdits] = useState(false);
+  const [documentRewriteDialogOpen, setDocumentRewriteDialogOpen] = useState(false);
+  const [documentRewritePresentationId, setDocumentRewritePresentationId] = useState<string | null>(null);
   const updateArtifact = useUpdateArtifactContent();
-  const displayContent = canEditArtifact ? draftContent : (content ?? "");
+  const queryClient = useQueryClient();
-  const isAutoPreviewLanguage = language === "html" || language === "markdown";
+  const documentRewrite = useDocumentRewrite();
-  const isPreviewStreaming = isAutoPreviewLanguage && thread.isLoading;
+  const rewritePresentation = useDocumentRewritePresentation();
+  const hydratedRewriteScopeRef = useRef<string | null>(null);
+  const mirroredRequirementsPlanRef = useRef<{ presentationId: string | null; plan: string }>({
+    presentationId: null,
+    plan: "",
+  });
+  const documentRewriteActive = documentRewrite.isActive;
+  const canUseFullDocumentRewrite = canEditArtifact && !hasLocalEdits;
+  const displayContent = documentRewriteActive
+    ? documentRewrite.run.draft
+    : (canEditArtifact ? draftContent : (content ?? ""));
+  const isAutoPreviewLanguage =
+    language === "html" || language === "markdown" || language === "mermaid";
+  const isPreviewStreaming =
+    isAutoPreviewLanguage && (thread.isLoading || documentRewriteActive);
   const hasMultipleArtifacts = (artifacts?.length ?? 0) > 1;
   const fileTypeLabel = useMemo(() => {
     if (isImageFile(filepath)) return "IMG";
@@ -255,17 +333,302 @@ export function ArtifactFileDetail({
   const artifactContentRef = useRef<HTMLDivElement | null>(null);
   const resumeButtonTimeoutRef = useRef<number | null>(null);
 
+  useEffect(() => {
+    if (!documentRewriteActive) return;
+    setAllowAutoViewSwitch(false);
+    setAutoScrollEnabled(true);
+    setShowResumeAutoScroll(false);
+    setViewMode("code");
+  }, [documentRewriteActive]);
+
   useEffect(() => {
     setDraftContent(content ?? "");
     setHasLocalEdits(false);
   }, [filepathFromProps]);
 
   useEffect(() => {
-    if (!canEditArtifact || hasLocalEdits) {
+    if (!canEditArtifact || hasLocalEdits || documentRewriteActive) {
       return;
     }
     setDraftContent(content ?? "");
-  }, [canEditArtifact, content, hasLocalEdits]);
+  }, [canEditArtifact, content, documentRewriteActive, hasLocalEdits]);
+
+  useEffect(() => {
+    if (
+      !canEditArtifact ||
+      !threadId ||
+      !filepath ||
+      isMock ||
+      useWriteFileStreaming ||
+      documentRewriteActive
+    ) {
+      return;
+    }
+    const scope = `${threadId}:${filepath}`;
+    if (hydratedRewriteScopeRef.current === scope) return;
+    hydratedRewriteScopeRef.current = scope;
+    let disposed = false;
+
+    const updatePresentation = (
+      presentationId: string,
+      event: DocumentRewriteStreamEvent,
+    ) => {
+      if (!rewritePresentation) return;
+      switch (event.type) {
+        case "snapshot_fixed":
+          rewritePresentation.update(presentationId, {
+            stage: "requirements",
+            fileName: event.fileName || getFileName(filepath),
+            originalCharCount: event.originalCharCount,
+            requirementsPlan: "",
+          });
+          break;
+        case "requirements_started":
+          rewritePresentation.update(presentationId, { stage: "requirements", requirementsPlan: "" });
+          break;
+        case "requirements_checkpoint":
+        case "requirements_completed":
+          rewritePresentation.update(presentationId, {
+            stage: "requirements",
+            requirementsPlan: event.content,
+          });
+          break;
+        case "requirements_resolved":
+          rewritePresentation.update(presentationId, {
+            stage: "writing",
+            ...(event.plan ? { requirementsPlan: event.plan } : {}),
+          });
+          break;
+        case "rewrite_delta":
+          rewritePresentation.update(presentationId, {
+            stage: "writing",
+            writtenCharCount: event.charCount,
+          });
+          break;
+        case "validation_started":
+          rewritePresentation.update(presentationId, { stage: "validation" });
+          break;
+        case "validation_completed":
+          rewritePresentation.update(presentationId, { warnings: event.warnings });
+          break;
+        case "comparison_ready":
+          rewritePresentation.update(presentationId, { summary: event.summary });
+          break;
+        case "commit_started":
+          rewritePresentation.update(presentationId, { stage: "committing" });
+          break;
+        case "committed":
+          rewritePresentation.update(presentationId, {
+            rewrittenContent: event.content,
+            versionId: event.versionId ?? null,
+          });
+          break;
+        case "done":
+          rewritePresentation.update(presentationId, {
+            stage: "completed",
+            versionId: event.versionId ?? null,
+          });
+          break;
+        case "conflict":
+          rewritePresentation.update(presentationId, { stage: "conflict", error: event.message });
+          break;
+        case "cancelled":
+          rewritePresentation.update(presentationId, { stage: "cancelled", error: event.message });
+          break;
+        case "error":
+          rewritePresentation.update(presentationId, { stage: "error", error: event.message });
+          break;
+        default:
+          break;
+      }
+    };
+
+    void (async () => {
+      try {
+        const jobs = await listDurableDocumentRewrites({ threadId, path: filepath });
+        const latest = jobs[0];
+        if (disposed || !latest) return;
+        // Restore prior terminal rewrites into the ordinary message timeline in
+        // chronological order.  The newest job is handled below because it may
+        // still be active and needs its SSE stream resumed.
+        for (const historical of jobs.slice(1).reverse()) {
+          const historicalResult = historical.result;
+          const historicalSummary = historicalResult.summary && typeof historicalResult.summary === "object"
+            ? historicalResult.summary as DocumentRewriteSummary
+            : null;
+          const historicalPresentationId = rewritePresentation?.create({
+            threadId,
+            source: { kind: "artifact", id: threadId, path: filepath },
+            fileName: getFileName(filepath),
+            instruction: historical.request.instruction,
+            style: historical.request.style,
+            modelName: historical.request.modelName,
+            originalContent: historical.request.originalContent,
+            rewrittenContent: typeof historicalResult.content === "string" ? historicalResult.content : null,
+            requirementsPlan: typeof historicalResult.requirementsPlan === "string"
+              ? historicalResult.requirementsPlan
+              : "",
+          });
+          if (!historicalPresentationId || !rewritePresentation) continue;
+          rewritePresentation.update(historicalPresentationId, {
+            stage: historical.status === "completed"
+              ? historicalResult.status === "conflict" ? "conflict" : "completed"
+              : historical.status === "cancelled" ? "cancelled" : "error",
+            summary: historicalSummary,
+            warnings: historicalSummary?.validationWarnings ?? [],
+            versionId: typeof historicalResult.versionId === "string" ? historicalResult.versionId : null,
+            error: historicalResult.status === "conflict"
+              ? "文件在改写期间已变化，未覆盖原文件。"
+              : historical.status === "cancelled"
+                ? "已停止全文改写，原文件未被修改。"
+                : historical.status === "failed" ? "全文改写未完成，原文件未被修改。" : null,
+          });
+        }
+        const result = latest.result;
+        const summary = result.summary && typeof result.summary === "object"
+          ? result.summary as DocumentRewriteSummary
+          : null;
+        const originalContent = latest.request.originalContent || draftContent;
+        const rewrittenContent = typeof result.content === "string" ? result.content : null;
+        const presentationId = rewritePresentation?.create({
+          threadId,
+          source: { kind: "artifact", id: threadId, path: filepath },
+          fileName: getFileName(filepath),
+          instruction: latest.request.instruction,
+          style: latest.request.style,
+          modelName: latest.request.modelName,
+          originalContent,
+          rewrittenContent,
+          requirementsPlan: typeof result.requirementsPlan === "string" ? result.requirementsPlan : "",
+        });
+        if (!presentationId || !rewritePresentation) return;
+        setDocumentRewritePresentationId(presentationId);
+
+        if (latest.status === "completed") {
+          rewritePresentation.update(presentationId, {
+            stage: result.status === "conflict" ? "conflict" : "completed",
+            summary,
+            warnings: summary?.validationWarnings ?? [],
+            versionId: typeof result.versionId === "string" ? result.versionId : null,
+            error: result.status === "conflict" ? "文件在改写期间已变化，未覆盖原文件。" : null,
+          });
+          if (rewrittenContent && result.status !== "conflict") {
+            setDraftContent(rewrittenContent);
+            setHasLocalEdits(false);
+            queryClient.setQueriesData(
+              { queryKey: ["artifact", filepath, threadId, isMock] },
+              { content: rewrittenContent, url: undefined },
+            );
+          }
+          return;
+        }
+        if (latest.status === "failed" || latest.status === "cancelled") {
+          rewritePresentation.update(presentationId, {
+            stage: latest.status === "cancelled" ? "cancelled" : "error",
+            summary,
+          });
+          return;
+        }
+
+        void documentRewrite.start(
+          {
+            threadId,
+            path: filepath,
+            instruction: latest.request.instruction,
+            style: latest.request.style,
+            modelName: latest.request.modelName ?? undefined,
+          },
+          {
+            jobId: latest.id,
+            stream: (signal) => streamDurableDocumentRewriteJob(
+              { threadId, path: filepath },
+              latest.id,
+              signal,
+            ),
+            onEvent: (event) => updatePresentation(presentationId, event),
+            onCommitted: (rewritten) => {
+              setDraftContent(rewritten);
+              setHasLocalEdits(false);
+              rewritePresentation.update(presentationId, { rewrittenContent: rewritten });
+              queryClient.setQueriesData(
+                { queryKey: ["artifact", filepath, threadId, isMock] },
+                { content: rewritten, url: undefined },
+              );
+            },
+          },
+        );
+      } catch {
+        // Existing artifacts remain available even if history hydration fails.
+      }
+    })();
+    return () => {
+      disposed = true;
+    };
+  }, [
+    canEditArtifact,
+    documentRewrite,
+    documentRewriteActive,
+    draftContent,
+    filepath,
+    isMock,
+    queryClient,
+    rewritePresentation,
+    threadId,
+    useWriteFileStreaming,
+  ]);
+
+  // The stream hook already coalesces requirements tokens with rAF. Mirror the
+  // coalesced plan into the ordinary message-list card instead of forcing a
+  // React context write for every individual SSE delta.
+  useEffect(() => {
+    const presentationId = documentRewritePresentationId;
+    const plan = documentRewrite.run.requirementsPlan;
+    if (!presentationId || !rewritePresentation || !plan) {
+      return;
+    }
+
+    // `update` replaces the presentation context value, which changes the
+    // context object in this effect's dependency list.  Only write when this
+    // particular card actually receives new text; otherwise React would
+    // re-enter this effect indefinitely after each context update.
+    const previous = mirroredRequirementsPlanRef.current;
+    if (previous.presentationId === presentationId && previous.plan === plan) {
+      return;
+    }
+    mirroredRequirementsPlanRef.current = { presentationId, plan };
+    rewritePresentation.update(presentationId, {
+      requirementsPlan: plan,
+    });
+  }, [
+    documentRewrite.run.requirementsPlan,
+    documentRewritePresentationId,
+    rewritePresentation,
+  ]);
+
+  useEffect(() => {
+    const handleRewriteUndo = (event: Event) => {
+      const detail = (event as CustomEvent<{
+        source?: { kind?: string; id?: string; path?: string };
+        content?: string;
+      }>).detail;
+      if (
+        detail?.source?.kind !== "artifact" ||
+        detail.source.id !== threadId ||
+        detail.source.path !== filepath ||
+        typeof detail.content !== "string"
+      ) {
+        return;
+      }
+      setDraftContent(detail.content);
+      setHasLocalEdits(false);
+      queryClient.setQueriesData(
+        { queryKey: ["artifact", filepath, threadId, isMock] },
+        { content: detail.content, url: undefined },
+      );
+    };
+    window.addEventListener(DOCUMENT_REWRITE_UNDONE_EVENT, handleRewriteUndo);
+    return () => window.removeEventListener(DOCUMENT_REWRITE_UNDONE_EVENT, handleRewriteUndo);
+  }, [filepath, isMock, queryClient, threadId]);
 
   useEffect(() => {
     setAllowAutoViewSwitch(true);
@@ -329,7 +692,7 @@ export function ArtifactFileDetail({
   );
 
   useEffect(() => {
-    if (!thread.isLoading || !autoScrollEnabled) {
+    if (!(thread.isLoading || documentRewriteActive) || !autoScrollEnabled) {
       return;
     }
 
@@ -340,17 +703,23 @@ export function ArtifactFileDetail({
     tick();
     const intervalId = window.setInterval(tick, 180);
     return () => window.clearInterval(intervalId);
-  }, [autoScrollEnabled, scrollArtifactToBottom, thread.isLoading]);
+  }, [
+    autoScrollEnabled,
+    documentRewriteActive,
+    scrollArtifactToBottom,
+    thread.isLoading,
+  ]);
 
   useEffect(() => {
-    if (!thread.isLoading || !autoScrollEnabled) {
+    if (!(thread.isLoading || documentRewriteActive) || !autoScrollEnabled) {
       return;
     }
 
     scrollArtifactToBottom("auto");
   }, [
     autoScrollEnabled,
-    content,
+    displayContent,
+    documentRewriteActive,
     scrollArtifactToBottom,
     thread.isLoading,
     viewMode,
@@ -451,7 +820,7 @@ export function ArtifactFileDetail({
   }, [scrollArtifactToBottom]);
 
   const handleSaveArtifact = useCallback(async () => {
-    if (!canEditArtifact || updateArtifact.isPending) {
+    if (!canEditArtifact || updateArtifact.isPending || documentRewriteActive) {
       return;
     }
     try {
@@ -474,8 +843,163 @@ export function ArtifactFileDetail({
     isMock,
     threadId,
     updateArtifact,
+    documentRewriteActive,
   ]);
 
+  const handleStartDocumentRewrite = useCallback(
+    async (input: {
+      instruction: string;
+      style: "formal_analysis" | "professional" | "concise" | "readable";
+      modelName: string | null;
+    }) => {
+      if (!canUseFullDocumentRewrite) {
+        toast.error(
+          hasLocalEdits
+            ? "请先保存当前 Markdown 修改后再进行全文改写。"
+            : "当前文件暂不支持全文改写。",
+        );
+        return;
+      }
+      setDocumentRewriteDialogOpen(false);
+      setAllowAutoViewSwitch(false);
+      setAutoScrollEnabled(true);
+      setViewMode("code");
+      const expectedHash = await sha256Content(draftContent);
+      const presentationId = rewritePresentation?.create({
+        threadId,
+        source: { kind: "artifact", id: threadId, path: filepath },
+        fileName: getFileName(filepath),
+        instruction: input.instruction,
+        style: input.style,
+        modelName: input.modelName,
+        originalContent: draftContent,
+      });
+      setDocumentRewritePresentationId(presentationId ?? null);
+      void documentRewrite.start(
+        {
+          threadId,
+          path: filepath,
+          instruction: input.instruction,
+          style: input.style,
+          modelName: input.modelName ?? undefined,
+          expectedHash,
+        },
+        {
+          onEvent: (event) => {
+            if (!presentationId || !rewritePresentation) return;
+            switch (event.type) {
+              case "snapshot_fixed":
+                rewritePresentation.update(presentationId, {
+                  stage: "requirements",
+                  fileName: event.fileName || getFileName(filepath),
+                  originalCharCount: event.originalCharCount,
+                  requirementsPlan: "",
+                });
+                break;
+              case "requirements_started":
+                rewritePresentation.update(presentationId, {
+                  stage: "requirements",
+                  requirementsPlan: "",
+                });
+                break;
+              case "requirements_checkpoint":
+              case "requirements_completed":
+                rewritePresentation.update(presentationId, {
+                  stage: "requirements",
+                  requirementsPlan: event.content,
+                });
+                break;
+              case "requirements_resolved":
+                rewritePresentation.update(presentationId, {
+                  stage: "writing",
+                  ...(event.plan ? { requirementsPlan: event.plan } : {}),
+                });
+                break;
+              case "rewrite_delta":
+                rewritePresentation.update(presentationId, {
+                  stage: "writing",
+                  writtenCharCount: event.charCount,
+                });
+                break;
+              case "validation_started":
+                rewritePresentation.update(presentationId, { stage: "validation" });
+                break;
+              case "validation_completed":
+                rewritePresentation.update(presentationId, { warnings: event.warnings });
+                break;
+              case "comparison_ready":
+                rewritePresentation.update(presentationId, { summary: event.summary });
+                break;
+              case "commit_started":
+                rewritePresentation.update(presentationId, { stage: "committing" });
+                break;
+              case "committed":
+                rewritePresentation.update(presentationId, {
+                  versionId: event.versionId ?? null,
+                });
+                break;
+              case "done":
+                rewritePresentation.update(presentationId, {
+                  stage: "completed",
+                  versionId: event.versionId ?? null,
+                });
+                break;
+              case "conflict":
+                rewritePresentation.update(presentationId, {
+                  stage: "conflict",
+                  error: event.message,
+                });
+                break;
+              case "error":
+                rewritePresentation.update(presentationId, {
+                  stage: "error",
+                  error: event.message,
+                });
+                break;
+              default:
+                break;
+            }
+          },
+          onCommitted: (rewritten) => {
+            setDraftContent(rewritten);
+            setHasLocalEdits(false);
+            if (presentationId && rewritePresentation) {
+              rewritePresentation.update(presentationId, { rewrittenContent: rewritten });
+            }
+            queryClient.setQueriesData(
+              {
+                queryKey: ["artifact", filepath, threadId, isMock],
+              },
+              { content: rewritten, url: undefined },
+            );
+            toast.success("Markdown 全文改写完成，已安全替换原文件。");
+          },
+        },
+      );
+    },
+    [
+      canUseFullDocumentRewrite,
+      draftContent,
+      documentRewrite,
+      filepath,
+      hasLocalEdits,
+      isMock,
+      queryClient,
+      rewritePresentation,
+      threadId,
+    ],
+  );
+
+  const handleCancelDocumentRewrite = useCallback(() => {
+    documentRewrite.cancel();
+    if (documentRewritePresentationId && rewritePresentation) {
+      rewritePresentation.update(documentRewritePresentationId, {
+        stage: "cancelled",
+        error: "已停止全文改写，原文件未被修改。",
+      });
+    }
+  }, [documentRewrite, documentRewritePresentationId, rewritePresentation]);
+
   // 发布入库：仅当当前路由是智能体会话（agents/:agent_id/chats/…）且该智能体
   // 配置了入库模板名（template_name）时，md 产物右上角才出现发布按钮。
   const { agent_id: routeAgentId } = useParams<{ agent_id?: string }>();
@@ -642,7 +1166,7 @@ export function ArtifactFileDetail({
                   }
                 }}
               >
-                {canUseAiEditor && (
+                {canUseAiEditor && !documentRewriteActive && (
                   <ToggleGroupItem
                     className="text-muted-foreground h-8 min-w-10 rounded-full border-0 bg-transparent px-3 shadow-none data-[state=on]:bg-background data-[state=on]:text-foreground data-[state=on]:shadow-[0_6px_14px_-10px_rgba(15,23,42,0.35)]"
                     value="edit"
@@ -689,10 +1213,25 @@ export function ArtifactFileDetail({
                 icon={updateArtifact.isPending ? LoaderIcon : SaveIcon}
                 label="保存 Markdown"
                 tooltip={hasLocalEdits ? "保存 Markdown 修改" : "Markdown 已保存"}
-                disabled={!hasLocalEdits || updateArtifact.isPending}
+                disabled={!hasLocalEdits || updateArtifact.isPending || documentRewriteActive}
                 onClick={handleSaveArtifact}
               />
             )}
+            {canEditArtifact && (
+              <ArtifactAction
+                icon={documentRewriteActive ? LoaderIcon : SparklesIcon}
+                label={documentRewriteActive ? "正在全文改写" : "AI 全文改写"}
+                tooltip={
+                  documentRewriteActive
+                    ? "正在生成临时草稿，原文件尚未被覆盖"
+                    : hasLocalEdits
+                      ? "请先保存当前 Markdown 修改"
+                      : "使用 AI 重写当前完整 Markdown"
+                }
+                disabled={documentRewriteActive || !canUseFullDocumentRewrite}
+                onClick={() => setDocumentRewriteDialogOpen(true)}
+              />
+            )}
             {!useWriteFileStreaming && filepath.endsWith(".skill") && (
               <Tooltip content={t.toolCalls.skillInstallTooltip}>
                 <ArtifactAction
@@ -723,7 +1262,7 @@ export function ArtifactFileDetail({
                 tooltip={t.clipboard.copyToClipboard}
               />
             )}
-            {language === "markdown" && (
+            {language === "markdown" && !onDownloadClick && (
               <ArtifactAction
                 icon={isExportingWord ? LoaderIcon : FileType2Icon}
                 label="另存为 Word"
@@ -746,6 +1285,10 @@ export function ArtifactFileDetail({
               label={t.common.download}
               tooltip={t.common.download}
               onClick={async () => {
+                if (onDownloadClick) {
+                  onDownloadClick();
+                  return;
+                }
                 if (useWriteFileStreaming) {
                   handleDownloadWriteFile();
                   return;
@@ -801,6 +1344,27 @@ export function ArtifactFileDetail({
             正在改写 Markdown
           </div>
         )}
+        {documentRewriteActive && (
+          <div className="absolute right-4 bottom-4 z-20 inline-flex items-center gap-2 rounded-full border border-[#d8b878] bg-[#fff3cf]/95 px-3 py-1.5 text-xs text-[#6d5625] shadow-sm">
+            <LoaderIcon className="size-3.5 animate-spin" />
+            {documentRewrite.run.stage === "requirements"
+              ? "正在理解改写需求，原文件未被修改"
+              : documentRewrite.run.stage === "validation"
+              ? "正在校验 Markdown"
+              : documentRewrite.run.stage === "committing"
+                ? "正在安全替换原文件"
+                : "正在写入临时草稿 · " +
+                  documentRewrite.run.writtenCharCount.toLocaleString() +
+                  " 字"}
+            <button
+              type="button"
+              className="ml-1 rounded px-1.5 py-0.5 font-medium hover:bg-[#ead9a6]"
+              onClick={handleCancelDocumentRewrite}
+            >
+              停止
+            </button>
+          </div>
+        )}
         {showResumeAutoScroll && (
           <button
             type="button"
@@ -811,7 +1375,7 @@ export function ArtifactFileDetail({
             滑动到底部并继续自动下滑
           </button>
         )}
-        {viewMode === "edit" && canUseAiEditor && (
+        {viewMode === "edit" && canUseAiEditor && !documentRewriteActive && (
           <MarkdownAiEditor
             // 编辑用原始内容（与源码模式一致，不脱敏）；保存仍走头部「保存 Markdown」按钮。
             markdown={displayContent ?? ""}
@@ -845,9 +1409,9 @@ export function ArtifactFileDetail({
                   ? (displayContent ?? "")
                   : desensitize(displayContent ?? "")
               }
-              readonly={!canEditArtifact}
+              readonly={!canEditArtifact || documentRewriteActive}
               onChange={
-                canEditArtifact
+                canEditArtifact && !documentRewriteActive
                   ? (value) => {
                       setDraftContent(value);
                       setHasLocalEdits(true);
@@ -885,6 +1449,13 @@ export function ArtifactFileDetail({
         threadId={threadId}
         filepath={filepath}
       />
+      <DocumentRewriteDialog
+        open={documentRewriteDialogOpen}
+        onOpenChange={setDocumentRewriteDialogOpen}
+        fileName={getFileName(filepath)}
+        charCount={(displayContent ?? "").replace(/\s/g, "").length}
+        onStart={handleStartDocumentRewrite}
+      />
     </Artifact>
   );
 }

frontend-web/src/components/workspace/artifacts/artifact-file-list.tsx

@@ -28,11 +28,14 @@ export function ArtifactFileList({
   files,
   threadId,
   onOpenArtifact,
+  onDownloadArtifact,
 }: {
   className?: string;
   files: string[];
   threadId: string;
   onOpenArtifact?: (filepath: string) => void;
+  /** Optional host download action for virtual/session-owned artifacts. */
+  onDownloadArtifact?: (filepath: string) => void | Promise<void>;
 }) {
   const { t } = useI18n();
   const { isMock, publicShareCode } = useThread();
@@ -68,7 +71,11 @@ export function ArtifactFileList({
       if (downloadingFile) return;
       setDownloadingFile(filepath);
       try {
+        if (onDownloadArtifact) {
+          await onDownloadArtifact(filepath);
+        } else {
           await downloadArtifactFile({ filepath, threadId, isMock, publicShareCode });
+        }
       } catch (error) {
         console.error(error);
         toast.error(
@@ -78,7 +85,7 @@ export function ArtifactFileList({
         setDownloadingFile(null);
       }
     },
-    [threadId, isMock, publicShareCode, downloadingFile],
+    [threadId, isMock, publicShareCode, downloadingFile, onDownloadArtifact],
   );
 
   return (

frontend-web/src/components/workspace/artifacts/context.tsx

@@ -2,6 +2,7 @@ import {
   createContext,
   useCallback,
   useContext,
+  useRef,
   useState,
   type ReactNode,
 } from "react";
@@ -9,13 +10,33 @@ import {
 import { useSidebarSafe } from "@/components/ui/sidebar";
 import { env } from "@/env";
 
+export function artifactPreviewKey(artifact: string): string {
+  if (!artifact.startsWith("write-file:")) {
+    return artifact.trim();
+  }
+  try {
+    const url = new URL(artifact);
+    const messageId = url.searchParams.get("message_id");
+    const toolCallId = url.searchParams.get("tool_call_id");
+    if (messageId && toolCallId) {
+      return `${messageId}:${toolCallId}`;
+    }
+  } catch {
+    // Fall back to the complete value for malformed legacy virtual URLs.
+  }
+  return artifact;
+}
+
 export interface ArtifactsContextType {
   artifacts: string[];
   setArtifacts: (artifacts: string[]) => void;
 
   selectedArtifact: string | null;
+  selectedArtifactKey: string | null;
   autoSelect: boolean;
   select: (artifact: string, autoSelect?: boolean) => void;
+  /** Open/update a streamed write without overriding a manual close of that call. */
+  openStreamedArtifact: (artifact: string, previewKey: string) => boolean;
   deselect: () => void;
 
   open: boolean;
@@ -37,16 +58,19 @@ export function ArtifactsProvider({ children }: ArtifactsProviderProps) {
     setArtifactsState(Array.isArray(next) ? next : []);
   }, []);
   const [selectedArtifact, setSelectedArtifact] = useState<string | null>(null);
+  const [selectedArtifactKey, setSelectedArtifactKey] = useState<string | null>(null);
   const [autoSelect, setAutoSelect] = useState(true);
-  const [open, setOpen] = useState(
+  const [open, setOpenState] = useState(
     env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true",
   );
   const [autoOpen, setAutoOpen] = useState(true);
+  const suppressedAutoOpenKeyRef = useRef<string | null>(null);
   const sidebar = useSidebarSafe();
 
   const select = useCallback(
     (artifact: string, autoSelect = false) => {
       setSelectedArtifact(artifact);
+      setSelectedArtifactKey(artifactPreviewKey(artifact));
       if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY !== "true") {
         sidebar?.setOpen(false);
       }
@@ -54,13 +78,33 @@ export function ArtifactsProvider({ children }: ArtifactsProviderProps) {
         setAutoSelect(false);
       }
     },
-    [sidebar, setSelectedArtifact, setAutoSelect],
+    [sidebar],
+  );
+
+  const openStreamedArtifact = useCallback(
+    (artifact: string, previewKey: string) => {
+      if (suppressedAutoOpenKeyRef.current === previewKey) {
+        return false;
+      }
+      setSelectedArtifact(artifact);
+      setSelectedArtifactKey(previewKey);
+      setAutoSelect(true);
+      setAutoOpen(true);
+      setOpenState(true);
+      if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY !== "true") {
+        sidebar?.setOpen(false);
+      }
+      return true;
+    },
+    [sidebar],
   );
 
   const deselect = useCallback(() => {
     setSelectedArtifact(null);
+    setSelectedArtifactKey(null);
     setAutoSelect(true);
-    setOpen(false);
+    setOpenState(false);
+    suppressedAutoOpenKeyRef.current = null;
   }, []);
 
   const value: ArtifactsContextType = {
@@ -75,11 +119,16 @@ export function ArtifactsProvider({ children }: ArtifactsProviderProps) {
         setAutoOpen(false);
         setAutoSelect(false);
       }
-      setOpen(isOpen);
+      if (!isOpen) {
+        suppressedAutoOpenKeyRef.current = selectedArtifactKey;
+      }
+      setOpenState(isOpen);
     },
 
     selectedArtifact,
+    selectedArtifactKey,
     select,
+    openStreamedArtifact,
     deselect,
   };
 

frontend-web/src/components/workspace/artifacts/document-rewrite-dialog.tsx

@@ -0,0 +1,157 @@
+"use client";
+
+import { SparklesIcon } from "lucide-react";
+import { useEffect, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Textarea } from "@/components/ui/textarea";
+import { ModelNameSelect } from "@/components/workspace/model-name-select";
+import type { DocumentRewriteStyle } from "@/open-canvas/api/rewrite";
+
+const STYLE_OPTIONS: { value: DocumentRewriteStyle; label: string; description: string }[] = [
+  {
+    value: "formal_analysis",
+    label: "正式分析",
+    description: "客观、严谨，适合报告与研究材料。",
+  },
+  {
+    value: "professional",
+    label: "专业正式",
+    description: "适合业务文档和说明材料。",
+  },
+  {
+    value: "concise",
+    label: "精炼简洁",
+    description: "减少重复，保留核心信息。",
+  },
+  {
+    value: "readable",
+    label: "清晰易读",
+    description: "优化段落衔接和阅读节奏。",
+  },
+];
+
+export function DocumentRewriteDialog({
+  open,
+  onOpenChange,
+  fileName,
+  charCount,
+  onStart,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  fileName: string;
+  charCount: number;
+  onStart: (input: {
+    instruction: string;
+    style: DocumentRewriteStyle;
+    modelName: string | null;
+  }) => void;
+}) {
+  const [instruction, setInstruction] = useState(
+    "统一表达风格，减少重复内容，改善段落衔接；不新增原文没有依据的事实。",
+  );
+  const [style, setStyle] = useState<DocumentRewriteStyle>("formal_analysis");
+  const [modelName, setModelName] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    setStyle("formal_analysis");
+    setModelName(null);
+  }, [open]);
+
+  const selectedStyle = STYLE_OPTIONS.find((item) => item.value === style);
+  const canStart = instruction.trim().length > 0;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-xl">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <SparklesIcon className="size-5 text-primary" />
+            AI 全文改写
+          </DialogTitle>
+          <DialogDescription>
+            将以当前文件快照生成临时草稿。校验通过前不会覆盖原 Markdown。
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="rounded-lg border bg-muted/35 px-3 py-2.5 text-sm">
+          <div className="font-medium">{fileName}</div>
+          <div className="text-muted-foreground mt-1">原文约 {charCount.toLocaleString()} 字</div>
+        </div>
+
+        <label className="grid gap-2 text-sm font-medium">
+          改写要求
+          <Textarea
+            value={instruction}
+            onChange={(event) => setInstruction(event.target.value)}
+            placeholder="例如：统一为正式行业分析语气，减少重复，不新增外部事实。"
+            rows={4}
+          />
+        </label>
+
+        <div className="grid gap-4 sm:grid-cols-2">
+          <label className="grid gap-2 text-sm font-medium">
+            改写风格
+            <Select value={style} onValueChange={(value) => setStyle(value as DocumentRewriteStyle)}>
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {STYLE_OPTIONS.map((item) => (
+                  <SelectItem key={item.value} value={item.value}>
+                    {item.label}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            <span className="text-muted-foreground text-xs">{selectedStyle?.description}</span>
+          </label>
+
+          <label className="grid gap-2 text-sm font-medium">
+            模型
+            <ModelNameSelect
+              value={modelName}
+              onChange={setModelName}
+              triggerClassName="h-10 text-sm"
+              defaultLabel="系统默认模型"
+            />
+            <span className="text-muted-foreground text-xs">仅影响本次全文改写。</span>
+          </label>
+        </div>
+
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>
+            取消
+          </Button>
+          <Button
+            disabled={!canStart}
+            onClick={() => {
+              if (!canStart) return;
+              onStart({ instruction: instruction.trim(), style, modelName });
+            }}
+          >
+            <SparklesIcon />
+            开始改写
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend-web/src/components/workspace/chats/chat-box.tsx

@@ -15,6 +15,8 @@ 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 { isSingleRoundRagMessage } from "@/core/threads/use-single-round-rag";
+import { isMultiRoundRagMessage } from "@/core/threads/use-multi-round-rag";
 import { useSkills } from "@/core/skills/hooks";
 import type { SkillDisplayConfig } from "@/core/skills/type";
 import {
@@ -92,6 +94,20 @@ const ChatBox: React.FC<{
   const [settings] = useLocalSettings();
   const ragModeEnabled =
     settings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
+  // Frontend RAG modes write their own hidden source tool messages. They use
+  // the existing reference panel, but must not request or write reference
+  // batches through DeerFlow's backend APIs.
+  const hasFrontendRag = useMemo(
+    () =>
+      (thread.values.messages ?? []).some(
+        (message) =>
+          isSingleRoundRagMessage(message) || isMultiRoundRagMessage(message),
+      ),
+    [thread.values.messages],
+  );
+  const referencesEnabled = ragModeEnabled || hasFrontendRag;
+  const shouldFetchBackendReferenceBatches =
+    referencesEnabled && !hasFrontendRag;
   const { skills } = useSkills();
 
   const {
@@ -102,15 +118,16 @@ const ChatBox: React.FC<{
     select: selectArtifact,
     deselect,
     selectedArtifact,
+    selectedArtifactKey,
   } = useArtifacts();
 
   const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true);
   const skillDisplayMap = useMemo(
-    () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    () => (referencesEnabled ? buildSkillDisplayMap(skills) : new Map()),
-    [ragModeEnabled, skills],
+    [referencesEnabled, skills],
   );
   const fallbackReferenceBatches = useMemo(() => {
-    if (!ragModeEnabled) {
+    if (!referencesEnabled) {
       return [];
     }
     return buildTurnReferenceBatches(
@@ -118,9 +135,9 @@ const ChatBox: React.FC<{
       skillDisplayMap,
       thread.isLoading,
     );
-  }, [ragModeEnabled, skillDisplayMap, thread.isLoading, thread.values.messages]);
+  }, [referencesEnabled, skillDisplayMap, thread.isLoading, thread.values.messages]);
   useEffect(() => {
-    if (!ragModeEnabled) {
+    if (!shouldFetchBackendReferenceBatches) {
       setBackendReferenceBatches([]);
       return;
     }
@@ -156,7 +173,12 @@ const ChatBox: React.FC<{
         }
       });
     return () => controller.abort();
-  }, [ragModeEnabled, thread.isLoading, threadId, thread.values.messages]);
+  }, [
+    shouldFetchBackendReferenceBatches,
+    thread.isLoading,
+    threadId,
+    thread.values.messages,
+  ]);
   const adaptedBackendReferenceBatches = useMemo(
     () =>
       adaptBackendReferenceBatches(
@@ -167,15 +189,22 @@ const ChatBox: React.FC<{
   );
   const referenceBatches = useMemo(
     () => {
-      if (adaptedBackendReferenceBatches.length > 0) {
+      if (
+        shouldFetchBackendReferenceBatches &&
+        adaptedBackendReferenceBatches.length > 0
+      ) {
         return adaptedBackendReferenceBatches;
       }
       return fallbackReferenceBatches;
     },
-    [adaptedBackendReferenceBatches, fallbackReferenceBatches],
+    [
+      adaptedBackendReferenceBatches,
+      fallbackReferenceBatches,
+      shouldFetchBackendReferenceBatches,
+    ],
   );
   useEffect(() => {
-    if (!ragModeEnabled) {
+    if (!shouldFetchBackendReferenceBatches) {
       return;
     }
     const signature = JSON.stringify({
@@ -202,7 +231,14 @@ const ChatBox: React.FC<{
       fallbackBatches: debugReferenceBatches(fallbackReferenceBatches),
       finalBatches: debugReferenceBatches(referenceBatches),
     });
-  }, [adaptedBackendReferenceBatches, backendReferenceBatches, fallbackReferenceBatches, ragModeEnabled, referenceBatches, threadId]);
+  }, [
+    adaptedBackendReferenceBatches,
+    backendReferenceBatches,
+    fallbackReferenceBatches,
+    referenceBatches,
+    shouldFetchBackendReferenceBatches,
+    threadId,
+  ]);
   const latestReferenceBatch =
     referenceBatches.length > 0
       ? referenceBatches[referenceBatches.length - 1]!
@@ -213,7 +249,7 @@ const ChatBox: React.FC<{
   const referenceSources = activeReferenceBatch?.sources ?? [];
   const hasCitationReferences = referenceSources.length > 0;
   useEffect(() => {
-    if (!ragModeEnabled || !activeReferenceBatch) {
+    if (!shouldFetchBackendReferenceBatches || !activeReferenceBatch) {
       return;
     }
     logReferenceDebug("frontend-active-reference-batch-payload", threadId, {
@@ -222,7 +258,7 @@ const ChatBox: React.FC<{
       sourceCount: activeReferenceBatch.sources.length,
       sources: activeReferenceBatch.sources.map(debugReferenceSource),
     });
-  }, [activeReferenceBatch, ragModeEnabled, threadId]);
+  }, [activeReferenceBatch, shouldFetchBackendReferenceBatches, threadId]);
   useEffect(() => {
     if (hasCitationReferences) {
       setReferencesOpen(true);
@@ -420,6 +456,7 @@ const ChatBox: React.FC<{
               </div>
               <TabsContent value="document" className="min-h-0 flex-1 overflow-hidden p-0">
                 <ArtifactFileDetail
+                  key={selectedArtifactKey ?? selectedArtifact}
                   className="size-full"
                   filepath={selectedArtifact}
                   threadId={threadId}
@@ -435,6 +472,7 @@ const ChatBox: React.FC<{
             </Tabs>
           ) : selectedArtifact ? (
             <ArtifactFileDetail
+              key={selectedArtifactKey ?? selectedArtifact}
               className="size-full"
               filepath={selectedArtifact}
               threadId={threadId}

frontend-web/src/components/workspace/citations/citation-link.tsx

@@ -8,8 +8,13 @@ export function CitationLink({
   href,
   children,
   className,
+  onReferenceClick,
+  onClick,
   ...props
-}: ComponentProps<"a">) {
+}: ComponentProps<"a"> & {
+  /** Lets a message renderer show an in-place source preview instead of scrolling. */
+  onReferenceClick?: (referenceId: string) => void;
+}) {
   const childrenText = normalizeCitationText(children);
   const displayText = childrenText ?? "";
   const referenceId = href?.startsWith("#reference-")
@@ -28,6 +33,11 @@ export function CitationLink({
         )}
         onClick={(event) => {
           event.preventDefault();
+          if (onReferenceClick) {
+            onReferenceClick(referenceId);
+            onClick?.(event);
+            return;
+          }
           const batchId =
             event.currentTarget.closest<HTMLElement>("[data-reference-batch-id]")
               ?.dataset.referenceBatchId;
@@ -41,6 +51,7 @@ export function CitationLink({
             target?.scrollIntoView({ behavior: "smooth", block: "center" });
           };
           window.setTimeout(scroll, 240);
+          onClick?.(event);
         }}
         {...props}
       >
@@ -58,6 +69,7 @@ export function CitationLink({
         "text-primary decoration-primary/30 hover:decoration-primary/60 underline underline-offset-2 transition-colors",
         className,
       )}
+      onClick={onClick}
       {...props}
     >
       {displayText || children}

frontend-web/src/components/workspace/general-qa-sidebar.tsx

@@ -83,6 +83,7 @@ import {
   sortThreadsPinnedFirst,
   titleOfThread,
 } from "@/core/threads/utils";
+import { buildFullChatNavigationPath } from "@/core/page-layout/chats-iframe-route";
 import { env } from "@/env";
 import { desensitize } from "@/lib/desensitize";
 import { isIMEComposing } from "@/lib/ime";
@@ -185,15 +186,24 @@ export function GeneralQaSidebar() {
   // 当前嵌入的智能体（URL 上的 ?agent=）：用于高亮对应卡片。
   const searchParams = useSearchParams();
   const activeAgentId = searchParams.get("agent");
+  const currentSearch = searchParams.toString();
+  const newChatHref = buildFullChatNavigationPath(NEW_CHAT_PATH, currentSearch);
+  const moreAgentsHref = buildFullChatNavigationPath(MORE_AGENTS_HREF, currentSearch);
+  const moreChatsHref = buildFullChatNavigationPath(MORE_CHATS_HREF, currentSearch);
 
   // 点击常用智能体 = 在通用问答右侧**原地嵌入**该智能体的对话页：停留在 /chats/new，
   // 仅给 URL 加 ?agent=<id>，由 NewChatContent 把右侧问答区换成 AgentChatPage。
   // 不跳转独立页面、左侧栏不变。每次点击都重开一个干净会话（NewChatContent 的 key）。
   const handleSelectAgent = useCallback(
     (agentId: string) => {
-      navigate(`/page/workspace/chats/new?agent=${encodeURIComponent(agentId)}`);
+      navigate(
+        buildFullChatNavigationPath(
+          `${NEW_CHAT_PATH}?agent=${encodeURIComponent(agentId)}`,
+          currentSearch,
+        ),
+      );
     },
-    [navigate],
+    [currentSearch, navigate],
   );
 
   // ── 最近的对话取数 + 搜索 ──
@@ -241,7 +251,7 @@ export function GeneralQaSidebar() {
   const handleNewChatClick = (event: React.MouseEvent<HTMLAnchorElement>) => {
     if (event.metaKey || event.ctrlKey || event.shiftKey || event.button === 1) return;
     event.preventDefault();
-    navigate(NEW_CHAT_PATH, { replace: true, state: { resetAt: Date.now() } });
+    navigate(newChatHref, { replace: true, state: { resetAt: Date.now() } });
   };
 
   const handleDelete = useCallback(
@@ -257,10 +267,17 @@ export function GeneralQaSidebar() {
             nextThreadPath = listPathOfThread(threads[threadIndex - 1]!);
           }
         }
-        void router.push(nextThreadPath);
+        void router.push(buildFullChatNavigationPath(nextThreadPath, currentSearch));
       }
     },
-    [agentIdFromPath, deleteThread, router, threadIdFromPath, threads],
+    [
+      agentIdFromPath,
+      currentSearch,
+      deleteThread,
+      router,
+      threadIdFromPath,
+      threads,
+    ],
   );
 
   const handleRenameClick = useCallback((threadId: string, currentTitle: string) => {
@@ -314,7 +331,7 @@ export function GeneralQaSidebar() {
             底色用「主色混入透明」=主色低透明度叠在当前侧栏底色上，浅/红/蓝/深蓝主题都自适应
             （不要混 white，否则深蓝主题下会变成浅色块）。 */}
         <Link
-          href={NEW_CHAT_PATH}
+          href={newChatHref}
           onClick={handleNewChatClick}
           style={{ borderColor: "var(--primary)", color: "var(--primary)" }}
           className={cn(
@@ -415,7 +432,7 @@ export function GeneralQaSidebar() {
                   );
                 })}
                 <Link
-                  href={MORE_AGENTS_HREF}
+                  href={moreAgentsHref}
                   className="flex items-center justify-between rounded-lg px-3 py-1.5 text-[12px] text-muted-foreground/70 transition-colors hover:bg-accent/50 hover:text-foreground"
                 >
                   <span>{t.common.more}</span>
@@ -454,7 +471,10 @@ export function GeneralQaSidebar() {
                   </div>
                 ) : (
                   filteredThreads.map((thread) => {
-                    const href = listPathOfThread(thread);
+                    const href = buildFullChatNavigationPath(
+                      listPathOfThread(thread),
+                      currentSearch,
+                    );
                     const isActive = href === pathname;
                     const isBoot = isBootstrapThread(thread);
                     const pinned = isThreadPinned(thread);
@@ -576,7 +596,7 @@ export function GeneralQaSidebar() {
                 )}
                 {!query && (
                   <Link
-                    href={MORE_CHATS_HREF}
+                    href={moreChatsHref}
                     className="mt-0.5 flex items-center justify-between rounded-lg px-3 py-1.5 text-[12px] text-muted-foreground/70 transition-colors hover:bg-accent/50 hover:text-foreground"
                   >
                     <span>更多最近对话</span>

frontend-web/src/components/workspace/input-box.tsx

@@ -24,6 +24,7 @@ import {
   useRef,
   useState,
   type ComponentProps,
+  type ReactNode,
 } from "react";
 
 import {
@@ -64,6 +65,7 @@ import { getBackendBaseURL } from "@/core/config";
 import { useI18n } from "@/core/i18n/hooks";
 import { isHiddenFromUIMessage } from "@/core/messages/utils";
 import { useModels } from "@/core/models/hooks";
+import type { Model } from "@/core/models/types";
 import type { AgentThreadContext } from "@/core/threads";
 import { textOfMessage } from "@/core/threads/utils";
 import { desensitize } from "@/lib/desensitize";
@@ -134,6 +136,8 @@ export function InputBox({
   onStop,
   promptPrefix,
   agentSelector,
+  knowledgeSelector,
+  extraModels = [],
   assistantId,
   hideAdminRecommendedQuestions,
   compact,
@@ -194,12 +198,24 @@ export function InputBox({
     selectedAgentId: string | null;
     onAgentChange: (agentId: string | null) => void;
   };
+  /** WeKnora-style knowledge-space picker rendered inside the composer toolbar. */
+  knowledgeSelector?: ReactNode;
+  /** Page-scoped model choices implemented outside the DeerFlow model API. */
+  extraModels?: Model[];
 }) {
   const { t } = useI18n();
   const [localSettings, setLocalSettings] = useLocalSettings();
   const searchParams = useSearchParams();
   const [modelDialogOpen, setModelDialogOpen] = useState(false);
   const { models } = useModels();
+  const singleRoundRagActive =
+    context.execution_profile === "single_round_rag";
+  const multiRoundRagActive =
+    context.execution_profile === "multi_round_rag";
+  const frontendRagActive = singleRoundRagActive || multiRoundRagActive;
+  const modelOptions = useMemo(() => {
+    return singleRoundRagActive ? extraModels : models;
+  }, [extraModels, models, singleRoundRagActive]);
   const { thread, isMock } = useThread();
   const { textInput } = usePromptInputController();
   const promptRootRef = useRef<HTMLDivElement | null>(null);
@@ -223,16 +239,25 @@ export function InputBox({
     recommendedQuestions.length > 0;
 
   useEffect(() => {
-    if (models.length === 0) {
+    // Multi-round RAG is a frontend execution profile, not a model option.
+    // Do not let the normal model fallback clear it on every render.
+    if (multiRoundRagActive) {
       return;
     }
-    const currentModel = models.find((m) => m.name === context.model_name);
+    if (modelOptions.length === 0) {
-    const fallbackModel = currentModel ?? models[0]!;
+      return;
+    }
+    const currentModel = modelOptions.find((m) => m.name === context.model_name);
+    const fallbackModel = currentModel ?? modelOptions[0]!;
     const supportsThinking = fallbackModel.supports_thinking ?? false;
     const nextModelName = fallbackModel.name;
     const nextMode = getResolvedMode(context.mode, supportsThinking);
 
-    if (context.model_name === nextModelName && context.mode === nextMode) {
+    if (
+      context.model_name === nextModelName &&
+      context.mode === nextMode &&
+      context.execution_profile === fallbackModel.execution_profile
+    ) {
       return;
     }
 
@@ -240,17 +265,19 @@ export function InputBox({
       ...context,
       model_name: nextModelName,
       mode: nextMode,
+      execution_profile: fallbackModel.execution_profile,
     });
-  }, [context, models, onContextChange]);
+  }, [context, modelOptions, multiRoundRagActive, onContextChange]);
 
   const selectedModel = useMemo(() => {
-    if (models.length === 0) {
+    if (modelOptions.length === 0) {
       return undefined;
     }
-    return models.find((m) => m.name === context.model_name) ?? models[0];
+    return modelOptions.find((m) => m.name === context.model_name) ?? modelOptions[0];
-  }, [context.model_name, models]);
+  }, [context.model_name, modelOptions]);
 
   const resolvedModelName = selectedModel?.name;
+  const selectedSingleRoundRag = singleRoundRagActive;
 
   const supportThinking = useMemo(
     () => selectedModel?.supports_thinking ?? false,
@@ -264,7 +291,7 @@ export function InputBox({
 
   const handleModelSelect = useCallback(
     (model_name: string) => {
-      const model = models.find((m) => m.name === model_name);
+      const model = modelOptions.find((m) => m.name === model_name);
       if (!model) {
         return;
       }
@@ -273,17 +300,24 @@ export function InputBox({
         model_name,
         mode: getResolvedMode(context.mode, model.supports_thinking ?? false),
         reasoning_effort: context.reasoning_effort,
+        execution_profile: model.execution_profile,
       });
       setModelDialogOpen(false);
     },
-    [onContextChange, context, models],
+    [onContextChange, context, modelOptions],
   );
 
   const handleModeSelect = useCallback(
     (mode: InputMode) => {
+      const ordinaryModel =
+        models.find((model) => model.name === context.model_name) ?? models[0];
       onContextChange?.({
         ...context,
-        mode: getResolvedMode(mode, supportThinking),
+        model_name: ordinaryModel?.name ?? context.model_name,
+        mode: getResolvedMode(
+          mode,
+          ordinaryModel?.supports_thinking ?? supportThinking,
+        ),
         reasoning_effort:
           mode === "ultra"
             ? "high"
@@ -292,11 +326,38 @@ export function InputBox({
               : mode === "thinking"
                 ? "low"
                 : "minimal",
+        execution_profile: undefined,
       });
     },
-    [onContextChange, context, supportThinking],
+    [onContextChange, context, models, supportThinking],
   );
 
+  const handleSingleRoundRagSelect = useCallback(() => {
+    const ragModel =
+      extraModels.find((model) => model.name === context.model_name) ??
+      extraModels[0];
+    if (!ragModel) {
+      return;
+    }
+
+    onContextChange?.({
+      ...context,
+      model_name: ragModel.name,
+      mode: getResolvedMode(
+        context.mode,
+        ragModel.supports_thinking ?? false,
+      ),
+      execution_profile: "single_round_rag",
+    });
+  }, [context, extraModels, onContextChange]);
+
+  const handleMultiRoundRagSelect = useCallback(() => {
+    onContextChange?.({
+      ...context,
+      execution_profile: "multi_round_rag",
+    });
+  }, [context, onContextChange]);
+
   const handleReasoningEffortSelect = useCallback(
     (effort: "minimal" | "low" | "medium" | "high") => {
       onContextChange?.({
@@ -365,6 +426,7 @@ export function InputBox({
             context.mode,
             selectedModel?.supports_thinking ?? false,
           ),
+          execution_profile: selectedModel?.execution_profile,
         });
         setTimeout(() => onSubmit?.(message), 0);
         return;
@@ -380,6 +442,7 @@ export function InputBox({
       resolvedModelName,
       ragModeEnabled,
       selectedModel?.supports_thinking,
+      selectedModel?.execution_profile,
       status,
       threadId,
     ],
@@ -439,6 +502,7 @@ export function InputBox({
   const showFollowups =
     !disabled &&
     !isNewThread &&
+    !selectedSingleRoundRag &&
     !followupsHidden &&
     (followupsLoading || followups.length > 0);
 
@@ -464,7 +528,7 @@ export function InputBox({
       return;
     }
 
-    if (disabled || isMock) {
+    if (disabled || isMock || selectedSingleRoundRag) {
       return;
     }
 
@@ -526,7 +590,7 @@ export function InputBox({
       });
 
     return () => controller.abort();
-  }, [context.model_name, disabled, isMock, status, thread.messages, threadId]);
+  }, [context.model_name, disabled, isMock, selectedSingleRoundRag, status, thread.messages, threadId]);
 
   return (
     <div ref={promptRootRef} className="relative flex flex-col gap-6">
@@ -663,6 +727,7 @@ export function InputBox({
               />
             </PromptInputActionMenuContent>
           </PromptInputActionMenu> */}
+            {!frontendRagActive && (
               <AddAttachmentsButton
                 className={cn(
                   "rounded-full border-0 bg-transparent px-2.5! shadow-none text-muted-foreground hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100",
@@ -670,7 +735,8 @@ export function InputBox({
                     "gap-1.5! rounded-lg px-2.5! py-1! text-[11px] font-medium",
                 )}
               />
-            <Tooltip
+            )}
+            {!frontendRagActive && <Tooltip
               content={
                 context.writing_mode
                   ? "写作模式已开启：最终输出会强制保存为 Markdown 文件"
@@ -695,8 +761,8 @@ export function InputBox({
                 <FileTextIcon className="size-3" />
                 <span className="text-xs font-normal">写作</span>
               </PromptInputButton>
-            </Tooltip>
+            </Tooltip>}
-            <Tooltip
+            {!frontendRagActive && <Tooltip
               content={
                 memoryInjectionEnabled
                   ? "记忆注入已开启：对话前会注入历史记忆"
@@ -721,8 +787,8 @@ export function InputBox({
                 <BrainCircuitIcon className="size-3" />
                 <span className="text-xs font-normal">记忆</span>
               </PromptInputButton>
-            </Tooltip>
+            </Tooltip>}
-            <Tooltip
+            {!frontendRagActive && <Tooltip
               content={
                 ragModeEnabled
                   ? "参考文献模式已开启：检索类结果会按编号引用展示"
@@ -751,8 +817,8 @@ export function InputBox({
                 <BookMarkedIcon className="size-3" />
                 <span className="text-xs font-normal">参考文献</span>
               </PromptInputButton>
-            </Tooltip>
+            </Tooltip>}
-            <Tooltip
+            {!frontendRagActive && <Tooltip
               content={
                 contextCompressionEnabled
                   ? "上下文压缩已开启：超长对话会自动压缩历史以节省 token"
@@ -780,7 +846,7 @@ export function InputBox({
                 <ShrinkIcon className="size-3" />
                 <span className="text-xs font-normal">上下文压缩</span>
               </PromptInputButton>
-            </Tooltip>
+            </Tooltip>}
             <PromptInputActionMenu>
               <ModeHoverGuide
                 mode={
@@ -791,13 +857,22 @@ export function InputBox({
                     ? context.mode
                     : "flash"
                 }
+                tooltipContent={
+                  singleRoundRagActive
+                    ? "单轮 RAG 问答：基于知识库检索生成答案，并展示参考资料"
+                    : multiRoundRagActive
+                      ? "多轮 RAG 问答：多次检索并展示检索过程与参考资料"
+                      : undefined
+                }
               >
                 <PromptInputActionMenuTrigger
                   className={cn(
                     "gap-1.5! rounded-full border-0 bg-transparent px-3! text-muted-foreground shadow-none hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100",
                     compact && "rounded-lg border px-2.5! py-1! text-[11px] font-medium",
                     compact &&
-                      (context.mode === "thinking"
+                      (frontendRagActive
+                        ? "border-emerald-200 bg-emerald-50/60 text-emerald-700 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-950/40 dark:text-emerald-200"
+                        : context.mode === "thinking"
                         ? "border-indigo-200 bg-indigo-50/60 text-indigo-700 hover:bg-indigo-100 dark:border-indigo-700 dark:bg-indigo-950/40 dark:text-indigo-200"
                         : context.mode === "pro"
                           ? "border-violet-200 bg-violet-50/60 text-violet-700 hover:bg-violet-100 dark:border-violet-700 dark:bg-violet-950/40 dark:text-violet-200"
@@ -807,16 +882,17 @@ export function InputBox({
                   )}
                   >
                     <div>
-                    {context.mode === "flash" && <ZapIcon className="size-3" />}
+                    {frontendRagActive ? (
-                    {context.mode === "thinking" && (
+                      <BookMarkedIcon className="size-3" />
+                    ) : context.mode === "flash" ? (
+                      <ZapIcon className="size-3" />
+                    ) : context.mode === "thinking" ? (
                       <LightbulbIcon className="size-3" />
-                    )}
+                    ) : context.mode === "pro" ? (
-                    {context.mode === "pro" && (
                       <GraduationCapIcon className="size-3" />
-                    )}
+                    ) : context.mode === "ultra" ? (
-                    {context.mode === "ultra" && (
                       <RocketIcon className="size-3 text-[#dabb5e]" />
-                    )}
+                    ) : null}
                     </div>
                   <div
                     className={cn(
@@ -824,7 +900,11 @@ export function InputBox({
                       context.mode === "ultra" ? "golden-text" : "",
                     )}
                   >
-                    {(context.mode === "flash" && t.inputBox.flashMode) ||
+                    {frontendRagActive
+                      ? multiRoundRagActive
+                        ? "多轮 RAG"
+                        : "单轮 RAG"
+                      : (context.mode === "flash" && t.inputBox.flashMode) ||
                       (context.mode === "thinking" &&
                         t.inputBox.reasoningMode) ||
                       (context.mode === "pro" && t.inputBox.proMode) ||
@@ -840,7 +920,7 @@ export function InputBox({
                   <PromptInputActionMenu>
                     <PromptInputActionMenuItem
                       className={cn(
-                        context.mode === "flash"
+                        !frontendRagActive && context.mode === "flash"
                           ? "text-accent-foreground"
                           : "text-muted-foreground/65",
                       )}
@@ -851,7 +931,7 @@ export function InputBox({
                           <ZapIcon
                             className={cn(
                               "mr-2 size-4",
-                              context.mode === "flash" &&
+                              !frontendRagActive && context.mode === "flash" &&
                                 "text-accent-foreground",
                             )}
                           />
@@ -861,7 +941,7 @@ export function InputBox({
                           {t.inputBox.flashModeDescription}
                         </div>
                       </div>
-                      {context.mode === "flash" ? (
+                      {!frontendRagActive && context.mode === "flash" ? (
                         <CheckIcon className="ml-auto size-4" />
                       ) : (
                         <div className="ml-auto size-4" />
@@ -870,7 +950,7 @@ export function InputBox({
                     {supportThinking && (
                       <PromptInputActionMenuItem
                         className={cn(
-                          context.mode === "thinking"
+                          !frontendRagActive && context.mode === "thinking"
                             ? "text-accent-foreground"
                             : "text-muted-foreground/65",
                         )}
@@ -881,7 +961,7 @@ export function InputBox({
                             <LightbulbIcon
                               className={cn(
                                 "mr-2 size-4",
-                                context.mode === "thinking" &&
+                                !frontendRagActive && context.mode === "thinking" &&
                                   "text-accent-foreground",
                               )}
                             />
@@ -891,7 +971,7 @@ export function InputBox({
                             {t.inputBox.reasoningModeDescription}
                           </div>
                         </div>
-                        {context.mode === "thinking" ? (
+                        {!frontendRagActive && context.mode === "thinking" ? (
                           <CheckIcon className="ml-auto size-4" />
                         ) : (
                           <div className="ml-auto size-4" />
@@ -900,7 +980,7 @@ export function InputBox({
                     )}
                     <PromptInputActionMenuItem
                       className={cn(
-                        context.mode === "pro"
+                        !frontendRagActive && context.mode === "pro"
                           ? "text-accent-foreground"
                           : "text-muted-foreground/65",
                       )}
@@ -911,7 +991,7 @@ export function InputBox({
                           <GraduationCapIcon
                             className={cn(
                               "mr-2 size-4",
-                              context.mode === "pro" &&
+                              !frontendRagActive && context.mode === "pro" &&
                                 "text-accent-foreground",
                             )}
                           />
@@ -921,7 +1001,7 @@ export function InputBox({
                           {t.inputBox.proModeDescription}
                         </div>
                       </div>
-                      {context.mode === "pro" ? (
+                      {!frontendRagActive && context.mode === "pro" ? (
                         <CheckIcon className="ml-auto size-4" />
                       ) : (
                         <div className="ml-auto size-4" />
@@ -929,7 +1009,7 @@ export function InputBox({
                     </PromptInputActionMenuItem>
                     <PromptInputActionMenuItem
                       className={cn(
-                        context.mode === "ultra"
+                        !frontendRagActive && context.mode === "ultra"
                           ? "text-accent-foreground"
                           : "text-muted-foreground/65",
                       )}
@@ -940,12 +1020,16 @@ export function InputBox({
                           <RocketIcon
                             className={cn(
                               "mr-2 size-4",
-                              context.mode === "ultra" && "text-[#dabb5e]",
+                              !frontendRagActive &&
+                                context.mode === "ultra" &&
+                                "text-[#dabb5e]",
                             )}
                           />
                           <div
                             className={cn(
-                              context.mode === "ultra" && "golden-text",
+                              !frontendRagActive &&
+                                context.mode === "ultra" &&
+                                "golden-text",
                             )}
                           >
                             {t.inputBox.ultraMode}
@@ -955,7 +1039,68 @@ export function InputBox({
                           {t.inputBox.ultraModeDescription}
                         </div>
                       </div>
-                      {context.mode === "ultra" ? (
+                      {!frontendRagActive && context.mode === "ultra" ? (
+                        <CheckIcon className="ml-auto size-4" />
+                      ) : (
+                        <div className="ml-auto size-4" />
+                      )}
+                    </PromptInputActionMenuItem>
+                    {extraModels.length > 0 && (
+                      <>
+                        <DropdownMenuSeparator className="my-2" />
+                        <PromptInputActionMenuItem
+                          className={cn(
+                            selectedSingleRoundRag
+                              ? "bg-emerald-50 text-emerald-800 hover:bg-emerald-100 focus:bg-emerald-100 dark:bg-emerald-950/40 dark:text-emerald-200 dark:hover:bg-emerald-950/60 dark:focus:bg-emerald-950/60"
+                              : "text-muted-foreground/65",
+                          )}
+                          onSelect={handleSingleRoundRagSelect}
+                        >
+                          <div className="flex flex-col gap-2">
+                            <div className="flex items-center gap-1 font-bold">
+                              <BookMarkedIcon
+                                className={cn(
+                                  "mr-2 size-4",
+                                  selectedSingleRoundRag && "text-emerald-700 dark:text-emerald-200",
+                                )}
+                              />
+                              单轮 RAG 问答
+                            </div>
+                            <div className="pl-7 text-xs">
+                              基于知识库检索生成答案，并展示思考内容与参考资料
+                            </div>
+                          </div>
+                          {selectedSingleRoundRag ? (
+                            <CheckIcon className="ml-auto size-4" />
+                          ) : (
+                            <div className="ml-auto size-4" />
+                          )}
+                        </PromptInputActionMenuItem>
+                      </>
+                    )}
+                    <PromptInputActionMenuItem
+                      className={cn(
+                        multiRoundRagActive
+                          ? "bg-emerald-50 text-emerald-800 hover:bg-emerald-100 focus:bg-emerald-100 dark:bg-emerald-950/40 dark:text-emerald-200 dark:hover:bg-emerald-950/60 dark:focus:bg-emerald-950/60"
+                          : "text-muted-foreground/65",
+                      )}
+                      onSelect={handleMultiRoundRagSelect}
+                    >
+                      <div className="flex flex-col gap-2">
+                        <div className="flex items-center gap-1 font-bold">
+                          <BookMarkedIcon
+                            className={cn(
+                              "mr-2 size-4",
+                              multiRoundRagActive && "text-emerald-700 dark:text-emerald-200",
+                            )}
+                          />
+                          多轮 RAG 问答
+                        </div>
+                        <div className="pl-7 text-xs">
+                          多次检索、展示过程与参考资料，适合复杂问题
+                        </div>
+                      </div>
+                      {multiRoundRagActive ? (
                         <CheckIcon className="ml-auto size-4" />
                       ) : (
                         <div className="ml-auto size-4" />
@@ -965,7 +1110,7 @@ export function InputBox({
                 </DropdownMenuGroup>
               </PromptInputActionMenuContent>
             </PromptInputActionMenu>
-            {supportReasoningEffort && context.mode !== "flash" && (
+            {!frontendRagActive && supportReasoningEffort && context.mode !== "flash" && (
               <PromptInputActionMenu>
                 <PromptInputActionMenuTrigger className={cn("gap-1.5! rounded-full border-0 bg-transparent px-3! text-muted-foreground shadow-none hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100", compact && "rounded-lg border border-border px-2.5! py-1! text-[13px]")}>
                   <div className="text-xs font-normal">
@@ -1083,7 +1228,7 @@ export function InputBox({
             )}
           </PromptInputTools>
           <PromptInputTools className={cn("gap-1.5", compact && "gap-2")}>
-            {agentSelector && (
+            {!frontendRagActive && agentSelector && (
               <AgentSelector
                 selectedAgentId={agentSelector.selectedAgentId}
                 onAgentChange={agentSelector.onAgentChange}
@@ -1091,7 +1236,8 @@ export function InputBox({
                 compact={compact}
               />
             )}
-            {promptPrefix && (
+            {!frontendRagActive && knowledgeSelector}
+            {!frontendRagActive && promptPrefix && (
               <Tooltip
                 content={
                   promptPrefix.on
@@ -1119,7 +1265,7 @@ export function InputBox({
                 </PromptInputButton>
               </Tooltip>
             )}
-            <ModelSelector
+            {!multiRoundRagActive && <ModelSelector
               open={modelDialogOpen}
               onOpenChange={setModelDialogOpen}
             >
@@ -1146,7 +1292,7 @@ export function InputBox({
               <ModelSelectorContent>
                 <ModelSelectorInput placeholder={t.inputBox.searchModels} />
                 <ModelSelectorList>
-                  {models.map((m) => (
+                  {modelOptions.map((m) => (
                     <ModelSelectorItem
                       key={m.name}
                       value={m.name}
@@ -1155,7 +1301,9 @@ export function InputBox({
                       <div className="flex min-w-0 flex-1 flex-col">
                         <ModelSelectorName>{m.display_name}</ModelSelectorName>
                         <span className="text-muted-foreground truncate text-[10px]">
-                          {m.model}
+                          {selectedSingleRoundRag
+                            ? `单轮知识库问答 · ${m.name}`
+                            : m.model}
                         </span>
                       </div>
                       {m.name === context.model_name ? (
@@ -1167,7 +1315,7 @@ export function InputBox({
                   ))}
                 </ModelSelectorList>
               </ModelSelectorContent>
-            </ModelSelector>
+            </ModelSelector>}
             <PromptInputSubmit
               className={cn(
                 "rounded-full border-border bg-background shadow-sm hover:bg-muted dark:bg-blue-500 dark:border-blue-500 dark:text-white dark:hover:bg-blue-400 dark:shadow-none",

frontend-web/src/components/workspace/llmwiki-knowledge-selector.tsx

@@ -0,0 +1,353 @@
+"use client";
+
+import {
+  Check,
+  Database,
+  Folder,
+  Globe2,
+  Loader2,
+  Search,
+} from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import {
+  type LlmWikiKnowledgeBase,
+  useAgentLlmWikiKnowledgeBases,
+  useLlmWikiKnowledgeBases,
+  useLlmWikiRuntime,
+} from "@/strategy-components/api/llmwiki";
+
+type SelectorSource = "all" | "agent";
+type SelectorVariant = "popover" | "panel";
+
+function groupRows(rows: LlmWikiKnowledgeBase[]) {
+  return [
+    {
+      key: "personal",
+      label: "我的知识空间",
+      rows: rows.filter((item) => item.publication_status !== "published" || item.is_owner),
+    },
+    {
+      key: "public",
+      label: "公共知识空间",
+      rows: rows.filter((item) => item.publication_status === "published" && !item.is_owner),
+    },
+  ].filter((group) => group.rows.length > 0);
+}
+
+function SpaceIcon({ item }: { item: LlmWikiKnowledgeBase }) {
+  return (
+    <span
+      className={cn(
+        "flex size-7 shrink-0 items-center justify-center rounded-md",
+        item.publication_status === "published"
+          ? "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400"
+          : "bg-primary/10 text-primary",
+      )}
+    >
+      {item.publication_status === "published" ? (
+        <Globe2 className="size-3.5" />
+      ) : (
+        <Folder className="size-3.5" />
+      )}
+    </span>
+  );
+}
+
+function SelectionContent({
+  rows,
+  value,
+  onChange,
+  search,
+  onSearchChange,
+  loading,
+  error,
+  source,
+  variant,
+}: {
+  rows: LlmWikiKnowledgeBase[];
+  value: string[];
+  onChange: (value: string[]) => void;
+  search: string;
+  onSearchChange: (value: string) => void;
+  loading: boolean;
+  error: unknown;
+  source: SelectorSource;
+  variant: SelectorVariant;
+}) {
+  const selected = useMemo(() => new Set(value), [value]);
+  const filtered = useMemo(() => {
+    const query = search.trim().toLocaleLowerCase();
+    if (!query) return rows;
+    return rows.filter((item) =>
+      `${item.name} ${item.description}`.toLocaleLowerCase().includes(query),
+    );
+  }, [rows, search]);
+  const groups = useMemo(() => groupRows(filtered), [filtered]);
+  const toggle = (id: string) => {
+    onChange(selected.has(id) ? value.filter((item) => item !== id) : [...value, id]);
+  };
+
+  return (
+    <>
+      <div className="border-b p-2.5">
+        <div className="relative">
+          <Search className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            value={search}
+            onChange={(event) => onSearchChange(event.target.value)}
+            onKeyDown={(event) => event.stopPropagation()}
+            placeholder="搜索知识空间"
+            className="h-8 bg-muted/40 pl-8 text-xs"
+          />
+        </div>
+      </div>
+
+      <div className={cn("overflow-y-auto p-1.5", variant === "popover" ? "max-h-64" : "max-h-80")}>
+        {loading ? (
+          <div className="flex h-28 items-center justify-center text-xs text-muted-foreground">
+            <Loader2 className="mr-2 size-4 animate-spin" />正在读取知识空间
+          </div>
+        ) : error ? (
+          <div className="m-2 rounded-lg border border-destructive/30 bg-destructive/5 p-3 text-xs text-destructive">
+            {error instanceof Error ? error.message : "知识空间读取失败"}
+          </div>
+        ) : groups.length === 0 ? (
+          <div className="flex h-28 items-center justify-center px-4 text-center text-xs text-muted-foreground">
+            {search
+              ? "没有匹配的知识空间"
+              : source === "agent"
+                ? "该智能体尚未绑定可用知识空间"
+                : "当前账号暂无可用知识空间"}
+          </div>
+        ) : (
+          groups.map((group, groupIndex) => (
+            <div key={group.key}>
+              {groupIndex > 0 && (
+                variant === "popover"
+                  ? <DropdownMenuSeparator className="my-1.5" />
+                  : <div className="my-1.5 border-t" />
+              )}
+              {variant === "popover" ? (
+                <DropdownMenuLabel className="flex items-center gap-1.5 px-2 py-1 text-[11px] font-semibold text-muted-foreground">
+                  {group.key === "personal" ? <Folder className="size-3" /> : <Globe2 className="size-3" />}{group.label}
+                </DropdownMenuLabel>
+              ) : (
+                <div className="flex items-center gap-1.5 px-2 py-1 text-[11px] font-semibold text-muted-foreground">
+                  {group.key === "personal" ? <Folder className="size-3" /> : <Globe2 className="size-3" />}{group.label}
+                </div>
+              )}
+              {group.rows.map((item) => {
+                const rowContent = (
+                  <>
+                    <SpaceIcon item={item} />
+                    <div className="min-w-0 flex-1">
+                      <div className="truncate text-xs font-medium">{item.name}</div>
+                      <div className="mt-0.5 truncate text-[10px] text-muted-foreground">
+                        {item.type === "faq" ? "FAQ" : "文档库"} · {item.knowledge_count ?? 0} 项知识
+                      </div>
+                    </div>
+                    {item.publication_status === "published" && (
+                      <Badge variant="outline" className="h-4 px-1 text-[9px]">公共</Badge>
+                    )}
+                  </>
+                );
+                return variant === "popover" ? (
+                  <DropdownMenuCheckboxItem
+                    key={item.id}
+                    checked={selected.has(item.id)}
+                    onCheckedChange={() => toggle(item.id)}
+                    onSelect={(event) => event.preventDefault()}
+                    className={cn(
+                      "my-0.5 min-h-10 rounded-md py-1.5 pr-2 pl-7",
+                      selected.has(item.id) && "bg-primary/8 focus:bg-primary/12",
+                    )}
+                  >
+                    {rowContent}
+                  </DropdownMenuCheckboxItem>
+                ) : (
+                  <button
+                    key={item.id}
+                    type="button"
+                    role="checkbox"
+                    aria-checked={selected.has(item.id)}
+                    onClick={() => toggle(item.id)}
+                    className={cn(
+                      "my-0.5 flex min-h-11 w-full items-center gap-2 rounded-md px-2 py-1.5 text-left outline-none transition-colors hover:bg-muted/60 focus-visible:ring-2 focus-visible:ring-primary",
+                      selected.has(item.id) && "bg-primary/8",
+                    )}
+                  >
+                    <span className={cn(
+                      "flex size-4 shrink-0 items-center justify-center rounded border",
+                      selected.has(item.id) && "border-primary bg-primary text-primary-foreground",
+                    )}>
+                      {selected.has(item.id) && <Check className="size-3" />}
+                    </span>
+                    {rowContent}
+                  </button>
+                );
+              })}
+            </div>
+          ))
+        )}
+      </div>
+
+      <div className="flex items-center justify-between gap-2 border-t bg-muted/20 px-2.5 py-2">
+        <span className="text-[11px] text-muted-foreground">已选择 {value.length} 个</span>
+        <div className="flex items-center gap-1">
+          <Button type="button" variant="ghost" size="sm" className="h-7 px-2 text-xs" onClick={() => onChange(filtered.map((item) => item.id))}>
+            全选
+          </Button>
+          <Button type="button" variant="ghost" size="sm" className="h-7 px-2 text-xs" onClick={() => onChange([])}>
+            清空
+          </Button>
+        </div>
+      </div>
+    </>
+  );
+}
+
+export function LlmWikiKnowledgeSelector({
+  value,
+  onChange,
+  source = "all",
+  agentId,
+  autoSelectAll = false,
+  disabled = false,
+  className,
+  label = "知识空间",
+  variant = "popover",
+}: {
+  value: string[];
+  onChange: (value: string[]) => void;
+  source?: SelectorSource;
+  agentId?: string | null;
+  autoSelectAll?: boolean;
+  disabled?: boolean;
+  className?: string;
+  label?: string;
+  variant?: SelectorVariant;
+}) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+  const runtime = useLlmWikiRuntime();
+  const all = useLlmWikiKnowledgeBases(
+    "all",
+    runtime.data?.provider === "weknora",
+  );
+  const agent = useAgentLlmWikiKnowledgeBases(
+    agentId,
+    runtime.data?.provider === "weknora" && source === "agent" && !!agentId,
+  );
+  const rows = all.data ?? [];
+  const defaultIds = useMemo(() => {
+    if (source !== "agent") {
+      return rows.map((item) => item.id);
+    }
+    return (agent.data ?? []).map((item) => item.id);
+  }, [agent.data, rows, source]);
+  const loading = all.isLoading || (source === "agent" && !!agentId && agent.isLoading);
+  const error = all.error ?? (source === "agent" ? agent.error : null);
+  const availableIds = useMemo(() => new Set(rows.map((item) => item.id)), [rows]);
+  const initializationKey = `${source}:${agentId ?? "all"}:${defaultIds.join(",")}`;
+  const initialized = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!all.data || (source === "agent" && agentId && !agent.data) || initialized.current === initializationKey) return;
+    initialized.current = initializationKey;
+    const valid = value.filter((id) => availableIds.has(id));
+    const next = autoSelectAll && valid.length === 0 && defaultIds.length > 0
+      ? defaultIds.filter((id) => availableIds.has(id))
+      : valid;
+    if (next.length !== value.length || next.some((id, index) => id !== value[index])) {
+      onChange(next);
+    }
+  }, [agent.data, agentId, all.data, autoSelectAll, availableIds, defaultIds, initializationKey, onChange, source, value]);
+
+  useEffect(() => {
+    if (!open) setSearch("");
+  }, [open]);
+
+  if (runtime.isError || runtime.data?.provider !== "weknora") return null;
+
+  const content = (
+    <SelectionContent
+      rows={rows}
+      value={value}
+      onChange={onChange}
+      search={search}
+      onSearchChange={setSearch}
+      loading={loading}
+      error={error}
+      source={source}
+      variant={variant}
+    />
+  );
+
+  if (variant === "panel") {
+    return (
+      <div className={cn("overflow-hidden rounded-xl border bg-background shadow-sm", className)}>
+        <div className="flex items-start justify-between gap-4 border-b px-4 py-3">
+          <div>
+            <div className="flex items-center gap-2 text-sm font-semibold">
+              <Database className="size-4 text-primary" />绑定知识空间
+            </div>
+            <p className="mt-1 text-xs text-muted-foreground">
+              新建该智能体对话时，只能从已绑定空间中选择本次检索范围。
+            </p>
+          </div>
+          <Badge variant="secondary" className="shrink-0">{value.length} 个</Badge>
+        </div>
+        {content}
+      </div>
+    );
+  }
+
+  const selectedName = value.length === 1
+    ? rows.find((item) => item.id === value[0])?.name
+    : null;
+
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <DropdownMenuTrigger asChild>
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          className={cn(
+            "h-8 max-w-52 gap-1.5 rounded-full border-0 bg-transparent px-2.5 text-muted-foreground shadow-none hover:bg-muted/70 hover:text-foreground",
+            value.length > 0 && "bg-primary/8 text-primary hover:bg-primary/12 hover:text-primary",
+            className,
+          )}
+          disabled={disabled || loading}
+        >
+          {loading ? <Loader2 className="size-3.5 animate-spin" /> : <Database className="size-3.5" />}
+          <span className="truncate text-xs font-normal">{selectedName || label}</span>
+          {value.length > 0 && (
+            <span className="flex size-4 items-center justify-center rounded-full bg-primary text-[9px] font-semibold text-primary-foreground">
+              {value.length}
+            </span>
+          )}
+          {value.length > 0 && value.length === rows.length && <Check className="size-3" />}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" sideOffset={8} className="w-80 overflow-hidden rounded-xl p-0 shadow-xl">
+        {content}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+export default LlmWikiKnowledgeSelector;

frontend-web/src/components/workspace/messages/document-rewrite-diff-dialog.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import { useMemo } from "react";
+
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { cn } from "@/lib/utils";
+
+type DiffRow = {
+  left: { text: string; kind: "same" | "removed" } | null;
+  right: { text: string; kind: "same" | "added" } | null;
+};
+
+function buildLineDiff(before: string, after: string): DiffRow[] {
+  const left = before.split("\n");
+  const right = after.split("\n");
+  // A large quadratic matrix would make the dialog itself a performance risk.
+  // Documents above this threshold still get an honest two-column comparison,
+  // just without expensive alignment of every unchanged line.
+  if (left.length * right.length > 1_000_000) {
+    const rows: DiffRow[] = [];
+    const length = Math.max(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+      const beforeLine = left[index];
+      const afterLine = right[index];
+      const same = beforeLine === afterLine;
+      rows.push({
+        left: beforeLine === undefined ? null : { text: beforeLine, kind: same ? "same" : "removed" },
+        right: afterLine === undefined ? null : { text: afterLine, kind: same ? "same" : "added" },
+      });
+    }
+    return rows;
+  }
+
+  const table = Array.from({ length: left.length + 1 }, () => new Uint16Array(right.length + 1));
+  for (let i = left.length - 1; i >= 0; i -= 1) {
+    for (let j = right.length - 1; j >= 0; j -= 1) {
+      table[i][j] = left[i] === right[j]
+        ? table[i + 1][j + 1] + 1
+        : Math.max(table[i + 1][j], table[i][j + 1]);
+    }
+  }
+  const rows: DiffRow[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < left.length || j < right.length) {
+    if (i < left.length && j < right.length && left[i] === right[j]) {
+      rows.push({ left: { text: left[i], kind: "same" }, right: { text: right[j], kind: "same" } });
+      i += 1;
+      j += 1;
+    } else if (j < right.length && (i === left.length || table[i][j + 1] >= table[i + 1][j])) {
+      rows.push({ left: null, right: { text: right[j], kind: "added" } });
+      j += 1;
+    } else {
+      rows.push({ left: { text: left[i], kind: "removed" }, right: null });
+      i += 1;
+    }
+  }
+  return rows;
+}
+
+function DiffCell({
+  value,
+  line,
+}: {
+  value: DiffRow["left"] | DiffRow["right"];
+  line: number | null;
+}) {
+  return (
+    <div
+      className={cn(
+        "grid min-w-0 grid-cols-[3rem_minmax(0,1fr)] border-b font-mono text-xs leading-5",
+        value?.kind === "removed" && "bg-red-50 text-red-950 dark:bg-red-950/30 dark:text-red-100",
+        value?.kind === "added" && "bg-emerald-50 text-emerald-950 dark:bg-emerald-950/30 dark:text-emerald-100",
+        !value && "bg-muted/30",
+      )}
+    >
+      <span className="select-none border-r px-2 text-right text-muted-foreground">{line ?? ""}</span>
+      <pre className="min-w-0 whitespace-pre-wrap break-words px-3">{value?.text ?? ""}</pre>
+    </div>
+  );
+}
+
+export function DocumentRewriteDiffDialog({
+  open,
+  onOpenChange,
+  fileName,
+  original,
+  rewritten,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  fileName: string;
+  original: string;
+  rewritten: string;
+}) {
+  const rows = useMemo(() => buildLineDiff(original, rewritten), [original, rewritten]);
+  let leftLine = 0;
+  let rightLine = 0;
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="flex max-h-[85vh] max-w-[calc(100vw-2rem)] flex-col p-0 sm:max-w-[min(94vw,1440px)]">
+        <DialogHeader className="border-b px-6 py-4">
+          <DialogTitle>改写前后对比 · {fileName}</DialogTitle>
+          <DialogDescription>红色为删除或调整前内容，绿色为新增或改写后内容。</DialogDescription>
+        </DialogHeader>
+        <div className="grid min-h-0 flex-1 grid-cols-2 divide-x overflow-auto" role="region" aria-label="Markdown 改写前后对比">
+          <section aria-label="改写前原文">
+            <div className="sticky top-0 z-10 border-b bg-background px-4 py-2 text-sm font-medium">改写前</div>
+            {rows.map((row, index) => {
+              const line = row.left ? ++leftLine : null;
+              return <DiffCell key={`left-${index}`} value={row.left} line={line} />;
+            })}
+          </section>
+          <section aria-label="改写后内容">
+            <div className="sticky top-0 z-10 border-b bg-background px-4 py-2 text-sm font-medium">改写后</div>
+            {rows.map((row, index) => {
+              const line = row.right ? ++rightLine : null;
+              return <DiffCell key={`right-${index}`} value={row.right} line={line} />;
+            })}
+          </section>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend-web/src/components/workspace/messages/document-rewrite-timeline.tsx

@@ -0,0 +1,295 @@
+"use client";
+
+import {
+  CheckCircle2Icon,
+  FilePenLineIcon,
+  Loader2Icon,
+  Undo2Icon,
+  XCircleIcon,
+} from "lucide-react";
+import { useState } from "react";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import { apiFetch } from "@/core/api/fetch-client";
+import {
+  DOCUMENT_REWRITE_UNDONE_EVENT,
+  type DocumentRewritePresentation,
+  useDocumentRewritePresentation,
+} from "@/core/document-rewrite/context";
+import { getBackendBaseURL } from "@/core/config";
+import { cn } from "@/lib/utils";
+
+import { DocumentRewriteDiffDialog } from "./document-rewrite-diff-dialog";
+
+const STEPS = [
+  { key: "snapshot", label: "固定原文版本" },
+  { key: "requirements", label: "理解改写要求" },
+  { key: "writing", label: "流式重写 Markdown" },
+  { key: "validation", label: "校验文档" },
+  { key: "comparison", label: "对比原文并生成说明" },
+] as const;
+
+function stepPosition(stage: DocumentRewritePresentation["stage"]): number {
+  switch (stage) {
+    case "snapshot":
+      return 0;
+    case "requirements":
+      return 1;
+    case "writing":
+      return 2;
+    case "validation":
+      return 3;
+    case "committing":
+    case "completed":
+      return 5;
+    case "conflict":
+    case "error":
+    case "cancelled":
+      return 4;
+    default:
+      return -1;
+  }
+}
+
+function isTerminal(stage: DocumentRewritePresentation["stage"]) {
+  return ["completed", "conflict", "error", "cancelled"].includes(stage);
+}
+
+export function DocumentRewriteTimeline({
+  item,
+}: {
+  item: DocumentRewritePresentation;
+}) {
+  const current = stepPosition(item.stage);
+  const failed = ["conflict", "error", "cancelled"].includes(item.stage);
+  const completed = item.stage === "completed";
+  const presentation = useDocumentRewritePresentation();
+  const [undoing, setUndoing] = useState(false);
+  const [diffOpen, setDiffOpen] = useState(false);
+
+  const reapplying = Boolean(item.revertedAt);
+  const activeVersionId = reapplying ? item.redoVersionId : item.versionId;
+
+  const handleUndo = async () => {
+    if (!activeVersionId || undoing) return;
+    const baseUrl = getBackendBaseURL();
+    const endpoint =
+      item.source.kind === "artifact"
+        ? `${baseUrl}/api/writing/document-rewrite/versions/${encodeURIComponent(activeVersionId)}/undo`
+        : `${baseUrl}/api/deep-research/sessions/${encodeURIComponent(item.source.id)}/document-rewrite/versions/${encodeURIComponent(activeVersionId)}/undo`;
+    const payload =
+      item.source.kind === "artifact"
+        ? { threadId: item.source.id, path: item.source.path }
+        : undefined;
+    setUndoing(true);
+    try {
+      const response = await apiFetch(endpoint, {
+        method: "POST",
+        headers: payload ? { "Content-Type": "application/json" } : undefined,
+        body: payload ? JSON.stringify(payload) : undefined,
+      });
+      const result = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+      if (!response.ok) {
+        throw new Error(
+          typeof result.detail === "string" ? result.detail : "撤销改写失败，请稍后重试。",
+        );
+      }
+      const content = typeof result.content === "string" ? result.content : "";
+      const nextInverseVersionId =
+        typeof result.redoVersionId === "string" ? result.redoVersionId : null;
+      presentation?.update(
+        item.id,
+        reapplying
+          ? { versionId: nextInverseVersionId, redoVersionId: null, revertedAt: null }
+          : { redoVersionId: nextInverseVersionId, revertedAt: new Date().toISOString() },
+      );
+      window.dispatchEvent(
+        new CustomEvent(DOCUMENT_REWRITE_UNDONE_EVENT, {
+          detail: { source: item.source, content },
+        }),
+      );
+      toast.success(reapplying ? "已重新应用本次 AI 全文改写版本。" : "已恢复到本次 AI 全文改写前的版本。");
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : "撤销改写失败，请稍后重试。");
+    } finally {
+      setUndoing(false);
+    }
+  };
+
+  return (
+    <article className="w-full rounded-2xl border bg-card shadow-sm">
+      <header className="flex items-start gap-3 border-b px-5 py-4">
+        <div className="bg-primary/10 text-primary flex size-8 shrink-0 items-center justify-center rounded-full">
+          <FilePenLineIcon className="size-4" />
+        </div>
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-center gap-2">
+            <h3 className="font-semibold">AI 全文改写 · {item.fileName}</h3>
+            <span
+              className={cn(
+                "rounded-full px-2 py-0.5 text-xs",
+                completed
+                  ? "bg-emerald-50 text-emerald-700 dark:bg-emerald-400/10 dark:text-emerald-300"
+                  : failed
+                    ? "bg-destructive/10 text-destructive"
+                    : "bg-primary/10 text-primary",
+              )}
+            >
+              {completed ? "已完成" : failed ? "未覆盖原文件" : "进行中"}
+            </span>
+          </div>
+          <p className="text-muted-foreground mt-1 text-sm">
+            {item.instruction}
+          </p>
+        </div>
+      </header>
+
+      <div className="space-y-3 px-5 py-4">
+        {STEPS.map((step, index) => {
+          const active = !isTerminal(item.stage) && index === current;
+          const done = completed || index < current;
+          return (
+            <div className="flex items-start gap-3" key={step.key}>
+              <div
+                className={cn(
+                  "mt-0.5 flex size-6 shrink-0 items-center justify-center rounded-full border",
+                  done
+                    ? "border-emerald-200 bg-emerald-50 text-emerald-600 dark:border-emerald-400/30 dark:bg-emerald-400/10"
+                    : active
+                      ? "border-primary/30 bg-primary/10 text-primary"
+                      : "border-border text-muted-foreground",
+                )}
+              >
+                {done ? (
+                  <CheckCircle2Icon className="size-4" />
+                ) : active ? (
+                  <Loader2Icon className="size-4 animate-spin" />
+                ) : (
+                  <span className="text-xs">{index + 1}</span>
+                )}
+              </div>
+              <div className="min-w-0 pt-0.5">
+                <div className="text-sm font-medium">{step.label}</div>
+                {step.key === "snapshot" && item.originalCharCount > 0 && (
+                  <p className="text-muted-foreground mt-0.5 text-xs">
+                    已冻结 {item.originalCharCount.toLocaleString()} 字原文快照。
+                  </p>
+                )}
+                {step.key === "requirements" && (
+                  item.requirementsPlan ? (
+                    <div
+                      aria-live={active ? "polite" : undefined}
+                      className="bg-muted/45 text-muted-foreground mt-2 max-w-3xl rounded-lg border px-3 py-2 text-xs leading-5 whitespace-pre-wrap"
+                      role={active ? "status" : undefined}
+                    >
+                      {item.requirementsPlan}
+                    </div>
+                  ) : active ? (
+                    <p className="text-muted-foreground mt-0.5 text-xs">
+                      正在识别改写目标、保留约束与执行方式…
+                    </p>
+                  ) : (
+                    <p className="text-muted-foreground mt-0.5 text-xs">
+                      已根据改写要求确定执行计划。
+                    </p>
+                  )
+                )}
+                {step.key === "writing" && item.writtenCharCount > 0 && (
+                  <p className="text-muted-foreground mt-0.5 text-xs">
+                    正在写入右侧沙箱，已生成 {item.writtenCharCount.toLocaleString()} 字。
+                  </p>
+                )}
+                {step.key === "validation" && item.warnings.length > 0 && (
+                  <p className="mt-0.5 text-xs text-amber-700 dark:text-amber-300">
+                    {item.warnings.join("；")}
+                  </p>
+                )}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+
+      {item.summary && (
+        <div className="border-t px-5 py-4 text-sm leading-6">
+          <div className="mb-2 font-semibold">改写说明</div>
+          <p>
+            原文 {item.summary.originalCharCount.toLocaleString()} 字，改写后{" "}
+            {item.summary.rewrittenCharCount.toLocaleString()} 字；调整了约{" "}
+            {item.summary.changedBlockCount} 个内容块。
+          </p>
+          <p className="text-muted-foreground">
+            标题数量 {item.summary.headingCountBefore} → {item.summary.headingCountAfter}，
+            使用模型：{item.summary.modelName}。
+          </p>
+          {item.summary.requestedOptimizations?.length ? (
+            <p className="text-muted-foreground">
+              本次优化：{item.summary.requestedOptimizations.join("、")}。
+            </p>
+          ) : null}
+          {item.summary.headingChanges && (
+            item.summary.headingChanges.reordered ||
+            item.summary.headingChanges.added.length > 0 ||
+            item.summary.headingChanges.removed.length > 0 ||
+            item.summary.headingChanges.levelWarnings.length > 0
+          ) && (
+            <p className="text-muted-foreground">
+              {item.summary.headingChanges.reordered ? "已调整章节顺序；" : ""}
+              {item.summary.headingChanges.added.length
+                ? `新增标题：${item.summary.headingChanges.added.join("、")}；`
+                : ""}
+              {item.summary.headingChanges.removed.length
+                ? `移除标题：${item.summary.headingChanges.removed.join("、")}；`
+                : ""}
+              {item.summary.headingChanges.levelWarnings.join("；")}
+            </p>
+          )}
+          {item.originalContent && item.rewrittenContent && (
+            <Button
+              className="mt-3 mr-2"
+              onClick={() => setDiffOpen(true)}
+              size="sm"
+              type="button"
+              variant="outline"
+            >
+              查看前后对比
+            </Button>
+          )}
+          {completed && activeVersionId && (
+            <Button
+              className="mt-3"
+              disabled={undoing}
+              onClick={() => void handleUndo()}
+              size="sm"
+              type="button"
+              variant="outline"
+            >
+              {undoing ? <Loader2Icon className="mr-1.5 size-3.5 animate-spin" /> : <Undo2Icon className="mr-1.5 size-3.5" />}
+              {reapplying ? "重新应用此次改写" : "撤销此次改写"}
+            </Button>
+          )}
+          {item.revertedAt && (
+            <p className="mt-2 text-xs text-emerald-700 dark:text-emerald-300">
+              已恢复为改写前版本。{item.redoVersionId ? "可重新应用本次改写。" : ""}
+            </p>
+          )}
+        </div>
+      )}
+
+      {item.error && (
+        <div className="flex items-center gap-2 border-t px-5 py-3 text-sm text-destructive">
+          <XCircleIcon className="size-4 shrink-0" />
+          {item.error}
+        </div>
+      )}
+      <DocumentRewriteDiffDialog
+        fileName={item.fileName}
+        onOpenChange={setDiffOpen}
+        open={diffOpen}
+        original={item.originalContent}
+        rewritten={item.rewrittenContent ?? ""}
+      />
+    </article>
+  );
+}

frontend-web/src/components/workspace/messages/message-group.tsx

@@ -1,19 +1,21 @@
 import type { Message } from "@langchain/langgraph-sdk";
 import {
   BookOpenTextIcon,
+  CheckCircle2Icon,
   ChevronDownIcon,
   ChevronUp,
   FolderOpenIcon,
   GlobeIcon,
   LightbulbIcon,
   ListTodoIcon,
+  Loader2Icon,
   MessageCircleQuestionMarkIcon,
   NotebookPenIcon,
   SearchIcon,
   SquareTerminalIcon,
   WrenchIcon,
 } from "lucide-react";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 
 import {
   ChainOfThought,
@@ -36,6 +38,12 @@ import {
   DialogHeader,
   DialogTitle,
 } from "@/components/ui/dialog";
+import {
+  buildWriteFileVirtualUrl,
+  hasCompleteArtifactExtension,
+  normalizeStreamingArtifactPath,
+  provisionalWriteFilePath,
+} from "@/core/artifacts/streaming-write-preview";
 import { useI18n } from "@/core/i18n/hooks";
 import {
   normalizeSearchResults,
@@ -249,8 +257,6 @@ function ToolCall({
   ragModeEnabled?: boolean;
 }) {
   const { t } = useI18n();
-  const artifacts = useArtifactsOptional();
-
   const displayMatch =
     result !== undefined && isDisplaySamplePayload(result)
       ? null
@@ -281,6 +287,13 @@ function ToolCall({
     );
   }
 
+  // Deep Research uses a virtual tool call for each durable writing phase.
+  // Rendering it here keeps its lifecycle in the very same ChainOfThought
+  // component as ordinary Q&A retrieval and sandbox tool calls.
+  if (name === "deep_research_progress") {
+    return <DeepResearchProgressStep id={id} args={args} />;
+  }
+
   const searchItems = normalizeSearchResults(result);
   if (ragModeEnabled && shouldUseDefaultCitationMode(name, result, args) && searchItems.length > 0) {
     const defaultItems = normalizeDefaultDisplaySources(result).map((item, index) => ({
@@ -301,8 +314,10 @@ function ToolCall({
     if (query) {
       label =
         name === "web_search"
-          ? t.toolCalls.searchOnWebFor(query)
+          ? `知识库检索 "${query}"`
           : t.toolCalls.searchFor(query);
+    } else if (name === "web_search") {
+      label = "知识库检索";
     }
     return (
       <ChainOfThoughtStep key={id} label={label} icon={SearchIcon}>
@@ -422,43 +437,17 @@ function ToolCall({
     if (!description) {
       description = t.toolCalls.writeFile;
     }
-    const path: string | undefined = (args as { path: string })?.path;
-    const artifactPath =
-      name === "write_file" && path
-        ? new URL(
-            `write-file:${path}?message_id=${messageId}&tool_call_id=${id}`,
-          ).toString()
-        : path;
-    if (artifacts && isLoading && isLast && artifacts.autoOpen && artifacts.autoSelect && path && !result) {
-      setTimeout(() => {
-        if (!artifactPath || artifacts.selectedArtifact === artifactPath) {
-          return;
-        }
-        artifacts.select(artifactPath, true);
-        artifacts.setOpen(true);
-      }, 100);
-    }
-
     return (
-      <ChainOfThoughtStep
+      <ArtifactWriteToolCall
-        key={id}
+        id={id}
-        className="cursor-pointer"
+        messageId={messageId}
-        label={description}
+        name={name}
-        icon={NotebookPenIcon}
+        args={args}
-        onClick={() => {
+        result={result}
-          if (!artifactPath || !artifacts) {
+        description={description}
-            return;
+        isLast={isLast}
-          }
+        isLoading={isLoading}
-          artifacts.select(artifactPath);
+      />
-          artifacts.setOpen(true);
-        }}
-      >
-        {path && (
-          <ChainOfThoughtSearchResult className="cursor-pointer">
-            {path}
-          </ChainOfThoughtSearchResult>
-        )}
-      </ChainOfThoughtStep>
     );
   } else if (name === "bash") {
     const description: string | undefined = (args as { description: string })
@@ -523,6 +512,123 @@ function ToolCall({
   }
 }
 
+function DeepResearchProgressStep({
+  id,
+  args,
+}: {
+  id?: string;
+  args: Record<string, unknown>;
+}) {
+  const label = typeof args.label === "string" && args.label.trim()
+    ? args.label
+    : "正在撰写研究报告";
+  const detail = typeof args.detail === "string" ? args.detail.trim() : "";
+  const active = args.status !== "complete";
+
+  return (
+    <ChainOfThoughtStep
+      key={id}
+      status={active ? "active" : "complete"}
+      icon={active
+        ? <Loader2Icon className="text-primary size-4 animate-spin" />
+        : <CheckCircle2Icon className="size-4 text-emerald-600 dark:text-emerald-400" />}
+      label={
+        <span className="flex flex-wrap items-center gap-x-2 gap-y-0.5">
+          <span>{label}</span>
+          <span className={active ? "text-primary text-xs" : "text-muted-foreground text-xs"}>
+            {active ? "进行中" : "已完成"}
+          </span>
+        </span>
+      }
+    >
+      {detail && (
+        <div className="text-muted-foreground text-xs leading-5">
+          {detail}
+        </div>
+      )}
+    </ChainOfThoughtStep>
+  );
+}
+
+function ArtifactWriteToolCall({
+  id,
+  messageId,
+  name,
+  args,
+  result,
+  description,
+  isLast,
+  isLoading,
+}: {
+  id?: string;
+  messageId?: string;
+  name: "write_file" | "str_replace";
+  args: Record<string, unknown>;
+  result?: string | Record<string, unknown>;
+  description: string;
+  isLast: boolean;
+  isLoading: boolean;
+}) {
+  const artifacts = useArtifactsOptional();
+  const openStreamedArtifact = artifacts?.openStreamedArtifact;
+  const rawPath = typeof args.path === "string" ? args.path : "";
+  const content = typeof args.content === "string" ? args.content : "";
+  const normalizedPath = normalizeStreamingArtifactPath(rawPath);
+  const hasUsablePath =
+    Boolean(normalizedPath) && hasCompleteArtifactExtension(normalizedPath);
+  const sourcePath = hasUsablePath
+    ? normalizedPath
+    : name === "write_file" && content.trim()
+      ? provisionalWriteFilePath(content)
+      : null;
+  const previewKey = messageId && id ? `${messageId}:${id}` : null;
+  const artifactPath =
+    sourcePath && name === "write_file" && messageId && id
+      ? buildWriteFileVirtualUrl({ path: sourcePath, messageId, toolCallId: id })
+      : sourcePath;
+
+  useEffect(() => {
+    if (
+      !openStreamedArtifact ||
+      !artifactPath ||
+      !previewKey ||
+      !isLoading ||
+      !isLast ||
+      result !== undefined
+    ) {
+      return;
+    }
+    openStreamedArtifact(artifactPath, previewKey);
+  }, [
+    artifactPath,
+    isLast,
+    isLoading,
+    openStreamedArtifact,
+    previewKey,
+    result,
+  ]);
+
+  return (
+    <ChainOfThoughtStep
+      key={id}
+      className={cn(artifactPath && "cursor-pointer")}
+      label={description}
+      icon={NotebookPenIcon}
+      onClick={() => {
+        if (!artifactPath || !artifacts) return;
+        artifacts.select(artifactPath);
+        artifacts.setOpen(true);
+      }}
+    >
+      {(normalizedPath || sourcePath) && (
+        <ChainOfThoughtSearchResult className="cursor-pointer">
+          {normalizedPath || sourcePath}
+        </ChainOfThoughtSearchResult>
+      )}
+    </ChainOfThoughtStep>
+  );
+}
+
 interface GenericCoTStep<T extends string = string> {
   id?: string;
   messageId?: string;

frontend-web/src/components/workspace/messages/message-list-item.tsx

@@ -1,5 +1,14 @@
 import type { Message } from '@langchain/langgraph-sdk';
-import { ClockIcon, FileIcon, Loader2Icon, PencilIcon } from 'lucide-react';
+import {
+  BookMarkedIcon,
+  ChevronDownIcon,
+  ClockIcon,
+  ExternalLinkIcon,
+  FileIcon,
+  Loader2Icon,
+  PencilIcon,
+  SearchIcon,
+} from 'lucide-react';
 import {
   memo,
   useCallback,
@@ -27,6 +36,18 @@ import {
 import { Task, TaskTrigger } from '@/components/ai-elements/task';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from '@/components/ui/collapsible';
 import { Textarea } from '@/components/ui/textarea';
 import {
   UploadedFilePreviewDialog,
@@ -35,6 +56,7 @@ import {
 import { resolveArtifactURL } from '@/core/artifacts/utils';
 import { useChatAskTimes } from '@/core/chat-timestamps';
 import { getBackendBaseURL } from '@/core/config';
+import { readRuntimeEnv } from '@/env';
 import { useI18n } from '@/core/i18n/hooks';
 import {
   extractContentFromMessage,
@@ -50,6 +72,11 @@ import {
   type RuntimeDisplaySource,
 } from '@/core/skill-display/runtime';
 import { humanMessagePlugins } from '@/core/streamdown';
+import {
+  getMultiRoundRagTrace,
+  isMultiRoundRagMessage,
+  type MultiRoundRagRound,
+} from '@/core/threads/use-multi-round-rag';
 import { cn } from '@/lib/utils';
 
 import { CitationLink } from '../citations/citation-link';
@@ -563,7 +590,26 @@ function MessageContent_({
   );
   const askTimes = useChatAskTimes();
   const isHuman = message.type === 'human';
+  const isSingleRoundRag =
+    message.additional_kwargs?.single_round_rag === true;
+  const isMultiRoundRag = isMultiRoundRagMessage(message);
+  const multiRoundTrace = isMultiRoundRag
+    ? getMultiRoundRagTrace(message)
+    : null;
+  const [selectedCitation, setSelectedCitation] =
+    useState<RuntimeDisplaySource | null>(null);
   const resolveArtifact = useArtifactResolver(threadId);
+  const handleCitationClick = useCallback(
+    (referenceId: string) => {
+      const referenceIndex = Number(referenceId);
+      if (!Number.isInteger(referenceIndex) || referenceIndex < 1) return;
+      const source =
+        displaySources.find((item) => item.index === referenceIndex) ??
+        displaySources[referenceIndex - 1];
+      if (source) setSelectedCitation(source);
+    },
+    [displaySources],
+  );
   const components = useMemo(
     () => ({
       img: (props: ImgHTMLAttributes<HTMLImageElement>) => (
@@ -571,7 +617,17 @@ function MessageContent_({
       ),
       a: ({ href, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) => {
         if (href?.startsWith('#reference-')) {
-          return <CitationLink href={href} {...props} />;
+          return (
+            <CitationLink
+              href={href}
+              {...props}
+              onReferenceClick={
+                isSingleRoundRag || isMultiRoundRag
+                  ? handleCitationClick
+                  : undefined
+              }
+            />
+          );
         }
         if (
           typeof props.children === 'string' &&
@@ -593,7 +649,13 @@ function MessageContent_({
         return <a {...props} href={href} />;
       },
     }),
-    [threadId, resolveArtifact],
+    [
+      handleCitationClick,
+      isMultiRoundRag,
+      isSingleRoundRag,
+      resolveArtifact,
+      threadId,
+    ],
   );
 
   // Question carries its own `client_ts` (round-trips through the checkpoint).
@@ -661,7 +723,7 @@ function MessageContent_({
   }
 
   // Reasoning-only AI message (no main response content yet)
-  if (!isHuman && reasoningContent && !rawContent) {
+  if (!isHuman && reasoningContent && !rawContent && !multiRoundTrace) {
     return (
       <AIElementMessageContent className={className}>
         <Reasoning isStreaming={isLoading}>
@@ -708,9 +770,20 @@ function MessageContent_({
   }
 
   return (
+    <>
       <AIElementMessageContent className={className}>
         {filesList}
         <div data-reference-batch-id={message.id} className="contents">
+          {multiRoundTrace ? (
+            <MultiRoundRagContent
+              trace={multiRoundTrace}
+              content={contentToDisplay}
+              displaySources={displaySources}
+              isLoading={isLoading}
+              rehypePlugins={[...rehypePlugins, [rehypeKatex, { output: 'html' }]]}
+              components={components}
+            />
+          ) : (
             <AssistantDisplayContent
               content={contentToDisplay}
               displaySources={displaySources}
@@ -719,7 +792,14 @@ function MessageContent_({
               rehypePlugins={[...rehypePlugins, [rehypeKatex, { output: 'html' }]]}
               components={components}
             />
+          )}
         </div>
+        {(isSingleRoundRag || isMultiRoundRag) && displaySources.length > 0 && (
+          <FrontendRagSourcesPanel
+            sources={displaySources}
+            onSelect={setSelectedCitation}
+          />
+        )}
         <MessageTokenUsage
           enabled={tokenUsageEnabled}
           isLoading={isLoading}
@@ -729,9 +809,319 @@ function MessageContent_({
           <MessageTimeStamp time={messageTime} align="left" />
         ) : null}
       </AIElementMessageContent>
+      {(isSingleRoundRag || isMultiRoundRag) && (
+        <SingleRoundRagCitationDialog
+          source={selectedCitation}
+          onOpenChange={(open) => {
+            if (!open) setSelectedCitation(null);
+          }}
+        />
+      )}
+    </>
   );
 }
 
+/**
+ * 单轮/多轮 RAG 专属的「引用来源」折叠面板。
+ *
+ * 参考 GeneralQA 的引用来源区：默认折叠，列出全部参考资料，点击任一条打开详情
+ * 弹窗（复用 SingleRoundRagCitationDialog）。这样即使模型正文里没有 `[1]` 编号，
+ * 用户也能看到本次回答依据的资料。
+ */
+function FrontendRagSourcesPanel({
+  sources,
+  onSelect,
+}: {
+  sources: RuntimeDisplaySource[];
+  onSelect: (source: RuntimeDisplaySource) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  if (sources.length === 0) return null;
+  return (
+    <Collapsible open={open} onOpenChange={setOpen} className="mt-3 w-full">
+      <CollapsibleTrigger asChild>
+        <button
+          type="button"
+          className="text-muted-foreground hover:text-foreground inline-flex items-center gap-1.5 text-xs transition-colors"
+        >
+          <BookMarkedIcon className="size-3.5" />
+          <span className="font-medium">引用来源</span>
+          <span className="text-muted-foreground/70">({sources.length})</span>
+          <ChevronDownIcon
+            className={cn(
+              'size-3.5 transition-transform duration-200',
+              !open && '-rotate-90',
+            )}
+          />
+        </button>
+      </CollapsibleTrigger>
+      <CollapsibleContent className="mt-2 grid gap-2">
+        {sources.map((source, idx) => (
+          <button
+            key={source.id ?? `${source.title}-${idx}`}
+            type="button"
+            onClick={() => onSelect(source)}
+            className="bg-card hover:bg-accent block w-full cursor-pointer rounded-lg border p-3 text-left transition-colors"
+          >
+            <div className="flex items-center gap-2">
+              <span className="bg-primary/10 text-primary flex size-5 shrink-0 items-center justify-center rounded-full text-xs font-semibold">
+                {source.index}
+              </span>
+              <span
+                className="text-foreground line-clamp-1 min-w-0 flex-1 text-sm font-medium"
+                title={source.title}
+              >
+                {source.title}
+              </span>
+              {source.type && (
+                <span className="bg-muted text-muted-foreground shrink-0 rounded px-1.5 py-0.5 text-xs">
+                  {source.type}
+                </span>
+              )}
+            </div>
+            {source.snippet && (
+              <p className="text-muted-foreground mt-1.5 line-clamp-2 text-xs leading-relaxed">
+                {source.snippet}
+              </p>
+            )}
+          </button>
+        ))}
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
+function SingleRoundRagCitationDialog({
+  source,
+  onOpenChange,
+}: {
+  source: RuntimeDisplaySource | null;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const sourceUrl = resolveSingleRoundRagSourceUrl(source);
+  return (
+    <Dialog open={!!source} onOpenChange={onOpenChange}>
+      <DialogContent className="max-h-[min(42rem,calc(100vh-2rem))] max-w-2xl overflow-hidden p-5 sm:max-w-2xl">
+        <DialogHeader className="pr-8">
+          <DialogTitle className="leading-relaxed">
+            {source?.title || "引用资料"}
+          </DialogTitle>
+          <DialogDescription className="space-y-1 text-xs">
+            <span className="block">来源：{source?.source || source?.type || "未知来源"}</span>
+            {source?.time && <span className="block">时间：{source.time}</span>}
+          </DialogDescription>
+        </DialogHeader>
+        {sourceUrl && (
+          <a
+            href={sourceUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="border-input hover:bg-accent inline-flex w-fit items-center gap-1.5 rounded-md border px-3 py-1.5 text-sm transition-colors"
+          >
+            <ExternalLinkIcon className="size-4" />
+            查看原文链接
+          </a>
+        )}
+        <div className="bg-muted/50 max-h-[min(26rem,calc(100vh-16rem))] overflow-auto rounded-lg p-3 text-sm leading-7 whitespace-pre-wrap">
+          {source?.content || source?.snippet || "暂无引用内容"}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function MultiRoundRagContent({
+  trace,
+  content,
+  displaySources,
+  isLoading,
+  rehypePlugins,
+  components,
+}: {
+  trace: NonNullable<ReturnType<typeof getMultiRoundRagTrace>>;
+  content: string;
+  displaySources: RuntimeDisplaySource[];
+  isLoading: boolean;
+  rehypePlugins: MarkdownContentProps['rehypePlugins'];
+  components: MarkdownContentProps['components'];
+}) {
+  const [open, setOpen] = useState(!trace.isComplete);
+  useEffect(() => {
+    if (!trace.isComplete) setOpen(true);
+  }, [trace.isComplete]);
+
+  return (
+    <div className="space-y-3">
+      <section className="border-border/70 overflow-hidden rounded-xl border bg-muted/20">
+        <button
+          type="button"
+          className="hover:bg-muted/50 flex w-full items-center justify-between gap-3 px-4 py-3 text-left transition-colors"
+          onClick={() => setOpen((value) => !value)}
+        >
+          <div className="flex min-w-0 items-center gap-2">
+            {trace.isComplete ? (
+              <SearchIcon className="text-primary size-4 shrink-0" />
+            ) : (
+              <Loader2Icon className="text-primary size-4 shrink-0 animate-spin" />
+            )}
+            <div>
+              <div className="text-sm font-medium">多轮检索过程</div>
+              <div className="text-muted-foreground text-xs">
+                {trace.isComplete
+                  ? `已完成 ${trace.rounds.length} 轮检索`
+                  : '正在分析问题并检索资料'}
+              </div>
+            </div>
+          </div>
+          <ChevronDownIcon
+            className={cn('text-muted-foreground size-4 transition-transform', !open && '-rotate-90')}
+          />
+        </button>
+        {open && (
+          <div className="border-border/60 space-y-3 border-t px-4 py-3">
+            {trace.rounds.map((round, index) => (
+              <MultiRoundRagRoundCard
+                key={round.id}
+                index={index + 1}
+                round={round}
+                isLoading={isLoading}
+                rehypePlugins={rehypePlugins}
+                components={components}
+              />
+            ))}
+          </div>
+        )}
+      </section>
+      <section className="border-border/70 rounded-xl border p-4">
+        <div className="mb-3 text-sm font-semibold">最终回答</div>
+        {content ? (
+          <AssistantDisplayContent
+            content={content}
+            displaySources={displaySources}
+            isLoading={isLoading}
+            renderSkillDisplayBlocks={false}
+            rehypePlugins={rehypePlugins}
+            components={components}
+          />
+        ) : (
+          <div className="text-muted-foreground flex items-center gap-2 text-sm">
+            <Loader2Icon className="size-4 animate-spin" />
+            正在生成最终回答…
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}
+
+function MultiRoundRagRoundCard({
+  index,
+  round,
+  isLoading,
+  rehypePlugins,
+  components,
+}: {
+  index: number;
+  round: MultiRoundRagRound;
+  isLoading: boolean;
+  rehypePlugins: MarkdownContentProps['rehypePlugins'];
+  components: MarkdownContentProps['components'];
+}) {
+  return (
+    <div className="border-border/60 rounded-lg border bg-background/70 p-3">
+      <div className="flex items-center gap-2 text-sm font-medium">
+        <span className="bg-primary/10 text-primary flex size-5 shrink-0 items-center justify-center rounded-full text-xs">
+          {index}
+        </span>
+        <span>{round.title}</span>
+        {round.isSearching && <Loader2Icon className="text-primary size-3.5 animate-spin" />}
+      </div>
+      {round.thought && (
+        <section className="border-border/50 bg-muted/30 mt-3 rounded-md border p-3">
+          <div className="text-muted-foreground mb-2 text-xs font-medium">思考内容</div>
+          <MarkdownContent
+            content={round.thought}
+            isLoading={isLoading}
+            rehypePlugins={rehypePlugins}
+            components={components}
+            className="text-muted-foreground text-sm"
+          />
+        </section>
+      )}
+      {round.body && (
+        <section className="border-border/50 mt-3 rounded-md border p-3">
+          <div className="text-muted-foreground mb-2 text-xs font-medium">本轮正文</div>
+          <MarkdownContent
+            content={round.body}
+            isLoading={isLoading}
+            rehypePlugins={rehypePlugins}
+            components={components}
+            className="text-sm"
+          />
+        </section>
+      )}
+      {round.query && (
+        <div className="border-primary/20 bg-primary/5 text-primary mt-2 inline-flex max-w-full items-center gap-1.5 rounded-full border px-2.5 py-1 text-xs">
+          <SearchIcon className="size-3 shrink-0" />
+          <span className="truncate">{round.query}</span>
+        </div>
+      )}
+      {round.retrievals.length > 0 && (
+        <section className="border-border/50 mt-3 rounded-md border p-3">
+          <div className="text-muted-foreground mb-2 text-xs font-medium">
+            检索内容 · {round.retrievals.length} 条
+          </div>
+          <div className="space-y-2">
+            {round.retrievals.map((item, resultIndex) => (
+              <details
+                key={`${item.id ?? item.title}-${resultIndex}`}
+                className="border-border/60 rounded-md border px-3 py-2"
+                open={resultIndex === 0}
+              >
+                <summary className="cursor-pointer list-none text-sm font-medium">
+                  <span className="mr-2 text-xs text-muted-foreground">{resultIndex + 1}.</span>
+                  {item.title}
+                </summary>
+                <div className="text-muted-foreground mt-2 text-sm leading-6 whitespace-pre-wrap">
+                  {item.content || '暂无资料摘要'}
+                </div>
+                {(item.source || item.time) && (
+                  <div className="text-muted-foreground mt-2 text-xs">
+                    {[item.source, item.time].filter(Boolean).join(' · ')}
+                  </div>
+                )}
+              </details>
+            ))}
+          </div>
+        </section>
+      )}
+    </div>
+  );
+}
+
+function resolveSingleRoundRagSourceUrl(
+  source: RuntimeDisplaySource | null,
+): string | undefined {
+  if (!source) return undefined;
+  if (source.url && /^https?:\/\//i.test(source.url)) return source.url;
+
+  const raw = source.raw ?? {};
+  const recordId =
+    source.id ??
+    readString(raw.recUuid) ??
+    readString(raw.rec_uuid) ??
+    readString(raw.uuid);
+  const knowledgeUrl = readRuntimeEnv("VITE_AIPI_KNOWLEDGE_URL")?.replace(/\/$/, "");
+  if (!knowledgeUrl || !recordId) return undefined;
+  return `${knowledgeUrl}/#/knowledge/mid-detail?recUuid=${encodeURIComponent(recordId)}`;
+}
+
+function readString(value: unknown): string | undefined {
+  if (typeof value === "string" && value.trim()) return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return undefined;
+}
+
 function EmbeddedPageContextCard({
   pageContext,
 }: {

frontend-web/src/components/workspace/messages/message-list.tsx

@@ -12,6 +12,7 @@ import {
 import { Button } from "@/components/ui/button";
 import { Textarea } from "@/components/ui/textarea";
 import { rememberAskTimes, useChatAskTimes } from "@/core/chat-timestamps";
+import { useDocumentRewritePresentation } from "@/core/document-rewrite/context";
 import { useI18n } from "@/core/i18n/hooks";
 import {
   extractContentFromMessage,
@@ -30,10 +31,13 @@ import { useSkills } from "@/core/skills/hooks";
 import {
   buildSkillDisplayMap,
   collectRuntimeDisplaySources,
+  type RuntimeDisplaySource,
 } from "@/core/skill-display/runtime";
 import type { Subtask } from "@/core/tasks";
 import { useUpdateSubtask } from "@/core/tasks/context";
 import type { AgentThreadState } from "@/core/threads";
+import { isSingleRoundRagMessage } from "@/core/threads/use-single-round-rag";
+import { isMultiRoundRagMessage } from "@/core/threads/use-multi-round-rag";
 import { cn } from "@/lib/utils";
 import { resolveAllowMultiple } from "@/roundtable-planning/lib/clarification";
 
@@ -43,6 +47,7 @@ import { StreamingIndicator } from "../streaming-indicator";
 
 import { ReferenceBatchesContext, ThreadContext } from "./context";
 import { MarkdownContent } from "./markdown-content";
+import { DocumentRewriteTimeline } from "./document-rewrite-timeline";
 import { MessageGroup } from "./message-group";
 import { MessageListItem } from "./message-list-item";
 import {
@@ -107,7 +112,9 @@ export function MessageList({
   onSetupWritingApprove,
   onSetupWritingReject,
   onSetupWritingStart,
+  researchApprovalSlot,
   onOpenArtifact,
+  onDownloadArtifact,
 }: {
   className?: string;
   contentClassName?: string;
@@ -130,7 +137,16 @@ export function MessageList({
   onSetupWritingReject?: (payload: SetupWritingApprovalPayload) => void | Promise<void>;
   /** 审批卡「直接开始写作」回调：应用配置（含已确认大纲）并立即启动写作流程（仅写作页提供，模板编辑等场景缺省隐藏该按钮）。 */
   onSetupWritingStart?: (payload: SetupWritingApprovalPayload) => void | Promise<void>;
+  /**
+   * 深度研究的交互卡插槽（报告配置、计划确认、失败重试）：workbench 向
+   * displayThread 注入带 `additional_kwargs.setup_research_approval` 的虚拟 ai
+   * 消息。撰写步骤和完成摘要不走此插槽，而是分别复用原生 tool-call 步骤条和
+   * assistant 消息行；不传该 slot 时普通对话/AI 写作零行为变化。
+   */
+  researchApprovalSlot?: (message: Message) => React.ReactNode;
   onOpenArtifact?: (filepath: string) => void;
+  /** Host override for downloading virtual/session-owned files in a present-files card. */
+  onDownloadArtifact?: (filepath: string) => void | Promise<void>;
 }) {
   const baseRehypePlugins = useRehypeSplitWordsIntoSpans(thread.isLoading);
   const rehypePlugins = useMemo(
@@ -138,6 +154,7 @@ export function MessageList({
     [baseRehypePlugins, extraRehypePlugins],
   );
   const updateSubtask = useUpdateSubtask();
+  const documentRewritePresentation = useDocumentRewritePresentation();
   const { t } = useI18n();
   const threadContext = useContext(ThreadContext);
   // Read-only contexts (public share, mock previews) must not offer deletion.
@@ -190,6 +207,7 @@ export function MessageList({
     },
     [allMessages, externallyHiddenMessageIds, hiddenMessageIds],
   );
+  const documentRewriteItems = documentRewritePresentation?.forThread(threadId) ?? [];
 
   const askTimes = useChatAskTimes();
 
@@ -237,10 +255,19 @@ export function MessageList({
   const [settings] = useLocalSettings();
   const ragModeEnabled =
     settings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
+  const hasSingleRoundRag = useMemo(
+    () =>
+      messages.some(
+        (message) =>
+          isSingleRoundRagMessage(message) || isMultiRoundRagMessage(message),
+      ),
+    [messages],
+  );
+  const referencesEnabled = ragModeEnabled || hasSingleRoundRag;
   const { skills } = useSkills();
   const skillDisplayMap = useMemo(
-    () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    () => (referencesEnabled ? buildSkillDisplayMap(skills) : new Map()),
-    [ragModeEnabled, skills],
+    [referencesEnabled, skills],
   );
   // Same per-turn reference batches the right-side panel renders (backend
   // batches preferred). Inline [n] tokens must resolve against these so badge
@@ -248,6 +275,53 @@ export function MessageList({
   // frontend tool-message scan below comes up empty (e.g. after a reload).
   const referenceBatches = useContext(ReferenceBatchesContext);
 
+  // 单轮/多轮 RAG 的参考资料存放在一条 hide_from_ui 的 tool 消息里（紧挨在
+  // assistant 消息之前）。allMessages 会把 hide_from_ui 消息过滤掉，导致通用
+  // 的 collectRuntimeDisplaySources 扫描不到它们。这里直接在原始消息流里按
+  // assistant 消息提取其对应的参考资料，保证 `[1]` 等编号能解析成可点击引用。
+  const frontendRagSourcesByAiId = useMemo(() => {
+    const map = new Map<string, RuntimeDisplaySource[]>();
+    const raw = thread.messages;
+    for (let i = 0; i < raw.length; i++) {
+      const msg = raw[i];
+      if (!msg || msg.type !== "ai" || !msg.id) continue;
+      const kwargs = msg.additional_kwargs;
+      if (!kwargs || (kwargs.single_round_rag !== true && kwargs.multi_round_rag !== true)) {
+        continue;
+      }
+      let sources: RuntimeDisplaySource[] = [];
+      for (let j = i - 1; j >= 0; j--) {
+        const prev = raw[j];
+        if (!prev) break;
+        // 前一条 human/ai 消息即为本轮边界，跨边界即停止。
+        if (prev.type === "human" || prev.type === "ai") break;
+        if (prev.type !== "tool") continue;
+        const prevKwargs = prev.additional_kwargs;
+        if (
+          !prevKwargs ||
+          (prevKwargs.single_round_rag !== true && prevKwargs.multi_round_rag !== true)
+        ) {
+          continue;
+        }
+        const results = extractFrontendRagResults(prev.content);
+        if (results && results.length > 0) {
+          const toolName = String(
+            (prev as { name?: unknown }).name ??
+              (prevKwargs.multi_round_rag === true
+                ? "multi_round_rag_references"
+                : "knowledge_base_search"),
+          );
+          sources = results.map((item, index) =>
+            toRuntimeDisplaySource(item, index + 1, toolName),
+          );
+        }
+        break;
+      }
+      map.set(msg.id, sources);
+    }
+    return map;
+  }, [thread.messages]);
+
   // Track which clarification messages are still awaiting an answer.
   // Pending = clarification tool messages that appear after the last human message
   // (no user reply has been sent for them yet).
@@ -372,8 +446,14 @@ export function MessageList({
         {groupMessages(messages, (group) => {
           if (group.type === "human" || group.type === "assistant") {
             return group.messages.map((msg) => {
+              // 深度研究的报告摘要由独立 SSE 作业驱动；把它接入既有 assistant 流式状态，
+              // 便于 Streamdown 在每次 summary_delta 到达时立即更新该普通消息行。
+              const messageIsLoading =
+                thread.isLoading ||
+                msg.additional_kwargs?.deep_research_summary_streaming === true ||
+                msg.additional_kwargs?.deep_research_follow_up_streaming === true;
               const isAssistantMessage =
-                ragModeEnabled &&
+                referencesEnabled &&
                 group.type === "assistant" &&
                 msg.type === "ai";
               const batchSources = isAssistantMessage
@@ -381,9 +461,16 @@ export function MessageList({
                     (batch) => batch.assistant_message_id === msg.id,
                   )?.sources ?? []
                 : [];
+              // 单轮/多轮 RAG 的参考资料来自隐藏的 tool 消息，优先于通用扫描。
+              const frontendRagSources =
+                isAssistantMessage && msg.id
+                  ? frontendRagSourcesByAiId.get(msg.id) ?? []
+                  : [];
               const displaySources = isAssistantMessage
                 ? batchSources.length > 0
                   ? batchSources
+                  : frontendRagSources.length > 0
+                    ? frontendRagSources
                     : collectRuntimeDisplaySources(messages, skillDisplayMap, {
                         afterMessageId: findPreviousHumanMessageId(messages, msg.id),
                         beforeMessageId: msg.id,
@@ -400,7 +487,7 @@ export function MessageList({
                       : undefined
                   }
                   message={msg}
-                  isLoading={thread.isLoading}
+                  isLoading={messageIsLoading}
                   threadId={threadId}
                   tokenUsageEnabled={tokenUsageEnabled}
                   displaySources={displaySources}
@@ -495,6 +582,15 @@ export function MessageList({
                 />
               </div>
             ) : null;
+          } else if (group.type === "assistant:research-approval") {
+            // 深度研究交互卡（配置/计划确认/失败重试）：宿主不传渲染函数时该
+            // 分组不渲染。撰写步骤和完成摘要会经过普通的 processing/assistant 分组。
+            const message = group.messages[0];
+            return researchApprovalSlot && message ? (
+              <div key={group.id} className="w-full pb-2">
+                {researchApprovalSlot(message)}
+              </div>
+            ) : null;
           } else if (group.type === "assistant:present-files") {
             const files: string[] = [];
             for (const message of group.messages) {
@@ -517,6 +613,7 @@ export function MessageList({
                   files={files}
                   threadId={threadId}
                   onOpenArtifact={onOpenArtifact}
+                  onDownloadArtifact={onDownloadArtifact}
                 />
                 <MessageTokenUsageList
                   enabled={tokenUsageEnabled}
@@ -642,6 +739,9 @@ export function MessageList({
             </div>
           );
         })}
+        {documentRewriteItems.map((item) => (
+          <DocumentRewriteTimeline key={item.id} item={item} />
+        ))}
         {thread.isLoading && <StreamingIndicator className="my-4" />}
         <div style={{ height: `${paddingBottom}px` }} />
         </MessageMetricsProvider>
@@ -717,6 +817,46 @@ function findPreviousHumanMessageId(
   return undefined;
 }
 
+/** 从单轮/多轮 RAG 的 tool 消息体里取出 `content.results`。 */
+function extractFrontendRagResults(content: unknown): unknown[] | null {
+  if (content && typeof content === "object" && !Array.isArray(content)) {
+    const results = (content as { results?: unknown }).results;
+    if (Array.isArray(results)) return results;
+  }
+  return null;
+}
+
+/** 把单轮/多轮 RAG 的一条参考资料归一化为展示用的 RuntimeDisplaySource。 */
+function toRuntimeDisplaySource(
+  item: unknown,
+  index: number,
+  skillName: string,
+): RuntimeDisplaySource {
+  const record =
+    item && typeof item === "object" && !Array.isArray(item)
+      ? (item as Record<string, unknown>)
+      : {};
+  const raw =
+    (record.raw as Record<string, unknown> | undefined) ?? record;
+  const content = String(record.content ?? record.snippet ?? "");
+  return {
+    id: typeof record.id === "string" && record.id ? record.id : undefined,
+    title: String(record.title ?? `参考资料 ${index}`),
+    type: String(record.type ?? "result"),
+    snippet: String(record.snippet ?? content),
+    content,
+    source:
+      typeof record.source === "string" && record.source ? record.source : undefined,
+    author: undefined,
+    time: typeof record.time === "string" && record.time ? record.time : undefined,
+    url: typeof record.url === "string" && record.url ? record.url : undefined,
+    raw,
+    index,
+    skillName,
+    mode: "citation",
+  };
+}
+
 function getSetupAgentApprovalPayload(
   message: unknown,
 ): SetupAgentApprovalPayload | null {

frontend-web/src/components/workspace/mode-hover-guide.tsx

@@ -50,16 +50,19 @@ export function ModeHoverGuide({
   mode,
   children,
   showTitle = true,
+  tooltipContent,
 }: {
   mode: AgentMode;
   children: React.ReactNode;
   /** When true, tooltip shows "ModeName: Description". When false, only description. */
   showTitle?: boolean;
+  /** Overrides the standard mode tooltip for page-specific execution modes. */
+  tooltipContent?: string;
 }) {
   const { t } = useI18n();
   const label = t.inputBox[getModeLabelKey(mode)];
   const description = t.inputBox[getModeDescriptionKey(mode)];
-  const content = showTitle ? `${label}: ${description}` : description;
+  const content = tooltipContent ?? (showTitle ? `${label}: ${description}` : description);
 
   return <Tooltip content={content}>{children}</Tooltip>;
 }

frontend-web/src/components/workspace/settings/custom-theme-library-settings.tsx

@@ -70,6 +70,18 @@ const ADVANCED_COLOR_FIELDS: Array<{
     description: "主按钮悬停时的背景色",
     token: "--theme-button-hover",
   },
+  {
+    key: "navigation_gradient_start",
+    label: "导航渐变起点",
+    description: "全量模式顶部导航栏左侧的渐变色",
+    token: "--navigation-gradient-start",
+  },
+  {
+    key: "navigation_gradient_end",
+    label: "导航渐变终点",
+    description: "全量模式顶部导航栏右侧的渐变色",
+    token: "--navigation-gradient-end",
+  },
   {
     key: "selected_background",
     label: "选中背景",
@@ -268,14 +280,20 @@ function CustomThemePreview({ theme }: { theme: CustomThemePreset }) {
       style={tokens}
       aria-label={`${theme.name} 的颜色预览`}
     >
-      <div className="flex items-center gap-2 border-b border-[var(--border)] bg-[var(--background)] px-3 py-2">
+      <div
+        className="flex items-center gap-2 border-b border-[var(--border)] px-3 py-2"
+        style={{
+          backgroundImage:
+            "linear-gradient(105deg, var(--navigation-gradient-start) 0%, var(--primary) 52%, var(--navigation-gradient-end) 100%)",
+        }}
+      >
         <span
-          className="flex size-5 items-center justify-center rounded-md bg-[var(--primary)] text-[10px] font-bold text-[var(--primary-foreground)] ring-2 ring-[var(--ring)]"
+          className="flex size-5 items-center justify-center rounded-md bg-white/25 text-[10px] font-bold text-[var(--navigation-foreground)] ring-2 ring-white/35"
           aria-hidden
         >
           C
         </span>
-        <span className="text-xs font-semibold text-[var(--foreground)]">
+        <span className="text-xs font-semibold text-[var(--navigation-foreground)]">
           实时预览
         </span>
         <span

frontend-web/src/components/workspace/settings/skill-settings-page.tsx

@@ -72,6 +72,7 @@ import { getStoredAuth } from "@/core/auth";
 import { useI18n } from "@/core/i18n/hooks";
 import type { ValidateSkillUploadResponse } from "@/core/skills/api";
 import {
+  useDeleteBuiltinSkill,
   useDeleteCustomSkill,
   useDuplicateSkill,
   useGenerateMissingSkillNameZh,
@@ -618,7 +619,8 @@ export function SkillRow({
   const setFeatured = useSetSkillFeatured();
   const setAlwaysOn = useSetSkillAlwaysOn();
   const { data: compression } = useSkillCompressionSettings();
-  const deleteSkill = useDeleteCustomSkill();
+  const deleteCustom = useDeleteCustomSkill();
+  const deleteBuiltin = useDeleteBuiltinSkill();
   const duplicateSkillMutation = useDuplicateSkill();
   const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
   const [tagPickerOpen, setTagPickerOpen] = useState(false);
@@ -634,8 +636,9 @@ export function SkillRow({
   const isOwned =
     isCustom && !isBuiltin && !!skill.owner_user_id && skill.owner_user_id === currentUserId;
   const isFromOthers = isCustom && !isBuiltin && !isOwned;
-  // Admin can edit/delete/unpublish anyone's skill; non-admin only their own.
+  // Admin can manage custom skills from any owner; non-admin only their own.
   const canManage = isCustom && (isOwned || isAdmin);
+  const canDelete = isAdmin || isOwned;
   const canTogglePublish = canManage && !isBuiltin;
   // 常驻(免压缩):内置技能仅管理员可设;自定义技能其所有者或管理员可设(与后端一致)。
   const canSetAlwaysOn = isAdmin || isOwned;
@@ -688,7 +691,11 @@ export function SkillRow({
 
   async function handleDelete() {
     try {
-      await deleteSkill.mutateAsync(skill.name);
+      if (isBuiltin) {
+        await deleteBuiltin.mutateAsync(skill.name);
+      } else {
+        await deleteCustom.mutateAsync(skill.name);
+      }
       toast.success(t.settings.skills.deleteSuccess);
       setConfirmDeleteOpen(false);
     } catch (err) {
@@ -1011,7 +1018,7 @@ export function SkillRow({
       >
         <CopyIcon className="size-3.5" />
       </Button>
-      {canManage && (
+      {canDelete && (
         <Button
           size="icon"
           variant="ghost"
@@ -1109,16 +1116,18 @@ export function SkillRow({
             <Button
               variant="outline"
               onClick={() => setConfirmDeleteOpen(false)}
-              disabled={deleteSkill.isPending}
+              disabled={deleteCustom.isPending || deleteBuiltin.isPending}
             >
               {t.common.cancel}
             </Button>
             <Button
               variant="destructive"
               onClick={() => void handleDelete()}
-              disabled={deleteSkill.isPending}
+              disabled={deleteCustom.isPending || deleteBuiltin.isPending}
             >
-              {deleteSkill.isPending ? t.common.loading : t.common.delete}
+              {deleteCustom.isPending || deleteBuiltin.isPending
+                ? t.common.loading
+                : t.common.delete}
             </Button>
           </DialogFooter>
         </DialogContent>

frontend-web/src/components/workspace/skill-display-sources.tsx

@@ -92,7 +92,7 @@ export function SourceCard({
       knowledge_base_id: previewTarget.knowledgeBaseId,
       chunk_id: previewTarget.chunkId,
     });
-    void apiFetch(`${getBackendBaseURL()}/api/weknora/source-context?${params}`)
+    void apiFetch(`${getBackendBaseURL()}/api/llmwiki/sources/context?${params}`)
       .then(async (response) => {
         const payload = (await response.json().catch(() => null)) as unknown;
         if (!response.ok || !isWeKnoraSourceContextResponse(payload)) {
@@ -240,7 +240,18 @@ type WeKnoraSourceContext = {
   knowledge_base_name?: string;
   document_title?: string;
   document_file_name?: string;
+  display_mode?: "wiki" | "chunks";
   focus_chunk_id: string;
+  wiki_page?: {
+    id?: string;
+    slug?: string;
+    title?: string;
+    page_type?: string;
+    status?: string;
+    summary?: string;
+    content?: string;
+    source_refs?: string[];
+  } | null;
   chunks: Array<{
     id: string;
     chunk_index?: number;
@@ -312,6 +323,33 @@ function WeKnoraSourceContextPanel({
   if (!context) {
     return null;
   }
+  const wikiPage = context.wiki_page;
+  const wikiContent = cleanReferenceText(
+    [wikiPage?.summary, wikiPage?.content].filter(Boolean).join("\n\n"),
+    [],
+  );
+  if (wikiPage && wikiContent) {
+    return (
+      <div className="max-h-[55vh] space-y-3 overflow-y-auto pr-1">
+        <div className="bg-muted/60 text-muted-foreground rounded-lg px-3 py-2 text-xs">
+          <span>{context.knowledge_base_name || "WeKnora 知识库"}</span>
+          <span> · LLMWiki</span>
+          {wikiPage.page_type && <span> · {wikiPage.page_type}</span>}
+        </div>
+        <section className="border-primary/40 bg-primary/5 rounded-lg border p-3 text-sm leading-relaxed shadow-sm">
+          <div className="mb-2 flex flex-wrap items-center gap-2">
+            <span className="text-foreground text-sm font-medium">
+              {wikiPage.title || wikiPage.slug || "LLMWiki 页面"}
+            </span>
+            <span className="bg-primary text-primary-foreground rounded px-1.5 py-0.5 text-xs font-medium">
+              清洗页
+            </span>
+          </div>
+          <div className="space-y-3 whitespace-pre-wrap">{wikiContent}</div>
+        </section>
+      </div>
+    );
+  }
   return (
     <div className="max-h-[55vh] space-y-3 overflow-y-auto pr-1">
       <div className="bg-muted/60 text-muted-foreground rounded-lg px-3 py-2 text-xs">

frontend-web/src/components/workspace/skills/skill-file-preview-dialog.tsx

@@ -5,6 +5,7 @@ import {
   DownloadIcon,
   Loader2,
   PencilIcon,
+  Trash2Icon,
   XIcon,
 } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
@@ -22,6 +23,7 @@ import { Textarea } from "@/components/ui/textarea";
 import { MarkdownContent } from "@/components/workspace/messages/markdown-content";
 import { getSkillFileDownloadURL } from "@/core/skills/api";
 import {
+  useDeleteSkillFile,
   useSaveSkillFile,
   useSkillFileContent,
 } from "@/core/skills/hooks";
@@ -66,6 +68,7 @@ export function SkillFilePreviewDialog({
     open ? path : null,
   );
   const save = useSaveSkillFile();
+  const remove = useDeleteSkillFile();
 
   const [editing, setEditing] = useState(false);
   const [draft, setDraft] = useState("");
@@ -77,6 +80,8 @@ export function SkillFilePreviewDialog({
   }, [path, open]);
 
   const fileEditable = !!data?.editable && treeEditable;
+  const isRootSkillFile = path?.replace(/\\/g, "/").toLowerCase() === "skill.md";
+  const fileDeletable = !!data && treeEditable && !isRootSkillFile;
   const isMarkdown = useMemo(() => {
     if (!path) return false;
     const lower = path.toLowerCase();
@@ -115,6 +120,18 @@ export function SkillFilePreviewDialog({
     }
   }
 
+  async function handleDelete() {
+    if (!skillName || !path) return;
+    if (!window.confirm(tx.filesDeleteConfirm.replace("{path}", path))) return;
+    try {
+      await remove.mutateAsync({ skillName, path });
+      toast.success(tx.filesDeleteSuccess);
+      onOpenChange(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
   async function handleCopyPath() {
     if (!path) return;
     await navigator.clipboard.writeText(path);
@@ -158,6 +175,18 @@ export function SkillFilePreviewDialog({
                   {tx.filesEditAction}
                 </Button>
               )}
+              {fileDeletable && !editing && (
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  className="h-7 px-2 text-xs text-destructive hover:text-destructive"
+                  onClick={() => void handleDelete()}
+                  disabled={remove.isPending}
+                >
+                  {remove.isPending ? <Loader2 className="size-3.5 animate-spin" /> : <Trash2Icon className="size-3.5" />}
+                  {tx.filesDeleteAction}
+                </Button>
+              )}
               {editing && (
                 <>
                   <Button

frontend-web/src/components/workspace/workspace-nav-chat-list.tsx

@@ -14,7 +14,7 @@ import {
 } from "@/components/ui/sidebar";
 import { useI18n } from "@/core/i18n/hooks";
 // import { BotIcon, BrainIcon, ListChecks, MessageSquarePlus, MessagesSquare, SparklesIcon, UsersIcon } from "lucide-react";
-import { BookOpen, BotIcon, BrainIcon, BriefcaseBusiness, ListChecks, MessageSquarePlus, MessagesSquare, PenLine, Plus, SparklesIcon, Users } from "lucide-react";
+import { BookOpen, BotIcon, BrainIcon, BriefcaseBusiness, ListChecks, MessageSquarePlus, MessagesSquare, PenLine, Plus, SparklesIcon, Telescope, Users } from "lucide-react";
 
 import { KnowledgeRagToggle } from "./knowledge-rag-toggle";
 import { SidebarCollapseButton } from "./workspace-header";
@@ -172,6 +172,18 @@ export function WorkspaceNavChatList({
                 </Link>
               </SidebarMenuButton>
             </SidebarMenuItem>
+            <SidebarMenuItem>
+              <SidebarMenuButton
+                isActive={pathname.startsWith("/page/workspace/deep-research")}
+                asChild
+                className={NAV_ITEM_CLASS}
+              >
+                <Link href="/page/workspace/deep-research">
+                  <Telescope />
+                  <span>深度研究</span>
+                </Link>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
             <SidebarMenuItem>
               <SidebarMenuButton
                 isActive={pathname.startsWith("/page/workspace/roundtable/planning")}
@@ -184,7 +196,7 @@ export function WorkspaceNavChatList({
                 </Link>
               </SidebarMenuButton>
             </SidebarMenuItem>
-            <SidebarMenuItem>
+            {/* <SidebarMenuItem>
               <SidebarMenuButton
                 isActive={pathname.startsWith("/page/workspace/roundtable/position")}
                 asChild
@@ -195,7 +207,7 @@ export function WorkspaceNavChatList({
                   <span>岗位会商</span>
                 </Link>
               </SidebarMenuButton>
-            </SidebarMenuItem>
+            </SidebarMenuItem> */}
             <SidebarMenuItem>
               <SidebarMenuButton
                 isActive={pathname === "/page/workspace/scheduled/tasks"}

frontend-web/src/components/workspace/workspace-nav-menu.tsx

@@ -234,6 +234,14 @@ export function WorkspaceNavMenu() {
                       岗位管理
                     </DropdownMenuItem>
                   )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/workspace/admin/position-roles")}
+                    >
+                      <BriefcaseIcon />
+                      岗位角色配置
+                    </DropdownMenuItem>
+                  )}
                   {isAdmin && (
                     <DropdownMenuItem
                       onClick={() =>

frontend-web/src/contexts/ThemeContext.tsx

@@ -229,6 +229,8 @@ function markExplicitChoice(): void {
 // 主题上下文
 interface ThemeContextType {
   theme: ThemeType;
+  /** Resolved visual mode; custom themes keep their own light/dark setting. */
+  baseMode: 'light' | 'dark';
   themeConfig: ThemeConfig;
   toggleTheme: () => void;
   setTheme: (theme: ThemeType) => void;
@@ -309,6 +311,7 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({ children }) => {
   const theme: ThemeType = isBuiltinTheme(requestedTheme)
     ? requestedTheme
     : customTheme?.id ?? 'light';
+  const baseMode: 'light' | 'dark' = customTheme?.mode ?? (theme === 'dark' ? 'dark' : 'light');
 
   useEffect(() => {
     if (typeof document === 'undefined') return;
@@ -377,7 +380,7 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({ children }) => {
 
   return (
     <ThemeContext.Provider
-      value={{ theme, themeConfig, toggleTheme, setTheme, mounted }}
+      value={{ theme, baseMode, themeConfig, toggleTheme, setTheme, mounted }}
     >
       {children}
     </ThemeContext.Provider>

frontend-web/src/core/agents/types.ts

@@ -62,6 +62,8 @@ export interface Agent {
    * (名称 + SKILL.md 路径 + 必须先 read_file 的硬指令) 拼进本轮任务以补偿弱模型。
    * 与业务链条同名开关取 OR。null/false = 关 (默认)。 */
   seat_skill_directive?: boolean | null;
+  /** DeerFlow LLMWiki mapping ids this agent allows conversations to select. */
+  llmwiki_knowledge_base_ids?: string[] | null;
   tags?: Tag[];
   featured_order?: number | null;
   /** Whether the current user has favorited (收藏) this agent. */
@@ -97,6 +99,7 @@ export interface CreateAgentRequest {
   template_name?: string | null;
   /** 会商席位「技能识别强化」开关；缺省/false = 关。 */
   seat_skill_directive?: boolean | null;
+  llmwiki_knowledge_base_ids?: string[] | null;
 }
 
 export interface UpdateAgentRequest {
@@ -114,4 +117,5 @@ export interface UpdateAgentRequest {
   template_name?: string | null;
   /** 会商席位「技能识别强化」开关；缺省/false = 关。 */
   seat_skill_directive?: boolean | null;
+  llmwiki_knowledge_base_ids?: string[] | null;
 }

frontend-web/src/core/artifacts/streaming-write-preview.ts

@@ -0,0 +1,68 @@
+export type StreamingArtifactLanguage = "markdown" | "html" | "mermaid";
+
+export function normalizeStreamingArtifactPath(path: string): string {
+  let normalized = path.trim();
+  const first = normalized[0];
+  const last = normalized.at(-1);
+  if (
+    normalized.length >= 2 &&
+    ((first === '"' && last === '"') ||
+      (first === "'" && last === "'") ||
+      (first === "`" && last === "`"))
+  ) {
+    normalized = normalized.slice(1, -1).trim();
+  }
+  return normalized;
+}
+
+export function hasCompleteArtifactExtension(path: string): boolean {
+  const pathname = normalizeStreamingArtifactPath(path).split(/[?#]/, 1)[0] ?? "";
+  const filename = pathname.split("/").filter(Boolean).at(-1) ?? "";
+  // JSON tool arguments commonly stream `report.m` before `report.md`.
+  // Treating the partial suffix as final makes the sandbox permanently TEXT.
+  return /\.[a-z0-9]{2,12}$/i.test(filename);
+}
+
+export function provisionalWriteFilePath(content: string): string {
+  const head = content.slice(0, 256).trimStart().toLowerCase();
+  if (head.startsWith("<!doctype html") || head.startsWith("<html")) {
+    return "未命名文件.html";
+  }
+  return "未命名文件.md";
+}
+
+export function languageOfStreamingArtifact(
+  path: string,
+): StreamingArtifactLanguage | null {
+  const pathname = normalizeStreamingArtifactPath(path)
+    .split(/[?#]/, 1)[0]
+    ?.toLowerCase();
+  if (pathname?.endsWith(".md") || pathname?.endsWith(".markdown")) {
+    return "markdown";
+  }
+  if (pathname?.endsWith(".html") || pathname?.endsWith(".htm")) {
+    return "html";
+  }
+  if (pathname?.endsWith(".mmd") || pathname?.endsWith(".mermaid")) {
+    return "mermaid";
+  }
+  return null;
+}
+
+export function buildWriteFileVirtualUrl({
+  path,
+  messageId,
+  toolCallId,
+}: {
+  path: string;
+  messageId: string;
+  toolCallId: string;
+}): string {
+  const language = languageOfStreamingArtifact(path);
+  const languageQuery = language ? `&language=${language}` : "";
+  return new URL(
+    `write-file:${path}?message_id=${encodeURIComponent(
+      messageId,
+    )}&tool_call_id=${encodeURIComponent(toolCallId)}${languageQuery}`,
+  ).toString();
+}

frontend-web/src/core/auth/route-key-login.ts

@@ -5,11 +5,25 @@ import { readRuntimeEnv } from "@/env";
  *
  * Add a new entry here when an external system needs a short ``routeKey``.
  * Targets must remain internal SPA routes; LoginPage validates them again
- * before navigating.
+ * before navigating. The optional display settings are converted into the
+ * existing route parameters on the destination URL.
  */
-export const ROUTE_KEY_MAPPINGS: Readonly<Record<string, string>> = {
+export interface RouteKeyMapping {
-  a: "/page/canvas/ai-writing",
+  /** Internal SPA route to open after sign-in. */
-  "8bf": "/page/strategy/qa/8bf-roundtable",
+  path: string;
+  /** Add `hideChrome=1` to hide the global header and page sidebar. */
+  hideChrome?: boolean;
+  /** Add the existing `theme` route parameter and apply it during sign-in. */
+  theme?: string;
+}
+
+export const ROUTE_KEY_MAPPINGS: Readonly<Record<string, RouteKeyMapping>> = {
+  a: { path: "/page/canvas/ai-writing" },
+  "8bf": {
+    path: "/page/strategy/qa/8bf-roundtable",
+    hideChrome: true,
+    theme: "dark-blue",
+  },
 };
 
 /** Login URL parameter that selects a route from ``ROUTE_KEY_MAPPINGS``. */
@@ -26,8 +40,23 @@ export function getRouteKeyLoginPassword(): string {
   return readRuntimeEnv("VITE_ROUTE_LOGIN_PASSWORD") ?? "";
 }
 
-export function resolveRouteKey(routeKey: string | null | undefined): string {
+export function resolveRouteKeyMapping(
+  routeKey: string | null | undefined,
+): RouteKeyMapping | undefined {
   const key = routeKey?.trim();
-  if (!key) return "";
+  if (!key) return undefined;
-  return ROUTE_KEY_MAPPINGS[key] ?? "";
+  return ROUTE_KEY_MAPPINGS[key];
+}
+
+export function resolveRouteKey(routeKey: string | null | undefined): string {
+  const mapping = resolveRouteKeyMapping(routeKey);
+  if (!mapping) return "";
+
+  const [path, ownQuery = ""] = mapping.path.split("?");
+  const query = new URLSearchParams(ownQuery);
+  if (mapping.hideChrome) query.set("hideChrome", "1");
+  if (mapping.theme) query.set("theme", mapping.theme);
+
+  const serializedQuery = query.toString();
+  return serializedQuery ? `${path}?${serializedQuery}` : path;
 }

frontend-web/src/core/config/index.ts

@@ -21,9 +21,23 @@ function getBaseOrigin() {
   return "http://localhost:2026";
 }
 
+function alignLoopbackHostname(url: URL): URL {
+  if (typeof window === "undefined") return url;
+  const loopbackHosts = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+  if (
+    loopbackHosts.has(url.hostname) &&
+    loopbackHosts.has(window.location.hostname)
+  ) {
+    url.hostname = window.location.hostname;
+  }
+  return url;
+}
+
 export function getBackendBaseURL() {
   if (env.NEXT_PUBLIC_BACKEND_BASE_URL) {
-    return new URL(env.NEXT_PUBLIC_BACKEND_BASE_URL, getBaseOrigin())
+    return alignLoopbackHostname(
+      new URL(env.NEXT_PUBLIC_BACKEND_BASE_URL, getBaseOrigin()),
+    )
       .toString()
       .replace(/\/+$/, "");
   } else {

frontend-web/src/core/document-rewrite/context.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+
+import type {
+  DocumentRewriteStage,
+} from "@/open-canvas/hooks/useDocumentRewrite";
+import type { DocumentRewriteSummary } from "@/open-canvas/api/rewrite";
+
+export type DocumentRewritePresentation = {
+  id: string;
+  threadId: string;
+  source: {
+    kind: "artifact" | "deep_research_report";
+    id: string;
+    path?: string;
+  };
+  fileName: string;
+  instruction: string;
+  style: string;
+  modelName: string | null;
+  stage: DocumentRewriteStage;
+  originalCharCount: number;
+  writtenCharCount: number;
+  /** Short model-generated plan, streamed while it understands the request. */
+  requirementsPlan: string;
+  warnings: string[];
+  summary: DocumentRewriteSummary | null;
+  /** Kept in-memory for the line-level compare dialog; backend job hydration refills it. */
+  originalContent: string;
+  rewrittenContent: string | null;
+  versionId: string | null;
+  /** Inverse snapshot created by a safe undo; enables a one-click reapply. */
+  redoVersionId: string | null;
+  revertedAt: string | null;
+  error: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type CreatePresentationInput = Omit<
+  DocumentRewritePresentation,
+  | "id"
+  | "stage"
+  | "originalCharCount"
+  | "writtenCharCount"
+  | "requirementsPlan"
+  | "warnings"
+  | "summary"
+  | "originalContent"
+  | "rewrittenContent"
+  | "versionId"
+  | "redoVersionId"
+  | "revertedAt"
+  | "error"
+  | "createdAt"
+  | "updatedAt"
+> & {
+  originalContent?: string;
+  rewrittenContent?: string | null;
+  requirementsPlan?: string;
+};
+
+type DocumentRewritePresentationContextValue = {
+  create: (input: CreatePresentationInput) => string;
+  update: (
+    id: string,
+    patch: Partial<Omit<DocumentRewritePresentation, "id" | "threadId" | "createdAt">>,
+  ) => void;
+  forThread: (threadId: string) => DocumentRewritePresentation[];
+};
+
+const DocumentRewritePresentationContext =
+  createContext<DocumentRewritePresentationContextValue | null>(null);
+
+function createId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return "drw-ui-" + crypto.randomUUID();
+  }
+  return "drw-ui-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2);
+}
+
+export function DocumentRewritePresentationProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const [presentations, setPresentations] = useState<DocumentRewritePresentation[]>([]);
+
+  const create = useCallback((input: CreatePresentationInput) => {
+    const id = createId();
+    const now = new Date().toISOString();
+    setPresentations((previous) => [
+      ...previous.slice(-29),
+      {
+        ...input,
+        id,
+        stage: "snapshot",
+        originalCharCount: 0,
+        writtenCharCount: 0,
+        requirementsPlan: input.requirementsPlan ?? "",
+        warnings: [],
+        summary: null,
+        originalContent: input.originalContent ?? "",
+        rewrittenContent: input.rewrittenContent ?? null,
+        versionId: null,
+        redoVersionId: null,
+        revertedAt: null,
+        error: null,
+        createdAt: now,
+        updatedAt: now,
+      },
+    ]);
+    return id;
+  }, []);
+
+  const update = useCallback(
+    (
+      id: string,
+      patch: Partial<Omit<DocumentRewritePresentation, "id" | "threadId" | "createdAt">>,
+    ) => {
+      setPresentations((previous) => {
+        const index = previous.findIndex((item) => item.id === id);
+        if (index < 0) return previous;
+
+        const current = previous[index];
+        const changed = Object.entries(patch).some(
+          ([key, value]) => current[key as keyof DocumentRewritePresentation] !== value,
+        );
+        // Do not create a new context value for an identical update.  Stream
+        // subscribers can legitimately receive an already-hydrated snapshot;
+        // treating it as a state change makes effect-based synchronisation
+        // vulnerable to update loops.
+        if (!changed) return previous;
+
+        const next = [...previous];
+        next[index] = { ...current, ...patch, updatedAt: new Date().toISOString() };
+        return next;
+      });
+    },
+    [],
+  );
+
+  const value = useMemo<DocumentRewritePresentationContextValue>(
+    () => ({
+      create,
+      update,
+      forThread: (threadId) =>
+        presentations.filter((item) => item.threadId === threadId),
+    }),
+    [create, presentations, update],
+  );
+
+  return (
+    <DocumentRewritePresentationContext.Provider value={value}>
+      {children}
+    </DocumentRewritePresentationContext.Provider>
+  );
+}
+
+export function useDocumentRewritePresentation() {
+  return useContext(DocumentRewritePresentationContext);
+}
+
+/** Browser event consumed by the open sandbox after an in-feed undo succeeds. */
+export const DOCUMENT_REWRITE_UNDONE_EVENT = "deerflow:document-rewrite-undone";

frontend-web/src/core/embed/frame-context.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether the application is currently hosted by another page.
+ *
+ * This intentionally covers both a native `<iframe>` and Wujie's child-app
+ * runtime. Accessing `window.top` is safe across origins for identity
+ * comparison, but the guard keeps the login/route bootstrap resilient to
+ * restrictive browser hosts.
+ */
+export function isEmbeddedHost(): boolean {
+  if (typeof window === "undefined") return false;
+
+  const hostWindow = window as Window & {
+    __POWERED_BY_WUJIE__?: boolean;
+  };
+  if (hostWindow.__POWERED_BY_WUJIE__) return true;
+
+  try {
+    return window.self !== window.top;
+  } catch {
+    // Some sandboxed or cross-origin hosts deny top-window access. They are
+    // still embedded contexts and should use the same safe entry route.
+    return true;
+  }
+}

frontend-web/src/core/i18n/locales/en-US.ts

@@ -548,7 +548,10 @@ export const enUS: Translations = {
       filesCopyPathAction: "Copy path",
       filesDiscardConfirm: "Discard unsaved changes?",
       filesSaveSuccess: "File saved",
-      filesReadOnlyHint: "Built-in skills are read-only.",
+      filesDeleteAction: "Delete",
+      filesDeleteConfirm: "Delete \"{path}\"? This cannot be undone.",
+      filesDeleteSuccess: "File deleted",
+      filesReadOnlyHint: "Only administrators can edit or delete built-in skill files.",
       viewDetailAction: "View skill details",
       stateSheet: {
         archivedTitle: "Archived skills",

frontend-web/src/core/i18n/locales/types.ts

@@ -478,6 +478,9 @@ export interface Translations {
       filesCopyPathAction: string;
       filesDiscardConfirm: string;
       filesSaveSuccess: string;
+      filesDeleteAction: string;
+      filesDeleteConfirm: string;
+      filesDeleteSuccess: string;
       filesReadOnlyHint: string;
       viewDetailAction: string;
       stateSheet: {

frontend-web/src/core/i18n/locales/zh-CN.ts

@@ -525,7 +525,10 @@ export const zhCN: Translations = {
       filesCopyPathAction: "复制路径",
       filesDiscardConfirm: "有未保存的修改,确定放弃吗?",
       filesSaveSuccess: "文件已保存",
-      filesReadOnlyHint: "内置技能为只读,仅可查看。",
+      filesDeleteAction: "删除",
+      filesDeleteConfirm: "确定删除“{path}”？该操作不可撤销。",
+      filesDeleteSuccess: "文件已删除",
+      filesReadOnlyHint: "仅管理员可以编辑或删除内置技能文件。",
       viewDetailAction: "查看技能详情",
       stateSheet: {
         archivedTitle: "归档的技能",

frontend-web/src/core/llmwiki/conversation-deposit.ts

@@ -0,0 +1,66 @@
+import type { Message } from "@langchain/langgraph-sdk";
+
+import { textOfMessage } from "@/core/threads/utils";
+import { createLlmWikiConversationDeposit } from "@/strategy-components/api/llmwiki";
+
+function isHidden(message: Message): boolean {
+  const extra = (message as { additional_kwargs?: Record<string, unknown> })
+    .additional_kwargs;
+  return extra?.hide_from_ui === true;
+}
+
+function messageText(message: Message | undefined): string {
+  return (message ? textOfMessage(message) : "")?.trim() ?? "";
+}
+
+function hasText(message: Message | undefined): message is Message {
+  return !!message && messageText(message).length > 0;
+}
+
+export function queueLlmWikiConversationDeposit({
+  threadId,
+  messages,
+  assistantId,
+  knowledgeBaseIds,
+}: {
+  threadId: string | null | undefined;
+  messages: Message[] | undefined;
+  assistantId?: string | null;
+  knowledgeBaseIds?: string[];
+}) {
+  if (!threadId || !messages?.length) {
+    return;
+  }
+  const visible = messages.filter((message) => !isHidden(message));
+  const assistantIndex = [...visible]
+    .map((message, index) => ({ message, index }))
+    .reverse()
+    .find(({ message }) => message.type === "ai" && hasText(message))?.index;
+  if (assistantIndex === undefined) {
+    return;
+  }
+  const assistantMessage = visible[assistantIndex];
+  const humanMessage = [...visible.slice(0, assistantIndex)]
+    .reverse()
+    .find((message) => message.type === "human" && hasText(message));
+  if (!assistantMessage?.id || !humanMessage) {
+    return;
+  }
+  const question = messageText(humanMessage);
+  const answer = messageText(assistantMessage);
+  if (!question || !answer) {
+    return;
+  }
+
+  void createLlmWikiConversationDeposit({
+    thread_id: threadId,
+    question,
+    answer,
+    human_message_id: humanMessage.id ?? null,
+    assistant_message_id: assistantMessage.id,
+    assistant_id: assistantId ?? null,
+    knowledge_base_ids: knowledgeBaseIds ?? [],
+  }).catch((error) => {
+    console.warn("Failed to queue LLMWiki conversation deposit", error);
+  });
+}

frontend-web/src/core/messages/utils.ts

@@ -22,6 +22,8 @@ interface AssistantSetupAgentApprovalGroup extends GenericMessageGroup<"assistan
 
 interface AssistantSetupWritingApprovalGroup extends GenericMessageGroup<"assistant:setup-writing-approval"> {}
 
+interface AssistantResearchApprovalGroup extends GenericMessageGroup<"assistant:research-approval"> {}
+
 interface AssistantSubagentGroup extends GenericMessageGroup<"assistant:subagent"> {}
 
 type MessageGroup =
@@ -32,6 +34,7 @@ type MessageGroup =
   | AssistantClarificationGroup
   | AssistantSetupAgentApprovalGroup
   | AssistantSetupWritingApprovalGroup
+  | AssistantResearchApprovalGroup
   | AssistantSubagentGroup;
 
 export function groupMessages<T>(
@@ -54,7 +57,8 @@ export function groupMessages<T>(
       last.type !== "assistant" &&
       last.type !== "assistant:clarification" &&
       last.type !== "assistant:setup-agent-approval" &&
-      last.type !== "assistant:setup-writing-approval"
+      last.type !== "assistant:setup-writing-approval" &&
+      last.type !== "assistant:research-approval"
     ) {
       return last;
     }
@@ -114,6 +118,18 @@ export function groupMessages<T>(
     }
 
     if (message.type === "ai") {
+      // Deep-research interaction card: virtual ai messages injected by the
+      // workbench (additional_kwargs.setup_research_approval) render through
+      // the host-provided slot. Writing phases use ordinary virtual tool calls
+      // and completed summaries remain normal assistant messages.
+      if (hasResearchApproval(message)) {
+        groups.push({
+          id: message.id,
+          type: "assistant:research-approval",
+          messages: [message],
+        });
+        continue;
+      }
       if (hasPresentFiles(message)) {
         groups.push({
           id: message.id,
@@ -386,6 +402,14 @@ export function isSetupWritingApprovalToolMessage(message: Message) {
   );
 }
 
+export function hasResearchApproval(message: Message) {
+  return (
+    message.type === "ai" &&
+    typeof message.additional_kwargs?.setup_research_approval === "object" &&
+    message.additional_kwargs.setup_research_approval !== null
+  );
+}
+
 export function extractPresentFilesFromMessage(message: Message) {
   if (message.type !== "ai" || !hasPresentFiles(message)) {
     return [];

frontend-web/src/core/model-management/api.ts

@@ -0,0 +1,114 @@
+import { apiFetch } from "@/core/api";
+import { getBackendBaseURL } from "@/core/config";
+
+export interface ManagedModel {
+  name: string;
+  display_name: string | null;
+  description: string | null;
+  use: string;
+  model: string;
+  base_url: string | null;
+  request_timeout: number | null;
+  max_retries: number | null;
+  max_tokens: number | null;
+  temperature: number | null;
+  stream_usage: boolean | null;
+  supports_thinking: boolean;
+  supports_reasoning_effort: boolean;
+  supports_vision: boolean;
+  when_thinking_enabled: Record<string, unknown> | null;
+  when_thinking_disabled: Record<string, unknown> | null;
+  thinking: Record<string, unknown> | null;
+  use_responses_api: boolean | null;
+  output_version: string | null;
+  extra_settings: Record<string, unknown>;
+  api_key_configured: boolean;
+  api_key_source: string | null;
+  source: "config.yaml";
+}
+
+export interface ManagedModelsResponse {
+  models: ManagedModel[];
+  config_path: string;
+  updated_at: string | null;
+}
+
+export interface ModelSavePayload {
+  name: string;
+  display_name?: string | null;
+  description?: string | null;
+  use: string;
+  model: string;
+  api_key?: string;
+  clear_api_key?: boolean;
+  base_url?: string | null;
+  request_timeout?: number | null;
+  max_retries?: number | null;
+  max_tokens?: number | null;
+  temperature?: number | null;
+  stream_usage?: boolean | null;
+  supports_thinking: boolean;
+  supports_reasoning_effort: boolean;
+  supports_vision: boolean;
+  when_thinking_enabled?: Record<string, unknown> | null;
+  when_thinking_disabled?: Record<string, unknown> | null;
+  thinking?: Record<string, unknown> | null;
+  use_responses_api?: boolean | null;
+  output_version?: string | null;
+  extra_settings: Record<string, unknown>;
+}
+
+export interface ModelConnectionTestResult {
+  success: boolean;
+  latency_ms: number;
+  message: string;
+  preview?: string | null;
+}
+
+async function readError(response: Response, fallback: string): Promise<never> {
+  const payload = await response.json().catch(() => null) as { detail?: string } | null;
+  throw new Error(payload?.detail || fallback);
+}
+
+export async function loadManagedModels(): Promise<ManagedModelsResponse> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models`);
+  if (!response.ok) return readError(response, "加载模型配置失败");
+  return response.json() as Promise<ManagedModelsResponse>;
+}
+
+export async function createManagedModel(payload: ModelSavePayload): Promise<ManagedModel> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) return readError(response, "创建模型失败");
+  return response.json() as Promise<ManagedModel>;
+}
+
+export async function updateManagedModel(name: string, payload: ModelSavePayload): Promise<ManagedModel> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models/${encodeURIComponent(name)}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) return readError(response, "保存模型配置失败");
+  return response.json() as Promise<ManagedModel>;
+}
+
+export async function deleteManagedModel(name: string): Promise<void> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models/${encodeURIComponent(name)}`, {
+    method: "DELETE",
+  });
+  if (!response.ok) return readError(response, "删除模型失败");
+}
+
+export async function testManagedModel(model: ModelSavePayload): Promise<ModelConnectionTestResult> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models/test`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model }),
+  });
+  if (!response.ok) return readError(response, "模型连接测试失败");
+  return response.json() as Promise<ModelConnectionTestResult>;
+}

frontend-web/src/core/model-management/hooks.ts

@@ -0,0 +1,52 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import {
+  createManagedModel,
+  deleteManagedModel,
+  loadManagedModels,
+  testManagedModel,
+  updateManagedModel,
+  type ModelSavePayload,
+} from "./api";
+
+export const MANAGED_MODELS_QUERY_KEY = ["admin", "model-config"] as const;
+
+export function useManagedModels() {
+  return useQuery({
+    queryKey: MANAGED_MODELS_QUERY_KEY,
+    queryFn: loadManagedModels,
+    staleTime: 10_000,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function useSaveManagedModel() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({ name, payload, isNew }: { name: string; payload: ModelSavePayload; isNew: boolean }) =>
+      isNew ? createManagedModel(payload) : updateManagedModel(name, payload),
+    onSuccess: async () => {
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: MANAGED_MODELS_QUERY_KEY }),
+        queryClient.invalidateQueries({ queryKey: ["models"] }),
+      ]);
+    },
+  });
+}
+
+export function useTestManagedModel() {
+  return useMutation({ mutationFn: testManagedModel });
+}
+
+export function useDeleteManagedModel() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: deleteManagedModel,
+    onSuccess: async () => {
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: MANAGED_MODELS_QUERY_KEY }),
+        queryClient.invalidateQueries({ queryKey: ["models"] }),
+      ]);
+    },
+  });
+}

frontend-web/src/core/model-management/index.ts

@@ -0,0 +1,2 @@
+export * from "./api";
+export * from "./hooks";

frontend-web/src/core/models/single-round-rag.ts

@@ -0,0 +1,36 @@
+import type { Model } from "./types";
+
+export const SINGLE_ROUND_RAG_MODELS: Model[] = [
+  { id: "single-round-rag-openai3", name: "OpenAI3", model: "OpenAI3", display_name: "Qwen3-32B", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai4", name: "OpenAI4", model: "OpenAI4", display_name: "Qwen3-235B", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai5", name: "OpenAI5", model: "OpenAI5", display_name: "GLM-5", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai6", name: "OpenAI6", model: "OpenAI6", display_name: "Qwen3.5-27B", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai7", name: "OpenAI7", model: "OpenAI7", display_name: "Qwen3-8B", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai9", name: "OpenAI9", model: "OpenAI9", display_name: "四季7B", supports_thinking: true, execution_profile: "single_round_rag" },
+];
+
+export function isSingleRoundRagProfile(
+  context: unknown,
+): boolean {
+  return (
+    typeof context === "object" &&
+    context !== null &&
+    (context as { execution_profile?: unknown }).execution_profile ===
+      "single_round_rag"
+  );
+}
+
+export function isMultiRoundRagProfile(
+  context: unknown,
+): boolean {
+  return (
+    typeof context === "object" &&
+    context !== null &&
+    (context as { execution_profile?: unknown }).execution_profile ===
+      "multi_round_rag"
+  );
+}
+
+export function isFrontendRagProfile(context: unknown): boolean {
+  return isSingleRoundRagProfile(context) || isMultiRoundRagProfile(context);
+}

frontend-web/src/core/models/types.ts

@@ -6,6 +6,8 @@ export interface Model {
   description?: string | null;
   supports_thinking?: boolean;
   supports_reasoning_effort?: boolean;
+  /** Execution profiles handled by the frontend instead of DeerFlow. */
+  execution_profile?: "single_round_rag" | "multi_round_rag";
 }
 
 export interface TokenUsageSettings {

frontend-web/src/core/page-layout/chats-iframe-route.test.mjs

@@ -2,13 +2,19 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import {
+  buildStandardChatRedirectPath,
+  buildFullChatNavigationPath,
+  buildEmbeddedIframeRedirectPath,
   buildChatsIframeRedirectPath,
   buildChatsIframeThreadPath,
+  hasIframePresentationOverride,
   isExplicitBrainyIframeMode,
   isChatsIframeWorkspacePath,
+  resolveChatsIframeEntryRedirect,
   resolvePostLoginRedirectPath,
   resolveForcedThemeForPath,
   resolveStandardChatFallback,
+  shouldUseChatsIframeProtocol,
 } from "./chats-iframe-route.ts";
 
 test("matches only workspace chats_iframe routes", () => {
@@ -37,7 +43,7 @@ test("forces light theme for landing and chats_iframe routes only", () => {
   assert.equal(resolveForcedThemeForPath("/page/workspace/chats/new"), undefined);
 });
 
-test("requires an explicit chatMode=iframe opt-in for the Brainy page", () => {
+test("recognizes an explicit chatMode=iframe independently of the legacy marker", () => {
   assert.equal(isExplicitBrainyIframeMode(""), false);
   assert.equal(isExplicitBrainyIframeMode("?from=iframe"), false);
   assert.equal(isExplicitBrainyIframeMode("?chatMode=full"), false);
@@ -45,34 +51,72 @@ test("requires an explicit chatMode=iframe opt-in for the Brainy page", () => {
   assert.equal(isExplicitBrainyIframeMode("chatMode=IFRAME"), true);
 });
 
-test("upgrades legacy iframe-source routes to the iframe protocol", () => {
+test("keeps bare from=iframe on the original dedicated iframe protocol", () => {
+  assert.equal(
+    resolveStandardChatFallback(
+      "/page/workspace/chats_iframe/new",
+      "?from=iframe",
+    ),
+    null,
+  );
+  assert.equal(shouldUseChatsIframeProtocol("?from=iframe"), true);
+  assert.equal(hasIframePresentationOverride("?from=iframe"), false);
+});
+
+test("uses the dedicated AgentSelector route for a bare embedded host", () => {
+  assert.equal(shouldUseChatsIframeProtocol("", true), true);
+  assert.equal(
+    buildEmbeddedIframeRedirectPath("?ticket=secret&theme=dark-blue"),
+    "/page/workspace/chats_iframe/new?from=iframe&theme=dark-blue",
+  );
+  assert.equal(
+    resolveChatsIframeEntryRedirect(
+      "/page/workspace/chats/new",
+      "",
+      true,
+    ),
+    "/page/workspace/chats_iframe/new?from=iframe",
+  );
+  assert.equal(
+    resolveChatsIframeEntryRedirect(
+      "/page/workspace/chats/thread-123",
+      "",
+      true,
+    ),
+    "/page/workspace/chats_iframe/thread-123?from=iframe",
+  );
+  assert.equal(shouldUseChatsIframeProtocol("?chatMode=full", true), false);
+  assert.equal(shouldUseChatsIframeProtocol("?hideChrome=1", true), false);
+  assert.equal(
+    buildStandardChatRedirectPath("?hideChrome=1"),
+    "/page/workspace/chats/new?hideChrome=1&chatMode=full",
+  );
+});
+
+test("routes legacy iframe links with standard presentation flags to full chat", () => {
+  assert.equal(
+    resolveStandardChatFallback(
+      "/page/workspace/chats_iframe/new",
+      "?from=iframe&hideHeader=1",
+    ),
+    "/page/workspace/chats/new?hideHeader=1&chatMode=full",
+  );
   assert.equal(
     resolveStandardChatFallback(
       "/page/workspace/chats_iframe/new",
       "?from=iframe&hideChrome=1",
     ),
-    "/page/workspace/chats_iframe/new?from=iframe&hideChrome=1&chatMode=iframe",
+    "/page/workspace/chats/new?hideChrome=1&chatMode=full",
   );
-});
-
-test("honors an explicit chat mode over the legacy iframe source", () => {
   assert.equal(
     resolveStandardChatFallback(
       "/page/workspace/chats_iframe/new",
-      "?from=iframe&chatMode=full",
+      "?from=iframe&embed=1&theme=dark-blue",
     ),
-    "/page/workspace/chats/new?chatMode=full",
+    "/page/workspace/chats/new?embed=1&theme=dark-blue&chatMode=full",
-  );
-});
-
-test("treats a blank chat mode as absent for the legacy iframe source", () => {
-  assert.equal(
-    resolveStandardChatFallback(
-      "/page/workspace/chats_iframe/new",
-      "?from=iframe&chatMode=%20%20",
-    ),
-    "/page/workspace/chats_iframe/new?from=iframe&chatMode=iframe",
   );
+  assert.equal(shouldUseChatsIframeProtocol("?from=iframe&hideChrome=1"), false);
+  assert.equal(hasIframePresentationOverride("?from=iframe&embed=1"), true);
 });
 
 test("redirects chats_iframe routes without the iframe source to standard full chat", () => {
@@ -139,32 +183,53 @@ test("forces the iframe theme on the login route without changing normal login",
     ),
     undefined,
   );
+  assert.equal(
+    resolveForcedThemeForPath(
+      "/login",
+      "?from=iframe&hideChrome=1&theme=dark-blue",
+    ),
+    undefined,
+  );
 });
 
-test("preserves the iframe theme in the post-login redirect", () => {
+test("does not add chatMode=iframe to the legacy post-login redirect", () => {
   assert.equal(
     buildChatsIframeRedirectPath("?from=iframe&theme=dark-blue"),
-    "/page/workspace/chats_iframe/new?from=iframe&chatMode=iframe&theme=dark-blue",
+    "/page/workspace/chats_iframe/new?from=iframe&theme=dark-blue",
   );
   assert.equal(
     buildChatsIframeRedirectPath("?from=iframe"),
-    "/page/workspace/chats_iframe/new?from=iframe&chatMode=iframe",
+    "/page/workspace/chats_iframe/new?from=iframe",
   );
   assert.equal(
     buildChatsIframeRedirectPath(
       "?from=iframe&theme=dark-blue&ticket=secret&authToken=secret",
     ),
-    "/page/workspace/chats_iframe/new?from=iframe&chatMode=iframe&theme=dark-blue",
+    "/page/workspace/chats_iframe/new?from=iframe&theme=dark-blue",
   );
 });
 
-test("keeps the iframe redirect ahead of login-method fallbacks", () => {
+test("uses full chat after login when a legacy iframe link sets presentation", () => {
   assert.equal(
     resolvePostLoginRedirectPath(
       "?from=iframe&theme=dark-blue&yUserId=user-1",
       "/page/workspace/chats/new",
     ),
-    "/page/workspace/chats_iframe/new?from=iframe&chatMode=iframe&theme=dark-blue",
+    "/page/workspace/chats_iframe/new?from=iframe&theme=dark-blue",
+  );
+  assert.equal(
+    resolvePostLoginRedirectPath(
+      "?from=iframe&hideChrome=1&theme=dark-blue",
+      "/page/workspace/chats/new",
+    ),
+    "/page/workspace/chats/new?hideChrome=1&chatMode=full",
+  );
+  assert.equal(
+    resolvePostLoginRedirectPath(
+      "?from=iframe&embed=1&theme=dark-blue",
+      "/page/workspace/chats/new",
+    ),
+    "/page/workspace/chats/new?embed=1&theme=dark-blue&chatMode=full",
   );
   assert.equal(
     resolvePostLoginRedirectPath("?yUserId=user-1", "/page/workspace/chats/new"),
@@ -179,7 +244,61 @@ test("preserves iframe theme when a new chat becomes a thread", () => {
       "thread-123",
       "?from=iframe&theme=dark-blue&ticket=secret",
     ),
-    "/page/workspace/chats_iframe/thread-123?from=iframe&chatMode=iframe&theme=dark-blue",
+    "/page/workspace/chats_iframe/thread-123?from=iframe&theme=dark-blue",
+  );
+});
+
+test("normalizes direct regular-chat legacy links according to the same split", () => {
+  assert.equal(
+    resolveChatsIframeEntryRedirect(
+      "/page/workspace/chats/new",
+      "?from=iframe",
+    ),
+    "/page/workspace/chats_iframe/new?from=iframe",
+  );
+  assert.equal(
+    resolveChatsIframeEntryRedirect(
+      "/page/workspace/chats/thread-123",
+      "?from=iframe&hideChrome=1",
+    ),
+    "/page/workspace/chats/thread-123?hideChrome=1&chatMode=full",
+  );
+  assert.equal(
+    resolveChatsIframeEntryRedirect(
+      "/page/workspace/chats/new",
+      "?from=iframe&embed=1&theme=dark-blue",
+    ),
+    "/page/workspace/chats/new?embed=1&theme=dark-blue&chatMode=full",
+  );
+});
+
+test("builds a standard full-chat URL without leaking the legacy marker", () => {
+  assert.equal(
+    buildStandardChatRedirectPath(
+      "?from=iframe&hideHeader=1&ticket=secret",
+    ),
+    "/page/workspace/chats/new?hideHeader=1&chatMode=full",
+  );
+});
+
+test("keeps full-chat presentation flags when the sidebar opens an agent or thread", () => {
+  assert.equal(
+    buildFullChatNavigationPath(
+      "/page/workspace/chats/new?agent=agent-1",
+      "?hideChrome=1&chatMode=full",
+    ),
+    "/page/workspace/chats/new?agent=agent-1&hideChrome=1&chatMode=full",
+  );
+  assert.equal(
+    buildFullChatNavigationPath(
+      "/page/workspace/chats/thread-123",
+      "?embed=1&theme=dark-blue&chatMode=full",
+    ),
+    "/page/workspace/chats/thread-123?embed=1&theme=dark-blue&chatMode=full",
+  );
+  assert.equal(
+    buildFullChatNavigationPath("/page/workspace/chats/new", ""),
+    "/page/workspace/chats/new",
   );
 });
 

frontend-web/src/core/page-layout/chats-iframe-route.ts

@@ -2,15 +2,131 @@ import { resolveEmbedThemeMode } from "../embed/theme-mode.mjs";
 
 const CHATS_IFRAME_PATH = "/page/workspace/chats_iframe/new";
 const IFRAME_LOGIN_SOURCE = "iframe";
+const STANDARD_CHATS_PATH = "/page/workspace/chats";
 
 function toSearchParams(search: string): URLSearchParams {
   return new URLSearchParams(search.startsWith("?") ? search : `?${search}`);
 }
 
+/** Keep the accepted URL booleans aligned with embed-session.ts. */
+function isEnabledPresentationParam(search: string, key: string): boolean {
+  const value = toSearchParams(search).get(key)?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
+}
+
 export function isChatsIframeLogin(search: string): boolean {
   return toSearchParams(search).get("from") === IFRAME_LOGIN_SOURCE;
 }
 
+function isExplicitFullChatMode(search: string): boolean {
+  return (
+    toSearchParams(search).get("chatMode")?.trim().toLowerCase() === "full"
+  );
+}
+
+/**
+ * A bare login URL embedded by an external host has no query parameter to
+ * survive the login redirect. Add the legacy source marker before building
+ * the private chat URL so refreshes and subsequent thread navigation retain
+ * the selected dedicated iframe workspace.
+ */
+export function buildEmbeddedIframeRedirectPath(search: string): string {
+  const source = toSearchParams(search);
+  if (!source.has("from")) {
+    source.set("from", IFRAME_LOGIN_SOURCE);
+  }
+  return buildChatsIframeRedirectPath(source.toString());
+}
+
+/**
+ * `from=iframe` predates the regular embedded-chat presentation flags.  Keep
+ * the two concerns separate: this only answers whether the caller explicitly
+ * asked PageLayout to alter global chrome, not whether it is an iframe page.
+ */
+export function hasIframePresentationOverride(search: string): boolean {
+  return (
+    isEnabledPresentationParam(search, "hideHeader") ||
+    isEnabledPresentationParam(search, "hideChrome") ||
+    isEnabledPresentationParam(search, "embed")
+  );
+}
+
+/**
+ * The private `chats_iframe` transport is the legacy default for
+ * `from=iframe`.  An explicit `chatMode=iframe` always wins, while a caller
+ * that also supplies one of the standard presentation flags deliberately uses
+ * the ordinary full chat workspace instead.
+ */
+export function shouldUseChatsIframeProtocol(
+  search: string,
+  embeddedHost = false,
+): boolean {
+  return (
+    !hasIframePresentationOverride(search) &&
+    (isExplicitBrainyIframeMode(search) ||
+      isChatsIframeLogin(search) ||
+      // The historical bare iframe integration enters `/login/admin` without
+      // any route parameters. Treat that embedded context as the legacy
+      // dedicated AgentSelector page, unless the caller explicitly selected
+      // the standard full-chat mode.
+      (embeddedHost && !isExplicitFullChatMode(search)))
+  );
+}
+
+/**
+ * Build the regular full-chat destination for a legacy iframe entry that has
+ * opted into a standard presentation mode.  Keeping the display flags in the
+ * address bar makes direct links and refreshes deterministic; `from` is
+ * intentionally omitted so the legacy protocol cannot take over again.
+ */
+export function buildStandardChatRedirectPath(
+  search: string,
+  fallbackPath = `${STANDARD_CHATS_PATH}/new`,
+): string {
+  const source = toSearchParams(search);
+  const [pathname, existingQuery = ""] = fallbackPath.split("?");
+  const target = new URLSearchParams(existingQuery);
+
+  for (const key of ["hideHeader", "hideChrome", "embed"] as const) {
+    const value = source.get(key)?.trim();
+    if (value && !target.has(key)) {
+      target.set(key, value);
+    }
+  }
+
+  // `theme` is meaningful only for embed mode, but preserving it here keeps a
+  // refreshed embedded page on the same forced theme before session storage is
+  // restored.
+  const theme = source.get("theme")?.trim();
+  if (theme && target.get("embed")) {
+    target.set("theme", theme);
+  }
+
+  target.set("chatMode", "full");
+  const query = target.toString();
+  return query ? `${pathname}?${query}` : pathname;
+}
+
+/**
+ * Keep an explicitly selected standard-chat presentation while navigating
+ * between `/chats/new` and a concrete chat thread.  Without this, a click in
+ * the full-chat sidebar drops `hideChrome=1&chatMode=full`; an iframe host
+ * then looks like the legacy bare integration and is incorrectly redirected
+ * to the private AgentSelector workspace.
+ *
+ * This deliberately whitelists presentation flags through
+ * `buildStandardChatRedirectPath` instead of copying arbitrary login/query
+ * values into user-facing chat URLs.
+ */
+export function buildFullChatNavigationPath(
+  destinationPath: string,
+  search: string,
+): string {
+  return hasIframePresentationOverride(search) || isExplicitFullChatMode(search)
+    ? buildStandardChatRedirectPath(search, destinationPath)
+    : destinationPath;
+}
+
 /**
  * Preserve only the presentation parameters consumed by the iframe workspace.
  * Login credentials must never be copied into the post-login address bar.
@@ -24,13 +140,11 @@ export function buildChatsIframeRedirectPath(search: string): string {
   }
 
   const requestedMode = source.get("chatMode")?.trim();
-  if (requestedMode) {
+  if (
+    requestedMode?.toLowerCase() === "iframe" ||
+    (!isChatsIframeLogin(search) && requestedMode)
+  ) {
     target.set("chatMode", requestedMode);
-  } else if (isChatsIframeLogin(search)) {
-    // Plugin links historically identify this protocol with `from=iframe`.
-    // Normalize that legacy marker into the explicit mode before handing the
-    // URL to the workspace route, so it does not fall back to the full chat.
-    target.set("chatMode", "iframe");
   }
 
   const theme = source.get("theme")?.trim();
@@ -57,8 +171,12 @@ export function resolvePostLoginRedirectPath(
   search: string,
   fallbackPath: string,
 ): string {
-  return isChatsIframeLogin(search)
+  if (shouldUseChatsIframeProtocol(search)) {
-    ? buildChatsIframeRedirectPath(search)
+    return buildChatsIframeRedirectPath(search);
+  }
+
+  return isChatsIframeLogin(search) && hasIframePresentationOverride(search)
+    ? buildStandardChatRedirectPath(search, fallbackPath)
     : fallbackPath;
 }
 
@@ -69,13 +187,88 @@ export function isChatsIframeWorkspacePath(pathname: string): boolean {
   );
 }
 
+/**
+ * A `from=iframe` link can arrive directly at a regular chat URL instead of
+ * passing through LoginPage. Normalize both entry paths to the same dedicated
+ * protocol workspace, including an existing thread id when one is supplied.
+ */
+export function resolveChatsIframeEntryRedirect(
+  pathname: string,
+  search: string,
+  embeddedHost = false,
+): string | null {
+  const isStandardChatPath =
+    pathname === STANDARD_CHATS_PATH ||
+    pathname === `${STANDARD_CHATS_PATH}/` ||
+    pathname.startsWith(`${STANDARD_CHATS_PATH}/`);
+
+  // Standard presentation flags deliberately bypass the private iframe
+  // protocol. Normalize direct legacy URLs once so the result stays on the
+  // normal full-chat workspace and retains its agent/history sidebar.
+  if (
+    isChatsIframeLogin(search) &&
+    hasIframePresentationOverride(search) &&
+    !isExplicitBrainyIframeMode(search)
+  ) {
+    return isStandardChatPath
+      ? buildStandardChatRedirectPath(search, pathname)
+      : null;
+  }
+
+  const inferredEmbeddedProtocol =
+    embeddedHost &&
+    !hasIframePresentationOverride(search) &&
+    !isExplicitFullChatMode(search) &&
+    !isChatsIframeLogin(search) &&
+    !isExplicitBrainyIframeMode(search);
+  const protocolSearch = inferredEmbeddedProtocol
+    ? `?${new URLSearchParams({
+        ...Object.fromEntries(toSearchParams(search)),
+        from: IFRAME_LOGIN_SOURCE,
+      }).toString()}`
+    : search;
+  const requestsIframeProtocol = shouldUseChatsIframeProtocol(
+    protocolSearch,
+    embeddedHost,
+  );
+  if (!requestsIframeProtocol) {
+    return null;
+  }
+
+  if (pathname === STANDARD_CHATS_PATH || pathname === `${STANDARD_CHATS_PATH}/`) {
+    return buildChatsIframeRedirectPath(protocolSearch);
+  }
+
+  if (!pathname.startsWith(`${STANDARD_CHATS_PATH}/`)) {
+    return null;
+  }
+
+  const routeSuffix = pathname.slice(`${STANDARD_CHATS_PATH}/`.length);
+  if (!routeSuffix || routeSuffix.includes("/")) {
+    return null;
+  }
+
+  if (routeSuffix === "new") {
+    return buildChatsIframeRedirectPath(protocolSearch);
+  }
+
+  try {
+    return buildChatsIframeThreadPath(
+      "/page/workspace",
+      decodeURIComponent(routeSuffix),
+      protocolSearch,
+    );
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The lightweight iframe page is a private transport for the Brainy
  * postMessage protocol, not a general-purpose embedded chat page.
  *
- * Requiring an explicit mode prevents legacy `from=iframe` links, ordinary
+ * `from=iframe` is the legacy equivalent of the explicit mode. Ordinary
- * iframes and micro-frontend containers from accidentally landing on the
+ * iframe/Wujie embedding without either marker remains standard chat.
- * protocol-only page.
  */
 export function isExplicitBrainyIframeMode(search: string): boolean {
   const normalizedSearch = search.startsWith("?") ? search.slice(1) : search;
@@ -95,25 +288,32 @@ export function resolveStandardChatFallback(
   pathname: string,
   search: string,
 ): string | null {
-  if (!isChatsIframeWorkspacePath(pathname) || isExplicitBrainyIframeMode(search)) {
+  if (!isChatsIframeWorkspacePath(pathname)) {
     return null;
   }
 
   const normalizedSearch = search.startsWith("?") ? search.slice(1) : search;
   const params = new URLSearchParams(normalizedSearch);
-  const requestedMode = params.get("chatMode")?.trim();
-  if (isChatsIframeLogin(search) && !requestedMode) {
-    params.set("chatMode", "iframe");
-    const targetSearch = params.toString();
-    return targetSearch ? `${pathname}?${targetSearch}` : pathname;
-  }
-
   const routePrefix = "/page/workspace/chats_iframe/";
   const routeSuffix = pathname.slice(routePrefix.length);
   const targetPath =
     routeSuffix && routeSuffix !== "new"
       ? `/page/workspace/chats/${routeSuffix}`
       : "/page/workspace/chats/new";
+
+  if (
+    isChatsIframeLogin(search) &&
+    hasIframePresentationOverride(search) &&
+    !isExplicitBrainyIframeMode(search)
+  ) {
+    return buildStandardChatRedirectPath(search, targetPath);
+  }
+
+  if (shouldUseChatsIframeProtocol(search)) {
+    // The legacy marker itself is enough. Do not add chatMode=iframe here: it
+    // is an implementation detail and adding it caused a self-redirect loop.
+    return null;
+  }
   params.delete("from");
   params.set("chatMode", "full");
   const targetSearch = params.toString();
@@ -131,7 +331,7 @@ export function resolveForcedThemeForPath(
   const isLoginPath = pathname === "/login" || pathname.startsWith("/login/");
   if (
     isChatsIframeWorkspacePath(pathname) ||
-    (isLoginPath && isChatsIframeLogin(search))
+    (isLoginPath && shouldUseChatsIframeProtocol(search))
   ) {
     const rawTheme = toSearchParams(search).get("theme")?.trim();
     return rawTheme ? resolveEmbedThemeMode(rawTheme) : "light";

frontend-web/src/core/page-layout/sidebar-menu.ts

@@ -35,6 +35,7 @@ import {
   Settings,
   Sparkles,
   Target,
+  Telescope,
   Trophy,
   Users,
 } from "lucide-react";
@@ -92,6 +93,12 @@ export const sidebarMenuItems: MenuItem[] = [
         icon: FileText,
         path: "/page/canvas/ai-writing-chat",
       },
+      {
+        id: "qa-deep-research",
+        label: "深度研究",
+        icon: Telescope,
+        path: "/page/strategy/qa/deep-research",
+      },
     ],
   },
   {
@@ -270,6 +277,13 @@ export const sidebarMenuItems: MenuItem[] = [
         path: "/page/strategy/admin/positions",
         adminOnly: true,
       },
+      {
+        id: "mgmt-position-roles",
+        label: "岗位角色配置",
+        icon: Briefcase,
+        path: "/page/strategy/admin/position-roles",
+        adminOnly: true,
+      },
       {
         id: "mgmt-admin-scheduled-tasks",
         label: "定时任务管理",

frontend-web/src/core/sentiment-agent/api.ts

@@ -0,0 +1,192 @@
+import type { Message } from "@langchain/langgraph-sdk";
+
+import {
+  buildSentimentAgentHeaders,
+  readSentimentAgentEndpoint,
+} from "./config";
+
+/**
+ * 舆情分析智能体走的是外部 AG-UI 协议网关（POST，SSE 返回）：
+ * 请求体为 { threadId, runId, state, tools, context, forwardedProps, messages }，
+ * 返回为 `data: {"type": ...}` 的 SSE 事件流：
+ *   RUN_STARTED / THINKING_TEXT_MESSAGE_START|CONTENT|END /
+ *   TEXT_MESSAGE_START|CONTENT|END / RUN_FINISHED（另有 RUN_ERROR 等异常事件）。
+ */
+
+/** AG-UI 协议消息（请求体里的 messages 数组元素）。 */
+export interface AgUiMessage {
+  role: "user" | "assistant";
+  id: string;
+  content: string;
+}
+
+export interface SentimentAgentRunHandlers {
+  /** 推理（思考）文本开始：reasoning 消息流开始。 */
+  onReasoningStart?: (messageId: string) => void;
+  onReasoningDelta?: (messageId: string, delta: string) => void;
+  /** 正文回答开始：answer 消息流开始。 */
+  onAnswerStart?: (messageId: string) => void;
+  onAnswerDelta?: (messageId: string, delta: string) => void;
+}
+
+function textOfMessage(message: Message): string {
+  if (typeof message.content === "string") return message.content;
+  if (!Array.isArray(message.content)) return "";
+  return message.content
+    .map((part) => {
+      if (typeof part === "string") return part;
+      if (!part || typeof part !== "object") return "";
+      const text = (part as { text?: unknown }).text;
+      return typeof text === "string" ? text : "";
+    })
+    .join("");
+}
+
+/** 把本地会话消息转成 AG-UI 请求的历史消息（过滤空内容）。 */
+export function toAgUiMessages(messages: Message[]): AgUiMessage[] {
+  return messages
+    .filter((message) => message.type === "human" || message.type === "ai")
+    .map((message) => ({
+      role: message.type === "human" ? ("user" as const) : ("assistant" as const),
+      id: message.id ?? "",
+      content: textOfMessage(message),
+    }))
+    .filter((message) => message.content.trim().length > 0);
+}
+
+type SseEvent = {
+  event?: string;
+  data: string;
+};
+
+/** 按 SSE 规范切帧：事件以空行分隔，`data:` 行可能跨多行、帧可能跨 chunk。 */
+function parseSseFrames(buffer: string): { frames: SseEvent[]; rest: string } {
+  const normalized = buffer.replace(/\r\n/g, "\n");
+  const parts = normalized.split("\n\n");
+  const rest = parts.pop() ?? "";
+  const frames: SseEvent[] = [];
+  for (const part of parts) {
+    if (!part.trim()) continue;
+    const dataLines: string[] = [];
+    let eventName: string | undefined;
+    for (const line of part.split("\n")) {
+      if (line.startsWith("data:")) {
+        dataLines.push(line.slice(5).replace(/^ /, ""));
+      } else if (line.startsWith("event:")) {
+        eventName = line.slice(6).replace(/^ /, "");
+      }
+    }
+    if (dataLines.length > 0) {
+      frames.push({ event: eventName, data: dataLines.join("\n") });
+    }
+  }
+  return { frames, rest };
+}
+
+export interface RunSentimentAgentOptions {
+  threadId: string;
+  runId: string;
+  messages: AgUiMessage[];
+  signal: AbortSignal;
+  handlers: SentimentAgentRunHandlers;
+}
+
+/**
+ * 发起一次舆情分析流式问答。resolve 于流正常结束（RUN_FINISHED 或连接关闭）；
+ * 网络错误 / 非 2xx / RUN_ERROR 事件都会 reject（AbortError 由调用方自行忽略）。
+ */
+export async function runSentimentAgent(
+  options: RunSentimentAgentOptions,
+): Promise<void> {
+  const { threadId, runId, messages, signal, handlers } = options;
+  const { apiUrl } = readSentimentAgentEndpoint();
+  if (!apiUrl) {
+    throw new Error("未配置舆情分析接口地址（runtime-config.js 的 VITE_SENTIMENT_AGENT_API_URL）。");
+  }
+
+  const response = await fetch(apiUrl, {
+    method: "POST",
+    headers: buildSentimentAgentHeaders(),
+    signal,
+    body: JSON.stringify({
+      threadId,
+      runId,
+      state: {},
+      tools: [],
+      context: [],
+      forwardedProps: {},
+      messages,
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(`舆情分析服务请求失败（HTTP ${response.status}）。`);
+  }
+  if (!response.body) {
+    throw new Error("舆情分析服务未返回流式响应。");
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const dispatch = (payload: Record<string, unknown>) => {
+    // 样例里思考事件使用 message_id，而正文事件使用 messageId；两种 AG-UI
+    // 字段形式都兼容，避免后端升级/不同事件类型造成流式状态断开。
+    const messageId = String(payload.message_id ?? payload.messageId ?? "");
+    const delta = typeof payload.delta === "string" ? payload.delta : "";
+    switch (payload.type) {
+      case "THINKING_TEXT_MESSAGE_START":
+        handlers.onReasoningStart?.(messageId);
+        break;
+      case "THINKING_TEXT_MESSAGE_CONTENT":
+        handlers.onReasoningDelta?.(messageId, delta);
+        break;
+      case "TEXT_MESSAGE_START":
+        handlers.onAnswerStart?.(messageId);
+        break;
+      case "TEXT_MESSAGE_CONTENT":
+        handlers.onAnswerDelta?.(messageId, delta);
+        break;
+      case "RUN_ERROR": {
+        const message =
+          typeof payload.message === "string" && payload.message
+            ? payload.message
+            : "舆情分析服务返回错误。";
+        throw new Error(message);
+      }
+      default:
+        // RUN_STARTED / *_END / RUN_FINISHED / TOOL_* 等事件不需要驱动 UI。
+        break;
+    }
+  };
+
+  const consumeFrames = (frames: SseEvent[]) => {
+    for (const frame of frames) {
+      let payload: Record<string, unknown>;
+      try {
+        payload = JSON.parse(frame.data) as Record<string, unknown>;
+      } catch {
+        continue; // 解析不了的脏帧直接跳过，不断流。
+      }
+      // RUN_ERROR 会在 dispatch 里抛出业务错误，正常往外传播。
+      dispatch(payload);
+    }
+  };
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      // 某些网关会在最后一帧后直接关闭连接而不补 SSE 的空行分隔符。流已
+      // 结束时剩余缓冲区就是完整帧，补上分隔符后仍要消费，避免丢最后几个字。
+      buffer += decoder.decode();
+      if (buffer.trim()) {
+        const { frames } = parseSseFrames(`${buffer}\n\n`);
+        consumeFrames(frames);
+      }
+      break;
+    }
+    buffer += decoder.decode(value, { stream: true });
+    const { frames, rest } = parseSseFrames(buffer);
+    buffer = rest;
+    consumeFrames(frames);
+  }
+}

frontend-web/src/core/sentiment-agent/config.ts

@@ -0,0 +1,59 @@
+import { readRuntimeEnv } from "@/env";
+
+/**
+ * 舆情分析智能体（前端直连的虚拟智能体）的接入配置。
+ * 接口地址与 Basic Auth 凭据都来自 public/runtime-config.js，部署后可直接改
+ * dist/runtime-config.js 切换环境，无需重新打包。
+ */
+
+/** 该虚拟智能体在路由里的固定 id（/agents/{id}/chats/...）。 */
+export const SENTIMENT_AGENT_ID = "sentiment-analysis";
+
+export interface SentimentAgentEndpoint {
+  apiUrl: string;
+  authUsername: string;
+  authPassword: string;
+}
+
+export function readSentimentAgentEndpoint(): SentimentAgentEndpoint {
+  return {
+    apiUrl: readRuntimeEnv("VITE_SENTIMENT_AGENT_API_URL") ?? "",
+    authUsername: readRuntimeEnv("VITE_SENTIMENT_AGENT_AUTH_USERNAME") ?? "",
+    authPassword: readRuntimeEnv("VITE_SENTIMENT_AGENT_AUTH_PASSWORD") ?? "",
+  };
+}
+
+export function isSentimentAgentConfigured(): boolean {
+  return !!readSentimentAgentEndpoint().apiUrl;
+}
+
+/**
+ * 是否开放舆情分析虚拟智能体。未配置时保持展示，避免旧部署升级后入口意外消失；
+ * 只有运行时配置显式写为 "false" 才关闭。
+ */
+export function isSentimentAgentVisible(): boolean {
+  return readRuntimeEnv("VITE_SENTIMENT_AGENT_VISIBLE") !== "false";
+}
+
+function toBase64(value: string): string {
+  // 凭据按 UTF-8 字节做 Basic Auth base64，避免非 ASCII 字符导致 btoa 抛错。
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+/** 组装请求头：Basic Auth（用户名/密码都配置了才带 Authorization）。 */
+export function buildSentimentAgentHeaders(): Record<string, string> {
+  const { authUsername, authPassword } = readSentimentAgentEndpoint();
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "text/event-stream",
+  };
+  if (authUsername && authPassword) {
+    headers.Authorization = `Basic ${toBase64(`${authUsername}:${authPassword}`)}`;
+  }
+  return headers;
+}

frontend-web/src/core/sentiment-agent/profile.ts

@@ -0,0 +1,55 @@
+/**
+ * 舆情分析智能体的展示信息（名称 / 简介）。
+ * 这是一个前端虚拟智能体（不落库后端 /api/agents），名称与简介保存在
+ * localStorage，可在智能体管理页的编辑弹窗里随时修改。
+ */
+export interface SentimentAgentProfile {
+  name: string;
+  description: string;
+}
+
+const STORAGE_KEY = "deerflow.sentiment-agent.profile";
+
+/** 名称 / 简介 未自定义时的默认文案。 */
+export const DEFAULT_SENTIMENT_AGENT_PROFILE: SentimentAgentProfile = {
+  name: "舆情分析",
+  description:
+    "面向舆情领域的态势问答助手：围绕指定话题或事件，自动梳理舆情脉络、研判发展态势、归纳各方观点与热点走向，输出结构化的分析结论，为舆情应对与决策提供参考。",
+};
+
+export function readSentimentAgentProfile(): SentimentAgentProfile {
+  if (typeof window === "undefined") return { ...DEFAULT_SENTIMENT_AGENT_PROFILE };
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return { ...DEFAULT_SENTIMENT_AGENT_PROFILE };
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return { ...DEFAULT_SENTIMENT_AGENT_PROFILE };
+    }
+    const record = parsed as Record<string, unknown>;
+    const name =
+      typeof record.name === "string" && record.name.trim()
+        ? record.name.trim()
+        : DEFAULT_SENTIMENT_AGENT_PROFILE.name;
+    const description =
+      typeof record.description === "string"
+        ? record.description.trim()
+        : DEFAULT_SENTIMENT_AGENT_PROFILE.description;
+    return { name, description };
+  } catch {
+    return { ...DEFAULT_SENTIMENT_AGENT_PROFILE };
+  }
+}
+
+export function saveSentimentAgentProfile(profile: SentimentAgentProfile): void {
+  if (typeof window === "undefined") return;
+  const name = profile.name.trim() || DEFAULT_SENTIMENT_AGENT_PROFILE.name;
+  const description =
+    profile.description.trim() || DEFAULT_SENTIMENT_AGENT_PROFILE.description;
+  window.localStorage.setItem(
+    STORAGE_KEY,
+    JSON.stringify({ name, description } satisfies SentimentAgentProfile),
+  );
+  // 编辑弹窗可能挂在管理页 / 对话页两处，广播一下让同页签的其他挂载点即时刷新。
+  window.dispatchEvent(new CustomEvent("sentiment-agent-profile-changed"));
+}

frontend-web/src/core/sentiment-agent/use-sentiment-agent-chat.ts

@@ -0,0 +1,187 @@
+import type { Message } from "@langchain/langgraph-sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { runSentimentAgent, toAgUiMessages } from "./api";
+
+const STORAGE_PREFIX = "workspace.sentiment-agent.";
+
+/**
+ * 舆情分析智能体的前端会话状态：消息只存在当前标签页的 sessionStorage，
+ * 不创建后端 thread、不进 LangGraph —— 所有问答都直连外部 AG-UI 网关。
+ * 整体结构参照 use-single-round-rag 的「合成 LangGraph 消息 + 本地持久化」模式。
+ */
+export function useSentimentAgentChat(threadId: string) {
+  const [messages, setMessages] = useState<Message[]>(() =>
+    readStoredMessages(threadId),
+  );
+  const messagesRef = useRef(messages);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const controllerRef = useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    const stored = readStoredMessages(threadId);
+    messagesRef.current = stored;
+    setMessages(stored);
+    setError(null);
+  }, [threadId]);
+
+  useEffect(() => {
+    messagesRef.current = messages;
+  }, [messages]);
+
+  // 卸载 / 切会话时中断进行中的流。
+  useEffect(() => () => controllerRef.current?.abort(), []);
+
+  const stop = useCallback(() => controllerRef.current?.abort(), []);
+
+  const commitMessages = useCallback(
+    (updater: (current: Message[]) => Message[]) => {
+      setMessages((current) => {
+        const next = updater(current);
+        messagesRef.current = next;
+        writeStoredMessages(threadId, next);
+        return next;
+      });
+    },
+    [threadId],
+  );
+
+  const submit = useCallback(
+    async ({ query }: { query: string }) => {
+      if (isLoading) return;
+      const question = query.trim();
+      if (!question) return;
+
+      const assistantId = `sentiment-ai-${crypto.randomUUID()}`;
+      const userMessage: Message = {
+        id: `sentiment-human-${crypto.randomUUID()}`,
+        type: "human",
+        content: [{ type: "text", text: question }],
+        additional_kwargs: {
+          client_ts: new Date().toISOString(),
+          sentiment_agent: true,
+        },
+      };
+      const initialAssistant: Message = {
+        id: assistantId,
+        type: "ai",
+        content: "",
+        additional_kwargs: { sentiment_agent: true },
+      };
+
+      // AG-UI 历史 = 之前已完成的轮次 + 本轮提问。
+      const history = [
+        ...toAgUiMessages(messagesRef.current),
+        { role: "user" as const, id: userMessage.id!, content: question },
+      ];
+
+      commitMessages((current) => [...current, userMessage, initialAssistant]);
+      setError(null);
+      setIsLoading(true);
+
+      const controller = new AbortController();
+      controllerRef.current = controller;
+
+      // 思考 / 正文两个缓冲区 + rAF 合帧刷新：SSE 一轮几千个 delta，
+      // 直接逐条 setState 会造成大量无效渲染。
+      let reasoning = "";
+      let answer = "";
+      let flushScheduled = false;
+      const flush = () => {
+        flushScheduled = false;
+        commitMessages((current) =>
+          current.map((message) =>
+            message.id === assistantId
+              ? ({
+                  ...message,
+                  content: answer,
+                  additional_kwargs: {
+                    ...message.additional_kwargs,
+                    sentiment_agent: true,
+                    reasoning_content: reasoning || null,
+                  },
+                } as Message)
+              : message,
+          ),
+        );
+      };
+      const scheduleFlush = () => {
+        if (flushScheduled) return;
+        flushScheduled = true;
+        requestAnimationFrame(flush);
+      };
+
+      try {
+        await runSentimentAgent({
+          threadId,
+          runId: `run-${crypto.randomUUID()}`,
+          messages: history,
+          signal: controller.signal,
+          handlers: {
+            onReasoningDelta: (_messageId, delta) => {
+              reasoning += delta;
+              scheduleFlush();
+            },
+            onAnswerDelta: (_messageId, delta) => {
+              answer += delta;
+              scheduleFlush();
+            },
+          },
+        });
+        flush();
+      } catch (caught) {
+        flush();
+        if (!isAbortError(caught)) {
+          const message =
+            caught instanceof Error ? caught.message : "舆情分析问答失败。";
+          setError(message);
+          // 一个字都没回答出来时，把错误写进气泡，用户能看到失败原因。
+          if (!answer) {
+            commitMessages((current) =>
+              current.map((item) =>
+                item.id === assistantId
+                  ? ({ ...item, content: message } as Message)
+                  : item,
+              ),
+            );
+          }
+        }
+      } finally {
+        if (controllerRef.current === controller) controllerRef.current = null;
+        setIsLoading(false);
+      }
+    },
+    [commitMessages, isLoading, threadId],
+  );
+
+  return { messages, isLoading, error, submit, stop };
+}
+
+function storageKey(threadId: string) {
+  return `${STORAGE_PREFIX}${threadId}`;
+}
+
+function readStoredMessages(threadId: string): Message[] {
+  if (typeof window === "undefined" || !threadId) return [];
+  try {
+    const raw = window.sessionStorage.getItem(storageKey(threadId));
+    const parsed: unknown = raw ? JSON.parse(raw) : [];
+    return Array.isArray(parsed) ? (parsed as Message[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeStoredMessages(threadId: string, messages: Message[]) {
+  if (typeof window === "undefined" || !threadId) return;
+  try {
+    window.sessionStorage.setItem(storageKey(threadId), JSON.stringify(messages));
+  } catch {
+    // 配额异常不能打断进行中的回答。
+  }
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}

frontend-web/src/core/skill-display/inline-citations.test.ts

@@ -71,6 +71,12 @@ test("keeps half-width syntax working", () => {
   assert.equal(out.includes(citation(3)), true);
 });
 
+test("converts double-bracket RAG references", () => {
+  const out = applyInlineCitations("RAG answer [[1]] and [[2]].", makeSources(2));
+  assert.equal(out.includes(citation(1)), true);
+  assert.equal(out.includes(citation(2)), true);
+});
+
 test("accepts spaced and full-width square brackets", () => {
   const out = applyInlineCitations("参考[ 1 ]和［2］。", makeSources(2));
   assert.equal(out.includes(citation(1)), true);

frontend-web/src/core/skills/api.ts

@@ -412,6 +412,17 @@ export async function deleteCustomSkill(skillName: string): Promise<void> {
   }
 }
 
+/** Delete a built-in skill. The backend permits this only for administrators. */
+export async function deleteBuiltinSkill(skillName: string): Promise<void> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}`,
+    { method: "DELETE" },
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to delete built-in skill");
+  }
+}
+
 export interface SkillFileNode {
   name: string;
   type: "file" | "dir";
@@ -498,6 +509,19 @@ export async function saveSkillFile(
   return response.json() as Promise<SkillFileSaveResponse>;
 }
 
+export async function deleteSkillFile(
+  skillName: string,
+  path: string,
+): Promise<void> {
+  const url =
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/files/content` +
+    `?path=${encodeURIComponent(path)}`;
+  const response = await apiFetch(url, { method: "DELETE" });
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to delete skill file");
+  }
+}
+
 export interface SkillNameZhResponse {
   name: string;
   name_zh: string | null;

frontend-web/src/core/skills/hooks.ts

@@ -6,7 +6,9 @@ import {
 } from "@tanstack/react-query";
 
 import {
+  deleteBuiltinSkill,
   deleteCustomSkill,
+  deleteSkillFile,
   duplicateSkill,
   enableSkill,
   generateMissingSkillNameZh,
@@ -341,3 +343,31 @@ export function useSaveSkillFile() {
     },
   });
 }
+
+export function useDeleteSkillFile() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      skillName,
+      path,
+    }: {
+      skillName: string;
+      path: string;
+    }) => deleteSkillFile(skillName, path),
+    onSuccess: (_data, { skillName, path }) => {
+      void queryClient.invalidateQueries({ queryKey: ["skill-files", skillName] });
+      void queryClient.removeQueries({ queryKey: ["skill-file", skillName, path] });
+    },
+  });
+}
+
+export function useDeleteBuiltinSkill() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: deleteBuiltinSkill,
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ["skills"] });
+      void queryClient.invalidateQueries({ queryKey: ["admin-skills"] });
+    },
+  });
+}

frontend-web/src/core/system-settings/api.ts

@@ -291,6 +291,8 @@ export type CustomThemeBaseMode = "light" | "dark";
 
 export interface CustomThemeColorOverrides {
   button_hover?: string | null;
+  navigation_gradient_start?: string | null;
+  navigation_gradient_end?: string | null;
   selected_background?: string | null;
   border?: string | null;
   muted?: string | null;

frontend-web/src/core/theme/custom-theme.ts

@@ -13,6 +13,8 @@ const BLACK: Rgb = { r: 0, g: 0, b: 0 };
 
 export const CUSTOM_THEME_ADVANCED_KEYS = [
   "button_hover",
+  "navigation_gradient_start",
+  "navigation_gradient_end",
   "selected_background",
   "border",
   "muted",
@@ -146,6 +148,18 @@ export function getCustomThemeTokens(theme: CustomThemeTokenInput): Record<strin
   const primaryHover = optionalHexColor(overrides.button_hover)
     ? toRgb(overrides.button_hover!)
     : defaultPrimaryHover;
+  // Keep the same left → main-colour → right treatment used by the built-in
+  // themes. These two values remain automatic unless the administrator opens
+  // “更多配色” and explicitly overrides one of them.
+  const defaultNavigationGradientStart = mix(primary, BLACK, isDark ? 0.46 : 0.3);
+  const defaultNavigationGradientEnd = mix(primary, WHITE, isDark ? 0.14 : 0.42);
+  const navigationGradientStart = optionalHexColor(overrides.navigation_gradient_start)
+    ? toRgb(overrides.navigation_gradient_start!)
+    : defaultNavigationGradientStart;
+  const navigationGradientEnd = optionalHexColor(overrides.navigation_gradient_end)
+    ? toRgb(overrides.navigation_gradient_end!)
+    : defaultNavigationGradientEnd;
+  const navigationForeground = readableForeground(mix(navigationGradientStart, navigationGradientEnd, 0.5));
   const primaryActive = isDark ? mix(primary, WHITE, 0.2) : mix(primary, BLACK, 0.2);
   const primaryForeground = optionalHexColor(overrides.primary_foreground) ?? readableForeground(primary);
   const buttonForeground = optionalHexColor(theme.text_color) ?? primaryForeground;
@@ -168,6 +182,8 @@ export function getCustomThemeTokens(theme: CustomThemeTokenInput): Record<strin
   const secondaryHex = toHex(secondary);
   const primaryHoverHex = toHex(primaryHover);
   const primaryActiveHex = toHex(primaryActive);
+  const navigationGradientStartHex = toHex(navigationGradientStart);
+  const navigationGradientEndHex = toHex(navigationGradientEnd);
   const sidebarHex = toHex(sidebar);
 
   return {
@@ -177,6 +193,9 @@ export function getCustomThemeTokens(theme: CustomThemeTokenInput): Record<strin
     "--brand-900": actionHex,
     "--brand-950": actionActiveHex,
     "--theme-button-hover": primaryHoverHex,
+    "--navigation-gradient-start": navigationGradientStartHex,
+    "--navigation-gradient-end": navigationGradientEndHex,
+    "--navigation-foreground": navigationForeground,
     "--theme-selected-background": accentHex,
     "--background": backgroundHex,
     "--foreground": foreground,

frontend-web/src/core/threads/hooks.ts

@@ -28,8 +28,11 @@ import type { AgentThread, AgentThreadState } from "./types";
 export type ToolEndEvent = {
   name: string;
   data: unknown;
+  toolCallId?: string;
 };
 
+export type ToolStartEvent = ToolEndEvent;
+
 export type ThreadStreamOptions = {
   threadId?: string | null | undefined;
   context: LocalSettings["context"];
@@ -49,6 +52,7 @@ export type ThreadStreamOptions = {
   threadMetadata?: Record<string, unknown>;
   onStart?: (threadId: string) => void;
   onFinish?: (state: AgentThreadState) => void;
+  onToolStart?: (event: ToolStartEvent) => void;
   onToolEnd?: (event: ToolEndEvent) => void;
 };
 
@@ -240,6 +244,11 @@ const TERMINAL_RUN_STATUSES = new Set([
 // for a while, then reconcile it from the authoritative run/state endpoints.
 const STREAM_RECONCILIATION_IDLE_MS = 12_000;
 const STREAM_RECONCILIATION_POLL_MS = 5_000;
+// A run can legitimately be quiet while a long tool call is in progress, so
+// reconnect more conservatively than the terminal-status check above.  The
+// reconnection only replaces the local SSE reader; the backend run keeps going.
+const STREAM_RECONNECT_IDLE_MS = 30_000;
+const STREAM_RECONNECT_MAX_ATTEMPTS = 3;
 
 async function fetchThreadTitleRefreshState(
   threadId: string,
@@ -449,6 +458,7 @@ export function useThreadStream({
   threadMetadata,
   onStart,
   onFinish,
+  onToolStart,
   onToolEnd,
 }: ThreadStreamOptions) {
   const { t } = useI18n();
@@ -461,21 +471,28 @@ export function useThreadStream({
   const startedRef = useRef(false);
   const lastStreamActivityAtRef = useRef(0);
   const streamReconciliationInFlightRef = useRef(false);
+  const streamReconnectAttemptsRef = useRef(0);
+  const streamReconnectToastShownRef = useRef(false);
+  const streamReconnectFailureToastShownRef = useRef(false);
 
   const markStreamActivity = useCallback(() => {
     lastStreamActivityAtRef.current = Date.now();
+    streamReconnectAttemptsRef.current = 0;
+    streamReconnectToastShownRef.current = false;
+    streamReconnectFailureToastShownRef.current = false;
   }, []);
 
   const listeners = useRef({
     onStart,
     onFinish,
+    onToolStart,
     onToolEnd,
   });
 
   // Keep listeners ref updated with latest callbacks
   useEffect(() => {
-    listeners.current = { onStart, onFinish, onToolEnd };
+    listeners.current = { onStart, onFinish, onToolStart, onToolEnd };
-  }, [onStart, onFinish, onToolEnd]);
+  }, [onStart, onFinish, onToolStart, onToolEnd]);
 
   useEffect(() => {
     const normalizedThreadId = threadId ?? null;
@@ -545,12 +562,6 @@ export function useThreadStream({
     },
     onLangChainEvent(event) {
       markStreamActivity();
-      if (event.event === "on_tool_end") {
-        listeners.current.onToolEnd?.({
-          name: event.name,
-          data: event.data,
-        });
-      }
       // 操作日志(Y-Log)：每一次大模型调用结束都各上报一条（一次 LLM 调用 = 一条），
       // 让问答日志尽量「多、全」——一个问答轮次里 lead agent / 子代理的每次模型调用
       // 都会落一条。门控与失败静默都在 writeYLog 内部处理，绝不影响问答。
@@ -574,6 +585,30 @@ export function useThreadStream({
         }
       }
     },
+    // The SDK emits UI tool lifecycle events on the dedicated `tools` stream
+    // mode. `events` is a separate LangChain trace channel; using it for UI
+    // reactions can miss a tool that the conversation has already rendered.
+    onToolEvent:
+      onToolStart || onToolEnd
+        ? (event) => {
+            markStreamActivity();
+            if (event.event === "on_tool_start") {
+              listeners.current.onToolStart?.({
+                name: event.name,
+                data: event.input,
+                toolCallId: event.toolCallId,
+              });
+              return;
+            }
+            if (event.event === "on_tool_end") {
+              listeners.current.onToolEnd?.({
+                name: event.name,
+                data: event.output,
+                toolCallId: event.toolCallId,
+              });
+            }
+          }
+        : undefined,
     onUpdateEvent(data) {
       markStreamActivity();
       const updates: Array<Partial<AgentThreadState> | null> = Object.values(
@@ -737,13 +772,6 @@ export function useThreadStream({
   threadStreamRef.current = thread;
 
   useEffect(() => {
-    if (!thread.isLoading) {
-      // A normal terminal event reached the browser.  A later run may use the
-      // same thread, so it must be eligible for recovery again.
-      streamReconciliationInFlightRef.current = false;
-      return;
-    }
-
     const activeThreadId = threadIdRef.current ?? onStreamThreadId ?? null;
     if (!activeThreadId || typeof window === "undefined") {
       return;
@@ -752,7 +780,7 @@ export function useThreadStream({
     let disposed = false;
     let refreshTimer: number | null = null;
 
-    const reconcileCompletedRun = async () => {
+    const reconcileRun = async () => {
       if (
         disposed ||
         streamReconciliationInFlightRef.current ||
@@ -769,7 +797,51 @@ export function useThreadStream({
       try {
         const client = getAPIClient(isMock);
         const run = await client.runs.get(activeThreadId, runId);
-        if (disposed || !TERMINAL_RUN_STATUSES.has(run.status)) {
+        if (disposed) {
+          return;
+        }
+
+        if (!TERMINAL_RUN_STATUSES.has(run.status)) {
+          // ``useStream`` retries one failed connection on its own.  If that
+          // reader quietly stalls, however, its internal queue never gets a
+          // terminal error and the page remains frozen despite the backend
+          // continuing the run.  Abort only the local reader, then join the
+          // same run so no work or tokens are lost server-side.
+          if (Date.now() - lastStreamActivityAtRef.current < STREAM_RECONNECT_IDLE_MS) {
+            return;
+          }
+
+          if (streamReconnectAttemptsRef.current >= STREAM_RECONNECT_MAX_ATTEMPTS) {
+            if (!streamReconnectFailureToastShownRef.current) {
+              streamReconnectFailureToastShownRef.current = true;
+              toast.error("回答仍在后台处理中，但页面连接暂未恢复；请稍后返回此会话查看结果。");
+            }
+            return;
+          }
+
+          streamReconnectAttemptsRef.current += 1;
+          // Avoid enqueueing another reconnect before this new reader has had
+          // enough time to receive its first event.  A genuine event resets
+          // the attempt counter through ``markStreamActivity``.
+          lastStreamActivityAtRef.current = Date.now();
+          if (!streamReconnectToastShownRef.current) {
+            streamReconnectToastShownRef.current = true;
+            toast.info("回答连接出现波动，正在自动恢复…");
+          }
+
+          const stream = threadStreamRef.current;
+          void Promise.resolve(stream.stop())
+            .catch(() => {
+              // Stopping a stale local reader is best-effort; joining is still
+              // useful if the SDK already considers the stream stopped.
+            })
+            .finally(() => {
+              if (disposed || threadIdRef.current !== activeThreadId) return;
+              void stream.joinStream(runId).catch(() => {
+                // The status poll will either reconcile a terminal run or
+                // schedule the next bounded reconnect attempt.
+              });
+            });
           return;
         }
 
@@ -777,13 +849,17 @@ export function useThreadStream({
         // receive any more useful events.  Load the checkpoint directly before
         // resetting the SDK stream; this preserves the normal onFinish side
         // effects (e.g. marking a position delivery complete) even when the
-        // browser missed the terminal event.
+        // browser missed the terminal event or already reported a transport
+        // error and dropped ``isLoading``.
         const finalState = await client.threads.getState(activeThreadId);
-        if (disposed || !threadStreamRef.current.isLoading) {
+        if (disposed) {
           return;
         }
 
         storage?.removeItem(`lg:stream:${activeThreadId}`);
+        streamReconnectAttemptsRef.current = 0;
+        streamReconnectToastShownRef.current = false;
+        streamReconnectFailureToastShownRef.current = false;
         if (run.status === "success") {
           listeners.current.onFinish?.(finalState.values as AgentThreadState);
           void queryClient.invalidateQueries({ queryKey: ["threads", "search"] });
@@ -812,7 +888,7 @@ export function useThreadStream({
     };
 
     const interval = window.setInterval(
-      () => void reconcileCompletedRun(),
+      () => void reconcileRun(),
       STREAM_RECONCILIATION_POLL_MS,
     );
 
@@ -1122,8 +1198,19 @@ export function useThreadStream({
           }),
         );
 
+        const mergedContext = {
+          ...context,
+          ...extraContext,
+        };
+        const selectedLlmWikiIds = Array.isArray(
+          mergedContext.llmwiki_knowledge_base_ids,
+        )
+          ? mergedContext.llmwiki_knowledge_base_ids
+          : [];
         const ragModeEnabled =
-          localSettings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
+          localSettings.display.ragModeEnabled ||
+          isThreadRagModeLocked(threadId) ||
+          selectedLlmWikiIds.length > 0;
         if (ragModeEnabled) {
           lockThreadRagMode(threadId);
         }
@@ -1131,11 +1218,6 @@ export function useThreadStream({
         const contextCompressionEnabled =
           localSettings.display.contextCompressionEnabled ?? false;
 
-        const mergedContext = {
-          ...context,
-          ...extraContext,
-        };
-
         const hiddenContextMessages = normalizeHiddenContextMessages(options);
         const submittedMessages: Message[] = [
           ...hiddenContextMessages.map((item) => ({

frontend-web/src/core/threads/types.ts

@@ -25,6 +25,10 @@ export interface AgentThreadContext extends Record<string, unknown> {
   summarization_enabled?: boolean;
   /** Per-conversation switch for knowledge-base RAG injection (phase 2). */
   knowledge_rag_enabled?: boolean;
+  /** DeerFlow LLMWiki mapping ids selected for this conversation. */
+  llmwiki_knowledge_base_ids?: string[];
+  /** Direct RAG modes handled in the frontend; these requests never enter Lead Agent. */
+  execution_profile?: "single_round_rag" | "multi_round_rag";
   agent_id?: string;
   /** @deprecated kept for reading legacy thread metadata; prefer agent_id */
   agent_name?: string;

frontend-web/src/core/threads/use-multi-round-rag.ts

@@ -0,0 +1,483 @@
+import type { Message } from "@langchain/langgraph-sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { readRuntimeEnv } from "@/env";
+
+const STORAGE_PREFIX = "workspace.multi-round-rag.";
+
+export type MultiRoundRagRetrieval = {
+  id?: string;
+  title: string;
+  content: string;
+  source?: string;
+  time?: string;
+  recUuid?: string;
+  url?: string;
+};
+
+export type MultiRoundRagRound = {
+  id: string;
+  title: string;
+  thought: string;
+  /** Model text emitted for this round, before its retrieval results. */
+  body: string;
+  query: string;
+  isSearching: boolean;
+  retrievals: MultiRoundRagRetrieval[];
+};
+
+export type MultiRoundRagTrace = {
+  rounds: MultiRoundRagRound[];
+  answer: string;
+  isComplete: boolean;
+};
+
+type MultiRoundRagSource = {
+  id?: string;
+  title: string;
+  type: string;
+  snippet: string;
+  content: string;
+  source?: string;
+  time?: string;
+  url?: string;
+  raw: Record<string, unknown>;
+};
+
+type MultiRoundEvent = {
+  event?: unknown;
+  data?: unknown;
+};
+
+function storageKey(threadId: string) {
+  return `${STORAGE_PREFIX}${threadId}`;
+}
+
+function readStoredMessages(threadId: string): Message[] {
+  if (typeof window === "undefined" || !threadId) return [];
+  try {
+    const raw = window.sessionStorage.getItem(storageKey(threadId));
+    const parsed: unknown = raw ? JSON.parse(raw) : [];
+    return Array.isArray(parsed) ? (parsed as Message[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeStoredMessages(threadId: string, messages: Message[]) {
+  if (typeof window === "undefined" || !threadId) return;
+  try {
+    window.sessionStorage.setItem(storageKey(threadId), JSON.stringify(messages));
+  } catch {
+    // Storage quota failures must not interrupt a running answer.
+  }
+}
+
+function createId(prefix: string) {
+  return `${prefix}-${crypto.randomUUID()}`;
+}
+
+function isAbortError(error: unknown) {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function parseJson(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return value;
+  }
+}
+
+function parseEventLine(line: string): MultiRoundEvent | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("data:")) return null;
+  try {
+    return JSON.parse(trimmed.slice("data:".length).trim()) as MultiRoundEvent;
+  } catch {
+    return null;
+  }
+}
+
+function initialTrace(): MultiRoundRagTrace {
+  return {
+    rounds: [
+      {
+        id: createId("multi-rag-round"),
+        title: "正在准备检索",
+        thought: "",
+        body: "",
+        query: "",
+        isSearching: true,
+        retrievals: [],
+      },
+    ],
+    answer: "",
+    isComplete: false,
+  };
+}
+
+function latestRound(trace: MultiRoundRagTrace): MultiRoundRagRound {
+  const current = trace.rounds.at(-1);
+  if (current) return current;
+  const next = initialTrace().rounds[0]!;
+  trace.rounds.push(next);
+  return next;
+}
+
+function addThinkingRound(trace: MultiRoundRagTrace, thought: string) {
+  const current = latestRound(trace);
+  if (current.title === "正在准备检索" && !current.thought && !current.query) {
+    current.title = "思考过程";
+    current.thought = thought;
+    return;
+  }
+  current.isSearching = false;
+  trace.rounds.push({
+    id: createId("multi-rag-round"),
+    title: "思考过程",
+    thought,
+    body: "",
+    query: "",
+    isSearching: true,
+    retrievals: [],
+  });
+}
+
+function appendRoundBody(trace: MultiRoundRagTrace, body: string) {
+  if (!body) return;
+  const current = latestRound(trace);
+  // Stored traces created before `body` was introduced remain readable.
+  current.body = `${current.body ?? ""}${body}`;
+}
+
+function mapRetrievals(value: unknown): MultiRoundRagRetrieval[] {
+  const root = asRecord(parseJson(value));
+  const list =
+    (Array.isArray(root?.results) && root.results) ||
+    (Array.isArray(root?.organic) && root.organic) ||
+    [];
+  return list.flatMap((item, index) => {
+    const record = asRecord(item);
+    if (!record) return [];
+    const recUuid = asString(record.recUuid ?? record.rec_uuid);
+    const url = asString(record.url ?? record.link ?? record.href);
+    return [
+      {
+        id: asString(record.id) || recUuid || undefined,
+        title: asString(record.title) || `检索资料 ${index + 1}`,
+        content: asString(record.content ?? record.snippet ?? record.text),
+        source: asString(record.source ?? record.source1 ?? url) || undefined,
+        time: asString(record.publish_time ?? record.m_publish ?? record.date) || undefined,
+        recUuid: recUuid || undefined,
+        url: /^https?:\/\//i.test(url) ? url : undefined,
+      },
+    ];
+  });
+}
+
+function mapReferences(value: unknown): MultiRoundRagSource[] {
+  const record = asRecord(value);
+  const list = Array.isArray(record?.references) ? record.references : [];
+  return list.flatMap((item, index) => {
+    const source = asRecord(item);
+    if (!source) return [];
+    const content = asString(source.content ?? source.snippet);
+    const rawUrl = asString(source.url ?? source.link ?? source.href);
+    const recUuid = asString(source.recUuid ?? source.rec_uuid ?? source.uuid);
+    return [
+      {
+        id: asString(source.id) || recUuid || undefined,
+        title: asString(source.title) || `参考资料 ${index + 1}`,
+        type: asString(source.type) || "参考资料",
+        snippet: asString(source.snippet) || content,
+        content,
+        source: asString(source.source ?? source.source1) || undefined,
+        time: asString(source.time ?? source.m_publish ?? source.publish_time) || undefined,
+        url: /^https?:\/\//i.test(rawUrl) ? rawUrl : undefined,
+        raw: source,
+      },
+    ];
+  });
+}
+
+function cloneTrace(trace: MultiRoundRagTrace): MultiRoundRagTrace {
+  return {
+    ...trace,
+    rounds: trace.rounds.map((round) => ({
+      ...round,
+      retrievals: [...round.retrievals],
+    })),
+  };
+}
+
+function isSingleRoundRagMessage(message: Message) {
+  return message.additional_kwargs?.single_round_rag === true;
+}
+
+export function isMultiRoundRagMessage(message: Message): boolean {
+  return message.additional_kwargs?.multi_round_rag === true;
+}
+
+export function getMultiRoundRagTrace(
+  message: Message,
+): MultiRoundRagTrace | null {
+  const trace = message.additional_kwargs?.multi_round_rag_trace;
+  return asRecord(trace)
+    ? (trace as unknown as MultiRoundRagTrace)
+    : null;
+}
+
+/**
+ * Frontend adapter for GeneralQA's multi-round endpoint. It keeps the external
+ * SSE protocol outside DeerFlow and stores only its UI messages in sessionStorage.
+ */
+export function useMultiRoundRagMessages(threadId: string) {
+  const [messages, setMessages] = useState<Message[]>(() => readStoredMessages(threadId));
+  const messagesRef = useRef(messages);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const controllerRef = useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    const stored = readStoredMessages(threadId);
+    messagesRef.current = stored;
+    setMessages(stored);
+    setError(null);
+  }, [threadId]);
+
+  useEffect(() => {
+    messagesRef.current = messages;
+  }, [messages]);
+
+  useEffect(() => () => controllerRef.current?.abort(), []);
+
+  const updateMessages = useCallback(
+    (targetThreadId: string, updater: (current: Message[]) => Message[]) => {
+      setMessages((current) => {
+        const next = updater(current);
+        messagesRef.current = next;
+        writeStoredMessages(targetThreadId, next);
+        return next;
+      });
+    },
+    [],
+  );
+
+  const stop = useCallback(() => controllerRef.current?.abort(), []);
+
+  const submit = useCallback(
+    async ({ targetThreadId, query }: { targetThreadId: string; query: string }) => {
+      if (isLoading) return;
+      const question = query.trim();
+      if (!question) return;
+
+      const humanId = createId("multi-rag-human");
+      const assistantId = createId("multi-rag-ai");
+      const sourceId = createId("multi-rag-sources");
+      const trace = initialTrace();
+      let sources: MultiRoundRagSource[] = [];
+      const clientTs = new Date().toISOString();
+      const userMessage: Message = {
+        id: humanId,
+        type: "human",
+        content: [{ type: "text", text: question }],
+        additional_kwargs: { client_ts: clientTs, multi_round_rag: true },
+      };
+      const assistantMessage: Message = {
+        id: assistantId,
+        type: "ai",
+        content: "",
+        additional_kwargs: {
+          multi_round_rag: true,
+          multi_round_rag_trace: trace,
+        },
+      };
+      updateMessages(targetThreadId, (current) => [
+        ...current,
+        userMessage,
+        assistantMessage,
+      ]);
+      setError(null);
+      setIsLoading(true);
+
+      const controller = new AbortController();
+      controllerRef.current = controller;
+      const refreshAssistant = () => {
+        const traceSnapshot = cloneTrace(trace);
+        updateMessages(targetThreadId, (current) => {
+          const next = current.filter((message) => message.id !== sourceId);
+          const assistantIndex = next.findIndex((message) => message.id === assistantId);
+          if (assistantIndex < 0) return current;
+          next[assistantIndex] = {
+            ...next[assistantIndex],
+            content: traceSnapshot.answer,
+            additional_kwargs: {
+              ...next[assistantIndex]!.additional_kwargs,
+              multi_round_rag: true,
+              multi_round_rag_trace: traceSnapshot,
+              reasoning_content: traceSnapshot.rounds
+                .map((round) => round.thought)
+                .filter(Boolean)
+                .join("\n\n") || null,
+            },
+          } as Message;
+          if (sources.length > 0) {
+            next.splice(assistantIndex, 0, {
+              id: sourceId,
+              type: "tool",
+              name: "multi_round_rag_references",
+              content: { results: sources },
+              additional_kwargs: {
+                hide_from_ui: true,
+                multi_round_rag: true,
+              },
+            } as unknown as Message);
+          }
+          return next;
+        });
+      };
+
+      try {
+        const baseUrl = readRuntimeEnv("VITE_AIPI_GENERATE_CHAT_URL") || "";
+        if (!baseUrl) {
+          throw new Error("未配置 VITE_AIPI_GENERATE_CHAT_URL，无法发起多轮 RAG 问答。");
+        }
+        const response = await fetch(`${baseUrl.replace(/\/$/, "")}/generate`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          signal: controller.signal,
+          body: JSON.stringify({ prompt: question }),
+        });
+        if (!response.ok) {
+          throw new Error(`多轮 RAG 服务请求失败（${response.status}）。`);
+        }
+        if (!response.body) {
+          throw new Error("多轮 RAG 服务未返回流式响应。");
+        }
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split(/\r?\n/);
+          buffer = lines.pop() ?? "";
+          for (const line of lines) {
+            const event = parseEventLine(line);
+            if (!event) continue;
+            const eventType = asString(event.event);
+            const data = event.data;
+            if (eventType === "tool_call") {
+              const tool = asRecord(data);
+              const toolName = asString(tool?.tool_name);
+              const input = asRecord(tool?.tool_input) ?? {};
+              const current = latestRound(trace);
+              if (toolName === "show_text") {
+                const text = asString(input.text);
+                if (text.includes("<think>")) {
+                  const thinkEnd = text.indexOf("</think>");
+                  addThinkingRound(
+                    trace,
+                    (thinkEnd >= 0
+                      ? text.slice(0, thinkEnd + "</think>".length)
+                      : text
+                    )
+                      .replace(/<\/?think>/g, "")
+                      .trim(),
+                  );
+                  if (thinkEnd >= 0) {
+                    const roundBody = text
+                      .slice(thinkEnd + "</think>".length)
+                      .trim();
+                    if (roundBody) {
+                      appendRoundBody(trace, roundBody);
+                    }
+                  }
+                } else {
+                  // A non-thinking `show_text` immediately after a thought is
+                  // this round's narrative; the terminal `message` event is
+                  // still rendered only as the final answer below all rounds.
+                  current.isSearching = false;
+                  trace.answer += text;
+                  trace.isComplete = true;
+                }
+              } else if (
+                toolName === "local_search" ||
+                toolName === "tavily_search" ||
+                toolName === "google_search"
+              ) {
+                const queryData = asRecord(parseJson(input.result));
+                current.title =
+                  toolName === "local_search" ? "本地知识检索" : "联网检索";
+                current.query =
+                  asString(input.q ?? input.query) ||
+                  asString(queryData?.query) ||
+                  current.query;
+                const retrievals = mapRetrievals(input.result);
+                if (retrievals.length > 0) current.retrievals = retrievals;
+                current.isSearching = false;
+              } else if (toolName === "get_textid_content") {
+                const article = asRecord(parseJson(input.result));
+                const body =
+                  asString(article?.content ?? article?.text) ||
+                  asString(input.content);
+                if (body) appendRoundBody(trace, body);
+                current.isSearching = false;
+              }
+              refreshAssistant();
+            } else if (eventType === "message" && typeof data === "string") {
+              latestRound(trace).isSearching = false;
+              trace.answer += data;
+              trace.isComplete = true;
+              refreshAssistant();
+            } else if (eventType === "references") {
+              sources = mapReferences(data);
+              refreshAssistant();
+            } else if (eventType === "done") {
+              trace.isComplete = true;
+              for (const round of trace.rounds) round.isSearching = false;
+              refreshAssistant();
+            }
+          }
+        }
+        trace.isComplete = true;
+        for (const round of trace.rounds) round.isSearching = false;
+        refreshAssistant();
+      } catch (caught) {
+        trace.isComplete = true;
+        for (const round of trace.rounds) round.isSearching = false;
+        if (!isAbortError(caught)) {
+          const message =
+            caught instanceof Error ? caught.message : "多轮 RAG 问答失败。";
+          setError(message);
+          if (!trace.answer) trace.answer = message;
+        }
+        refreshAssistant();
+      } finally {
+        if (controllerRef.current === controller) controllerRef.current = null;
+        setIsLoading(false);
+      }
+    },
+    [isLoading, updateMessages],
+  );
+
+  return { messages, isLoading, error, submit, stop };
+}
+
+export function isFrontendRagMessage(message: Message): boolean {
+  return isSingleRoundRagMessage(message) || isMultiRoundRagMessage(message);
+}

frontend-web/src/core/threads/use-single-round-rag.ts

@@ -0,0 +1,432 @@
+import type { Message } from "@langchain/langgraph-sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { readRuntimeEnv } from "@/env";
+
+const STORAGE_PREFIX = "workspace.single-round-rag.";
+
+type KnowledgeBaseChunk = {
+  answer?: unknown;
+  docs?: unknown;
+};
+
+type RagSource = {
+  id?: string;
+  title: string;
+  type: string;
+  snippet: string;
+  content: string;
+  source?: string;
+  time?: string;
+  url?: string;
+  raw: Record<string, unknown>;
+};
+
+type RagHistoryEntry = {
+  role: "user" | "assistant";
+  content: string;
+};
+
+const MAX_HISTORY_MESSAGES = 12;
+
+/** Same JSON-object framing used by the established GeneralQA single-RAG flow. */
+function extractJsonObjects(raw: string): { objects: string[]; rest: string } {
+  const objects: string[] = [];
+  let depth = 0;
+  let stringQuote: '"' | "'" | null = null;
+  let escaped = false;
+  let start = -1;
+  for (let index = 0; index < raw.length; index += 1) {
+    const char = raw[index]!;
+    if (stringQuote) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === stringQuote) stringQuote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      stringQuote = char;
+      continue;
+    }
+    if (char === "{") {
+      if (depth === 0) start = index;
+      depth += 1;
+    } else if (char === "}") {
+      depth -= 1;
+      if (depth === 0 && start !== -1) {
+        objects.push(raw.slice(start, index + 1));
+        start = -1;
+      }
+    }
+  }
+  return depth > 0 && start !== -1
+    ? { objects, rest: raw.slice(start) }
+    : { objects, rest: "" };
+}
+
+/** Same `<think>` split semantics as GeneralQA, kept local to avoid loading its demo data. */
+function parseSingleRagStream(chunks: { answer: string }[]) {
+  let thinkingMarkdown = "";
+  let answerMarkdown = "";
+  let inThink = false;
+  let thinkingComplete = false;
+  for (const { answer } of chunks) {
+    let remaining = answer;
+    while (remaining) {
+      if (inThink) {
+        const endIndex = remaining.indexOf("</think>");
+        if (endIndex === -1) {
+          thinkingMarkdown += remaining;
+          remaining = "";
+        } else {
+          thinkingMarkdown += remaining.slice(0, endIndex);
+          remaining = remaining.slice(endIndex + "</think>".length);
+          inThink = false;
+          thinkingComplete = true;
+        }
+      } else {
+        const startIndex = remaining.indexOf("<think>");
+        if (startIndex === -1) {
+          answerMarkdown += remaining;
+          remaining = "";
+        } else {
+          answerMarkdown += remaining.slice(0, startIndex);
+          remaining = remaining.slice(startIndex + "<think>".length);
+          inThink = true;
+        }
+      }
+    }
+  }
+  return { thinkingMarkdown, answerMarkdown, thinkingComplete };
+}
+
+function storageKey(threadId: string) {
+  return `${STORAGE_PREFIX}${threadId}`;
+}
+
+function readStoredMessages(threadId: string): Message[] {
+  if (typeof window === "undefined" || !threadId) return [];
+  try {
+    const raw = window.sessionStorage.getItem(storageKey(threadId));
+    const parsed: unknown = raw ? JSON.parse(raw) : [];
+    return Array.isArray(parsed) ? (parsed as Message[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeStoredMessages(threadId: string, messages: Message[]) {
+  if (typeof window === "undefined" || !threadId) return;
+  try {
+    window.sessionStorage.setItem(storageKey(threadId), JSON.stringify(messages));
+  } catch {
+    // Quota errors must never interrupt an already-running answer.
+  }
+}
+
+function parseLooseStringValue(rawValue: string): string {
+  try {
+    return JSON.parse(rawValue) as string;
+  } catch {
+    const value = rawValue.trim();
+    if (value.startsWith("'") && value.endsWith("'")) {
+      return value
+        .slice(1, -1)
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\r")
+        .replace(/\\t/g, "\t")
+        .replace(/\\'/g, "'")
+        .replace(/\\\\/g, "\\");
+    }
+    throw new Error(`无法解析知识库流片段：${rawValue}`);
+  }
+}
+
+function parseKnowledgeBaseChunk(jsonText: string): KnowledgeBaseChunk {
+  try {
+    return JSON.parse(jsonText) as KnowledgeBaseChunk;
+  } catch {
+    const objectText = jsonText.trim();
+    const answerMatch = objectText.match(/^\{\s*answer\s*:\s*([\s\S]*)\s*\}$/);
+    if (answerMatch) {
+      return { answer: parseLooseStringValue(answerMatch[1]!.trim()) };
+    }
+    const docsMatch = objectText.match(/^\{\s*docs\s*:\s*([\s\S]*)\s*\}$/);
+    if (docsMatch) {
+      const rawValue = docsMatch[1]!.trim();
+      try {
+        return { docs: JSON.parse(rawValue) };
+      } catch {
+        return { docs: parseLooseStringValue(rawValue) };
+      }
+    }
+    const normalizedText = objectText.replace(
+      /([{,]\s*)(answer|docs)(\s*:)/g,
+      '$1"$2"$3',
+    );
+    return JSON.parse(normalizedText) as KnowledgeBaseChunk;
+  }
+}
+
+function flattenDocs(value: unknown): Record<string, unknown>[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => flattenDocs(item));
+  }
+  if (!value || typeof value !== "object") return [];
+  const record = value as Record<string, unknown>;
+  if ("docs" in record) return flattenDocs(record.docs);
+  return [record];
+}
+
+function normalizeSources(value: unknown): RagSource[] {
+  return flattenDocs(value).map((item, index) => {
+    const title = String(item.m_title ?? item.title ?? item.source ?? `参考资料 ${index + 1}`);
+    const content = String(item.m_content ?? item.content ?? item.snippet ?? "");
+    const source = item.source1 ?? item.source;
+    const rawUrl = item.url ?? item.link ?? item.href;
+    return {
+      id: String(item.recUuid ?? item.rec_uuid ?? item.uuid ?? item.id ?? "") || undefined,
+      title,
+      type: String(item.source1 ?? item.type ?? "知识库"),
+      snippet: content,
+      content,
+      source: typeof source === "string" ? source : undefined,
+      time: typeof item.m_publish === "string" ? item.m_publish : undefined,
+      url: typeof rawUrl === "string" && /^https?:\/\//i.test(rawUrl) ? rawUrl : undefined,
+      raw: item,
+    };
+  });
+}
+
+function createId(prefix: string) {
+  return `${prefix}-${crypto.randomUUID()}`;
+}
+
+function isAbortError(error: unknown) {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+function textFromMessage(message: Message): string {
+  if (typeof message.content === "string") {
+    return message.content.trim();
+  }
+  if (!Array.isArray(message.content)) {
+    return "";
+  }
+  return message.content
+    .map((part) => {
+      if (typeof part === "string") return part;
+      if (!part || typeof part !== "object") return "";
+      const text = (part as { text?: unknown }).text;
+      return typeof text === "string" ? text : "";
+    })
+    .join("\n")
+    .trim();
+}
+
+/**
+ * The general-QA endpoint accepts the usual `{ role, content }` history
+ * format. Keep it scoped to completed single-round-RAG turns so a normal
+ * DeerFlow conversation never leaks into this external endpoint.
+ */
+function buildRagHistory(messages: Message[]): RagHistoryEntry[] {
+  return messages
+    .filter(
+      (message) =>
+        message.additional_kwargs?.single_round_rag === true &&
+        (message.type === "human" || message.type === "ai"),
+    )
+    .map((message): RagHistoryEntry => ({
+      role: message.type === "human" ? "user" : "assistant",
+      content: textFromMessage(message),
+    }))
+    .filter((entry) => entry.content.length > 0)
+    .slice(-MAX_HISTORY_MESSAGES);
+}
+
+export function isSingleRoundRagMessage(message: Message): boolean {
+  return message.additional_kwargs?.single_round_rag === true;
+}
+
+/**
+ * Frontend-only adapter for the existing general-QA single-round endpoint.
+ * It deliberately never submits a run to DeerFlow or mutates the Lead Agent.
+ */
+export function useSingleRoundRagMessages(threadId: string) {
+  const [messages, setMessages] = useState<Message[]>(() => readStoredMessages(threadId));
+  const messagesRef = useRef(messages);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const controllerRef = useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    const stored = readStoredMessages(threadId);
+    messagesRef.current = stored;
+    setMessages(stored);
+    setError(null);
+  }, [threadId]);
+
+  useEffect(() => {
+    messagesRef.current = messages;
+  }, [messages]);
+
+  useEffect(() => () => controllerRef.current?.abort(), []);
+
+  const updateMessages = useCallback(
+    (targetThreadId: string, updater: (current: Message[]) => Message[]) => {
+      setMessages((current) => {
+        const next = updater(current);
+        messagesRef.current = next;
+        writeStoredMessages(targetThreadId, next);
+        return next;
+      });
+    },
+    [],
+  );
+
+  const stop = useCallback(() => controllerRef.current?.abort(), []);
+
+  const submit = useCallback(
+    async ({
+      targetThreadId,
+      query,
+      modelName,
+    }: {
+      targetThreadId: string;
+      query: string;
+      modelName: string;
+    }) => {
+      if (isLoading) return;
+      const question = query.trim();
+      if (!question) return;
+
+      const humanId = createId("single-rag-human");
+      const assistantId = createId("single-rag-ai");
+      const sourceId = createId("single-rag-sources");
+      const clientTs = new Date().toISOString();
+      const history = buildRagHistory(messagesRef.current);
+      const userMessage: Message = {
+        id: humanId,
+        type: "human",
+        content: [{ type: "text", text: question }],
+        additional_kwargs: { client_ts: clientTs, single_round_rag: true },
+      };
+      const initialAssistant: Message = {
+        id: assistantId,
+        type: "ai",
+        content: "",
+        additional_kwargs: { single_round_rag: true },
+      };
+      updateMessages(targetThreadId, (current) => [...current, userMessage, initialAssistant]);
+      setError(null);
+      setIsLoading(true);
+
+      const controller = new AbortController();
+      controllerRef.current = controller;
+      const answerChunks: { answer: string }[] = [];
+      let sources: RagSource[] = [];
+
+      const refreshAssistant = () => {
+        const trace = parseSingleRagStream(answerChunks);
+        updateMessages(targetThreadId, (current) => {
+          const next = current.filter((message) => message.id !== sourceId);
+          const assistantIndex = next.findIndex((message) => message.id === assistantId);
+          if (assistantIndex < 0) return current;
+          next[assistantIndex] = {
+            ...next[assistantIndex],
+            content: trace.answerMarkdown,
+            additional_kwargs: {
+              ...next[assistantIndex]!.additional_kwargs,
+              single_round_rag: true,
+              reasoning_content: trace.thinkingMarkdown || null,
+            },
+          } as Message;
+          if (sources.length > 0) {
+            next.splice(assistantIndex, 0, {
+              id: sourceId,
+              type: "tool",
+              name: "knowledge_base_search",
+              content: { results: sources },
+              additional_kwargs: {
+                hide_from_ui: true,
+                single_round_rag: true,
+              },
+            } as unknown as Message);
+          }
+          return next;
+        });
+      };
+
+      try {
+        const chatUrl = readRuntimeEnv("VITE_AIPI_CHAT_URL") || "";
+        if (!chatUrl) {
+          throw new Error("未配置 VITE_AIPI_CHAT_URL，无法发起单轮 RAG 问答。");
+        }
+        const response = await fetch(
+          `${chatUrl.replace(/\/$/, "")}/chat/knowledge_base_chat_tiaoshi`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            signal: controller.signal,
+            body: JSON.stringify({
+              query: question,
+              knowledge_base_name: [],
+              top_k: 5,
+              score_threshold: 0.5,
+              history,
+              stream: true,
+              model_name: modelName,
+              temperature: 0.3,
+              prompt_name: "default",
+              local_doc_url: false,
+            }),
+          },
+        );
+        if (!response.ok) throw new Error(`知识库服务请求失败（${response.status}）`);
+        if (!response.body) throw new Error("知识库服务未返回流式响应。");
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const extracted = extractJsonObjects(buffer);
+          buffer = extracted.rest;
+          for (const jsonText of extracted.objects) {
+            const chunk = parseKnowledgeBaseChunk(jsonText);
+            if (typeof chunk.answer === "string") answerChunks.push({ answer: chunk.answer });
+            if (chunk.docs !== undefined) sources = normalizeSources(chunk.docs);
+            refreshAssistant();
+          }
+        }
+      } catch (caught) {
+        if (!isAbortError(caught)) {
+          const message = caught instanceof Error ? caught.message : "单轮 RAG 问答失败。";
+          setError(message);
+          updateMessages(targetThreadId, (current) =>
+            current.map((item) =>
+              item.id === assistantId
+                ? ({
+                    ...item,
+                    content: answerChunks.length > 0 ? item.content : message,
+                    additional_kwargs: {
+                      ...item.additional_kwargs,
+                      single_round_rag: true,
+                    },
+                  } as Message)
+                : item,
+            ),
+          );
+        }
+      } finally {
+        if (controllerRef.current === controller) controllerRef.current = null;
+        setIsLoading(false);
+      }
+    },
+    [isLoading, updateMessages],
+  );
+
+  return { messages, isLoading, error, submit, stop };
+}

frontend-web/src/eightbf-roundtable/pages/EightBfRoundtablePage.tsx

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
-import { Check, Loader2, Save, Settings2, X } from "lucide-react";
+import { Loader2, Save, Settings2, X } from "lucide-react";
 
-import { getStoredAuth } from "@/core/auth";
+import { getAccountDisplayName, getStoredAuth } from "@/core/auth";
+import { PositionBusinessChainFlow } from "@/position-roundtable/components/PositionBusinessChainFlow";
 import RoundtablePlanningPage from "@/roundtable-planning/pages/RoundtablePlanningPage";
 import { listChains } from "@/roundtable-planning/api/chains";
 import type { BusinessChain } from "@/roundtable-planning/lib/business-chain";
@@ -25,7 +26,9 @@ const BUSINESS_CODE = "8BF";
  */
 export default function EightBfRoundtablePage({ compactChrome = false }: { compactChrome?: boolean }) {
   const auth = getStoredAuth();
-  const isAdmin = auth?.system_role === "admin";
+  // 8BF 公共业务链由指定账号维护，不依赖外部透传的管理员角色。
+  // 与敏感词管理使用同一可信账户展示名规则（登录邮箱 @ 前缀）。
+  const canConfigureChain = getAccountDisplayName(auth).toLowerCase() === "lqq";
   const storageTaskId = useMemo(() => `8bf:${auth?.user_id || "anonymous"}`, [auth?.user_id]);
   const [mapping, setMapping] = useState<BusinessMapping | null>(null);
   const [chains, setChains] = useState<BusinessChain[]>([]);
@@ -34,6 +37,10 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa
   const [selectedChainId, setSelectedChainId] = useState("");
   const [isSaving, setIsSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const configuredChain = useMemo(
+    () => chains.find((chain) => chain.id === mapping?.chainId) ?? null,
+    [chains, mapping?.chainId],
+  );
 
   const loadConfiguration = useCallback(async () => {
     setIsLoading(true);
@@ -41,7 +48,7 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa
     try {
       const [mappings, availableChains] = await Promise.all([
         listBusinessMappings(),
-        listChains(isAdmin ? "all" : "public"),
+        listChains("public"),
       ]);
       const nextMapping = mappings.find((item) => item.businessCode === BUSINESS_CODE) ?? null;
       // 8BF 只允许绑定已发布业务链；后端同样会进行二次校验。
@@ -54,13 +61,17 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa
     } finally {
       setIsLoading(false);
     }
-  }, [isAdmin]);
+  }, []);
 
   useEffect(() => {
     void loadConfiguration();
   }, [loadConfiguration]);
 
   const handleSave = useCallback(async () => {
+    if (!canConfigureChain) {
+      setError("仅 lqq 账号可以配置 8BF 业务链条");
+      return;
+    }
     const selected = chains.find((chain) => chain.id === selectedChainId);
     if (!selected) {
       setError("请选择一条已发布的业务链");
@@ -81,17 +92,11 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa
     } finally {
       setIsSaving(false);
     }
-  }, [chains, selectedChainId]);
+  }, [canConfigureChain, chains, selectedChainId]);
 
   const toolbarSlot = (
     <>
-      <div className="eightbf-roundtable__chain-status" aria-live="polite">
+      {canConfigureChain && (
-        <span className="eightbf-roundtable__chain-status-label">8BF 业务链</span>
-        <span className="eightbf-roundtable__chain-status-value">
-          {isLoading ? "加载中…" : mapping?.chainTitle || "待管理员配置"}
-        </span>
-      </div>
-      {isAdmin && (
         <button
           type="button"
           className="eightbf-roundtable__chain-settings-button"
@@ -101,7 +106,7 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa
           配置业务链
         </button>
       )}
-      {isSettingsOpen && (
+      {canConfigureChain && isSettingsOpen && (
         <div className="eightbf-roundtable__settings-mask" role="presentation">
           <section
             className="eightbf-roundtable__settings-dialog"
@@ -137,7 +142,7 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa
                 ))}
               </select>
             </label>
-            {error && <p className="eightbf-roundtable__settings-error">{error}</p>}
+            {error && <p className="eightbf-roundtable__settings-error" role="alert">{error}</p>}
             <div className="eightbf-roundtable__settings-actions">
               <button type="button" onClick={() => setIsSettingsOpen(false)}>取消</button>
               <button type="button" onClick={() => void handleSave()} disabled={isSaving}>
@@ -148,7 +153,6 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa
           </section>
         </div>
       )}
-      {!isLoading && mapping?.chainId && <Check className="eightbf-roundtable__configured-icon h-4 w-4" aria-label="已配置" />}
     </>
   );
 
@@ -159,6 +163,13 @@ export default function EightBfRoundtablePage({ compactChrome = false }: { compa
       lockBusinessChain
       storageTaskId={storageTaskId}
       toolbarSlot={toolbarSlot}
+      entryRailBusinessChainSlot={
+        <PositionBusinessChainFlow
+          chain={configuredChain}
+          loading={isLoading}
+          className="eightbf-roundtable__business-chain-flow"
+        />
+      }
       rootClassName="eightbf-roundtable"
     />
   );

frontend-web/src/eightbf-roundtable/styles/step1.css

@@ -21,4 +21,10 @@
 .eightbf-roundtable .eightbf-roundtable__chain-status-value { color: #134e4a; font-weight: 600; }
 .eightbf-roundtable .eightbf-roundtable__configured-icon { color: var(--eightbf-accent); }
 
+/* 8BF 左上业务链区域：复用岗位会商的纵向节点、点阵画布与放大查看交互。 */
+.eightbf-roundtable .eightbf-roundtable__business-chain-flow {
+  height: 500px;
+  min-height: 460px;
+}
+
 /* 可在此继续覆盖第 1 步的任务理解面板与业务链流程图样式。 */

frontend-web/src/eightbf-roundtable/styles/step3.css

@@ -31,4 +31,49 @@
 .eightbf-roundtable .eightbf-roundtable__settings-actions button:last-child { display: inline-flex; align-items: center; gap: 6px; background: #0f766e; color: #fff; }
 .eightbf-roundtable .eightbf-roundtable__settings-actions button:disabled { cursor: not-allowed; opacity: .65; }
 
+/* 管理员业务链配置弹窗：深色主题下与会商工作区使用同一套深蓝表面与高对比文字。 */
+.dark .eightbf-roundtable .eightbf-roundtable__settings-mask {
+  background: rgb(2 12 30 / 72%);
+  backdrop-filter: blur(3px);
+}
+
+.dark .eightbf-roundtable .eightbf-roundtable__settings-dialog {
+  border: 1px solid rgb(69 195 243 / 42%);
+  background: #082b57;
+  box-shadow: 0 24px 56px rgb(0 0 0 / 45%);
+}
+
+.dark .eightbf-roundtable .eightbf-roundtable__settings-kicker { color: #65d6c6; }
+.dark .eightbf-roundtable .eightbf-roundtable__settings-heading h2 { color: #f1f7ff; }
+.dark .eightbf-roundtable .eightbf-roundtable__settings-close { color: #a9bddb; }
+.dark .eightbf-roundtable .eightbf-roundtable__settings-close:hover { color: #fff; }
+.dark .eightbf-roundtable .eightbf-roundtable__settings-tip { color: #b9c9df; }
+.dark .eightbf-roundtable .eightbf-roundtable__settings-field { color: #e6effc; }
+.dark .eightbf-roundtable .eightbf-roundtable__settings-field select {
+  border-color: rgb(143 196 255 / 48%);
+  background: #0d3768;
+  color: #f1f7ff;
+  color-scheme: dark;
+}
+.dark .eightbf-roundtable .eightbf-roundtable__settings-field select:focus {
+  border-color: #65d6c6;
+  outline: 2px solid rgb(101 214 198 / 28%);
+  outline-offset: 1px;
+}
+.dark .eightbf-roundtable .eightbf-roundtable__settings-field option { background: #0d3768; color: #f1f7ff; }
+.dark .eightbf-roundtable .eightbf-roundtable__settings-error { color: #fca5a5; }
+.dark .eightbf-roundtable .eightbf-roundtable__settings-actions button:first-child {
+  color: #b9c9df;
+}
+.dark .eightbf-roundtable .eightbf-roundtable__settings-actions button:first-child:hover {
+  background: rgb(143 196 255 / 12%);
+  color: #fff;
+}
+.dark .eightbf-roundtable .eightbf-roundtable__settings-actions button:last-child {
+  background: #167d74;
+}
+.dark .eightbf-roundtable .eightbf-roundtable__settings-actions button:last-child:hover {
+  background: #21958a;
+}
+
 /* 可在此继续覆盖第 3 步报告、流程图与放大弹窗的样式。 */

frontend-web/src/env.ts

@@ -20,6 +20,13 @@ export function readRuntimeFlag(key: string): boolean {
   return readRuntimeEnv(key) === "true";
 }
 
+/**
+ * Read an integer setting supplied by ``runtime-config.js``.
+ *
+ * Runtime configuration is editable after the frontend is built, so validate
+ * numeric values here instead of letting an invalid deployment value bypass a
+ * UI constraint that the backend cannot accept.
+ */
 export const env = {
   NEXT_PUBLIC_BACKEND_BASE_URL: readRuntimeEnv("VITE_BACKEND_BASE_URL"),
   NEXT_PUBLIC_LANGGRAPH_BASE_URL: readRuntimeEnv("VITE_LANGGRAPH_BASE_URL"),

frontend-web/src/open-canvas/api/rewrite.ts

@@ -31,7 +31,7 @@ export type RewriteStreamEvent =
 
 // ── SSE parser ────────────────────────────────────────────────────────────────
 
-async function* parseSse(body: ReadableStream<Uint8Array>): AsyncGenerator<{ event: string; data: string }> {
+export async function* parseSse(body: ReadableStream<Uint8Array>): AsyncGenerator<{ event: string; data: string }> {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
@@ -106,3 +106,288 @@ export async function* streamRewrite(
     }
   }
 }
+
+export type DocumentRewriteStyle =
+  | "formal_analysis"
+  | "professional"
+  | "concise"
+  | "readable";
+
+export interface DocumentRewriteRequest {
+  threadId: string;
+  path: string;
+  instruction: string;
+  style?: DocumentRewriteStyle;
+  modelName?: string;
+  expectedHash?: string;
+}
+
+export interface DocumentRewriteSummary {
+  sourceDisplayName: string;
+  instruction: string;
+  modelName: string;
+  originalCharCount: number;
+  rewrittenCharCount: number;
+  charChangeRatio: number;
+  changedBlockCount: number;
+  headingCountBefore: number;
+  headingCountAfter: number;
+  headingChanges?: {
+    added: string[];
+    removed: string[];
+    reordered: boolean;
+    levelWarnings: string[];
+  };
+  requestedOptimizations?: string[];
+  validationWarnings?: string[];
+}
+
+export type DocumentRewriteStreamEvent =
+  | { type: "job_started"; jobId: string; reused: boolean }
+  | { type: "snapshot_fixed"; fileName: string; originalCharCount: number; baseHash: string }
+  | { type: "requirements_started" }
+  /** Small live rewrite plan shown in the message-list requirements step. */
+  | { type: "requirements_delta"; delta: string }
+  /** Durable recovery point for a plan produced before an SSE reconnect. */
+  | { type: "requirements_checkpoint"; content: string }
+  | { type: "requirements_completed"; content: string; fallback: boolean }
+  | { type: "requirements_resolved"; instruction: string; style: string; modelName: string; plan?: string }
+  | { type: "thinking"; chunk: string }
+  | { type: "rewrite_delta"; delta: string; charCount: number }
+  /** Durable full-draft recovery point used after an SSE reconnect. */
+  | { type: "rewrite_checkpoint"; content: string; charCount: number }
+  | { type: "validation_started" }
+  | { type: "validation_completed"; passed: boolean; warnings: string[] }
+  | { type: "comparison_ready"; summary: DocumentRewriteSummary }
+  | { type: "commit_started" }
+  | { type: "committed"; content: string; committedHash: string; versionId?: string }
+  | { type: "done"; committedHash: string; versionId?: string }
+  | { type: "conflict"; message: string }
+  | { type: "cancelled"; message: string }
+  | { type: "error"; message: string; stage?: string };
+
+export interface DurableDocumentRewriteJob {
+  id: string;
+  status: string;
+  phase: string;
+  progress: number;
+  createdAt?: string | null;
+  result: Record<string, unknown>;
+  request: {
+    instruction: string;
+    style: DocumentRewriteStyle;
+    modelName: string | null;
+    originalContent: string;
+  };
+}
+
+async function readDocumentRewriteEvent(
+  event: string,
+  data: string,
+): Promise<DocumentRewriteStreamEvent | null> {
+  try {
+    const parsed = JSON.parse(data) as Record<string, unknown>;
+    switch (event) {
+      case "snapshot_fixed":
+        return {
+          type: "snapshot_fixed",
+          fileName: String(parsed.fileName ?? ""),
+          originalCharCount: Number(parsed.originalCharCount ?? 0),
+          baseHash: String(parsed.baseHash ?? ""),
+        };
+      case "requirements_resolved":
+        return {
+          type: "requirements_resolved",
+          instruction: String(parsed.instruction ?? ""),
+          style: String(parsed.style ?? ""),
+          modelName: String(parsed.modelName ?? ""),
+          plan: typeof parsed.plan === "string" ? parsed.plan : undefined,
+        };
+      case "requirements_started":
+        return { type: "requirements_started" };
+      case "requirements_delta":
+        return { type: "requirements_delta", delta: String(parsed.delta ?? "") };
+      case "requirements_checkpoint":
+        return { type: "requirements_checkpoint", content: String(parsed.content ?? "") };
+      case "requirements_completed":
+        return {
+          type: "requirements_completed",
+          content: String(parsed.content ?? ""),
+          fallback: parsed.fallback === true,
+        };
+      case "thinking":
+        return { type: "thinking", chunk: String(parsed.chunk ?? "") };
+      case "rewrite_delta":
+        return {
+          type: "rewrite_delta",
+          delta: String(parsed.delta ?? ""),
+          charCount: Number(parsed.charCount ?? 0),
+        };
+      case "rewrite_checkpoint":
+        return {
+          type: "rewrite_checkpoint",
+          content: String(parsed.content ?? ""),
+          charCount: Number(parsed.charCount ?? 0),
+        };
+      case "validation_started":
+        return { type: "validation_started" };
+      case "validation_completed":
+        return {
+          type: "validation_completed",
+          passed: parsed.passed === true,
+          warnings: Array.isArray(parsed.warnings)
+            ? parsed.warnings.filter((item): item is string => typeof item === "string")
+            : [],
+        };
+      case "comparison_ready":
+        return { type: "comparison_ready", summary: parsed as unknown as DocumentRewriteSummary };
+      case "commit_started":
+        return { type: "commit_started" };
+      case "committed":
+        return {
+          type: "committed",
+          content: String(parsed.content ?? ""),
+          committedHash: String(parsed.committedHash ?? ""),
+          versionId: typeof parsed.versionId === "string" ? parsed.versionId : undefined,
+        };
+      case "done":
+        return {
+          type: "done",
+          committedHash: String(parsed.committedHash ?? ""),
+          versionId: typeof parsed.versionId === "string" ? parsed.versionId : undefined,
+        };
+      case "conflict":
+        return { type: "conflict", message: String(parsed.message ?? "文件内容已变化") };
+      case "cancelled":
+        return { type: "cancelled", message: String(parsed.message ?? "已停止全文改写") };
+      case "error":
+        return {
+          type: "error",
+          message: String(parsed.message ?? "全文改写失败"),
+          stage: typeof parsed.stage === "string" ? parsed.stage : undefined,
+        };
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
+async function startDurableDocumentRewrite(
+  req: DocumentRewriteRequest,
+  signal?: AbortSignal,
+): Promise<{ jobId: string; reused: boolean }> {
+  const response = await apiFetch(getBackendBaseURL() + "/api/writing/document-rewrite/jobs", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(req),
+    signal,
+  });
+  const body = await response.json().catch(() => ({})) as Record<string, unknown>;
+  if (!response.ok || typeof body.jobId !== "string") {
+    throw new Error(
+      (body.detail as string | undefined) ??
+      (body.message as string | undefined) ??
+      `HTTP ${response.status}`,
+    );
+  }
+  return { jobId: body.jobId, reused: body.reused === true };
+}
+
+export async function* streamDurableDocumentRewriteJob(
+  req: Pick<DocumentRewriteRequest, "threadId" | "path">,
+  jobId: string,
+  signal?: AbortSignal,
+  after = 0,
+): AsyncGenerator<DocumentRewriteStreamEvent> {
+  const query = new URLSearchParams({
+    thread_id: req.threadId,
+    path: req.path,
+    after: String(after),
+  });
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/writing/document-rewrite/jobs/${encodeURIComponent(jobId)}/stream?${query.toString()}`,
+    { method: "GET", signal },
+  );
+  if (!response.ok || !response.body) {
+    const body = await response.json().catch(() => ({})) as Record<string, unknown>;
+    throw new Error((body.detail as string | undefined) ?? `HTTP ${response.status}`);
+  }
+  for await (const { event, data } of parseSse(response.body)) {
+    if (signal?.aborted) return;
+    const parsed = await readDocumentRewriteEvent(event, data);
+    if (!parsed) continue;
+    yield parsed;
+    if (["done", "conflict", "cancelled", "error"].includes(parsed.type)) return;
+  }
+}
+
+export async function getLatestDurableDocumentRewrite(
+  req: Pick<DocumentRewriteRequest, "threadId" | "path">,
+): Promise<DurableDocumentRewriteJob | null> {
+  const jobs = await listDurableDocumentRewrites(req, 1);
+  return jobs[0] ?? null;
+}
+
+export async function listDurableDocumentRewrites(
+  req: Pick<DocumentRewriteRequest, "threadId" | "path">,
+  limit = 20,
+): Promise<DurableDocumentRewriteJob[]> {
+  const query = new URLSearchParams({
+    thread_id: req.threadId,
+    path: req.path,
+    limit: String(Math.min(Math.max(limit, 1), 20)),
+  });
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/writing/document-rewrite/jobs?${query.toString()}`,
+    { method: "GET" },
+  );
+  const body = await response.json().catch(() => ({})) as Record<string, unknown>;
+  if (!response.ok) throw new Error((body.detail as string | undefined) ?? `HTTP ${response.status}`);
+  const rows = Array.isArray(body.items) ? body.items : [];
+  return rows.flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const job = item as Record<string, unknown>;
+    if (typeof job.id !== "string") return [];
+    const request = (job.request ?? {}) as Record<string, unknown>;
+    return [{
+      id: job.id,
+      status: String(job.status ?? "queued"),
+      phase: String(job.phase ?? "initializing"),
+      progress: Number(job.progress ?? 0),
+      createdAt: typeof job.createdAt === "string" ? job.createdAt : null,
+      result: (job.result ?? {}) as Record<string, unknown>,
+      request: {
+        instruction: String(request.instruction ?? ""),
+        style: (request.style ?? "professional") as DocumentRewriteStyle,
+        modelName: typeof request.modelName === "string" ? request.modelName : null,
+        originalContent: String(request.originalContent ?? ""),
+      },
+    }];
+  });
+}
+
+export async function cancelDurableDocumentRewrite(
+  req: Pick<DocumentRewriteRequest, "threadId" | "path">,
+  jobId: string,
+): Promise<void> {
+  const query = new URLSearchParams({ thread_id: req.threadId, path: req.path });
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/writing/document-rewrite/jobs/${encodeURIComponent(jobId)}/cancel?${query.toString()}`,
+    { method: "POST" },
+  );
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({})) as Record<string, unknown>;
+    throw new Error((body.detail as string | undefined) ?? "停止全文改写失败");
+  }
+}
+
+export async function* streamDocumentRewrite(
+  req: DocumentRewriteRequest,
+  signal?: AbortSignal,
+): AsyncGenerator<DocumentRewriteStreamEvent> {
+  const started = await startDurableDocumentRewrite(req, signal);
+  yield { type: "job_started", jobId: started.jobId, reused: started.reused };
+  yield* streamDurableDocumentRewriteJob(req, started.jobId, signal);
+}

frontend-web/src/open-canvas/components/artifact/MarkdownAiEditor.tsx

@@ -5,8 +5,15 @@ import { CanvasUIProvider, useCanvasUIContext } from "../../contexts/CanvasUICon
 import { TiptapEditor } from "../../editor/TiptapEditor";
 import { useWritingEditor } from "../../hooks/useWritingEditor";
 import { useWritingRewrite } from "../../hooks/useWritingRewrite";
-import { applyInsert, applyReplace } from "../../utils/apply-rewrite";
+import {
+  applyInsert,
+  applyReplace,
+  createRewriteSelectionSnapshot,
+  isRewriteSelectionSnapshotCurrent,
+  type RewriteSelectionSnapshot,
+} from "../../utils/apply-rewrite";
 import type { RewriteAction, RewriteTone } from "../../api/rewrite";
+import { toast } from "sonner";
 
 import { WritingAiMenu } from "./WritingAiMenu";
 import { WritingBubbleMenu } from "./WritingBubbleMenu";
@@ -69,6 +76,7 @@ function MarkdownAiEditorInner({
   const [phase, setPhase] = useState<FlowPhase>("idle");
   const [panelPos, setPanelPos] = useState<PanelPos>({ x: 0, y: 0 });
   const lastActionRef = useRef<LastAction | null>(null);
+  const candidateSnapshotRef = useRef<RewriteSelectionSnapshot | null>(null);
 
   const editor = useWritingEditor({
     markdown,
@@ -99,10 +107,17 @@ function MarkdownAiEditorInner({
 
   const closeAll = useCallback(() => {
     editor?.commands.clearAiHighlight();
+    candidateSnapshotRef.current = null;
     setPhase("idle");
     reset();
   }, [reset, editor]);
 
+  const snapshotCurrentSelection = useCallback(() => {
+    if (!editor || !writingSelection) return false;
+    candidateSnapshotRef.current = createRewriteSelectionSnapshot(editor, writingSelection);
+    return true;
+  }, [editor, writingSelection]);
+
   const handleAction = useCallback(
     (
       action: RewriteAction,
@@ -110,39 +125,53 @@ function MarkdownAiEditorInner({
       customInstruction?: string,
       referenceText?: string,
     ) => {
+      if (!snapshotCurrentSelection()) return;
       lastActionRef.current = { action, tone, customInstruction, referenceText };
       rewrite(action, tone, customInstruction, referenceText);
       setPhase("preview");
     },
-    [rewrite],
+    [rewrite, snapshotCurrentSelection],
   );
 
   const handleRetry = useCallback(() => {
     if (!lastActionRef.current) return;
+    if (!snapshotCurrentSelection()) return;
     const { action, tone, customInstruction, referenceText } = lastActionRef.current;
     rewrite(action, tone, customInstruction, referenceText);
-  }, [rewrite]);
+  }, [rewrite, snapshotCurrentSelection]);
 
   const handleFollowUp = useCallback(
     (instruction: string) => {
       if (!lastActionRef.current) return;
+      if (!snapshotCurrentSelection()) return;
       const { action, tone, referenceText } = lastActionRef.current;
       rewriteFollowUp(instruction, action, tone, referenceText);
     },
-    [rewriteFollowUp],
+    [rewriteFollowUp, snapshotCurrentSelection],
   );
 
+  const canApplyCandidate = useCallback(() => {
+    if (!editor || !candidateSnapshotRef.current) return false;
+    if (isRewriteSelectionSnapshotCurrent(editor, candidateSnapshotRef.current)) return true;
+    toast.error("原文已变化，请重新生成候选稿。", {
+      description: "为避免将过期候选替换到错误位置，本次内容没有写入文档。",
+    });
+    return false;
+  }, [editor]);
+
   const handleReplace = useCallback(() => {
-    if (!editor || !writingSelection || !result) return;
+    const snapshot = candidateSnapshotRef.current;
-    applyReplace(editor, writingSelection, result);
+    if (!editor || !snapshot || !result || !canApplyCandidate()) return;
+    applyReplace(editor, snapshot, result);
     closeAll();
-  }, [editor, writingSelection, result, closeAll]);
+  }, [editor, result, canApplyCandidate, closeAll]);
 
   const handleInsert = useCallback(() => {
-    if (!editor || !writingSelection || !result) return;
+    const snapshot = candidateSnapshotRef.current;
-    applyInsert(editor, writingSelection, result);
+    if (!editor || !snapshot || !result || !canApplyCandidate()) return;
+    applyInsert(editor, snapshot, result);
     closeAll();
-  }, [editor, writingSelection, result, closeAll]);
+  }, [editor, result, canApplyCandidate, closeAll]);
 
   return (
     <div className={className ?? "h-full flex flex-col overflow-hidden"}>