Merge branch 'master' into master-zl

# Conflicts:
#	frontend-web/src/components/workspace/input-box.tsx
#	offline-backend-20260512/backend/CLAUDE.md
#	offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/prompt.py
#	offline-backend-20260512/backend/tests/test_es_query_routing_prompt.py

.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
@@ -80,8 +87,39 @@ offline-backend-20260512/backend/skill_evolution.json
 skills/
 hermes-agent-main/
 .gitignore
-offline-backend-20260512/backend/tests/*
-deploy
+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 formal Word OOXML and embedded-font regression coverage versioned.
+!offline-backend-20260512/backend/tests/test_word_export.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
+# Keep the forced-research agent runtime gate and sandbox-policy regressions versioned.
+!offline-backend-20260512/backend/tests/test_forced_research_agent.py
+# Keep fixed-question exact-match and streaming regression coverage versioned.
+!offline-backend-20260512/backend/tests/test_fixed_questions.py
+# Keep configurable es_query system-prompt routing regression coverage versioned.
+!offline-backend-20260512/backend/tests/test_es_query_routing_prompt.py
+# Keep the local LLMWiki vector-index and external API regression coverage versioned.
+!offline-backend-20260512/backend/tests/test_llmwiki_local_index_repository.py
+!offline-backend-20260512/backend/tests/test_llmwiki_vector_search.py
+!offline-backend-20260512/backend/tests/test_llmwiki_wiki_sync.py
+!offline-backend-20260512/backend/tests/test_external_llmwiki_search.py
+!offline-backend-20260512/backend/tests/test_llmwiki_wiki_retrieval.py
+!offline-backend-20260512/backend/tests/test_public_llmwiki_embed.py
+# Deep-research reliability regression coverage.
+!offline-backend-20260512/backend/tests/test_deep_research_persistence.py
+!offline-backend-20260512/backend/tests/test_deep_research_event_sink.py
+!offline-backend-20260512/backend/tests/test_deep_research_executor_reliability.py
+!offline-backend-20260512/backend/tests/test_deep_research_start_job.py
+!offline-backend-20260512/backend/tests/test_summarization_human_message.py
+!offline-backend-20260512/backend/tests/test_compact_menu_overrides.py
+# Independent enterprise-research persistence, HTTP and race regressions.
+!offline-backend-20260512/backend/tests/test_enterprise_research_tasks.py
+# Position-roundtable per-turn write/present cap (weak-model duplicate artifacts).
+!offline-backend-20260512/backend/tests/test_position_artifact_cap.py
+deploy
 .history
 
 # Cloned third-party repos (local only)
@@ -93,6 +131,16 @@ git-clone/
 # Frontend offline pack working directories
 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
+
+# Local offline bundles and scratch tooling
+/*.tar.gz
+/offline-backend-20260512/*.zip
+/tmp/
 
 .codegraph
 codegraph.mdc
@@ -112,4 +160,4 @@ offline-backend-20260512/backend/uv.lock
 __pycache__/
 
 # misc
-.DS_Store
+.DS_Store

.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: VS Code Start",
+      "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,175 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "DeerFlow: VS Code Start",
+      "type": "process",
+      "command": "powershell.exe",
+      "args": [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        "${workspaceFolder}/scripts/vscode-start.ps1",
+        "-OpenBrowser"
+      ],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated",
+        "clear": true
+      },
+      "problemMatcher": []
+    },
+    {
+      "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

@@ -11,6 +11,13 @@ This is a customized offline deployment of **DeerFlow** — a LangGraph-based AI
 
 Managed together via shell scripts in `scripts/`.
 
+## Offline Release Repository
+
+Linux AMD64 离线发版脚本、wheelhouse、`deploy.env` 模板和部署文档统一维护在
+`knowledge-base-bj/deerflow-offline-deployment`，不要把离线镜像或发版资产提交到
+本业务源码仓库。正式发版从该仓库执行 `scripts/build-latest-master.sh`，脚本会读取
+本仓库最新 `master` 的干净源码快照。
+
 ## Commands
 
 ### Full Application (from repo root)
@@ -81,15 +88,19 @@ The frontend (`frontend-web/`) is a React 19 + Vite SPA:
 - **Pages**: `ChatPage` (thread chat), `AgentChatPage` (custom agent chat), `AgentsPage`/`NewAgentPage` (agent management), `ScheduledTasksPage`/`ScheduledTaskRunDetailPage` (scheduled tasks), `LightAppManagementPage`/`LightAppListPage`/`LightAppIframeView` (轻应用中心 — register/list/embed mini-apps)
 - **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).
+- **菜单管理 (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). **简介模式** uses a separate overlay: every compact workspace menu item can be placed in `sidebar`（左侧菜单）、`settings`（设置和更多）or `toolbox`（右侧工具箱）; `CompactToolbox` (`components/workspace/compact-toolbox.tsx`, mounted by `PageRoutes.tsx`) opens only when the square right-edge trigger is clicked, then slides a compact, content-height right-side drawer over a backdrop above global dropdowns; configured items render top-to-bottom as centered square cards with a large icon above the label while the effective layout is compact. `/api/compact-menu-overrides` stores two independent sets (type `A` / `B`); each website picks one via `runtime-config.js` `VITE_COMPACT_MENU_TYPE`.
+- **舆情分析智能体（前端虚拟智能体）**: 智能体管理页新增「舆情分析」类型 tab，固定一张虚拟智能体卡片（名称/简介可编辑，存 localStorage）。对话页 `pages/SentimentAgentChatPage.tsx`（路由 `agents/sentiment-analysis/chats/:thread_id`）复用普通问答布局 + `MessageList`，**输入框只有发送按钮**；问答经 Gateway `POST /api/sentiment-agent/stream` 转发外部 AG-UI 网关（不经过 LangGraph），会话仅存 sessionStorage。接口地址 + Basic Auth 在 `runtime-config.js` 配置（`VITE_SENTIMENT_AGENT_API_URL` / `_AUTH_USERNAME` / `_AUTH_PASSWORD`）并随请求传给后台；后台按传入地址转发、关闭 TLS 校验，失败时把完整错误回传。核心模块 `src/core/sentiment-agent/`。
+- **简洁模式用户引导 (Compact-mode onboarding tour)**: 简洁模式（外观设置的「全量/简洁」= compact，无全局导航栏 + 页面侧边栏）新增 TDesign React `Guide` 组件驱动的分步引导。组件 `components/workspace/compact-mode-guide.tsx`（挂在 `ChatPage`）：9 步 —— 欢迎弹窗（dialog 模式）→ 左侧功能导航 → 聊天记录 → 设置和更多 → 换肤 → 界面模式（切回全量）→ 常用提示词栏 → 提示词管理弹窗 → 输入框；高亮目标由各组件上的 `data-compact-guide` 标记定位（`workspace-nav-chat-list` / `recent-chat-list` / `workspace-nav-menu` / `appearance-controls` / `custom-prompt-menu.tsx` 的 `CustomPromptBar`（提示词栏，仅新对话落地态渲染）与其 `ManagePromptsDialog`（`prompt-dialog` 锚点）/ ChatPage 输入框容器），**启动时按目标是否存在过滤步骤**（如新用户无聊天记录、侧栏收起时自动剔除该步 —— Guide 对缺失元素会抛错，不能盲传）。**提示词管理弹窗步骤是动态目标**：弹窗平时不渲染，引导切到该步前先广播 `PROMPT_DIALOG_GUIDE_EVENT`（`custom-prompt-menu.tsx` 导出）让 `CustomPromptBar` 打开 `ManagePromptsDialog` 并**接管**（`owner: true` 期间 ESC/点遮罩不关闭，防止高亮目标消失导致 Guide 报错），轮询锚点真正挂载后才切步；离开该步 / 跳过 / 完成 / 中途卸载时以 `owner: false` 收回弹窗，4 秒打不开则跳过该步防卡死。**TDesign Guide × Radix 模态互操作**：Radix 模态弹窗打开时会把 `body` 置 `pointer-events:none`（滚动锁定），Guide 直接挂在 body 下的遮罩/高亮/弹层会一并继承失活（引导按钮点不动），`styles/tdesign-theme.css` 末尾对 `.t-guide__overlay/__highlight/__popup/__wrapper` 显式 `pointer-events:auto` 兜底。触发：① 自动 —— 简洁模式新对话落地页自动演示，直到用户显式点「完成」或「跳过」才写 localStorage `deerflow.compact-guide-finished` 记忆（浏览器级）；**中途刷新/离开不记忆，下次进入还会再演示**。② 手动 —— 「设置和更多」下拉新增「界面使用引导」（该下拉仅存在于简洁模式工作区侧栏 footer）：已在问答页时广播 `compact-guide:start` 窗口事件直接启动，否则写 sessionStorage 请求并导航 `/chats/new` 由挂载的引导消费（消费在定时器真正启动时才执行，规避 StrictMode effect 双跑吞请求）。`eligible` 排除 embed=1 / hideChrome=1 / chats_iframe / FORCE_COLLAPSED_SIDEBAR（无界）等同样无全局 chrome 的特殊环境；启动延迟 800ms 等侧栏宽度过渡稳定后再测量高亮框。
+- **智能体使用引导 (Agent onboarding tour, 三段式)**: 智能体「浏览管理 → 创建与配置 → 发起问答」全流程分步引导，组件 `components/workspace/agents/agent-guide.tsx`（同一 TDesign `Guide` 封装模式，与简洁模式引导共享记忆语义：**仅显式点「完成/跳过」才写 localStorage** `deerflow.agent-guide.<stage>.finished`，中途刷新/离开不记忆）。**自动演示仅 create / chat 两段**（进智能体列表页不弹引导，点「创建智能体」进入新建页时才自动演示；list 段的 `AgentGuide` 传 `autoStart={false}`，只能由头部「使用引导」按钮手动触发）。三段各自挂载、各自记忆：① `list`（`agent-gallery.tsx`，/page/workspace/agents）——分区 Tabs、搜索排序、智能体卡片操作、右上「创建智能体」按钮；**完成/跳过就地结束（不跳转创建页，与 create 段无联动）**，最后一步仅提示进入创建页后会有配置引导；② `create`（`NewAgentPage.tsx`，/page/workspace/agents/new）——左侧对话式创建输入区、基本信息、运行模型+入库模板名、知识空间、SOUL.md、技能穿梭框、保存按钮（9 步）；③ `chat`（`AgentChatPage.tsx`，agents/:id/chats）——左栏切换与历史、常用问题 chips、输入框（落地态/会话态两个挂点同一 `chat-input` 标记）、右侧详情面板；`eligible` 限定普通智能体对话页（`showAgentList && !isEmbedded && !taskCtxOn`，即排除通用问答原地嵌入与任务深链工作区），三段共用 `isAgentGuideEnvironment()` 排除 embed/hideChrome/无界环境。高亮锚点 `data-agent-guide`：列表页 `tabs`/`search`/`agent-card`（卡片+列表两种布局的根元素）/`new-agent-btn`，创建页 `create-chat-input`/`create-basic`/`create-model`/`create-knowledge`/`create-soul`/`create-skills`/`create-save-btn`，对话页 `chat-sidebar`/`chat-questions`/`chat-input`/`chat-detail`；同样**启动时按目标存在性过滤步骤**（新用户无卡片/无预设问题时自动剔除）。手动重放：三个页面头部各有「使用引导」按钮（列表页创建按钮左侧、创建页 header 右侧、对话页 header），广播 `agent-guide:start:<stage>` 窗口事件强制重放（忽略已看过记忆）。
 - **敏感词管理 (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`.
+- **按钮管理 (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). **`host`（宿主路由）** asks the embedding parent to navigate: `runTaskButton` sends `window.parent.postMessage({ type:'HOST_NAVIGATE', path, queryParams:{ [idParam]: Number(taskId) } }, hostOrigin)` — `target` is the host route, `appendTaskId`/`idParam` become numeric `queryParams` (task id only), origin from `runtime-config.js` `VITE_HOST_NAVIGATE_ORIGIN` (else ancestorOrigins/referrer; never `*`). **`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`.
 - **State**: TanStack Query for server state, context providers (`SubtasksProvider`, `ArtifactsProvider`, `PromptInputProvider`) scoped to `WorkspaceRoutes`
 - **LLM streaming**: `@langchain/langgraph-sdk` streams messages from the backend via SSE
 - **UI**: Radix UI primitives + TailwindCSS v4 + shadcn-style components in `src/components/ui/`
 - **Shims**: `src/shims/` provides `next/link` and `next/navigation` polyfills (original code was Next.js)
 - **Login URL params** (`LoginPage.tsx`, frontend-only — the backend never sees these): besides the auth params (`ticket`/`userId`/`env`/`theme`/`yUserId`/`token`/`access_token`/`authToken`/`password`), the page supports a **task deep-link** via `?taskId=&goPath=`. After login it calls the consumer API `GET {VITE_AIPI_CONSUMER_URL}/taskAnalyseSearch/cop-task-detail?taskId=` (header `Authorization: Bearer admin`, auto-injected by `utils/request.ts`), stashes the full `data` (`id/overview/taskDirection/taskName/taskContent`) into `sessionStorage["login.copTaskDetail"]`, then routes by `goPath`: base codes `3qfx`/`rwfx`/`xdfx` → that business's configured **single agent** Q&A inside a **任务工作区** (resolved via `/api/business-mapping`; `resolveTaskDeeplinkTarget` calls `persistTaskContext({taskId, agentId, openingText})` and navigates to the `…/chats` **index**, which opens the latest task conversation or 新建 — a 1:N task↔对话 workspace, NOT `pendingAgentMessage`); the `-A` suffix (`3qfx-A`/…) → **multi-agent roundtable** with `roundtablePrefill.businessCode` so the page auto-selects the configured 业务链条. **xdfx's deep-link `?taskId=` is actually an 行动id, not a 任务id** — `resolveDeeplinkTaskId(goPath, rawId)` (called in `LoginPage` before everything) detects `xdfx`/`xdfx-A` and resolves it via `GET {action_detail_url}/{actionId}` → `data.taskId` (`fetchTaskIdFromAction`; `action_test`+`mock.action_detail` for offline testing); the resolved 任务id then drives `cop-task-detail`, the purpose tree, and the 1:N binding (other businesses pass the id through unchanged). **xdfx additionally partitions its chat records by 行动id (action_id), NOT by task_id**: `resolveTaskDeeplinkTarget` sets `partitionByAction:true` + keeps the raw action_id as `TaskContext.actionId`, so new threads are tagged `metadata.{taskId,actionId}` (taskId kept only to preserve the backend「任务深链对话全局共享」semantics, which keys off `metadata.taskId`) and the conversation list filters by `actionId` (+`agent_id`) — different actions of the same task get separate lists. xdfx's first-question opening text also appends `行动id（action_id）为…` (see `buildOpeningText` / `taskThreadMetadata`). goPath→businessCode: `3qfx`→`3Q`, `rwfx`→`6BF`, `xdfx`→`7BF`. The roundtable target also threads the URL `taskId` into `roundtablePrefill.taskId` (`resolveTaskDeeplinkTarget(goPath, detail, taskId)`), which turns on two taskId-scoped behaviors: (1) **separate, unpartitioned per-task storage** — taskId 会商聊天记录 live in their **own** store/table (`roundtable_task_drafts`), keyed **only by `task_id`** (one taskId = many records, shared across users, **no user 分权** at all; `created_by` is audit-only), kept entirely out of the per-user personal store (`roundtable_drafts`, now strictly per-user) so the two never mix. Backend router `/api/roundtable-task-drafts` (`GET /by-task/{id}` + `/by-task/{id}/latest`, `POST`, `GET/PUT/DELETE /{id}` — all user-agnostic); frontend client `roundtable-planning/api/task-drafts.ts`, and `useDraftPersistence`/`useRoundtableDrafts` route **all** CRUD to it when a `taskId` is present (else the personal `drafts.ts`). The matching **background jobs** are shared by task too: `roundtable_jobs.task_id` marks a task job; reads/dedup/stream/resume/cancel pass `?task_id=` so any user opening the task sees the same running 研讨 (progress/flowchart), and the executor writes the final report back to the task-draft store. Existing rows are moved over by `scripts/migrate_roundtable_task_drafts.py` (migration `20260618_01`). The history dropdown filters to the task and 新建 keeps the binding; (2) **Step-3 auto structured output** — after the `roundtable-summary` agent writes the Markdown report it automatically runs a second round emitting a `flow-json` flowchart (`useStep3Summary` `autoFlow`+`chainLevels`), whose hierarchy follows the business chain's stage goals (任务 → 目的 → 行为体 → …; coordinatorPrompt-specified hierarchy wins) and whose nodes never carry 阶段编号/阶段名 (the prior bug). **Both targets render embedded under the 任务管理 layout** — nested routes under `task-management/<business-path>/{roundtable,agent/:agent_id/chats}` in `StrategyRoutes.tsx` (`<business-path>` = `plan-task-sentiment` / `plan-task/plan-task-fx` / `plan-task/plan-task-action`, matching the COH中任务 menu paths in `sidebar-menu.ts`) so the global sidebar keeps 任务管理 → COH中任务 → the matching business highlighted. **All three single-agent businesses share `TaskFxWorkspace`** (`task-components/TaskFxWorkspace.tsx`): left = a「当前任务」card (`readCopTaskDetail()` 任务名称 + 简介, desensitized, 留存 above 新建对话) + per-task 1:N conversation list (`useTaskThreads(taskId, agentId, actionId?)` — filtered by **both** `metadata.taskId` AND `metadata.agent_id` so the three businesses' conversations staLine truncated
+- **agentfx 任务深链（新系统 iframe 嵌入的智能体问答，3qfx 单智能体 lite 模式的独立复制）**: goPath=`agentfx`（`${loginBase}?password=…&taskId=…&goPath=agentfx&embed=1&hideJump=1&theme=dark-blue`）。与 3qfx 的差异：①任务详情不走外部 consumer，改调**本系统 Gateway** `GET {backend}/taskAnalyseSearch/cop-task-detail?taskId=`（`apiFetch` 带刚登录的 DeerFlow 态；任务数据来自 TaskCOP 任务表，与任务列表/报告导入同一份）；②**固定使用内置智能体** `agentfx-analyst`（不走业务映射）；③路由 `task-management/plan-task-agentfx/agent/:agent_id/chats`，页面为独立复制的 `AgentFxWorkspace.tsx`（`AgentFxWorkspace`/`AgentFxIndexResolver`/`AgentFxChat` —— 左「当前任务」卡 + 1:N 对话列表 + 新建对话，`AgentChatPage taskBind` 自动发开场白；无 TaskJumpBar/清除记录/闸门/xdfx 行动卡）。模块 `core/auth/agentfx-deeplink.ts`（`isAgentfxGoPath`/`fetchAgentfxTaskDetail`/`resolveAgentfxDeeplinkTarget`）；任务详情整包仍存共享键 `login.copTaskDetail`（按标签页隔离），`AgentChatPage` 的 taskBind 自恢复对 agentfx 生效。`LoginPage` 在既有深链分支前用 `isAgentfxGoPath` 分流。**内置「任务研判报告助手」**：后端 seeder `app/gateway/routers/_agentfx_seed.py` + `_agentfx_seed_assets/`（config.yaml + SOUL.md，目录存在不覆盖；app.py lifespan 在 `_sync_legacy_agents` 之前调用，自动进 agents 表 user_id IS NULL）——SOUL 规定工作流「搜集信息（`web_search`，**首步不可跳过**）→ `write_file` 生成 `/mnt/user-data/outputs/report.md` + `task-reports.json`（14 个 categoryType 的 `{contentJson, categoryType}` 数组，contentJson 为 JSON 字符串）→ 聊天总结 → 引导入库」，硬性约束：categoryType 逐字用 14 个全称（禁缩写自造如「DQ关键事件」）、JSON 直接写汉字禁 `\uXXXX` 转义、每类必须有实质内容不许空数组/纯占位、文件一律用 `/mnt/user-data/...` 虚拟路径（防宿主路径泄漏进 tool args）。**检索依赖 `config.yaml tools.web_search`（DDG，enabled 已开；内网需换 configurable_search 时改回并填 endpoint）**。任务工作区输入框在 `taskCtxOn` 时隐藏「写作/记忆/参考文献」（InputBox `hideContextTools` prop）与「知识空间」（不传 knowledgeSelector）；消息流里 write_file 文件卡片只显示文件名（`artifactDisplayName` 收敛宿主/虚拟路径）。**入库两条路径**：(a) **前端协助卡** —— `AgentChatPage`（taskBind 且非 taskGate）检测线程 artifacts 出现 `task-reports.json`（按文件名后缀匹配，兼容本地沙箱记录的宿主路径）且流式结束时，向 displayThread 尾部注入 `additional_kwargs.task_report_import_approval` 虚拟 ai 消息（`core/messages/utils.ts` 分组 `assistant:task-report-import` + `MessageList` 的 `taskReportImportSlot` 插槽渲染 `TaskReportImportCard`），点「开始入库」前端校验（`strategy-components/lib/agentfx-report-schema.ts`，14 类 + contentJson 合法 JSON + **\u 转义归一化还原为汉字**，与技能脚本同规则）后 `importTaskReport`（`strategy-components/api/task-reports.ts`）POST 导入接口整体替换；任务已有详情**不抑制**卡片（入库即整体替换，卡片文案说明覆盖语义），导入成功按 thread 记 sessionStorage（刷新不重复询问）、「暂不入库」为会话内记忆；(b) **入库技能** `task-report-import`（seeder 一并复制到 `skills/public/`，public 类技能 extensions_config 缺省即启用）—— 用户聊天里说「入库」时智能体按 SKILL.md 用 bash 跑 `scripts/task_report_import.py`（纯标准库：同样的校验规则 + 转义归一化；**默认关闭 SSL 证书校验** `ssl._create_unverified_context` + 忽略代理，适配内网自签证书；鉴权 `--token`/env `AGENTFX_IMPORT_TOKEN`→`DEERFLOW_AUTH_TOKEN`→`TOOLS_TOKEN` 优先，缺省经公共端点 `POST /api/parallel-agents/auth/token` 以 `agentfx-import` 用户现签 token——内网既有鉴权旁路；gateway 地址 env `AGENTFX_GATEWAY_URL` 或 `http://127.0.0.1:{DEER_FLOW_GATEWAY_PORT}`）；`--strict` 可要求 14 类齐全，默认允许部分导入并在 stdout JSON 的 `missing_categories` 里列缺。入库成功后任务 TaskCOP 状态自动置 25（已完成分析）。**入库成功通知宿主**（iframe 嵌入场景）：两条路径成功后都会 `window.top.postMessage({source: "magent-web", type: "task-report:saved", taskId: String(taskId)}, "*")`（`notifyTaskReportSaved`，`agentfx-report-schema.ts`）——卡片路径在 `TaskReportImportCard` 导入成功回调里直发；技能路径由 `AgentChatPage` 从消息流检测 `task_report_import.py` 的成功 stdout（`"success": true` + `task_id`）代发——**仅在回合结束后检测**（`!thread.isLoading` 才扫描；流式过程中 messages Line truncated
 - **iframe 嵌入模式 (外部系统用 iframe 套用深链问答/会商)** — 三个**按标签页**开关，全部由深链 URL 参数开启、存进同一份 `sessionStorage` 会话（`embed.session`，键名常量在 `core/embed/embed-session.ts`），跨登录跳转/刷新/页内导航存活，**绝不跨标签污染**同浏览器另开的正常系统页。核心隔离手法：用 `sessionStorage`（按标签页/浏览上下文隔离，iframe 即便同源也有独立一份）而非 `localStorage`（跨标签共享）。开关：(1) **`?embed=1`（可带 `&theme=`）** — 去全局 chrome（`PageLayout` 的 `pageSidebarAllowed && !isEmbedActive()` → 隐藏 Header + PageSidebar）+ 按外部主题色**强制**明/暗：走 next-themes 的 `forcedTheme`（`App.tsx` `AppProviders` 调 `resolveForcedEmbedTheme`，**不写** localStorage `strategy-theme`），离散映射 `dark-blue`/`dark`→深、其余→浅；嵌入侧**绝不**调 `setTheme`/`persistSidebarEnabled`（那俩落 localStorage 跨标签污染，`LoginPage` 据 `readEmbedParam` 跳过）。(2) **`?hideJump=1`** — 隐藏深链底部「快捷跳转」栏 `TaskJumpBar` 的两部分（底部「下一步」等按钮 + 右侧垂直居中悬浮菜单），单智能体问答 + 会商共用该栏，`isJumpBarHidden()` 为真时整条 `return null`。(3) **登录用户隔离** — 嵌入态下鉴权/身份键（`deerflow.auth` token、`userInfo`、`login.*`、`tools_token`、maxkey/userDetail token）全部经 `core/auth/scoped-storage.ts` 的 `authStorage()`（嵌入→sessionStorage / 正常→localStorage）读写，使 iframe 里登录的用户与正常登录用户**完全隔离**、互不覆盖；所有 token 读取都过 `getStoredAuth()`/`getAuthorizationHeaderValue()`（API 客户端 `core/api/*` 全走这俩），改中心函数即让全体调用方自动隔离；跨标签账号变更监听 `AuthSyncWatcher`（`core/auth/sync.tsx`）在嵌入态禁用。嵌入会话在 `main.tsx` 渲染前 `syncEmbedSessionFromCurrentUrl()` 同步启用（早于任何鉴权写入，避免首帧 effect 顺序漏写 localStorage）；`AppProviders` 的 effect 再按 SPA 导航同步。`embed=0`/`hideJump=0` 可显式关闭。正常（非嵌入）标签页所有 `isXxx()` 恒 false，行为**零变化**。第三个开关 `?isolate=1`（**独立登录会话**）把同一套**登录用户隔离**单独提供给**普通（带 chrome）标签页**——只切换鉴权存储、不去 chrome / 不强制主题 / 不动跳转栏：`authStorage()` 的条件从「仅嵌入」放宽为 `isEmbedActive() || isIsolatedSession()`，`AuthSyncWatcher` 的跨标签监听对嵌入态**或**独立态都即时忽略（handler 内实时判，运行时开关也即刻生效）。除 URL 参数外，**设置 → 外观 →「登录会话」** 有一个 Switch「独立登录会话（本标签页）」运行时切换（`setIsolatedSession`，`appearance-settings-page.tsx`）：**开启时先 `migrateAuthToSession()`**（`scoped-storage.ts`，把 localStorage 的受保护键 `deerflow.auth`/`userInfo`/`userId`/`tools_token` + `login.*` 前缀快照搬进 sessionStorage）再翻标志，故无感不登出；此后本标签页登录态独立——别处登录/换号影响不到它，它换号也影响不到别人，但关掉该标签即结束（需重登）。开启给 toast 提示。
 
 ### Configuration

CLAUDE.md

@@ -82,13 +82,13 @@ The frontend (`frontend-web/`) is a React 19 + Vite SPA:
 - **定时任务「JSON → HTML 模板填充」(模板数据转换器)**: a third scheduled-task execution mode. In the create/edit dialog (`ScheduledTasksPage.tsx`), selecting the built-in agent **「模板数据转换器」** (`execution_agent_name === "template-json-builder"`, `TEMPLATE_BUILDER_AGENT_ID`) reveals a 「HTML模板」 select (`useHtmlTemplates` → `GET /api/scheduled-tasks/html-templates`) + a **.json 上传** button (reads the file's text into the prompt box) and **hides** the 必须生成 HTML/Markdown switches (this mode always outputs HTML). The chosen template persists as `execution_context.template_config.template_id` (`TemplateFillConfig` in `core/scheduled-tasks/types.ts`). At run time the backend converts the source JSON (the task prompt) into that template's `DATA` structure, validates (retry-on-fail), fills the template, and stores an HTML page previewable via the existing run-detail HTML preview. The source can be **pure JSON, plain text, or text-with-embedded-JSON** — the backend pre-extracts any embedded JSON and the agent's `SOUL.md` maps it (or the plain text's semantics) to the template's schema skeleton. **Chat-page debug entry (only this agent's `AgentChatPage`)**: when `agent_id === "template-json-builder"`, the chat header shows a 「页面模板」 select + a 「渲染预览」 button — after a normal Q&A run, the button takes the **latest AI reply**, POSTs it to `POST /api/scheduled-tasks/template-fill/render` (`renderTemplateFill`), and pops a dialog rendering the filled HTML in a `sandbox="allow-scripts"` iframe plus the structure-validation status/errors/gaps — for debugging the agent's conversion effect without creating a scheduled task. Gated strictly on the agent id, so other agents' chat pages are untouched. See the backend CLAUDE.md「Template-fill mode」for the engine (`deerflow/runtime/scheduler/template_fill.py`), agent seed, dispatch, and the render API.
 - **AI 写作·对话版（对话驱动写作台）**: a **parallel new entry** beside the classic AI-writing page (classic page/routes untouched) — route `/page/canvas/ai-writing-chat` (`OpenCanvasRoutes.tsx`), sidebar 「问答管理 → 课题研究(对话版)」. Page `open-canvas/pages/AIWritingChatPage.tsx` fully **reuses the engine** (`AIWritingContext` state machine + LangGraph `useStream`, `AIWritingHistoryProvider`, right-side `AIWritingDraftPanel`) but replaces the presentation: left = `components/ai-writing-chat/WritingChatPanel.tsx` (timeline + **button-only intervention cards** `ChatInterventionCards.tsx` — the five pause cards copied from `InterventionCard.tsx` with all inline textareas removed, confirm/action buttons kept — plus a bottom **unified smart composer**). Free text goes through two-level intent resolution (`open-canvas/api/ai-writing-intent.ts`): deterministic short-phrase fast path (确认/继续/重新搜索/重写大纲…; high-cost actions never fast-pathed) then `POST /api/ai-writing/sessions/{id}/intent` — the backend reads the graph checkpoint (authoritative pause point from the pending interrupt) and routes via `deerflow/agents/ai_writing/intent_router.py` (LLM + strict per-pause action whitelist aligned to the graph's real resume actions, confidence gates: finalize/force_finalize/覆盖式 re_search need ≥0.85 else clarify, payload key-whitelist cleaning). Results map to `submitIntervention`/control (暂停/继续/后台挂起)/QA bypass (`answer` rendered as a chat bubble, never touches graph state)/clarify (amber follow-up bubble with multi-turn context). **Two-state layout**: idle (未开始写作) renders the **classic setup experience unchanged** — `WritingSetupChat` + collapsible `AIWritingPanel` form under `WritingFormProvider` (same as `AIWritingPage`'s idle branch); once writing starts (or history view opens) it switches to the chat workbench. **Unified chronological feed** (`ChatFlowTimeline.tsx`): intent-layer chat bubbles are interleaved INTO the progress-event timeline by anchor (= `progressEvents.length` at message creation), so events triggered by a user message render **below** it (Google-AI-Studio-style single stream, not timeline-above/chat-below); composer-driven interventions suppress the duplicate 「我的要求」card (`suppressedRequirementIndices`). **素材不足自动续跑** only at `material_confirm` (the only pause the graph supports re-search from): needResearch caches the payload as a pending intent, submits `re_search + userQuery`, and auto-submits the pending intent when the new material-confirm pause arrives (cancellable pill). Stage chips + per-stage placeholder + 「当前交互对象」status badge. Backend 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).
+- **菜单管理 (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). **简介模式** left-nav is a separate overlay: `/api/compact-menu-overrides` stores two independent sets (type `A` / `B`); each website picks one via `runtime-config.js` `VITE_COMPACT_MENU_TYPE`.
 - **白名单管理 (Login Whitelist, admin-only)**: gates **who may log in**, run as a **blocklist (黑名单模式)**. Two pieces: a global master switch (`system_settings.json → login_whitelist.enabled`, surfaced by **admin-only** `GET|PUT /api/system-settings/login-whitelist`) + a per-user **放行** flag (`users.approved` column, migration `20260625_02`). Users **self-register** as usual and **every new account defaults to `approved=True`** — so a user who has never logged into this system before is allowed straight through; the switch only blocks users an admin has explicitly **取消放行** (`approved=False`). (`create_user`/`User`/`UserRow` all default `approved=True`; admins are always approved; existing rows are backfilled `True`.) Login interception is the single helper `enforce_user_approved(user)` in `app/gateway/routers/auth.py`, called in all three login endpoints (`/login/{local,username,token}`) **after** the account is resolved/created and **before** the JWT is issued: switch off → everyone passes; `system_role=="admin"` → always passes (anti-lockout); else `approved=False` (admin-revoked) → 403 `{code:"PENDING_APPROVAL"}` (the frontend's `extractErrorMessage` surfaces the message and login throws before writing any auth state, so no half-login). Admin approves on `pages/LoginWhitelistPage.tsx` (route `/page/strategy/admin/login-whitelist`, entry「白名单管理」in the bottom-left settings dropdown of `components/page-sidebar.tsx`, both sidebar modes): a top master-switch + a list of all registered users (`GET /api/v1/auth/users`, now carrying `approved`) with a per-row 放行 Switch (`PUT /api/v1/auth/users/{id}/approval`, admin-only; revoking only blocks the **next** login — `token_version` is left untouched, existing sessions are not force-killed). Client/hooks: switch in `strategy-components/api/login-whitelist.ts`, user list + approval in `core/auth/{api,hooks}.ts` (`useSetUserApproval`). Backend tests: `tests/test_login_approval.py`. **账号级「登录口令」(per-account password — 临时开通)**: the same page also lets an admin assign one specific account an individual **plaintext** password (`users.login_password` column, migration `20260625_04`, nullable; auto-added on startup by `_ensure_orm_columns_sync`). Once set, **that account's** username login (`POST /api/v1/auth/login/username`) **requires** `?password=` to exactly match it and that personal password **takes precedence over** the global shared-password gate (`username_login.require_password`); accounts without one keep today's shared-gate / passwordless behavior. The user then logs in via the **existing** frontend URL `#/login/<用户名>?password=xxxx` (LoginPage already forwards `?password=`; `<用户名>` = the account's email `@`-prefix). **Plaintext is intentional** — the password rides in the URL query anyway, so storing it readably lets the admin re-copy the full login link from the page; it is exposed only on the **admin-only** `GET /api/v1/auth/users` (`UserListItem.login_password`) and the new admin-only `PUT /api/v1/auth/users/{id}/login-password` (set non-empty / clear with null·empty; doesn't touch `token_version`). The whitelist page renders a per-user 「登录口令」 column with a set/修改 editor + a live 「复制登录链接」 button (`useSetUserLoginPassword` in `core/auth/hooks.ts`, `setUserLoginPassword` in `core/auth/api.ts`). Backend gate helper `_lookup_user_by_username` (lookup-only, no auto-register) in `routers/auth.py`; tests `tests/test_login_personal_password.py`.
 - **敏感词管理 (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, openMode, loginParams, appendAuth, authTokenParam, authNameParam, 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). **`url` buttons support two independent, coexisting login-append mechanisms**: (1) **`loginParams` (追加登录参数, like 应用管理/Light App Center)** — a list of `{key, source, customValue}` resolved at click time: `runTaskButton` reads `userInfo` (via `readUserInfo` from `strategy-components/lib/light-app`, embed-isolated through `authStorage`) and appends `?{key}={value}` for each (`source` = a userInfo field such as `accessToken`/`yUserId`, or `other` → literal `customValue`); empty list = nothing appended. Reuses `LOGIN_SOURCE_OPTIONS` from light-app; stored as JSON column `task_buttons.login_params_json` (`PortableJSON`, migration `20260625_01`). (2) **`appendAuth` (追加登录态)** — appends `?{authTokenParam}={token1}&{authNameParam}={username}` (default param names `token`/`username`) so the跳转目标外部系统 can identify the current user — e.g. `…/action/sentiment?token=<JWT>&username=lizhaoxing`. **Gated on token login**: `token1` = the `?authToken=` used by token-exchange login; `username` = the raw login name the backend resolved from `getTokenInfo`. Both are stashed at login by `persistLoginCredentials` into `login.token1`/`login.username` (`core/auth/login-credentials.ts`, scoped via [[scoped-storage]] so嵌入/独立会话隔离 + 随独立会话迁移). Only token login writes them → a non-token-login session has no `token1`, so `runTaskButton` silently skips the auth append (the jump still works, just without those two params). The frontend reads `username` straight from the new `UsernameLoginResponse.username` field (the stored email local-part is lossy — lowercased/normalized — so not used), **not** by decoding the JWT. Stored as columns `task_buttons.{append_auth, auth_token_param, auth_name_param}` (migration `20260625_02`). The admin page renders both editors for `url` buttons (loginParams 虚线框 + 追加登录态 switch). **`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. **Bottom 快捷跳转 bar groups by prev/next**: `TaskJumpBar` renders only「上一步/下一步」-type buttons in the bottom bar — a `prev` group (id 含 `prev` 或文案「上一步」, 描边次要样式 + ←图标) rendered **左侧**, then a `next` group (id 含 `next` 或文案「下一步」, 实心主色) on the **右侧** (container `justify-end`); everything else goes to the right-edge floating menu. The default 上一步 button (`rwfx-prev`, `url`, target = `DASHBOARD_AGENT_ROUTE` `/page/strategy/dashboard-agent`, `appendTaskId` + `idParam=taskId` → `?taskId=任务id`, `openMode=self`) 默认指向**应用内**「大屏绘制」页，在 **both** 单智能体 (`TaskFxWorkspace`) 与 多智能体会商 (`RoundtablePlanningPage` 深链 rwfx-A) 都显示（共用 `TaskJumpBar`）。**`runTaskButton` 的 `url` 类型支持应用内路由**：target 以单个 `/` 开头时按内部路由处理——`self` 走 react-router 同窗导航（不刷新），`blank` 拼成当前源的 hash 路由新标签打开；外链行为不变。 The old hardcoded jump buttons were migrated out: `TaskFxWorkspace` no longer hardcodes 切换到三Line truncated
+- **按钮管理 (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, openMode, loginParams, appendAuth, authTokenParam, authNameParam, 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). **`host`（宿主路由）** asks the embedding parent to navigate: `runTaskButton` sends `window.parent.postMessage({ type:'HOST_NAVIGATE', path, queryParams:{ [idParam]: Number(taskId) } }, hostOrigin)` — `target` is the host route (e.g. `/task/item-aiceh/step-analysis-audience`), `appendTaskId`/`idParam` become numeric `queryParams` (task id only), origin from `runtime-config.js` `VITE_HOST_NAVIGATE_ORIGIN` (else ancestorOrigins/referrer; never `*`). Independent-tab clicks toast and do nothing. **`url` buttons support two independent, coexisting login-append mechanisms**: (1) **`loginParams` (追加登录参数, like 应用管理/Light App Center)** — a list of `{key, source, customValue}` resolved at click time: `runTaskButton` reads `userInfo` (via `readUserInfo` from `strategy-components/lib/light-app`, embed-isolated through `authStorage`) and appends `?{key}={value}` for each (`source` = a userInfo field such as `accessToken`/`yUserId`, or `other` → literal `customValue`); empty list = nothing appended. Reuses `LOGIN_SOURCE_OPTIONS` from light-app; stored as JSON column `task_buttons.login_params_json` (`PortableJSON`, migration `20260625_01`). (2) **`appendAuth` (追加登录态)** — appends `?{authTokenParam}={token1}&{authNameParam}={username}` (default param names `token`/`username`) so the跳转目标外部系统 can identify the current user — e.g. `…/action/sentiment?token=<JWT>&username=lizhaoxing`. **Gated on token login**: `token1` = the `?authToken=` used by token-exchange login; `username` = the raw login name the backend resolved from `getTokenInfo`. Both are stashed at login by `persistLoginCredentials` into `login.token1`/`login.username` (`core/auth/login-credentials.ts`, scoped via [[scoped-storage]] so嵌入/独立会话隔离 + 随独立会话迁移). Only token login writes them → a non-token-login session has no `token1`, so `runTaskButton` silently skips the auth append (the jump still works, just without those two params). The frontend reads `username` straight from the new `UsernameLoginResponse.username` field (the stored email local-part is lossy — lowercased/normalized — so not used), **not** by decoding the JWT. Stored as columns `task_buttons.{append_auth, auth_token_param, auth_name_param}` (migration `20260625_02`). The admin page renders both editors for `url` buttons (loginParams 虚线框 + 追加登录态 switch). **`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. **Bottom 快捷跳转 bar groups by prev/next**: `TaskJumpBar` renders only「上一步/下一步」-type buttons in the bottom bar — a `prev` group (id 含 `prev` 或文案「上一步」, 描边次要样式 + ←图标) rendered **左侧**, then a `next` group (id 含 `next` 或文案「下一步」, 实心主色) on the **右侧** (container `justify-end`); everything else goes to the right-edge floating menu. The default 上一步 button (`rwfx-prev`, `url`, target = `DASHBOARD_AGENT_ROUTE` `/page/strategy/dashboard-agent`, `appendTaskId` + `idParam=taskId` → `?taskId=任务id`, `openMode=self`) 默认指向**应用内**「大屏绘制」Line truncated
 - **实时并发监控 (Concurrency / System-Pressure Monitor, admin-only)**: a live panel mounted at the **top of the admin 排行榜 page** (`components/workspace/admin/concurrency-monitor.tsx` `ConcurrencyMonitorPanel`, rendered in `pages/AdminUserLeaderboardPage.tsx`) showing **当前并发的大模型调用数 + 列表（用户/智能体/类型/已运行时长）**, each row with a 「停止」button (and a 「全部停止」) that **truly aborts** that run's in-flight model stream via `RunManager.cancel` (`POST /api/admin/active-runs/{run_id}/cancel`) — to relieve pressure when 使用人数过多. Two line charts (minute/hour toggle): **并发量折线图** (peak/avg, `GET /api/admin/active-runs/concurrency`, fed by a lightweight background sampler into `concurrency_samples`) and **大模型出字速度折线图** (tokens/sec, `GET /api/admin/active-runs/token-speed`, aggregated from `llm_call_metrics`) so a dip pinpoints where the bottleneck is. A **「后台采样」Switch** (`system_settings.json → concurrency_monitor.enabled`, **default off / opt-in**, `GET|PUT /api/admin/active-runs/settings`) turns the background sampling on/off **at runtime, no restart** (the live concurrency count + 「停止」 work even while sampling is off — only the 并发量 history chart needs it on); everything is designed to **never impact production** (one tiny INSERT/15s, retention-purged, best-effort). Client/hooks: `core/admin/active-runs.ts` + `core/admin/hooks.ts` (`useActiveRuns`/`useConcurrencySeries`/`useTokenSpeedSeries`/`useCancel*`/`useMonitorSettings`). See the backend CLAUDE.md「Admin Concurrency Monitor」.
-- **会话冲突 409 中文化**: when a user submits a new question while the previous turn is still streaming, the backend's `RunManager.create_or_reject` rejects with HTTP 409 (`services.py` now returns a **Chinese** detail「当前对话还在生成回答…」). `core/threads/hooks.ts` `onError` detects the conflict (`isActiveRunConflictError`: 409 / "already has an active run" / the Chinese text) and shows a friendly `toast.info` instead of a raw error.
+- **会话冲突 409 中文化**: when a user submits a new question while the previous turn is still streaming, the backend's `RunManager.create_or_reject` rejects with HTTP 409 (`services.py` now returns a **Chinese** detail「当前对话还在生成回答…」). `core/threads/hooks.ts` `onError` detects the conflict (`isActiveRunConflictError`: 409 / "already has an active run" / the Chinese text). A premature SSE close (SDK treats it as success and restores the send button while the backend run is still occupying the thread) is recovered by `confirmOrRejoin`: hold the stop button, `joinStream` the live run, and on 409 auto-reconnect instead of a fake AI bubble. `sse_consumer` no longer ends a resumable (`on_disconnect=continue`) stream on a false-positive `is_disconnected()`.
 - **State**: TanStack Query for server state, context providers (`SubtasksProvider`, `ArtifactsProvider`, `PromptInputProvider`) scoped to `WorkspaceRoutes`
 - **LLM streaming**: `@langchain/langgraph-sdk` streams messages from the backend via SSE
 - **UI**: Radix UI primitives + TailwindCSS v4 + shadcn-style components in `src/components/ui/`

frontend-web/.env.development

@@ -8,7 +8,7 @@ VITE_USE_REAL_DATA=true
 VITE_MOCK_COP_TASK_DETAIL=true
 
 # 研判情报报告（大屏绘制智能体深链 selectSqReport）数据源：true 走本地样例假数据（真实接口未就绪时调试用）；联调通过后置 false。
-VITE_MOCK_SQ_REPORT=true
+VITE_MOCK_SQ_REPORT=false
 
 # 深链任务详情（cop-task-detail：任务名称/描述）数据源：true 走本地假数据（真实接口未就绪时调试用）；联调通过后置 false。
 VITE_MOCK_COP_TASK_DETAIL=true

frontend-web/.env.example

@@ -37,6 +37,10 @@
 # 默认真实接口（未设/false）；改成 true 时该接口走本地假数据（consumer 外网不可达时调试用）。
 # 与 VITE_USE_REAL_DATA 独立。改后需重启 dev / 重新打包生效。
 # VITE_MOCK_COP_TASK_DETAIL=false
+# VITE_POSITION_ROUNDTABLE_DEMO_MODE=false
+# true=免登录直达岗位分析，完全使用前端 JSON，不请求任何后台接口。
+# 仅限离线演示环境；生产环境请保持 false。
+# VITE_POSITION_ROUNDTABLE_STANDALONE_MODE=false
 
 # MaxKey 鉴权根地址（无界 onlineTicket 换 token）
 # VITE_AUTH_BASE_URL=https://auth.y.sit.4.cn
@@ -52,4 +56,7 @@
 # VITE_STATIC_WEBSITE_ONLY=
 # 部署级紧凑导航：true 时固定收起工作台左侧栏，并隐藏换肤与全量/简洁模式切换。
 # VITE_FORCE_COLLAPSED_SIDEBAR=false
+# 简介模式左侧菜单类型：与菜单管理页「简介模式」的类型 A / B 对应。两套网页分别填 A 或 B。
+# 不填或留空时按类型 A，继续使用原来的简介菜单数据。
+# VITE_COMPACT_MENU_TYPE=A
 # VITE_GITHUB_OAUTH_TOKEN=

frontend-web/design-qa.md

@@ -0,0 +1,46 @@
+**Comparison target**
+
+- Source visual truth (dark intelligent-agent list): `C:/Users/董宏凯/AppData/Local/Temp/codex-clipboard-75f6ce1c-cd70-4b8c-a80a-a3d100105c69.png`
+- Additional source references: `C:/Users/董宏凯/AppData/Local/Temp/codex-clipboard-00567484-ba8a-4595-b386-52e1467ae9cf.png` (segmented switch), `C:/Users/董宏凯/AppData/Local/Temp/codex-clipboard-02808803-05ba-4f2c-be50-c72b484a9f06.png` (business-chain node card), `C:/Users/董宏凯/AppData/Local/Temp/codex-clipboard-adf38fec-7baf-4d01-9c73-bdbae94b774e.png` (business-chain selector)
+- Implementation screenshots: `C:/Users/董宏凯/AppData/Local/Temp/position-roundtable-revised-light.png`, `C:/Users/董宏凯/AppData/Local/Temp/position-roundtable-revised-dark.png`
+- Full-view comparison evidence: `C:/Users/董宏凯/AppData/Local/Temp/position-roundtable-revised-comparison.png`
+- Viewport: 1280 × 720. Light route: `#/page/strategy/qa/position-roundtable`; dark embedded route: `#/page/strategy/qa/position-roundtable?embed=1&theme=dark`.
+- State: local browser has no authenticated API session. The original intent API is invoked and reports `Authentication required`; business-chain and agent endpoints return no usable data.
+
+**Findings**
+
+- [P1] Populated agent and business-chain states cannot be compared yet.
+  Location: right agent list and non-planning-role chain diagram.
+  Evidence: reference images show populated cards and nodes; the implementation has `0 个` agents and no available business chain in the unauthenticated preview.
+  Impact: card density, selected-card indicator, chain node flow, and agent-detail transition cannot be truthfully verified against live data.
+  Fix: verify the route in an authenticated session with at least one public chain and tagged agents.
+
+**Open Questions**
+
+- The final business-chain stage arrangement is still pending product confirmation. The compact graph maps whatever stage configuration is returned, while intentionally omitting dependency-label text as requested.
+
+**Implementation Checklist**
+
+1. Left task panel is now display-only and retains its independent position-roundtable task adapter.
+2. Business-chain selection uses the original roundtable card/radio/relationship-entry pattern.
+3. Every position uses the original `useStep1Intent` interface and `Step1Panel` message list/input panel; only the position header changes.
+4. The right switch now uses the exact `课题研究 / ai写作` segmented-control treatment (light gray track, white active state; dark blue glass equivalent).
+5. The embedded layout widens the left panel to 360px and applies the deep-blue right-panel tokens used by the reference.
+6. Other roles render a taller top-to-bottom card-node flow without dependency labels. The canvas supports mouse-drag panning, and each node retains only a name plus a single-line description.
+
+**Follow-up Polish**
+
+- [P3] If live content is unusually long, tune the compact flow node width or horizontal scrolling after seeing the production chain data.
+
+**Comparison history**
+
+- Iteration 1: task fields were editable and the right TDesign card tabs looked unlike the reference. Replaced the task form with display-only information and replaced the tabs with the existing `课题研究 / ai写作` segmented switch.
+- Iteration 2: business-chain selection was a dropdown and the flow was vertical avatar chips. Replaced it with original-roundtable selection cards and compact business-chain configuration-style node cards with link lines but no dependency labels.
+- Iteration 3: dark right-panel background differed from the supplied deep-blue reference. Applied the `#032650` / `#042b59` / `#2b8ffe` token family and captured the revised embedded dark state in the full-view comparison.
+- Iteration 4: removed the custom disabled input from non-planning positions and reused the original roundtable input panel. Enlarged the left flow viewport, retained its connection lines, and removed node level/seat/status metadata.
+- Iteration 5: converted the compact flow from left-to-right to top-to-bottom. Added mouse-drag panning and single-line description truncation; populated-chain visual QA remains blocked by the unauthenticated preview.
+- Iteration 6: constrained the flow canvas to its card viewport, narrowed nodes from 190px to 158px, and realigned branch gaps plus connector anchors to prevent clipping and offset lines.
+
+**Final result**
+
+blocked

frontend-web/docs/position-roundtable-delivery-workflow-plan.md

@@ -0,0 +1,362 @@
+# 岗位会商交付闭环与内置智能体实现计划
+
+> 页面：`/page/strategy/qa/position-roundtable`
+>
+> 目标：在现有岗位会商基础上补齐“产物交付、查看、驳回、方案总结、行动规划”的完整闭环，同时继续保持原多智能体会商页面不受影响。
+
+## 实施核对（2026-07-21）
+
+本计划已按“岗位会商独立路由、无总控、各席位直接问答”的边界完成第一轮闭环。实际流程调整为：
+
+```text
+任务信息 → 情报分析岗识别并确认意图 → 启动校验并冻结业务链
+→ 分阶段席位直接问答/交付 Markdown → 全部有效交付
+→ 方案总结智能体（roundtable-summary）→ 行动规划智能体（position-action-planner）
+→ 可随时返回交付产物驳回 → 后续阶段及内置产物级联失效 → 重做后重新收口
+```
+
+- [x] 情报意图、业务链选择、席位岗位归属和席位智能体配置均在启动前校验；启动后保存业务链快照。
+- [x] 普通席位直接调用各自分配的智能体，并注入任务、意图及已完成上游席位的问答/产物；不经过总控智能体。
+- [x] 普通席位必须在 `outputs` 中交付 Markdown 才会完成；情报分析岗以确认的结构化意图完成为准。
+- [x] 节点、交付卡片、流程图和大图弹窗均展示 `locked / ready / running / done / rejected / stale / error` 状态，并可回看节点会话和产物。
+- [x] 驳回要求标题和理由；当前节点转为 `rejected`，后续阶段按依赖转为 `stale/locked`，总结和行动规划同时失效，历史内容保留可查看。
+- [x] 被驳回或失效的普通席位必须写入一份**新的或已改写** Markdown 才能再次完成；单纯继续问答且没有新交付不会误使下游产物失效。
+- [x] 方案总结复用 `roundtable-summary` 的真实流式线程；行动规划新增 `position-action-planner`，强制输出 Markdown 报告和 `action-plan-subtasks.json`。
+- [x] 两个内置智能体的线程、产物快照和来源节点版本栅栏均持久化；流式期间若上游版本变化，旧运行不能覆盖最新状态。
+- [x] 右侧“交付产物”可查看内置节点结果、继续同一线程问答/修改交付，并在打开 Markdown 沙箱时自动收起右栏。
+
+设计收敛：当前版本以节点的 `artifact_manifest`、`latest_answer`、版本、驳回记录及 Session 内置快照作为唯一事实来源，已能覆盖统一产物卡片和级联逻辑，因此不新增重复的 `position_roundtable_deliverables` 表。若后续需要“单个文件独立驳回、跨会话检索或完整版本对比”，再将清单归一化为独立产物表，避免现在的双写一致性风险。
+
+## 数据持久化与灾难恢复（2026-07-23）
+
+岗位会商现在使用“两层持久化”，两层职责不同：
+
+1. LangGraph checkpoint/thread 是智能体继续推理与流式问答的执行源。
+2. `position_roundtable_sessions` / `position_roundtable_nodes` 是页面历史的数据库恢复源。
+
+数据库恢复源会保存：
+
+- 情报分析岗完整消息、步骤时间线和未发送输入草稿；
+- 每个业务链岗位的完整消息和未发送输入草稿；
+- 方案总结、行动规划两个收口智能体的完整消息和未发送输入草稿；
+- 已确认意图、冻结任务与业务链快照、节点状态、版本、驳回记录；
+- Markdown / JSON 等文本产物正文（单文件最多 400 万字符）和文件元数据。
+
+因此即使线上重启后 checkpoint 或沙箱 outputs 卷丢失，历史页仍能从数据库展示对话与产物正文，后续收口智能体也能继续读取数据库中的有效上游交付。新任务在意图识别开始前就会创建 Session，用户不必等到“启动业务链”才获得持久化保护。历史下拉支持删除，删除会显式清理 Session 与全部节点恢复快照，不依赖 SQLite 外键开关。
+
+对应迁移：`20260723_05_position_roundtable_conversations.py`。部署时必须执行到 Alembic head。
+
+## 0. 核心结论
+
+- 方案总结智能体建议复用现有会商里的 `roundtable-summary` 能力，但不要直接搬整套 Step 3 页面流程。
+  - 可复用：内置智能体 ID、总结报告 prompt 组织方式、Markdown 报告产物、流式对话、报告续问与文件预览能力。
+  - 需要改造：输入材料从“总控共识 + 各席位交付”改成“任务信息 + 意图结果 + 已通过的岗位产物 + 业务链快照”，并把结果存到岗位会商 Session 下。
+- 行动规划智能体建议作为新的内置智能体新增。
+  - 输入：方案总结报告、各岗位最终有效产物、业务链阶段信息、任务意图。
+  - 输出：行动规划报告、结构化子任务清单。
+- 这个模式仍然不需要总控智能体。情报分析岗负责意图识别，业务链节点直接调用各自配置的智能体，最终再由内置总结/规划智能体收口。
+- 驳回不删除历史内容，只改变“当前有效版本”的状态；被驳回节点和后续节点需要重新交付，既保留可追溯性，也方便后续返回查看。
+
+## 1. 目标业务流程
+
+1. 情报分析岗进入页面，查看任务信息并完成意图识别。
+2. 用户点击“确认意图并启动业务链”。
+3. 启动前做校验：
+   - 未选择业务链：提示“请先选择业务链”。
+   - 业务链存在未配置岗位的席位：提示并引导去业务链配置页。
+   - 业务链席位缺少智能体：提示具体席位名称。
+   - 意图尚未完成：提示先完成任务意图识别。
+4. 校验通过后冻结业务链快照，初始化岗位会商节点。
+5. 各岗位只对分配给本岗位的智能体进行问答。
+6. 节点问答完成后形成交付产物，右侧产物卡片显示“已完成 / 未完成 / 进行中 / 已驳回 / 已失效”。
+7. 左侧流程图显示各节点状态，节点可点击查看该节点对话与产物。
+8. 流程图右上角提供“查看”按钮，打开弹窗展示更完整的业务链流程图。
+9. 当业务链中所有岗位产物都处于有效已交付状态后，开放“方案总结”。
+10. 方案总结完成后开放“行动规划”。
+11. 即使进入方案总结或行动规划，用户仍可返回产物列表执行驳回。
+12. 若驳回早期阶段产物，后续阶段产物、方案总结、行动规划都一起失效并回到待重新完成状态。
+
+## 2. 状态设计
+
+### 2.1 节点状态
+
+现有节点状态需要扩展或映射为更贴近页面的展示状态：
+
+| 展示状态 | 建议内部状态 | 含义 |
+| --- | --- | --- |
+| 未完成 | `ready` / `locked` / `rejected` | 尚未有效交付，或被驳回后等待重做 |
+| 进行中 | `running` | 当前智能体正在回答或产物正在生成 |
+| 已完成 | `done` | 当前节点已有有效交付 |
+| 已失效 | `stale` | 上游被更新或驳回，当前结果不可作为最终材料 |
+| 异常 | `error` | 生成或保存失败 |
+
+建议新增 `rejected` 状态，便于区分“从未完成”和“被驳回后待重做”。如果第一轮想少改后端，也可以先用 `ready + rejection_record` 表示被驳回。
+
+### 2.2 产物状态
+
+产物状态建议独立于节点状态保存，因为一个节点可能同时有回答文本和多个文件产物。
+
+| 状态 | 含义 |
+| --- | --- |
+| `pending` | 还没有交付 |
+| `running` | 正在生成 |
+| `delivered` | 已交付且当前有效 |
+| `rejected` | 被用户驳回 |
+| `stale` | 受上游驳回或重做影响，已经失效 |
+
+### 2.3 内置收口节点
+
+在流程图中把两个内置节点追加到业务链末尾：
+
+1. `builtin:summary`：方案总结智能体。
+2. `builtin:action-plan`：行动规划智能体。
+
+这两个节点不属于普通业务链席位，但要和普通节点一样显示状态、支持点击查看结果。
+
+## 3. 数据模型调整
+
+### 3.1 Session 扩展
+
+`position_roundtable_sessions` 已使用下列持久化字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `status` | `intent_pending / active / completed / archived`；总结/规划运行态由前端瞬时状态与对应快照的 `status` 表示，避免一次运行中断后留下伪运行态 |
+| `summary_thread_id` | 方案总结智能体线程 |
+| `summary_snapshot` | 最新有效总结报告快照 |
+| `action_plan_thread_id` | 行动规划智能体线程 |
+| `action_plan_snapshot` | 最新有效行动规划快照 |
+| `invalidated_at` | 记录在 `summary_snapshot` / `action_plan_snapshot` 内，包含 `invalidated_by`，无需重复写 Session 字段 |
+
+### 3.2 Node 扩展
+
+`position_roundtable_nodes` 已使用下列字段（展示状态由前端按状态映射）：
+
+| 字段 | 含义 |
+| --- | --- |
+| `status` | `locked / ready / running / done / stale / rejected / error`，前端直接映射为展示状态 |
+| `rejection_count` | 当前节点累计驳回次数 |
+| `last_rejection` | 最新驳回标题、理由、操作者、时间 |
+| `revision` | 当前有效交付版本 |
+| `invalidated_by` | 导致当前节点失效的上游节点 key |
+
+### 3.3 Deliverable 新表（后续可选）
+
+当需要“单个文件独立驳回、跨会话检索或完整版本对比”时，再新增 `position_roundtable_deliverables`，不要只依赖 `artifact_manifest`。
+
+| 字段 | 含义 |
+| --- | --- |
+| `id` | 产物 ID |
+| `session_id` | 会话 ID |
+| `node_key` | 来源节点 |
+| `agent_id` | 来源智能体 |
+| `position_id` | 来源岗位 |
+| `title` | 产物名称 |
+| `kind` | `answer / file / summary / action_plan` |
+| `content` | 文本产物内容摘要或正文 |
+| `artifact_path` | 文件产物虚拟路径 |
+| `thread_id` | 所属线程 |
+| `status` | `pending / running / delivered / rejected / stale` |
+| `revision` | 来源节点版本 |
+| `rejection_title` | 驳回标题 |
+| `rejection_reason` | 驳回理由 |
+| `created_at` | 创建时间 |
+| `updated_at` | 更新时间 |
+
+当前第一轮不新增这张表：右侧产物卡片、驳回记录、总结输入材料从节点 `artifact_manifest`、节点版本/驳回记录和 Session 快照聚合，避免节点表与产物表双写。后续引入该表时，应把它提升为唯一事实来源，而不是并行维护两套状态。
+
+## 4. 驳回与级联失效规则
+
+### 4.1 基本驳回
+
+用户点击产物卡片的“驳回”后弹窗填写：
+
+- 驳回标题。
+- 驳回理由。
+
+提交后：
+
+- 当前产物状态改为 `rejected`。
+- 当前节点状态改为 `rejected` 或 `ready`。
+- 当前节点的 `latest_answer` 和历史文件不删除，但不再作为有效交付输入。
+- 记录 `last_rejection`，用于页面展示和后续追踪。
+
+### 4.2 级联失效
+
+如果驳回的节点位于第 N 阶段：
+
+- 同阶段其他节点不自动驳回，除非业务链未来明确配置了依赖关系。
+- 第 N+1 阶段及之后所有节点的有效产物全部标记为 `stale`。
+- 后续节点状态回到未完成展示态。
+- `builtin:summary` 和 `builtin:action-plan` 如果已经生成，也标记为 `stale`。
+- 页面允许用户继续查看旧报告和旧行动规划，但必须提示“上游产物已变更，需要重新生成”。
+
+### 4.3 重新交付
+
+被驳回节点重新问答并完成后：
+
+- 当前节点产生新的 `revision`。
+- 当前节点产物状态变为 `delivered`。
+- 只有当该阶段所有必要节点都重新有效交付后，下一阶段才重新解锁。
+- 方案总结和行动规划必须基于最新有效产物重新生成。
+
+## 5. 接口规划
+
+### 5.1 启动与校验
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| `POST` | `/api/position-roundtable/sessions/{id}/validate-activation` | 校验业务链、岗位、智能体、意图状态 |
+| `POST` | `/api/position-roundtable/sessions/{id}/activate` | 校验通过后冻结链条并初始化节点 |
+
+第一轮也可以先把校验合并在 `activate` 内，前端根据后端返回的错误码提示。
+
+### 5.2 产物
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| `GET` | `/api/position-roundtable/sessions/{id}/results` | 获取右侧统一产物来源节点（前端聚合文件与内置快照） |
+| `GET` | `/api/position-roundtable/sessions/{id}/nodes/{node_key}` | 获取节点详情；文件正文由既有线程产物预览接口读取 |
+| `POST` | `/api/position-roundtable/sessions/{id}/nodes/{node_key}/reject` | 驳回当前节点交付并触发级联失效 |
+| `POST` | `/api/position-roundtable/sessions/{id}/nodes/{node_key}/complete-turn` | 节点回答结束后同步回答与产物 |
+
+### 5.3 方案总结与行动规划
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| `POST` | `/api/position-roundtable/sessions/{id}/summary/prepare` | 服务端准备版本锁定的总结材料和线程信息 |
+| `POST` | `/api/position-roundtable/sessions/{id}/summary/ask` | 服务端准备总结的同线程续问材料 |
+| `POST` | `/api/position-roundtable/sessions/{id}/summary/complete` | 校验 Markdown 交付与来源版本后持久化总结快照 |
+| `POST` | `/api/position-roundtable/sessions/{id}/action-plan/prepare` | 服务端准备行动规划材料和线程信息 |
+| `POST` | `/api/position-roundtable/sessions/{id}/action-plan/ask` | 服务端准备行动规划同线程续问材料 |
+| `POST` | `/api/position-roundtable/sessions/{id}/action-plan/complete` | 校验 Markdown + JSON 交付与来源版本后持久化行动规划快照 |
+
+可以复用现有 `streamMultiAgent` 流式协议，但建议在岗位会商下包一层 API，由后端负责拼装岗位会商材料，前端不直接拼长 prompt。
+
+## 6. 前端实施步骤
+
+### 阶段 1：状态与启动校验（已完成）
+
+- 扩展 `PositionNodeStatus` 和状态显示映射。
+- “确认意图并启动业务链”前补齐校验提示。
+- 后端 `activate` 返回未配置岗位、缺智能体、未选择链条等具体错误。
+- 左侧流程图节点右上角添加状态小图标。
+- 节点样式调整为上方智能体名称、下方岗位名称，移除左侧 logo。
+
+验收标准：未选择业务链、岗位未配齐、意图未完成时都能准确阻止启动；启动后流程图能显示各节点状态。
+
+### 阶段 2：流程图弹窗（已完成）
+
+- 左侧保留小型从上到下流程图。
+- 流程图右上角增加“查看”按钮。
+- 点击后打开弹窗，展示更大的流程图。
+- 弹窗内支持点击节点查看对话与产物，保持和主页面选中节点同步。
+
+验收标准：小图不挤占左侧空间，大图能完整展示业务链和两个内置收口节点。
+
+### 阶段 3：产物卡片与预览（已完成）
+
+- 右侧新增或改造“分析结果”Tab 为“交付产物”列表。
+- 卡片展示智能体名称、产物名称、岗位名称、时间、状态。
+- 点击卡片打开详情弹窗。
+- 文本产物直接展示正文，文件产物复用现有 `ArtifactPreviewModal`。
+- 每个有效产物提供“驳回”入口。
+
+验收标准：节点回答和文件产物能进入统一产物列表；点击可查看详情。
+
+### 阶段 4：驳回弹窗与级联失效（已完成）
+
+- 新增 `RejectDeliverableDialog`。
+- 驳回表单包含标题和理由，均必填。
+- 后端事务内完成当前产物驳回、当前节点状态更新、后续阶段级联失效、总结和行动规划失效。
+- 前端刷新 Session、Node、Deliverable 和流程图状态。
+- 被驳回节点在对话区显示驳回信息，提示用户重新交付。
+
+验收标准：驳回第一阶段任意节点后，第二阶段及之后产物都显示未完成或已失效；旧内容可查看但不能作为总结输入。
+
+### 阶段 5：方案总结智能体（已完成）
+
+- 封装 `usePositionSummary`，内部复用 `roundtable-summary` 的线程初始化、流式输出和 Markdown 产物预览能力。
+- 输入材料改为岗位会商材料：
+  - 任务信息。
+  - 情报分析岗意图结果。
+  - 业务链快照。
+  - 所有状态为 `delivered` 的岗位产物。
+  - 已驳回或失效产物只作为历史参考，不进入默认总结材料。
+- 方案总结节点追加到流程图末尾。
+- 所有产物有效交付后才允许点击“生成方案总结”。
+- 总结结果写入 `summary_snapshot`，同时进入产物列表。
+
+验收标准：总结报告使用现有方案总结能力生成 Markdown；刷新页面后可恢复；上游驳回后总结标记失效。
+
+### 阶段 6：行动规划智能体（已完成）
+
+- 新增内置智能体 ID，建议先命名为 `position-action-planner`。
+- 新增行动规划 prompt：
+  - 读取方案总结报告。
+  - 读取各岗位最终有效产物。
+  - 拆解为若干子任务。
+  - 每个子任务包含名称、目标、输入依据、责任岗位建议、前置依赖、交付物、验收标准。
+- 输出两类产物：
+  - `行动规划报告.md`。
+  - `action-plan-subtasks.json`。
+- 行动规划节点追加到方案总结之后。
+- 方案总结有效完成后才允许启动行动规划。
+
+验收标准：行动规划能生成可读报告和结构化子任务；刷新可恢复；上游驳回后自动失效。
+
+### 阶段 7：返回修改与重新生成（已完成）
+
+- 用户在方案总结或行动规划视图中仍可切回“交付产物”。
+- 驳回后自动显示需要重做的节点。
+- 重做节点完成后，允许重新生成方案总结和行动规划。
+- 旧总结、旧行动规划保留历史查看，但状态显示“已失效”。
+
+验收标准：不会因为进入总结/规划阶段而锁死前序产物；前序重做后能形成新版本闭环。
+
+### 阶段 8：测试与回归（已完成）
+
+- 后端测试：
+  - activate 校验。
+  - 节点完成后产物入库。
+  - 驳回当前节点。
+  - 驳回第一阶段时后续阶段级联失效。
+  - 总结和行动规划失效。
+- 前端测试：
+  - 启动校验提示。
+  - 状态图标显示。
+  - 产物卡片筛选和预览。
+  - 驳回弹窗必填校验。
+- 回归验证：
+  - 原多智能体会商页面不受影响。
+  - 业务链普通配置入口不显示岗位配置。
+  - 岗位会商页面刷新恢复正常。
+  - 深色模式和嵌入模式布局不溢出。
+
+## 7. 推荐提交拆分
+
+1. `feat(position-roundtable): add delivery status model`
+2. `feat(position-roundtable): validate chain activation`
+3. `feat(position-roundtable): add workflow status graph`
+4. `feat(position-roundtable): add deliverable cards and preview`
+5. `feat(position-roundtable): support rejection cascade`
+6. `feat(position-roundtable): add summary builtin node`
+7. `feat(position-roundtable): add action planning builtin node`
+8. `test(position-roundtable): cover delivery workflow`
+
+## 8. 第一轮建议范围
+
+第一轮优先做最小可闭环：
+
+```text
+意图识别
+→ 启动校验
+→ 业务链节点状态
+→ 节点产物列表
+→ 产物详情查看
+→ 驳回与级联失效
+→ 全部交付后生成方案总结
+→ 基于总结生成行动规划
+```
+
+如果时间紧，行动规划可以先生成 Markdown 报告，结构化 `subtasks.json` 放到第二轮；但数据模型和 UI 入口第一轮就要预留，否则后面会返工。

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/index.html

@@ -16,7 +16,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>CM 助手</title>
-    <script src="/runtime-config.js"></script>
+    <script src="/runtime-config.js" data-runtime-config></script>
   </head>
   <body>
     <div id="root"></div>

frontend-web/package-lock.json

@@ -70,6 +70,7 @@
         "hast": "^1.0.0",
         "katex": "^0.16.28",
         "lucide-react": "^0.562.0",
+        "mermaid": "^11.15.0",
         "motion": "^12.26.2",
         "nanoid": "^5.1.6",
         "next-themes": "^0.4.6",
@@ -104,6 +105,7 @@
         "@types/react": "^19.0.0",
         "@types/react-dom": "^19.0.0",
         "@vitejs/plugin-react": "^5.0.4",
+        "lightningcss": "^1.30.2",
         "postcss": "^8.5.3",
         "tailwindcss": "^4.0.15",
         "tw-animate-css": "^1.4.0",
@@ -460,37 +462,11 @@
       "resolved": "https://registry.npmjs.org/@cfworker/json-schema/-/json-schema-4.1.1.tgz",
       "integrity": "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og=="
     },
-    "node_modules/@chevrotain/cst-dts-gen": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-12.0.0.tgz",
-      "integrity": "sha512-fSL4KXjTl7cDgf0B5Rip9Q05BOrYvkJV/RrBTE/bKDN096E4hN/ySpcBK5B24T76dlQ2i32Zc3PAE27jFnFrKg==",
-      "dependencies": {
-        "@chevrotain/gast": "12.0.0",
-        "@chevrotain/types": "12.0.0"
-      }
-    },
-    "node_modules/@chevrotain/gast": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-12.0.0.tgz",
-      "integrity": "sha512-1ne/m3XsIT8aEdrvT33so0GUC+wkctpUPK6zU9IlOyJLUbR0rg4G7ZiApiJbggpgPir9ERy3FRjT6T7lpgetnQ==",
-      "dependencies": {
-        "@chevrotain/types": "12.0.0"
-      }
-    },
-    "node_modules/@chevrotain/regexp-to-ast": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-12.0.0.tgz",
-      "integrity": "sha512-p+EW9MaJwgaHguhoqwOtx/FwuGr+DnNn857sXWOi/mClXIkPGl3rn7hGNWvo31HA3vyeQxjqe+H36yZJwYU8cA=="
-    },
     "node_modules/@chevrotain/types": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-12.0.0.tgz",
-      "integrity": "sha512-S+04vjFQKeuYw0/eW3U52LkAHQsB1ASxsPGsLPUyQgrZ2iNNibQrsidruDzjEX2JYfespXMG0eZmXlhA6z7nWA=="
-    },
-    "node_modules/@chevrotain/utils": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-12.0.0.tgz",
-      "integrity": "sha512-lB59uJoaGIfOOL9knQqQRfhl9g7x8/wqFkp13zTdkRu1huG9kg6IJs1O8hqj9rs6h7orGxHJUKb+mX3rPbWGhA=="
+      "version": "11.1.2",
+      "resolved": "https://registry.npmmirror.com/@chevrotain/types/-/types-11.1.2.tgz",
+      "integrity": "sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==",
+      "license": "Apache-2.0"
     },
     "node_modules/@codemirror/autocomplete": {
       "version": "6.20.1",
@@ -1732,11 +1708,12 @@
       "integrity": "sha512-l0h88YhZFyKdXIFNfSWpyjStDjGHwZ/U7iobcK1cQQD8sejsONdQtTVU+1wVN1PBw40PiiHB1vA5S7VTfQiP9g=="
     },
     "node_modules/@mermaid-js/parser": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.0.tgz",
-      "integrity": "sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==",
+      "version": "1.2.0",
+      "resolved": "https://registry.npmmirror.com/@mermaid-js/parser/-/parser-1.2.0.tgz",
+      "integrity": "sha512-oYPyv8A4As1yH5Bx+04iQEQxXuIQDe0GKCNSRgao6z8AM9jixXIfP0vsppRLvGf+nKIOb9/LdpWA4YuJiVvESA==",
+      "license": "MIT",
       "dependencies": {
-        "langium": "^4.0.0"
+        "@chevrotain/types": "~11.1.2"
       }
     },
     "node_modules/@opentelemetry/api": {
@@ -4274,6 +4251,66 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": {
+      "version": "1.7.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.1.0",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": {
+      "version": "1.7.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": {
+      "version": "1.1.0",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": {
+      "version": "1.1.0",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/core": "^1.7.1",
+        "@emnapi/runtime": "^1.7.1",
+        "@tybys/wasm-util": "^0.10.1"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": {
+      "version": "0.10.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": {
+      "version": "2.8.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "0BSD",
+      "optional": true
+    },
     "node_modules/@tailwindcss/oxide-win32-arm64-msvc": {
       "version": "4.1.18",
       "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.18.tgz",
@@ -5650,32 +5687,6 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
-    "node_modules/chevrotain": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-12.0.0.tgz",
-      "integrity": "sha512-csJvb+6kEiQaqo1woTdSAuOWdN0WTLIydkKrBnS+V5gZz0oqBrp4kQ35519QgK6TpBThiG3V1vNSHlIkv4AglQ==",
-      "dependencies": {
-        "@chevrotain/cst-dts-gen": "12.0.0",
-        "@chevrotain/gast": "12.0.0",
-        "@chevrotain/regexp-to-ast": "12.0.0",
-        "@chevrotain/types": "12.0.0",
-        "@chevrotain/utils": "12.0.0"
-      },
-      "engines": {
-        "node": ">=22.0.0"
-      }
-    },
-    "node_modules/chevrotain-allstar": {
-      "version": "0.4.3",
-      "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.4.3.tgz",
-      "integrity": "sha512-2X4mkroolSMKqW+H22pyPMUVDqYZzPhephTmg/NODKb1IGYPHfxfhcW0EjS7wcPJNbze2i4vBWT7zT5FKF2lrQ==",
-      "dependencies": {
-        "lodash-es": "^4.18.1"
-      },
-      "peerDependencies": {
-        "chevrotain": "^12.0.0"
-      }
-    },
     "node_modules/class-variance-authority": {
       "version": "0.7.1",
       "license": "Apache-2.0",
@@ -6547,6 +6558,16 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/es-toolkit": {
+      "version": "1.49.0",
+      "resolved": "https://registry.npmmirror.com/es-toolkit/-/es-toolkit-1.49.0.tgz",
+      "integrity": "sha512-G5iZ6Pc/FNRY/soKZHC+TxGDD83rHUDXxzaWhGCX44vAv/tMs56WMusnm/KMNK+luUPsgA9U28cGr4RDlSzL2g==",
+      "license": "MIT",
+      "workspaces": [
+        "docs",
+        "benchmarks"
+      ]
+    },
     "node_modules/esbuild": {
       "version": "0.25.12",
       "resolved": "https://registry.npmmirror.com/esbuild/-/esbuild-0.25.12.tgz",
@@ -7354,7 +7375,9 @@
       }
     },
     "node_modules/katex": {
-      "version": "0.16.28",
+      "version": "0.16.47",
+      "resolved": "https://registry.npmmirror.com/katex/-/katex-0.16.47.tgz",
+      "integrity": "sha512-Eeo8Ys1doU1z+x8AZsPpQu+p/QcZBI5PeOo7QGQdy2x2m0MU/hYagBbGOmXwr5KVbEfVuWv9LpnQWeehogurjg==",
       "funding": [
         "https://opencollective.com/katex",
         "https://github.com/sponsors/katex"
@@ -7372,23 +7395,6 @@
       "resolved": "https://registry.npmjs.org/khroma/-/khroma-2.1.0.tgz",
       "integrity": "sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw=="
     },
-    "node_modules/langium": {
-      "version": "4.2.3",
-      "resolved": "https://registry.npmjs.org/langium/-/langium-4.2.3.tgz",
-      "integrity": "sha512-sOPIi4hISFnY7twwV97ca1TsxpBtXq0URu/LL1AvxwccPG/RIBBlKS7a/f/EL6w8lTNaS0EFs/F+IdSOaqYpng==",
-      "dependencies": {
-        "@chevrotain/regexp-to-ast": "~12.0.0",
-        "chevrotain": "~12.0.0",
-        "chevrotain-allstar": "~0.4.3",
-        "vscode-languageserver": "~9.0.1",
-        "vscode-languageserver-textdocument": "~1.0.11",
-        "vscode-uri": "~3.1.0"
-      },
-      "engines": {
-        "node": ">=20.10.0",
-        "npm": ">=10.2.3"
-      }
-    },
     "node_modules/langsmith": {
       "version": "0.6.0",
       "resolved": "https://registry.npmjs.org/langsmith/-/langsmith-0.6.0.tgz",
@@ -8100,43 +8106,32 @@
       "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w=="
     },
     "node_modules/mermaid": {
-      "version": "11.14.0",
-      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.14.0.tgz",
-      "integrity": "sha512-GSGloRsBs+JINmmhl0JDwjpuezCsHB4WGI4NASHxL3fHo3o/BRXTxhDLKnln8/Q0lRFRyDdEjmk1/d5Sn1Xz8g==",
+      "version": "11.16.0",
+      "resolved": "https://registry.npmmirror.com/mermaid/-/mermaid-11.16.0.tgz",
+      "integrity": "sha512-Zvm3kbstgdpvIJPPItlL7fppIZ3kibvc1oZIGxdvk9t6UFz6flv+Jw7FtRGKwfcI8OckmH04LqG6LlS6X4B1pA==",
+      "license": "MIT",
       "dependencies": {
-        "@braintree/sanitize-url": "^7.1.1",
+        "@braintree/sanitize-url": "^7.1.2",
         "@iconify/utils": "^3.0.2",
-        "@mermaid-js/parser": "^1.1.0",
+        "@mermaid-js/parser": "^1.2.0",
         "@types/d3": "^7.4.3",
         "@upsetjs/venn.js": "^2.0.0",
-        "cytoscape": "^3.33.1",
+        "cytoscape": "^3.33.3",
         "cytoscape-cose-bilkent": "^4.1.0",
         "cytoscape-fcose": "^2.2.0",
         "d3": "^7.9.0",
         "d3-sankey": "^0.12.3",
         "dagre-d3-es": "7.0.14",
-        "dayjs": "^1.11.19",
-        "dompurify": "^3.3.1",
-        "katex": "^0.16.25",
+        "dayjs": "^1.11.20",
+        "dompurify": "^3.3.3",
+        "es-toolkit": "^1.45.1",
+        "katex": "^0.16.45",
         "khroma": "^2.1.0",
-        "lodash-es": "^4.17.23",
         "marked": "^16.3.0",
         "roughjs": "^4.6.6",
         "stylis": "^4.3.6",
         "ts-dedent": "^2.2.0",
-        "uuid": "^11.1.0"
-      }
-    },
-    "node_modules/mermaid/node_modules/uuid": {
-      "version": "11.1.1",
-      "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.1.tgz",
-      "integrity": "sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==",
-      "funding": [
-        "https://github.com/sponsors/broofa",
-        "https://github.com/sponsors/ctavan"
-      ],
-      "bin": {
-        "uuid": "dist/esm/bin/uuid"
+        "uuid": "^11.1.0 || ^12 || ^13 || ^14.0.0"
       }
     },
     "node_modules/micromark": {
@@ -10414,49 +10409,6 @@
         "vite": ">=5.0.0"
       }
     },
-    "node_modules/vscode-jsonrpc": {
-      "version": "8.2.0",
-      "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
-      "integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
-      "engines": {
-        "node": ">=14.0.0"
-      }
-    },
-    "node_modules/vscode-languageserver": {
-      "version": "9.0.1",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz",
-      "integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==",
-      "dependencies": {
-        "vscode-languageserver-protocol": "3.17.5"
-      },
-      "bin": {
-        "installServerIntoExtension": "bin/installServerIntoExtension"
-      }
-    },
-    "node_modules/vscode-languageserver-protocol": {
-      "version": "3.17.5",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
-      "integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
-      "dependencies": {
-        "vscode-jsonrpc": "8.2.0",
-        "vscode-languageserver-types": "3.17.5"
-      }
-    },
-    "node_modules/vscode-languageserver-textdocument": {
-      "version": "1.0.12",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz",
-      "integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA=="
-    },
-    "node_modules/vscode-languageserver-types": {
-      "version": "3.17.5",
-      "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
-      "integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg=="
-    },
-    "node_modules/vscode-uri": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.1.0.tgz",
-      "integrity": "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ=="
-    },
     "node_modules/w3c-keyname": {
       "version": "2.2.8",
       "resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz",

frontend-web/public/runtime-config.js

@@ -7,21 +7,62 @@
 // 4. 这里的默认值来自 .env.network；如某个环境不用某项，可以留空字符串。
 // 5. 布尔开关也用字符串形式填写："true" / "false"。
 window.__CM_RUNTIME_CONFIG__ = {
+  // 品牌图片相对路径会以 runtime-config.js 所在目录为基准解析。
+  // Nginx 以子路径部署时不需要修改前端图片路径。
+  // 打包后可直接替换 dist/brand-assets/ 内的同名 PNG。
+  // 也可以把下方图片地址改为其他 PNG 地址，无需重新打包。
+  // 是否显示整块欢迎页图标区域："true" 显示，"false" 隐藏，默认隐藏。
+  VITE_WELCOME_LOGO_VISIBLE: "false",
+  // 深色主题顶栏 Logo 位置："center" 显示在中间，"left" 显示在左上角，默认中间。
+  VITE_DARK_LOGO_POSITION: "center",
+  // 红白主题的顶栏系统 Logo 图片地址。
+  VITE_BRAND_LOGO_LIGHT_URL: "brand-assets/brand-logo-light.png",
+  // 浅蓝主题的顶栏系统 Logo 图片地址。
+  VITE_BRAND_LOGO_LIGHTBLUE_URL: "brand-assets/brand-logo-lightblue.png",
+  // 绿色主题可单独替换 Logo；默认复用浅色 Logo。
+  VITE_BRAND_LOGO_LIGHTGREEN_URL: "brand-assets/brand-logo-light.png",
+  // 深色主题的顶栏系统 Logo 图片地址。
+  VITE_BRAND_LOGO_DARK_URL: "brand-assets/brand-logo-dark.png",
+  // 红白主题的欢迎页 Logo 图片地址：为空时显示原有 CM 文字和渐变背景。
+  VITE_BRAND_WELCOME_LIGHT_URL: "",
+  // 浅蓝主题的欢迎页 Logo 图片地址：为空时显示原有 CM 文字和渐变背景。
+  VITE_BRAND_WELCOME_LIGHTBLUE_URL: "",
+  VITE_BRAND_WELCOME_LIGHTGREEN_URL: "",
+  // 深色主题的欢迎页 Logo 图片地址：为空时显示原有 CM 文字和渐变背景。
+  VITE_BRAND_WELCOME_DARK_URL: "",
+
   // DeerFlow Gateway 地址：前端自有后端接口，例如 /api/agents、/api/auth、/api/threads 等。
-  // VITE_BACKEND_BASE_URL: "http://10.19.200.5:2026",
+  // VITE_BACKEND_BASE_URL: "https://ch1.b.uat.4.cn/deerflow",
 
   // LangGraph 流式对话接口地址：普通问答、智能体对话等流式能力使用。
-  // VITE_LANGGRAPH_BASE_URL: "http://10.19.200.5:2026/api",
+  // VITE_LANGGRAPH_BASE_URL: "https://ch1.b.uat.4.cn/deerflow/api",
 
   // Canvas/AI 写作独立 LangGraph 地址：为空时前端会回退使用 VITE_LANGGRAPH_BASE_URL。
   VITE_CANVAS_LANGGRAPH_BASE_URL: "",
 
+  // routeKey 短路由的用户名直登口令：例如 #/login/admin?routeKey=a。
+  // 填值时优先使用这里的 password；留空时使用 URL 中的 ?password=。
+  VITE_ROUTE_LOGIN_PASSWORD: "",
+
   // 轻应用「新建笔记」系列接口地址。
   VITE_NOTE_API_BASE_URL: "http://47.88.25.99:8000",
 
   // CMZS 后端接口：任务管理、任务分析、三情分析、行动分析等业务接口。
   VITE_API_BASE_URL: "https://ch1.b.uat.4.cn/zncm",
 
+  // 8BF 嵌入页专用任务系统接口。部署到其他系统时只需修改这一项，
+  // 不影响原多智能体会商使用的任务详情接口。
+  VITE_8BF_TASK_API_BASE_URL: "https://ch1.b.uat.4.cn/zl_consumer",
+
+  // 8BF 会商页右上角「返回」按钮的跳转地址（当前窗口 window.location.href）。
+  // 部署后直接改 dist/runtime-config.js 即可，无需重新打包。留空则点击时提示未配置。
+  VITE_8BF_ROUNDTABLE_BACK_URL: "",
+
+  // 任务深链「宿主路由」按钮的 postMessage targetOrigin（HOST_NAVIGATE）。
+  // 填宿主系统 origin，例如 https://localhost:4912；生产改成他们线上地址。
+  // 留空时尝试用 iframe 的 ancestorOrigins / referrer 自动探测，探测失败则不发送。
+  VITE_HOST_NAVIGATE_ORIGIN: "",
+
   // 佳来模型对话接口。
   VITE_AIPI_CHAT_URL: "https://ch1.b.uat.4.cn/gpt",
 
@@ -62,7 +103,7 @@ window.__CM_RUNTIME_CONFIG__ = {
   VITE_AIPI_FRONTEND_URL: "http://47.88.25.99:3000",
 
   // Consumer 接口：深链任务详情 cop-task-detail、研判情报报告 selectSqReport 等使用。
-  VITE_AIPI_CONSUMER_URL: "http://10.19.200.5:8002/consumer",
+  VITE_AIPI_CONSUMER_URL: "https://ch1.b.uat.4.cn/consumer",
 
   // A 系统跳转地址：人物、组织、事件等列表项打开链接使用。
   VITE_AIPI_PRESENT_URL: "http://present.a.uat.4.cn/present/domain",
@@ -71,7 +112,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",
@@ -85,6 +126,13 @@ window.__CM_RUNTIME_CONFIG__ = {
   // 登录深链任务详情是否使用本地 mock：false=真实接口；true=本地 mock。
   VITE_MOCK_COP_TASK_DETAIL: "false",
 
+  // 岗位会商完整演示数据：true=启动时幂等写入后端；后端不可用时直接使用前端 JSON 兜底。
+  // 默认关闭，避免演示历史记录出现在正常生产账号中。
+  VITE_POSITION_ROUNDTABLE_DEMO_MODE: "false",
+  // 纯前端岗位分析演示：跳过登录，直接进入岗位分析页，并禁止所有后台请求。
+  // 仅用于离线展台/演示环境，生产环境必须保持 false。
+  VITE_POSITION_ROUNDTABLE_STANDALONE_MODE: "false",
+
   // 大屏绘制 selectSqReport 是否使用本地 mock：不在运行时强制覆盖，
   // 由各环境的 .env 文件决定（开发环境为 true，生产环境为 false）。
 
@@ -95,6 +143,25 @@ window.__CM_RUNTIME_CONFIG__ = {
   // 隐藏系统 Logo、换肤按钮以及“全量/简洁模式”切换。修改后刷新页面即可生效。
   VITE_FORCE_COLLAPSED_SIDEBAR: "false",
 
+  // 简介模式左侧菜单类型：与菜单管理页「简介模式」里的类型 A / B 对应。
+  // 两套网页部署时分别填 "A" 或 "B"。不填、留空、或旧配置没有这一项，都按类型 A，
+  // 继续读取原来的简介菜单数据，无需改旧页面。
+  VITE_COMPACT_MENU_TYPE: "A",
+
   // GitHub OAuth Token；不使用 GitHub 相关能力时留空。
   VITE_GITHUB_OAUTH_TOKEN: "",
+
+  // 是否在智能体管理页显示「舆情分析」类型："true" 显示，"false" 隐藏。
+  // 关闭后，该智能体的专用对话地址也会自动跳回智能体管理页。
+  VITE_SENTIMENT_AGENT_VISIBLE: "true",
+
+  // 舆情分析智能体：外部流式问答接口地址（POST，SSE 流式返回）。
+  // 前端会把该地址随请求传给后台转发。留空时该智能体对话页会提示未配置。
+  VITE_SENTIMENT_AGENT_API_URL: "http://alg.gw.y.uat.cn/a6_report_agent/alg/stream/report-agent",
+
+  // 舆情分析智能体：请求头 Authorization Basic Auth 用户名。
+  VITE_SENTIMENT_AGENT_AUTH_USERNAME: "1054841959975223296",
+
+  // 舆情分析智能体：请求头 Authorization Basic Auth 密码。
+  VITE_SENTIMENT_AGENT_AUTH_PASSWORD: "LzqqMTUxMTIwMjQxNjQ2MjY5MDUduC",
 };

frontend-web/scripts/check-chrome109-css.mjs

@@ -31,6 +31,16 @@ const requiredLegacyFallbacks = [
     pattern: /<InputGroup className="h-auto min-h-16">/,
     description: "Prompt textarea must not rely on :has() for its parent height",
   },
+  {
+    file: "src/core/utils/mermaid.ts",
+    pattern: /htmlLabels:\s*false[\s\S]*secure:\s*\[[\s\S]*"htmlLabels"/,
+    description: "Sandbox flowcharts must use native SVG labels in legacy browsers",
+  },
+  {
+    file: "src/core/utils/legacy-html-preview.ts",
+    pattern: /export function downlevelModernColors[\s\S]*function injectLegacyChartShim/,
+    description: "Generated HTML charts must downlevel modern CSS colors for Chrome 109",
+  },
 ];
 
 for (const file of cssFiles) {

frontend-web/src/App.tsx

@@ -37,15 +37,27 @@ import PublicRoundtableSharePage from "./pages/PublicRoundtableSharePage";
 import EmbedChatPage from "./pages/EmbedChatPage";
 import EmbedRoundtablePage from "./pages/EmbedRoundtablePage";
 import DashboardStandalonePage from "@/roundtable-planning/pages/DashboardStandalonePage";
+import PositionRoundtablePage from "@/position-roundtable/pages/PositionRoundtablePage";
+import WeKnoraWikiPageView from "@/strategy-components/components/resource-management/llmwiki/WeKnoraWikiPageView";
+import {
+  isPositionRoundtableStandaloneMode,
+  POSITION_ROUNDTABLE_ROUTE,
+} from "@/position-roundtable/demo/position-roundtable-demo-config";
 import { ChatRuntime } from "./pages/WorkspaceRoutes";
 import { NotFoundPage } from "./pages/NotFoundPage";
 
-const PUBLIC_EMBED_PREFIXES = ["/share/", "/public/", "/roundtable-share/"];
+const PUBLIC_EMBED_PREFIXES = [
+  "/share/",
+  "/public/",
+  "/roundtable-share/",
+  "/embed/knowledge/",
+];
 
 function AppProviders({ children }: { children: React.ReactNode }) {
   const locale = useMemo(() => detectLocale(), []);
   const location = useLocation();
   const publicEmbedTheme = usePublicEmbedTheme();
+  const positionStandaloneMode = isPositionRoundtableStandaloneMode();
   // iframe 嵌入会话（按标签页 sessionStorage）集中在此同步：任何带 `&embed=1` 的入口（深链登录页
   // 或直接深链路由）一进来就启用、`embed=0` 关闭，后续干净路由靠会话维持去 chrome + 强制主题。
   useEffect(() => {
@@ -54,14 +66,18 @@ function AppProviders({ children }: { children: React.ReactNode }) {
   // 操作日志(Y-Log)：启动早期预热上报配置，使 writeYLog 同步读缓存即可工作
   // （刷新后 module 缓存清空，token 登录用户也能继续上报）。失败静默。
   useEffect(() => {
+    if (positionStandaloneMode) return;
     void fetchYLogConfig();
-  }, []);
+  }, [positionStandaloneMode]);
   const forcedTheme = useMemo(() => {
     // iframe 嵌入模式（外部系统 `&embed=1`）最高优先：按本标签页的嵌入主题强制明/暗。
     // 走 next-themes forcedTheme（不写 localStorage）→ 同浏览器另开的正常系统页不受影响。
     const embedTheme = resolveForcedEmbedTheme(location.search);
     if (embedTheme) return embedTheme;
-    const routeTheme = resolveForcedThemeForPath(location.pathname);
+    const routeTheme = resolveForcedThemeForPath(
+      location.pathname,
+      location.search,
+    );
     if (routeTheme) return routeTheme;
     if (location.pathname === "/embed/roundtable") {
       const wp = readWujieProps();
@@ -86,22 +102,23 @@ function AppProviders({ children }: { children: React.ReactNode }) {
       attribute="class"
       storageKey="strategy-theme"
       defaultTheme="light"
-      themes={["light", "dark", "lightblue", "lightgreen"]}
+      themes={["light", "dark", "lightblue", "lightgreen", "iceblue", "lightyellow"]}
       enableSystem={false}
       disableTransitionOnChange
       forcedTheme={forcedTheme}
     >
       <QueryClientProvider>
-        <I18nProvider initialLocale={locale}>
-          <ThemeProvider>
-            <ChatProvider>
-              <AuthSyncWatcher />
-              <DesensitizeWordsLoader />
-              <FontScaleApplier />
-              {children}
-            </ChatProvider>
-          </ThemeProvider>
-        </I18nProvider>
+        <AuthSyncWatcher disabled={positionStandaloneMode}>
+          <I18nProvider initialLocale={locale}>
+            <ThemeProvider>
+              <ChatProvider>
+                {!positionStandaloneMode && <DesensitizeWordsLoader />}
+                <FontScaleApplier />
+                {children}
+              </ChatProvider>
+            </ThemeProvider>
+          </I18nProvider>
+        </AuthSyncWatcher>
       </QueryClientProvider>
     </NextThemesProvider>
   );
@@ -114,17 +131,38 @@ function AppProviders({ children }: { children: React.ReactNode }) {
  */
 function RootRedirect() {
   const { search } = useLocation();
+  if (isPositionRoundtableStandaloneMode()) {
+    return <Navigate to={POSITION_ROUNDTABLE_ROUTE} replace />;
+  }
   return <Navigate to={`/login${search}`} replace />;
 }
 
 export function App() {
+  const positionStandaloneMode = isPositionRoundtableStandaloneMode();
+  const standaloneLoginRedirect = (
+    <Navigate to={POSITION_ROUNDTABLE_ROUTE} replace />
+  );
+  const pageElement = positionStandaloneMode ? (
+    <ChatRuntime>
+      <PositionRoundtablePage compactChrome />
+    </ChatRuntime>
+  ) : (
+    <PageRoutes />
+  );
+
   return (
     <HashRouter>
       <AppProviders>
         <Routes>
           <Route path="/" element={<RootRedirect />} />
-          <Route path="/login" element={<LoginPage />} />
-          <Route path="/login/:username" element={<LoginPage />} />
+          <Route
+            path="/login"
+            element={positionStandaloneMode ? standaloneLoginRedirect : <LoginPage />}
+          />
+          <Route
+            path="/login/:username"
+            element={positionStandaloneMode ? standaloneLoginRedirect : <LoginPage />}
+          />
           <Route path="/landing" element={<LandingPage />} />
           <Route path="/share/:shareCode" element={<PublicSharePage />} />
           <Route path="/public/leaderboard" element={<PublicLeaderboardPage />} />
@@ -157,11 +195,15 @@ export function App() {
             }
           />
           <Route path="/embed/roundtable" element={<EmbedRoundtablePage />} />
+          <Route
+            path="/embed/knowledge/:noteId"
+            element={<WeKnoraWikiPageView publicEmbed />}
+          />
           <Route
             path="/roundtable-dashboard"
             element={<DashboardStandalonePage />}
           />
-          <Route path="/page/*" element={<PageRoutes />} />
+          <Route path="/page/*" element={pageElement} />
           <Route path="*" element={<NotFoundPage />} />
         </Routes>
       </AppProviders>

frontend-web/src/assets/eightbf-roundtable/back-arrow.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="14" height="12" viewBox="0 0 14 12" fill="none" aria-hidden="true">
+  <path d="M13 6H1.5M1.5 6L6.2 1.4M1.5 6L6.2 10.6" stroke="#A2E1F9" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

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/down-logo.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 12 12">
+  <defs>
+    <style>
+      .hit { fill: rgba(255, 255, 255, 0.8); opacity: 0; }
+      .mark { fill: #fff; }
+    </style>
+  </defs>
+  <g transform="translate(-2434.135 -67.941)">
+    <rect class="hit" width="12" height="12" transform="translate(2434.135 67.941)"/>
+    <path class="mark" d="M.885,0,0,.885,3.692,4.577,4.135,5l.442-.423L8.269.885,7.385,0,4.135,3.25Z" transform="translate(2436 71.942)"/>
+  </g>
+</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/expand-logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">
+  <defs>
+    <style>
+      .background { fill: none; }
+      .mark { stroke: rgba(0, 0, 0, 0); stroke-miterlimit: 10; fill: url(#gradient); }
+    </style>
+    <linearGradient id="gradient" x1="0.277" y1="0.03" x2="0.725" y2="1.083" gradientUnits="objectBoundingBox">
+      <stop offset="0" stop-color="#a2e1f9"/>
+      <stop offset="1" stop-color="#45c3f3"/>
+    </linearGradient>
+  </defs>
+  <rect class="background" width="16" height="16"/>
+  <path class="mark" d="M14554.5,10202.5a1,1,0,1,1,0-2h5a1,1,0,0,1,0,2Zm9.8-.482-2.95-2.157a.445.445,0,0,1-.187-.361.46.46,0,0,1,.187-.366l2.95-2.152a.45.45,0,0,1,.716.365v4.307a.44.44,0,0,1-.131.317.445.445,0,0,1-.322.136A.454.454,0,0,1,14564.3,10202.019Zm-9.8-3.521a1,1,0,1,1,0-2h5a1,1,0,1,1,0,2Zm0-4a1,1,0,1,1,0-2h10a1,1,0,1,1,0,2Z" transform="translate(-14551.5 -10189.5)"/>
+</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/ai-elements/reasoning.tsx

@@ -165,7 +165,7 @@ export const ReasoningTrigger = memo(
 export type ReasoningContentProps = ComponentProps<
   typeof CollapsibleContent
 > & {
-  children: string;
+  children: ReactNode;
 };
 
 export const ReasoningContent = memo(
@@ -178,7 +178,11 @@ export const ReasoningContent = memo(
       )}
       {...props}
     >
-      <Streamdown {...reasoningPlugins}>{children}</Streamdown>
+      {typeof children === "string" ? (
+        <Streamdown {...reasoningPlugins}>{children}</Streamdown>
+      ) : (
+        children
+      )}
     </CollapsibleContent>
   ),
 );

frontend-web/src/components/analysis-results/AnalysisResultCardList.tsx

@@ -0,0 +1,104 @@
+import { FileOutput } from "lucide-react";
+import { toast } from "sonner";
+
+import responsibilityIcon from "@/assets/position-roundtable/责任岗位.svg";
+import resultTimeIcon from "@/assets/position-roundtable/时间.svg";
+import { desensitize } from "@/lib/desensitize";
+import { cn } from "@/lib/utils";
+
+import "./analysis-results.css";
+import type { AnalysisResultCardItem } from "./types";
+
+function formatResultTime(value: string | undefined, fallback: string): string {
+  if (!value) return fallback;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return new Intl.DateTimeFormat("zh-CN", {
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).format(date);
+}
+
+export function AnalysisResultCardList({
+  items,
+  emptyTitle = "暂无交付产物",
+  emptyDescription = "第二步研讨与第三步总结生成 Markdown 后，产物会显示在这里。",
+  padded = true,
+  onOpen,
+}: {
+  items: AnalysisResultCardItem[];
+  emptyTitle?: string;
+  emptyDescription?: string;
+  padded?: boolean;
+  onOpen: (item: AnalysisResultCardItem) => void;
+}) {
+  if (items.length === 0) {
+    return (
+      <div className="position-roundtable-analysis-results-empty flex h-full min-h-[260px] flex-col items-center justify-center p-6 text-center">
+        <FileOutput className="mb-3 size-8 text-muted-foreground/50" />
+        <p className="text-sm font-semibold">{emptyTitle}</p>
+        <p className="mt-1 max-w-[240px] text-xs leading-5 text-muted-foreground">
+          {emptyDescription}
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("analysis-result-card-list", padded && "p-[15px]")}>
+      {items.map((item, index) => {
+        const displayedTime = formatResultTime(
+          item.updatedAt,
+          item.fallbackTime || "刚刚",
+        );
+        const displayedProductName = item.delivered ? item.productName : "未交付";
+        return (
+          <button
+            key={item.id}
+            type="button"
+            className="position-roundtable-analysis-result-card"
+            onClick={() => {
+              if (!item.delivered) {
+                toast.info(
+                  item.unavailableMessage ||
+                    `「${desensitize(item.agentName)}」尚未交付可预览的 Markdown 文件。`,
+                );
+                return;
+              }
+              onOpen(item);
+            }}
+          >
+            <div className="position-roundtable-analysis-result-card-body">
+              <div
+                className={cn(
+                  "position-roundtable-analysis-result-tag",
+                  `position-roundtable-analysis-result-tag--${(index % 6) + 1}`,
+                )}
+                aria-label={desensitize(item.agentName)}
+              >
+                <span>{desensitize(item.agentName)}</span>
+              </div>
+              <p className="position-roundtable-analysis-result-product">
+                {desensitize(displayedProductName)}
+              </p>
+              <footer className="position-roundtable-analysis-result-meta">
+                <span>
+                  <img src={responsibilityIcon} alt="" aria-hidden="true" />
+                  {desensitize(item.positionName)}
+                </span>
+                <i aria-hidden="true" />
+                <span>
+                  <img src={resultTimeIcon} alt="" aria-hidden="true" />
+                  {displayedTime}
+                </span>
+              </footer>
+            </div>
+          </button>
+        );
+      })}
+    </div>
+  );
+}

frontend-web/src/components/analysis-results/AnalysisResultDetailDialog.tsx

@@ -0,0 +1,141 @@
+import { useQuery } from "@tanstack/react-query";
+import { FileOutput, Loader2 } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { ArtifactFilePreview } from "@/components/workspace/artifacts";
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { loadArtifactContent } from "@/core/artifacts/loader";
+import { desensitize } from "@/lib/desensitize";
+import { Button as TButton } from "tdesign-react";
+
+import type { AnalysisResultCardItem } from "./types";
+
+function isArtifactErrorContent(content: string | null | undefined): boolean {
+  const trimmed = content?.trim();
+  if (!trimmed || !trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+    const detail = parsed.detail ?? parsed.message ?? parsed.error;
+    return typeof detail === "string" && detail.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function fallbackContent(item: AnalysisResultCardItem | null): string {
+  return (
+    item?.artifactContent?.trim() ||
+    item?.summary?.trim() ||
+    "暂无产物正文"
+  );
+}
+
+export function AnalysisResultDetailDialog({
+  item,
+  onOpenChange,
+  extraBody,
+  footerStart,
+}: {
+  item: AnalysisResultCardItem | null;
+  onOpenChange: (open: boolean) => void;
+  extraBody?: ReactNode;
+  footerStart?: ReactNode;
+}) {
+  const artifactThreadId = item?.artifactThreadId || null;
+  const artifactPathValue = item?.artifactPath || "";
+  const artifactContentQuery = useQuery({
+    queryKey: [
+      "analysis-results",
+      "deliverable-artifact-content",
+      artifactThreadId,
+      artifactPathValue,
+    ],
+    queryFn: async () => {
+      if (!artifactThreadId || !artifactPathValue) return "";
+      const result = await loadArtifactContent({
+        filepath: artifactPathValue,
+        threadId: artifactThreadId,
+        isMock: false,
+      });
+      return result.content;
+    },
+    enabled: Boolean(item && artifactThreadId && artifactPathValue),
+    staleTime: 30_000,
+  });
+  const loadedArtifactContent =
+    typeof artifactContentQuery.data === "string" ? artifactContentQuery.data : "";
+  const loadedArtifactIsError = isArtifactErrorContent(loadedArtifactContent);
+  const artifactContent =
+    loadedArtifactContent.trim() && !loadedArtifactIsError ? loadedArtifactContent : null;
+  const displayedContent = artifactContent || fallbackContent(item);
+  const artifactLoadFailed =
+    (artifactContentQuery.isError || loadedArtifactIsError) &&
+    !item?.artifactContent?.trim();
+
+  return (
+    <Dialog open={Boolean(item)} onOpenChange={onOpenChange}>
+      <DialogContent
+        overlayClassName="!z-[6000]"
+        className="!z-[6001] flex max-h-[86vh] w-[900px] !max-w-[calc(100vw-2rem)] flex-col gap-0 overflow-hidden p-0"
+      >
+        <DialogHeader className="shrink-0 border-b px-5 py-4 dark:border-[#2b8ffe]/25">
+          <DialogTitle className="flex items-center gap-2 text-base">
+            <FileOutput className="size-4 text-primary" />
+            交付产物详情
+          </DialogTitle>
+        </DialogHeader>
+        {!item ? null : (
+          <div className="custom-scrollbar min-h-0 flex-1 overflow-y-auto px-5 py-4">
+            <div className="min-w-0">
+              <p className="text-sm font-extrabold text-slate-900 dark:text-[#e8edf5]">
+                {desensitize(item.productName)}
+              </p>
+              <p className="mt-1 truncate text-xs text-muted-foreground">
+                {desensitize(item.agentName)} · {desensitize(item.positionName)}
+              </p>
+            </div>
+            {extraBody}
+            <div className="mt-4 rounded-xl border border-slate-200 bg-white p-3 dark:border-[#2b8ffe]/30 dark:bg-[#042b59]/65">
+              <div className="mb-2 flex items-center justify-between gap-2">
+                <p className="text-xs font-bold text-slate-700 dark:text-[#e8edf5]">产物内容</p>
+              </div>
+              <div className="h-[52vh] min-h-[320px] overflow-hidden rounded-lg border border-slate-100 bg-slate-50/60 dark:border-[#2b8ffe]/20 dark:bg-[#021d3d]/70">
+                {artifactContentQuery.isLoading ? (
+                  <div className="flex h-full items-center justify-center gap-2 text-sm text-muted-foreground dark:text-[#8aa0c4]">
+                    <Loader2 className="size-4 animate-spin" />
+                    正在加载 Markdown 文件内容…
+                  </div>
+                ) : (
+                  <ArtifactFilePreview
+                    content={displayedContent}
+                    language="markdown"
+                    threadId={artifactThreadId ?? ""}
+                  />
+                )}
+              </div>
+              {artifactLoadFailed && (
+                <p className="mt-2 text-[11px] text-amber-600 dark:text-amber-300">
+                  Markdown 文件内容加载失败，当前展示的是已保存正文。
+                </p>
+              )}
+            </div>
+          </div>
+        )}
+        <DialogFooter className="shrink-0 border-t px-5 py-3 dark:border-[#2b8ffe]/25">
+          {footerStart}
+          <TButton variant="outline" onClick={() => onOpenChange(false)}>
+            关闭
+          </TButton>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend-web/src/components/analysis-results/analysis-results.css

@@ -0,0 +1,130 @@
+.analysis-result-card-list {
+  display: grid;
+  gap: 10px;
+  min-width: 0;
+  max-width: 100%;
+}
+
+.position-roundtable-analysis-result-card {
+  position: relative;
+  display: block;
+  width: 100%;
+  max-width: 100%;
+  min-width: 0;
+  min-height: 102px;
+  box-sizing: border-box;
+  padding: 40px 12px 12px;
+  border: 1px solid rgba(85, 166, 254, 0.1);
+  border-radius: 4px;
+  background: rgba(0, 98, 217, 0.1);
+  color: #ffffff;
+  text-align: left;
+  cursor: pointer;
+  transition: background 160ms ease, border-color 160ms ease, box-shadow 160ms ease;
+}
+
+.position-roundtable-analysis-result-card:hover,
+.position-roundtable-analysis-result-card:focus-visible {
+  border-color: #0062d9;
+  background: rgba(0, 98, 217, 0.3);
+  box-shadow: 0 4px 14px rgba(0, 44, 110, 0.18);
+  outline: none;
+}
+
+.position-roundtable-analysis-result-card-body {
+  position: relative;
+  min-width: 0;
+  max-width: 100%;
+}
+
+.position-roundtable-analysis-result-tag {
+  position: absolute;
+  top: -40px;
+  left: -12px;
+  display: inline-flex;
+  width: fit-content;
+  max-width: calc(100% + 12px);
+  height: 26px;
+  align-items: center;
+  box-sizing: border-box;
+  padding: 0 22px 0 12px;
+  overflow: hidden;
+  border-radius: 4px 0 0 0;
+  background: rgba(212, 120, 0, 0.5);
+  color: #ffffff;
+  font-family: "Noto Sans S Chinese", "Noto Sans SC", sans-serif;
+  font-size: 16px;
+  line-height: normal;
+  white-space: nowrap;
+  clip-path: polygon(0 0, 100% 0, calc(100% - 14px) 100%, 0 100%);
+}
+
+.position-roundtable-analysis-result-tag--1 { background: rgba(212, 120, 0, 0.5); }
+.position-roundtable-analysis-result-tag--2 { background: rgba(207, 19, 34, 0.5); }
+.position-roundtable-analysis-result-tag--3 { background: rgba(29, 171, 123, 0.5); }
+.position-roundtable-analysis-result-tag--4 { background: rgba(132, 85, 230, 0.5); }
+.position-roundtable-analysis-result-tag--5 { background: rgba(201, 181, 0, 0.5); }
+.position-roundtable-analysis-result-tag--6 { background: rgba(69, 195, 243, 0.5); }
+
+.position-roundtable-analysis-result-tag span {
+  position: relative;
+  z-index: 1;
+  box-sizing: border-box;
+  min-width: 0;
+  max-width: 100%;
+  overflow: hidden;
+  padding: 0;
+  text-overflow: ellipsis;
+}
+
+.position-roundtable-analysis-result-product {
+  margin: 0;
+  overflow: hidden;
+  color: #ffffff;
+  font-family: "Noto Sans S Chinese", "Noto Sans SC", sans-serif;
+  font-size: 18px;
+  font-weight: 500;
+  line-height: 24px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.position-roundtable-analysis-result-meta {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 10px;
+  margin-top: 6px;
+  color: #80b7ff;
+  font-family: "Noto Sans S Chinese", "Noto Sans SC", sans-serif;
+  font-size: 16px;
+  font-weight: 300;
+  line-height: 24px;
+}
+
+.position-roundtable-analysis-result-meta span {
+  display: inline-flex;
+  min-width: 0;
+  align-items: center;
+  gap: 5px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.position-roundtable-analysis-result-meta img {
+  width: 16px;
+  height: 16px;
+  flex: 0 0 auto;
+}
+
+.position-roundtable-analysis-result-meta i {
+  width: 1px;
+  height: 14px;
+  flex: 0 0 auto;
+  background: rgba(128, 183, 255, 0.45);
+}
+
+.position-roundtable-analysis-results-empty {
+  color: #80b7ff;
+}

frontend-web/src/components/analysis-results/index.ts

@@ -0,0 +1,3 @@
+export { AnalysisResultCardList } from "./AnalysisResultCardList";
+export { AnalysisResultDetailDialog } from "./AnalysisResultDetailDialog";
+export type { AnalysisResultCardItem } from "./types";

frontend-web/src/components/analysis-results/types.ts

@@ -0,0 +1,17 @@
+export interface AnalysisResultCardItem {
+  id: string;
+  agentName: string;
+  productName: string;
+  positionName: string;
+  updatedAt?: string;
+  /** Shown when `updatedAt` is missing. */
+  fallbackTime?: string;
+  /** Clickable preview is available. */
+  delivered: boolean;
+  artifactPath?: string;
+  artifactMimeType?: string | null;
+  artifactThreadId?: string | null;
+  artifactContent?: string | null;
+  summary?: string;
+  unavailableMessage?: string;
+}

frontend-web/src/components/html-preview-frame.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 
-import { injectInPageAnchorHandler } from "@/core/utils/markdown";
+import { prepareGeneratedHtml } from "@/core/utils/legacy-html-preview";
 
 /**
  * Sandboxed preview of a generated HTML document.
@@ -26,7 +26,7 @@ export function HtmlPreviewFrame({
   const [url, setUrl] = useState<string>();
 
   useEffect(() => {
-    const blob = new Blob([injectInPageAnchorHandler(html ?? "")], {
+    const blob = new Blob([prepareGeneratedHtml(html ?? "")], {
       type: "text/html;charset=utf-8",
     });
     const objectUrl = URL.createObjectURL(blob);

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

@@ -8,6 +8,17 @@
     flex-shrink: 0;
 }
 
+/* `?hideHeader=1`: keep the menu rail, but let it occupy the Header's space. */
+.sidebar-contnet--header-hidden {
+    top: 0;
+    height: 100vh;
+}
+
+.sidebar-contnet--header-hidden .item-nav-content {
+    height: calc(100vh - 20px);
+    min-height: calc(100vh - 20px);
+}
+
 .sidebar-contents {
     width: 98px;
     min-height: calc(100% - 20px);
@@ -564,7 +575,59 @@
     background: #ffffff;
 }
 
+/* Ice blue has a deliberately light banner. Keep top-level navigation and
+   its active marker dark enough to remain readable against #9BCEF1. */
+html.iceblue .light-topnav-item {
+    color: rgba(24, 50, 74, 0.78);
+}
+
+html.iceblue .light-topnav-item:hover,
+html.iceblue .light-topnav-item--active,
+html.iceblue .light-topnav-item--active:hover {
+    color: #18324a;
+}
+
+html.iceblue .light-topnav-item--active::after {
+    background: #3d6e96;
+}
+
+/* Pale yellow has the same light-banner contrast requirement as ice blue. */
+html.lightyellow .light-topnav-item {
+    color: rgba(48, 61, 35, 0.78);
+}
+
+html.lightyellow .light-topnav-item:hover,
+html.lightyellow .light-topnav-item--active,
+html.lightyellow .light-topnav-item--active:hover {
+    color: #303d23;
+}
+
+html.lightyellow .light-topnav-item--active::after {
+    background: #4c6330;
+}
+
 /* ── 侧边栏：二级图标卡片列（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;
@@ -587,6 +650,12 @@
     width: 236px;
 }
 
+/* `?hideHeader=1`: preserve the light sidebar while removing only Header. */
+.light-sidebar--header-hidden {
+    top: 0;
+    height: 100vh;
+}
+
 /* 二级列：固定 96px，竖排图标卡片 + 底部设置 */
 .light-sidebar__primary {
     flex: 0 0 96px;

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

@@ -17,9 +17,15 @@ type PageSidebarDarkProps = {
   /** 是否收起（true 时只渲染左下角浮动入口，sidebar 主体隐藏） */
   collapsed: boolean;
   onToggleCollapsed: () => void;
+  /** 全局 Header 隐藏时，侧边栏从视口顶部开始占满高度。 */
+  headerHidden?: boolean;
 };
 
-export function PageSidebarDark({ collapsed, onToggleCollapsed }: PageSidebarDarkProps) {
+export function PageSidebarDark({
+  collapsed,
+  onToggleCollapsed,
+  headerHidden = false,
+}: PageSidebarDarkProps) {
   const isAdmin = getStoredAuth()?.system_role === "admin";
   const visibleMenuItems = useSidebarMenuItems(!!isAdmin);
   const inWujieEnv = isWujieEnv();
@@ -196,7 +202,7 @@ export function PageSidebarDark({ collapsed, onToggleCollapsed }: PageSidebarDar
     </div>
   );
 
-  // collapsed 状态：sidebar 主体完全消失（包括占据的宽度），只渲染左下角浮动入口
+  // 收起时主侧栏不占宽度，保留左下角入口以便随时恢复。
   if (collapsed) {
     return (
       <button
@@ -207,13 +213,17 @@ export function PageSidebarDark({ collapsed, onToggleCollapsed }: PageSidebarDar
         onClick={onToggleCollapsed}
       >
         <PanelLeftOpen className="sidebar-collapse-btn__icon" aria-hidden="true" />
-        <span className="sidebar-collapse-btn__label">收起面板</span>
+        <span className="sidebar-collapse-btn__label">展开面板</span>
       </button>
     );
   }
 
   return (
-    <aside className={`sidebar-contnet ${inWujieEnv ? "" : "sidebar-contnet--top-submenu"}`}>
+    <aside
+      className={`sidebar-contnet ${inWujieEnv ? "" : "sidebar-contnet--top-submenu"} ${
+        headerHidden ? "sidebar-contnet--header-hidden" : ""
+      }`}
+    >
       <div className="sidebar-contents">
         {sidebarMenuItemsToRender.map((item) => (
           <div
@@ -244,7 +254,6 @@ export function PageSidebarDark({ collapsed, onToggleCollapsed }: PageSidebarDar
           </div>
         ))}
 
-        {/* 底部"收起面板"按钮：独立样式，mt-auto 推到底 */}
         <button
           type="button"
           title="收起侧边栏"

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,
@@ -9,7 +10,9 @@ import {
   FolderOpen,
   Gauge,
   ListTree,
+  MessageSquareText,
   MousePointerClick,
+  BriefcaseBusiness,
   Settings,
   ShieldAlert,
   ShieldCheck,
@@ -49,6 +52,8 @@ import "@/components/page-sdebar.css";
 type PageSidebarProps = {
   collapsed: boolean;
   onToggleCollapsed: () => void;
+  /** Global Header is hidden but this sidebar remains available. */
+  headerHidden?: boolean;
 };
 
 type SettingsSection = "account" | "appearance" | "memory" | "tools" | "about";
@@ -79,23 +84,28 @@ const findFirstRoutePath = (items?: MenuItem[]): string | null => {
  * - wujie 嵌入环境：顶栏被宿主隐藏，一级导航无处安放，故回落到原手风琴整树菜单
  *   （保证嵌入模式下所有层级仍可达，零回归）。
  */
-export function PageSidebar({ collapsed, onToggleCollapsed }: PageSidebarProps) {
+export function PageSidebar({
+  collapsed,
+  onToggleCollapsed,
+  headerHidden = false,
+}: PageSidebarProps) {
   if (isWujieEnv()) {
     return (
       <LegacyAccordionSidebar
         collapsed={collapsed}
         onToggleCollapsed={onToggleCollapsed}
+        headerHidden={headerHidden}
       />
     );
   }
-  return <SecondaryNavSidebar />;
+  return <SecondaryNavSidebar headerHidden={headerHidden} />;
 }
 
 /**
  * 浅色二级导航侧边栏（图标卡片，红/蓝主题色经 --brand-* 变量自动切换）。
  * 浅色模式不支持侧边栏收起，故无收起按钮、不接收 collapsed 相关 props。
  */
-function SecondaryNavSidebar() {
+function SecondaryNavSidebar({ headerHidden }: { headerHidden: boolean }) {
   const isAdmin = getStoredAuth()?.system_role === "admin";
   const visibleMenuItems = useSidebarMenuItems(!!isAdmin);
   const { t } = useI18n();
@@ -150,7 +160,11 @@ function SecondaryNavSidebar() {
         open={notificationOpen}
         onOpenChange={setNotificationOpen}
       />
-      <aside className={`light-sidebar ${expanded ? "light-sidebar--expanded" : ""}`}>
+      <aside
+        className={`light-sidebar ${expanded ? "light-sidebar--expanded" : ""} ${
+          headerHidden ? "light-sidebar--header-hidden" : ""
+        }`}
+      >
         {/* 一级列：二级图标卡片 + 底部设置 */}
         <div className="light-sidebar__primary">
           <nav className="light-sidebar__list" aria-label="二级菜单">
@@ -224,6 +238,22 @@ function SecondaryNavSidebar() {
                       按钮管理
                     </DropdownMenuItem>
                   )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/strategy/admin/fixed-questions")}
+                    >
+                      <MessageSquareText className="size-4" />
+                      问题配置
+                    </DropdownMenuItem>
+                  )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/strategy/admin/position-roles")}
+                    >
+                      <BriefcaseBusiness className="size-4" />
+                      岗位角色配置
+                    </DropdownMenuItem>
+                  )}
                   {isAdmin && (
                     <DropdownMenuItem
                       onClick={() => navigate("/page/strategy/admin/login-whitelist")}
@@ -232,6 +262,14 @@ function SecondaryNavSidebar() {
                       白名单管理
                     </DropdownMenuItem>
                   )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/workspace/admin/models")}
+                    >
+                      <Cpu className="size-4" />
+                      模型配置
+                    </DropdownMenuItem>
+                  )}
                   {isAdmin && (
                     <DropdownMenuItem
                       onClick={() => navigate("/page/strategy/settings/model-concurrency")}
@@ -287,6 +325,7 @@ function SecondaryNavSidebar() {
 function LegacyAccordionSidebar({
   collapsed,
   onToggleCollapsed,
+  headerHidden,
 }: PageSidebarProps) {
   const { theme } = useTheme();
   const isDark = theme === "dark";
@@ -438,7 +477,9 @@ function LegacyAccordionSidebar({
         onOpenChange={setNotificationOpen}
       />
       <aside
-        className={`fixed left-0 top-16 z-40 flex h-[calc(100vh-4rem)] flex-col overflow-hidden shadow-sm theme-transition transition-all duration-300 ${
+        className={`fixed left-0 z-40 flex flex-col overflow-hidden shadow-sm theme-transition transition-all duration-300 ${
+          headerHidden ? "top-0 h-screen" : "top-16 h-[calc(100vh-4rem)]"
+        } ${
           isDark
             ? "border-r border-blue-800/30 bg-slate-900"
             : "border-r border-red-100 bg-white"
@@ -526,6 +567,24 @@ function LegacyAccordionSidebar({
                   按钮管理
                 </DropdownMenuItem>
               )}
+              {isAdmin && (
+                <DropdownMenuItem onClick={() => navigate("/page/strategy/admin/fixed-questions")}>
+                  <MessageSquareText className="size-4" />
+                  问题配置
+                </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/ui/button.tsx

@@ -10,7 +10,7 @@ const buttonVariants = cva(
     variants: {
       variant: {
         default:
-          "cursor-pointer bg-primary text-primary-foreground hover:bg-primary/90",
+            "cursor-pointer bg-primary text-[var(--button-foreground,var(--primary-foreground))] hover:bg-primary/90",
         destructive:
           "cursor-pointer bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
         outline:

frontend-web/src/components/ui/dialog.tsx

@@ -71,15 +71,17 @@ const DialogOverlay = React.forwardRef<
 
 DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
 
-const DialogContent = React.forwardRef<
-  React.ElementRef<typeof DialogPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & {
-    showCloseButton?: boolean;
-  }
->(({ className, children, showCloseButton = true, ...props }, ref) => {
-  return (
-    <DialogPortal data-slot="dialog-portal">
-      <DialogOverlay />
+const DialogContent = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & {
+    showCloseButton?: boolean;
+    /** Use when this dialog is opened from a higher-layer surface such as a Drawer. */
+    overlayClassName?: string;
+  }
+>(({ className, children, showCloseButton = true, overlayClassName, ...props }, ref) => {
+  return (
+    <DialogPortal data-slot="dialog-portal">
+      <DialogOverlay className={overlayClassName} />
       <DialogPrimitive.Content
         ref={ref}
         data-slot="dialog-content"

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

@@ -59,18 +59,21 @@ function useSidebarSafe() {
   return React.useContext(SidebarContext);
 }
 
-function SidebarProvider({
-  defaultOpen = true,
-  open: openProp,
-  onOpenChange: setOpenProp,
-  className,
+function SidebarProvider({
+  defaultOpen = true,
+  open: openProp,
+  onOpenChange: setOpenProp,
+  disableToggle = false,
+  className,
   style,
   children,
   ...props
-}: React.ComponentProps<"div"> & {
-  defaultOpen?: boolean;
-  open?: boolean;
-  onOpenChange?: (open: boolean) => void;
+}: React.ComponentProps<"div"> & {
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Keep a controlled deployment-level rail from being reopened by hotkeys. */
+  disableToggle?: boolean;
 }) {
   const isMobile = useIsMobile();
   const [openMobile, setOpenMobile] = React.useState(false);
@@ -94,10 +97,11 @@ function SidebarProvider({
     [setOpenProp, open],
   );
 
-  // Helper to toggle the sidebar.
-  const toggleSidebar = React.useCallback(() => {
-    return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open);
-  }, [isMobile, setOpen, setOpenMobile]);
+  // Helper to toggle the sidebar.
+  const toggleSidebar = React.useCallback(() => {
+    if (disableToggle) return;
+    return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open);
+  }, [disableToggle, isMobile, setOpen, setOpenMobile]);
 
   // Adds a keyboard shortcut to toggle the sidebar.
   React.useEffect(() => {

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

@@ -0,0 +1,71 @@
+"use client";
+
+import { markdown, markdownLanguage } from "@codemirror/lang-markdown";
+import { languages } from "@codemirror/language-data";
+import { basicLightInit } from "@uiw/codemirror-theme-basic";
+import { monokaiInit } from "@uiw/codemirror-theme-monokai";
+import CodeMirror from "@uiw/react-codemirror";
+import { useTheme } from "next-themes";
+import { useMemo } from "react";
+
+import { cn } from "@/lib/utils";
+import { MarkdownContent } from "@/components/workspace/messages/markdown-content";
+import { reasoningPlugins } from "@/core/streamdown";
+
+const lightTheme = basicLightInit({ settings: { background: "transparent", fontSize: "14px" } });
+const darkTheme = monokaiInit({
+  settings: { background: "transparent", gutterBackground: "transparent", fontSize: "14px" },
+});
+
+/** Markdown-aware source editor shared by Wiki create/edit dialogs. */
+export function MarkdownCodeEditor({
+  value,
+  onChange,
+  className,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  className?: string;
+}) {
+  const { resolvedTheme } = useTheme();
+  const extensions = useMemo(
+    () => [markdown({ base: markdownLanguage, codeLanguages: languages })],
+    [],
+  );
+
+  return (
+    <div className={cn("grid min-h-[46vh] overflow-hidden rounded-lg border bg-background lg:grid-cols-2", className)}>
+      <section className="flex min-h-0 flex-col border-b lg:border-r lg:border-b-0">
+        <div className="flex h-9 shrink-0 items-center border-b bg-muted/40 px-3 text-xs font-medium text-muted-foreground">
+          Markdown 编辑
+        </div>
+        <CodeMirror
+          value={value}
+          onChange={onChange}
+          theme={resolvedTheme === "dark" ? darkTheme : lightTheme}
+          extensions={extensions}
+          basicSetup={{
+            foldGutter: true,
+            highlightActiveLine: true,
+            highlightActiveLineGutter: false,
+            lineNumbers: true,
+          }}
+          className="min-h-[42vh] flex-1 overflow-auto font-mono text-sm [&_.cm-editor]:min-h-[42vh] [&_.cm-focused]:outline-none!"
+        />
+      </section>
+      <section className="flex min-h-0 flex-col bg-muted/10">
+        <div className="flex h-9 shrink-0 items-center border-b bg-muted/40 px-3 text-xs font-medium text-muted-foreground">
+          实时渲染
+        </div>
+        <div className="min-h-[42vh] flex-1 overflow-auto p-4">
+          <MarkdownContent
+            content={value || "*暂无正文*"}
+            isLoading={false}
+            remarkPlugins={reasoningPlugins.remarkPlugins}
+            rehypePlugins={reasoningPlugins.rehypePlugins}
+          />
+        </div>
+      </section>
+    </div>
+  );
+}

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

@@ -0,0 +1,189 @@
+"use client";
+
+import { BookOpen, ListTree } from "lucide-react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { MarkdownContent } from "@/components/workspace/messages/markdown-content";
+import { Badge } from "@/components/ui/badge";
+import { reasoningPlugins } from "@/core/streamdown";
+import { createMarkdownAnchorResolver } from "@/core/utils/markdown";
+import { cn } from "@/lib/utils";
+
+import "./wiki.css";
+
+function stripMarkdownToText(markdown: string): string {
+  return markdown
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/~~~[\s\S]*?~~~/g, " ")
+    .replace(/!\[[^\]]*\]\([^)]+\)/g, " ")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/^#{1,6}\s+/gm, "")
+    .replace(/^[>\-*+\d.)\s]+/gm, "")
+    .replace(/[`*_~|]/g, "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function getMarkdownExcerpt(markdown: string): string {
+  const text = stripMarkdownToText(markdown);
+  if (!text) return "";
+  return text.length > 150 ? `${text.slice(0, 150)}...` : text;
+}
+
+function countReadableWords(markdown: string): number {
+  const text = stripMarkdownToText(markdown);
+  if (!text) return 0;
+  const cjk = text.match(/[\u4e00-\u9fff]/g)?.length ?? 0;
+  const words = text.replace(/[\u4e00-\u9fff]/g, " ").match(/[A-Za-z0-9]+/g)?.length ?? 0;
+  return cjk + words;
+}
+
+function selectorForId(id: string): string {
+  const css = window.CSS;
+  if (css?.escape) return `#${css.escape(id)}`;
+  return `[id="${id.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]`;
+}
+
+export function ReportMarkdownView({
+  content,
+  title,
+  subtitle,
+  badgeLabel = "报告阅读",
+  className,
+  compactHeader = false,
+}: {
+  content: string;
+  title?: string;
+  subtitle?: string;
+  badgeLabel?: string;
+  className?: string;
+  compactHeader?: boolean;
+}) {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const anchorResolver = useMemo(() => createMarkdownAnchorResolver(content), [content]);
+  const headings = useMemo(
+    () => anchorResolver.headings.filter((item) => item.level >= 1 && item.level <= 3),
+    [anchorResolver],
+  );
+  const [activeHeadingId, setActiveHeadingId] = useState<string | null>(null);
+  const excerpt = useMemo(() => getMarkdownExcerpt(content), [content]);
+  const sectionCount = headings.length;
+  const wordCount = useMemo(() => countReadableWords(content), [content]);
+
+  useEffect(() => {
+    setActiveHeadingId(headings[0]?.id ?? null);
+  }, [headings]);
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root || headings.length === 0) return;
+
+    const targets = headings
+      .map((item) => root.querySelector<HTMLElement>(selectorForId(item.id)))
+      .filter((item): item is HTMLElement => !!item);
+    if (targets.length === 0) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const visible = entries
+          .filter((entry) => entry.isIntersecting)
+          .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top)[0];
+        if (visible?.target.id) setActiveHeadingId(visible.target.id);
+      },
+      {
+        root: root.closest("[data-radix-scroll-area-viewport]") ?? null,
+        rootMargin: "-96px 0px -65% 0px",
+        threshold: [0, 1],
+      },
+    );
+
+    targets.forEach((target) => observer.observe(target));
+    return () => observer.disconnect();
+  }, [headings, content]);
+
+  const scrollToHeading = useCallback((id: string) => {
+    const root = rootRef.current;
+    const target =
+      root?.querySelector<HTMLElement>(selectorForId(id)) ?? document.getElementById(id);
+    setActiveHeadingId(id);
+    target?.scrollIntoView({ behavior: "smooth", block: "start" });
+  }, []);
+
+  return (
+    <div
+      ref={rootRef}
+      className={cn("report-markdown-shell grid min-h-0 gap-5 lg:grid-cols-[minmax(0,1fr)_300px]", className)}
+    >
+      <article className="report-markdown-paper min-w-0 overflow-hidden">
+        <header className={cn("report-markdown-header", compactHeader && "report-markdown-header-compact")}>
+          <div className="flex flex-wrap items-center gap-2">
+            <Badge variant="secondary" className="report-markdown-badge">
+              <BookOpen className="size-3.5" />
+              {badgeLabel}
+            </Badge>
+            {subtitle && (
+              <span className="max-w-full truncate text-xs text-slate-500 dark:text-slate-400">
+                {subtitle}
+              </span>
+            )}
+          </div>
+          {title && <h1 className="report-markdown-title">{title}</h1>}
+          {!compactHeader && excerpt && <p className="report-markdown-excerpt">{excerpt}</p>}
+          <div className="report-markdown-metrics">
+            <span>{sectionCount || 1} 个章节</span>
+            <span>约 {wordCount} 字</span>
+          </div>
+        </header>
+
+        <div className="wiki-markdown report-markdown-body">
+          <MarkdownContent
+            className="max-w-none"
+            content={content}
+            isLoading={false}
+            remarkPlugins={reasoningPlugins.remarkPlugins}
+            rehypePlugins={reasoningPlugins.rehypePlugins}
+          />
+        </div>
+      </article>
+
+      <aside className="hidden min-w-0 lg:block">
+        <div className="report-markdown-toc">
+          <div className="mb-3 flex items-center justify-between gap-2">
+            <div className="flex items-center gap-2 text-sm font-semibold text-slate-900 dark:text-slate-100">
+              <ListTree className="size-4" />
+              内容目录
+            </div>
+            <span className="rounded-md bg-slate-100 px-1.5 py-0.5 text-xs text-slate-500 dark:bg-slate-800 dark:text-slate-400">
+              {sectionCount || 0}
+            </span>
+          </div>
+          {headings.length > 0 ? (
+            <nav className="report-markdown-toc-list">
+              {headings.map((item) => (
+                <button
+                  key={item.id}
+                  type="button"
+                  className={cn(
+                    "report-markdown-toc-item",
+                    activeHeadingId === item.id && "report-markdown-toc-item-active",
+                    item.level === 2 && "report-markdown-toc-level-2",
+                    item.level === 3 && "report-markdown-toc-level-3",
+                  )}
+                  title={item.text}
+                  onClick={() => scrollToHeading(item.id)}
+                >
+                  {item.text}
+                </button>
+              ))}
+            </nav>
+          ) : (
+            <div className="rounded-md border border-dashed p-3 text-xs text-slate-500 dark:border-slate-800 dark:text-slate-400">
+              暂无标题目录
+            </div>
+          )}
+        </div>
+      </aside>
+    </div>
+  );
+}

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">
@@ -74,11 +77,12 @@ export function WikiHeader({
           <Menu className="size-5" />
         </button>
         <div className="text-base font-semibold tracking-tight text-slate-900 dark:text-slate-100">
-          问答梳理
+          知识库管理
         </div>
       </div>
 
       <div className="flex items-center gap-2">
+        {extraActions}
         <HeaderButton
           icon={<Upload className="size-4" />}
           label="导入文件"

frontend-web/src/components/wiki/wiki.css

@@ -111,6 +111,340 @@
   border-color: #eef1f5;
 }
 
+.public-report-markdown {
+  color: #334155;
+  font-feature-settings: "kern";
+  text-rendering: optimizeLegibility;
+}
+
+.public-report-markdown h1 {
+  font-size: 30px;
+  letter-spacing: 0;
+  margin-bottom: 24px;
+}
+
+.public-report-markdown h2 {
+  font-size: 22px;
+  margin-top: 42px;
+  margin-bottom: 16px;
+  padding-bottom: 10px;
+}
+
+.public-report-markdown h3 {
+  font-size: 18px;
+  margin-top: 30px;
+  margin-bottom: 12px;
+}
+
+.public-report-markdown p,
+.public-report-markdown li {
+  font-size: 16px;
+  line-height: 1.9;
+}
+
+.public-report-markdown p {
+  margin-bottom: 16px;
+}
+
+.public-report-markdown ul,
+.public-report-markdown ol {
+  margin: 14px 0 18px;
+  padding-left: 26px;
+}
+
+.public-report-markdown ul {
+  list-style-type: disc;
+}
+
+.public-report-markdown ol {
+  list-style-type: decimal;
+}
+
+.public-report-markdown li {
+  padding-left: 2px;
+}
+
+.public-report-markdown code {
+  border-radius: 6px;
+  background: #f1f5f9;
+  padding: 2px 6px;
+  color: #be123c;
+  font-size: 0.92em;
+}
+
+.public-report-markdown pre {
+  margin: 20px 0;
+  border-radius: 8px;
+  background: #0f172a;
+  padding: 16px;
+  overflow-x: auto;
+}
+
+.public-report-markdown pre code {
+  background: transparent;
+  padding: 0;
+  color: inherit;
+}
+
+.public-report-markdown table {
+  display: block;
+  overflow-x: auto;
+  border-radius: 8px;
+  border: 1px solid #e8ecf1;
+}
+
+.public-report-markdown th,
+.public-report-markdown td {
+  min-width: 120px;
+  vertical-align: top;
+}
+
+.public-report-markdown blockquote {
+  margin: 20px 0;
+}
+
+.dark .public-report-markdown {
+  color: #cbd5e1;
+}
+
+.dark .public-report-markdown code {
+  background: #1e293b;
+  color: #f9a8d4;
+}
+
+.dark .public-report-markdown pre {
+  background: #020617;
+}
+
+.dark .public-report-markdown table {
+  border-color: #334155;
+}
+
+.report-markdown-shell {
+  align-items: start;
+  padding: 2px;
+}
+
+.report-markdown-paper {
+  border: 1px solid rgba(203, 213, 225, 0.85);
+  border-radius: 8px;
+  background:
+    linear-gradient(180deg, rgba(248, 250, 252, 0.92), rgba(255, 255, 255, 0) 220px),
+    #ffffff;
+  box-shadow:
+    0 1px 2px rgba(15, 23, 42, 0.04),
+    0 18px 44px rgba(15, 23, 42, 0.07);
+}
+
+.report-markdown-header {
+  border-bottom: 1px solid #e8edf4;
+  padding: 26px 34px 22px;
+}
+
+.report-markdown-header-compact {
+  padding-bottom: 18px;
+}
+
+.report-markdown-badge {
+  gap: 6px;
+  border: 1px solid #dbe3ef;
+  background: #ffffff;
+  color: #475569;
+}
+
+.report-markdown-title {
+  margin: 14px 0 0;
+  color: #0f172a;
+  font-size: 26px;
+  font-weight: 700;
+  line-height: 1.35;
+  letter-spacing: 0;
+}
+
+.report-markdown-excerpt {
+  margin: 14px 0 0;
+  max-width: 840px;
+  color: #64748b;
+  font-size: 14px;
+  line-height: 1.8;
+}
+
+.report-markdown-metrics {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 16px;
+  color: #64748b;
+  font-size: 12px;
+}
+
+.report-markdown-metrics span {
+  border: 1px solid #e2e8f0;
+  border-radius: 6px;
+  background: rgba(255, 255, 255, 0.78);
+  padding: 4px 8px;
+}
+
+.report-markdown-body {
+  max-width: 920px;
+  margin: 0 auto;
+  padding: 32px 42px 44px;
+}
+
+.report-markdown-body h1 {
+  font-size: 28px;
+}
+
+.report-markdown-body h2 {
+  position: relative;
+  margin-top: 44px;
+  border-bottom-color: #e5edf7;
+  font-size: 22px;
+}
+
+.report-markdown-body h2::before {
+  content: "";
+  position: absolute;
+  left: -16px;
+  top: 0.34em;
+  width: 4px;
+  height: 1.05em;
+  border-radius: 999px;
+  background: #2563eb;
+}
+
+.report-markdown-body h3 {
+  color: #1e293b;
+  font-size: 18px;
+}
+
+.report-markdown-body p,
+.report-markdown-body li {
+  font-size: 16px;
+  line-height: 1.92;
+}
+
+.report-markdown-body blockquote {
+  border-left-color: #2563eb;
+  background: #f8fbff;
+}
+
+.report-markdown-body table {
+  box-shadow: 0 1px 0 rgba(15, 23, 42, 0.04);
+}
+
+.report-markdown-toc {
+  position: sticky;
+  top: 16px;
+  max-height: calc(100vh - 32px);
+  overflow: hidden;
+  border: 1px solid rgba(203, 213, 225, 0.82);
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.92);
+  padding: 14px;
+  box-shadow: 0 12px 34px rgba(15, 23, 42, 0.06);
+  backdrop-filter: blur(10px);
+}
+
+.report-markdown-toc-list {
+  max-height: calc(100vh - 128px);
+  overflow: auto;
+  padding-right: 4px;
+}
+
+.report-markdown-toc-item {
+  display: block;
+  width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  border-left: 2px solid transparent;
+  border-radius: 6px;
+  padding: 7px 8px;
+  color: #64748b;
+  font-size: 12px;
+  line-height: 1.4;
+  text-align: left;
+  transition: background 160ms ease, border-color 160ms ease, color 160ms ease;
+}
+
+.report-markdown-toc-item:hover {
+  background: #f1f5f9;
+  color: #0f172a;
+}
+
+.report-markdown-toc-item-active {
+  border-left-color: #2563eb;
+  background: #eff6ff;
+  color: #1d4ed8;
+  font-weight: 600;
+}
+
+.report-markdown-toc-level-2 {
+  padding-left: 18px;
+}
+
+.report-markdown-toc-level-3 {
+  padding-left: 30px;
+  color: #94a3b8;
+}
+
+.dark .report-markdown-paper {
+  border-color: #1f2937;
+  background:
+    linear-gradient(180deg, rgba(15, 23, 42, 0.9), rgba(2, 6, 23, 0) 220px),
+    #020617;
+  box-shadow: 0 18px 44px rgba(0, 0, 0, 0.24);
+}
+
+.dark .report-markdown-header {
+  border-bottom-color: #1e293b;
+}
+
+.dark .report-markdown-badge,
+.dark .report-markdown-metrics span {
+  border-color: #334155;
+  background: #0f172a;
+  color: #cbd5e1;
+}
+
+.dark .report-markdown-title {
+  color: #f8fafc;
+}
+
+.dark .report-markdown-excerpt,
+.dark .report-markdown-metrics {
+  color: #94a3b8;
+}
+
+.dark .report-markdown-body h3 {
+  color: #e2e8f0;
+}
+
+.dark .report-markdown-body h2::before {
+  background: #60a5fa;
+}
+
+.dark .report-markdown-body blockquote {
+  background: #0f172a;
+  border-left-color: #60a5fa;
+}
+
+.dark .report-markdown-toc {
+  border-color: #1f2937;
+  background: rgba(2, 6, 23, 0.88);
+}
+
+.dark .report-markdown-toc-item:hover {
+  background: #0f172a;
+  color: #f8fafc;
+}
+
+.dark .report-markdown-toc-item-active {
+  background: rgba(37, 99, 235, 0.16);
+  color: #93c5fd;
+}
+
 /* Anchor target offset so headings clear the floating "目录" pill. */
 .wiki-markdown h1,
 .wiki-markdown h2,

frontend-web/src/components/wiki/wikiUtils.ts

@@ -204,7 +204,7 @@ export function noteFolderSegments(note: KnowledgeNote): string[] {
 
 /** Breadcrumb segments for a note (folders only; the title is appended by the caller). */
 export function noteBreadcrumbSegments(note: KnowledgeNote): string[] {
-  return ["问答梳理", ...noteFolderSegments(note).map(localizeFolderName)];
+  return ["知识库管理", ...noteFolderSegments(note).map(localizeFolderName)];
 }
 
 function sortTree(nodes: TreeNode[]): void {

frontend-web/src/components/workspace/agent-icon-color.ts

@@ -24,12 +24,60 @@ const AGENT_COLORS_DARK = [
   { from: "#69B1FF", to: "#003EB3" }, // 浅蓝 → 主色按下
 ] as const;
 
-/** 按 agent id 稳定散列出一对渐变色（from → to）。`isDark` 切换深蓝/浅色调色板。 */
-export function agentColor(id: string, isDark: boolean) {
+/** 按 agent id 稳定散列出一对渐变色，并根据当前主题返回可读的图标前景色。 */
+const AGENT_COLORS_ICEBLUE = [
+  { from: "#eff8fd", to: "#b7dcf5" },
+  { from: "#e3f2fb", to: "#9bcef1" },
+  { from: "#ebf6fb", to: "#add8e9" },
+  { from: "#edf2fc", to: "#b7cdef" },
+  { from: "#e9f7f5", to: "#afe0dc" },
+] as const;
+
+const AGENT_COLORS_LIGHTYELLOW = [
+  { from: "#fbfdef", to: "#e4efbf" },
+  { from: "#f7fae9", to: "#F3FBD9" },
+  { from: "#f9fbe8", to: "#dcebad" },
+  { from: "#faf8e9", to: "#e7dfb9" },
+  { from: "#f1f8e5", to: "#cce0af" },
+] as const;
+
+type AgentAvatarTheme =
+  | "dark"
+  | "iceblue"
+  | "lightyellow"
+  | "light"
+  | "lightblue"
+  | "lightgreen"
+  | `custom-theme-${string}`;
+
+/** Returns a stable avatar gradient and readable icon color for each theme. */
+export function agentColor(id: string, theme: AgentAvatarTheme) {
+  if (theme.startsWith("custom-theme-")) {
+    return {
+      from: "var(--accent)",
+      to: "var(--brand-200)",
+      foreground: "var(--accent-foreground)",
+    };
+  }
   let hash = 0;
   for (let i = 0; i < id.length; i++) {
     hash = (hash * 31 + id.charCodeAt(i)) >>> 0;
   }
-  const palette = isDark ? AGENT_COLORS_DARK : AGENT_COLORS_LIGHT;
-  return palette[hash % palette.length]!;
+  const palette =
+    theme === "dark"
+      ? AGENT_COLORS_DARK
+      : theme === "iceblue"
+        ? AGENT_COLORS_ICEBLUE
+        : theme === "lightyellow"
+          ? AGENT_COLORS_LIGHTYELLOW
+        : AGENT_COLORS_LIGHT;
+  return {
+    ...palette[hash % palette.length]!,
+    foreground:
+      theme === "iceblue"
+        ? "#2d587a"
+        : theme === "lightyellow"
+          ? "#4c6330"
+          : "#ffffff",
+  };
 }

frontend-web/src/components/workspace/agents/agent-brand-icon.tsx

@@ -1,5 +1,7 @@
 "use client";
 
+import agentAvatarDark from "@/assets/img/agent-avatar.png";
+import agentAvatarLight from "@/assets/img/agent-avatar-red.png";
 import { useTheme } from "@/contexts/ThemeContext";
 import { cn } from "@/lib/utils";
 
@@ -30,7 +32,7 @@ export function AgentBrandIcon({
   const styles = SIZE_STYLES[size];
   const { theme } = useTheme();
   const avatarSrc =
-    theme === "light" ? "/agent-avatar-red.png" : "/agent-avatar.png";
+    theme === "light" ? agentAvatarLight : agentAvatarDark;
 
   return (
     <span

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

@@ -947,6 +947,7 @@ export function AgentCard({ agent, layout = "card", onPublisherClick }: AgentCar
         "group flex min-h-[334px] min-w-0 flex-col gap-0 overflow-hidden rounded-2xl border-slate-200/90 bg-white py-0 shadow-[0_5px_18px_rgba(15,23,42,0.035)] transition-[background-color,border-color,box-shadow] duration-200 hover:!border-primary/30 hover:!bg-primary/5 hover:!ring-1 hover:!ring-primary/10 hover:shadow-[0_8px_24px_rgba(15,23,42,0.08)] dark:border-slate-800 dark:bg-slate-900",
         agent.featured_order != null && "border-primary/40 ring-1 ring-primary/15 dark:border-primary/45 dark:ring-primary/20",
       )}
+      data-agent-guide="agent-card"
     >
       <CardHeader className="min-w-0 gap-0 px-5 pt-5 pb-2">
         {agent.featured_order != null ? (
@@ -1008,7 +1009,10 @@ export function AgentCard({ agent, layout = "card", onPublisherClick }: AgentCar
   );
 
   const listLayout = (
-    <div className="group flex min-w-0 items-center gap-4 rounded-2xl border border-slate-200/90 bg-white p-4 shadow-[0_8px_24px_rgba(15,23,42,0.04)] transition-all hover:border-primary/25 hover:shadow-[0_12px_32px_rgba(15,23,42,0.09)] dark:border-slate-800 dark:bg-slate-900">
+    <div
+      className="group flex min-w-0 items-center gap-4 rounded-2xl border border-slate-200/90 bg-white p-4 shadow-[0_8px_24px_rgba(15,23,42,0.04)] transition-all hover:border-primary/25 hover:shadow-[0_12px_32px_rgba(15,23,42,0.09)] dark:border-slate-800 dark:bg-slate-900"
+      data-agent-guide="agent-card"
+    >
       <AgentBrandIcon className="agent-avatar" size="md" />
       <div className="min-w-0 flex-1 overflow-hidden">
         <div className="flex min-w-0 items-center gap-2">
@@ -1093,7 +1097,7 @@ export function AgentCard({ agent, layout = "card", onPublisherClick }: AgentCar
                     ? "正在加载 SOUL.md..."
                     : "输入 SOUL.md 内容"
                 }
-                className="max-h-[45vh] min-h-48 resize-y text-xs"
+                className="max-h-[45vh] min-h-48 resize-y text-xs"
               />
             </div>
             <div className="space-y-2">

frontend-web/src/components/workspace/agents/agent-chat-sidebar.tsx

@@ -72,6 +72,7 @@ import type { AgentThread, AgentThreadState } from "@/core/threads/types";
 import {
   bootstrapResumePath,
   isBootstrapThread,
+  isHiddenFromRecentChats,
   isThreadFavorite,
   isThreadPinned,
   sortThreadsPinnedFirst,
@@ -254,7 +255,7 @@ export function AgentChatSidebar({ activeAgentId }: { activeAgentId?: string })
                   {agents.map((agent) => {
                     const href = `${routeBase}/agents/${agent.id}/chats/new`;
                     const isActive = agent.id === activeAgentId;
-                    const { from, to } = agentColor(agent.id, isDark);
+                    const { from, to, foreground } = agentColor(agent.id, theme);
                     return (
                       <Link
                         key={agent.id}
@@ -279,6 +280,7 @@ export function AgentChatSidebar({ activeAgentId }: { activeAgentId?: string })
                           )}
                           style={{
                             backgroundImage: `linear-gradient(135deg, ${from}, ${to})`,
+                            color: foreground,
                           }}
                         >
                           <Bot className="size-[19px]" />
@@ -371,17 +373,10 @@ function RecentChatsPane({ activeAgentId }: { activeAgentId?: string }) {
   const [renameValue, setRenameValue] = useState("");
   const [shareThreadId, setShareThreadId] = useState<string | null>(null);
 
-  // 排除调度/会商类系统会话，与首页一致；智能体创建（bootstrap）会话保留展示
-  // （带机器人图标、点击回创建页）；置顶优先。
+  // 排除调度/会商/报告结构&写作配置向导等系统会话，与首页一致；
+  // 智能体创建（bootstrap）会话保留展示（带机器人图标、点击回创建页）；置顶优先。
   const visibleThreads = useMemo(
-    () =>
-      sortThreadsPinnedFirst(
-        threads.filter(
-          (thread) =>
-            thread.metadata?.thread_type !== "scheduler" &&
-            thread.metadata?.thread_type !== "roundtable",
-        ),
-      ),
+    () => sortThreadsPinnedFirst(threads.filter((thread) => !isHiddenFromRecentChats(thread))),
     [threads],
   );
 

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

@@ -1,7 +1,10 @@
 "use client";
 
 import {
+  BotIcon,
+  BriefcaseBusinessIcon,
   CheckIcon,
+  DatabaseIcon,
   GlobeIcon,
   InfoIcon,
   Loader2Icon,
@@ -42,7 +45,7 @@ import {
 import { Switch } from "@/components/ui/switch";
 import { Textarea } from "@/components/ui/textarea";
 import { AgentQuestionEditor } from "@/components/workspace/agents/agent-question-editor";
-import { AgentBrandIcon } from "@/components/workspace/agents/agent-brand-icon";
+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 +83,7 @@ interface AgentDraft {
   templateName: string;
   /** 会商席位「技能识别强化」开关。 */
   seatSkillDirective: boolean;
+  knowledgeBaseIds: string[];
 }
 
 function draftFromAgent(agent: Agent): AgentDraft {
@@ -93,6 +97,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 +105,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}
@@ -137,8 +144,20 @@ export function AgentDetailPanel({
   onAskQuestion,
   disabled,
   defaultCollapsed,
+  collapsed: collapsedProp,
+  onCollapsedChange,
   showRecentChats,
   compactAppearanceActions,
+  avatarSrc,
+  positionName,
+  skillsIcon,
+  skillsTitle,
+  showCommonQuestions = false,
+  jobResponsibilities,
+  panelTitle,
+  embedded,
+  hideStatusBadges = false,
+  editIcon,
 }: {
   agent: Agent | null | undefined;
   agentName: string;
@@ -146,13 +165,47 @@ export function AgentDetailPanel({
   disabled?: boolean;
   /** 初始收起（任务工作区进入时默认收起智能体信息面板）。 */
   defaultCollapsed?: boolean;
+  /**
+   * 受控折叠态：传入时由父级持有状态（智能体问答页把展开/收起按钮放在顶部
+   * 「新对话」右侧）。此时收起 = 整列宽度动画归零（不保留细条），面板内置的
+   * 收起按钮不再渲染。不传则沿用面板内置状态 + 细条收起交互（会商等工作区）。
+   */
+  collapsed?: boolean;
+  /** 受控折叠态变化回调（配合 `collapsed` 使用）。 */
+  onCollapsedChange?: (collapsed: boolean) => void;
   /** 在面板底部展示「有关此智能体的最近对话」（仅智能体问答页开启，任务工作区不展示）。 */
   showRecentChats?: boolean;
   /** 简洁模式下挂在右上角收起/展开按钮左侧的外观控件。 */
   compactAppearanceActions?: ReactNode;
+  avatarSrc?: string;
+  positionName?: string;
+  skillsIcon?: ReactNode;
+  skillsTitle?: string;
+  showCommonQuestions?: boolean;
+  /**
+   * 业务链席位上配置的岗位职责。传入（含空字符串）时在常用问题上方展示；
+   * 不传则隐藏该区块。此字段来自业务链，不随智能体本身编辑。
+   */
+  jobResponsibilities?: string | null;
+  /** 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);
+  // 折叠态：受控（collapsedProp 传入，智能体问答页）优先；否则面板内置（会商等工作区）。
+  const [internalCollapsed, setInternalCollapsed] = useState(
+    defaultCollapsed ?? false,
+  );
+  const collapsed = collapsedProp ?? internalCollapsed;
+  const setCollapsed = (next: boolean) => {
+    if (collapsedProp === undefined) setInternalCollapsed(next);
+    onCollapsedChange?.(next);
+  };
   const [mobileOpen, setMobileOpen] = useState(false);
   const [editing, setEditing] = useState(false);
   const [draft, setDraft] = useState<AgentDraft | null>(null);
@@ -202,9 +255,10 @@ export function AgentDetailPanel({
 
   const isSaving = updateAgent.isPending || setFeatured.isPending;
 
-  // 对话生成文件（md/txt 等 artifact）并在右侧展开预览时，自动收起智能体
-  // 信息面板给预览让位；切换到新文件时同样收起。编辑中不打断用户，用户随时
-  // 可手动重新展开。
+  // 对话生成文件（md/txt 等 artifact）并首次展开预览时，自动收起智能体
+  // 信息面板给预览让位。目录内切换文件不能再次改写用户的手动选择：否则用户
+  // 刚展开智能体信息，点另一个文件时面板又会突然收起，看起来就像收起按钮被
+  // 移除了。编辑中也不打断用户。
   //
   // 关键：判定用 open + selectedArtifact，而非 artifacts.length。流式写文件时
   // message-group 一开始就调用 select()+setOpen(true) 打开预览并选中该文件，但
@@ -213,20 +267,19 @@ export function AgentDetailPanel({
   const artifactsCtx = useArtifactsOptional();
   const artifactCount = artifactsCtx?.artifacts.length ?? 0;
   const selectedArtifact = artifactsCtx?.selectedArtifact ?? null;
+  // preOpen：流式自动开沙箱的两阶段标记 —— 沙箱真正展开（open 翻转）前就
+  // 先收起本面板，让收起布局先落地，避免与沙箱展开同帧叠加造成卡顿。
   const artifactPanelVisible =
-    !!artifactsCtx?.open && (!!selectedArtifact || artifactCount > 0);
+    (!!artifactsCtx?.open || !!artifactsCtx?.preOpen) &&
+    (!!selectedArtifact || artifactCount > 0);
   const prevArtifactPanelVisible = useRef(false);
-  const prevSelectedArtifact = useRef<string | null>(null);
   useEffect(() => {
     const opened = artifactPanelVisible && !prevArtifactPanelVisible.current;
-    const switched =
-      artifactPanelVisible && selectedArtifact !== prevSelectedArtifact.current;
     prevArtifactPanelVisible.current = artifactPanelVisible;
-    prevSelectedArtifact.current = selectedArtifact;
-    if ((opened || switched) && !editing) {
+    if (opened && !editing) {
       setCollapsed(true);
     }
-  }, [artifactPanelVisible, selectedArtifact, editing]);
+  }, [artifactPanelVisible, editing]);
 
   const displayName = desensitize(agent?.name ?? agentName);
   const questions = useMemo(
@@ -310,6 +363,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 +530,25 @@ export function AgentDetailPanel({
       </div>
     ) : (
       <div className="flex items-center gap-1">
-        <Button size="sm" variant="outline" onClick={beginEdit}>
-          <SquarePenIcon className="size-3.5" />
-          编辑
-        </Button>
-        {canTogglePublish && (
+        {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>
+        )}
+        {!embedded && canTogglePublish && (
           <Tooltip content={agent?.published ? "下架" : "发布"}>
             <Button
               size="icon-sm"
@@ -493,17 +565,19 @@ export function AgentDetailPanel({
             </Button>
           </Tooltip>
         )}
-        <Tooltip content="删除智能体">
-          <Button
-            size="icon-sm"
-            variant="ghost"
-            className="text-destructive hover:text-destructive"
-            onClick={() => setDeleteOpen(true)}
-            aria-label="删除智能体"
-          >
-            <Trash2Icon className="size-3.5" />
-          </Button>
-        </Tooltip>
+        {!embedded && (
+          <Tooltip content="删除智能体">
+            <Button
+              size="icon-sm"
+              variant="ghost"
+              className="text-destructive hover:text-destructive"
+              onClick={() => setDeleteOpen(true)}
+              aria-label="删除智能体"
+            >
+              <Trash2Icon className="size-3.5" />
+            </Button>
+          </Tooltip>
+        )}
       </div>
     )
   ) : null;
@@ -520,7 +594,13 @@ export function AgentDetailPanel({
       {/* ── Identity / 基础信息 ─────────────────────────────────────────── */}
       <section className="bg-card/60 rounded-xl border p-4">
         <div className="flex items-start gap-3">
-          <AgentBrandIcon className="agent-avatar" size="lg" />
+          <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 ? (
               <Input
@@ -539,9 +619,16 @@ export function AgentDetailPanel({
                 {displayName}
               </div>
             )}
-            <div className="flex flex-wrap items-center gap-1">
-              {statusBadges}
-            </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" />
@@ -577,6 +664,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">
@@ -594,6 +688,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>
@@ -643,8 +745,25 @@ export function AgentDetailPanel({
       </section>
 
 
+      {/* ── 岗位职责（业务链席位配置，只读）────────────────────────────── */}
+      {jobResponsibilities !== undefined && (
+        <Section
+          icon={<BriefcaseBusinessIcon className="size-3.5" />}
+          title="岗位职责"
+        >
+          {jobResponsibilities?.trim() ? (
+            <p className="text-muted-foreground text-sm leading-relaxed whitespace-pre-wrap">
+              {desensitize(jobResponsibilities)}
+            </p>
+          ) : (
+            <p className="text-muted-foreground/60 text-sm">暂无岗位职责</p>
+          )}
+        </Section>
+      )}
+
+
       {/* ── 常用问题 ───────────────────────────────────────────────────── */}
-      {(editing || questions.length > 0 || canEdit) && (
+      {(showCommonQuestions || editing || questions.length > 0 || canEdit) && (
         <Section
           icon={<MessageCircleQuestionIcon className="size-3.5" />}
           title="常用问题"
@@ -785,8 +904,9 @@ export function AgentDetailPanel({
 
       {/* ── 技能管理 ───────────────────────────────────────────────────── */}
       <Section
-        icon={<SparklesIcon className="size-3.5" />}
-        title={`已启用技能 ${skillNamesShown.length} 个`}
+        icon={skillsIcon ?? <SparklesIcon className="size-3.5" />}
+        title={skillsTitle ?? `已启用技能 ${skillNamesShown.length} 个`}
+        className="position-roundtable-skills-section"
         extra={
           editing ? (
             <Button
@@ -827,12 +947,18 @@ 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>
-        <div className="flex min-w-0 items-center gap-1">
-          {headerActions}
-          {compactAppearanceActions}
-          {collapseButton}
+      <div className="flex h-12 shrink-0 items-center gap-2 border-b px-4">
+        {/* 标题不参与压缩（此前被简洁模式外观控件挤成单字）；空间不足时只
+            裁剪 compactAppearanceActions，编辑等主操作与标题始终完整。 */}
+        <span className="shrink-0 text-sm font-semibold whitespace-nowrap">
+          {panelTitle ?? "智能体信息"}
+        </span>
+        <div className="flex min-w-0 flex-1 items-center justify-end gap-1">
+          <div className="flex shrink-0 items-center gap-1">{headerActions}</div>
+          <div className="flex min-w-0 items-center justify-end gap-1 overflow-hidden">
+            {compactAppearanceActions}
+          </div>
+          {collapseButton && <div className="shrink-0">{collapseButton}</div>}
         </div>
       </div>
       <div className="min-h-0 flex-1 overflow-y-auto">{body}</div>
@@ -841,17 +967,48 @@ export function AgentDetailPanel({
 
   return (
     <>
-      {/* ── Desktop (lg+): inline aside, collapsible to a rail ───────────── */}
-      {collapsed ? (
+      {/* ── Desktop (lg+) ────────────────────────────────────────────────── */}
+      {embedded ? (
+        <aside className="bg-card/40 flex h-full w-full min-w-0 shrink-0 flex-col border-l">
+          {panelChrome(null)}
+        </aside>
+      ) : collapsedProp !== undefined ? (
+        /* 受控模式（智能体问答页）：收起时整列宽度动画归零（含左边框），不再保留细条；
+           展开态的「收起」按钮在面板右上角，收起态的「展开」按钮在页面
+           header「新对话」按钮右侧。 */
+        <div
+          className={cn(
+            "hidden h-full shrink-0 overflow-hidden transition-[width] duration-300 ease-in-out lg:block",
+            collapsed ? "w-0" : "w-[360px]",
+          )}
+        >
+          <aside className="bg-card/40 flex h-full w-[360px] flex-col border-l">
+            {panelChrome(
+              <Tooltip content="收起">
+                <Button
+                  variant="ghost"
+                  size="icon-sm"
+                  onClick={() => setCollapsed(true)}
+                  aria-label="收起智能体信息"
+                  aria-expanded={true}
+                >
+                  <PanelRightCloseIcon className="size-4" />
+                </Button>
+              </Tooltip>,
+            )}
+          </aside>
+        </div>
+      ) : collapsed ? (
         <div className="hidden shrink-0 items-start border-l px-2 pt-3 lg:flex">
           <div className="flex items-center gap-1">
             {compactAppearanceActions}
-            <Tooltip content="智能体信息">
+            <Tooltip content="展开智能体信息">
               <Button
                 variant="ghost"
                 size="icon-sm"
                 onClick={() => setCollapsed(false)}
                 aria-label="展开智能体信息"
+                aria-expanded={false}
               >
                 <PanelRightOpenIcon className="size-4" />
               </Button>
@@ -867,6 +1024,7 @@ export function AgentDetailPanel({
                 size="icon-sm"
                 onClick={() => setCollapsed(true)}
                 aria-label="收起智能体信息"
+                aria-expanded={true}
               >
                 <PanelRightCloseIcon className="size-4" />
               </Button>
@@ -875,30 +1033,34 @@ export function AgentDetailPanel({
         </aside>
       )}
 
-      {/* ── 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="智能体信息">
-          <Button
-            variant="ghost"
-            size="icon-sm"
-            onClick={() => setMobileOpen(true)}
-            aria-label="打开智能体信息"
-          >
-            <InfoIcon className="size-4" />
-          </Button>
-        </Tooltip>
-      </div>
-      <Sheet open={mobileOpen} onOpenChange={setMobileOpen}>
-        <SheetContent side="right" className="flex w-full flex-col gap-0 p-0 sm:max-w-md">
-          <SheetHeader className="border-b px-4 pb-3 pt-4">
-            <SheetTitle className="flex items-center justify-between text-sm">
-              智能体信息
-              <span className="mr-6">{headerActions}</span>
-            </SheetTitle>
-          </SheetHeader>
-          <div className="min-h-0 flex-1 overflow-y-auto">{body}</div>
-        </SheetContent>
-      </Sheet>
+      {!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="智能体信息">
+              <Button
+                variant="ghost"
+                size="icon-sm"
+                onClick={() => setMobileOpen(true)}
+                aria-label="打开智能体信息"
+              >
+                <InfoIcon className="size-4" />
+              </Button>
+            </Tooltip>
+          </div>
+          <Sheet open={mobileOpen} onOpenChange={setMobileOpen}>
+            <SheetContent side="right" className="flex w-full flex-col gap-0 p-0 sm:max-w-md">
+              <SheetHeader className="border-b px-4 pb-3 pt-4">
+                <SheetTitle className="flex items-center justify-between text-sm">
+                  智能体信息
+                  <span className="mr-6">{headerActions}</span>
+                </SheetTitle>
+              </SheetHeader>
+              <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

@@ -1,15 +1,6 @@
 "use client";
 
-import {
-  ArrowDownUpIcon,
-  BotIcon,
-  Loader2,
-  LockIcon,
-  PlusIcon,
-  SearchIcon,
-  ShieldIcon,
-  XIcon,
-} from "lucide-react";
+import { ArrowDownUpIcon, BotIcon, Compass, Loader2, LockIcon, PlusIcon, ShieldIcon, XIcon } from "lucide-react";
 import { useRouter } from "next/navigation";
 import { useEffect, useState } from "react";
 import { toast } from "sonner";
@@ -19,17 +10,24 @@ import { Input } from "@/components/ui/input";
 import { Pagination } from "@/components/ui/pagination";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
-import { AgentBrandIcon } from "@/components/workspace/agents/agent-brand-icon";
+import { TagSearchBar } from "@/components/workspace/tags/tag-search-bar";
+import { ViewModeToggle } from "@/components/workspace/view-mode-toggle";
 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 { usePrivateSquareStatus, usePublishSquares } from "@/core/system-settings/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";
+import {
+  AgentGuide,
+  isAgentGuideEnvironment,
+  startAgentGuide,
+} from "./agent-guide";
 
 const PAGE_SIZE = 12;
-type AgentStatusFilter = "all" | "published" | "draft" | "private" | "builtin";
 
 // Within a single tab the verified password is kept in sessionStorage so a
 // refresh / route navigation does not re-prompt. Cleared on tab close, so the
@@ -39,16 +37,21 @@ 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");
   const [activeTab, setActiveTab] = useState<string>("mine");
   const [search, setSearch] = useState("");
+  const [tagIds, setTagIds] = useState<string[]>([]);
   const [sort, setSort] = useState<AgentSort>("time_desc");
-  const [statusFilter, setStatusFilter] = useState<AgentStatusFilter>("all");
   const { data: publishSquares } = usePublishSquares();
   // 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>(
@@ -61,9 +64,10 @@ export function AgentGallery() {
   // frontend's desensitize map, so typing the displayed abbreviation (e.g.
   // "TS") still matches the stored raw name (e.g. "态势分析"). Whenever the
   // filters change, every tab returns to its first page.
+  const tagKey = tagIds.join(",");
   useEffect(() => {
     setPages({});
-  }, [search, sort, publisher?.id, statusFilter]);
+  }, [search, tagKey, sort, publisher?.id]);
 
   // If the active square tab disappears (admin removed that square), fall back
   // to "我的" so the gallery never points at a dead tab.
@@ -77,6 +81,7 @@ export function AgentGallery() {
       activeTab !== "mine" &&
       activeTab !== "private" &&
       activeTab !== "builtin" &&
+      activeTab !== "sentiment" &&
       squareTabs.length > 0 &&
       !squareTabs.some((sq) => sq.id === activeTab)
     ) {
@@ -97,9 +102,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"
@@ -115,10 +124,11 @@ export function AgentGallery() {
   } = useAgentsPaginated({
     scope: mainScope,
     search,
+    tagIds,
     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,
@@ -132,6 +142,7 @@ export function AgentGallery() {
     error: privateError,
   } = usePrivateAgentsPaginated(privatePassword, {
     search,
+    tagIds,
     sort,
     page: pages.private ?? 1,
     pageSize: PAGE_SIZE,
@@ -153,9 +164,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 }));
 
@@ -182,22 +200,21 @@ export function AgentGallery() {
   const handlePublisherClick = (p: { id: string; label: string }) =>
     setPublisher(p);
 
-  const filterByStatus = (agent: Agent) => {
-    if (statusFilter === "published") return agent.published && !agent.is_private;
-    if (statusFilter === "draft") return !agent.published && !agent.is_private && !agent.builtin;
-    if (statusFilter === "private") return agent.is_private;
-    if (statusFilter === "builtin") return agent.builtin;
-    return true;
-  };
-
-  const renderGrid = (list: Agent[]) => {
-    const visibleAgents = list.filter(filterByStatus);
-    if (visibleAgents.length === 0 && list.length > 0) {
-      return renderEmpty("当前状态筛选下没有智能体。");
-    }
-    return (
-      <div className="grid grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-3">
-        {visibleAgents.map((agent) => (
+  const renderGrid = (list: Agent[]) =>
+    viewMode === "list" ? (
+      <div className="flex flex-col gap-2">
+        {list.map((agent) => (
+          <AgentCard
+            key={agent.id}
+            agent={agent}
+            layout="list"
+            onPublisherClick={handlePublisherClick}
+          />
+        ))}
+      </div>
+    ) : (
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+        {list.map((agent) => (
           <AgentCard
             key={agent.id}
             agent={agent}
@@ -206,7 +223,6 @@ export function AgentGallery() {
         ))}
       </div>
     );
-  };
 
   /** Loading / empty / (grid + pagination) for one paginated tab. */
   const renderListBody = (opts: {
@@ -271,17 +287,20 @@ export function AgentGallery() {
   };
 
   const renderEmpty = (description: string, showNewButton = false) => (
-    <div className="flex h-72 flex-col items-center justify-center gap-3 rounded-2xl border border-dashed border-primary/25 bg-white/70 text-center shadow-[0_12px_36px_rgba(15,23,42,0.05)] dark:border-primary/40 dark:bg-slate-900/70">
-      <AgentBrandIcon size="lg" />
+    <div className="flex h-64 flex-col items-center justify-center gap-3 text-center">
+      <div className="bg-muted flex h-14 w-14 items-center justify-center rounded-full dark:bg-[#022248]">
+        <BotIcon className="text-muted-foreground h-7 w-7 dark:text-[#AACEFF]" />
+      </div>
       <div>
-        <p className="font-medium">{t.agents.emptyTitle}</p>
-        <p className="text-muted-foreground mt-1 text-sm">
+        <p className="font-medium dark:text-[#AACEFF]">{t.agents.emptyTitle}</p>
+        <p className="text-muted-foreground mt-1 text-sm dark:text-[#55A6FE]">
           {description}
         </p>
       </div>
       {showNewButton && (
         <Button
-          className="bg-primary hover:bg-primary/90 mt-2 rounded-xl px-5 text-primary-foreground shadow-[0_8px_20px_rgba(15,23,42,0.16)]"
+          variant="outline"
+          className="mt-2 dark:border-[#2580FF] dark:bg-[#2580FF] dark:text-white dark:hover:border-[#2580FF] dark:hover:bg-[#2580FF]/90 dark:hover:text-white"
           onClick={handleNewAgent}
         >
           <PlusIcon className="mr-1.5 h-4 w-4" />
@@ -332,15 +351,22 @@ export function AgentGallery() {
               请输入访问密码，验证通过后才能查看其中的智能体。
             </p>
           </div>
-          <div className="flex flex-col gap-2">
+          <form
+            className="flex flex-col gap-2"
+            onSubmit={(event) => {
+              event.preventDefault();
+              handleSubmitPassword();
+            }}
+          >
+            <label className="sr-only" htmlFor="private-square-access-code">
+              访问密码
+            </label>
             <Input
+              id="private-square-access-code"
               type="password"
               placeholder="访问密码"
               value={passwordInput}
               onChange={(e) => setPasswordInput(e.target.value)}
-              onKeyDown={(e) => {
-                if (e.key === "Enter") handleSubmitPassword();
-              }}
               // This is a one-off access code, not a login credential. Tell
               // browsers / password managers not to save or autofill it (which
               // would also stop them from spilling a saved account into the
@@ -351,8 +377,8 @@ export function AgentGallery() {
               data-lpignore="true"
               data-form-type="other"
             />
-            <Button onClick={handleSubmitPassword}>进入私密广场</Button>
-          </div>
+            <Button type="submit">进入私密广场</Button>
+          </form>
         </div>
       );
     }
@@ -368,24 +394,31 @@ export function AgentGallery() {
   };
 
   return (
-    <div className="flex size-full min-h-0 flex-col overflow-hidden bg-white dark:bg-slate-950">
+    <div className="flex size-full min-h-0 flex-col">
       {/* Page header */}
-      <div className="flex shrink-0 items-start justify-between px-5 pt-7 pb-6 sm:px-8">
+      <div className="flex items-center justify-between border-b px-6 py-4">
         <div>
-          <h1 className="text-[26px] leading-none font-semibold tracking-[-0.03em] text-slate-950 dark:text-white">
-            {t.agents.title}
-          </h1>
-          <p className="mt-2.5 text-[15px] text-slate-500 dark:text-slate-400">
-            创建并管理专属的 AI 智能体，助力更高效的工作与决策。
+          <h1 className="text-xl font-semibold">{t.agents.title}</h1>
+          <p className="text-muted-foreground mt-0.5 text-sm">
+            {t.agents.description}
           </p>
         </div>
-        <Button
-          onClick={handleNewAgent}
-          className="bg-primary hover:bg-primary/90 h-11 w-[148px] rounded-xl px-0 text-[15px] font-medium text-primary-foreground shadow-[0_9px_22px_rgba(15,23,42,0.16)]"
-        >
-          <PlusIcon className="mr-2 h-[18px] w-[18px]" />
-          {t.agents.newAgent}
-        </Button>
+        <div className="flex items-center gap-2">
+          <Button
+            variant="ghost"
+            size="sm"
+            className="text-muted-foreground hover:text-foreground"
+            title="重新播放智能体使用引导"
+            onClick={() => startAgentGuide("list")}
+          >
+            <Compass className="mr-1.5 h-4 w-4" />
+            使用引导
+          </Button>
+          <Button onClick={handleNewAgent} data-agent-guide="new-agent-btn">
+            <PlusIcon className="mr-1.5 h-4 w-4" />
+            {t.agents.newAgent}
+          </Button>
+        </div>
       </div>
 
       {/* Tabs */}
@@ -393,99 +426,61 @@ export function AgentGallery() {
         value={activeTab}
         onValueChange={(v) => {
           setActiveTab(v);
-          // Each tab starts from a clean slate instead of carrying filters over.
+          // Each tab starts from a clean slate: switching tabs clears the
+          // keyword / tag / sort / publisher filters instead of carrying them
+          // over. The TagSearchBar's own input box is reset via its key below.
           setSearch("");
+          setTagIds([]);
           setSort("time_desc");
-          setStatusFilter("all");
           setPublisher(null);
         }}
         className="flex min-h-0 flex-1 flex-col overflow-hidden"
       >
-        <div className="shrink-0 px-5 sm:px-8">
-          <div className="flex min-h-12 flex-col gap-3 border-b border-slate-200/90 lg:flex-row lg:items-end lg:justify-between dark:border-slate-800">
-            <TabsList variant="line" className="h-auto w-auto max-w-full flex-wrap justify-start self-start rounded-none border-0 bg-transparent p-0">
-              <TabsTrigger
-                value="mine"
-                  className="h-12 rounded-none border-x-0 border-t-0 border-b-2 border-transparent bg-transparent px-3 text-[15px] shadow-none after:hidden data-[state=active]:border-x-0 data-[state=active]:border-t-0 data-[state=active]:!border-b-primary data-[state=active]:bg-transparent data-[state=active]:text-primary data-[state=active]:!shadow-none"
-              >
-                我的
-              </TabsTrigger>
-              {squareTabs.map((sq) => (
+        <div className="mx-6 mt-4 flex flex-col gap-3">
+          <div className="flex items-center justify-between gap-3">
+            <TabsList
+              className="w-auto max-w-full flex-wrap justify-start self-start"
+              data-agent-guide="tabs"
+            >
+              <TabsTrigger value="mine">我的</TabsTrigger>
+              {defaultSquare && (
                 <TabsTrigger
-                  key={sq.id}
-                  value={sq.id}
-                  title={sq.description || sq.name}
-                  className="h-12 rounded-none border-x-0 border-t-0 border-b-2 border-transparent bg-transparent px-5 text-[15px] shadow-none after:hidden data-[state=active]:border-x-0 data-[state=active]:border-t-0 data-[state=active]:!border-b-primary data-[state=active]:bg-transparent data-[state=active]:text-primary data-[state=active]:!shadow-none"
+                  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>
               ))}
               {privateFeatureAvailable && (
-                <TabsTrigger
-                  value="private"
-                  className="h-12 rounded-none border-x-0 border-t-0 border-b-2 border-transparent bg-transparent px-5 text-[15px] shadow-none after:hidden data-[state=active]:border-x-0 data-[state=active]:border-t-0 data-[state=active]:!border-b-primary data-[state=active]:bg-transparent data-[state=active]:text-primary data-[state=active]:!shadow-none"
-                >
+                <TabsTrigger value="private">
                   <LockIcon className="mr-1 h-3.5 w-3.5" />
                   私密广场
                 </TabsTrigger>
               )}
               {isAdmin && (
-                <TabsTrigger
-                  value="builtin"
-                  title="内置/功能型智能体（仅管理员可见）"
-                  className="h-12 rounded-none border-x-0 border-t-0 border-b-2 border-transparent bg-transparent px-5 text-[15px] shadow-none after:hidden data-[state=active]:border-x-0 data-[state=active]:border-t-0 data-[state=active]:!border-b-primary data-[state=active]:bg-transparent data-[state=active]:text-primary data-[state=active]:!shadow-none"
-                >
+                <TabsTrigger value="builtin" title="内置/功能型智能体（仅管理员可见）">
                   <BotIcon className="mr-1 h-3.5 w-3.5" />
                   内置智能体
                 </TabsTrigger>
               )}
             </TabsList>
-            {showSearchBar && (
-              <div className="flex flex-wrap items-center justify-end gap-3 pb-2">
-                <div className="relative w-[320px] max-w-full">
-                  <SearchIcon className="pointer-events-none absolute top-1/2 left-3.5 size-[18px] -translate-y-1/2 text-slate-500" />
-                  <Input
-                    value={search}
-                    onChange={(event) => setSearch(event.target.value)}
-                    placeholder="搜索智能体名称或描述"
-                    className="h-11 rounded-xl border-slate-200 bg-white pl-11 text-sm shadow-none placeholder:text-slate-400 focus-visible:border-primary/50 focus-visible:ring-primary/15 dark:border-slate-700 dark:bg-slate-900"
-                  />
-                  {(activeTab === "private" ? isPrivateFetching : mainFetching) && (
-                    <Loader2 className="text-primary absolute top-1/2 right-3.5 size-4 -translate-y-1/2 animate-spin" />
-                  )}
-                </div>
-                <Select
-                  value={statusFilter}
-                  onValueChange={(value) => setStatusFilter(value as AgentStatusFilter)}
-                >
-                  <SelectTrigger className="h-11 w-[150px] rounded-xl border-slate-200 px-4 text-sm shadow-none dark:border-slate-700">
-                    <SelectValue />
-                  </SelectTrigger>
-                  <SelectContent position="popper" side="bottom" sideOffset={4}>
-                    <SelectItem value="all">全部状态</SelectItem>
-                    <SelectItem value="published">已发布</SelectItem>
-                    <SelectItem value="draft">未发布</SelectItem>
-                    <SelectItem value="private">私密</SelectItem>
-                    <SelectItem value="builtin">内置</SelectItem>
-                  </SelectContent>
-                </Select>
-                <Select value={sort} onValueChange={(v) => setSort(v as AgentSort)}>
-                  <SelectTrigger
-                    className="h-11 w-[150px] rounded-xl border-slate-200 px-4 text-sm shadow-none dark:border-slate-700"
-                    title="排序"
-                  >
-                    <ArrowDownUpIcon className="mr-1 size-4 text-slate-500" />
-                    <SelectValue />
-                  </SelectTrigger>
-                  <SelectContent position="popper" side="bottom" sideOffset={4}>
-                    <SelectItem value="time_desc">更新时间</SelectItem>
-                    <SelectItem value="time_asc">最早创建</SelectItem>
-                    <SelectItem value="updated_desc">最近更新</SelectItem>
-                    <SelectItem value="updated_asc">最早更新</SelectItem>
-                    <SelectItem value="name_asc">名称 A-Z</SelectItem>
-                    <SelectItem value="name_desc">名称 Z-A</SelectItem>
-                  </SelectContent>
-                </Select>
+            <div className="flex items-center gap-3">
+              <span className="text-muted-foreground text-sm whitespace-nowrap">
+                共 {activeTotal} 个
+              </span>
+              <ViewModeToggle value={viewMode} onChange={setViewMode} />
               {activeTab === "private" && privatePassword && (
                 <Button
                   variant="outline"
@@ -497,16 +492,50 @@ export function AgentGallery() {
                   锁定
                 </Button>
               )}
-              </div>
-            )}
+            </div>
           </div>
+          {showSearchBar && (
+            <div data-agent-guide="search">
+              <TagSearchBar
+              // Remount per tab so the internal keyword input / 展开 state also
+              // resets when the parent-owned filters are cleared on tab switch.
+              key={activeTab}
+              targetType="agent"
+              searching={
+                activeTab === "private" ? isPrivateFetching : mainFetching
+              }
+              onSearchChange={setSearch}
+              tagIds={tagIds}
+              onTagIdsChange={setTagIds}
+              actions={
+                <Select value={sort} onValueChange={(v) => setSort(v as AgentSort)}>
+                  <SelectTrigger
+                    className="h-9 w-full gap-2 px-3 text-xs sm:w-[148px]"
+                    title="排序"
+                  >
+                    <ArrowDownUpIcon className="text-muted-foreground size-3.5" />
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent position="popper" side="bottom" sideOffset={4}>
+                    <SelectItem value="time_desc">最新创建</SelectItem>
+                    <SelectItem value="time_asc">最早创建</SelectItem>
+                    <SelectItem value="updated_desc">最近更新</SelectItem>
+                    <SelectItem value="updated_asc">最早更新</SelectItem>
+                    <SelectItem value="name_asc">名称 A-Z</SelectItem>
+                    <SelectItem value="name_desc">名称 Z-A</SelectItem>
+                  </SelectContent>
+                </Select>
+              }
+            />
+            </div>
+          )}
           {publisher && (
-            <div className="mt-3 flex items-center gap-2">
+            <div className="flex items-center gap-2">
               <span className="text-muted-foreground text-xs">筛选发布者：</span>
               <button
                 type="button"
                 onClick={() => setPublisher(null)}
-              className="bg-primary/5 text-primary hover:bg-primary/10 inline-flex items-center gap-1 rounded-full px-3 py-1 text-xs font-medium transition-colors dark:bg-primary/15 dark:text-primary"
+                className="bg-primary/10 text-primary hover:bg-primary/20 inline-flex items-center gap-1 rounded-full px-3 py-1 text-xs font-medium transition-colors"
                 title="点击清除发布者筛选"
               >
                 {publisher.label}
@@ -514,16 +543,13 @@ export function AgentGallery() {
               </button>
             </div>
           )}
-          <div className="py-4 text-[15px] text-slate-600 dark:text-slate-300">
-            共 {activeTotal} 个智能体
-          </div>
         </div>
 
         {squareTabs.map((sq) => (
           <TabsContent
             key={sq.id}
             value={sq.id}
-            className="mt-0 flex-1 overflow-y-auto px-5 pb-6 sm:px-8"
+            className="flex-1 overflow-y-auto p-6 mt-0"
           >
             {renderListBody({
               list: mainAgents,
@@ -536,7 +562,7 @@ export function AgentGallery() {
           </TabsContent>
         ))}
 
-        <TabsContent value="mine" className="mt-0 flex-1 overflow-y-auto px-5 pb-6 sm:px-8">
+        <TabsContent value="mine" className="flex-1 overflow-y-auto p-6 mt-0">
           {renderListBody({
             list: mainAgents,
             total: mainTotal,
@@ -548,8 +574,27 @@ 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="mt-0 flex-1 overflow-y-auto px-5 pb-6 sm:px-8">
+          <TabsContent value="builtin" className="flex-1 overflow-y-auto p-6 mt-0">
             {renderListBody({
               list: mainAgents,
               total: mainTotal,
@@ -564,12 +609,17 @@ export function AgentGallery() {
         {privateFeatureAvailable && (
           <TabsContent
             value="private"
-            className="mt-0 flex-1 overflow-y-auto px-5 pb-6 sm:px-8"
+            className="flex-1 overflow-y-auto p-6 mt-0"
           >
             {renderPrivateTab()}
           </TabsContent>
         )}
       </Tabs>
+      <AgentGuide
+        stage="list"
+        eligible={isAgentGuideEnvironment()}
+        autoStart={false}
+      />
     </div>
   );
 }

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

@@ -0,0 +1,331 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Guide, type GuideStep } from "tdesign-react";
+
+import { env } from "@/env";
+import { isEmbedActive, isHideChromeActive } from "@/core/embed/embed-session";
+import { isWujieEnv } from "@/core/embed/wujie";
+
+/**
+ * 智能体使用引导（三段式，基于 TDesign React 的 Guide 组件），完整覆盖
+ * 「浏览管理 → 创建与配置 → 发起问答」流程：
+ *
+ *   - list   ：智能体列表页（/page/workspace/agents）——分区、搜索排序、卡片操作、
+ *              创建入口；完成 / 跳过就地结束，不跳转创建页（创建页有自己的一段
+ *              引导，点「创建智能体」进入时自动演示）。
+ *   - create ：创建页（/page/workspace/agents/new）——对话式创建、基本信息、模型、
+ *              知识空间、SOUL.md、技能、保存。
+ *   - chat   ：智能体对话页（/page/workspace/agents/:id/chats/...）——侧栏切换与
+ *              历史、常用问题、输入框、右侧详情面板。
+ *
+ * 记忆语义与简洁模式引导（compact-mode-guide.tsx）一致：每个阶段各自记一个
+ * localStorage 标记，**只有用户显式点「完成」或「跳过」才写入**；中途刷新/离开
+ * 不记忆，下次进入该页面还会自动演示。各页头部的「使用引导」按钮可随时强制重放。
+ *
+ * 自动演示范围：只有 create 段（进入新建页）与 chat 段自动弹；list 段挂在
+ * 智能体列表页但不自动演示（`autoStart={false}`，避免一进列表页就弹引导），
+ * 仅由头部「使用引导」按钮手动触发。
+ *
+ * 高亮目标通过 `data-agent-guide` 标记在各组件上；启动时按目标是否存在过滤步骤
+ * （如新用户无智能体卡片、无预设常用问题时自动剔除该步）——Guide 对找不到的
+ * 目标元素会抛错，不能盲传。
+ */
+
+export type AgentGuideStage = "list" | "create" | "chat";
+
+const finishedKey = (stage: AgentGuideStage) =>
+  `deerflow.agent-guide.${stage}.finished`;
+
+const startEventName = (stage: AgentGuideStage) =>
+  `agent-guide:start:${stage}`;
+
+/** 手动触发某阶段的引导（各页面头部「使用引导」按钮调用，忽略已看过记忆）。 */
+export function startAgentGuide(stage: AgentGuideStage) {
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(new CustomEvent(startEventName(stage)));
+  }
+}
+
+/** 环境闸门：iframe 嵌入 / 去 chrome / 强制收起侧栏（无界）等环境不弹引导。 */
+export function isAgentGuideEnvironment(): boolean {
+  return (
+    !env.FORCE_COLLAPSED_SIDEBAR &&
+    !isEmbedActive() &&
+    !isHideChromeActive() &&
+    !isWujieEnv()
+  );
+}
+
+/** 引导步骤高亮目标选择器；各目标元素由所在组件打上同名 data 标记。 */
+const TARGET = {
+  // list 阶段（智能体列表页）
+  tabs: '[data-agent-guide="tabs"]',
+  search: '[data-agent-guide="search"]',
+  agentCard: '[data-agent-guide="agent-card"]',
+  newAgentBtn: '[data-agent-guide="new-agent-btn"]',
+  // create 阶段（创建页）
+  createChatInput: '[data-agent-guide="create-chat-input"]',
+  createBasic: '[data-agent-guide="create-basic"]',
+  createModel: '[data-agent-guide="create-model"]',
+  createKnowledge: '[data-agent-guide="create-knowledge"]',
+  createSoul: '[data-agent-guide="create-soul"]',
+  createSkills: '[data-agent-guide="create-skills"]',
+  createSaveBtn: '[data-agent-guide="create-save-btn"]',
+  // chat 阶段（智能体对话页）
+  chatSidebar: '[data-agent-guide="chat-sidebar"]',
+  chatQuestions: '[data-agent-guide="chat-questions"]',
+  chatInput: '[data-agent-guide="chat-input"]',
+  chatDetail: '[data-agent-guide="chat-detail"]',
+} as const;
+
+// 等布局稳定后再启动：Guide 只在步骤切换时测量目标位置，起步太早会把高亮框
+// 定位到过渡中的坐标且不会自行纠正。
+const START_DELAY_MS = 800;
+
+interface StepSpec {
+  /** 高亮目标选择器；缺省（dialog 步骤）以 body 兜底。 */
+  selector?: string;
+  mode: "popup" | "dialog";
+  placement: NonNullable<GuideStep["placement"]>;
+  title: string;
+  body: string;
+}
+
+const LIST_STEPS: StepSpec[] = [
+  {
+    mode: "dialog",
+    placement: "center",
+    title: "欢迎使用智能体",
+    body: "这里是你的智能体中心。接下来花几分钟走完整个流程：浏览与管理智能体 → 创建与配置 → 发起问答。",
+  },
+  {
+    selector: TARGET.tabs,
+    mode: "popup",
+    placement: "bottom",
+    title: "分区浏览",
+    body: "「我的」放着你创建和收藏的智能体；各「广场」是他人发布共享的，可直接使用或收藏；「私密广场」需要密码访问（管理员还可以查看「内置智能体」）。",
+  },
+  {
+    selector: TARGET.search,
+    mode: "popup",
+    placement: "bottom",
+    title: "搜索与排序",
+    body: "支持关键词、标签搜索，可按最新创建、最近更新、名称排序；右侧按钮可在卡片 / 列表两种视图间切换。",
+  },
+  {
+    selector: TARGET.agentCard,
+    mode: "popup",
+    placement: "top",
+    title: "智能体卡片",
+    body: "卡片展示名称、简介、模型与技能徽章；底部操作栏支持收藏、置顶、打标签、发布到广场、复制、编辑、删除；点「对话」直接进入该智能体的问答。",
+  },
+  {
+    selector: TARGET.newAgentBtn,
+    mode: "popup",
+    placement: "bottom-left",
+    title: "创建智能体",
+    body: "准备好了就点这里，开始创建你的专属智能体；进入创建页后还会有一段配置引导。",
+  },
+];
+
+const CREATE_STEPS: StepSpec[] = [
+  {
+    mode: "dialog",
+    placement: "center",
+    title: "创建智能体",
+    body: "页面分两栏：左侧直接与模型对话，让它帮你配置；右侧表单手动填写。两边内容实时联动，选顺手的方式即可。",
+  },
+  {
+    selector: TARGET.createChatInput,
+    mode: "popup",
+    placement: "top",
+    title: "对话式创建",
+    body: "在这里描述你想要的智能体，例如「帮我做一个周报助手，语气正式、要点条目化」。模型会追问细节并给出配置方案，你确认后方案自动填入右侧表单，可继续微调。",
+  },
+  {
+    selector: TARGET.createBasic,
+    mode: "popup",
+    placement: "left",
+    title: "基本信息",
+    body: "「名称」显示在卡片和对话页；「描述」用一句话说明它擅长什么，方便日后挑选。",
+  },
+  {
+    selector: TARGET.createModel,
+    mode: "popup",
+    placement: "left",
+    title: "运行模型与入库",
+    body: "「模型」选择该智能体被使用时调用的模型；「入库模板名」配置后，对话生成的文档可一键发布入库（不需要可留空）。",
+  },
+  {
+    selector: TARGET.createKnowledge,
+    mode: "popup",
+    placement: "left",
+    title: "知识空间",
+    body: "为智能体挂载知识库，回答时会优先检索其中的资料，让结果更贴合你的业务数据。",
+  },
+  {
+    selector: TARGET.createSoul,
+    mode: "popup",
+    placement: "left",
+    title: "SOUL.md · 人设",
+    body: "智能体的「灵魂文件」——写清角色定位、能力边界、工作步骤和输出格式。这份提示词直接决定回答质量，是最值得花时间打磨的配置。",
+  },
+  {
+    selector: TARGET.createSkills,
+    mode: "popup",
+    placement: "left",
+    title: "技能挂载",
+    body: "从可用技能中勾选要赋予的能力，已选技能会作为工具在对话中被调用；全部不选则是纯对话型智能体。",
+  },
+  {
+    selector: TARGET.createSaveBtn,
+    mode: "popup",
+    placement: "top",
+    title: "创建并保存",
+    body: "配置完成后点这里保存（左侧对话只是试用场，内容不会自动保存）。保存成功会回到智能体列表。",
+  },
+  {
+    mode: "dialog",
+    placement: "center",
+    title: "开始问答",
+    body: "回到列表页后，点智能体卡片上的「对话」按钮即可开始问答；进入对话页还会有最后一段引导。",
+  },
+];
+
+const CHAT_STEPS: StepSpec[] = [
+  {
+    mode: "dialog",
+    placement: "center",
+    title: "智能体问答",
+    body: "一切就绪！这里就是与智能体对话的工作区，快速认识一下。",
+  },
+  {
+    selector: TARGET.chatSidebar,
+    mode: "popup",
+    placement: "right",
+    title: "切换与历史",
+    body: "左栏顶部可在「我的 / 广场」智能体之间切换；下方是当前智能体的历史会话，点击任意一条继续上次的对话。",
+  },
+  {
+    selector: TARGET.chatQuestions,
+    mode: "popup",
+    placement: "bottom",
+    title: "常用问题",
+    body: "智能体预设的开场问题，点击即可直接提问，快速体验它的能力。",
+  },
+  {
+    selector: TARGET.chatInput,
+    mode: "popup",
+    placement: "top",
+    title: "输入框",
+    body: "输入问题后发送即可开始问答；新对话里还可以挂载知识空间，让回答优先检索知识库。",
+  },
+  {
+    selector: TARGET.chatDetail,
+    mode: "popup",
+    placement: "left",
+    title: "智能体详情",
+    body: "右侧面板展示当前智能体的配置（人设、技能、常用问题），可以直接修改并即时生效；里面的快捷提问也能一键发送。",
+  },
+];
+
+const STAGE_STEPS: Record<AgentGuideStage, StepSpec[]> = {
+  list: LIST_STEPS,
+  create: CREATE_STEPS,
+  chat: CHAT_STEPS,
+};
+
+function isBrowser(): boolean {
+  return typeof window !== "undefined";
+}
+
+function isStageFinished(stage: AgentGuideStage): boolean {
+  return (
+    isBrowser() && localStorage.getItem(finishedKey(stage)) === "1"
+  );
+}
+
+function markStageFinished(stage: AgentGuideStage) {
+  if (isBrowser()) localStorage.setItem(finishedKey(stage), "1");
+}
+
+function buildSteps(stage: AgentGuideStage): GuideStep[] {
+  if (!isBrowser()) return [];
+  return STAGE_STEPS[stage]
+    .filter((spec) => !spec.selector || document.querySelector(spec.selector))
+    .map((spec) => ({
+      element: spec.selector ?? (() => document.body),
+      mode: spec.mode,
+      placement: spec.placement,
+      title: spec.title,
+      body: spec.body,
+    }));
+}
+
+/**
+ * 智能体三段引导的运行组件：`stage` 决定步骤内容，`eligible` 为 false 时完全
+ * 静默（不监听、不自动弹）。挂在三个页面各自的作用域内；`autoStart` 为 false
+ * 时仅响应手动触发（列表页不自动弹，进新建页才自动演示）。
+ */
+export function AgentGuide({
+  stage,
+  eligible,
+  autoStart = true,
+}: {
+  stage: AgentGuideStage;
+  eligible: boolean;
+  autoStart?: boolean;
+}) {
+  const [current, setCurrent] = useState(-1);
+  const stepsRef = useRef<GuideStep[]>([]);
+
+  const start = useCallback(() => {
+    const steps = buildSteps(stage);
+    if (steps.length === 0) return;
+    stepsRef.current = steps;
+    setCurrent(0);
+  }, [stage]);
+
+  // 自动演示：没显式结束过（没点过完成/跳过）时，每次进入该页都演示；是否
+  // 「已看过」只由 finish 回调（完成/跳过）写入。
+  const autoTriedRef = useRef(false);
+  useEffect(() => {
+    if (!eligible || !autoStart || autoTriedRef.current) return;
+    autoTriedRef.current = true;
+    if (isStageFinished(stage)) return;
+    const timer = setTimeout(start, START_DELAY_MS);
+    return () => {
+      clearTimeout(timer);
+      // 组件在计时窗口内卸载（用户迅速离开页面）则下次进入再演示。
+      autoTriedRef.current = false;
+    };
+  }, [eligible, autoStart, stage, start]);
+
+  // 手动触发：页面头部「使用引导」按钮广播事件，忽略已看过记忆强制重放。
+  useEffect(() => {
+    if (!eligible) return;
+    const handler = () => start();
+    window.addEventListener(startEventName(stage), handler);
+    return () =>
+      window.removeEventListener(startEventName(stage), handler);
+  }, [eligible, stage, start]);
+
+  // 完成 / 跳过都是用户显式结束引导，就地关闭并记忆「已看过」，不跳转任何页面。
+  const finish = useCallback(() => {
+    markStageFinished(stage);
+    setCurrent(-1);
+  }, [stage]);
+
+  if (!eligible) return null;
+
+  return (
+    <Guide
+      current={current}
+      steps={stepsRef.current}
+      onChange={setCurrent}
+      onFinish={finish}
+      onSkip={finish}
+    />
+  );
+}

frontend-web/src/components/workspace/agents/agent-module-sidebar.tsx

@@ -206,7 +206,7 @@ export function AgentModuleSidebar({
   const renderAgentCard = (agent: Agent, keyPrefix: string) => {
     const href = `${routeBase}/agents/${agent.id}/chats/new`;
     const isActive = agent.id === activeAgentId;
-    const { from, to } = agentColor(agent.id, isDark);
+    const { from, to, foreground } = agentColor(agent.id, theme);
     return (
       <Link
         key={`${keyPrefix}:${agent.id}`}
@@ -236,7 +236,10 @@ export function AgentModuleSidebar({
               isActive &&
               "ring-2 ring-[#83c1ff]/35 shadow-[0_0_18px_rgba(43,143,254,0.45)]",
           )}
-          style={{ backgroundImage: `linear-gradient(135deg, ${from}, ${to})` }}
+          style={{
+            backgroundImage: `linear-gradient(135deg, ${from}, ${to})`,
+            color: foreground,
+          }}
         >
           <Bot className="size-[19px]" />
         </span>

frontend-web/src/components/workspace/agents/agent-recent-chats.tsx

@@ -5,7 +5,7 @@ import Link from "next/link";
 import { usePathname } from "next/navigation";
 
 import { useThreadsPage } from "@/core/threads/hooks";
-import { pathOfThread, titleOfThread } from "@/core/threads/utils";
+import { pathOfThread, titleOfThread, isHiddenFromRecentChats, isBootstrapThread } from "@/core/threads/utils";
 import { desensitize } from "@/lib/desensitize";
 import { cn } from "@/lib/utils";
 
@@ -22,12 +22,9 @@ export function AgentRecentChats({ agentId }: { agentId: string }) {
     pageSize: RECENT_LIMIT,
     metadata: { agent_id: agentId },
   });
-  // 该智能体的会话里同样排除调度 / 引导 / 会商类系统会话。
+  // 该智能体的会话里同样排除引导 / 系统 / 配置向导会话。
   const threads = (data?.threads ?? []).filter(
-    (th) =>
-      th.metadata?.thread_type !== "bootstrap" &&
-      th.metadata?.thread_type !== "scheduler" &&
-      th.metadata?.thread_type !== "roundtable",
+    (th) => !isBootstrapThread(th) && !isHiddenFromRecentChats(th),
   );
 
   return (

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

@@ -93,43 +93,47 @@ export function AgentSelector({
   return (
     <>
       <Dialog open={open} onOpenChange={setOpen}>
-        <DialogTrigger asChild>
-          {iconMode ? (
-            <Tooltip content={iconTooltipLabel}>
-              <Button
-                type="button"
-                variant="ghost"
-                size="icon"
-                disabled={disabled}
-                aria-label={selectedAgent ? `已选择智能体：${triggerLabel}` : "选择智能体"}
-                className={cn(
-                  "relative size-9 rounded-full text-muted-foreground shadow-none hover:bg-muted/60 hover:text-foreground",
-                  selectedAgent && "text-amber-600 hover:text-amber-700",
-                  selectedAgent && iconActiveClassName,
-                  iconButtonClassName,
-                )}
-              >
-                <BotIcon className="size-4" />
-                {selectedAgent && (
-                  <span
-                    role="button"
-                    tabIndex={0}
-                    aria-label="清除已选 agent"
-                    className="absolute -right-1 -top-1 inline-flex size-4 items-center justify-center rounded-full border bg-background text-foreground shadow-sm hover:bg-muted"
-                    onClick={handleClear}
-                    onKeyDown={(e) => {
-                      if (e.key === "Enter" || e.key === " ") {
-                        e.preventDefault();
-                        onAgentChange(null);
-                      }
-                    }}
-                  >
-                    <XIcon className="size-2.5" />
-                  </span>
-                )}
-              </Button>
-            </Tooltip>
-          ) : (
+        {iconMode ? (
+          <Tooltip content={iconTooltipLabel}>
+            <div>
+              <DialogTrigger asChild>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon"
+                  disabled={disabled}
+                  aria-label={selectedAgent ? `已选择智能体：${triggerLabel}` : "选择智能体"}
+                  className={cn(
+                    "relative size-9 rounded-full text-muted-foreground shadow-none hover:bg-muted/60 hover:text-foreground",
+                    selectedAgent && "text-amber-600 hover:text-amber-700",
+                    selectedAgent && iconActiveClassName,
+                    iconButtonClassName,
+                  )}
+                >
+                  <BotIcon className="size-4" />
+                  {selectedAgent && (
+                    <span
+                      role="button"
+                      tabIndex={0}
+                      aria-label="清除已选 agent"
+                      className="absolute -right-1 -top-1 inline-flex size-4 items-center justify-center rounded-full border bg-background text-foreground shadow-sm hover:bg-muted"
+                      onClick={handleClear}
+                      onKeyDown={(e) => {
+                        if (e.key === "Enter" || e.key === " ") {
+                          e.preventDefault();
+                          onAgentChange(null);
+                        }
+                      }}
+                    >
+                      <XIcon className="size-2.5" />
+                    </span>
+                  )}
+                </Button>
+              </DialogTrigger>
+            </div>
+          </Tooltip>
+        ) : (
+          <DialogTrigger asChild>
             <PromptInputButton
               type="button"
               disabled={disabled}
@@ -167,8 +171,8 @@ export function AgentSelector({
                 </span>
               )}
             </PromptInputButton>
-          )}
-        </DialogTrigger>
+          </DialogTrigger>
+        )}
         <DialogContent className="overflow-hidden p-0 sm:max-w-md">
           <DialogTitle className="sr-only">选择 Agent</DialogTitle>
           <Command className="**:data-[slot=command-input-wrapper]:h-auto">

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），
+ * 对话经 Gateway 转发外部 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/agents/skill-picker-sheet.tsx

@@ -165,10 +165,26 @@ export function SkillPickerSheet({
       return;
     }
     try {
-      const validation = await validateUpload.mutateAsync(file);
+      const validation = await validateUpload.mutateAsync({
+        file,
+        targetCategory: "custom",
+      });
       if (validation.conflict) {
+        const owner = validation.owner_username ?? validation.owner_user_id;
+        if (validation.owned_by_other && owner) {
+          toast.error(
+            `技能「${validation.skill_name}」已由用户「${owner}」上传，不能覆盖。`,
+          );
+          return;
+        }
+        if (validation.owned_by_me && validation.can_overwrite) {
+          toast.warning(
+            `您已上传过同名技能「${validation.skill_name}」，可到「技能」设置页重复上传并覆盖原版本。`,
+          );
+          return;
+        }
         toast.warning(
-          `已存在同名技能「${validation.skill_name}」，请到「技能」设置页上传以选择是否覆盖。`,
+          `已存在同名技能「${validation.skill_name}」，当前不可覆盖。`,
         );
         return;
       }

frontend-web/src/components/workspace/agents/skill-transfer-selector.tsx

@@ -45,11 +45,32 @@ function skillLabel(skill: Skill) {
 
 function matchesQuery(skill: Skill, q: string) {
   if (!q) return true;
-  return (
-    skill.name.toLowerCase().includes(q) ||
-    (skill.name_zh ?? "").toLowerCase().includes(q) ||
-    (skill.description ?? "").toLowerCase().includes(q)
-  );
+  const haystack = [
+    skill.name,
+    skill.name_zh,
+    skill.description,
+    skill.detail,
+    skill.category,
+    skill.license,
+    skill.source,
+    skill.state,
+    skill.owner_username,
+    skill.created_at,
+    skill.last_activity_at,
+    skill.use_count != null ? `使用 ${skill.use_count}` : null,
+    skill.view_count != null ? `查看 ${skill.view_count}` : null,
+    skill.patch_count != null ? `变迁 ${skill.patch_count}` : null,
+    ...(skill.tags ?? []).flatMap((tag) => [
+      tag.name,
+      tag.description,
+      tag.color,
+      tag.usage_count != null ? `标签使用 ${tag.usage_count}` : null,
+    ]),
+  ]
+    .filter((value): value is string => typeof value === "string" && value.length > 0)
+    .join(" ")
+    .toLowerCase();
+  return haystack.includes(q);
 }
 
 export function SkillTransferSelector({
@@ -159,7 +180,7 @@ export function SkillTransferSelector({
         <div className="relative flex-1">
           <SearchIcon className="text-muted-foreground absolute left-2 top-1/2 size-3.5 -translate-y-1/2" />
           <Input
-            placeholder="搜索全部技能(中英文名称、描述)…"
+            placeholder="搜索技能名称、描述、分类、标签、变迁..."
             value={search}
             onChange={(e) => {
               setSearch(e.currentTarget.value);
@@ -239,7 +260,7 @@ export function SkillTransferSelector({
       {/* Two-column transfer panes */}
       <div className="grid grid-cols-2 gap-3">
         <SkillPane
-          title="可用技能"
+          title="未勾选技能"
           count={availableSkills.length}
           items={availableView}
           variant="available"
@@ -248,10 +269,10 @@ export function SkillTransferSelector({
           onPageChange={setAvailablePage}
           onPick={add}
           onViewDetail={onViewDetail}
-          emptyHint={query || category !== ALL_CATEGORIES ? "没有匹配的技能" : "已全部启用"}
+          emptyHint={query || category !== ALL_CATEGORIES ? "没有匹配的技能" : "已全部勾选"}
         />
         <SkillPane
-          title="已启用技能"
+          title="已勾选技能"
           count={selectedSkills.length}
           items={selectedView}
           variant="selected"
@@ -260,7 +281,7 @@ export function SkillTransferSelector({
           onPageChange={setSelectedPage}
           onPick={remove}
           onViewDetail={onViewDetail}
-          emptyHint={query ? "没有匹配的已选技能" : "尚未启用任何技能"}
+          emptyHint={query ? "没有匹配的已选技能" : "尚未勾选任何技能"}
         />
       </div>
     </div>

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

@@ -1,7 +1,7 @@
 "use client";
 
 import { Check, ExternalLink, LayoutIcon, PanelLeftIcon, Shirt } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { useNavigate } from "react-router-dom";
 
 import { Button } from "@/components/ui/button";
@@ -14,10 +14,12 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { useTheme, type ThemeType } from "@/contexts/ThemeContext";
-import { env } from "@/env";
+import type { CompactShortcutRouteParam } from "@/core/system-settings/api";
 import { useAppearanceSettings, useLayoutMode } from "@/core/system-settings/hooks";
+import { isHideChromeActive } from "@/core/embed/embed-session";
+import { env } from "@/env";
 import { cn } from "@/lib/utils";
-import { buildLightAppUrl } from "@/strategy-components/lib/light-app";
+import { buildLightAppUrl, resolveRouteParamValue } from "@/strategy-components/lib/light-app";
 
 /**
  * 换肤 / 界面模式 顶栏控件。深色顶栏（Header）与简洁模式页面级顶栏（ChatPage 等）共用，
@@ -25,13 +27,15 @@ 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)，绿色=WeKnora 绿色主题(lightgreen)，蓝色=浅蓝主题(lightblue)，深蓝色=深色主题(dark)
+// 换肤色板：红色=红白主题(light)，蓝色=浅蓝主题(lightblue)，冰川蓝=柔和浅蓝主题(iceblue)，浅黄色=柔和黄主题(lightyellow)，深蓝色=深色主题(dark)
 export const THEME_SWATCHES: { id: ThemeType; label: string; color: string }[] = [
   { id: "light", label: "红色", color: "#cf1322" },
   { id: "lightgreen", label: "绿色", color: "#07c05f" },
   { id: "lightblue", label: "蓝色", color: "#0062d9" },
+  { id: "iceblue", label: "冰川蓝", color: "#9BCEF1" },
+  { id: "lightyellow", label: "浅黄色", color: "#F3FBD9" },
   { id: "dark", label: "深蓝色", color: "#002466" },
 ];
 
@@ -40,8 +44,38 @@ 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";
 
+function appendShortcutPathParams(url: string, params: CompactShortcutRouteParam[]) {
+  const pathSegments = params
+    .filter((param) => param.paramType === "path")
+    .map((param) =>
+      resolveRouteParamValue({ ...param, paramType: "login" }).trim(),
+    )
+    .filter(Boolean)
+    .map((value) => encodeURIComponent(value));
+  if (pathSegments.length === 0) return url;
+
+  const hashIndex = url.indexOf("#");
+  if (hashIndex < 0) {
+    const [path, query = ""] = url.split("?", 2);
+    return `${path.replace(/\/+$/, "")}/${pathSegments.join("/")}${query ? `?${query}` : ""}`;
+  }
+
+  const beforeHash = url.slice(0, hashIndex);
+  const fragment = url.slice(hashIndex + 1);
+  const [routePath, query = ""] = fragment.split("?", 2);
+  return `${beforeHash}#${routePath.replace(/\/+$/, "")}/${pathSegments.join("/")}${query ? `?${query}` : ""}`;
+}
+
+function isQueryShortcutParam(
+  param: CompactShortcutRouteParam,
+): param is CompactShortcutRouteParam & { paramType: "login" | "theme" } {
+  return param.paramType === "login" || param.paramType === "theme";
+}
+
 export function CompactShortcutButtons({ tone }: { tone: AppearanceControlTone }) {
   const { data: appearance } = useAppearanceSettings();
   const buttons = (appearance?.compact_shortcut_buttons ?? [])
@@ -64,9 +98,10 @@ export function CompactShortcutButtons({ tone }: { tone: AppearanceControlTone }
           )}
           title={button.label}
           onClick={() => {
+            const routeParams = (button.route_params ?? []).map((param) => ({ ...param }));
             const url = buildLightAppUrl({
-              url: button.url,
-              routeParams: button.route_params.map((param) => ({ ...param })),
+              url: appendShortcutPathParams(button.url, routeParams),
+              routeParams: routeParams.filter(isQueryShortcutParam),
             });
             window.open(url, "_blank", "noopener,noreferrer");
           }}
@@ -80,11 +115,24 @@ export function CompactShortcutButtons({ tone }: { tone: AppearanceControlTone }
 }
 
 export function ThemeSwitcher({ tone }: { tone: AppearanceControlTone }) {
-  if (env.FORCE_COLLAPSED_SIDEBAR) return null;
-
   const { theme, setTheme } = useTheme();
+  const { data: appearance } = useAppearanceSettings();
   const [open, setOpen] = useState(false);
   const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const swatches = useMemo(
+    () => [
+      ...THEME_SWATCHES,
+      ...(appearance?.custom_themes ?? [])
+        .filter((preset) => preset.enabled)
+        .sort((a, b) => a.sort_order - b.sort_order)
+        .map((preset) => ({
+          id: preset.id as ThemeType,
+          label: preset.name,
+          color: preset.primary,
+        })),
+    ],
+    [appearance?.custom_themes],
+  );
 
   const cancelClose = () => {
     if (closeTimer.current) {
@@ -99,9 +147,12 @@ export function ThemeSwitcher({ tone }: { tone: AppearanceControlTone }) {
 
   useEffect(() => () => cancelClose(), []);
 
+  if (env.FORCE_COLLAPSED_SIDEBAR || isHideChromeActive()) return null;
+
   return (
     <div
       className="relative"
+      data-compact-guide="theme-switcher"
       onMouseEnter={() => {
         cancelClose();
         setOpen(true);
@@ -121,9 +172,9 @@ export function ThemeSwitcher({ tone }: { tone: AppearanceControlTone }) {
       </Button>
       {open ? (
         <div className="absolute top-full left-1/2 z-50 -translate-x-1/2 pt-2">
-          <div className="relative flex items-center gap-2 rounded-lg border border-black/5 bg-white px-2.5 py-1.5 shadow-lg">
-            <div className="absolute -top-1 left-1/2 size-2 -translate-x-1/2 rotate-45 rounded-[1px] border-t border-l border-black/5 bg-white" />
-            {THEME_SWATCHES.map((swatch) => {
+          <div className="relative flex max-w-64 flex-wrap items-center justify-center gap-2 rounded-lg border border-border bg-popover px-2.5 py-1.5 shadow-lg">
+            <div className="absolute -top-1 left-1/2 size-2 -translate-x-1/2 rotate-45 rounded-[1px] border-t border-l border-border bg-popover" />
+            {swatches.map((swatch) => {
               const active = theme === swatch.id;
               return (
                 <button
@@ -184,13 +235,13 @@ export function LayoutModeSwitcher({
   fallback?: "full" | "compact";
   navigateTo?: string | null;
 }) {
-  if (env.FORCE_COLLAPSED_SIDEBAR) return null;
-
   const [mode, setLayoutMode] = useLayoutMode();
   const navigate = useNavigate();
   const current = mode ?? fallback;
   const TriggerIcon = current === "full" ? PanelLeftIcon : LayoutIcon;
 
+  if (env.FORCE_COLLAPSED_SIDEBAR || isHideChromeActive()) return null;
+
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
@@ -201,6 +252,7 @@ export function LayoutModeSwitcher({
           className={cn("size-8 shrink-0 rounded-sm", triggerToneClass(tone))}
           title="界面模式"
           aria-label="界面模式"
+          data-compact-guide="layout-mode"
         >
           <TriggerIcon className="size-4" />
         </Button>

frontend-web/src/components/workspace/artifacts/artifact-directory.tsx

@@ -0,0 +1,226 @@
+import {
+  ChevronDownIcon,
+  ChevronRightIcon,
+  FolderIcon,
+  FolderOpenIcon,
+  RefreshCwIcon,
+} from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import { artifactPathname, artifactRelativePath } from "@/core/artifacts/listing";
+import { getFileIcon, getFileName } from "@/core/utils/files";
+import { cn } from "@/lib/utils";
+
+type DirectoryNode = {
+  name: string;
+  path: string;
+  directories: DirectoryNode[];
+  files: Array<{ artifact: string; name: string; relativePath: string }>;
+};
+
+function buildDirectoryTree(artifacts: string[]): DirectoryNode {
+  const root: DirectoryNode = {
+    name: "生成文件",
+    path: "",
+    directories: [],
+    files: [],
+  };
+
+  for (const artifact of artifacts) {
+    const relativePath = artifactRelativePath(artifact);
+    const parts = relativePath.split("/").filter(Boolean);
+    if (parts.length === 0) continue;
+
+    let current = root;
+    for (const directoryName of parts.slice(0, -1)) {
+      let child = current.directories.find((node) => node.name === directoryName);
+      if (!child) {
+        child = {
+          name: directoryName,
+          path: current.path ? `${current.path}/${directoryName}` : directoryName,
+          directories: [],
+          files: [],
+        };
+        current.directories.push(child);
+      }
+      current = child;
+    }
+
+    current.files.push({
+      artifact,
+      name: parts.at(-1) ?? getFileName(artifact),
+      relativePath,
+    });
+  }
+
+  const sort = (node: DirectoryNode) => {
+    node.directories.sort((left, right) =>
+      left.name.localeCompare(right.name, "zh-CN"),
+    );
+    node.files.sort((left, right) =>
+      left.name.localeCompare(right.name, "zh-CN"),
+    );
+    node.directories.forEach(sort);
+  };
+  sort(root);
+  return root;
+}
+
+function DirectoryBranch({
+  node,
+  depth,
+  collapsedDirectories,
+  onToggleDirectory,
+  selectedArtifact,
+  onSelect,
+}: {
+  node: DirectoryNode;
+  depth: number;
+  collapsedDirectories: Set<string>;
+  onToggleDirectory: (path: string) => void;
+  selectedArtifact: string | null;
+  onSelect: (artifact: string) => void;
+}) {
+  return (
+    <>
+      {node.directories.map((directory) => {
+        const collapsed = collapsedDirectories.has(directory.path);
+        return (
+          <div key={directory.path}>
+            <button
+              type="button"
+              className="text-muted-foreground hover:bg-muted/70 hover:text-foreground flex h-8 w-full items-center gap-1.5 rounded-md pr-2 text-left text-xs"
+              style={{ paddingLeft: `${8 + depth * 14}px` }}
+              onClick={() => onToggleDirectory(directory.path)}
+              title={directory.path}
+            >
+              {collapsed ? (
+                <ChevronRightIcon className="size-3.5 shrink-0" />
+              ) : (
+                <ChevronDownIcon className="size-3.5 shrink-0" />
+              )}
+              {collapsed ? (
+                <FolderIcon className="size-4 shrink-0 text-amber-500" />
+              ) : (
+                <FolderOpenIcon className="size-4 shrink-0 text-amber-500" />
+              )}
+              <span className="truncate">{directory.name}</span>
+            </button>
+            {!collapsed && (
+              <DirectoryBranch
+                node={directory}
+                depth={depth + 1}
+                collapsedDirectories={collapsedDirectories}
+                onToggleDirectory={onToggleDirectory}
+                selectedArtifact={selectedArtifact}
+                onSelect={onSelect}
+              />
+            )}
+          </div>
+        );
+      })}
+      {node.files.map((file) => {
+        const selected =
+          !!selectedArtifact &&
+          artifactPathname(selectedArtifact) === artifactPathname(file.artifact);
+        return (
+          <button
+            key={file.relativePath}
+            type="button"
+            className={cn(
+              "hover:bg-muted/70 flex min-h-8 w-full items-center gap-2 rounded-md py-1 pr-2 text-left text-xs",
+              selected
+                ? "bg-primary/10 text-primary font-medium"
+                : "text-foreground/85",
+            )}
+            style={{ paddingLeft: `${27 + depth * 14}px` }}
+            onClick={() => onSelect(file.artifact)}
+            title={file.relativePath}
+            aria-current={selected ? "page" : undefined}
+          >
+            <span className="shrink-0">{getFileIcon(file.artifact, "size-4")}</span>
+            <span className="truncate">{file.name}</span>
+          </button>
+        );
+      })}
+    </>
+  );
+}
+
+export function ArtifactDirectory({
+  className,
+  artifacts,
+  selectedArtifact,
+  onSelect,
+  onRefresh,
+  refreshing = false,
+}: {
+  className?: string;
+  artifacts: string[];
+  selectedArtifact: string | null;
+  onSelect: (artifact: string) => void;
+  onRefresh?: () => void;
+  refreshing?: boolean;
+}) {
+  const tree = useMemo(() => buildDirectoryTree(artifacts), [artifacts]);
+  const [collapsedDirectories, setCollapsedDirectories] = useState<Set<string>>(
+    () => new Set(),
+  );
+
+  const toggleDirectory = (path: string) => {
+    setCollapsedDirectories((current) => {
+      const next = new Set(current);
+      if (next.has(path)) next.delete(path);
+      else next.add(path);
+      return next;
+    });
+  };
+
+  return (
+    <aside
+      className={cn(
+        "bg-muted/20 flex min-h-0 w-48 shrink-0 flex-col border-r xl:w-56",
+        className,
+      )}
+      aria-label="生成文件目录"
+    >
+      <div className="flex h-12 shrink-0 items-center justify-between gap-2 border-b px-3">
+        <div className="min-w-0">
+          <div className="truncate text-sm font-semibold">生成文件</div>
+          <div className="text-muted-foreground text-[11px]">{artifacts.length} 个文件</div>
+        </div>
+        {onRefresh && (
+          <Button
+            type="button"
+            size="icon-sm"
+            variant="ghost"
+            className="size-7 shrink-0"
+            onClick={onRefresh}
+            disabled={refreshing}
+            title="刷新文件目录"
+            aria-label="刷新文件目录"
+          >
+            <RefreshCwIcon className={cn("size-3.5", refreshing && "animate-spin")} />
+          </Button>
+        )}
+      </div>
+      <div className="min-h-0 flex-1 overflow-y-auto p-2">
+        {artifacts.length > 0 ? (
+          <DirectoryBranch
+            node={tree}
+            depth={0}
+            collapsedDirectories={collapsedDirectories}
+            onToggleDirectory={toggleDirectory}
+            selectedArtifact={selectedArtifact}
+            onSelect={onSelect}
+          />
+        ) : (
+          <div className="text-muted-foreground px-2 py-8 text-center text-xs leading-5">
+            生成的文件会显示在这里
+          </div>
+        )}
+      </div>
+    </aside>
+  );
+}

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

@@ -1,5 +1,5 @@
 import { DownloadIcon, LoaderIcon, PackageIcon } from "lucide-react";
-import { useCallback, useState } from "react";
+import { useCallback, useState, type ReactNode } from "react";
 import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
@@ -23,28 +23,40 @@ import { useThread } from "../messages/context";
 import { useArtifacts } from "./context";
 import { SkillInstallDialog } from "./skill-install-dialog";
 
-export function ArtifactFileList({
-  className,
-  files,
-  threadId,
-}: {
-  className?: string;
-  files: string[];
-  threadId: string;
-}) {
+export function ArtifactFileList({
+  className,
+  files,
+  threadId,
+  onOpenArtifact,
+  onDownloadArtifact,
+  fileDescriptions,
+}: {
+  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>;
+  /** Optional per-file secondary text, such as the report structure used. */
+  fileDescriptions?: Record<string, ReactNode>;
+}) {
   const { t } = useI18n();
   const { isMock, publicShareCode } = useThread();
   const { select: selectArtifact, setOpen } = useArtifacts();
   const [installFile, setInstallFile] = useState<string | null>(null);
   const [downloadingFile, setDownloadingFile] = useState<string | null>(null);
 
-  const handleClick = useCallback(
-    (filepath: string) => {
-      selectArtifact(filepath);
-      setOpen(true);
-    },
-    [selectArtifact, setOpen],
-  );
+  const handleClick = useCallback(
+    (filepath: string) => {
+      if (onOpenArtifact) {
+        onOpenArtifact(filepath);
+        return;
+      }
+      selectArtifact(filepath);
+      setOpen(true);
+    },
+    [onOpenArtifact, selectArtifact, setOpen],
+  );
 
   const handleInstallSkill = useCallback(
     (e: React.MouseEvent, filepath: string) => {
@@ -59,10 +71,14 @@ export function ArtifactFileList({
     async (e: React.MouseEvent, filepath: string) => {
       e.stopPropagation();
       e.preventDefault();
-      if (downloadingFile) return;
-      setDownloadingFile(filepath);
-      try {
-        await downloadArtifactFile({ filepath, threadId, isMock, publicShareCode });
+      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(
@@ -72,7 +88,7 @@ export function ArtifactFileList({
         setDownloadingFile(null);
       }
     },
-    [threadId, isMock, publicShareCode, downloadingFile],
+    [threadId, isMock, publicShareCode, downloadingFile, onDownloadArtifact],
   );
 
   return (
@@ -89,10 +105,10 @@ export function ArtifactFileList({
               <div className="absolute top-2 -left-0.5">
                 {getFileIcon(file, "size-6")}
               </div>
-            </CardTitle>
-            <CardDescription className="min-w-0 pl-8 text-xs">
-              {getFileExtensionDisplayName(file)} file
-            </CardDescription>
+            </CardTitle>
+            <CardDescription className="min-w-0 pl-8 text-xs">
+              {fileDescriptions?.[file] ?? `${getFileExtensionDisplayName(file)} file`}
+            </CardDescription>
             <CardAction className="row-span-1 self-center">
               {file.endsWith(".skill") && (
                 <Button

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

@@ -1,103 +1,247 @@
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useState,
-  type ReactNode,
-} from "react";
-
-import { useSidebarSafe } from "@/components/ui/sidebar";
-import { env } from "@/env";
-
-export interface ArtifactsContextType {
-  artifacts: string[];
-  setArtifacts: (artifacts: string[]) => void;
-
-  selectedArtifact: string | null;
-  autoSelect: boolean;
-  select: (artifact: string, autoSelect?: boolean) => void;
-  deselect: () => void;
-
-  open: boolean;
-  autoOpen: boolean;
-  setOpen: (open: boolean) => void;
-}
-
-const ArtifactsContext = createContext<ArtifactsContextType | undefined>(
-  undefined,
-);
-
-interface ArtifactsProviderProps {
-  children: ReactNode;
-}
-
-export function ArtifactsProvider({ children }: ArtifactsProviderProps) {
-  const [artifacts, setArtifactsState] = useState<string[]>([]);
-  const setArtifacts = useCallback((next: string[]) => {
-    setArtifactsState(Array.isArray(next) ? next : []);
-  }, []);
-  const [selectedArtifact, setSelectedArtifact] = useState<string | null>(null);
-  const [autoSelect, setAutoSelect] = useState(true);
-  const [open, setOpen] = useState(
-    env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true",
-  );
-  const [autoOpen, setAutoOpen] = useState(true);
-  const sidebar = useSidebarSafe();
-
-  const select = useCallback(
-    (artifact: string, autoSelect = false) => {
-      setSelectedArtifact(artifact);
-      if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY !== "true") {
-        sidebar?.setOpen(false);
-      }
-      if (!autoSelect) {
-        setAutoSelect(false);
-      }
-    },
-    [sidebar, setSelectedArtifact, setAutoSelect],
-  );
-
-  const deselect = useCallback(() => {
-    setSelectedArtifact(null);
-    setAutoSelect(true);
-    setOpen(false);
-  }, []);
-
-  const value: ArtifactsContextType = {
-    artifacts,
-    setArtifacts,
-
-    open,
-    autoOpen,
-    autoSelect,
-    setOpen: (isOpen: boolean) => {
-      if (!isOpen && autoOpen) {
-        setAutoOpen(false);
-        setAutoSelect(false);
-      }
-      setOpen(isOpen);
-    },
-
-    selectedArtifact,
-    select,
-    deselect,
-  };
-
-  return (
-    <ArtifactsContext.Provider value={value}>
-      {children}
-    </ArtifactsContext.Provider>
-  );
-}
-
-export function useArtifacts() {
-  const context = useContext(ArtifactsContext);
-  if (context === undefined) {
-    throw new Error("useArtifacts must be used within an ArtifactsProvider");
-  }
-  return context;
-}
-
-export function useArtifactsOptional(): ArtifactsContextType | null {
-  return useContext(ArtifactsContext) ?? null;
-}
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+
+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;
+  autoOpen: boolean;
+  setOpen: (open: boolean) => void;
+  /**
+   * 流式写文件自动开沙箱的两阶段标记：openStreamedArtifact 先收起两侧侧栏
+   * （阶段一），等收起布局落定后再真正翻转 open（阶段二）。两阶段之间为
+   * true —— 右侧智能体信息面板据此提前收起，避免与沙箱展开同帧叠加造成卡顿。
+   */
+  preOpen: boolean;
+}
+
+const ArtifactsContext = createContext<ArtifactsContextType | undefined>(
+  undefined,
+);
+
+interface ArtifactsProviderProps {
+  children: ReactNode;
+}
+
+// 流式写文件自动开沙箱的分步延迟：t=0 收起左侧聊天记录侧栏，延迟
+// STREAMED_PREOPEN_DELAY_MS 后再收右侧智能体信息面板（两次收起错开、
+// 不做「左边收完再收右边」的判断，只给固定延迟，避免收起瞬间同帧叠加
+// 卡顿），到 STREAMED_OPEN_DELAY_MS（右侧 300ms 收起动画结束）才展开沙箱。
+const STREAMED_PREOPEN_DELAY_MS = 200;
+const STREAMED_OPEN_DELAY_MS = 500;
+
+export function ArtifactsProvider({ children }: ArtifactsProviderProps) {
+  const [artifacts, setArtifactsState] = useState<string[]>([]);
+  const setArtifacts = useCallback((next: string[]) => {
+    const normalized = Array.isArray(next) ? next : [];
+    setArtifactsState((previous) =>
+      previous.length === normalized.length &&
+      previous.every((artifact, index) => artifact === normalized[index])
+        ? previous
+        : normalized,
+    );
+  }, []);
+  const [selectedArtifact, setSelectedArtifact] = useState<string | null>(null);
+  const [selectedArtifactKey, setSelectedArtifactKey] = useState<string | null>(null);
+  const [autoSelect, setAutoSelect] = useState(true);
+  const [open, setOpenState] = useState(
+    env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true",
+  );
+  const [preOpen, setPreOpen] = useState(false);
+  const [autoOpen, setAutoOpen] = useState(true);
+  const suppressedAutoOpenKeyRef = useRef<string | null>(null);
+  // 供稳定的 setOpen 回调同步读取。写文件流会高频调用 select/setOpen，避免每次
+  // Context 状态变化都重建 setter 并触发依赖它的布局 effect。
+  const selectedArtifactKeyRef = useRef<string | null>(selectedArtifactKey);
+  const autoOpenRef = useRef(autoOpen);
+  const openStateRef = useRef(open);
+  const preOpenTimerRef = useRef<number | null>(null);
+  const openTimerRef = useRef<number | null>(null);
+  const sidebar = useSidebarSafe();
+
+  const applyOpen = useCallback((next: boolean) => {
+    openStateRef.current = next;
+    setOpenState((previous) => (previous === next ? previous : next));
+  }, []);
+
+  // 取消尚未触发的分步自动开沙箱（用户手动关闭 / 切换会话时）。
+  const cancelPendingStreamedOpen = useCallback(() => {
+    if (preOpenTimerRef.current !== null) {
+      window.clearTimeout(preOpenTimerRef.current);
+      preOpenTimerRef.current = null;
+    }
+    if (openTimerRef.current !== null) {
+      window.clearTimeout(openTimerRef.current);
+      openTimerRef.current = null;
+    }
+    setPreOpen(false);
+  }, []);
+
+  useEffect(
+    () => () => {
+      if (preOpenTimerRef.current !== null) {
+        window.clearTimeout(preOpenTimerRef.current);
+        preOpenTimerRef.current = null;
+      }
+      if (openTimerRef.current !== null) {
+        window.clearTimeout(openTimerRef.current);
+        openTimerRef.current = null;
+      }
+    },
+    [],
+  );
+
+  const select = useCallback(
+    (artifact: string, autoSelect = false) => {
+      const previewKey = artifactPreviewKey(artifact);
+      selectedArtifactKeyRef.current = previewKey;
+      setSelectedArtifact((previous) => (previous === artifact ? previous : artifact));
+      setSelectedArtifactKey((previous) => (previous === previewKey ? previous : previewKey));
+      if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY !== "true") {
+        sidebar?.setOpen(false);
+      }
+      if (!autoSelect) {
+        setAutoSelect((previous) => (previous ? false : previous));
+      }
+    },
+    [sidebar],
+  );
+
+  const openStreamedArtifact = useCallback(
+    (artifact: string, previewKey: string) => {
+      if (suppressedAutoOpenKeyRef.current === previewKey) {
+        return false;
+      }
+      selectedArtifactKeyRef.current = previewKey;
+      autoOpenRef.current = true;
+      setSelectedArtifact((previous) => (previous === artifact ? previous : artifact));
+      setSelectedArtifactKey((previous) => (previous === previewKey ? previous : previewKey));
+      setAutoSelect((previous) => (previous ? previous : true));
+      setAutoOpen((previous) => (previous ? previous : true));
+      // 阶段一（t=0）：立即收起左侧聊天记录侧栏。
+      if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY !== "true") {
+        sidebar?.setOpen(false);
+      }
+      if (openStateRef.current) {
+        // 沙箱已展开（如连续写多个文件）：只需切换选中文件，无需分步。
+        cancelPendingStreamedOpen();
+        return true;
+      }
+      if (openTimerRef.current === null) {
+        // 阶段二（t=+200ms）：延迟固定时长再置 preOpen，右侧智能体信息
+        // 面板此时才开始收起 —— 与左侧错开，避免两次收起同帧叠加卡顿。
+        preOpenTimerRef.current = window.setTimeout(() => {
+          preOpenTimerRef.current = null;
+          setPreOpen(true);
+        }, STREAMED_PREOPEN_DELAY_MS);
+        // 阶段三（t=+500ms，右侧 300ms 收起动画结束）：翻转 open 展开
+        // 沙箱，把「聊天列变窄 + 沙箱内容挂载」与侧栏收起彻底分帧。
+        openTimerRef.current = window.setTimeout(() => {
+          openTimerRef.current = null;
+          applyOpen(true);
+          setPreOpen(false);
+        }, STREAMED_OPEN_DELAY_MS);
+      }
+      return true;
+    },
+    [applyOpen, cancelPendingStreamedOpen, sidebar],
+  );
+
+  const deselect = useCallback(() => {
+    selectedArtifactKeyRef.current = null;
+    setSelectedArtifact((previous) => (previous === null ? previous : null));
+    setSelectedArtifactKey((previous) => (previous === null ? previous : null));
+    setAutoSelect((previous) => (previous ? previous : true));
+    cancelPendingStreamedOpen();
+    applyOpen(false);
+    suppressedAutoOpenKeyRef.current = null;
+  }, [applyOpen, cancelPendingStreamedOpen]);
+
+  const setOpen = useCallback(
+    (isOpen: boolean) => {
+      if (!isOpen) {
+        // 两阶段等待期间用户手动关闭：取消尚未触发的自动展开。
+        cancelPendingStreamedOpen();
+        if (autoOpenRef.current) {
+          autoOpenRef.current = false;
+          setAutoOpen((previous) => (previous ? false : previous));
+          setAutoSelect((previous) => (previous ? false : previous));
+        }
+        suppressedAutoOpenKeyRef.current = selectedArtifactKeyRef.current;
+      }
+      applyOpen(isOpen);
+    },
+    [applyOpen, cancelPendingStreamedOpen],
+  );
+
+  const value: ArtifactsContextType = {
+    artifacts,
+    setArtifacts,
+
+    open,
+    preOpen,
+    autoOpen,
+    autoSelect,
+    setOpen,
+
+    selectedArtifact,
+    selectedArtifactKey,
+    select,
+    openStreamedArtifact,
+    deselect,
+  };
+
+  return (
+    <ArtifactsContext.Provider value={value}>
+      {children}
+    </ArtifactsContext.Provider>
+  );
+}
+
+export function useArtifacts() {
+  const context = useContext(ArtifactsContext);
+  if (context === undefined) {
+    throw new Error("useArtifacts must be used within an ArtifactsProvider");
+  }
+  return context;
+}
+
+export function useArtifactsOptional(): ArtifactsContextType | null {
+  return useContext(ArtifactsContext) ?? null;
+}

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

@@ -0,0 +1,344 @@
+"use client";
+
+import { FilePenLineIcon, ImagePlusIcon, SparklesIcon } from "lucide-react";
+import { useEffect, useMemo, 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 { Switch } from "@/components/ui/switch";
+import { ModelNameSelect } from "@/components/workspace/model-name-select";
+import type { DocumentRewriteStyle } from "@/open-canvas/api/rewrite";
+import { useReportStructures, REPORT_STRUCTURE_MODE_OPTIONS, normalizeReportStructureMode, type ReportStructureMode } from "@/strategy-components/api/report-structures";
+
+const KEEP_CURRENT_REPORT_STRUCTURE = "__keep_current_report_structure__";
+const DEFAULT_REWRITE_INSTRUCTION = "统一表达风格，减少重复内容，改善段落衔接；不新增原文没有依据的事实。";
+const DEFAULT_GENERATE_INSTRUCTION = "基于已选资料按所选报告结构生成一篇新的完整报告；保持事实可核验，不补充没有依据的信息。";
+
+export interface DocumentRewriteDialogInput {
+  instruction: string;
+  style: DocumentRewriteStyle;
+  modelName: string | null;
+  reportOutline: string;
+  structureMode: "fixed" | "adaptive";
+  generateImages: boolean;
+  maxGeneratedImages: number;
+}
+
+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,
+  imageGenerationAvailable = false,
+  maxGeneratedImages = 4,
+  initialReportOutline,
+  operationLabel,
+  operationDescription,
+  submitLabel,
+  operation,
+  onStart,
+  onRewriteOriginal,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  fileName: string;
+  charCount: number;
+  imageGenerationAvailable?: boolean;
+  maxGeneratedImages?: number;
+  /** A saved report structure selected before the dialog was opened. */
+  initialReportOutline?: string;
+  /** Optional copy for flows that create a new document instead of replacing one. */
+  operationLabel?: string;
+  operationDescription?: string;
+  submitLabel?: string;
+  /** ``generate`` creates an independent report; ``rewrite`` edits this report in place. */
+  operation?: "rewrite" | "generate";
+  onStart: (input: DocumentRewriteDialogInput) => void;
+  /** Optional secondary action for generation flows that rewrites the source report in place. */
+  onRewriteOriginal?: (input: DocumentRewriteDialogInput) => void;
+}) {
+  const isNewReportGeneration = operation === "generate";
+  const [instruction, setInstruction] = useState(DEFAULT_REWRITE_INSTRUCTION);
+  const [style, setStyle] = useState<DocumentRewriteStyle>("formal_analysis");
+  const [modelName, setModelName] = useState<string | null>(null);
+  const [reportStructureId, setReportStructureId] = useState(KEEP_CURRENT_REPORT_STRUCTURE);
+  const [structureMode, setStructureMode] = useState<ReportStructureMode>("adaptive");
+  const [generateImages, setGenerateImages] = useState(false);
+  const [imageCount, setImageCount] = useState("2");
+  const reportStructuresQuery = useReportStructures({ status: "enabled" });
+  const reportStructures = reportStructuresQuery.data ?? [];
+  const selectedReportStructure = reportStructures.find((item) => item.id === reportStructureId);
+  const initialReportStructureId = useMemo(() => {
+    const outline = initialReportOutline?.trim();
+    if (!outline) return null;
+    return reportStructures.find((item) => item.content.trim() === outline)?.id ?? null;
+  }, [initialReportOutline, reportStructures]);
+
+  useEffect(() => {
+    if (!open) return;
+    setInstruction(isNewReportGeneration ? DEFAULT_GENERATE_INSTRUCTION : DEFAULT_REWRITE_INSTRUCTION);
+    setStyle("formal_analysis");
+    setModelName(null);
+    setReportStructureId(KEEP_CURRENT_REPORT_STRUCTURE);
+    setStructureMode("adaptive");
+    setGenerateImages(false);
+    setImageCount("2");
+  }, [isNewReportGeneration, open]);
+
+  // The structures query may resolve after the dialog opens. Only seed the
+  // value while the user still has the default selection, so a manual choice
+  // is never overwritten by a query refresh.
+  useEffect(() => {
+    if (!open || !initialReportStructureId) return;
+    setReportStructureId((current) => (
+      current === KEEP_CURRENT_REPORT_STRUCTURE ? initialReportStructureId : current
+    ));
+  }, [initialReportStructureId, open]);
+
+  useEffect(() => {
+    if (!selectedReportStructure) return;
+    setStructureMode(selectedReportStructure.structureMode);
+  }, [selectedReportStructure?.id, selectedReportStructure?.structureMode]);
+
+  const selectedStyle = STYLE_OPTIONS.find((item) => item.value === style);
+  const canStart = instruction.trim().length > 0;
+  const startWith = (handler: (input: DocumentRewriteDialogInput) => void) => {
+    if (!canStart) return;
+    handler({
+      instruction: instruction.trim(),
+      style,
+      modelName,
+      reportOutline: selectedReportStructure?.content ?? "",
+      structureMode,
+      generateImages,
+      maxGeneratedImages: Math.min(
+        Math.max(Number(imageCount) || 1, 1),
+        Math.max(Math.min(maxGeneratedImages, 4), 1),
+      ),
+    });
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-2xl">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <SparklesIcon className="size-5 text-primary" />
+            {operationLabel ?? "AI 全文改写"}
+          </DialogTitle>
+          <DialogDescription>
+            {operationDescription ?? "将以当前文件快照生成临时草稿。校验通过前不会覆盖原 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">
+            {isNewReportGeneration ? "来源报告" : "原文"}约 {charCount.toLocaleString()} 字
+          </div>
+        </div>
+
+        <label className="grid gap-2 text-sm font-medium">
+          {isNewReportGeneration ? "生成要求" : "改写要求"}
+          <Textarea
+            value={instruction}
+            onChange={(event) => setInstruction(event.target.value)}
+            placeholder={isNewReportGeneration
+              ? "例如：突出政策影响，并按所选结构组织章节；仅使用已选资料。"
+              : "例如：统一为正式行业分析语气，减少重复，不新增外部事实。"}
+            rows={4}
+          />
+        </label>
+
+        <div className="grid gap-4 sm:grid-cols-2">
+          <label className="grid gap-2 text-sm font-medium">
+            {isNewReportGeneration ? "报告风格" : "改写风格"}
+            <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">
+            报告结构
+            <Select value={reportStructureId} onValueChange={setReportStructureId}>
+              <SelectTrigger aria-label="报告结构">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value={KEEP_CURRENT_REPORT_STRUCTURE}>沿用当前结构</SelectItem>
+                {reportStructuresQuery.isLoading && (
+                  <SelectItem value="__report_structures_loading__" disabled>
+                    正在加载结构…
+                  </SelectItem>
+                )}
+                {reportStructuresQuery.isError && (
+                  <SelectItem value="__report_structures_error__" disabled>
+                    报告结构库加载失败
+                  </SelectItem>
+                )}
+                {reportStructures.map((structure) => (
+                  <SelectItem key={structure.id} value={structure.id}>
+                    {structure.title}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            <span className="text-muted-foreground text-xs">
+              {selectedReportStructure?.name || "默认保留原文的章节安排。"}
+            </span>
+          </label>
+
+          <label className="grid gap-2 text-sm font-medium">
+            结构约束
+            <Select
+              value={structureMode}
+              onValueChange={(value) => setStructureMode(normalizeReportStructureMode(value))}
+            >
+              <SelectTrigger aria-label="结构约束">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {REPORT_STRUCTURE_MODE_OPTIONS.map((option) => (
+                  <SelectItem key={option.value} value={option.value}>
+                    {option.label}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            <span className="text-muted-foreground text-xs">
+              {REPORT_STRUCTURE_MODE_OPTIONS.find((option) => option.value === structureMode)?.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">
+              仅影响本次{isNewReportGeneration ? "新报告生成" : "全文改写"}。
+            </span>
+          </label>
+        </div>
+
+        {imageGenerationAvailable && (
+          <div className="rounded-lg border bg-muted/20 p-3">
+            <div className="flex items-start justify-between gap-4">
+              <label className="flex min-w-0 cursor-pointer items-start gap-3" htmlFor="document-rewrite-images">
+                <span className="bg-primary/10 text-primary mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-full">
+                  <ImagePlusIcon className="size-4" />
+                </span>
+                <span className="grid gap-0.5">
+                  <span className="text-sm font-medium">
+                    {isNewReportGeneration ? "为新报告补充配图" : "改写后补充配图"}
+                  </span>
+                  <span className="text-muted-foreground text-xs leading-5">
+                    根据章节生成并保存为当前沙箱的本地图片，不使用外部图片链接。
+                  </span>
+                </span>
+              </label>
+              <Switch
+                aria-label={isNewReportGeneration ? "为新报告补充配图" : "改写后补充配图"}
+                checked={generateImages}
+                id="document-rewrite-images"
+                onCheckedChange={setGenerateImages}
+              />
+            </div>
+            {generateImages && (
+              <div className="mt-3 flex items-center justify-between gap-3 border-t pt-3">
+                <span className="text-muted-foreground text-xs">每次会额外消耗图片模型额度</span>
+                <label className="flex items-center gap-2 text-sm">
+                  配图数量
+                  <Select value={imageCount} onValueChange={setImageCount}>
+                    <SelectTrigger className="h-8 w-20 text-xs">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {Array.from({ length: Math.min(Math.max(maxGeneratedImages, 1), 4) }, (_, index) => index + 1).map((count) => (
+                        <SelectItem key={count} value={String(count)}>{count} 张</SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </label>
+              </div>
+            )}
+          </div>
+        )}
+
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>
+            取消
+          </Button>
+          {isNewReportGeneration && onRewriteOriginal && (
+            <Button
+              variant="outline"
+              disabled={!canStart}
+              onClick={() => startWith(onRewriteOriginal)}
+            >
+              <FilePenLineIcon />
+              改写原文
+            </Button>
+          )}
+          <Button
+            disabled={!canStart}
+            onClick={() => startWith(onStart)}
+          >
+            <SparklesIcon />
+            {submitLabel ?? "开始改写"}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

frontend-web/src/components/workspace/artifacts/index.ts

@@ -1,4 +1,5 @@
-export * from "./artifact-file-detail";
-export * from "./artifact-file-list";
+export * from "./artifact-file-detail";
+export * from "./artifact-directory";
+export * from "./artifact-file-list";
 export * from "./artifact-trigger";
 export * from "./context";

frontend-web/src/components/workspace/artifacts/spreadsheet-preview.tsx

@@ -117,7 +117,7 @@ export function SpreadsheetPreview({
                 {Array.from({ length: columnCount }, (_, columnIndex) => (
                   <th
                     key={columnIndex}
-                    className="border-border bg-muted/60 text-foreground sticky top-0 border px-3 py-1.5 text-left font-medium whitespace-pre-wrap"
+                    className="border-border bg-muted/60 text-foreground border px-3 py-1.5 text-left font-semibold whitespace-pre-wrap"
                   >
                     {desensitize(headerRow?.[columnIndex] ?? "")}
                   </th>

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

@@ -1,4 +1,5 @@
 import type { Message } from "@langchain/langgraph-sdk";
+import { useQuery } from "@tanstack/react-query";
 import { FilesIcon, XIcon } from "lucide-react";
 import { usePathname } from "next/navigation";
 import { useEffect, useMemo, useRef, useState } from "react";
@@ -13,8 +14,15 @@ import {
 } from "@/components/ui/resizable";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { apiFetch } from "@/core/api";
+import {
+  listThreadArtifacts,
+  mergeArtifactPaths,
+} from "@/core/artifacts/listing";
 import { getBackendBaseURL } from "@/core/config";
 import { isThreadRagModeLocked, useLocalSettings } from "@/core/settings";
+import { useCitationDisplaySettings } from "@/core/system-settings/hooks";
+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 {
@@ -30,6 +38,7 @@ import { cn } from "@/lib/utils";
 
 import {
   ArtifactFileDetail,
+  ArtifactDirectory,
   ArtifactFileList,
   useArtifacts,
 } from "../artifacts";
@@ -38,6 +47,7 @@ import { SkillDisplaySources } from "../skill-display-sources";
 
 const CLOSE_MODE = { chat: 100, artifacts: 0 };
 const OPEN_MODE = { chat: 60, artifacts: 40 };
+const DIRECTORY_OPEN_MODE = { chat: 48, artifacts: 52 };
 const SHOW_REFERENCE_EVENT = "workspace:show-reference";
 
 type BackendReferenceSource = Parameters<typeof SkillDisplaySources>[0]["sources"][number];
@@ -76,7 +86,11 @@ const ChatBox: React.FC<{
   threadId,
   disableArtifacts = false,
 }) => {
-  const { thread } = useThread();
+  const {
+    isMock,
+    thread,
+    knowledgeReferencesEnabled = false,
+  } = useThread();
   const pathname = usePathname();
   const threadIdRef = useRef(threadId);
   const artifactsCountRef = useRef(0);
@@ -90,10 +104,77 @@ const ChatBox: React.FC<{
   const [pinnedReferenceId, setPinnedReferenceId] = useState<string | null>(null);
   const [backendReferenceBatches, setBackendReferenceBatches] = useState<BackendReferenceBatch[]>([]);
   const [settings] = useLocalSettings();
+  const artifactDirectoryModeEnabled =
+    settings.display.artifactDirectoryModeEnabled ?? false;
+  const { data: citationDisplay } = useCitationDisplaySettings();
+  const referenceModeEntryEnabled =
+    citationDisplay?.reference_mode_enabled ?? false;
   const ragModeEnabled =
-    settings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
+    (referenceModeEntryEnabled && settings.display.ragModeEnabled) ||
+    isThreadRagModeLocked(threadId) ||
+    knowledgeReferencesEnabled;
+  // 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 && !!threadId && threadId !== "new";
   const { skills } = useSkills();
 
+  const canScanArtifactDirectory =
+    artifactDirectoryModeEnabled &&
+    !disableArtifacts &&
+    !isMock &&
+    !!threadId &&
+    threadId !== "new";
+  const artifactListingQuery = useQuery({
+    queryKey: ["artifact-directory", threadId],
+    queryFn: ({ signal }) => listThreadArtifacts(threadId, signal),
+    enabled: canScanArtifactDirectory,
+    refetchInterval: thread.isLoading ? 1_500 : false,
+    retry: false,
+  });
+  const checkpointArtifacts = useMemo(
+    () => (disableArtifacts ? [] : (thread.values.artifacts ?? [])),
+    [disableArtifacts, thread.values.artifacts],
+  );
+  const checkpointArtifactSignature = checkpointArtifacts.join("\n");
+  const availableArtifacts = useMemo(
+    () =>
+      artifactDirectoryModeEnabled
+        ? mergeArtifactPaths(
+            checkpointArtifacts,
+            (artifactListingQuery.data?.files ?? []).map((file) => file.path),
+          )
+        : checkpointArtifacts,
+    [
+      artifactDirectoryModeEnabled,
+      artifactListingQuery.data?.files,
+      checkpointArtifacts,
+    ],
+  );
+
+  useEffect(() => {
+    if (!canScanArtifactDirectory || thread.isLoading) return;
+    // Run once after streaming settles as well as when checkpoint artifacts
+    // change, so files written without present_files are not missed by the
+    // last polling tick.
+    void artifactListingQuery.refetch();
+  }, [
+    artifactListingQuery.refetch,
+    canScanArtifactDirectory,
+    checkpointArtifactSignature,
+    thread.isLoading,
+  ]);
+
   const {
     artifacts,
     open: artifactsOpen,
@@ -102,15 +183,16 @@ const ChatBox: React.FC<{
     select: selectArtifact,
     deselect,
     selectedArtifact,
+    selectedArtifactKey,
   } = useArtifacts();
 
   const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true);
   const skillDisplayMap = useMemo(
-    () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
-    [ragModeEnabled, skills],
+    () => (referencesEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [referencesEnabled, skills],
   );
   const fallbackReferenceBatches = useMemo(() => {
-    if (!ragModeEnabled) {
+    if (!referencesEnabled) {
       return [];
     }
     return buildTurnReferenceBatches(
@@ -118,9 +200,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 +238,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 +254,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 +296,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 +314,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 +323,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);
@@ -266,7 +367,8 @@ const ChatBox: React.FC<{
     };
   }, []);
   useEffect(() => {
-    if (threadIdRef.current !== threadId) {
+    const threadChanged = threadIdRef.current !== threadId;
+    if (threadChanged) {
       threadIdRef.current = threadId;
       artifactsCountRef.current = 0;
       deselect();
@@ -280,15 +382,21 @@ const ChatBox: React.FC<{
     }
 
     // Update artifacts from the current thread
-    const nextArtifacts = disableArtifacts ? [] : (thread.values.artifacts ?? []);
+    const nextArtifacts = availableArtifacts;
     const hadArtifacts = artifactsCountRef.current > 0;
     const hasNewArtifact = nextArtifacts.length > artifactsCountRef.current;
     artifactsCountRef.current = nextArtifacts.length;
-    setArtifacts(nextArtifacts);
+    const artifactsChanged =
+      artifacts.length !== nextArtifacts.length ||
+      artifacts.some((artifact, index) => artifact !== nextArtifacts[index]);
+    if (artifactsChanged) {
+      setArtifacts(nextArtifacts);
+    }
     if (
       !disableArtifacts &&
-      (hasNewArtifact || (!hadArtifacts && nextArtifacts.length > 0)) &&
-      !selectedArtifact
+      nextArtifacts.length > 0 &&
+      ((artifactDirectoryModeEnabled && threadChanged) ||
+        ((hasNewArtifact || !hadArtifacts) && !selectedArtifact))
     ) {
       selectArtifact(nextArtifacts[nextArtifacts.length - 1]!);
       setArtifactsOpen(true);
@@ -315,15 +423,41 @@ const ChatBox: React.FC<{
     }
   }, [
     threadId,
+    artifactDirectoryModeEnabled,
     autoSelectFirstArtifact,
     deselect,
     selectArtifact,
     selectedArtifact,
+    artifacts,
     setArtifacts,
-    thread.values.artifacts,
+    availableArtifacts,
     disableArtifacts,
   ]);
 
+  const directoryModeWasEnabledRef = useRef(artifactDirectoryModeEnabled);
+  useEffect(() => {
+    const wasEnabled = directoryModeWasEnabledRef.current;
+    directoryModeWasEnabledRef.current = artifactDirectoryModeEnabled;
+    if (
+      wasEnabled ||
+      !artifactDirectoryModeEnabled ||
+      availableArtifacts.length === 0
+    ) {
+      return;
+    }
+    if (!selectedArtifact) {
+      selectArtifact(availableArtifacts[availableArtifacts.length - 1]!);
+    }
+    setArtifactsOpen(true);
+    setSideTab("document");
+  }, [
+    artifactDirectoryModeEnabled,
+    availableArtifacts,
+    selectArtifact,
+    selectedArtifact,
+    setArtifactsOpen,
+  ]);
+
   const artifactPanelOpen = useMemo(() => {
     if (disableArtifacts) {
       return false;
@@ -334,7 +468,10 @@ const ChatBox: React.FC<{
     return artifactsOpen;
   }, [artifactsOpen, artifacts, disableArtifacts]);
   const sidePanelOpen = artifactPanelOpen || (hasCitationReferences && referencesOpen);
-  const showTabs = !!selectedArtifact && hasCitationReferences;
+  const showTabs =
+    hasCitationReferences &&
+    (!!selectedArtifact ||
+      (artifactDirectoryModeEnabled && artifacts.length > 0));
 
   useEffect(() => {
     if (selectedArtifact) {
@@ -354,12 +491,103 @@ const ChatBox: React.FC<{
   useEffect(() => {
     if (layoutRef.current) {
       if (sidePanelOpen) {
-        layoutRef.current.setLayout(OPEN_MODE);
+        layoutRef.current.setLayout(
+          artifactDirectoryModeEnabled && artifactPanelOpen
+            ? DIRECTORY_OPEN_MODE
+            : OPEN_MODE,
+        );
       } else {
         layoutRef.current.setLayout(CLOSE_MODE);
       }
     }
-  }, [sidePanelOpen]);
+  }, [artifactDirectoryModeEnabled, artifactPanelOpen, sidePanelOpen]);
+
+  const artifactDocumentPanel = artifactDirectoryModeEnabled ? (
+    <div className="flex size-full min-w-0 overflow-hidden rounded-lg border">
+      <ArtifactDirectory
+        artifacts={artifacts}
+        selectedArtifact={selectedArtifact}
+        onSelect={(artifact) => {
+          selectArtifact(artifact);
+          setArtifactsOpen(true);
+        }}
+        onRefresh={
+          canScanArtifactDirectory
+            ? () => void artifactListingQuery.refetch()
+            : undefined
+        }
+        refreshing={artifactListingQuery.isFetching}
+      />
+      <div className="relative min-w-0 flex-1 overflow-hidden">
+        {selectedArtifact ? (
+          <ArtifactFileDetail
+            key={selectedArtifactKey ?? selectedArtifact}
+            className="size-full"
+            filepath={selectedArtifact}
+            threadId={threadId}
+            allowVirtualMarkdownEdit
+          />
+        ) : (
+          <>
+            <div className="absolute top-1 right-1 z-30">
+              <Button
+                size="icon-sm"
+                variant="ghost"
+                onClick={() => setArtifactsOpen(false)}
+              >
+                <XIcon />
+              </Button>
+            </div>
+            <ConversationEmptyState
+              icon={<FilesIcon />}
+              title="请选择文件"
+              description="从左侧目录中选择一个文件进行查看"
+            />
+          </>
+        )}
+      </div>
+    </div>
+  ) : selectedArtifact ? (
+    <ArtifactFileDetail
+      key={selectedArtifactKey ?? selectedArtifact}
+      className="size-full"
+      filepath={selectedArtifact}
+      threadId={threadId}
+      allowVirtualMarkdownEdit
+    />
+  ) : (
+    <div className="relative flex size-full justify-center">
+      <div className="absolute top-1 right-1 z-30">
+        <Button
+          size="icon-sm"
+          variant="ghost"
+          onClick={() => setArtifactsOpen(false)}
+        >
+          <XIcon />
+        </Button>
+      </div>
+      {artifacts.length === 0 ? (
+        <ConversationEmptyState
+          icon={<FilesIcon />}
+          title="No artifact selected"
+          description="Select an artifact to view its details"
+        />
+      ) : (
+        <div className="flex size-full max-w-(--container-width-sm) flex-col justify-center p-4 pt-8">
+          <header className="shrink-0">
+            <h2 className="text-lg font-medium">Artifacts</h2>
+          </header>
+          <main className="min-h-0 grow">
+            <ArtifactFileList
+              className="max-w-(--container-width-sm) p-4 pt-12"
+              files={artifacts}
+              threadId={threadId}
+            />
+          </main>
+        </div>
+      )}
+    </div>
+  );
 
   if (disableArtifacts) {
     return (
@@ -419,12 +647,7 @@ const ChatBox: React.FC<{
                 </Button>
               </div>
               <TabsContent value="document" className="min-h-0 flex-1 overflow-hidden p-0">
-                <ArtifactFileDetail
-                  className="size-full"
-                  filepath={selectedArtifact}
-                  threadId={threadId}
-                  allowVirtualMarkdownEdit
-                />
+                {artifactDocumentPanel}
               </TabsContent>
               <TabsContent value="references" className="min-h-0 flex-1 overflow-y-auto p-0">
                 <ReferencePanel
@@ -433,13 +656,8 @@ const ChatBox: React.FC<{
                 />
               </TabsContent>
             </Tabs>
-          ) : selectedArtifact ? (
-            <ArtifactFileDetail
-              className="size-full"
-              filepath={selectedArtifact}
-              threadId={threadId}
-              allowVirtualMarkdownEdit
-            />
+          ) : artifactPanelOpen ? (
+            artifactDocumentPanel
           ) : hasCitationReferences ? (
             <div className="relative size-full overflow-hidden">
               <div className="absolute top-1 right-1 z-30">
@@ -459,41 +677,7 @@ const ChatBox: React.FC<{
                 sources={referenceSources}
               />
             </div>
-          ) : (
-            <div className="relative flex size-full justify-center">
-              <div className="absolute top-1 right-1 z-30">
-                <Button
-                  size="icon-sm"
-                  variant="ghost"
-                  onClick={() => {
-                    setArtifactsOpen(false);
-                  }}
-                >
-                  <XIcon />
-                </Button>
-              </div>
-              {thread.values.artifacts?.length === 0 ? (
-                <ConversationEmptyState
-                  icon={<FilesIcon />}
-                  title="No artifact selected"
-                  description="Select an artifact to view its details"
-                />
-              ) : (
-                <div className="flex size-full max-w-(--container-width-sm) flex-col justify-center p-4 pt-8">
-                  <header className="shrink-0">
-                    <h2 className="text-lg font-medium">Artifacts</h2>
-                  </header>
-                  <main className="min-h-0 grow">
-                    <ArtifactFileList
-                      className="max-w-(--container-width-sm) p-4 pt-12"
-                      files={thread.values.artifacts ?? []}
-                      threadId={threadId}
-                    />
-                  </main>
-                </div>
-              )}
-            </div>
-          )}
+          ) : null}
         </div>
       </ResizablePanel>
     </ResizablePanelGroup>
@@ -742,11 +926,10 @@ function buildTurnReferenceBatches(
       continue;
     }
     const nextHumanIndex = findNextHumanIndex(messages, index + 1);
-    if (nextHumanIndex === -1 && isLoading) {
-      continue;
-    }
     const endIndex = nextHumanIndex === -1 ? messages.length : nextHumanIndex;
-    const assistant = findLastAssistantAnswer(messages, index + 1, endIndex);
+    const assistant =
+      findLastAssistantAnswer(messages, index + 1, endIndex) ??
+      findFrontendRagAssistant(messages, index + 1, endIndex);
     if (!assistant?.id) {
       continue;
     }
@@ -756,6 +939,14 @@ function buildTurnReferenceBatches(
         nextHumanIndex === -1 ? undefined : messages[nextHumanIndex]?.id,
       includeBeforeMessage: false,
     }).filter((source) => source.mode !== "none");
+    // GeneralQA's single-RAG stream sends `docs` before the answer.  Make
+    // those cards available immediately, while keeping normal streaming turns
+    // on their existing "wait for an answer" behavior.
+    const isFrontendRagTurn =
+      isSingleRoundRagMessage(assistant) || isMultiRoundRagMessage(assistant);
+    if (nextHumanIndex === -1 && isLoading && !isFrontendRagTurn) {
+      continue;
+    }
     if (sources.length > 0) {
       batches.push({
         id: assistant.id,
@@ -794,6 +985,23 @@ function findLastAssistantAnswer(
   return null;
 }
 
+function findFrontendRagAssistant(
+  messages: Message[],
+  start: number,
+  end: number,
+): Message | null {
+  for (let index = end - 1; index >= start; index -= 1) {
+    const message = messages[index];
+    if (
+      message?.type === "ai" &&
+      (isSingleRoundRagMessage(message) || isMultiRoundRagMessage(message))
+    ) {
+      return message;
+    }
+  }
+  return null;
+}
+
 function hasAssistantAnswerContent(message: Message): boolean {
   const content = message.content;
   if (typeof content === "string") {

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/cm-chat-sidebar.tsx

@@ -17,6 +17,8 @@ import { usePathname } from "next/navigation";
 import type { MouseEvent } from "react";
 import { useNavigate } from "react-router-dom";
 
+import cmAssistantLogoDark from "@/assets/img/cm-assistant-logo.png";
+import cmAssistantLogoLight from "@/assets/img/cm-assistant-logo-red.png";
 import { cn } from "@/lib/utils";
 import { useTheme } from "@/contexts/ThemeContext";
 
@@ -68,7 +70,7 @@ export function CmChatSidebar({
   const pathname = usePathname();
   const navigate = useNavigate();
   const { theme } = useTheme();
-  const brandLogoSrc = theme === "light" ? "/cm-assistant-logo-red.png" : "/cm-assistant-logo.png";
+  const brandLogoSrc = theme === "light" ? cmAssistantLogoLight : cmAssistantLogoDark;
 
   const handleNewChat = (event: MouseEvent<HTMLAnchorElement>) => {
     if (event.metaKey || event.ctrlKey || event.shiftKey || event.button === 1) return;

frontend-web/src/components/workspace/code-editor.tsx

@@ -11,12 +11,11 @@ import { basicLightInit } from "@uiw/codemirror-theme-basic";
 import { monokaiInit } from "@uiw/codemirror-theme-monokai";
 import CodeMirror from "@uiw/react-codemirror";
 import { useTheme } from "next-themes";
-import { useMemo } from "react";
+import { memo, useMemo } from "react";
 
 import { Textarea } from "@/components/ui/textarea";
 import { cn } from "@/lib/utils";
 
-import { useThread } from "./messages/context";
 const customDarkTheme = monokaiInit({
   settings: {
     background: "transparent",
@@ -34,7 +33,7 @@ const customLightTheme = basicLightInit({
   },
 });
 
-export function CodeEditor({
+export const CodeEditor = memo(function CodeEditor({
   className,
   placeholder,
   value,
@@ -43,6 +42,7 @@ export function CodeEditor({
   disabled,
   autoFocus,
   settings,
+  isStreaming = false,
   streamingReadonlyFallback = true,
 }: {
   className?: string;
@@ -53,11 +53,10 @@ export function CodeEditor({
   disabled?: boolean;
   autoFocus?: boolean;
   settings?: unknown;
+  /** Parent-owned streaming flag so this editor does not subscribe to `thread`. */
+  isStreaming?: boolean;
   streamingReadonlyFallback?: boolean;
 }) {
-  const {
-    thread: { isLoading },
-  } = useThread();
   const { resolvedTheme } = useTheme();
 
   const extensions = useMemo(() => {
@@ -81,7 +80,7 @@ export function CodeEditor({
         className,
       )}
     >
-      {isLoading && streamingReadonlyFallback ? (
+      {isStreaming && streamingReadonlyFallback ? (
         <Textarea
           className={cn(
             "h-full overflow-auto font-mono [&_.cm-editor]:h-full [&_.cm-focused]:outline-none!",
@@ -116,4 +115,4 @@ export function CodeEditor({
       )}
     </div>
   );
-}
+});