Merge branch 'master' of http://192.168.0.200/knowledge-base-bj/deerflow-server into xhy

fix(roundtable): 文件卡截断、Step3 完整 HTML 与跨标签页登录体验

See merge request knowledge-base-bj/deerflow-server!85

.claude/launch.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "md-viewer-frontend",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["ng", "serve", "--port", "4200"],
+      "port": 4200,
+      "cwd": "F:\\angular\\md-viewer\\frontend"
+    }
+  ]
+}

.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "PowerShell(uv --version)",
+      "PowerShell(netstat -ano)",
+      "PowerShell(Get-NetTCPConnection -LocalPort 8001 -ErrorAction SilentlyContinue)",
+      "PowerShell(Get-Process -Id 20560 -ErrorAction SilentlyContinue | Select-Object Id,ProcessName,Path,StartTime; try { \\(Invoke-WebRequest -Uri \"http://127.0.0.1:8001/health\" -UseBasicParsing -TimeoutSec 5\\).Content } catch { \"health check failed: $_\" })"
+    ]
+  }
+}

.gitignore

@@ -7,9 +7,13 @@ frontend-web/.vscode/
 
 # Local runtime logs and pid files
 .runtime/
+logs/
+offline-backend-20260512/backend/logs/
 
 # Frontend local/runtime artifacts
 frontend-web/.env
+frontend-web/.env.local
+frontend-web/.env.*.local
 frontend-web/node_modules/
 frontend-web/.pnpm-store/
 frontend-web/tsconfig.tsbuildinfo
@@ -77,4 +81,23 @@ skills/
 hermes-agent-main/
 .gitignore
 offline-backend-20260512/backend/tests/*
-deploy
+deploy
+.history
+
+# Repo-root offline dependency pack (local only)
+/dist/
+
+# Frontend offline pack working directories
+frontend-web/.offline-pack-build/
+frontend-web/.offline-extract-test/
+
+.codegraph
+codegraph.mdc
+
+docs/aidev-docs
+docs/backups
+# Frontend skills components must be tracked (excluded from the broad skills/ ignore above)
+!frontend-web/src/components/workspace/skills/
+
+# uv lockfile (not tracked per project preference)
+offline-backend-20260512/backend/uv.lock

NEW_CHAT_STREAM_FORMAT.md

@@ -0,0 +1,474 @@
+# New Chat 接口流式返回格式说明
+
+## 接口概览
+
+- **路径**：`POST /new_chat`
+- **传输协议**：Server-Sent Events (SSE)
+- **Content-Type**：`text/event-stream`
+- **协议基础**：Vercel AI SDK Data Stream Protocol
+
+---
+
+## 请求格式
+
+```json
+{
+  "chat_id": 123,
+  "search_space_id": 456,
+  "user_query": "用户问题",
+  "pic_query": [{"image_url": "/tmp/xxx.png"}],
+  "model_name": "gpt-4o",
+  "enable_citations": true,
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `chat_id` | int | ✅ | 会话 ID，同时作为 LangGraph 的 thread_id |
+| `search_space_id` | int | ✅ | 搜索空间 ID |
+| `user_query` | string | ✅ | 用户问题 |
+| `pic_query` | list\|null | ❌ | 图片路径列表，格式 `[{"image_url": "..."}]` |
+| `model_name` | string\|null | ❌ | 指定模型名称（插件场景使用） |
+| `enable_citations` | bool | ❌ | 是否启用引用（默认 true） |
+| `messages` | list\|null | ❌ | 历史消息列表 |
+| `attachments` | list\|null | ❌ | 上传附件（已解析为 Markdown） |
+| `mentioned_document_ids` | list\|null | ❌ | 前端 @ 引用的文档 ID 列表 |
+
+---
+
+## 响应 Headers
+
+```
+Content-Type: text/event-stream
+Cache-Control: no-cache
+Connection: keep-alive
+X-Accel-Buffering: no
+```
+
+---
+
+## SSE 数据帧格式
+
+每条消息均为标准 SSE 格式：
+
+```
+data: {JSON 对象}\n\n
+```
+
+流结束时发送：
+
+```
+data: [DONE]\n\n
+```
+
+---
+
+## 事件类型详解
+
+### 1. 消息生命周期
+
+#### `start` — 消息开始
+
+```json
+{"type": "start", "messageId": "msg_abc123"}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `messageId` | 本次消息的唯一 ID |
+
+---
+
+#### `finish` — 消息结束
+
+```json
+{"type": "finish"}
+```
+
+---
+
+#### `[DONE]` — 流终止标记
+
+```
+data: [DONE]
+```
+
+> 这是流中最后一帧，为纯字符串，不是 JSON。
+
+---
+
+### 2. 步骤控制（多轮工具调用）
+
+#### `start-step` — 步骤开始
+
+```json
+{"type": "start-step"}
+```
+
+#### `finish-step` — 步骤结束
+
+```json
+{"type": "finish-step"}
+```
+
+> 每次 LLM 调用算一个 step。工具调用期间会有多个 step 交替出现。
+
+---
+
+### 3. 文本块（start / delta / end 模式）
+
+#### `text-start` — 文本块开始
+
+```json
+{"type": "text-start", "id": "text_abc123"}
+```
+
+#### `text-delta` — 文本增量内容
+
+```json
+{"type": "text-delta", "id": "text_abc123", "delta": "Hello, "}
+```
+
+#### `text-end` — 文本块结束
+
+```json
+{"type": "text-end", "id": "text_abc123"}
+```
+
+---
+
+### 4. 推理块（Reasoning，适用于 DeepSeek R1 等思维链模型）
+
+#### `reasoning-start` — 推理块开始
+
+```json
+{"type": "reasoning-start", "id": "reasoning_abc123"}
+```
+
+#### `reasoning-delta` — 推理增量内容
+
+```json
+{"type": "reasoning-delta", "id": "reasoning_abc123", "delta": "让我先思考..."}
+```
+
+#### `reasoning-end` — 推理块结束
+
+```json
+{"type": "reasoning-end", "id": "reasoning_abc123"}
+```
+
+> 触发时机：
+> - 模型返回 `additional_kwargs.reasoning_content`（DeepSeek R1 原生）
+> - 模型输出中包含 `<think>...</think>` 标签（自动剥离）
+
+---
+
+### 5. 工具调用
+
+#### `tool-input-start` — 工具调用开始
+
+```json
+{"type": "tool-input-start", "toolCallId": "call_abc123", "toolName": "search_knowledge_base"}
+```
+
+#### `tool-input-delta` — 工具输入流式内容（增量）
+
+```json
+{"type": "tool-input-delta", "toolCallId": "call_abc123", "inputTextDelta": "San Fra"}
+```
+
+#### `tool-input-available` — 工具输入完整参数
+
+```json
+{
+  "type": "tool-input-available",
+  "toolCallId": "call_abc123",
+  "toolName": "search_knowledge_base",
+  "input": {"query": "机器学习入门"}
+}
+```
+
+#### `tool-output-available` — 工具执行结果
+
+```json
+{
+  "type": "tool-output-available",
+  "toolCallId": "call_abc123",
+  "output": {"status": "completed", "result_length": 1234}
+}
+```
+
+> 注意：`search_knowledge_base` 只返回摘要（不含全文），`write_todos`、`link_preview`、`display_image`、`scrape_webpage`、`generate_podcast` 会返回完整 output 供前端渲染组件。
+
+---
+
+### 6. 来源引用
+
+#### `source-url` — URL 来源
+
+```json
+{
+  "type": "source-url",
+  "sourceId": "https://example.com",
+  "url": "https://example.com",
+  "title": "示例页面"
+}
+```
+
+#### `source-document` — 文档来源
+
+```json
+{
+  "type": "source-document",
+  "sourceId": "doc_123",
+  "mediaType": "file",
+  "title": "报告.pdf",
+  "description": "第三季度报告"
+}
+```
+
+---
+
+### 7. 文件
+
+```json
+{"type": "file", "url": "https://example.com/image.png", "mediaType": "image/png"}
+```
+
+---
+
+### 8. 自定义数据（`data-*` 类型）
+
+#### `data-terminal-info` — 终端信息提示
+
+```json
+{
+  "type": "data-terminal-info",
+  "data": {
+    "text": "知识库搜索已完成",
+    "type": "success"
+  }
+}
+```
+
+`type` 枚举值：`info` | `error` | `success` | `warning`
+
+---
+
+#### `data-further-questions` — 推荐追问问题
+
+```json
+{
+  "type": "data-further-questions",
+  "data": {
+    "questions": ["问题1", "问题2", "问题3"]
+  }
+}
+```
+
+---
+
+#### `data-thinking-step` — 思考步骤（思维链 UI 展示）
+
+```json
+{
+  "type": "data-thinking-step",
+  "data": {
+    "id": "thinking-1",
+    "title": "正在搜索知识库",
+    "status": "in_progress",
+    "items": ["Query: 机器学习入门"]
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `id` | 步骤唯一 ID（格式 `thinking-N`） |
+| `title` | 步骤标题 |
+| `status` | `pending` \| `in_progress` \| `completed` |
+| `items` | 步骤详情列表（可选） |
+
+> 同一个 `id` 的步骤事件会被重复发送以更新状态（先 `in_progress` 后 `completed`）。
+
+**常见步骤标题对照：**
+
+| 工具 / 场景 | 标题 |
+|------------|------|
+| 初始分析 | 正在理解您的请求 / 正在分析您的内容 |
+| `search_knowledge_base` | 查询个人知识库中 |
+| `search_web` | 网查搜索中 |
+| `link_preview` | 正在获取链接预览 |
+| `display_image` | 正在分析图片 |
+| `scrape_webpage` | 正在抓取网页 |
+| `write_todos`（首次） | 正在创建计划 |
+| `write_todos`（更新） | 正在更新进度 |
+| `generate_podcast` | 正在生成播客 |
+
+---
+
+### 9. 错误
+
+```json
+{
+  "type": "error",
+  "errorText": "API rate limit exceeded",
+  "errorType": "llm",
+  "errorCode": "rate_limit"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `errorText` | 错误描述文本 |
+| `errorType` | 错误类型（见下表） |
+| `errorCode` | 具体错误代码（可选） |
+
+**errorType 枚举：**
+
+| 值 | 含义 |
+|----|------|
+| `llm` | LLM / API 错误（模型不存在、限流、密钥错误等） |
+| `network` | 网络连通性错误 |
+| `timeout` | 请求超时 |
+| `authentication` | 鉴权 / 权限错误 |
+| `rate_limit` | 速率限制 |
+| `validation` | 输入验证错误 |
+| `internal` | 内部服务器错误 |
+| `unknown` | 未知错误 |
+
+---
+
+### 10. 中断（Human-in-the-loop）
+
+```json
+{
+  "type": "interrupt",
+  "messageId": "msg_abc123",
+  "interrupt": {
+    "action_requests": [...],
+    "review_configs": [...]
+  },
+  "payload": {"expertAgentId": 42}
+}
+```
+
+---
+
+## 完整流示例（普通问答）
+
+```
+data: {"type":"start","messageId":"msg_abc123"}
+
+data: {"type":"start-step"}
+
+data: {"type":"data-thinking-step","data":{"id":"thinking-1","title":"正在理解您的请求","status":"in_progress","items":["Processing: 什么是向量数据库？"]}}
+
+data: {"type":"data-thinking-step","data":{"id":"thinking-1","title":"正在理解您的请求","status":"completed","items":["Processing: 什么是向量数据库？"]}}
+
+data: {"type":"text-start","id":"text_xyz789"}
+
+data: {"type":"text-delta","id":"text_xyz789","delta":"向量数据库是"}
+
+data: {"type":"text-delta","id":"text_xyz789","delta":"一种专为存储和检索"}
+
+data: {"type":"text-delta","id":"text_xyz789","delta":"高维向量而设计的数据库..."}
+
+data: {"type":"text-end","id":"text_xyz789"}
+
+data: {"type":"finish-step"}
+
+data: {"type":"finish"}
+
+data: [DONE]
+```
+
+---
+
+## 完整流示例（含工具调用）
+
+```
+data: {"type":"start","messageId":"msg_abc123"}
+
+data: {"type":"start-step"}
+
+data: {"type":"data-thinking-step","data":{"id":"thinking-1","title":"正在理解您的请求","status":"in_progress","items":["Processing: 搜索最新 AI 论文"]}}
+
+data: {"type":"data-thinking-step","data":{"id":"thinking-1","title":"正在理解您的请求","status":"completed","items":["Processing: 搜索最新 AI 论文"]}}
+
+data: {"type":"data-thinking-step","data":{"id":"thinking-2","title":"查询个人知识库中","status":"in_progress","items":["Query: 最新 AI 论文"]}}
+
+data: {"type":"tool-input-start","toolCallId":"call_xxx","toolName":"search_knowledge_base"}
+
+data: {"type":"tool-input-available","toolCallId":"call_xxx","toolName":"search_knowledge_base","input":{"query":"最新 AI 论文"}}
+
+data: {"type":"data-thinking-step","data":{"id":"thinking-2","title":"Searching knowledge base","status":"completed","items":["Query: 最新 AI 论文","Found relevant information (2048 chars)"]}}
+
+data: {"type":"tool-output-available","toolCallId":"call_xxx","output":{"status":"completed","result_length":2048}}
+
+data: {"type":"data-terminal-info","data":{"text":"知识库搜索已完成","type":"success"}}
+
+data: {"type":"text-start","id":"text_xyz789"}
+
+data: {"type":"text-delta","id":"text_xyz789","delta":"根据知识库中的内容..."}
+
+data: {"type":"text-end","id":"text_xyz789"}
+
+data: {"type":"finish-step"}
+
+data: {"type":"finish"}
+
+data: [DONE]
+```
+
+---
+
+## 完整流示例（含推理过程）
+
+```
+data: {"type":"start","messageId":"msg_abc123"}
+
+data: {"type":"start-step"}
+
+data: {"type":"reasoning-start","id":"reasoning_r01"}
+
+data: {"type":"reasoning-delta","id":"reasoning_r01","delta":"让我先分析这个问题..."}
+
+data: {"type":"reasoning-delta","id":"reasoning_r01","delta":"需要考虑以下几个方面..."}
+
+data: {"type":"reasoning-end","id":"reasoning_r01"}
+
+data: {"type":"text-start","id":"text_xyz789"}
+
+data: {"type":"text-delta","id":"text_xyz789","delta":"综合分析后，结论是..."}
+
+data: {"type":"text-end","id":"text_xyz789"}
+
+data: {"type":"finish-step"}
+
+data: {"type":"finish"}
+
+data: [DONE]
+```
+
+---
+
+## 标准消息流顺序
+
+```
+start
+  └─ start-step
+       ├─ [data-thinking-step × N]   思考步骤（可多次）
+       ├─ [reasoning-start/delta/end] 推理过程（可选）
+       ├─ [tool-input-start]          工具调用开始（可多次）
+       ├─ [tool-input-available]      工具参数确认
+       ├─ [tool-output-available]     工具结果
+       ├─ [data-terminal-info]        终端提示（可多次）
+       ├─ [source-url / source-document] 来源引用（可选）
+       ├─ text-start
+       │    └─ text-delta × N         流式文本
+       └─ text-end
+     finish-step
+finish
+[DONE]
+```

cankaoyangshi/metadata.json

@@ -1,6 +0,0 @@
-{
-  "name": "Gemini Style Assistant",
-  "description": "A clean, modern AI assistant interface inspired by Google Gemini with centered search, suggestion pills, and a minimalist sidebar.",
-  "requestFramePermissions": [],
-  "majorCapabilities": ["MAJOR_CAPABILITY_SERVER_SIDE_GEMINI_API"]
-}

cankaoyangshi/src/App.tsx

@@ -1,238 +0,0 @@
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { useState } from 'react';
-import { motion, AnimatePresence } from 'motion/react';
-import { 
-  MessageSquare, 
-  Bot, 
-  Wrench, 
-  Brain, 
-  ListChecks, 
-  Settings, 
-  Menu, 
-  Mic, 
-  Plus, 
-  Sparkles,
-  ArrowRight,
-  User,
-  History,
-  LayoutGrid,
-  Languages,
-  Code2,
-  Music,
-  Database,
-  Search
-} from 'lucide-react';
-
-export default function App() {
-  const [sidebarOpen, setSidebarOpen] = useState(true);
-
-  const navItems = [
-    { icon: MessageSquare, label: '对话', active: true },
-    { icon: Bot, label: '智能体' },
-    { icon: Wrench, label: '技能' },
-    { icon: Brain, label: '记忆' },
-    { icon: ListChecks, label: '任务管理' },
-  ];
-
-  const recentChats = [
-    'CM助手初次问候交谈',
-    'Untitled',
-    'Untitled',
-    'Untitled',
-    '帮我写一个500字的文案',
-    '帮我生成一个写论文的实例',
-  ];
-
-  const suggestions = [
-    { icon: Code2, label: 'Build an Android app', color: 'text-green-600', bg: 'bg-green-50' },
-    { icon: Languages, label: 'Convert text to speech', color: 'text-blue-600', bg: 'bg-blue-50' },
-    { icon: Music, label: 'Generate music', color: 'text-purple-600', bg: 'bg-purple-50' },
-    { icon: Database, label: 'Add database and auth', color: 'text-cyan-600', bg: 'bg-cyan-50' },
-  ];
-
-  return (
-    <div className="flex h-screen w-full bg-white font-sans text-gray-900 overflow-hidden">
-      {/* Sidebar */}
-      <motion.aside
-        initial={false}
-        animate={{ width: sidebarOpen ? 280 : 0, opacity: sidebarOpen ? 1 : 0 }}
-        className="relative bg-gray-50 border-r border-gray-100 flex flex-col h-full"
-      >
-        <div className="p-4 flex items-center justify-between">
-          <div className="flex items-center gap-2 px-2 py-1.5 bg-red-50 text-red-700 rounded-lg cursor-pointer">
-            <Plus size={18} />
-            <span className="font-medium text-sm">新对话</span>
-          </div>
-        </div>
-
-        <nav className="flex-1 overflow-y-auto px-2 space-y-1">
-          <div className="space-y-1 pb-4">
-            {navItems.map((item) => (
-              <div
-                key={item.label}
-                className={`flex items-center gap-3 px-3 py-2 rounded-xl cursor-pointer transition-colors ${
-                  item.active ? 'bg-white shadow-sm font-medium' : 'hover:bg-gray-100 text-gray-600'
-                }`}
-              >
-                <item.icon size={18} />
-                <span className="text-sm">{item.label}</span>
-              </div>
-            ))}
-          </div>
-
-          <div className="pt-4 border-t border-gray-200">
-            <h3 className="px-3 mb-2 text-xs font-semibold text-gray-400 uppercase tracking-wider">
-              最近对话
-            </h3>
-            {recentChats.map((chat, idx) => (
-              <div
-                key={idx}
-                className="px-3 py-1.5 text-sm text-gray-600 hover:bg-gray-100 rounded-lg cursor-pointer truncate"
-              >
-                {chat}
-              </div>
-            ))}
-          </div>
-        </nav>
-
-        <div className="p-4 border-t border-gray-200">
-          <div className="flex items-center gap-3 px-3 py-2 text-gray-600 hover:bg-gray-100 rounded-xl cursor-pointer">
-            <Settings size={18} />
-            <span className="text-sm">设置和更多</span>
-          </div>
-        </div>
-      </motion.aside>
-
-      {/* Main Content */}
-      <main className="flex-1 flex flex-col relative h-full overflow-y-auto">
-        {/* Top bar */}
-        <header className="absolute top-0 w-full p-4 flex items-center justify-between z-10">
-          <button
-            onClick={() => setSidebarOpen(!sidebarOpen)}
-            className="p-2 hover:bg-gray-100 rounded-lg text-gray-500 transition-colors"
-          >
-            <Menu size={20} />
-          </button>
-          
-          <div className="flex items-center gap-2">
-            <button className="p-2 hover:bg-gray-100 rounded-lg text-gray-500 transition-colors">
-              <Settings size={20} />
-            </button>
-            <div className="w-8 h-8 rounded-full bg-gradient-to-tr from-blue-400 to-purple-400 flex items-center justify-center text-white shadow-sm ring-2 ring-white cursor-pointer overflow-hidden">
-              <User size={16} />
-            </div>
-          </div>
-        </header>
-
-        {/* Center Canvas */}
-        <div className="flex-1 flex flex-col items-center justify-center px-4 max-w-4xl mx-auto w-full pt-16">
-          <motion.div
-            initial={{ opacity: 0, y: 20 }}
-            animate={{ opacity: 1, y: 0 }}
-            className="text-center mb-12 relative"
-          >
-            <div className="absolute -top-16 left-1/2 -translate-x-1/2 opacity-10 blur-2xl pointer-events-none">
-              <Sparkles size={120} className="text-blue-500 animate-pulse" />
-            </div>
-            <h1 className="text-5xl font-display font-medium tracking-tight bg-clip-text text-transparent bg-gradient-to-r from-gray-900 to-gray-500 mb-4 px-4">
-              Build your ideas with Gemini
-            </h1>
-            <Sparkles className="absolute -right-8 top-0 text-blue-200 opacity-50" size={48} />
-          </motion.div>
-
-          {/* Search/Input Area */}
-          <motion.div
-             initial={{ opacity: 0, scale: 0.95 }}
-             animate={{ opacity: 1, scale: 1 }}
-             transition={{ delay: 0.1 }}
-             className="w-full max-w-2xl relative group"
-          >
-            <div className="gemini-gradient-border gemini-shadow rounded-3xl bg-white p-2">
-              <div className="flex flex-col p-4 space-y-4">
-                <textarea
-                  placeholder="Describe an app and let Gemini do the rest"
-                  className="w-full bg-transparent resize-none focus:outline-none text-lg text-gray-700 min-h-[80px]"
-                />
-                
-                <div className="flex items-center justify-between pt-2">
-                  <div className="flex items-center gap-2">
-                    <button className="p-2 hover:bg-gray-100 rounded-full text-gray-400 transition-colors">
-                      <Mic size={20} />
-                    </button>
-                    <button className="p-2 hover:bg-gray-100 rounded-full text-gray-400 transition-colors">
-                      <Plus size={20} />
-                    </button>
-                  </div>
-                  
-                  <button className="flex items-center gap-2 px-5 py-2.5 bg-gray-50 hover:bg-gray-100 text-gray-700 rounded-full border border-gray-200 transition-all font-medium text-sm group/btn shadow-sm">
-                    <Sparkles size={16} className="text-blue-500" />
-                    I'm feeling lucky
-                    <ArrowRight size={14} className="opacity-0 -translate-x-2 group-hover/btn:opacity-100 group-hover/btn:translate-x-0 transition-all" />
-                  </button>
-                </div>
-              </div>
-            </div>
-          </motion.div>
-
-          {/* Suggestion Chips */}
-          <div className="mt-8 flex flex-wrap justify-center gap-3">
-            {suggestions.map((suggestion, idx) => (
-              <motion.button
-                key={suggestion.label}
-                initial={{ opacity: 0, y: 10 }}
-                animate={{ opacity: 1, y: 0 }}
-                transition={{ delay: 0.2 + idx * 0.05 }}
-                whileHover={{ scale: 1.02 }}
-                whileTap={{ scale: 0.98 }}
-                className={`flex items-center gap-2 px-4 py-2.5 rounded-2xl border border-gray-100 bg-white hover:bg-gray-50 shadow-sm transition-all text-sm font-medium group hover:border-gray-200 text-gray-700`}
-              >
-                <suggestion.icon className={`w-4 h-4 ${suggestion.color}`} />
-                {suggestion.label}
-              </motion.button>
-            ))}
-            <motion.button
-               initial={{ opacity: 0, y: 10 }}
-               animate={{ opacity: 1, y: 0 }}
-               transition={{ delay: 0.4 }}
-               className="flex items-center justify-center p-2 rounded-full border border-gray-100 bg-white hover:bg-gray-50 text-gray-400 shadow-sm transition-all"
-            >
-              <ArrowRight size={16} />
-            </motion.button>
-          </div>
-        </div>
-
-        {/* Footer info/links */}
-        <footer className="w-full max-w-4xl mx-auto px-4 py-12 mt-auto">
-          <div className="rounded-3xl border border-gray-100 bg-gray-50/50 p-8 flex items-center justify-between group hover:bg-gray-50 transition-colors">
-            <div>
-              <h2 className="text-2xl font-display font-medium text-gray-800 mb-1">
-                Discover and remix app ideas
-              </h2>
-              <p className="text-gray-500 text-sm italic">
-                (Gallery view pending implementation)
-              </p>
-            </div>
-            <button className="flex items-center gap-2 px-6 py-2.5 bg-white border border-gray-200 rounded-xl hover:shadow-md transition-all font-medium text-gray-700">
-              Browse the app gallery
-              <ArrowRight size={18} />
-            </button>
-          </div>
-        </footer>
-        
-        {/* Floating Right Bar (from target image) */}
-        <div className="absolute right-6 top-1/2 -translate-y-1/2 flex flex-col gap-4">
-          <button className="p-2.5 bg-white shadow-lg border border-gray-100 rounded-xl hover:scale-110 transition-all text-gray-400">
-            <LayoutGrid size={22} />
-          </button>
-          <button className="p-2.5 bg-white shadow-lg border border-gray-100 rounded-xl hover:scale-110 transition-all text-gray-400">
-            <Languages size={22} />
-          </button>
-        </div>
-      </main>
-    </div>
-  );
-}

cankaoyangshi/src/index.css

@@ -1,71 +0,0 @@
-@import "tailwindcss";
-
-@theme {
-  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
-  --font-display: "Outfit", "Inter", sans-serif;
-}
-
-@layer base {
-  body {
-    @apply bg-white text-gray-900 antialiased;
-  }
-}
-
-@layer utilities {
-  .gemini-shadow {
-    box-shadow: 0 0 20px rgba(66, 133, 244, 0.08),
-                0 0 40px rgba(219, 68, 55, 0.04),
-                0 0 60px rgba(244, 180, 0, 0.04),
-                0 0 80px rgba(15, 157, 88, 0.04);
-  }
-  
-  .gemini-gradient-border {
-    position: relative;
-    background: white;
-    border-radius: 1.5rem; /* rounded-3xl */
-    z-index: 0;
-    overflow: hidden;
-  }
-  
-  .gemini-gradient-border::before {
-    content: '';
-    position: absolute;
-    width: 150%;
-    height: 150%;
-    top: -25%;
-    left: -25%;
-    background: conic-gradient(
-      from 0deg,
-      transparent 0deg,
-      transparent 90deg,
-      #4285F4 120deg,
-      #DB4437 150deg,
-      #F4B400 180deg,
-      #0F9D58 210deg,
-      transparent 240deg
-    );
-    z-index: -2;
-    animation: rotate 3s linear infinite;
-    filter: blur(15px);
-  }
-
-  .gemini-gradient-border::after {
-    content: '';
-    position: absolute;
-    inset: 1.5px; /* The "thickness" of the glow border */
-    background: white;
-    border-radius: calc(1.5rem - 1px);
-    z-index: -1;
-  }
-
-  @keyframes rotate {
-    from {
-      transform: rotate(0deg);
-    }
-    to {
-      transform: rotate(360deg);
-    }
-  }
-}
-
-@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=Outfit:wght@400;500;600&display=swap');

docs/superpowers/plans/2026-06-01-iframe-chat-page.md

@@ -0,0 +1,139 @@
+# Iframe Chat Page Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a standalone `/page/workspace/chats_iframe/*` chat page that reuses the existing thread system and history, while showing only `你好` and no input box before the first user message.
+
+**Architecture:** Keep the existing workspace shell and chat runtime intact, then add a new route pair and a copied page component dedicated to the iframe path. The new page keeps the original chat behavior once a thread already has messages, but it owns its empty-state rendering and URL transition to `/page/workspace/chats_iframe/:thread_id`.
+
+**Tech Stack:** React, TypeScript, React Router, Next navigation shim, existing LangGraph thread hooks
+
+---
+
+### Task 1: Add the iframe chat routes
+
+**Files:**
+- Modify: `frontend-web/src/pages/WorkspaceRoutes.tsx`
+
+- [ ] **Step 1: Add `chats_iframe/new` and `chats_iframe/:thread_id` routes that render the new page inside the existing workspace layout and chat runtime**
+
+```tsx
+      <Route
+        path="chats_iframe/new"
+        element={
+          <WorkspaceLayout {...layoutProps}>
+            <ChatRuntime>
+              <IframeChatPage />
+            </ChatRuntime>
+          </WorkspaceLayout>
+        }
+      />
+      <Route
+        path="chats_iframe/:thread_id"
+        element={
+          <WorkspaceLayout {...layoutProps}>
+            <ChatRuntime>
+              <IframeChatPage />
+            </ChatRuntime>
+          </WorkspaceLayout>
+        }
+      />
+```
+
+- [ ] **Step 2: Ensure the new route imports compile cleanly**
+
+Run: `rg -n "IframeChatPage|chats_iframe" frontend-web/src/pages/WorkspaceRoutes.tsx`
+Expected: `WorkspaceRoutes.tsx` contains one import for `IframeChatPage` and both `chats_iframe` route entries.
+
+### Task 2: Add a standalone iframe chat page
+
+**Files:**
+- Create: `frontend-web/src/pages/IframeChatPage.tsx`
+- Reference: `frontend-web/src/pages/ChatPage.tsx`
+
+- [ ] **Step 1: Copy the current `ChatPage` implementation into `IframeChatPage` and preserve the existing chat runtime integration**
+
+```tsx
+export default function IframeChatPage() {
+  const routeBase = useRouteBase();
+  const router = useRouter();
+  const [showFollowups, setShowFollowups] = useState(false);
+  const [hasStartedConversation, setHasStartedConversation] = useState(false);
+  const { threadId, setThreadId, isNewThread, setIsNewThread, isMock } =
+    useThreadChat();
+  // keep the rest of the existing chat hooks and handlers aligned with ChatPage
+}
+```
+
+- [ ] **Step 2: Change the thread creation URL replacement to stay on the iframe route family**
+
+```tsx
+    onStart: (createdThreadId) => {
+      setThreadId(createdThreadId);
+      setIsNewThread(false);
+      history.replaceState(
+        null,
+        "",
+        `${window.location.pathname}${window.location.search}#${routeBase}/chats_iframe/${createdThreadId}`,
+      );
+    },
+```
+
+- [ ] **Step 3: Replace the default landing state with a simple `你好` view and do not render the input box while the iframe page is still a brand-new untouched chat**
+
+```tsx
+                {isLandingState && mounted ? (
+                  <div className="flex min-h-[240px] items-center justify-center">
+                    <div className="text-2xl font-medium">你好</div>
+                  </div>
+                ) : null}
+                {!isLandingState &&
+                  (mounted ? (
+                    <div className="w-full -translate-y-4">
+                      <InputBox
+                        className="w-full"
+                        isNewThread={false}
+                        threadId={threadId}
+                        autoFocus={false}
+                        status={thread.error ? "error" : thread.isLoading ? "streaming" : "ready"}
+                        context={settings.context}
+                        disabled={env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" || isUploading}
+                        onContextChange={(context) => setSettings("context", context)}
+                        promptPrefix={promptPrefixProp}
+                        onFollowupsVisibilityChange={setShowFollowups}
+                        onSubmit={handleSubmit}
+                        onStop={handleStop}
+                      />
+                    </div>
+                  ) : (
+                    <div aria-hidden="true" className="bg-background/5 h-32 w-full -translate-y-4 rounded-3xl border" />
+                  ))}
+```
+
+- [ ] **Step 4: Keep message rendering, thread title, export, token usage, todos, artifact triggers, and all post-first-message behavior identical to the original page**
+
+Run: `rg -n "MessageList|ThreadTitle|ArtifactTrigger|TokenUsageIndicator|TodoList" frontend-web/src/pages/IframeChatPage.tsx`
+Expected: The new page still renders the same core chat primitives used by `ChatPage`.
+
+### Task 3: Verify the new page compiles
+
+**Files:**
+- Test: `frontend-web/src/pages/IframeChatPage.tsx`
+- Test: `frontend-web/src/pages/WorkspaceRoutes.tsx`
+
+- [ ] **Step 1: Run the frontend build**
+
+Run: `cmd /c npm run build`
+Expected: Build succeeds without TypeScript or bundling errors related to `IframeChatPage` or `chats_iframe`.
+
+- [ ] **Step 2: Spot-check the changed routes in the built source**
+
+Run: `rg -n "chats_iframe" frontend-web/src/pages`
+Expected: Matches appear in `WorkspaceRoutes.tsx` and `IframeChatPage.tsx`.
+
+- [ ] **Step 3: Commit after verification**
+
+```bash
+git add docs/superpowers/plans/2026-06-01-iframe-chat-page.md frontend-web/src/pages/WorkspaceRoutes.tsx frontend-web/src/pages/IframeChatPage.tsx
+git commit -m "feat: add iframe chat page routes"
+```

docs/superpowers/specs/2026-05-20-router-subagent-design.md

@@ -0,0 +1,229 @@
+# 问答模式路由智能体设计方案
+
+> **状态**：部分实现 ✓
+> - ✅ `subagent_mode` 注入机制已实现（`build_run_config`、`_CONTEXT_CONFIGURABLE_KEYS`）
+> - ✅ DeerFlow 运行时 `subagent_mode` 加载已实现（`make_lead_agent`）
+> - ✅ `router_quality_tool.py` 已创建
+> - ✅ 子 Agent 目录结构已创建（7个子 Agent 的 SOUL.md 和 config.yaml）
+> - ✅ 路由器 SOUL.md 已更新
+> - ⏳ 集成测试和质检提示词测试待完成
+
+## 1. 背景与目标
+
+路由器智能体（`f0e75f44f7594053ba1567ed89258f35`）根据用户问题判断最合适的问答模式（fast/rag/bigMode/moreModes/taskChat/hxchat/deerFlow），选择后需要调用相应子 Agent 执行，路由器对执行结果进行**完整性质检**，通过则流式输出到前端，不通过则重新匹配模式并再次执行。
+
+## 2. 整体流程
+
+```
+用户问题
+    │
+    ▼
+┌──────────────────────────────┐
+│ 路由器智能体                  │
+│ (已有 SOUL.md)                │
+│ ① 判断最佳模式                │
+└─────────────┬────────────────┘
+              │ 选择模式
+              ▼
+┌──────────────────────────────┐
+│ 子 Agent 执行                 │
+│ (完整执行完毕，结果缓存)        │
+└─────────────┬────────────────┘
+              │ 执行完毕
+              ▼
+┌──────────────────────────────┐
+│ 路由器质检                    │
+│ LLM 判断结果是否完整覆盖用户问题 │
+└─────────────┬────────────────┘
+              │
+         ③ 质检结果
+         ┌────┴────┐
+         │通过      │不通过
+         ▼         ▼
+     流式输出   重新匹配模式
+     到前端     (最多重试2次)
+```
+
+- **最大重试次数**：每个问题最多 2 次重试（总共最多 3 次执行），超过后强制输出当前结果并标注"结果可能不完整"
+
+## 3. 目录结构
+
+```
+.deer-flow/agents/f0e75f44f7594053ba1567ed89258f35/
+├── SOUL.md                     ← 路由器智能体（已有）
+├── config.yaml                 ← 路由器配置
+└── subagents/
+    ├── fast/
+    │   ├── SOUL.md             ← 快速问答子 Agent
+    │   └── config.yaml         ← tool_groups 声明
+    ├── rag/
+    │   ├── SOUL.md
+    │   └── config.yaml
+    ├── bigMode/
+    │   ├── SOUL.md
+    │   └── config.yaml
+    ├── moreModes/
+    │   ├── SOUL.md
+    │   └── config.yaml
+    ├── taskChat/
+    │   ├── SOUL.md
+    │   └── config.yaml
+    ├── hxchat/
+    │   ├── SOUL.md
+    │   └── config.yaml
+    └── deerFlow/
+        ├── SOUL.md
+        └── config.yaml
+```
+
+**父子关系**：子 Agent 目录放在路由器下二级 `subagents/`，通过目录层级体现父子结构。
+
+## 4. 子 Agent 配置
+
+### 4.1 config.yaml 格式
+
+```yaml
+id: rag
+name: 知识库问答子Agent
+description: 从知识库检索并返回引用
+tool_groups:
+  - knowledge          # 知识库检索工具组
+  - file:read          # 只读文件工具
+skills: []
+model: deepseek-chat
+```
+
+### 4.2 tool_groups 说明
+
+- tool_groups 在系统级 `config.yaml` 中统一定义（`tool_groups` 列表）
+- 子 Agent 的 config.yaml 通过 `tool_groups` 字段声明自己可以使用哪些工具组
+- 工具组示例：web（网页搜索）、knowledge（知识库检索）、file:read、file:write、bash 等
+
+## 5. 调用方式
+
+### 5.1 复用 Gateway API（方案 A — 推荐）
+
+路由器通过 DeerFlow 现有 `/api/threads/{thread_id}/runs/stream` 接口调用子 Agent：
+
+```
+POST /api/threads/{thread_id}/runs/stream
+{
+  "assistant_id": "f0e75f44f7594053ba1567ed89258f35",
+  "context": {
+    "subagent_mode": "rag"          ← 路由器注入子模式
+  },
+  "input": {
+    "messages": [...]
+  },
+  "stream_mode": ["values"]
+}
+```
+
+**执行步骤**：
+1. 路由器启动一个 run，assistant_id 指向路由器本身
+2. 路由器通过 `context.subagent_mode` 告知 DeerFlow 运行时本次应加载哪个子 Agent
+3. DeerFlow 运行时加载 `subagents/{subagent_mode}/SOUL.md` 和对应的 tool_groups
+4. 子 Agent 完整执行，结果缓存在 StreamBridge 中
+5. 执行完毕后，路由器读取完整结果
+
+**context.subagent_mode 注入机制**：
+- `build_run_config` 中新增 `subagent_mode` 到 `_CONTEXT_CONFIGURABLE_KEYS`
+- `make_lead_agent` 读取 `configurable.subagent_mode`，如果存在则加载对应子 Agent 的 SOUL.md 和工具配置
+- 如果 `subagent_mode` 不存在，则正常运行路由器自己的 SOUL.md
+
+### 5.2 质检提示词
+
+路由器在子 Agent 执行完毕后，用 LLM 进行完整性质检：
+
+```
+你是一个质检员。上游子 Agent 已根据问题执行完毕。
+请判断以下结果是否完整覆盖了用户问题的所有子问题。
+
+用户原始问题：{original_question}
+
+子 Agent 执行结果：
+{agent_output}
+
+请只返回 JSON 格式：
+{
+  "passed": true/false,
+  "reason": "判断理由（10字内）",
+  "missing_parts": ["缺失的子问题1", "缺失的子问题2"]  // 如果 passed=false
+}
+```
+
+**质检维度**：完整性（结果是否覆盖了用户问题的所有子问题）
+
+## 6. 关键代码改动
+
+### 6.1 DeerFlow 运行时改动 ✓
+
+**文件**：`packages/harness/deerflow/agents/lead_agent/agent.py`
+
+已实现：
+- `make_lead_agent` 读取 `configurable.subagent_mode`（第362-394行）
+- 如果存在，加载 `.deer-flow/agents/{agent_id}/subagents/{subagent_mode}/SOUL.md` 和对应 `config.yaml`
+- 工具绑定使用子 Agent 的 tool_groups，而非父 Agent 的
+
+### 6.2 build_run_config 改动 ✓
+
+**文件**：`app/gateway/services.py`
+
+已实现：
+- `_CONTEXT_CONFIGURABLE_KEYS` 已包含 `subagent_mode`（第149-171行）
+- `merge_run_context_overrides` 将 `subagent_mode` 透传到 configurable
+
+### 6.3 路由器 SOUL.md 改动 ✓
+
+**文件**：`.deer-flow/agents/f0e75f44f7594053ba1567ed89258f35/SOUL.md`
+
+已更新：
+- 角色扩展：增加"在确定模式后，调用相应子 Agent 执行并对结果进行质检"的职责
+- 工具描述：已声明 router_quality_check 工具
+
+### 6.4 新增路由器质检工具 ✓
+
+**文件**：`packages/harness/deerflow/tools/builtins/router_quality_tool.py`
+
+已实现：
+```python
+@tool("router_quality_check", parse_docstring=True, return_direct=True)
+def router_quality_check(original_question: str, agent_output: str) -> str:
+    """质检工具 — 判断子 Agent 输出是否完整覆盖用户问题"""
+```
+
+## 7. 数据流
+
+```
+用户问题
+    │
+    ▼
+路由器 SOUL.md 判断模式
+    │
+    ▼
+启动子 Agent Run（context.subagent_mode = rag）
+    │
+    ▼
+子 Agent SOUL.md + tool_groups 执行
+    │
+    ▼
+StreamBridge 缓存完整结果
+    │
+    ▼
+路由器调用 router_quality_check 质检
+    │
+    ├── passed=true → 流式输出到前端
+    └── passed=false → 重新匹配模式（最多2次重试）
+```
+
+## 8. 测试计划
+
+- **单元测试**：`tests/test_router_subagent.py` — 测试模式判断、质检逻辑、重试机制
+- **集成测试**：手动调用 `/api/threads/{thread_id}/runs/stream`，验证完整流程
+- **质检提示词测试**：针对不同问题类型测试质检结果的准确性
+
+## 9. 依赖项
+
+- 路由器复用现有 Gateway API，无需新建接口
+- 质检使用 LLM（deepseek-chat 或配置中指定的模型）
+- tool_groups 机制依赖系统级 config.yaml 中的工具组定义

frontend-web/.env.development

@@ -0,0 +1,39 @@
+# 本地开发（pnpm dev）— 与原先 .env 保持一致
+# 个人覆盖请新建 .env.development.local（已 gitignore，优先级更高）
+
+# Gateway / DeerFlow API
+VITE_BACKEND_BASE_URL=http://127.0.0.1:8001
+VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api
+
+# 轻应用「新建笔记」系列接口
+VITE_NOTE_API_BASE_URL=http://47.88.25.99:8000
+# CMZS后端接口
+VITE_API_BASE_URL=https://ch1.b.uat.4.cn/zncm
+# 佳来模型对话接口
+VITE_AIPI_CHAT_URL=https://ch1.b.uat.4.cn/gpt
+# 多轮检索接口
+VITE_AIPI_GENERATE_CHAT_URL=https://ch1.b.uat.4.cn/jialai_b1_chat
+VITE_AIPI_TASK_CHAT_URL=https://ch1.b.uat.4.cn/qq_b1_chat
+VITE_AIPI_KNOWLEDGE_URL=https://chlib.b.uat.4.cn/knowlibrary
+VITE_AIPI_B1COH_URL=https://ch1.b.uat.4.cn/web
+VITE_AIPI_B2ACTOR_URL=https://ty.b.uat.4.cn
+VITE_AIPI_B2ACTOR_XWT_PATH=/fromB/toXWT?isFrame=1
+VITE_AIPI_KNOWLEDGE_IFRAME_API_URL=https://ch1.b.uat.4.cn/knowes/api/iframeKnowledgeUrl
+VITE_AIPI_KNOWLEDGE_IFRAME_SKIN=red
+VITE_AIPI_B2ACTOR_XWT_PATH=/fromB/toXWT?isFrame=1
+VITE_AIPI_KNOWLEDGE_IFRAME_API_URL=https://ch1.b.uat.4.cn/knowes/api/iframeKnowledgeUrl
+VITE_AIPI_KNOWLEDGE_IFRAME_SKIN=red
+VITE_AIPI_MOPECHAT_URL=https://ch1.b.uat.4.cn/likun_b1_mope
+VITE_AIPI_BACKENP_URL=https://knowledgetoolserver.b.uat.4.cn
+# 我的笔记前端
+VITE_AIPI_FRONTEND_URL=https://knowledgetoolserver.b.uat.4.cn
+VITE_AIPI_CONSUMER_URL=https://ch1.b.uat.4.cn/consumer
+# MaxKey 鉴权（getTokenByOnlineTicket）
+VITE_AUTH_BASE_URL=https://auth.y.sit.4.cn
+VITE_AIPI_PGLINKTO_URL=https://pg.b.uat.4.cn
+VITE_AIPI_XKLINKTO_URL=https://kz.b.uat.4.cn
+# 可选：Canvas 独立 LangGraph 地址（不设则回退到 VITE_LANGGRAPH_BASE_URL）
+# VITE_CANVAS_LANGGRAPH_BASE_URL=
+
+# 我的笔记是否显示，侧边栏
+VITE_STUDIO_ENABLED=false

frontend-web/.env.development.local.example

@@ -0,0 +1,24 @@
+# 复制为 .env.development.local，仅本机生效，不提交 Git
+# 直连本机 Gateway（需后端 CORS_ORIGINS 包含 http://127.0.0.1:5173 等）
+
+VITE_BACKEND_BASE_URL=http://127.0.0.1:8001
+VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api
+# 佳来模型对话接口
+VITE_AIPI_CHAT_URL=https://ch1.b.uat.4.cn/gpt
+# 多轮检索接口
+VITE_AIPI_GENERATE_CHAT_URL=https://ch1.b.uat.4.cn/jialai_b1_chat
+VITE_AIPI_TASK_CHAT_URL=https://ch1.b.uat.4.cn/qq_b1_chat
+VITE_AIPI_KNOWLEDGE_URL=https://chlib.b.uat.4.cn/knowlibrary
+VITE_AIPI_B1COH_URL=https://ch1.b.uat.4.cn/web
+VITE_AIPI_B2ACTOR_URL=https://ty.b.uat.4.cn
+VITE_AIPI_B2ACTOR_XWT_PATH=/fromB/toXWT?isFrame=1
+VITE_AIPI_KNOWLEDGE_IFRAME_API_URL=https://ch1.b.uat.4.cn/knowes/api/iframeKnowledgeUrl
+VITE_AIPI_KNOWLEDGE_IFRAME_SKIN=red
+VITE_AIPI_MOPECHAT_URL=https://ch1.b.uat.4.cn/likun_b1_mope
+VITE_AIPI_BACKENP_URL=https://knowledgetoolserver.b.uat.4.cn
+VITE_AIPI_CONSUMER_URL=https://ch1.b.uat.4.cn/consumer
+VITE_AUTH_BASE_URL=https://auth.y.sit.4.cn
+VITE_AIPI_PGLINKTO_URL=https://pg.b.uat.4.cn
+VITE_AIPI_XKLINKTO_URL=https://kz.b.uat.4.cn
+
+# VITE_NOTE_API_BASE_URL=http://127.0.0.1:8000

frontend-web/.env.example

@@ -1,9 +1,40 @@
-# 复制为 .env 后按需修改（Vite 仅暴露以 VITE_ 开头的变量）
-# 直连本机 Gateway 时使用；若浏览器报 CORS，请在网关环境设置 CORS_ORIGINS，包含前端源站，例如：
-#   CORS_ORIGINS=http://127.0.0.1:5173,http://localhost:5173
+# 环境变量说明（Vite 仅暴露以 VITE_ 开头的变量）
+#
+# ┌─────────────────┬──────────────────────────────────────────────────┐
+# │ 命令            │ 生效文件                                          │
+# ├─────────────────┼──────────────────────────────────────────────────┤
+# │ pnpm dev        │ .env.development + .env.development.local        │
+# │ pnpm build      │ .env.production + .env.production.local          │
+# │ pnpm build:network │ .env.network + .env.network.local（内网地址） │
+# │ scripts/start-* │ 脚本注入的环境变量会覆盖上述文件（见下方说明）      │
+# └─────────────────┴──────────────────────────────────────────────────┘
+#
+# 推荐：
+# - 日常本地开发：改 .env.development（已提交，团队默认 UAT 地址）
+# - 本机连 127.0.0.1:8001：复制 .env.development.local.example → .env.development.local
+# - 内网打包部署：改 .env.network 后执行 pnpm build:network（或改 .env.production 后 pnpm build）
+#
+# 若浏览器直连后端报 CORS，请在 Gateway 配置 CORS_ORIGINS，包含前端源站，例如：
+#   CORS_ORIGINS=http://127.0.0.1:5173,http://localhost:5173,http://127.0.0.1:5174
 
-VITE_BACKEND_BASE_URL=https://ch1.b.uat.4.cn/deerflow
-VITE_LANGGRAPH_BASE_URL=https://ch1.b.uat.4.cn/deerflow/api
+# --- 开发环境（见 .env.development）---
+# VITE_BACKEND_BASE_URL=https://ch1.b.uat.4.cn/deerflow
+# VITE_LANGGRAPH_BASE_URL=https://ch1.b.uat.4.cn/deerflow/api
+# VITE_NOTE_API_BASE_URL=http://47.88.25.99:8000
 
-# 轻应用「新建笔记」系列接口（与 DeerFlow Gateway 分离）
-VITE_NOTE_API_BASE_URL=http://47.88.25.99:8000
+# --- 生产打包（见 .env.production）---
+# 部署前修改 .env.production 中的地址，再执行 pnpm build
+
+# MaxKey 鉴权根地址（无界 onlineTicket 换 token）
+# VITE_AUTH_BASE_URL=https://auth.y.sit.4.cn
+# VITE_AIPI_CONSUMER_URL=https://ch1.b.uat.4.cn/consumer
+
+# VITE_AIPI_B2ACTOR_URL=https://ty.b.uat.4.cn
+# VITE_AIPI_B2ACTOR_XWT_PATH=/fromB/toXWT?isFrame=1
+# VITE_AIPI_KNOWLEDGE_IFRAME_API_URL=https://ch1.b.uat.4.cn/knowes/api/iframeKnowledgeUrl
+# VITE_AIPI_KNOWLEDGE_IFRAME_SKIN=red
+
+# 可选
+# VITE_CANVAS_LANGGRAPH_BASE_URL=
+# VITE_STATIC_WEBSITE_ONLY=
+# VITE_GITHUB_OAUTH_TOKEN=

frontend-web/.env.network

@@ -0,0 +1,32 @@
+# 内网 / 局域网生产打包（npm run build:network 或 pnpm build:network）
+# 打包前请将 192.168.1.100 改为实际服务器 IP；变量会写入 dist，运行时不可再改
+
+# Gateway / DeerFlow API（与 offline-backend DEPLOY 文档一致）
+VITE_BACKEND_BASE_URL=http://47.88.25.99:7001
+VITE_LANGGRAPH_BASE_URL=http://47.88.25.99:7001/api
+
+# 轻应用「新建笔记」系列接口
+VITE_NOTE_API_BASE_URL=http://192.168.1.100:8000
+# CMZS 后端接口
+VITE_API_BASE_URL=http://192.168.1.100/zncm
+# 佳来模型对话接口
+VITE_AIPI_CHAT_URL=http://192.168.1.100/gpt
+# 多轮检索接口
+VITE_AIPI_GENERATE_CHAT_URL=http://192.168.1.100/jialai_b1_chat
+VITE_AIPI_TASK_CHAT_URL=http://192.168.1.100/qq_b1_chat
+VITE_AIPI_KNOWLEDGE_URL=http://192.168.1.100/knowlibrary
+VITE_AIPI_B1COH_URL=http://192.168.1.100/web
+VITE_AIPI_B2ACTOR_URL=http://192.168.1.100
+VITE_AIPI_B2ACTOR_XWT_PATH=/fromB/toXWT?isFrame=1
+VITE_AIPI_KNOWLEDGE_IFRAME_API_URL=http://192.168.1.100/knowes/api/iframeKnowledgeUrl
+VITE_AIPI_KNOWLEDGE_IFRAME_SKIN=red
+VITE_AIPI_MOPECHAT_URL=http://192.168.1.100/likun_b1_mope
+VITE_AIPI_BACKENP_URL=http://192.168.1.100
+VITE_AIPI_CONSUMER_URL=http://192.168.1.100/consumer
+# MaxKey 鉴权（getTokenByOnlineTicket，内网部署请改为实际地址）
+VITE_AUTH_BASE_URL=https://auth.y.sit.4.cn
+VITE_AIPI_PGLINKTO_URL=http://192.168.1.100
+VITE_AIPI_XKLINKTO_URL=http://192.168.1.100
+
+# 可选：Canvas 独立 LangGraph 地址
+# VITE_CANVAS_LANGGRAPH_BASE_URL=

frontend-web/.env.production

@@ -0,0 +1,31 @@
+# 生产打包（pnpm build）— 部署前请改成实际内网/生产地址
+# 打包后变量会写入 dist，运行时不可再改
+
+# Gateway / DeerFlow API
+VITE_BACKEND_BASE_URL=https://ch1.b.uat.4.cn/deerflow
+VITE_LANGGRAPH_BASE_URL=https://ch1.b.uat.4.cn/deerflow/api
+
+# 轻应用「新建笔记」系列接口
+VITE_NOTE_API_BASE_URL=https://your-intranet-host/note-api
+# 佳来模型对话接口
+VITE_AIPI_CHAT_URL=https://ch1.b.uat.4.cn/gpt
+# 多轮检索接口
+VITE_AIPI_GENERATE_CHAT_URL=https://ch1.b.uat.4.cn/jialai_b1_chat
+VITE_AIPI_TASK_CHAT_URL=https://ch1.b.uat.4.cn/qq_b1_chat
+VITE_AIPI_KNOWLEDGE_URL=https://chlib.b.uat.4.cn/knowlibrary
+VITE_AIPI_B1COH_URL=https://ch1.b.uat.4.cn/web
+VITE_AIPI_B2ACTOR_URL=https://ty.b.uat.4.cn
+VITE_AIPI_B2ACTOR_XWT_PATH=/fromB/toXWT?isFrame=1
+VITE_AIPI_KNOWLEDGE_IFRAME_API_URL=https://ch1.b.uat.4.cn/knowes/api/iframeKnowledgeUrl
+VITE_AIPI_KNOWLEDGE_IFRAME_SKIN=red
+VITE_AIPI_MOPECHAT_URL=https://ch1.b.uat.4.cn/likun_b1_mope
+VITE_AIPI_BACKENP_URL=https://knowledgetoolserver.b.uat.4.cn
+VITE_AIPI_CONSUMER_URL=https://ch1.b.uat.4.cn/consumer
+# MaxKey 鉴权（getTokenByOnlineTicket）
+VITE_AUTH_BASE_URL=https://auth.y.uat.4.cn
+VITE_AIPI_PGLINKTO_URL=https://pg.b.uat.4.cn
+VITE_AIPI_XKLINKTO_URL=https://kz.b.uat.4.cn
+VITE_AIPI_FRONTEND_URL=https://knowledgetoolserver.b.uat.4.cn
+
+# 可选：Canvas 独立 LangGraph 地址
+# VITE_CANVAS_LANGGRAPH_BASE_URL=

frontend-web/.env.production.local.example

@@ -0,0 +1,5 @@
+# 复制为 .env.production.local，打包前临时覆盖生产地址（不提交 Git）
+
+# VITE_BACKEND_BASE_URL=https://your-intranet-host/deerflow
+# VITE_LANGGRAPH_BASE_URL=https://your-intranet-host/deerflow/api
+# VITE_NOTE_API_BASE_URL=https://your-intranet-host/note-api

frontend-web/.env.sit

@@ -0,0 +1,30 @@
+# SIT 环境打包（pnpm build:sit / npm run build:sit）— 接口地址为 UAT 的 sit 版本
+# 打包后变量会写入 dist，运行时不可再改
+
+# Gateway / DeerFlow API
+VITE_BACKEND_BASE_URL=https://ch1.b.sit.4.cn/deerflow
+VITE_LANGGRAPH_BASE_URL=https://ch1.b.sit.4.cn/deerflow/api
+
+# 轻应用「新建笔记」系列接口
+VITE_NOTE_API_BASE_URL=https://your-intranet-host/note-api
+# 佳来模型对话接口
+VITE_AIPI_CHAT_URL=https://ch1.b.sit.4.cn/gpt
+# 多轮检索接口
+VITE_AIPI_GENERATE_CHAT_URL=https://ch1.b.sit.4.cn/jialai_b1_chat
+VITE_AIPI_TASK_CHAT_URL=https://ch1.b.sit.4.cn/qq_b1_chat
+VITE_AIPI_KNOWLEDGE_URL=https://chlib.b.sit.4.cn/knowlibrary
+VITE_AIPI_B1COH_URL=https://ch1.b.sit.4.cn/web
+VITE_AIPI_B2ACTOR_URL=https://ty.b.sit.4.cn
+VITE_AIPI_B2ACTOR_XWT_PATH=/fromB/toXWT?isFrame=1
+VITE_AIPI_KNOWLEDGE_IFRAME_API_URL=https://ch1.b.sit.4.cn/knowes/api/iframeKnowledgeUrl
+VITE_AIPI_KNOWLEDGE_IFRAME_SKIN=red
+VITE_AIPI_MOPECHAT_URL=https://ch1.b.sit.4.cn/likun_b1_mope
+VITE_AIPI_BACKENP_URL=https://knowledgetoolserver.b.sit.4.cn
+VITE_AIPI_CONSUMER_URL=https://ch1.b.sit.4.cn/consumer
+# MaxKey 鉴权（getTokenByOnlineTicket）
+VITE_AUTH_BASE_URL=https://auth.y.sit.4.cn
+VITE_AIPI_PGLINKTO_URL=https://pg.b.sit.4.cn
+VITE_AIPI_XKLINKTO_URL=https://kz.b.sit.4.cn
+
+# 可选：Canvas 独立 LangGraph 地址
+# VITE_CANVAS_LANGGRAPH_BASE_URL=

frontend-web/docs/AI_WRITING_BACKEND_DEV_ZH.md

@@ -1,916 +0,0 @@
-# AI 写作 — 后端开发文档
-
-> **本文档目的**：帮助后端开发者快速理解 AI 写作子系统的代码结构、Graph 拓扑、数据流、持久化、容错策略和扩展点。
->
-> **配套文档**：
-> - 前端：`frontend-web/docs/ai-writing-frontend-dev.md`
-> - 故障排查：`frontend-web/docs/ai-writing-说明.md`
-> - 前端 API 字段索引：`frontend-web/docs/ai-writing-assistant-backend-api.md`
-
----
-
-## 一、产品定位与技术架构
-
-### 产品定位
-**杂志社协作写作子系统**：由 4 个 AI Agent（**素材收集专家 / 作家 / 编辑 / 系统**）协作完成一篇文章，通过 4 个用户干预点参与决策。
-
-### 技术栈
-- **编排框架**：LangGraph（独立 StateGraph，不复用主 lead agent 的 middleware 链）
-- **节点驱动**：异步 LLM 调用（`langchain_openai` 等），支持流式 token 推送到 SSE
-- **状态持久化**：LangGraph checkpointer（SQLite 文件，跨重启可恢复）
-- **业务数据**：MySQL `ai_writing_sessions` 表
-- **协议**：SSE（Server-Sent Events）推进度 + REST 控制流
-
-### 与主 Agent 的关系
-**完全独立**。AI 写作 graph 不通过 `make_lead_agent` 也不走主 agent 的 18 层 middleware。它有自己的 StateGraph、自己的 checkpointer、自己的路由前缀（`/api/ai-writing/*`），跟主 agent 解耦。
-
----
-
-## 二、目录结构
-
-```
-offline-backend-20260512/backend/
-├── app/gateway/
-│   ├── routers/
-│   │   └── ai_writing.py                # FastAPI 路由 + 模块级状态字典 + SSE 生成器（1000+ 行，核心）
-│   ├── ai_writing_cleanup.py            # 定期清理 + cron 调度（独立模块）
-│   └── app.py                           # lifespan 启动/停止清理任务、检测多 worker、关闭 checkpointer
-│
-└── packages/harness/deerflow/
-    ├── agents/ai_writing/
-    │   ├── __init__.py                  # 暴露 AI_WRITING_GRAPH + 工厂函数
-    │   ├── graph.py                     # ⭐ StateGraph 定义 + 4 个 pause 节点 + checkpointer 工厂（538 行）
-    │   ├── state.py                     # AIWritingState TypedDict（121 行）
-    │   │
-    │   ├── nodes/                        # ── Graph 节点 ──
-    │   │   ├── _utils.py                # LLM 工具：parse_json, ThinkTagParser, llm_json
-    │   │   ├── intent_parser.py         # 节点 1：意图解析
-    │   │   ├── researcher.py            # 节点 2：素材检索（支持流式 progress）
-    │   │   ├── writer_outline.py        # 节点 3：大纲规划
-    │   │   ├── writer_draft.py          # 节点 4：草稿生成（按章节流式）
-    │   │   └── editor.py                # 节点 5：编辑审核（3 维度并行流式）
-    │   │
-    │   ├── prompts/                      # ── Prompt 模板 ──
-    │   │   ├── __init__.py
-    │   │   ├── researcher_prompts.py
-    │   │   ├── writer_prompts.py
-    │   │   └── editor_prompts.py
-    │   │
-    │   └── search/                       # ── 素材检索 provider ──
-    │       ├── base.py                   # SearchResult / SearchProvider 接口
-    │       ├── duckduckgo_search.py
-    │       ├── internet_search.py        # 互联网检索（默认）
-    │       ├── intranet_stub.py          # 内网检索占位（按部署接入）
-    │       └── demo_search.py            # 离线 demo 数据
-    │
-    └── persistence/ai_writing_sessions/
-        ├── __init__.py                   # AIWritingSessionRepository 工厂
-        ├── model.py                      # ORM：AIWritingSessionRow
-        └── sql.py                        # CRUD 实现（含清理用的 list_older_than / delete_by_ids）
-```
-
----
-
-## 三、Graph 拓扑（最重要）
-
-### StateGraph 节点 + 边
-
-```
-                     START
-                       │
-                       ↓
-              ┌─────────────────┐
-              │  intent_parser  │   解析用户意图（确定 article_type / target_audience）
-              └────────┬────────┘
-                       ↓
-              ┌─────────────────┐
-              │   researcher    │   ← (re_search 回到这里)
-              └────────┬────────┘
-                       ↓ (after_researcher: ⼟材 ready)
-              ┌──────────────────────┐
-              │  pause_material      │   ⚙️ PAUSE-1：素材确认
-              └─┬──────────┬─────────┘
-                │ confirm  │ re_search
-                ↓          └→ researcher
-              ┌─────────────────┐
-              │ writer_outline  │   ← (re_outline 回到这里)
-              └────────┬────────┘
-                       ↓
-              ┌──────────────────────┐
-              │  pause_outline       │   ⚙️ PAUSE-2：大纲确认
-              └─┬──────────┬─────────┘
-                │ confirm  │ re_outline
-                ↓          └→ writer_outline
-              ┌─────────────────┐
-              │  writer_draft   │   ← (素材补充后回到这里)
-              └─┬───────────────┘
-                ↓ (after_writer_draft)
-        ┌──────┴────────────────┐
-        ↓                       ↓
-  ┌──────────────────┐   ┌────────────────────┐
-  │ pause_section_   │   │ pause_draft        │   ⚙️ PAUSE-3：草稿确认
-  │ help（素材不足）│   │                    │
-  └─┬─────────────┬──┘   └─┬────────┬───┬─────┘
-    │ supplement  │ del/    │        │   │ to_editor
-    │↓            │ loose   │        │ user_revise
-    research     writer_     │ final  ↓
-                  draft     │ ize   writer_draft
-                            │↓
-                            done
-                                       │
-                            (to_editor)│
-                                       ↓
-                              ┌─────────────────┐
-                              │     editor      │   3 维度并行流式审核
-                              └────────┬────────┘
-                                       ↓ (after_review)
-                              ┌──────────────────────┐
-                              │  pause_review        │   ⚙️ PAUSE-4：审核确认
-                              └─┬──────────┬─────────┘
-                                │ confirm  │ revise
-                                │↓         └→ writer_draft
-                              done
-```
-
-### 节点定义位置一览
-
-| 节点名 | 实现文件 | 类型 | 流式? |
-|---|---|---|---|
-| `intent_parser` | `nodes/intent_parser.py` | async function | 否 |
-| `researcher` | `nodes/researcher.py` | async function | 是（research_progress） |
-| `pause_material` | `graph.py` 顶部 | async, 调 `interrupt()` | — |
-| `writer_outline` | `nodes/writer_outline.py` | async function | 是（outline_chunk） |
-| `pause_outline` | `graph.py` 顶部 | async, 调 `interrupt()` | — |
-| `writer_draft` | `nodes/writer_draft.py` | async function | 是（draft_chunk，按章节） |
-| `pause_section_help` | `graph.py` 顶部 | async, 调 `interrupt()` | — |
-| `pause_draft` | `graph.py` 顶部 | async, 调 `interrupt()` | — |
-| `editor` | `nodes/editor.py` | async function | 是（review_chunk，3 路并行） |
-| `pause_review` | `graph.py` 顶部 | async, 调 `interrupt()` | — |
-
-### 条件路由函数（graph.py）
-
-| 函数 | 在哪个节点之后 | 路由依据 |
-|---|---|---|
-| `after_researcher` | researcher | 是否找到素材 |
-| `after_material_pause` | pause_material | `state["status"]` 是 researching 还是 writing_outline |
-| `after_outline_pause` | pause_outline | 同上，writing_outline 还是 writing_draft |
-| `after_writer_draft` | writer_draft | 是否有 blocked_sections |
-| `after_section_help_pause` | pause_section_help | status |
-| `after_draft_pause` | pause_draft | done / revising / reviewing |
-| `after_review` | editor | review_result.verdict 是 pass 还是 reject + revision_count 上限 |
-| `after_review_pause` | pause_review | done / writing_draft |
-
----
-
-## 四、State 定义（state.py）
-
-```python
-class AIWritingState(TypedDict):
-    # —— 写作配置（启动时填充）——
-    user_intent: str
-    article_type: str
-    target_audience: str
-    word_count_target: int
-    keyword_count: int            # 1-10，默认 6
-    writing_mode: str             # "strict" | "loose"
-
-    # —— Agent 产出 ——
-    material_package: Optional[MaterialPackage]      # 素材收集专家
-    current_outline: Optional[Outline]               # 作家
-    drafts: Annotated[List[DraftArticle], operator.add]  # 累计所有版本
-    current_draft: Optional[DraftArticle]            # 最新草稿
-    review_result: Optional[ReviewResult]            # 编辑
-
-    # —— 用户干预 ——
-    last_user_intervention: Optional[UserInterventionPayload]
-    blocked_sections: Optional[List[BlockedSection]]  # 素材不足的章节
-
-    # —— 流程控制 ——
-    revision_count: int
-    max_revisions: int            # 默认 3
-    status: WritingStatus
-
-    # —— SSE 推送队列 ——
-    progress_events: Annotated[List[dict], operator.add]  # 累加，不覆盖
-```
-
-### State 字段的特殊语义
-
-- **`Annotated[..., operator.add]`** — LangGraph 的累加 reducer，节点 return 时 `progress_events: [evt]` 会**追加**到现有列表，而不是替换
-- **TypedDict** — 运行时是普通 dict，类型注解仅供 IDE 提示
-- **节点输出** — 节点 return 的 dict 只需要包含**要更新的字段**，未指定的字段保持不变
-
----
-
-## 五、路由层（app/gateway/routers/ai_writing.py）
-
-### 14 个接口一览
-
-| HTTP | 路径 | 用途 | 鉴权 |
-|---|---|---|---|
-| POST | `/api/ai-writing/start` | 启动写作，返回 session_id | 用户 |
-| GET | `/api/ai-writing/{id}/stream` | SSE 进度流 | 用户 |
-| POST | `/api/ai-writing/{id}/resume` | 提交用户干预 | 用户 |
-| GET | `/api/ai-writing/{id}/state` | 查 graph 状态快照（调试用） | 用户 |
-| GET | `/api/ai-writing/sessions` | 列出当前用户的历史会话 | 用户 |
-| GET | `/api/ai-writing/sessions/{id}` | 获取单个历史会话 | 用户 |
-| PATCH | `/api/ai-writing/sessions/{id}` | 重命名会话 | 用户 |
-| DELETE | `/api/ai-writing/sessions/{id}` | 删除会话 | 用户 |
-| PUT | `/api/ai-writing/sessions/{id}/transcript` | 保存对话时间线（**fire-and-forget**） | 用户 |
-| GET | `/api/ai-writing/article-types` | 列出文章类型 | 用户 |
-| POST | `/api/ai-writing/article-types` | 新增文章类型 | 用户（建议改成 admin） |
-| PATCH | `/api/ai-writing/article-types/{id}` | 更新文章类型 | 用户 |
-| DELETE | `/api/ai-writing/article-types/{id}` | 删除文章类型 | 用户 |
-| POST | `/api/ai-writing/admin/cleanup` | **手动触发清理** | admin only |
-
-### 模块级状态字典（关键设计 — 也是 worker 限制的根源）
-
-```python
-# 每个 session_id 对应一份内存状态。多 worker 部署时每个 worker 一份，互不共享。
-_event_queues:          dict[str, asyncio.Queue]  # SSE 事件队列
-_session_pending_pause: dict[str, tuple]          # 挂起的 await_user 事件（供重连重投）
-_session_model_names:   dict[str, str]            # 用户选的模型
-_session_interventions: dict[str, list]           # 累计干预历史
-_session_repos:         dict[str, repo]           # DB 仓库引用
-_session_user_ids:      dict[str, str]            # 用户 id
-_session_article_types: dict[str, list]           # 动态文章类型列表
-_session_error_flags:   dict[str, bool]
-_inflight_graph_tasks:  set[asyncio.Task]          # in-flight task 注册表（lifespan drain 用）
-_recovery_lock:         asyncio.Lock              # 跨 worker 会话恢复的并发锁
-```
-
-⚠️ **关键限制**：这些都是 per-process 内存。多 worker 部署下，worker B 看不到 worker A 的状态 → SSE 事件分发失败。详见 `frontend-web/docs/ai-writing-说明.md` 第五、六章。
-
-### `_stream_graph_segment`（graph 推进函数）
-
-`/start` 和 `/resume` 都调用这个函数（用 `_spawn_graph_task` 包装），负责：
-1. 调 `graph.astream(input_or_command, config=config, stream_mode="updates")`
-2. 把每个 chunk 解析成 SSE 事件 put 进 `_event_queues[session_id]`
-3. 遇到 `__interrupt__` → 推 `await_user` 事件 → 返回（不关闭 queue）
-4. 遇到 END → 推 `done` 事件 → 关闭 queue（put None 哨兵）
-5. 任何异常 → 推 `error` 事件 → 关闭 queue
-6. finally 段：更新 DB 最终状态、清理所有模块字典
-
-### SSE 生成器 `_sse_generator`
-
-`GET /stream` 的实现，从 `_event_queues[session_id]` 拿事件 → `_sse(event, data)` 序列化 → yield 给 fastapi `StreamingResponse`。
-
-**关键逻辑**：
-- 队列不存在时**等待 5 秒**，期间触发 `_recover_session`（跨 worker / 进程重启恢复）
-- `_sse()` 三层兜底：`default=str` → 手写 notice 帧 → 永不抛 TypeError
-- 收到 None 哨兵 → 关闭流
-
-### `_recover_session`（跨 worker 恢复）
-
-当 worker 内存里没有 session_id 但 sqlite checkpointer 有快照时：
-1. 从 checkpointer 读出 state snapshot
-2. 重建 `_event_queues[sid]` 队列
-3. 从 snapshot 提取当前 interrupt 负载，put 进队列
-4. 同时尽量恢复 `_session_repos`、`_session_user_ids` 等
-
-返回三种状态：
-- `"interrupted"` — 图停在干预点，已重建队列
-- `"finished"` — 图已完成或中断在节点中间，推 done/error 事件后关闭
-- `"unrecoverable"` — sqlite 也没有这个 thread_id → 真的丢了
-
-### `_spawn_graph_task` / `wait_for_inflight_graph_tasks`（优雅关闭）
-
-- `_spawn_graph_task(coro)` — 启 task 并自动登记到 `_inflight_graph_tasks`，完成时反登记
-- `wait_for_inflight_graph_tasks(timeout)` — lifespan shutdown 等所有 task 跑到下一个 interrupt / END（默认 30s），超时则 cancel 强制结束
-
----
-
-## 六、Graph 与持久化（graph.py）
-
-### Lazy 单例 + 自动降级
-
-```python
-AI_WRITING_GRAPH = None                      # 模块级槽位（测试可 monkeypatch）
-_async_checkpointer_singleton = None         # checkpointer 单例
-
-async def get_ai_writing_graph():
-    """懒加载 graph。第一次调用时按 config.yaml 决定 checkpointer。"""
-    global AI_WRITING_GRAPH
-    if AI_WRITING_GRAPH is not None:
-        return AI_WRITING_GRAPH
-    checkpointer = await _get_async_checkpointer()
-    AI_WRITING_GRAPH = build_ai_writing_graph(checkpointer=checkpointer)
-    return AI_WRITING_GRAPH
-```
-
-### Checkpointer 优先级（_get_async_checkpointer）
-
-```
-1. config.yaml 的 checkpointer 段
-   ├── type: sqlite    → AsyncSqliteSaver(aiosqlite.connect(...))
-   ├── type: postgres  → AsyncPostgresSaver(AsyncConnectionPool(...))
-   └── type: memory    → InMemorySaver
-
-2. 任何初始化失败                 → InMemorySaver（降级，打 warning）
-3. 未配置 checkpointer 段         → InMemorySaver（降级，打 warning）
-4. 未知 type（如 "mysql"）         → InMemorySaver（降级，打 warning）
-```
-
-**核心契约**：`_get_async_checkpointer()` **绝不抛异常**，永远返回一个可用的 saver。这是「写作流程能完整继续」契约的关键。
-
-### Shutdown
-
-`shutdown_ai_writing_graph()` 在 lifespan shutdown 时调用：
-- 关闭 `aiosqlite.Connection` / `AsyncConnectionPool`
-- 清空 `AI_WRITING_GRAPH` / `_async_checkpointer_singleton`
-
-调用顺序（详见 `app/gateway/app.py` lifespan）：
-1. 停清理任务
-2. `wait_for_inflight_graph_tasks(30s)`
-3. `shutdown_ai_writing_graph()`
-
----
-
-## 七、节点详解（nodes/）
-
-### `nodes/_utils.py`（公共工具）
-
-| 函数 / 类 | 用途 |
-|---|---|
-| `get_model(config, model_name)` | 从 config.configurable 拿 model_name 或回退默认 |
-| `parse_json(text, fallback)` | 鲁棒 JSON 解析（支持代码块、不完整 JSON、转义错误） |
-| `_extract_balanced(text)` | 找出第一对平衡的 `{...}` |
-| `_repair_json(text)` | 修复常见的 JSON 错误（缺尾引号等） |
-| `ThinkTagParser` | 流式解析 `<think>...</think>` 标签（思考 / 正文分流） |
-| `llm_json(system, user, fallback, config)` | 调 LLM 并解析 JSON 输出 |
-| `count_words(text)` | 中文 + 英文混合计字数 |
-
-### `nodes/intent_parser.py` — 意图解析
-
-- 调 LLM 把用户意图（`user_intent` 字符串）解析成结构化字段：`article_type`、`target_audience`、`word_count_target`
-- 用户已经在 `AIWritingRequest` 里指定的字段会**覆盖** LLM 推断
-- 输出：更新 state 的对应字段，推 `step_done` 事件
-
-### `nodes/researcher.py` — 素材检索
-
-- 根据 `user_intent` 用 LLM 生成 N 个关键词（N = `keyword_count`，默认 6）
-- 用 `search/*` 的 provider 并行检索
-- 流式推 `research_progress` 事件（"正在搜索关键词 X 中..."）
-- 输出：`material_package = {keywords, materials, summary}`，推 `materials_ready`
-
-### `nodes/writer_outline.py` — 大纲规划
-
-- 输入：`user_intent` + `material_package`
-- 调 LLM 流式生成大纲 JSON，期间推 `outline_chunk`（正文 + thinking 分流）
-- 解析最终 JSON → `current_outline`，推 `outline_ready`
-
-### `nodes/writer_draft.py` — 草稿生成（最复杂）
-
-- 按大纲**逐章节**调 LLM 生成正文，每章节独立流式推 `draft_chunk`
-- 检测 LLM 是否「拒答」（`_looks_like_refusal`），如果是则换提示重试
-- **严格模式下**：如果章节关联的素材不足，把该章节加入 `blocked_sections`，触发 `pause_section_help`
-- 完成所有章节后拼成 `current_draft.full_markdown`，推 `draft_ready`
-
-### `nodes/editor.py` — 编辑审核（3 维度并行）
-
-- 3 个维度（**fact / logic / language**）并行调 LLM
-- 每个维度独立流式推 `review_chunk`，完成后推 `review_item_done`
-- 三个都完成后聚合成 `review_result`，推 `review_ready`
-- 评分加权（fact 40% + logic 30% + language 30%），超过 `pass_threshold`（默认 80）verdict = `pass`
-
----
-
-## 八、持久化（persistence/ai_writing_sessions/）
-
-### `model.py` — ORM
-
-```python
-class AIWritingSessionRow(Base):
-    __tablename__ = "ai_writing_sessions"
-    id: Mapped[str]                        # = session_id（uuid）
-    user_id: Mapped[str | None]            # NULL = no-auth 模式
-    title: Mapped[str]                     # 从 user_intent 截取前 50 字
-    user_intent: Mapped[str | None]
-    status: Mapped[str]                    # in_progress / draft_ready / review_ready / done / error
-    draft_title: Mapped[str | None]
-    draft_markdown: Mapped[str | None]
-    completed_interventions: Mapped[str | None]   # JSON 字符串
-    review_result: Mapped[str | None]              # JSON 字符串
-    transcript: Mapped[str | None]                 # PortableLongText（MySQL→LONGTEXT，4GB）
-    created_at / updated_at: BeijingDateTime
-```
-
-### `sql.py` — Repository
-
-| 方法 | 用途 |
-|---|---|
-| `create(id, title, user_intent, user_id)` | 启动写作时建一行 |
-| `get(session_id, user_id)` | 取单个（带 user_id 权限校验） |
-| `list(user_id, limit)` | 列出当前用户的会话 |
-| `update(session_id, user_id, ...)` | 更新指定字段（其他保持不变） |
-| `delete(session_id, user_id)` | 删除（带权限校验） |
-| `list_older_than(cutoff, only_finished, limit)` | 清理用：列出过期 session_id |
-| `delete_by_ids(session_ids)` | 清理用：批量删除 |
-
-### Alembic 迁移
-
-- `20260517_03_ai_writing_transcript.py` — 加 transcript 列（TEXT）
-- `20260519_02_ai_writing_transcript_longtext.py` — MySQL 上把 transcript 改成 LONGTEXT（修 64KB 限制导致的 500）
-
----
-
-## 九、定期清理（ai_writing_cleanup.py）
-
-### 设计目标
-- 删超过 `retention_days`（默认 7）的旧会话
-- 联动清理：MySQL 业务行 + SQLite checkpointer 里的 thread 状态
-- **绝对不删正在写的会话**（活跃保护）
-
-### 关键函数
-
-```python
-async def run_cleanup_once(*, retention_days, only_finished=False, batch_size=500) -> dict
-```
-
-返回 `{deleted_db, deleted_checkpoints, skipped_active}`。
-
-执行流程：
-1. 调 `repo.list_older_than(cutoff, only_finished, batch_size)` 拿过期 id
-2. 从 `_event_queues.keys()` 拿活跃 session_id 集合 → **过滤掉所有仍在跑的**
-3. 对每个待删 id：调 `checkpointer.adelete_thread(id)` 删 checkpoint
-4. 调 `repo.delete_by_ids(ids)` 批量删 MySQL
-5. 循环直到本批 < batch_size
-
-### Cron 调度
-
-`cleanup_scheduler_loop()` 常驻后台任务：
-- 用 `croniter` 解析 `ai_writing.cleanup.cron`（默认 `"0 3 * * *"`，每天凌晨 3 点）
-- `asyncio.sleep` 到下次触发时间
-- 多 worker 用文件锁（`runtime_home() / ".ai_writing_cleanup.lock"`）做 leader election
-
-### Admin 手动触发
-
-`POST /api/ai-writing/admin/cleanup`：
-- 鉴权：`system_role == "admin"`
-- 可选覆盖 `retention_days` / `only_finished` / `batch_size`
-- 即使传 `retention_days: 0` 也不会秒杀活跃会话（活跃保护硬保证）
-
----
-
-## 十、配置（config.yaml）
-
-```yaml
-# Checkpointer：graph 状态持久化
-checkpointer:
-  type: sqlite                           # sqlite | postgres | memory
-  connection_string: .deer-flow/data/checkpoints.db
-
-# AI 写作子系统
-ai_writing:
-  # ── 清理调度 ─────────────────────────────────────────────
-  cleanup:
-    enabled: true
-    retention_days: 7
-    cron: "0 3 * * *"                    # 每天凌晨 3 点
-    delete_only_finished: false
-    batch_size: 500
-
-  # ── 素材收集专家（researcher）专用配置 ──────────────────
-  # 这两个模型名必须出现在顶层 models[] 段里；留空 / 不配则回退当前写作主模型。
-  # 拆出来是为了让「检索词生成 / 素材排序」这种结构化抽取任务可以走更轻量、
-  # 不带思考输出的小模型，省钱省时间，也避开写作主模型的思考干扰。
-  keyword_model: qwen3-4b-instruct       # 检索词生成（EXTRACT_KEYWORDS_*）
-  rank_model:    qwen3-4b-instruct       # 素材排序筛选（RANK_MATERIALS_*）
-
-  # 素材总量上限：合并去重后保留多少条素材进入大纲 / 草稿阶段
-  # 取值范围 [1, 100]，非法值或缺省回退 20。
-  # 每个检索词分到的检索条数 = ceil(max_materials / keyword_count)，
-  # 所以这个数越大，每个关键词向 provider 拉的条数越多，整体耗时也越长。
-  max_materials: 20
-
-  # ── 素材检索 provider ───────────────────────────────────
-  # internet(默认,DuckDuckGo) / intranet(内网 ES) / tavily / demo
-  search_provider: internet
-
-  # internet 模式：DuckDuckGo 区域代码（cn-zh / us-en / wt-wt 等）
-  ddg_region: "cn-zh"
-
-  # intranet 模式：对接内网知识库 ES 检索接口
-  # 接口契约（POST）：
-  #   payload  = {"query": "...", "knowledge_base_name": "<intranet_knowledge_base>", "ts": "yes"}
-  #   response = [{"page_content": "...", "metadata": {m_title, content, recUuid, m_publish, source1}}]
-  # 实现见 packages/harness/deerflow/agents/ai_writing/search/intranet_stub.py
-  intranet_search_url: http://10.106.57.180:7863/knowledge_base/search_docs_es
-  intranet_knowledge_base: samples       # 默认 samples，按部署的实际知识库名改
-```
-
-### 配置项与代码的对应关系
-
-| 配置键 | 默认值 | 取值范围 / 说明 | 读取位置 |
-|---|---|---|---|
-| `ai_writing.keyword_model` | 空（回退写作主模型） | 必须是 `models[]` 段里已声明的模型名 | `nodes/researcher.py` → `llm_json(..., model_name=keyword_model)` |
-| `ai_writing.rank_model` | 空（回退写作主模型） | 同上 | `nodes/researcher.py` → 排序分支 `llm_json(..., model_name=rank_model)` |
-| `ai_writing.max_materials` | `20` | `[1, 100]`，非法值回退 20；`_resolve_max_materials` 钳制 | `nodes/researcher.py:_DEFAULT_MAX_MATERIALS` |
-| `ai_writing.search_provider` | `"internet"` | `internet` / `intranet` / `tavily` / `demo` | `search/__init__.py:get_search_provider` |
-| `ai_writing.ddg_region` | `"cn-zh"` | DuckDuckGo 区域代码，仅 `internet` 模式生效 | 同上 |
-| `ai_writing.intranet_search_url` | `http://10.106.57.180:7863/knowledge_base/search_docs_es` | 仅 `intranet` 模式生效，POST JSON 接口 | `search/intranet_stub.py:_DEFAULT_ENDPOINT` |
-| `ai_writing.intranet_knowledge_base` | `"samples"` | 仅 `intranet` 模式生效，知识库 ID/名称 | 同上 |
-
-### 配置如何传到节点
-
-```
-config.yaml
-   └─ ai_writing: { ... }
-         │
-         ▼  _ai_writing_config() 取出整个 dict
-   routers/ai_writing.py:_make_config()
-         │  注入到 config.configurable.ai_writing_config
-         ▼
-   nodes/researcher.py
-     cfg = config.get("configurable", {})
-     ai_writing_config = cfg.get("ai_writing_config", {})
-     keyword_model = ai_writing_config.get("keyword_model")
-     rank_model    = ai_writing_config.get("rank_model")
-     max_materials = _resolve_max_materials(ai_writing_config.get("max_materials"))
-     provider      = get_search_provider(ai_writing_config)   # ← search_provider 等也从这里读
-```
-
-### 切换内网检索的最小步骤
-
-1. `config.yaml` 改 `ai_writing.search_provider: intranet`
-2. 填 `intranet_search_url` 和 `intranet_knowledge_base`（部署侧给）
-3. 内网 ES 接口若返回结构异常 / 网络抖动，researcher 节点会收集 `provider.errors` + `provider.raw_responses`，作为非致命 `notice` 事件推前端时间线（折叠显示原始响应体），**不会中断写作流程**
-4. 健康检查：可通过 `IntranetSearchProvider.health_check()` 单测，或直接发一笔 `/start` 看 `research_progress` 是否报错
-
-### 备注
-
-- `keyword_model` / `rank_model` 只影响素材收集专家的 LLM 调用，**不影响**大纲、草稿、编辑审核三个节点（它们各自走自己的主模型）。
-- `max_materials` 是「合并去重后的总量上限」，不是每个关键词的检索条数；每个词的检索数会按 `ceil(max_materials / keyword_count)` 均分。`keyword_count` 由前端启动写作时传入（1~10，默认 6）。
-- `intranet` 模式不带 fallback；如果内网 ES 全挂，researcher 拿到空结果会直接进入「未检索到素材，可重新搜索或在无素材的情况下继续写作」分支。如果想让内网失败时退回互联网检索，需要在 `get_search_provider` 里手动用 `_FallbackSearchProvider(IntranetSearchProvider(...), DuckDuckGoSearchProvider(...))` 包一层。
-
-ai_writing:
-  keyword_model: deepseek-chat       # 检索词生成专用模型，留空回退写作主模型
-  rank_model: deepseek-chat          # 素材排序专用模型，留空回退写作主模型
-  max_materials: 50                  # 合并去重后的素材总量上限，范围 [1, 100]，默认 20
-
----
-
-## 十一、SSE 事件协议（后端 → 前端契约）
-
-后端通过 `_sse(event_type, data)` 推 `event: <type>\ndata: <json>\n\n` 格式。
-
-### 推出事件的位置
-
-| 事件 | 推出位置 |
-|---|---|
-| `connected` | `_sse_generator` 入口 |
-| `step_start` / `step_done` | 节点内部主动 emit |
-| `research_progress` | `researcher_node` 内的 `_emit` |
-| `materials_ready` | `_stream_graph_segment` 检测到 `material_package` 字段 |
-| `outline_chunk` | `writer_outline_node` 流式推（通过 `sse_queue`） |
-| `outline_ready` | `_stream_graph_segment` 检测到 `current_outline` |
-| `draft_chunk` | `writer_draft_node` 按章节流式推 |
-| `draft_ready` | `_stream_graph_segment` 检测到 `current_draft` |
-| `review_chunk` / `review_item_done` | `editor_node` 3 维度并行流式 |
-| `review_ready` | `_stream_graph_segment` 检测到 `review_result` |
-| `await_user` | `_stream_graph_segment` 捕获 `__interrupt__` |
-| `resumed` | pause 节点 return 时塞进 `progress_events` |
-| `notice` | 节点内手动推（非致命告警） |
-| `done` | `_stream_graph_segment` 正常结束 |
-| `error` | `_stream_graph_segment` except 分支 |
-
-### 节点如何流式推 chunk
-
-通过 `config.configurable.sse_queue`：
-
-```python
-async def writer_outline_node(state, config):
-    sse_queue = config.get("configurable", {}).get("sse_queue")
-    sse_session_id = config.get("configurable", {}).get("sse_session_id")
-    
-    async for chunk in llm.astream(prompt):
-        if sse_queue:
-            await sse_queue.put(("outline_chunk", {
-                "session_id": sse_session_id,
-                "text": chunk.content,
-                "is_thinking": False,
-            }))
-    
-    return {"current_outline": parsed, ...}
-```
-
-`sse_queue` 是路由层在 `_make_config` 里注入的 `_event_queues[session_id]`。
-
----
-
-## 十二、扩展指南：常见开发任务
-
-### 任务 1：新增一个 Graph 节点
-
-**例**：在 `editor` 之后加一个「术语统一」节点。
-
-1. **写节点**：在 `nodes/` 新建 `terminology.py`：
-   ```python
-   async def terminology_node(state, config):
-       # ... 读 current_draft 改术语
-       return {
-           "current_draft": new_draft,
-           "progress_events": [{"type": "step_done", "agent_name": "术语统一", "message": "..."}],
-       }
-   ```
-
-2. **注册到 graph**：在 `graph.py` 的 `build_ai_writing_graph` 里：
-   ```python
-   from .nodes.terminology import terminology_node
-   g.add_node("terminology", terminology_node)
-   # 改 editor 后的边
-   g.add_edge("editor", "terminology")
-   g.add_edge("terminology", "pause_review")
-   ```
-
-3. **State 加字段**（如果需要）：`state.py` 加新字段到 `AIWritingState`
-
-4. **前端事件支持**（如果要新事件类型）：见前端文档「扩展指南」
-
-5. **测试**：在 `tests/` 加单元测试，至少测节点能正常 return 和 graph 拓扑能编译
-
-### 任务 2：新增一个用户干预点
-
-1. **写 pause 节点**：在 `graph.py` 顶部加：
-   ```python
-   async def pause_xxx(state):
-       user_input = interrupt({
-           "pause_point": "xxx_confirm",
-           "message": "...",
-           "context_field": state["..."],
-       })
-       action = user_input.get("action", "confirm")
-       if action == "confirm":
-           return {"status": "next_status", "progress_events": [{"type": "resumed", ...}]}
-       # ... 其他分支
-   ```
-
-2. **路由层 ResumeRequest 加字段**（如果干预需要新字段）：
-   ```python
-   class ResumeRequest(BaseModel):
-       # ...
-       new_field: Optional[str] = None
-   ```
-
-3. **`resume_writing` 路由把字段塞进 Command(resume=...)**：
-   ```python
-   intervention = {
-       # ...
-       "newField": body.new_field,
-   }
-   ```
-
-4. **graph 拓扑加 pause 节点的边**：在 build_ai_writing_graph 里
-
-5. **前端配合**：见前端文档
-
-### 任务 3：新增一种素材检索 provider
-
-1. 在 `agents/ai_writing/search/` 加新文件，实现 `SearchProvider` 接口（参考 `internet_search.py`）：
-   ```python
-   class MyProvider(SearchProvider):
-       async def search(self, keyword: str, limit: int) -> list[SearchResult]:
-           ...
-   ```
-
-2. 配置 `config.yaml`：
-   ```yaml
-   ai_writing:
-     search:
-       provider: my_pkg.search:MyProvider
-       # provider 特定的配置...
-   ```
-
-3. `researcher_node` 通过 `config.configurable.ai_writing_config.search.provider` 用 `resolve_class` 动态加载
-
-### 任务 4：修改 LLM Prompt
-
-所有 prompt 集中在 `agents/ai_writing/prompts/`：
-- `researcher_prompts.py` — 检索专家
-- `writer_prompts.py` — 大纲 + 草稿
-- `editor_prompts.py` — 审核
-
-改 prompt 后**强烈建议**：
-1. 在 `tests/` 加针对该 prompt 输出的回归测试（用 LLM mock 或固定输入）
-2. 跑现有测试确认拓扑兼容
-
-### 任务 5：扩展持久化字段
-
-例：给 `ai_writing_sessions` 加一个 `total_tokens` 列。
-
-1. `model.py` 加列：
-   ```python
-   total_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
-   ```
-
-2. **必须**新建 alembic 迁移：
-   ```bash
-   PYTHONPATH=. uv run alembic revision -m "add total_tokens column"
-   ```
-   然后填 upgrade/downgrade 逻辑（参考 `20260519_02_ai_writing_transcript_longtext.py`）
-
-3. `sql.py` 的 `update()` / `to_dict()` 加字段处理
-
-4. `routers/ai_writing.py` 的 `SessionResponse` 加字段
-
-5. 测试：在 `tests/test_ai_writing_session_repo.py` 加新字段的 round-trip 测试
-
----
-
-## 十三、容错策略（关键设计原则）
-
-### 「写作流程能完整继续」契约
-
-后端承诺：**除非 Pydantic 校验失败（4xx），AI 写作的 4 个核心接口任何后端组件失败都不阻断当次写作的完整执行**。
-
-### 落实位置
-
-| 失败点 | 兜底位置 | 行为 |
-|---|---|---|
-| sqlite checkpointer 初始化失败 | `_get_async_checkpointer` | 自动降级 InMemorySaver |
-| SSE JSON 序列化失败 | `_sse()` | 三层兜底（default=str → notice 帧） |
-| DB `create()` session 行失败 | `start_writing` | try/except 吞掉，session_id 仍返回 |
-| DB `update(draft)` 失败 | `_stream_graph_segment` | try/except 吞掉，graph 继续推 |
-| DB `update(review)` 失败 | 同上 | 同上 |
-| DB `update(transcript)` 失败 | `save_transcript` 路由 | 返回 `success=false`，不抛 5xx |
-| 文章类型加载失败 | `start_writing` | 退回 `[]` |
-| Graph 编译失败 | `start_writing` | 抛 503（极端情况，节点 import 错） |
-| Graph 运行时节点抛错 | `_stream_graph_segment` | except 推 error 事件，session 结束 |
-| Cleanup 误删活跃会话 | `run_cleanup_once` | 活跃保护硬过滤 |
-
-### 容器优雅关闭
-
-lifespan shutdown 顺序：
-1. 停 cleanup scheduler
-2. `wait_for_inflight_graph_tasks(30s)` — 等所有 in-flight 写作跑到下一个 checkpoint
-3. 超时未结束的 task `cancel()` + 2s ack 等待
-4. `shutdown_ai_writing_graph()` — 关闭 aiosqlite Connection / pg pool
-
----
-
-## 十四、测试覆盖
-
-| 测试文件 | 数量 | 覆盖范围 |
-|---|---|---|
-| `tests/test_ai_writing_session_repo.py` | 7 | Repo CRUD + 清理用的 list_older_than / delete_by_ids |
-| `tests/test_ai_writing_session_recovery.py` | 8 | `_recover_session` / `_extract_interrupt` / `resume_writing` 跨 worker 恢复 |
-| `tests/test_ai_writing_transcript_endpoint.py` | 5 | transcript 保存兜底 |
-| `tests/test_ai_writing_cleanup.py` | 26 | 清理 + drain + checkpointer 降级 + SSE 序列化 + admin 接口 + 多 worker 检测 |
-| `tests/test_portable_long_text.py` | 5 | LONGTEXT 列类型 + 迁移链 |
-
-跑全部：
-```bash
-PYTHONPATH=. uv run pytest tests/test_ai_writing*.py tests/test_portable_long_text.py -v
-```
-
-期望 **51 个测试全过**。
-
----
-
-## 十五、关键调试 / 排查命令
-
-### 看 graph 当前状态
-
-```python
-# 进 python shell
-from deerflow.agents.ai_writing.graph import get_ai_writing_graph
-graph = await get_ai_writing_graph()
-snap = await graph.aget_state({"configurable": {"thread_id": "<session_id>"}})
-print(snap.values, snap.next, snap.tasks)
-```
-
-### 直接读 sqlite checkpointer
-
-```bash
-sqlite3 /app/.deer-flow/data/checkpoints.db
-.tables                          # 看表（checkpoints / checkpoint_writes 等）
-SELECT thread_id, checkpoint_ns, checkpoint_id FROM checkpoints 
-  WHERE thread_id = '<session_id>' LIMIT 5;
-```
-
-### 查 MySQL 业务行
-
-```sql
-SELECT id, status, draft_title, updated_at,
-       JSON_LENGTH(transcript) AS transcript_size
-  FROM ai_writing_sessions
-  WHERE id = '<session_id>';
-```
-
-### 查内存中的活跃会话（调试时手动加）
-
-```python
-# 临时在路由加一个 admin 接口
-@router.get("/admin/inflight")
-async def admin_inflight():
-    return {
-        "event_queues": list(_event_queues.keys()),
-        "inflight_tasks": len(_inflight_graph_tasks),
-        "pending_pause": list(_session_pending_pause.keys()),
-    }
-```
-
-### 日志关键字
-
-```bash
-docker logs <gateway> 2>&1 | grep -E 'ai_writing|AsyncSqliteSaver|checkpointer|recovered'
-```
-
-期望看到（启动时）：
-- `ai_writing: 使用 AsyncSqliteSaver (xxx.db)` — 持久化生效
-- `ai_writing_cleanup: 已启动 cron=...` — 清理调度起来
-
-警告：
-- `ai_writing: 持久化 checkpointer 不可用，退回 InMemorySaver` — sqlite 故障
-- `⚠ 检测到 WEB_CONCURRENCY=N` — 多 worker 警告（详见 `ai-writing-说明.md`）
-
----
-
-## 十六、性能与限制
-
-### 单 session 资源占用
-- 内存：~50KB（state + progress_events 累计）
-- sqlite checkpoint：每次 state update 写一行（一篇完整文章约 20-50 行）
-- LLM tokens：约 30K-100K（取决于素材量 + 字数 + 修订次数）
-
-### 并发上限
-- 单 worker 内：理论上百级 session 并发（IO bound），实际 LLM API rate limit 才是瓶颈
-- 多 worker：**当前 in-memory dict 隔离，详见 ai-writing-说明.md 第六章**
-
-### 长会话风险
-- progress_events 累加无界 → 长会话 state 可能膨胀到几 MB
-- transcript JSON 同理 → MySQL 行可能上 MB（但 LONGTEXT 列上限 4GB，影响读取性能）
-
-### 优化方向
-- progress_events 节流（聚合 chunk 事件）
-- transcript 增量保存（diff 而非全量覆盖）
-- 节点级 LLM 调用加 retry（tenacity）
-
----
-
-## 十七、与主 Agent 的关系
-
-| 维度 | 主 Agent | AI 写作 |
-|---|---|---|
-| Graph 入口 | `make_lead_agent` | `AI_WRITING_GRAPH` |
-| Middleware | 18 层中间件 | 无（直接节点链） |
-| State | `ThreadState` | `AIWritingState` |
-| Checkpointer | `make_checkpointer()`（共享） | `_get_async_checkpointer()`（同一文件，不同 thread_id 命名空间） |
-| 路由前缀 | `/api/langgraph/*` `/api/threads/*` | `/api/ai-writing/*` |
-| 流式协议 | LangGraph stream_mode（messages-tuple/values） | 自定义 SSE 事件 |
-| 用户干预 | 通过 `ask_clarification` 工具 | 通过 LangGraph `interrupt()` |
-| 持久化业务表 | `threads_meta`、`runs` | `ai_writing_sessions` |
-
-二者**完全独立**，仅在「共享同一个 sqlite checkpointer 文件」这一点上有间接关联（也可以拆开，性能层面没区别）。
-
----
-
-## 十八、未来 RFC 方向
-
-| 主题 | 描述 |
-|---|---|
-| 多 worker 部署支持 | 把 `_event_queues` 等搬 Redis Pub/Sub，参考 `ai-writing-说明.md` 方案 B |
-| Graph 拓扑可配置 | 现在节点链路写死，未来按 article_type 走不同拓扑（如「研报」vs「散文」） |
-| 节点级重试 | LLM 抽风时自动重试 N 次，参考 `tenacity` |
-| 素材跨 session 复用 | 同一用户多次写作可能用同一批素材 → 缓存层 |
-| 多模态素材 | 支持图片素材输入和图文混合输出 |
-| 中文标点 / 排版规则注入 | 在节点 prompt 里强化中文出版规范 |
-
----
-
-## 附录 A：相关文件速查
-
-| 文件 | 行数 | 用途 |
-|---|---|---|
-| `routers/ai_writing.py` | 1006 | 路由 + 状态字典 + SSE + drain |
-| `agents/ai_writing/graph.py` | 538 | StateGraph + checkpointer 工厂 |
-| `agents/ai_writing/state.py` | 121 | AIWritingState 定义 |
-| `agents/ai_writing/nodes/_utils.py` | 242 | LLM 工具 |
-| `agents/ai_writing/nodes/intent_parser.py` | 131 | 节点：意图解析 |
-| `agents/ai_writing/nodes/researcher.py` | 271 | 节点：素材检索 |
-| `agents/ai_writing/nodes/writer_outline.py` | 147 | 节点：大纲规划 |
-| `agents/ai_writing/nodes/writer_draft.py` | 318 | 节点：草稿生成 |
-| `agents/ai_writing/nodes/editor.py` | 180 | 节点：编辑审核 |
-| `app/gateway/ai_writing_cleanup.py` | ~280 | 清理 + 调度 |
-| `persistence/ai_writing_sessions/sql.py` | ~200 | Repository |
-| `persistence/ai_writing_sessions/model.py` | ~35 | ORM |
-
----
-
-## 附录 B：常见踩坑
-
-| 现象 | 根因 | 解决 |
-|---|---|---|
-| `/start` 报 500 | graph 编译失败（多半是 import 错） | 看启动日志 stack trace |
-| `/resume` 报 404 | session_id 不存在或 checkpointer 没快照 | 看 `ai_writing recover` 日志 |
-| transcript 500 | DB 列容量 / 网络抖 | ✅ 已修，前端 fire-and-forget |
-| SSE 卡住不动 | 多 worker SSE 隔离 / 反代超时 | 见 `ai-writing-说明.md` |
-| `draft_chunk` 丢失内容 | `ThinkTagParser` 在 `<think>` 标签边界处理 | 看 `_utils.py:ThinkTagParser.feed` 单测 |
-| graph 卡在某节点不退出 | LLM API 卡住 / 无限重试 | 看节点日志，加 timeout |
-| cleanup 没跑 | cron 表达式配错 / 文件锁被其他 worker 持有 | 看 `ai_writing_cleanup` 日志 |
-| 草稿在前端看不到但 MySQL 有 | 多 worker 导致 SSE 事件丢失 | 同上 |
-| 配 mysql 做 checkpointer 报错 | LangGraph 不支持 MySQL checkpointer | 用 sqlite 或 postgres |
-
----
-
-如需补充内容，请直接编辑本文件，并在 git commit message 里注明改动原因。

frontend-web/docs/ai-writing-assistant-backend-api.md

@@ -1,726 +0,0 @@
-# AI 写作助手后端接口与 Prompt 协议文档
-
-## 1. 文档目标
-
-本文档用于指导 AI 写作助手第二阶段升级中的后端开发、接口设计、提示词设计和联调约束。
-
-本轮后端目标不是重做 DeerFlow 的整体架构，而是在保留现有 Python + LangGraph + 线程体系的基础上，新增一套稳定的“选区改写型能力”，服务前端的 Tiptap 写作编辑器。
-
----
-
-## 2. 本轮后端职责
-
-后端负责：
-
-- 接收当前线程信息
-- 接收用户选区文本
-- 接收改写动作
-- 选取必要上下文
-- 调用模型生成候选改写结果
-- 返回纯净候选文本
-
-后端本轮不负责：
-
-- 直接编辑 Tiptap JSON
-- 直接操作前端编辑器选区
-- 直接替换前端文档内容
-- 做复杂富文本 patch
-- 做 tracked changes
-
----
-
-## 3. 设计原则
-
-### 3.1 纯文本协议优先
-
-首版只让后端处理：
-
-- 选区文本
-- 前后文文本
-- 动作类型
-- 风格参数
-
-不让后端直接理解完整富文本 JSON。
-
-### 3.2 前端负责应用，后端负责生成
-
-- 前端负责选区获取
-- 前端负责候选结果展示
-- 前端负责替换 / 插入
-- 后端只负责“给出候选文本”
-
-### 3.3 结果必须可直接落文档
-
-后端输出必须尽量是可直接放回编辑器的正文，不应带解释性前缀，例如：
-
-- “当然可以，以下是润色版本：”
-- “我帮你改写如下：”
-- “下面是优化后的内容：”
-
-这类内容必须禁止。
-
----
-
-## 4. 推荐接口设计
-
-## 4.1 主接口
-
-推荐新增统一接口：
-
-```text
-POST /api/writing/rewrite
-```
-
-由 `action` 决定具体重写类型。
-
-## 4.2 为什么推荐统一接口
-
-因为前端交互是一套统一浮层和统一预览面板，拆成多个接口会导致：
-
-- 前端判断分支增多
-- 埋点与异常处理分散
-- 后续新增动作不方便扩展
-
-统一接口更适合本轮需求。
-
----
-
-## 5. 请求体定义
-
-建议请求体如下：
-
-```json
-{
-  "threadId": "string",
-  "documentId": "string",
-  "selection": {
-    "from": 120,
-    "to": 260,
-    "text": "待改写文本"
-  },
-  "action": "polish",
-  "tone": "professional",
-  "surroundingContext": {
-    "before": "选区前文",
-    "after": "选区后文"
-  }
-}
-```
-
----
-
-## 6. 字段说明
-
-### 6.1 `threadId`
-
-用途：
-
-- 关联当前 DeerFlow 线程
-- 必要时取线程上下文或会话元数据
-
-### 6.2 `documentId`
-
-用途：
-
-- 标识当前右侧文档
-- 首版可选
-- 如果当前系统还没有独立文档 ID，可先允许为空
-
-### 6.3 `selection.from` / `selection.to`
-
-用途：
-
-- 帮助前后端联调排查
-- 首版后端通常不需要真正使用偏移量
-- 建议保留，便于日志定位
-
-### 6.4 `selection.text`
-
-用途：
-
-- 这是本轮最核心输入
-- 后端实际重写的主文本
-
-### 6.5 `action`
-
-允许值：
-
-- `polish`
-- `expand`
-- `shorten`
-- `tone`
-
-### 6.6 `tone`
-
-仅当 `action = tone` 时使用。
-
-建议允许值：
-
-- `professional`
-- `casual`
-- `readable`
-- `academic`
-- `expressive`
-
-### 6.7 `surroundingContext.before`
-
-用途：
-
-- 提供选区前文
-- 帮助模型理解语气、主语、叙事连续性
-
-建议：
-
-- 控制长度
-- 不要塞太多无关上下文
-
-### 6.8 `surroundingContext.after`
-
-用途：
-
-- 提供选区后文
-- 帮助模型在扩写、改语气时与后续内容衔接
-
----
-
-## 7. 返回体定义
-
-建议返回体如下：
-
-```json
-{
-  "output": "AI 改写后的候选文本",
-  "originalSelection": {
-    "from": 120,
-    "to": 260,
-    "text": "待改写文本"
-  },
-  "metadata": {
-    "action": "polish",
-    "tone": null,
-    "model": "your-model-name"
-  }
-}
-```
-
----
-
-## 8. 返回字段要求
-
-## 8.1 `output`
-
-必须：
-
-- 只包含候选正文
-- 尽量不夹带解释语
-- 能直接被前端替换或插入
-
-## 8.2 `originalSelection`
-
-作用：
-
-- 前端可以做校验
-- 联调时方便确认是针对哪段文本返回的
-
-## 8.3 `metadata`
-
-作用：
-
-- 便于埋点
-- 便于日志记录
-- 便于问题追踪
-
----
-
-## 9. 错误响应规范
-
-建议统一错误结构：
-
-```json
-{
-  "error": {
-    "code": "WRITING_REWRITE_FAILED",
-    "message": "rewrite failed"
-  }
-}
-```
-
-建议错误码：
-
-- `WRITING_REWRITE_FAILED`
-- `WRITING_INVALID_ACTION`
-- `WRITING_INVALID_TONE`
-- `WRITING_EMPTY_SELECTION`
-- `WRITING_MODEL_UNAVAILABLE`
-- `WRITING_CONTEXT_TOO_LARGE`
-
----
-
-## 10. 动作语义定义
-
-## 10.1 `polish`
-
-目标：
-
-- 保持原意
-- 改善表达
-- 提升通顺度、自然度和可读性
-
-不应：
-
-- 引入新事实
-- 改写成完全不同内容
-
-## 10.2 `expand`
-
-目标：
-
-- 保持主旨
-- 扩充细节
-- 增强画面感、解释性或完整度
-
-不应：
-
-- 无限制发散
-- 添加明显脱离主题的新内容
-
-## 10.3 `shorten`
-
-目标：
-
-- 压缩篇幅
-- 保留关键信息
-- 减少重复表达
-
-不应：
-
-- 丢失关键论点
-- 压缩到语义残缺
-
-## 10.4 `tone`
-
-目标：
-
-- 不改变原意
-- 调整语言风格
-
-不应：
-
-- 改写事实
-- 改写逻辑结构到完全不同
-
----
-
-## 11. Prompt 设计原则
-
-## 11.1 通用系统约束
-
-所有改写类 prompt 都应包含以下约束：
-
-- 直接输出最终可用正文
-- 不输出标题，除非原文本身就是标题改写
-- 不输出解释
-- 不输出分析过程
-- 不输出“以下是结果”之类前缀
-- 保持与上下文语气一致
-
-## 11.2 上下文使用原则
-
-前后文只用于理解，不要求模型重写前后文。
-
-明确告诉模型：
-
-- 只改写选中文本
-- 前后文仅用于参考衔接
-
-## 11.3 长度控制原则
-
-- `polish`：长度与原文接近
-- `expand`：长度可明显增加，但不要失控
-- `shorten`：长度明显缩短，但要保留关键信息
-- `tone`：长度尽量与原文接近
-
----
-
-## 12. Prompt 模板建议
-
-## 12.1 润色模板
-
-```text
-你是一名中文写作编辑助手。
-
-请在不改变原意的前提下，对“选中文本”进行润色，使表达更自然、更流畅、更清晰。
-
-要求：
-1. 保留原文事实和核心意思。
-2. 不要添加原文没有的新事实。
-3. 不要输出解释，不要输出前缀，不要输出分析过程。
-4. 直接输出润色后的正文。
-
-前文参考：
-{before}
-
-选中文本：
-{selection}
-
-后文参考：
-{after}
-```
-
-## 12.2 扩写模板
-
-```text
-你是一名中文写作编辑助手。
-
-请在不偏离主题的前提下，对“选中文本”进行扩写，增加必要细节、画面感或补充说明，使内容更充实。
-
-要求：
-1. 保持原文主旨不变。
-2. 增加内容时要自然，不要跑题。
-3. 不要输出解释，不要输出前缀，不要输出分析过程。
-4. 直接输出扩写后的正文。
-
-前文参考：
-{before}
-
-选中文本：
-{selection}
-
-后文参考：
-{after}
-```
-
-## 12.3 缩写模板
-
-```text
-你是一名中文写作编辑助手。
-
-请在保留关键信息和原意的前提下，对“选中文本”进行缩写，使其更精炼。
-
-要求：
-1. 不要丢掉核心信息。
-2. 去掉重复、冗余和拖沓表达。
-3. 不要输出解释，不要输出前缀，不要输出分析过程。
-4. 直接输出缩写后的正文。
-
-前文参考：
-{before}
-
-选中文本：
-{selection}
-
-后文参考：
-{after}
-```
-
-## 12.4 改语气模板
-
-```text
-你是一名中文写作编辑助手。
-
-请在不改变原意和事实的前提下，把“选中文本”改写成更{tone_label}的表达方式。
-
-要求：
-1. 保持原文信息不变。
-2. 只调整表达风格，不改变事实和逻辑。
-3. 不要输出解释，不要输出前缀，不要输出分析过程。
-4. 直接输出改写后的正文。
-
-前文参考：
-{before}
-
-选中文本：
-{selection}
-
-后文参考：
-{after}
-```
-
----
-
-## 13. Tone 映射建议
-
-建议前端传标准值，后端映射中文标签：
-
-- `professional` -> 专业、正式
-- `casual` -> 口语化、轻松自然
-- `readable` -> 更易读、更清晰
-- `academic` -> 学术、严谨
-- `expressive` -> 更有文采、更有表现力
-
----
-
-## 14. 上下文截取策略
-
-## 14.1 推荐策略
-
-前端传：
-
-- 选区前固定长度文本
-- 选区后固定长度文本
-
-例如：
-
-- 前文 200 到 500 字
-- 后文 200 到 500 字
-
-### 原因
-
-- 足够帮助模型理解文气和衔接
-- 不会让请求太重
-
-## 14.2 不建议
-
-- 把整篇长文全量塞进去
-- 把整个线程消息都塞进改写接口
-
-如果后端确实要参考线程上下文，也建议只取最近和写作相关的少量消息摘要。
-
----
-
-## 15. LangGraph 接入建议
-
-## 15.1 推荐接入方式
-
-在现有 LangGraph / gateway 架构中新增一个写作改写专用入口。
-
-建议二选一：
-
-### 方案 A
-
-新增专用 router：
-
-- `POST /api/writing/rewrite`
-
-内部调用现有模型层 / agent 层。
-
-### 方案 B
-
-新增专用 graph node 或 tool：
-
-- `rewrite_selection`
-
-再由 router 调用该能力。
-
-## 15.2 更推荐方案
-
-推荐：
-
-- 对外暴露统一 router
-- 内部走已有模型封装或 LangGraph 节点
-
-这样前端接口更稳定，后续后端内部重构不会影响前端。
-
----
-
-## 16. 后端模块拆解
-
-## 16.1 模块 A：接口层
-
-负责：
-
-- 请求校验
-- 错误响应
-- 参数标准化
-
-需要完成：
-
-- 统一 rewrite API
-- action / tone 校验
-- 空选区校验
-
-## 16.2 模块 B：上下文拼装层
-
-负责：
-
-- 拼装 before / selection / after
-- 必要时提取线程相关信息
-
-需要完成：
-
-- 上下文长度控制
-- 清洗空白和异常字符
-
-## 16.3 模块 C：Prompt 层
-
-负责：
-
-- 选择模板
-- 填充 action 和 tone
-
-需要完成：
-
-- 4 类动作模板
-- tone 映射
-
-## 16.4 模块 D：模型调用层
-
-负责：
-
-- 走现有模型配置体系
-- 执行大模型请求
-
-需要完成：
-
-- 统一调用入口
-- 模型不可用错误处理
-
-## 16.5 模块 E：结果清洗层
-
-负责：
-
-- 去掉解释性前缀
-- 去掉多余包裹
-- 标准化返回
-
-需要完成：
-
-- 输出清洗
-- metadata 填充
-
----
-
-## 17. 返回结果清洗建议
-
-即使 prompt 已经约束，模型仍可能输出：
-
-- “以下是润色后的内容：”
-- “当然，这里是改写结果：”
-- “优化如下：”
-
-建议后端加一层轻量清洗：
-
-- 去掉常见说明性前缀
-- 去掉包裹性 markdown 代码块
-- 去掉多余首尾空白
-
-注意：
-
-- 清洗必须保守
-- 不要误删正文
-
----
-
-## 18. 日志与观测建议
-
-建议记录：
-
-- `threadId`
-- `documentId`
-- `action`
-- `tone`
-- `selection_length`
-- `before_length`
-- `after_length`
-- `model_name`
-- `latency_ms`
-- `success / fail`
-
-不要直接把整段用户正文原文打到普通日志里，避免敏感信息风险。
-
----
-
-## 19. 后端测试清单
-
-## 19.1 单元测试
-
-- action 校验
-- tone 校验
-- 空选区校验
-- prompt 选择逻辑
-- 输出清洗逻辑
-
-## 19.2 集成测试
-
-- `polish`
-- `expand`
-- `shorten`
-- `tone-professional`
-- `tone-casual`
-- `tone-readable`
-- `tone-academic`
-- `tone-expressive`
-
-## 19.3 边界测试
-
-- 选区过短
-- 选区过长
-- 前后文为空
-- 多段文本带换行
-- 模型超时
-- 模型不可用
-
----
-
-## 20. 联调约束
-
-## 20.1 前后端必须统一
-
-- `action` 枚举值
-- `tone` 枚举值
-- 错误码
-- 返回体字段名
-
-## 20.2 联调重点
-
-- 多段落文本中换行保留是否正确
-- AI 返回内容是否适合直接落文档
-- 超时和失败时前端是否能优雅重试
-
-## 20.3 联调建议顺序
-
-1. 先 mock 返回固定文本
-2. 再接真实模型
-3. 先验证单段落
-4. 再验证多段落
-5. 最后验证大段文本
-
----
-
-## 21. 优先级建议
-
-### P0
-
-- 统一 rewrite API
-- 4 类动作支持
-- 输出纯净正文
-- 错误结构标准化
-
-### P1
-
-- 输出清洗增强
-- 埋点与日志
-- 上下文截断策略优化
-
-### P2
-
-- 更细粒度风格控制
-- 结果质量二次校验
-
----
-
-## 22. 完成定义
-
-后端满足以下条件即可视为本轮完成：
-
-- 前端能通过统一接口发起改写
-- 4 类动作均可稳定返回候选文本
-- 返回文本基本可直接用于替换或插入
-- 多段落文本能稳定处理
-- 错误结构规范统一
-
----
-
-## 23. 结论
-
-本轮后端最重要的，不是做复杂文档结构编辑，而是把“选区改写”做成稳定、可预测、可直接接入前端编辑器的能力。
-
-最稳妥的路线是：
-
-- 统一接口
-- 统一动作枚举
-- 统一 prompt 模板
-- 统一错误结构
-- 统一输出约束
-
-只要这层做稳，前端的 Tiptap 写作编辑器就能很顺畅地完成豆包式“选中即改、预览后应用”的核心体验。 

frontend-web/docs/ai-writing-assistant-frontend-checklist.md

@@ -1,703 +0,0 @@
-# AI 写作助手前端开发任务清单
-
-## 1. 文档目标
-
-本文档用于把《AI 写作助手右侧编辑器升级需求文档》进一步拆成前端可直接执行的任务清单。
-
-目标是让前端团队按模块并行推进，最终完成：
-
-- 保留左侧聊天区
-- 右侧升级为 `Tiptap` 写作编辑器
-- 支持选区浮层
-- 支持润色 / 扩写 / 缩写 / 改语气
-- 支持替换 / 插入
-- 支持标题 / 列表 / 引用 / 代码块工具条
-- UI 参考豆包 + Novel + open-canvas
-
----
-
-## 2. 本轮前端改造范围
-
-### 2.1 保留不动
-
-- 左侧聊天主链路
-- 现有线程消息流
-- 现有模型选择器
-- 现有输入框的 `writing_mode` 总入口
-
-### 2.2 重点改造
-
-- 右侧 Artifact 面板承载方式
-- 新增独立写作工作区
-- 富文本编辑器内核
-- 选区浮层
-- AI 改写结果预览
-- 文档级工具条
-
----
-
-## 3. 推荐目录结构
-
-建议新增独立模块目录：
-
-```text
-frontend-web/src/open-canvas-writing/
-  routes/
-    WritingRoutes.tsx
-  pages/
-    WritingWorkspacePage.tsx
-  components/
-    WritingShell.tsx
-    WritingHeader.tsx
-    WritingToolbar.tsx
-    WritingEditorPane.tsx
-    WritingBubbleMenu.tsx
-    WritingAiMenu.tsx
-    WritingRewritePreview.tsx
-    WritingStatusBar.tsx
-    WritingEmptyState.tsx
-  editor/
-    TiptapEditor.tsx
-    TiptapExtensions.ts
-    commands.ts
-    selection.ts
-  context/
-    WritingEditorContext.tsx
-  hooks/
-    useWritingEditor.ts
-    useWritingSelection.ts
-    useWritingRewrite.ts
-    useWritingToolbar.ts
-  api/
-    rewrite.ts
-    documents.ts
-  types/
-    document.ts
-    rewrite.ts
-  utils/
-    apply-rewrite.ts
-    markdown.ts
-    editor-style.ts
-```
-
----
-
-## 4. 现有代码落点
-
-## 4.1 需要接入的现有文件
-
-- `frontend-web/src/pages/PageRoutes.tsx`
-  - 增加新写作路由入口
-
-- `frontend-web/src/components/workspace/chats/chat-box.tsx`
-  - 当前双栏布局参考来源
-  - 后续决定是否复用布局容器，或在新页面中重建双栏
-
-- `frontend-web/src/components/workspace/input-box.tsx`
-  - 保留 `writing_mode`
-  - 后续可在切换写作模式时跳转到新写作页面
-
-- `frontend-web/src/components/workspace/artifacts/context.tsx`
-  - 仅保留给旧 Artifact 逻辑
-  - 不要继续承载写作编辑器状态
-
-## 4.2 不建议继续沿用的方式
-
-- 不要把编辑器主状态存成 `string[] artifacts`
-- 不要把右侧主体验继续建在 `artifact-file-detail.tsx` 上
-- 不要让 AI 改写结果先回聊天，再由用户手动复制
-
----
-
-## 5. 任务分阶段拆解
-
-## 阶段 A：路由与页面壳
-
-### 目标
-
-先把新的写作工作区页面立起来，让后续编辑器与交互都有落点。
-
-### 任务
-
-- 新增 `WritingRoutes.tsx`
-- 新增 `WritingWorkspacePage.tsx`
-- 在 `PageRoutes.tsx` 中挂入 `page/writing/*`
-- 确认新页面进入方式
-- 确定是：
-  - 通过左侧聊天上下文进入
-  - 通过 `writing_mode` 入口进入
-  - 或二者都支持
-
-### 交付物
-
-- 新写作页面能被路由访问
-- 页面有基础左右布局和空态
-
-### 验收
-
-- 打开 `page/writing` 能进入工作区
-- 页面不报错
-
----
-
-## 阶段 B：编辑器底座
-
-### 目标
-
-把右侧正式替换成富文本编辑器。
-
-### 任务
-
-- 安装 Tiptap 依赖
-- 建立 `TiptapEditor.tsx`
-- 建立 `TiptapExtensions.ts`
-- 配置节点：
-  - paragraph
-  - heading
-  - bulletList
-  - orderedList
-  - listItem
-  - blockquote
-  - codeBlock
-  - hardBreak
-- 配置 marks：
-  - bold
-  - italic
-  - underline
-  - strike
-  - code
-- 建立编辑器初始化逻辑
-- 建立编辑器销毁逻辑
-- 定义最小文档状态
-
-### 交付物
-
-- 可编辑正文区域
-- 初始文档可加载
-- 内容可读可写
-
-### 验收
-
-- 可以直接输入正文
-- 可以换行、加标题、切换列表
-- 不出现内容错位和明显闪烁
-
----
-
-## 阶段 C：主工具栏
-
-### 目标
-
-右侧具备正式写作工具栏。
-
-### 任务
-
-- 新增 `WritingToolbar.tsx`
-- 新增 `useWritingToolbar.ts`
-- 实现按钮：
-  - 正文
-  - H1
-  - H2
-  - H3
-  - 有序列表
-  - 无序列表
-  - 引用
-  - 代码块
-  - 加粗
-  - 斜体
-  - 下划线
-  - 删除线
-- 处理 active 状态
-- 处理不可用状态
-- 处理光标块状态联动
-
-### 交付物
-
-- 主工具栏可用
-
-### 验收
-
-- 工具条按钮能正确反映当前块状态
-- 操作后编辑器内容正确变化
-
----
-
-## 阶段 D：选区状态与浮层
-
-### 目标
-
-实现豆包式选区浮层基础能力。
-
-### 任务
-
-- 新增 `useWritingSelection.ts`
-- 新增 `selection.ts`
-- 新增 `WritingBubbleMenu.tsx`
-- 基于 Tiptap 监听 selection 变化
-- 过滤掉空选区
-- 处理多段连续选区
-- 浮层按钮：
-  - AI 改写
-  - 加粗
-  - 斜体
-  - 标题
-  - 复制
-- 处理滚动定位
-- 处理窗口尺寸变化
-
-### 交付物
-
-- 选中内容后出现浮层
-
-### 验收
-
-- 单段可触发
-- 多段可触发
-- 浮层位置稳定
-
----
-
-## 阶段 E：AI 改写菜单
-
-### 目标
-
-把选区浮层接到 AI 改写工作流。
-
-### 任务
-
-- 新增 `WritingAiMenu.tsx`
-- 新增 `useWritingRewrite.ts`
-- 新增 `api/rewrite.ts`
-- 实现一级动作：
-  - 润色
-  - 扩写
-  - 缩写
-  - 改语气
-- 实现改语气二级菜单：
-  - 更专业
-  - 更口语化
-  - 更易读
-  - 更学术
-  - 更有文采
-- 封装请求入参
-- 增加 loading 态
-- 增加 error 态
-- 增加 retry 入口
-
-### 交付物
-
-- AI 改写菜单和请求链路
-
-### 验收
-
-- 4 个动作都能发请求
-- 改语气的二级菜单可正常展开
-- 请求失败时有反馈
-
----
-
-## 阶段 F：候选结果预览
-
-### 目标
-
-把 AI 结果变成“可预览、可决策、可回退”的候选内容。
-
-### 任务
-
-- 新增 `WritingRewritePreview.tsx`
-- 新增 `apply-rewrite.ts`
-- 显示原文与候选内容
-- 提供按钮：
-  - 替换
-  - 插入
-  - 重试
-  - 取消
-- 用 transaction 应用结果
-- 处理应用成功后的焦点与滚动
-
-### 交付物
-
-- 改写结果预览卡片或面板
-
-### 验收
-
-- 替换准确
-- 插入准确
-- 取消后文档保持原样
-
----
-
-## 阶段 G：文档状态与容器体验
-
-### 目标
-
-补齐正式产品的壳层体验。
-
-### 任务
-
-- 新增 `WritingShell.tsx`
-- 新增 `WritingHeader.tsx`
-- 新增 `WritingStatusBar.tsx`
-- 新增 `WritingEmptyState.tsx`
-- 补充文档标题区域
-- 补充文档状态提示
-- 补充空态和加载态
-
-### 交付物
-
-- 页面完整壳层
-
-### 验收
-
-- 页面不是裸编辑器
-- 有完整的文档工作区感
-
----
-
-## 阶段 H：视觉打磨
-
-### 目标
-
-让整体观感接近成熟产品。
-
-### 任务
-
-- 调整右侧阅读宽度
-- 调整字体大小和行高
-- 调整段距和标题层级
-- 调整工具栏阴影、边框、圆角
-- 调整浮层动效
-- 调整 AI 预览卡片质感
-- 优化深浅色模式兼容
-
-### 交付物
-
-- 完整视觉优化
-
-### 验收
-
-- 明显优于当前版本
-- 有豆包 / Novel 风格的编辑器质感
-
----
-
-## 6. 组件级开发清单
-
-## 6.1 `WritingWorkspacePage.tsx`
-
-职责：
-
-- 页面级容器
-- 获取线程 / 文档上下文
-- 组织左右布局
-
-必须完成：
-
-- 页面初始化
-- 与左侧聊天协同
-- 右侧编辑区挂载
-
-## 6.2 `WritingShell.tsx`
-
-职责：
-
-- 写作工作区总壳层
-- 布局标题区、工具栏、正文区、状态区
-
-必须完成：
-
-- 自适应布局
-- 桌面端优先
-- 窄屏降级
-
-## 6.3 `TiptapEditor.tsx`
-
-职责：
-
-- 包装 Tiptap EditorContent
-- 负责 editor 实例初始化
-
-必须完成：
-
-- `onUpdate`
-- `onSelectionUpdate`
-- 内容同步
-
-## 6.4 `WritingToolbar.tsx`
-
-职责：
-
-- 顶部主工具栏
-
-必须完成：
-
-- 所有基础格式化命令
-- 当前状态高亮
-
-## 6.5 `WritingBubbleMenu.tsx`
-
-职责：
-
-- 选区浮层
-
-必须完成：
-
-- 跟随选区
-- 基础快捷操作
-- AI 改写入口
-
-## 6.6 `WritingAiMenu.tsx`
-
-职责：
-
-- AI 改写动作菜单
-
-必须完成：
-
-- 一级菜单
-- 改语气二级菜单
-- 动作触发
-
-## 6.7 `WritingRewritePreview.tsx`
-
-职责：
-
-- 展示候选内容
-
-必须完成：
-
-- 替换
-- 插入
-- 重试
-- 取消
-
----
-
-## 7. Hook 级开发清单
-
-## 7.1 `useWritingEditor.ts`
-
-负责：
-
-- editor 生命周期
-- 初始内容装载
-- 内容变更同步
-
-## 7.2 `useWritingSelection.ts`
-
-负责：
-
-- 当前选区抽取
-- 选区文本缓存
-- 多段落纯文本拼接
-
-## 7.3 `useWritingRewrite.ts`
-
-负责：
-
-- 改写请求
-- loading / success / error
-- 结果缓存
-- 重试
-
-## 7.4 `useWritingToolbar.ts`
-
-负责：
-
-- toolbar active 状态
-- editor command 映射
-
----
-
-## 8. API 对接清单
-
-前端需向后端约定以下接口能力：
-
-- `POST /api/writing/rewrite`
-
-前端请求内容至少包括：
-
-- `threadId`
-- `documentId`
-- `selection.from`
-- `selection.to`
-- `selection.text`
-- `action`
-- `tone`
-- `surroundingContext.before`
-- `surroundingContext.after`
-
-前端需处理的返回字段：
-
-- `output`
-- `originalSelection`
-- `metadata`
-
----
-
-## 9. 状态管理建议
-
-建议新增独立 Context：
-
-- `WritingEditorContext.tsx`
-
-建议持有：
-
-- 当前文档内容
-- 当前 editor 实例
-- 当前选区
-- 当前改写请求状态
-- 当前候选结果
-- 当前 UI 面板状态
-
-不建议继续复用旧 Artifact Context 的原因：
-
-- 旧 Context 关注文件列表和文件路径
-- 新编辑器关注选区、结构、候选结果、应用动作
-- 关注点完全不同
-
----
-
-## 10. 前端联调检查点
-
-## 10.1 与后端联调前
-
-- 先用 mock 数据打通浮层和预览
-- 先验证替换 / 插入逻辑
-
-## 10.2 与后端联调时
-
-- 检查多段落选区拼接结果
-- 检查 AI 返回内容是否带说明性前缀
-- 检查替换后位置是否准确
-
-## 10.3 联调后
-
-- 验证大段文本性能
-- 验证撤销 / 重做
-- 验证快速连续触发是否会状态错乱
-
----
-
-## 11. 前端测试清单
-
-## 11.1 功能测试
-
-- 输入正文
-- 插入标题
-- 切换列表
-- 插入引用
-- 插入代码块
-- 加粗 / 斜体 / 下划线 / 删除线
-- 选区浮层显示
-- 选区浮层隐藏
-- AI 改写菜单打开
-- 改语气二级菜单打开
-- 改写结果替换
-- 改写结果插入
-- 改写结果取消
-
-## 11.2 场景测试
-
-- 单段短文本润色
-- 多段文本润色
-- 多段文本扩写
-- 多段文本缩写
-- 多段文本改语气
-- 连续两次改写同一段
-- 快速切换线程后重新进入
-
-## 11.3 回归测试
-
-- 左侧聊天是否正常
-- 模型切换是否正常
-- `writing_mode` 是否正常
-- 原有 artifact 模块是否仍可使用
-
----
-
-## 12. 任务优先级
-
-### P0
-
-- 路由与页面壳
-- Tiptap 接入
-- 主工具栏
-- 选区浮层
-- 改写菜单
-- 替换 / 插入
-
-### P1
-
-- 页面头部与状态
-- 优雅 loading / error / retry
-- 多段落稳定性
-- UI 打磨
-
-### P2
-
-- 空态优化
-- 动效优化
-- 快捷键支持
-
----
-
-## 13. 建议分工
-
-### 前端 1 号
-
-负责：
-
-- 路由与页面壳
-- Tiptap 接入
-- 主工具栏
-
-### 前端 2 号
-
-负责：
-
-- 选区状态
-- BubbleMenu
-- AI 菜单
-
-### 前端 3 号
-
-负责：
-
-- 候选结果预览
-- 替换 / 插入
-- 状态栏与页面体验
-
-### 联调负责人
-
-负责：
-
-- 前后端请求协议
-- 错误态规范
-- 多段落测试和回归
-
----
-
-## 14. 前端完成定义
-
-满足以下条件可视为前端完成：
-
-- 右侧能作为正式编辑器独立使用
-- 选区后可直接发起 AI 改写
-- 改写后可替换或插入
-- 视觉上明显优于当前版本
-- 左侧聊天和现有系统不被破坏
-
----
-
-## 15. 下一步建议
-
-前端团队可以按以下顺序开工：
-
-1. 先起页面和路由
-2. 再接 Tiptap 与主工具栏
-3. 再做选区浮层
-4. 再接 AI 菜单和结果预览
-5. 最后做视觉打磨
-
-这个顺序风险最小，也最容易在中途验收。 

frontend-web/docs/ai-writing-assistant-source-map.md

@@ -1,457 +0,0 @@
-# AI 写作助手源码与实现映射表
-
-## 1. 文档目标
-
-本文档用于把以下几类信息对应起来：
-
-- 豆包 AI 写作助手里要借鉴的交互
-- Novel / open-canvas / Tiptap 中可参考的实现思路
-- DeerFlow 当前项目里已经存在的落点
-- 本次新建模块应该落到哪里
-
-这份文档不是源码复制文档，而是开发时的“对照表”和“导航图”。
-
----
-
-## 2. 使用方式
-
-开发时建议按以下顺序看：
-
-1. 先看“目标能力”
-2. 再看“参考来源”
-3. 再看“DeerFlow 当前落点”
-4. 最后看“本次目标文件”
-
-这样可以避免出现两种常见问题：
-
-- 直接照搬外部项目结构，结果和你们现有架构冲突
-- 只看自己项目，不知道成熟产品交互应该怎么落
-
----
-
-## 3. 总体映射
-
-| 目标能力 | 产品参考 | 外部参考实现 | DeerFlow 当前落点 | 本次目标文件 |
-| --- | --- | --- | --- | --- |
-| 写作工作区路由 | open-canvas 独立页面 | open-canvas 路由组织思路 | `frontend-web/src/pages/PageRoutes.tsx` | `frontend-web/src/open-canvas-writing/routes/WritingRoutes.tsx` |
-| 左右双栏工作区 | 豆包写作页 / open-canvas | open-canvas 页面壳思路 | `frontend-web/src/components/workspace/chats/chat-box.tsx` | `frontend-web/src/open-canvas-writing/pages/WritingWorkspacePage.tsx`、`WritingShell.tsx` |
-| 富文本正文编辑 | Novel | Tiptap 官方编辑器模式 | 当前无正式富文本正文编辑器 | `frontend-web/src/open-canvas-writing/editor/TiptapEditor.tsx` |
-| 文档工具栏 | 豆包 / Novel | Tiptap Toolbar 组合思路 | 当前右侧无正式工具栏 | `frontend-web/src/open-canvas-writing/components/WritingToolbar.tsx` |
-| 选区浮层 | 豆包 | Tiptap BubbleMenu | 当前右侧无选区浮层 | `frontend-web/src/open-canvas-writing/components/WritingBubbleMenu.tsx` |
-| AI 改写菜单 | 豆包 | 自定义菜单 + BubbleMenu 挂接 | 当前无 | `frontend-web/src/open-canvas-writing/components/WritingAiMenu.tsx` |
-| 候选结果预览 | 豆包 / open-canvas | open-canvas 候选应用思路 | 当前无 | `frontend-web/src/open-canvas-writing/components/WritingRewritePreview.tsx` |
-| 替换 / 插入 | 豆包 | Tiptap transaction 应用 | 当前无 | `frontend-web/src/open-canvas-writing/utils/apply-rewrite.ts` |
-| 写作模式总入口 | 当前 DeerFlow | 现有 `writing_mode` 开关 | `frontend-web/src/components/workspace/input-box.tsx` | 保留现有入口并接新页面 |
-| 线程与模型协同 | 当前 DeerFlow | 现有线程 / 模型体系 | 现有 `core/threads`、`core/models` | 继续复用，新增 `api/rewrite.ts` |
-
----
-
-## 4. 豆包功能到 DeerFlow 的映射
-
-## 4.1 滑词 / 选区浮层
-
-### 豆包里的体验
-
-- 选中文本后出现轻量浮层
-- 浮层里有：
-  - AI 改写
-  - 文本样式
-  - 复制
-
-### DeerFlow 当前状态
-
-- 右侧还没有正式的选区级工具层
-
-### 本次实现方式
-
-- 使用 Tiptap 的 `BubbleMenu`
-- 再叠加自定义菜单逻辑
-
-### 本次落点
-
-- `frontend-web/src/open-canvas-writing/components/WritingBubbleMenu.tsx`
-- `frontend-web/src/open-canvas-writing/hooks/useWritingSelection.ts`
-- `frontend-web/src/open-canvas-writing/editor/selection.ts`
-
----
-
-## 4.2 多段落改写
-
-### 豆包里的体验
-
-- 不是只改单句
-- 能对连续几段一起润色、扩写、缩写、改语气
-
-### DeerFlow 当前状态
-
-- 现有右侧编辑区没有正式的多段落选区改写模型
-
-### 本次实现方式
-
-- 前端提取连续选区纯文本
-- 前端附带前后文
-- 后端返回候选纯文本
-- 前端决定替换或插入
-
-### 本次落点
-
-- `frontend-web/src/open-canvas-writing/hooks/useWritingSelection.ts`
-- `frontend-web/src/open-canvas-writing/hooks/useWritingRewrite.ts`
-- `frontend-web/src/open-canvas-writing/api/rewrite.ts`
-
----
-
-## 4.3 替换 / 插入
-
-### 豆包里的体验
-
-- 改写结果不是直接覆盖原文
-- 用户可选择：
-  - 替换
-  - 插入
-
-### DeerFlow 当前状态
-
-- 当前没有候选文本应用层
-
-### 本次实现方式
-
-- 建立候选结果预览区
-- 基于 Tiptap transaction 应用文本
-
-### 本次落点
-
-- `frontend-web/src/open-canvas-writing/components/WritingRewritePreview.tsx`
-- `frontend-web/src/open-canvas-writing/utils/apply-rewrite.ts`
-
----
-
-## 4.4 标题 / 列表 / 引用 / 代码块工具条
-
-### 豆包里的体验
-
-- 右侧本身就是正式文档编辑器
-- 可以快速切换文档结构
-
-### DeerFlow 当前状态
-
-- 当前右侧偏预览，不是正式写作编辑器
-
-### 本次实现方式
-
-- 使用 Tiptap 节点和命令
-- 在主工具栏中集中承载
-
-### 本次落点
-
-- `frontend-web/src/open-canvas-writing/components/WritingToolbar.tsx`
-- `frontend-web/src/open-canvas-writing/hooks/useWritingToolbar.ts`
-- `frontend-web/src/open-canvas-writing/editor/commands.ts`
-- `frontend-web/src/open-canvas-writing/editor/TiptapExtensions.ts`
-
----
-
-## 5. Novel 参考映射
-
-## 5.1 最值得借鉴的不是“代码整搬”，而是这三件事
-
-- 编辑器主容器的产品感
-- 工具栏和空态的组织方式
-- 正文阅读宽度、排版、留白
-
-## 5.2 对应到 DeerFlow 的实现位置
-
-- 页面壳：`WritingShell.tsx`
-- 顶部文档区：`WritingHeader.tsx`
-- 编辑容器：`TiptapEditor.tsx`
-- 工具栏：`WritingToolbar.tsx`
-- 空态：`WritingEmptyState.tsx`
-
-## 5.3 不建议直接照搬的部分
-
-- Next.js 页面结构
-- 依赖其服务端 AI 调用方式
-- 与 Vercel AI SDK 深绑定的部分
-
----
-
-## 6. open-canvas 参考映射
-
-## 6.1 主要借鉴对象
-
-open-canvas 这次最值得借鉴的不是页面外观，而是：
-
-- AI 工作流组织方式
-- 改写结果应用节奏
-- 编辑器和聊天协作的模式
-
-## 6.2 借鉴重点
-
-### 借鉴 1：独立工作区思想
-
-不要把写作体验塞进一个零散的弹窗或文件详情页，要有独立工作区。
-
-对应 DeerFlow：
-
-- `frontend-web/src/open-canvas-writing/pages/WritingWorkspacePage.tsx`
-
-### 借鉴 2：画布状态独立维护
-
-不要让写作状态完全依附聊天消息渲染结果，要独立维护文档和候选状态。
-
-对应 DeerFlow：
-
-- `frontend-web/src/open-canvas-writing/context/WritingEditorContext.tsx`
-
-### 借鉴 3：AI 输出先预览，再应用
-
-对应 DeerFlow：
-
-- `frontend-web/src/open-canvas-writing/components/WritingRewritePreview.tsx`
-
----
-
-## 7. Tiptap 参考映射
-
-## 7.1 Tiptap 在本项目中的职责
-
-- 作为右侧正式富文本编辑器内核
-- 提供结构节点与 marks
-- 提供 BubbleMenu 能力
-- 提供 transaction 应用能力
-
-## 7.2 建议直接参考的实现点
-
-- `EditorContent` 的封装模式
-- `BubbleMenu` 的接入方式
-- heading / list / blockquote / codeBlock 扩展配置
-- `editor.chain().focus()` 命令调用模式
-- selection 变化监听
-
-## 7.3 DeerFlow 本次落点
-
-- `frontend-web/src/open-canvas-writing/editor/TiptapEditor.tsx`
-- `frontend-web/src/open-canvas-writing/editor/TiptapExtensions.ts`
-- `frontend-web/src/open-canvas-writing/editor/commands.ts`
-- `frontend-web/src/open-canvas-writing/components/WritingBubbleMenu.tsx`
-
----
-
-## 8. DeerFlow 现有文件到新模块的映射
-
-## 8.1 `frontend-web/src/pages/PageRoutes.tsx`
-
-### 当前职责
-
-- 汇总页面路由
-
-### 本次作用
-
-- 挂入新的写作助手路由
-
-### 后续动作
-
-- 引入 `WritingRoutes`
-- 增加 `page/writing/*`
-
----
-
-## 8.2 `frontend-web/src/components/workspace/chats/chat-box.tsx`
-
-### 当前职责
-
-- 左聊天 + 右 Artifact 双栏布局
-
-### 本次作用
-
-- 提供双栏工作区组织思路
-- 可复用布局比例和 panel 交互经验
-
-### 不建议直接复用的部分
-
-- 不要继续让右侧核心能力挂在 ArtifactFileDetail 上
-
-### 本次目标替代
-
-- `WritingWorkspacePage.tsx`
-- `WritingShell.tsx`
-
----
-
-## 8.3 `frontend-web/src/components/workspace/artifacts/context.tsx`
-
-### 当前职责
-
-- 管理文件型 artifact 列表、选中项和开关状态
-
-### 本次作用
-
-- 仅作为旧 Artifact 模块保留
-
-### 本次目标替代
-
-- `WritingEditorContext.tsx`
-
-### 原因
-
-- 写作编辑器需要的不是文件路径状态
-- 而是文档状态、选区状态、候选结果状态、工具层状态
-
----
-
-## 8.4 `frontend-web/src/components/workspace/input-box.tsx`
-
-### 当前职责
-
-- 聊天输入区
-- 已有 `writing_mode` 入口
-
-### 本次作用
-
-- 保留为用户进入写作模式的现有入口
-
-### 本次改造建议
-
-- 写作模式打开时，跳转或唤起新的写作工作区
-- 不再只停留在“生成 Markdown 文件”这个层面
-
----
-
-## 9. 新模块间的依赖关系
-
-## 9.1 页面层
-
-- `WritingRoutes.tsx`
-- `WritingWorkspacePage.tsx`
-- `WritingShell.tsx`
-
-职责：
-
-- 页面路由
-- 双栏或工作区布局
-- 上下文装配
-
-## 9.2 编辑器层
-
-- `TiptapEditor.tsx`
-- `TiptapExtensions.ts`
-- `commands.ts`
-- `selection.ts`
-
-职责：
-
-- 编辑器内核
-- 节点和 marks
-- 基础命令
-- 选区抽取
-
-## 9.3 交互层
-
-- `WritingToolbar.tsx`
-- `WritingBubbleMenu.tsx`
-- `WritingAiMenu.tsx`
-- `WritingRewritePreview.tsx`
-
-职责：
-
-- 工具栏
-- 浮层
-- AI 菜单
-- 候选内容应用
-
-## 9.4 状态层
-
-- `WritingEditorContext.tsx`
-- `useWritingEditor.ts`
-- `useWritingSelection.ts`
-- `useWritingRewrite.ts`
-- `useWritingToolbar.ts`
-
-职责：
-
-- 主状态
-- 选区状态
-- 改写状态
-- 工具栏状态
-
-## 9.5 API 层
-
-- `api/rewrite.ts`
-- `api/documents.ts`
-
-职责：
-
-- 对接后端写作改写接口
-- 对接文档加载与保存接口
-
----
-
-## 10. 能力到文件的精确映射
-
-| 能力 | 新文件 | 说明 |
-| --- | --- | --- |
-| 新写作页面 | `frontend-web/src/open-canvas-writing/pages/WritingWorkspacePage.tsx` | 承载整个新模式 |
-| 写作路由 | `frontend-web/src/open-canvas-writing/routes/WritingRoutes.tsx` | 统一路由入口 |
-| 页面外壳 | `frontend-web/src/open-canvas-writing/components/WritingShell.tsx` | 页面布局与容器 |
-| 文档头部 | `frontend-web/src/open-canvas-writing/components/WritingHeader.tsx` | 标题、状态 |
-| 主工具栏 | `frontend-web/src/open-canvas-writing/components/WritingToolbar.tsx` | 文档结构与格式工具 |
-| 正文编辑器 | `frontend-web/src/open-canvas-writing/editor/TiptapEditor.tsx` | Tiptap 核心封装 |
-| 扩展配置 | `frontend-web/src/open-canvas-writing/editor/TiptapExtensions.ts` | 节点和 marks |
-| 选区浮层 | `frontend-web/src/open-canvas-writing/components/WritingBubbleMenu.tsx` | 选区出现的悬浮条 |
-| AI 菜单 | `frontend-web/src/open-canvas-writing/components/WritingAiMenu.tsx` | 润色、扩写等动作 |
-| 改写预览 | `frontend-web/src/open-canvas-writing/components/WritingRewritePreview.tsx` | 候选内容展示与应用 |
-| 替换 / 插入 | `frontend-web/src/open-canvas-writing/utils/apply-rewrite.ts` | 应用候选结果 |
-| 编辑器状态 | `frontend-web/src/open-canvas-writing/context/WritingEditorContext.tsx` | 独立上下文 |
-| 改写请求 | `frontend-web/src/open-canvas-writing/api/rewrite.ts` | 调后端接口 |
-
----
-
-## 11. 开发时的参考顺序
-
-建议开发顺序如下：
-
-1. 先看 `PageRoutes.tsx`，确定路由接法
-2. 再看 `chat-box.tsx`，理解当前左右布局
-3. 然后起 `WritingWorkspacePage.tsx` 和 `WritingShell.tsx`
-4. 再接 `TiptapEditor.tsx`
-5. 再做 `WritingToolbar.tsx`
-6. 再做 `WritingBubbleMenu.tsx`
-7. 再做 `WritingAiMenu.tsx`
-8. 最后做 `WritingRewritePreview.tsx`
-
-这样可以让每一层都有稳定承载，不会出现“先做了 AI 菜单，但页面还没落点”的混乱情况。
-
----
-
-## 12. 明确哪些是“参考”，哪些是“目标”
-
-### 12.1 参考
-
-- 豆包：交互体验参考
-- Novel：页面和编辑器质感参考
-- open-canvas：AI 工作流参考
-- Tiptap：编辑器技术实现参考
-
-### 12.2 目标
-
-目标不是复刻任何一个外部项目，而是：
-
-- 在 DeerFlow 现有架构中
-- 用 React + Vite + 现有线程体系
-- 做出一个更成熟的 AI 写作编辑器模式
-
----
-
-## 13. 结论
-
-这份映射表的核心作用，是避免团队在开发时迷路。
-
-真正推荐的姿势是：
-
-- 用豆包定义目标体验
-- 用 Novel 定义页面质感
-- 用 open-canvas 定义 AI 工作流
-- 用 Tiptap 作为编辑器内核
-- 用 DeerFlow 现有路由、线程、模型体系做宿主
-
-这样推进，既不会脱离你们现有工程，也能尽量快地把右侧编辑区拉到更接近成熟产品的水平。 

frontend-web/docs/ai-writing-backend-orchestrator-blueprint.md

@@ -1,645 +0,0 @@
-# AI 写作后端新路线设计草案
-
-## 1. 目标
-
-为“弱模型多 Agent 写作工作流”建设一条独立后端路线，满足以下要求：
-
-- 不影响现有同事正在开发的功能
-- 不强耦合现有 DeerFlow 通用对话主链路
-- 可独立部署、独立调试、独立回滚
-- 支持多阶段写作编排、人工介入、失败重试、流式事件输出
-
----
-
-## 2. 推荐建设方式
-
-优先建议：
-
-- 在 `offline-backend-20260512` 下新建独立应用或独立模块
-
-建议目录：
-
-```text
-offline-backend-20260512/
-  apps/
-    ai_writing_orchestrator/
-      api/
-      application/
-      domain/
-      infrastructure/
-      prompts/
-      tests/
-```
-
-如果当前后端没有 `apps/` 结构，也可以采用：
-
-```text
-offline-backend-20260512/
-  ai-writing-orchestrator/
-    api/
-    application/
-    domain/
-    infrastructure/
-    prompts/
-    tests/
-```
-
-重点不是目录名字，而是一定要把“多 Agent 写作编排”与现有通用聊天能力隔离开。
-
----
-
-## 3. 技术路线建议
-
-推荐组合：
-
-- 编排框架：`LangGraph`
-- 模型调用：接你们内网模型网关
-- 检索层：接内网知识库 / 文档库 / 搜索服务
-- 状态存储：先用数据库或 Redis + DB，后续再演进
-- 事件输出：SSE 或流式 HTTP
-
-推荐原因：
-
-- `LangGraph` 适合状态机和多节点回退
-- 对弱模型最关键的是“强流程控制”，不是“自由 Agent 对话”
-- 后续加人工确认节点和 checkpoint 会更自然
-
----
-
-## 4. 分层设计
-
-建议按四层拆分。
-
-## 4.1 API 层
-
-职责：
-
-- 接收前端请求
-- 鉴权
-- 参数校验
-- 返回 workflow 信息
-- 提供事件流出口
-
-建议文件：
-
-```text
-api/
-  routes/
-    workflows.py
-    workflow_events.py
-  schemas/
-    workflow_request.py
-    workflow_response.py
-```
-
-## 4.2 Application 层
-
-职责：
-
-- 组织用例
-- 调度 workflow service
-- 管理人工确认动作
-- 处理重试和终止逻辑
-
-建议文件：
-
-```text
-application/
-  services/
-    workflow_service.py
-    workflow_event_service.py
-    human_action_service.py
-  use_cases/
-    create_workflow.py
-    start_workflow.py
-    confirm_outline.py
-    rewrite_section.py
-    approve_final.py
-```
-
-## 4.3 Domain 层
-
-职责：
-
-- 定义工作流状态机
-- 定义 Agent 输入输出协议
-- 定义 artifact 与评分模型
-
-建议文件：
-
-```text
-domain/
-  models/
-    workflow.py
-    workflow_stage.py
-    workflow_event.py
-    artifact.py
-    review_result.py
-  agents/
-    researcher.py
-    outliner.py
-    writer.py
-    editor.py
-    supervisor.py
-  graphs/
-    writing_graph.py
-  policies/
-    retry_policy.py
-    quality_policy.py
-```
-
-## 4.4 Infrastructure 层
-
-职责：
-
-- 访问模型网关
-- 访问检索服务
-- 访问数据库
-- 发送事件
-- 缓存与日志
-
-建议文件：
-
-```text
-infrastructure/
-  llm/
-    model_client.py
-  retrieval/
-    intranet_search_client.py
-    knowledge_base_client.py
-  persistence/
-    workflow_repository.py
-    artifact_repository.py
-  streaming/
-    sse_publisher.py
-  logging/
-    workflow_logger.py
-```
-
----
-
-## 5. 工作流最小闭环
-
-第一版建议只做如下状态机：
-
-1. `collect_materials`
-2. `generate_outline`
-3. `await_outline_confirmation`
-4. `write_draft`
-5. `review_draft`
-6. `rewrite_if_needed`
-7. `complete`
-
-终止规则：
-
-- 编辑评分达标则完成
-- 否则进入重写
-- 最多重写 2 次
-- 超过次数则标记 `human_intervention_required`
-
----
-
-## 6. Agent 模块设计
-
-## 6.1 Researcher
-
-输入：
-
-- 主题
-- 用户要求
-- 检索范围
-- 可用资料源
-
-输出：
-
-- `material_cards`
-- `facts`
-- `quotes`
-- `examples`
-- `risks`
-- `source_refs`
-
-程序职责：
-
-- 先做检索
-- 再把检索结果裁剪后送给模型
-- 输出必须结构化
-
-## 6.2 Outliner
-
-输入：
-
-- 用户要求
-- 研究结果
-
-输出：
-
-- `title_candidates`
-- `outline_sections`
-- `key_points_per_section`
-
-约束：
-
-- 提纲优先，不写正文
-
-## 6.3 Writer
-
-输入：
-
-- 已确认提纲
-- 素材卡片
-- 风格要求
-
-输出：
-
-- `draft_sections`
-- `section_source_refs`
-- `full_draft_markdown`
-
-建议：
-
-- 按章节分段生成，不要一次长文直出
-
-## 6.4 Editor
-
-输入：
-
-- 初稿
-- 提纲
-- 素材
-- 用户要求
-
-输出：
-
-- `issues`
-- `severity`
-- `score`
-- `rewrite_instructions`
-- `decision`
-
-规则：
-
-- 先查事实，再查结构，再查文风
-
-## 6.5 Supervisor
-
-输入：
-
-- 各阶段结果
-- 重试计数
-- 评分结果
-
-输出：
-
-- 下一跳节点
-- 是否需要人工确认
-- 是否结束
-
----
-
-## 7. Prompt 组织建议
-
-建议为每个 Agent 分开管理 prompt，不要写成一个超级 prompt。
-
-建议目录：
-
-```text
-prompts/
-  researcher/
-    system.txt
-    output_schema.json
-  outliner/
-    system.txt
-    output_schema.json
-  writer/
-    system.txt
-    output_schema.json
-  editor/
-    system.txt
-    output_schema.json
-  supervisor/
-    system.txt
-```
-
-原则：
-
-- 每个 Agent 一套职责
-- 每个 Agent 一套输出 schema
-- Prompt 版本可管理
-- 后续支持 A/B 调参
-
----
-
-## 8. 弱模型适配策略
-
-## 8.1 先检索后生成
-
-不要让模型自己“想资料”，程序先检索、裁剪、去重后再喂给模型。
-
-## 8.2 短上下文任务化
-
-每个节点只给弱模型一小段明确任务：
-
-- 研究归纳
-- 提纲整理
-- 单章节写作
-- 单章节审稿
-
-## 8.3 结构化输出
-
-优先 JSON 或 Pydantic schema，不要放任自然语言自由返回。
-
-## 8.4 章节级重写
-
-不要整篇回炉。编辑指出第 2 节有问题，就只重写第 2 节。
-
-## 8.5 程序接管质量门槛
-
-例如：
-
-- 资料引用数不足，不进入下一步
-- 提纲章节数过少，直接重生
-- 编辑评分低于阈值，自动重写
-
----
-
-## 9. 数据模型建议
-
-## 9.1 Workflow
-
-建议字段：
-
-- `id`
-- `status`
-- `current_stage`
-- `user_id`
-- `thread_id`
-- `input_payload`
-- `current_artifact_id`
-- `retry_count`
-- `created_at`
-- `updated_at`
-
-## 9.2 Workflow Artifact
-
-建议字段：
-
-- `id`
-- `workflow_id`
-- `artifact_type`
-- `stage`
-- `version`
-- `title`
-- `content`
-- `metadata`
-
-## 9.3 Workflow Event
-
-建议字段：
-
-- `id`
-- `workflow_id`
-- `event_type`
-- `stage`
-- `agent_name`
-- `payload`
-- `created_at`
-
-## 9.4 Human Action
-
-建议字段：
-
-- `workflow_id`
-- `action_type`
-- `payload`
-- `operator`
-- `created_at`
-
----
-
-## 10. API 草案
-
-## 10.1 创建任务
-
-`POST /api/ai-writing/workflows`
-
-请求：
-
-```json
-{
-  "topic": "主题",
-  "articleType": "行业分析",
-  "audience": "管理层",
-  "tone": "专业克制",
-  "targetLength": 3000,
-  "constraints": ["避免口语化"],
-  "referenceScope": ["内网知识库", "项目复盘文档"]
-}
-```
-
-返回：
-
-```json
-{
-  "workflowId": "wf_xxx",
-  "status": "idle"
-}
-```
-
-## 10.2 启动任务
-
-`POST /api/ai-writing/workflows/{id}/start`
-
-## 10.3 查询任务
-
-`GET /api/ai-writing/workflows/{id}`
-
-## 10.4 订阅事件
-
-`GET /api/ai-writing/workflows/{id}/events`
-
-返回事件流示例：
-
-```json
-{
-  "type": "stage_changed",
-  "stage": "generating_outline",
-  "message": "正在生成提纲"
-}
-```
-
-## 10.5 确认提纲
-
-`POST /api/ai-writing/workflows/{id}/confirm-outline`
-
-## 10.6 指定章节重写
-
-`POST /api/ai-writing/workflows/{id}/rewrite-section`
-
-## 10.7 确认终稿
-
-`POST /api/ai-writing/workflows/{id}/approve-final`
-
----
-
-## 11. LangGraph 实现建议
-
-## 11.1 推荐 graph 节点
-
-- `load_input`
-- `retrieve_materials`
-- `normalize_materials`
-- `generate_outline`
-- `wait_for_outline_confirmation`
-- `write_sections`
-- `merge_sections`
-- `review_draft`
-- `rewrite_sections`
-- `publish_final_artifact`
-
-## 11.2 推荐 state
-
-建议 state 字段：
-
-- `workflow_id`
-- `input_payload`
-- `materials`
-- `outline`
-- `outline_confirmed`
-- `draft_sections`
-- `merged_draft`
-- `review_result`
-- `rewrite_targets`
-- `final_article`
-- `retry_count`
-- `events`
-
-## 11.3 条件边
-
-建议条件边逻辑：
-
-- 提纲未确认 -> 等待用户
-- 编辑通过 -> 完成
-- 编辑不通过且可重试 -> 重写
-- 编辑不通过且超限 -> 人工介入
-
----
-
-## 12. 可观测性要求
-
-第一版就建议带上以下能力：
-
-- 每个 workflow 的事件日志
-- 每个 Agent 的输入输出摘要
-- 每次重试原因
-- 每个阶段耗时
-- 每次模型调用 token 与错误日志
-
-后续排问题会非常依赖这些数据。
-
----
-
-## 13. 测试建议
-
-## 13.1 单元测试
-
-覆盖：
-
-- stage 流转
-- retry policy
-- quality policy
-- 事件构造
-
-## 13.2 集成测试
-
-覆盖：
-
-- 创建任务到完成的主链路
-- 提纲确认链路
-- 审稿失败后重写链路
-- 人工介入链路
-
-## 13.3 Prompt 回归集
-
-建议建立 10-20 个固定写作样例，做回归：
-
-- 短文
-- 长文
-- 事实密集型文章
-- 宣传型文章
-- 分析型文章
-
----
-
-## 14. 开发顺序建议
-
-## Step 1：先做 domain 与 API 契约
-
-先定：
-
-- stage 枚举
-- event 枚举
-- artifact 结构
-- human action payload
-
-## Step 2：先做 fake orchestrator
-
-先不接真实模型，只模拟事件流，把前后端联调跑通。
-
-## Step 3：接 Researcher + Outliner
-
-优先把“研究 + 提纲”做出来，因为这是弱模型提升最大的环节。
-
-## Step 4：接 Writer + Editor
-
-再接初稿和审稿重写。
-
-## Step 5：接可观测性和缓存
-
-最后再补生产化能力。
-
----
-
-## 15. 风险控制建议
-
-### 风险 1：直接复用现有线程流，导致协议污染
-
-建议：
-
-- workflow 用独立 route 和独立 event schema
-
-### 风险 2：写作结果与右侧 artifact 模型不兼容
-
-建议：
-
-- 后端统一输出标准 markdown artifact
-
-### 风险 3：弱模型频繁输出不合法 JSON
-
-建议：
-
-- 每个节点加 schema repair
-- 加轻量重试
-- 尽量减少复杂嵌套输出
-
-### 风险 4：研究资料太多导致上下文爆炸
-
-建议：
-
-- 检索后先裁剪、摘要、分桶
-
----
-
-## 16. 最终建议
-
-后端第一版最重要的是把“状态机、事件流、人工确认、章节重写”这四件事做对，而不是一开始就追求很多花哨 Agent。
-
-建议 MVP 只保留：
-
-1. Researcher
-2. Outliner
-3. Writer
-4. Editor
-5. Supervisor
-
-当这条链路稳定后，再继续扩展 fact-checker、style editor、compliance reviewer。

frontend-web/docs/ai-writing-final-execution-plan.md

@@ -1,806 +0,0 @@
-# AI 写作执行方案
-
-## 1. 总体原则
-
-本项目的最终落地原则：
-
-1. 前端继续基于当前 `open-canvas` 页面开发，不复制第二套页面
-2. 后端单独开 `ai-writing-orchestrator` 新路线，不侵入现有主链路
-3. 编排框架采用 `LangGraph`
-4. 写作工作流采用 `Researcher -> Outliner -> Writer -> Editor -> Supervisor`
-5. Agent 间输出统一采用 `JSON Schema / Pydantic`
-6. 前后端通过 `SSE` 传递工作流事件
-7. 第一版只做最小闭环，不做过多花哨扩展
-
-一句话说明：
-
-用独立的新后端路线承载多 Agent 写作工作流，前端继续复用 `open-canvas`，实现上采用 `LangGraph + A/B/C Agent + SSE` 的最小闭环。
-
----
-
-## 2. 项目边界
-
-## 2.1 前端边界
-
-继续使用当前页面：
-
-- [CanvasResizableLayout.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/layout/CanvasResizableLayout.tsx)
-- [CanvasChatPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/chat/CanvasChatPanel.tsx)
-- [CanvasArtifactPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/artifact/CanvasArtifactPanel.tsx)
-
-前端做的事情：
-
-- 左侧增加“写作工作流模式”
-- 展示多 Agent 执行进度与中间产物
-- 提供提纲确认和指定章节重写
-- 将初稿、终稿同步到右侧 artifact
-
-前端不做的事情：
-
-- 不重写右侧编辑器
-- 不重写现有普通 chat 流程
-- 不把 workflow 状态散落在多个旧 context 里
-
-## 2.2 后端边界
-
-后端采用独立新路线：
-
-推荐目录：
-
-```text
-offline-backend-20260512/
-  apps/
-    ai_writing_orchestrator/
-      api/
-      application/
-      domain/
-      infrastructure/
-      prompts/
-      tests/
-```
-
-后端做的事情：
-
-- 实现写作 workflow 状态机
-- 实现 A/B/C Agent 与 Supervisor
-- 接内网模型与内网检索
-- 输出标准事件流和文章 artifact
-
-后端不做的事情：
-
-- 不直接改现有 DeerFlow 主流程
-- 不把工作流逻辑塞到现有通用 thread 协议里
-
-## 2.3 资料搜集边界
-
-第一版处于互联网开发阶段，因此研究员的资料搜集先走互联网检索，不接内网检索服务。
-
-第一版要求：
-
-- 研究员可以调用互联网搜索能力收集公开资料
-- 研究结果必须保留来源 URL、标题、摘要、抓取时间
-- 检索层必须抽象成统一接口，不能把互联网搜索逻辑写死在 Agent prompt 或 graph 节点里
-
-第二版预留：
-
-- 后续替换或并行接入内网搜索接口
-- 后续接入内部知识库、文档库、FAQ、项目复盘库
-- 前端和工作流层不因检索源变化而改协议
-
-统一设计要求：
-
-- `Researcher` 只依赖“检索接口”，不依赖具体是互联网还是内网
-- `writing_graph` 只读取标准化后的素材结果
-- API、事件流、artifact 结构不区分互联网资料和内网资料
-
-推荐检索抽象：
-
-```text
-infrastructure/
-  retrieval/
-    base.py
-    internet_search_client.py
-    intranet_search_client.py
-    retriever_router.py
-```
-
-建议接口：
-
-```python
-class RetrievalProvider(Protocol):
-    def search(self, query: str, top_k: int) -> list[RetrievedDocument]: ...
-
-class RetrievedDocument(BaseModel):
-    title: str
-    url: str | None
-    source_type: str
-    snippet: str
-    published_at: str | None = None
-    fetched_at: str
-    reliability: str | None = None
-```
-
-第一版路由策略：
-
-- 默认 `internet`
-- 配置项预留 `intranet`、`hybrid`
-
-例如：
-
-```yaml
-retrieval:
-  provider: internet
-  top_k: 8
-  timeout_seconds: 15
-```
-
-这样第一版先跑公网资料，后续切换内网时，只替换 `retriever_router` 和对应 provider，不改 workflow 主逻辑。
-
----
-
-## 3. 第一版产品目标
-
-用户在 `open-canvas` 中选择“写作工作流模式”后，可以完成以下流程：
-
-1. 输入主题、体裁、读者、风格、篇幅
-2. 研究员搜集资料并输出素材卡片
-3. 提纲 Agent 生成提纲
-4. 用户确认提纲
-5. Writer 生成初稿
-6. Editor 给出问题清单与评分
-7. 不达标则重写一次或两次
-8. 终稿写入右侧 artifact
-
-第一版成功标准：
-
-- 不是“生成得像最强模型一样好”
-- 而是“明显优于单轮直出，并且流程可控、可回退、可人工介入”
-
-## 3.1 第一版研究员目标
-
-第一版 `Researcher` 的核心职责，不是“写文章”，而是“给 Writer 准备可信、可引用、可筛选的素材”。
-
-第一版输入：
-
-- 用户主题
-- 用户写作要求
-- 检索源配置，第一版默认 `internet`
-
-第一版输出至少包含：
-
-- `material_cards`
-- `facts`
-- `quotes`
-- `examples`
-- `risks`
-- `source_refs`
-
-每条素材最少要带：
-
-- 来源标题
-- 来源 URL
-- 摘要
-- 可信度标签
-- 被引用的原始片段或整理后的事实点
-
-第一版 Researcher 的程序流程建议：
-
-1. 根据主题自动生成 3-5 个检索 query
-2. 调用互联网检索接口拿回候选文档
-3. 做去重、裁剪、初筛
-4. 让模型将结果整理成结构化素材卡片
-5. 将结构化结果返回给 Outliner 和 Writer
-
-第一版先不做：
-
-- 深度网页 crawling
-- 多轮自动追问式深研究
-- 内网知识库接入
-- 复杂引用格式生成
-
----
-
-## 4. 最终工作流
-
-## 4.1 Agent 角色
-
-### `Researcher`
-
-职责：
-
-- 从配置的检索源检索信息
-- 产出结构化素材卡片
-- 标注来源、可信度、风险点
-
-第一版说明：
-
-- 默认走互联网公开资料检索
-- 必须预留后续切换到内网检索源的接口
-- 检索实现放在 `infrastructure/retrieval/`，不要写死在 prompt 中
-
-第一版检索源字段建议：
-
-- `source_type = "internet"`
-- 后续预留 `source_type = "intranet" | "hybrid"`
-
-输出：
-
-- `material_cards`
-- `facts`
-- `quotes`
-- `examples`
-- `risks`
-- `source_refs`
-
-### `Outliner`
-
-职责：
-
-- 根据用户要求和研究结果生成提纲
-
-输出：
-
-- `title_candidates`
-- `outline_sections`
-- `key_points_per_section`
-
-### `Writer`
-
-职责：
-
-- 基于提纲和素材写初稿
-- 按章节写，不一次生成整篇长文
-
-输出：
-
-- `draft_sections`
-- `section_source_refs`
-- `full_draft_markdown`
-
-### `Editor`
-
-职责：
-
-- 检查事实、结构、文风
-- 给出评分与重写建议
-
-输出：
-
-- `issues`
-- `severity`
-- `score`
-- `rewrite_instructions`
-- `decision`
-
-### `Supervisor`
-
-职责：
-
-- 负责流程调度
-- 负责通过 / 重写 / 人工介入判断
-
-## 4.2 状态机
-
-第一版统一采用：
-
-- `idle`
-- `collecting_materials`
-- `generating_outline`
-- `await_outline_confirmation`
-- `writing_draft`
-- `reviewing_draft`
-- `rewriting_draft`
-- `completed`
-- `failed`
-- `human_intervention_required`
-
-## 4.3 流程闭环
-
-最小闭环固定为：
-
-1. `Research`
-2. `Outline`
-3. `HumanConfirmOutline`
-4. `Draft`
-5. `Review`
-6. `RewriteIfNeeded`
-7. `Complete`
-
-重试规则：
-
-- 最多重写 2 次
-- 达标则完成
-- 超限则进入人工介入
-
-## 4.4 LangGraph 推荐节点
-
-第一版推荐节点：
-
-- `load_input`
-- `build_search_queries`
-- `retrieve_materials`
-- `normalize_materials`
-- `generate_outline`
-- `wait_for_outline_confirmation`
-- `write_sections`
-- `merge_sections`
-- `review_draft`
-- `rewrite_sections`
-- `publish_final_artifact`
-
-其中和资料搜集直接相关的节点说明：
-
-### `build_search_queries`
-
-职责：
-
-- 根据用户主题和目标文章类型，生成 3-5 个检索 query
-
-### `retrieve_materials`
-
-职责：
-
-- 调用检索 provider 获取候选文档
-- 第一版默认走 `internet_search_client`
-- 后续可切到 `intranet_search_client`
-
-### `normalize_materials`
-
-职责：
-
-- 做去重
-- 做摘要裁剪
-- 做来源字段统一
-- 输出标准 `RetrievedDocument[]`
-
----
-
-## 5. 前端最终做法
-
-## 5.1 目录建议
-
-在现有 `open-canvas` 下新增：
-
-```text
-frontend-web/src/open-canvas/
-  workflow/
-    api/
-      writing-workflow.ts
-    components/
-      WritingWorkflowEntryForm.tsx
-      WritingWorkflowTimeline.tsx
-      WritingWorkflowEventList.tsx
-      WritingWorkflowArtifactDrawer.tsx
-      WritingWorkflowConfirmCard.tsx
-      WritingWorkflowHeader.tsx
-      CanvasWorkflowPanel.tsx
-    contexts/
-      WritingWorkflowContext.tsx
-    hooks/
-      useWritingWorkflow.ts
-      useWritingWorkflowEvents.ts
-    types/
-      workflow.ts
-```
-
-## 5.2 左侧改造策略
-
-`CanvasChatPanel` 只承担模式切换与容器职责：
-
-- `chat` 模式：沿用现有普通聊天
-- `writing_pipeline` 模式：渲染 `CanvasWorkflowPanel`
-
-新面板负责：
-
-- 写作任务表单
-- 进度时间线
-- 事件列表
-- 中间产物抽屉
-- 提纲确认卡片
-
-## 5.3 右侧衔接策略
-
-继续复用现有 `CanvasArtifactPanel`。
-
-同步规则：
-
-- 提纲：可选同步到右侧预览
-- 初稿：同步到右侧
-- 重写稿：覆盖当前草稿
-- 终稿：作为最终 artifact
-
-## 5.4 前端状态设计
-
-新增：
-
-- `workflowMode`
-- `workflowRunId`
-- `workflowStage`
-- `workflowStatus`
-- `workflowEvents`
-- `workflowArtifacts`
-- `workflowPendingAction`
-
-注意：
-
-- workflow 状态放进新的 `WritingWorkflowContext`
-- 不塞进现有 `CanvasGraphContext`
-
-## 5.5 前端显示的资料信息
-
-第一版左侧至少要能展示研究员产出的资料摘要：
-
-- 来源标题
-- 来源域名或 URL
-- 资料摘要
-- 可信度标签
-- 是否被提纲或正文引用
-
-建议在 `WritingWorkflowArtifactDrawer.tsx` 中增加“素材卡片”视图。
-
-注意：
-
-- 第一版显示公开互联网来源即可
-- 后续接内网时，这个展示层不变，只是来源字段从 URL 变成内网文档标识或内部链接
-
----
-
-## 6. 后端最终做法
-
-## 6.1 分层
-
-推荐分层：
-
-```text
-api/
-application/
-domain/
-infrastructure/
-prompts/
-tests/
-```
-
-## 6.2 核心模块
-
-建议核心文件：
-
-```text
-domain/
-  models/
-    workflow.py
-    workflow_stage.py
-    workflow_event.py
-    artifact.py
-    review_result.py
-  agents/
-    researcher.py
-    outliner.py
-    writer.py
-    editor.py
-    supervisor.py
-  graphs/
-    writing_graph.py
-  policies/
-    retry_policy.py
-    quality_policy.py
-```
-
-## 6.3 检索层实现要求
-
-第一版检索层必须独立成基础设施模块，不允许：
-
-- 在 Agent prompt 中直接拼接“去网上找资料”
-- 在 graph 节点中散落请求第三方搜索的代码
-- 把互联网检索和内网检索混在一个无抽象的函数里
-
-建议结构：
-
-```text
-infrastructure/
-  retrieval/
-    base.py
-    internet_search_client.py
-    intranet_search_client.py
-    retriever_router.py
-    material_normalizer.py
-```
-
-建议职责：
-
-- `internet_search_client.py`
-  - 第一版实际使用
-  - 对接互联网搜索 API 或爬取网关
-
-- `intranet_search_client.py`
-  - 第一版只保留接口和空实现或 mock
-  - 后续接企业内部接口
-
-- `retriever_router.py`
-  - 根据配置选择 provider
-
-- `material_normalizer.py`
-  - 统一清洗和标准化结果
-
-## 6.4 Prompt 管理
-
-统一独立存放：
-
-```text
-prompts/
-  researcher/
-    system.txt
-    output_schema.json
-  outliner/
-    system.txt
-    output_schema.json
-  writer/
-    system.txt
-    output_schema.json
-  editor/
-    system.txt
-    output_schema.json
-  supervisor/
-    system.txt
-```
-
-## 6.5 输出约束
-
-每个 Agent 都必须：
-
-- 优先输出 JSON / Pydantic schema
-- 失败时允许轻量 repair 和一次重试
-- 避免自由散文式输出
-
-## 6.6 Researcher 的实现细则
-
-Researcher 推荐由两部分组成：
-
-1. 程序化检索
-2. 模型化整理
-
-推荐伪流程：
-
-```python
-def run_research(topic: str, article_type: str, provider: RetrievalProvider):
-    queries = build_queries(topic, article_type)
-    raw_docs = []
-    for query in queries:
-        raw_docs.extend(provider.search(query=query, top_k=5))
-    docs = normalize_materials(raw_docs)
-    docs = dedupe_materials(docs)
-    docs = rank_materials(docs)
-    return llm_extract_material_cards(docs)
-```
-
-第一版建议：
-
-- 先把 query 生成逻辑做简单
-- `top_k` 先控制在 5-10
-- 先做轻量去重和摘要裁剪
-- 不做很重的网页全文抓取
-
----
-
-## 7. 前后端协议
-
-## 7.1 API
-
-第一版统一提供：
-
-- `POST /api/ai-writing/workflows`
-- `POST /api/ai-writing/workflows/{id}/start`
-- `GET /api/ai-writing/workflows/{id}`
-- `GET /api/ai-writing/workflows/{id}/events`
-- `POST /api/ai-writing/workflows/{id}/confirm-outline`
-- `POST /api/ai-writing/workflows/{id}/rewrite-section`
-- `POST /api/ai-writing/workflows/{id}/approve-final`
-
-## 7.2 SSE 事件
-
-统一事件类型：
-
-- `workflow_started`
-- `stage_changed`
-- `agent_started`
-- `agent_output_chunk`
-- `artifact_generated`
-- `human_confirmation_required`
-- `retry_scheduled`
-- `workflow_completed`
-- `workflow_failed`
-
-第一版前端不需要消费复杂嵌套事件，只要先把这 9 类打通。
-
-## 7.3 配置项补充
-
-建议增加以下配置项：
-
-```yaml
-retrieval:
-  provider: internet
-  top_k: 8
-  timeout_seconds: 15
-  enable_content_fetch: false
-
-workflow:
-  max_revisions: 2
-
-models:
-  researcher: your-default-model
-  outliner: your-default-model
-  writer: your-default-model
-  editor: your-default-model
-```
-
-说明：
-
-- 第一版 `provider=internet`
-- 第二版可切成 `intranet` 或 `hybrid`
-
----
-
-## 8. 必须做 / 延后做 / 不建议现在做
-
-## 8.1 必须做
-
-### 架构
-
-- 独立后端路线 `ai-writing-orchestrator`
-- 前端独立 `workflow/` 目录
-- LangGraph 状态机
-- `Researcher / Outliner / Writer / Editor / Supervisor`
-- 独立检索抽象层，第一版先落互联网 provider
-
-### 协议
-
-- 标准 workflow 状态枚举
-- 标准 SSE 事件枚举
-- 标准 artifact 结构
-- JSON / Pydantic 输出约束
-
-### 功能
-
-- 启动写作任务
-- 研究阶段
-- 提纲阶段
-- 提纲确认
-- 初稿生成
-- 审稿与最多 2 次重写
-- 终稿同步到右侧
-- 素材卡片展示
-- 来源 URL、标题、摘要、可信度落库或挂在 artifact metadata
-
-### UI
-
-- 模式切换
-- 时间线
-- 事件列表
-- 提纲确认卡片
-- 右侧终稿显示
-- 左侧素材卡片视图
-
-## 8.2 延后做
-
-- 章节级精准重写
-- 初稿多版本树
-- FactChecker
-- StyleEditor
-- ComplianceReviewer
-- 自动评分看板
-- 素材引用可视化高亮
-- 更复杂的人机协作节点
-- 内网知识库正式接入
-- 混合检索 `hybrid`
-- 网页全文抓取与深摘要
-
-## 8.3 不建议现在做
-
-- 直接接入现有 DeerFlow 主 agent 包
-- 同时试 MetaGPT、CrewAI、AutoGen 多套底座
-- 一开始就做 5 个以上 Agent
-- 一开始就做很复杂的文章版本管理
-- 一开始就把评分阈值和 prompt 写死得非常细
-
-## 9. 最终开发顺序
-
-## Step 1：先定契约
-
-先一起拍板：
-
-- stage 枚举
-- event 枚举
-- artifact 结构
-- confirm / rewrite 的 payload
-- retrieval provider 接口
-- RetrievedDocument 结构
-
-## Step 2：先做 fake workflow
-
-后端先不接真实模型，只吐 mock SSE 事件，前端把左侧工作台跑通。
-
-## Step 3：先接互联网版 Researcher + Outliner
-
-优先打磨“研究 + 提纲”，这是弱模型提升最大的部分。
-
-这一阶段要求：
-
-- `Researcher` 先走互联网检索
-- `retriever_router` 可配置
-- `intranet_search_client` 先留接口空壳
-
-## Step 4：接 Writer + Editor
-
-再补初稿与审稿重写闭环。
-
-## Step 5：接右侧 artifact
-
-把初稿和终稿稳定写入右侧。
-
-## Step 6：补生产化
-
-- 缓存
-- 日志
-- 错误回放
-- 配置化 prompt
-
-## 10. 推荐任务拆分
-
-## 前端
-
-- `CanvasChatPanel` 模式切换
-- `workflow/` 目录与类型
-- 时间线 / 事件列表 / 确认卡片
-- SSE 订阅 hook
-- 右侧 artifact 映射
-- 素材卡片列表展示
-- 来源字段展示规范
-
-## 后端
-
-- workflow API
-- LangGraph graph
-- 5 个 Agent 模块
-- Prompt 目录
-- SSE 输出
-- 仓储与日志
-- `RetrievalProvider` 抽象
-- `internet_search_client`
-- `intranet_search_client` 预留接口
-- `material_normalizer`
-
-## Prompt / 算法
-
-- Researcher prompt
-- Outliner prompt
-- Writer prompt
-- Editor prompt
-- JSON schema
-- 失败样本回归
-
-## 联调
-
-- mock SSE
-- 真模型接入
-- artifact 同步校验
-- 提纲确认链路验证
-- 互联网资料来源字段联调
-- 素材卡片到提纲引用链路联调
-
----
-
-## 11. 开发过程中的约束
-
-开发过程中统一采用下面这套口径：
-
-- 产品形态：当前 `open-canvas` 页面上的“写作工作流模式”
-- 技术底座：`LangGraph`
-- 核心模式：`Researcher -> Outliner -> Writer -> Editor -> Supervisor`
-- 后端方式：独立 `ai-writing-orchestrator`
-- 检索方式：第一版 `internet`，接口预留 `intranet`
-- 通信方式：`SSE`
-- 输出方式：`JSON Schema / Pydantic`
-- 第一版目标：先做最小闭环，不追求角色数量和复杂度
-
-给开发团队的统一口径：
-
-“我们在 `open-canvas` 上开发写作工作流模式，后端单开 `ai-writing-orchestrator`，第一版先用互联网资料检索，保留内网检索接入口，用 LangGraph 编排 Researcher、Outliner、Writer、Editor、Supervisor，把研究、提纲、初稿、审稿重写这条最小闭环做稳。”

frontend-web/docs/ai-writing-frontend-dev.md

@@ -1,538 +0,0 @@
-# AI 写作 — 前端开发文档
-
-> **本文档目的**：帮助前端开发者快速理解 AI 写作子系统的代码结构、数据流、状态机和扩展点。
->
-> **配套文档**：
-> - `ai-writing-说明.md` — 故障排查与运维向解决方案
-> - `ai-writing-assistant-backend-api.md` — 后端 API 详细字段定义
-> - `ai-writing-assistant-source-map.md` — 旧版前端结构索引（已合并到本文档）
-
----
-
-## 一、产品定位
-
-AI 写作是 DeerFlow 的「**杂志社协作写作**」子产品，由 LangGraph 后端驱动 4 个 AI Agent（**素材收集专家 / 作家 / 编辑 / 系统**）协作完成一篇文章。用户通过 **4 个干预点**（素材确认、大纲确认、草稿确认、审核确认）参与决策，UI 实时呈现进度。
-
-### UI 入口
-- 路由：`/canvas/ai-writing`（在 `WorkspaceRoutes.tsx` 注册）
-- 入口页：`src/open-canvas/pages/AIWritingPage.tsx`
-- 双栏布局：左 AI 写作面板（聊天 + 干预），右草稿预览
-
----
-
-## 二、目录结构
-
-```
-frontend-web/src/open-canvas/
-├── pages/
-│   └── AIWritingPage.tsx              # 入口页（双栏 Resizable 布局）
-│
-├── api/                               # ── 后端 API 适配层 ──
-│   ├── ai-writing.ts                  # /start /resume + SSE 订阅（核心）
-│   ├── ai-writing-sessions.ts         # 历史会话 CRUD + transcript 保存
-│   └── ai-writing-article-types.ts    # 文章类型 CRUD
-│
-├── hooks/                             # ── 状态管理 ──
-│   ├── useAIWriting.ts                # 写作主状态机（最重要）
-│   ├── useAIWritingSessions.ts        # 历史会话列表 hook
-│   └── useArticleTypes.ts             # 文章类型选项 hook
-│
-├── components/ai-writing/             # ── UI 组件 ──
-│   ├── AIWritingPanel.tsx             # 左侧主面板（聊天 + 干预编排）
-│   ├── AIWritingDraftPanel.tsx        # 右侧草稿预览面板
-│   ├── AIWritingPageHeader.tsx        # 顶部标题/历史下拉
-│   ├── AIWritingForm.tsx              # 写作请求表单（首次启动用）
-│   │
-│   ├── AIWritingTimeline.tsx          # 时间线主容器
-│   ├── TimelineStep.tsx               # 单条进度事件
-│   ├── CompletedInterventionCard.tsx  # 已完成的干预记录
-│   │
-│   ├── InterventionCard.tsx           # 4 个干预点 + 求助点的卡片（核心）
-│   ├── MaterialsCard.tsx              # 素材确认
-│   ├── MaterialItem.tsx               # 单个素材项
-│   ├── MaterialsToolbar.tsx           # 素材筛选/搜索工具栏
-│   ├── OutlineCard.tsx                # 大纲确认（含编辑）
-│   ├── OutlineSection.tsx             # 大纲单章节
-│   ├── ReviewCard.tsx                 # 审核确认
-│   ├── IssueList.tsx                  # 审核意见列表
-│   ├── ScoreBar.tsx                   # 评分进度条
-│   │
-│   ├── OutlineStreamingView.tsx       # 大纲流式打字机
-│   ├── DraftStreamingView.tsx         # 草稿流式打字机
-│   ├── ReviewStreamingView.tsx        # 审核流式打字机
-│   ├── WritingSkeletonCard.tsx        # 加载骨架屏
-│   ├── RevisionSummaryCard.tsx        # 修改前后对比摘要
-│   │
-│   ├── AIWritingHistoryDropdown.tsx   # 历史会话下拉
-│   └── AIWritingHistoryView.tsx       # 历史会话只读回显
-│
-└── types/
-    └── ai-writing.ts                   # 全部类型定义（重要参考）
-```
-
----
-
-## 三、数据流总览
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                       AIWritingPanel                            │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │  useAIWriting() 主状态 hook                              │   │
-│  │  ┌────────────────────────────────────────────────────┐  │   │
-│  │  │  startWriting()  ─── POST /api/ai-writing/start    │  │   │
-│  │  │                       ↓ 返回 session_id            │  │   │
-│  │  │                                                    │  │   │
-│  │  │  subscribeToProgress(sessionId)                    │  │   │
-│  │  │      ─── GET /api/ai-writing/{id}/stream (SSE)     │  │   │
-│  │  │      ─── 持续推 ProgressEvent 给 handleEvent       │  │   │
-│  │  │      ─── handleEvent reducer → setState            │  │   │
-│  │  │                                                    │  │   │
-│  │  │  submitIntervention()                              │  │   │
-│  │  │      ─── POST /api/ai-writing/{id}/resume          │  │   │
-│  │  │      ─── graph 续推 → 新事件继续走 SSE             │  │   │
-│  │  │                                                    │  │   │
-│  │  │  saveAIWritingTranscript()（fire-and-forget）      │  │   │
-│  │  │      ─── PUT /api/ai-writing/sessions/{id}/transcript │ │
-│  │  └────────────────────────────────────────────────────┘  │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│                                                                 │
-│  渲染：                                                         │
-│  ├ AIWritingForm（idle 状态）                                   │
-│  ├ AIWritingTimeline（运行中）                                  │
-│  │   ├ TimelineStep × N（progressEvents）                       │
-│  │   └ CompletedInterventionCard × N（已完成的干预）            │
-│  ├ {Outline,Draft,Review}StreamingView（流式打字机）            │
-│  ├ InterventionCard（当前 currentPause 存在时弹出）             │
-│  └ WritingSkeletonCard（运行中无 pause 时的骨架屏）             │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 四、状态机（useAIWriting.ts）
-
-### 状态字段（完整定义见 `types/ai-writing.ts`）
-
-```typescript
-interface AIWritingState {
-  // —— 核心标识 ——
-  sessionId: string | null;         // 后端返回的会话 id
-  status: WritingStatus;            // 当前阶段（13 种状态之一）
-  isPaused: boolean;                // 是否在干预点等待用户
-  error: string | null;
-
-  // —— 配置 ——
-  request: AIWritingRequest | null; // 用户提交的写作请求
-
-  // —— 累计数据 ——
-  progressEvents: ProgressEvent[];  // SSE 事件全量历史（供时间线渲染）
-  materials: AIMaterial[];          // 素材列表（素材就绪后填充）
-  outline: AIOutline | null;        // 大纲（大纲就绪后填充）
-  currentDraftMarkdown: string;     // 草稿正文（草稿就绪后填充）
-  currentDraftTitle: string;
-  reviewResult: ReviewResult | null;
-  revisionCount: number;
-  completedInterventions: CompletedIntervention[];  // 已完成的干预历史
-
-  // —— 干预 ——
-  currentPause: ProgressEvent | null;  // 当前挂起的 await_user 事件
-
-  // —— 流式视图状态 ——
-  streamingDraftTitle: string;
-  streamingDraftSections: StreamingDraftSection[];
-  outlineStreamingText: string;
-  outlineThinkingText: string;
-  researchProgress: string;
-  streamingReviewItems: StreamingReviewItem[];
-  revisionSummary: RevisionSummary | null;
-  pendingRevisionContext: { /* ... */ } | null;
-}
-```
-
-### 状态转移图（写作状态机）
-
-```
-                ┌──────┐
-                │ idle │ ←─────────────────────────────────────┐
-                └──┬───┘                                       │
-                   │ startWriting()                            │
-                   ↓                                           │
-            ┌─────────────────┐                                │
-            │  researching    │                                │
-            └──┬──────────────┘                                │
-               ↓ materials_ready                               │
-            ┌─────────────────────────────┐                    │
-            │ awaiting_material_confirm   │ ← await_user       │
-            └──┬──────────────────────────┘                    │
-               ↓ submit(confirm)                               │
-            ┌─────────────────┐                                │
-            │ writing_outline │ ← (re_search 路径)             │
-            └──┬──────────────┘                                │
-               ↓ outline_ready                                 │
-            ┌─────────────────────────────┐                    │
-            │ awaiting_outline_confirm    │                    │
-            └──┬──────────────────────────┘                    │
-               ↓ submit(confirm)                               │
-            ┌─────────────────┐                                │
-            │ writing_draft   │ ← (re_outline 路径)            │
-            └──┬──────────────┘                                │
-               │                                               │
-       ┌───────┴────────┐                                      │
-       ↓                ↓                                      │
-  awaiting_section_   awaiting_draft_confirm                   │
-   help (素材不足)    └─┬───┬───┬──────────────┐               │
-       │ (supplement)   │   │   │ to_editor    │               │
-       │ ↑回到 research │   │   ↓              │               │
-       │                │   │ reviewing        │               │
-       │                │   │ └─┬──────┐       │               │
-       │                │   │   ↓      ↓      │               │
-       │                │   │ awaiting_review_confirm          │
-       │                │   │   └─┬────────┐                   │
-       │                │   │     ↓ submit  ↓                  │
-       │                │   │   revising   done ───────────────┘
-       │                │   │     │
-       │                │   │     └─→ writing_draft (循环修订)
-       │                │   │
-       │                │   │ user_revise
-       │                │   └─→ revising
-       │                │
-       │                │ finalize
-       │                └─→ done
-       │
-       └──→ (delete/loose) writing_draft 继续
-```
-
-### handleEvent reducer（核心）
-
-`useAIWriting.ts` 里的 `handleEvent` 是个**纯 reducer**，根据 SSE 事件类型更新状态：
-
-| 事件类型 | 主要影响的状态字段 |
-|---|---|
-| `connected` | 仅记录到 progressEvents |
-| `step_start` | 切到对应 `status`（如「编辑」→ reviewing） |
-| `step_done` | 仅记录 |
-| `research_progress` | `researchProgress`（实时检索进度文案） |
-| `materials_ready` | `materials`、清空 researchProgress |
-| `outline_chunk` | `outlineStreamingText` / `outlineThinkingText`（打字机） |
-| `outline_ready` | `outline`、清空流式文本 |
-| `draft_chunk` | `streamingDraftSections`（按章节拼接打字机） |
-| `draft_ready` | `currentDraftMarkdown` / `currentDraftTitle` |
-| `review_chunk` | `streamingReviewItems[i].streamingText`（逐条打字机） |
-| `review_item_done` | `streamingReviewItems[i]` 标记 isDone + 结构化结果 |
-| `review_ready` | `reviewResult` |
-| `await_user` | `currentPause = event`，`isPaused = true`，**弹出 InterventionCard** |
-| `resumed` | `currentPause = null` |
-| `notice` | 仅记录（非致命告警） |
-| `done` | `status = 'done'` |
-| `error` | `status = 'error'`，`error = event.message` |
-
----
-
-## 五、API 层（api/）
-
-### 1. `api/ai-writing.ts` — 核心写作 API
-
-```typescript
-// 启动写作 → 返回 session_id
-export async function startWritingSession(req: AIWritingRequest): Promise<string>
-
-// 订阅 SSE 进度流 → 返回取消订阅函数
-export function subscribeToProgress(
-  sessionId: string,
-  onEvent: (event: ProgressEvent) => void,
-): () => void
-
-// 提交用户干预 → 让 graph 续推
-export async function resumeWriting(
-  sessionId: string,
-  payload: UserInterventionPayload,
-): Promise<void>
-```
-
-**关键实现细节**：
-- **snake_case ↔ camelCase 转换**：后端返回 snake_case，前端类型是 camelCase。所有 normalize 函数（`normalizeMaterial`、`normalizeOutlineSection`...）集中在这一层做转换
-- **SSE 事件白名单**：`SSE_EVENT_TYPES` 数组列出所有合法事件名，未知事件会被静默忽略
-- **取消订阅**：`subscribeToProgress` 返回的函数会调用 `AbortController.abort()` 关闭 fetch stream
-- **重连机制**：当前**没有内置重连** — 如果 SSE 断开（网络抖动、反代超时），需要用户主动重启写作或刷新页面
-  - 后端 `_recover_session` 能让 SSE 重连时从 checkpointer 恢复事件，但前端没主动重连逻辑
-
-### 2. `api/ai-writing-sessions.ts` — 历史会话
-
-```typescript
-// CRUD
-listAIWritingSessions()                  : Promise<AIWritingSessionSummary[]>
-getAIWritingSession(id)                  : Promise<AIWritingSessionSummary>
-renameAIWritingSession(id, title)        : Promise<AIWritingSessionSummary>
-deleteAIWritingSession(id)               : Promise<void>
-
-// 时间线持久化（fire-and-forget，永不抛错）
-saveAIWritingTranscript(id, transcript)  : Promise<boolean>
-```
-
-**关键设计**：`saveAIWritingTranscript` 内部用 try/catch 吞掉所有异常（网络错误、HTTP 500 等），只 `console.warn` 不影响主流程。这是**「锦上添花」契约**的前端侧。
-
-### 3. `api/ai-writing-article-types.ts` — 文章类型管理
-
-| 函数 | 用途 |
-|---|---|
-| `listArticleTypes()` | 表单下拉框选项 |
-| `createArticleType()` | 管理员新增 |
-| `updateArticleType()` | 管理员编辑 |
-| `deleteArticleType()` | 管理员删除 |
-
----
-
-## 六、组件树详解
-
-### 顶层：`AIWritingPanel`（457 行，最大）
-
-负责：
-1. 调用 `useAIWriting()` 拿主状态
-2. 调用 `useAIWritingSessions()` 拿历史列表
-3. 协调表单 / 时间线 / 干预卡 / 流式视图 / 草稿同步
-4. **自动滚底逻辑**：检测用户是否手动上划，决定是否跟随最新内容
-5. **草稿同步到右侧画布**：监听 `currentDraftMarkdown` 变化，调 `setArtifact` 更新右侧
-6. **历史会话回显**：当 `historySession` 非空时，渲染 `AIWritingHistoryView` 而不是实时面板
-
-### 干预卡：`InterventionCard`（663 行，第二大）
-
-按 `pausePoint` 渲染**不同的卡片**：
-
-| pausePoint | 卡片 | 用户能做的 |
-|---|---|---|
-| `material_confirm` | `MaterialsCard` | 勾选保留素材 / 加关键词重新搜 |
-| `outline_confirm` | `OutlineCard` | 直接编辑大纲 / 给反馈让重写 |
-| `draft_confirm` | 草稿确认卡 | 定稿 / 给修订意见 / 提交编辑审核 |
-| `review_confirm` | `ReviewCard` | 勾选采纳的意见 / 强制通过 |
-| `section_help` | 求助卡 | 逐章选择：补充检索 / 删除 / 按通用知识续写 |
-
-### 时间线：`AIWritingTimeline`
-
-迭代 `progressEvents`，每个 `step_start` / `step_done` / `notice` 渲染成一条 `TimelineStep`。`CompletedInterventionCard` 穿插显示已完成的干预记录。
-
-### 流式视图：`{Outline,Draft,Review}StreamingView`
-
-- **OutlineStreamingView**：打字机渲染 `outlineStreamingText`，支持 `<think>...</think>` 折叠显示
-- **DraftStreamingView**：按章节流式拼接 `streamingDraftSections`，每章节独立打字机
-- **ReviewStreamingView**：3 条审核（事实 / 逻辑 / 语言）并行打字机，完成后切到结构化评分
-
-### 历史回显：`AIWritingHistoryView`
-
-只读模式，从 `AIWritingSessionSummary` 重建 UI。**当 `transcript` 字段有值时**，从里面拿到完整 `progressEvents`，UI 表现跟实时一模一样。`transcript` 没有时退回到只显示最终草稿。
-
----
-
-## 七、SSE 事件协议（前后端契约）
-
-后端通过 SSE 推 `event: <type>\ndata: <json>\n\n` 格式，前端用浏览器原生 `fetch + ReadableStream` 解析（不用 `EventSource`，因为 EventSource 不能自定义 header）。
-
-### 解析流程
-
-```
-ReadableStream → TextDecoder
-              → 按 "\n\n" 分帧
-              → 每帧匹配 /^event: (.+)\ndata: (.+)$/
-              → JSON.parse(data)
-              → normalize(parsed)（snake → camel）
-              → onEvent(normalized)
-```
-
-### 事件载荷字段（不完全列表）
-
-| 字段 | 出现在哪些事件 | 用途 |
-|---|---|---|
-| `type` | 全部 | 事件类别 |
-| `sessionId` | 全部 | 标识 |
-| `message` | 大多数 | 显示给用户的文案 |
-| `agentName` | step_*  | 「素材收集专家」/「作家」/「编辑」/「系统」 |
-| `materials` | materials_ready | 素材数组 |
-| `outline` | outline_ready | 大纲对象 |
-| `draftMarkdown` / `draftTitle` | draft_ready | 草稿内容 |
-| `reviewResult` | review_ready | 完整审核结果 |
-| `pausePoint` | await_user | 哪个干预点 |
-| `pauseContext` | await_user | 干预所需的上下文（如待确认的素材列表） |
-| `blockedSections` | await_user (section_help) | 素材不足的章节列表 |
-| `title` / `detail` / `raw` | notice / error | 非致命告警的标题、详情、原始错误 |
-
----
-
-## 八、扩展指南：常见开发任务
-
-### 新增一个干预点
-
-1. **前端类型扩展**：
-   - 在 `types/ai-writing.ts` 的 `ProgressEvent.pausePoint` 联合类型里加新 case
-   - 在 `WritingStatus` 加对应的 `awaiting_xxx`
-   - 在 `CompletedIntervention.pausePoint` 加 case
-
-2. **写 InterventionCard 分支**：在 `InterventionCard.tsx` 里加新 `pausePoint` 分支，做 UI + 提交逻辑
-
-3. **后端配合**（详见后端开发文档）：
-   - `graph.py` 加 `pause_xxx_confirm` 节点
-   - graph 拓扑加这个节点的边
-
-4. **完成干预后的清理**：在 `useAIWriting.ts` 的 `submitIntervention` 函数里，**确保把这次干预 push 到 `completedInterventions`**，让历史能看到
-
-### 新增一个 SSE 事件类型
-
-1. `types/ai-writing.ts`：
-   - `ProgressEventType` 联合类型加新值
-   - `ProgressEvent` 接口加新字段（如果有载荷）
-
-2. `api/ai-writing.ts`：
-   - `SSE_EVENT_TYPES` 数组加新值（不加会被忽略）
-   - `normalizeEvent` 函数里加字段转换（如果是 snake_case 需要 normalize）
-
-3. `useAIWriting.ts` 的 `handleEvent`：加新 case 处理状态更新
-
-4. 组件层：根据需要在时间线 / 干预卡 / 流式视图里渲染
-
-### 修改一个流式打字机的行为
-
-每个 streaming view 内部都是独立的：
-- 状态在 `useAIWriting.ts` 的 `streaming*` 系列字段
-- 渲染在 `*StreamingView.tsx`
-- 流式 chunk 处理在 `handleEvent` 的 `outline_chunk` / `draft_chunk` / `review_chunk` 分支
-
-### 新增草稿到右侧画布的逻辑
-
-`AIWritingPanel.tsx` 里 `useEffect` 监听 `state.currentDraftMarkdown` → 调 `setArtifact` 更新右侧 `CanvasGraphContext`。如果需要新的 artifact 类型，看 `contexts/CanvasGraphContext.tsx` 的 artifact 接口。
-
----
-
-## 九、容错与边界处理
-
-### 已落实的容错（不会阻断写作）
-- ✅ `saveAIWritingTranscript` 失败仅 `console.warn`
-- ✅ 历史会话列表加载失败仅 `console.warn`
-- ✅ 重命名/删除会话失败静默吞掉
-- ✅ 后端 SSE 推 `notice` / `error` 事件时，前端只渲染不中断
-- ✅ JSON parse 失败时 SSE 帧被静默丢弃（不影响后续帧）
-
-### 已知边界（可能影响 UI 体验）
-- ⚠️ **SSE 断线无自动重连** — 网络抖动 / 反代超时后用户需要手动刷新
-- ⚠️ **多 worker 部署下 SSE 事件丢失**（详见 `ai-writing-说明.md`）—— 前端只能感知到「卡住」，没有重连恢复机制
-- ⚠️ `outline_chunk` / `draft_chunk` / `review_chunk` 的 `text` / `is_thinking` 字段是 snake_case，前端类型是 `text` / `isThinking` 但 normalize 时是**保留 snake_case 直接读**（参考 `useAIWriting.ts` 的 `(event as unknown as { text: string }).text`），这是历史包袱，未来 normalize 函数应统一处理
-
----
-
-## 十、调试技巧
-
-### 看 SSE 原始事件
-浏览器 DevTools → Network → 找 `/api/ai-writing/<id>/stream` 请求 → Response（注意是 EventStream 格式，不能直接展开 JSON）。
-
-### 查当前 hook 状态
-在浏览器 console 里：
-```js
-// 需要安装 React DevTools，在 Components tab 找到 AIWritingPanel
-// 或在 useAIWriting 里临时加：
-useEffect(() => { (window as any).__aiwriting = state; }, [state]);
-// 然后在 console 里 __aiwriting 看
-```
-
-### 模拟事件
-开发期可以注释掉 `subscribeToProgress`，手动调 `handleEvent({...})` 测试 reducer 行为。
-
-### 看后端 transcript
-```
-GET /api/ai-writing/sessions/<id>
-```
-返回里 `transcript` 字段就是前端组装过的完整时间线 JSON。
-
----
-
-## 十一、性能注意点
-
-### 大数组渲染
-- `progressEvents` 在长写作里可能上千条 → `AIWritingTimeline` 应该考虑虚拟滚动（当前未实现，会议室会议讨论过）
-- `streamingDraftSections` 章节多时也是潜在瓶颈
-
-### transcript PUT 频率
-- 当前每次 `progressEvents` 变化都会触发保存（实际上是 useEffect 监听）
-- 大量 chunk 事件会导致**每秒 N 次 PUT**，后端 MySQL 写压力大
-- **优化建议**：在 `useAIWriting.ts` 给 saveAIWritingTranscript 加 debounce（1-2 秒），或者只在 `await_user` / `done` / `error` 关键节点保存
-
-### 浏览器内存
-- progressEvents 不主动清理 → 长会话可能占用几十 MB
-- 完成一篇文章后建议 `reset()` 清空状态
-
----
-
-## 十二、相关后端接口（速查）
-
-| 接口 | 用途 | 前端调用方 |
-|---|---|---|
-| `POST /api/ai-writing/start` | 启动写作 | `startWritingSession` |
-| `GET /api/ai-writing/{id}/stream` | SSE 进度流 | `subscribeToProgress` |
-| `POST /api/ai-writing/{id}/resume` | 提交干预 | `resumeWriting` |
-| `GET /api/ai-writing/{id}/state` | 查 graph 状态快照（调试用） | 暂未调用 |
-| `GET /api/ai-writing/sessions` | 历史列表 | `listAIWritingSessions` |
-| `GET /api/ai-writing/sessions/{id}` | 历史详情 | `getAIWritingSession` |
-| `PATCH /api/ai-writing/sessions/{id}` | 重命名 | `renameAIWritingSession` |
-| `DELETE /api/ai-writing/sessions/{id}` | 删除会话 | `deleteAIWritingSession` |
-| `PUT /api/ai-writing/sessions/{id}/transcript` | 保存时间线（fire-and-forget） | `saveAIWritingTranscript` |
-| `GET /api/ai-writing/article-types` | 文章类型下拉 | `listArticleTypes` |
-| `POST /api/ai-writing/admin/cleanup` | admin 手动清理 | 暂未在 UI 暴露 |
-
----
-
-## 十三、未来优化方向
-
-| 项目 | 说明 | 工作量 |
-|---|---|---|
-| transcript PUT 防抖 | 减少 MySQL 写压力 | 1 小时 |
-| SSE 自动重连 | 网络抖动 / 反代超时后能恢复 | 0.5 天 |
-| 时间线虚拟滚动 | 处理超长 progressEvents | 0.5 天 |
-| 干预卡组件解耦 | 663 行的 InterventionCard 拆成 5 个独立卡片 | 1 天 |
-| AbortController 串行化 | 避免重启写作时旧 SSE 还没断 | 0.5 天 |
-| 后端字段统一 camelCase | 消除 snake_case ↔ camelCase 转换层 | 需后端配合 |
-
----
-
-## 附录 A：所有类型一览
-
-完整定义在 `types/ai-writing.ts`，主要类型：
-
-```typescript
-// 业务实体
-AIMaterial            // 单个素材
-AIOutline             // 大纲
-OutlineSection        // 大纲单章节
-ReviewIssue           // 审核问题
-ReviewResult          // 完整审核结果
-BlockedSection        // 素材不足的章节
-SectionDecision       // 章节求助决策
-
-// 流程
-WritingStatus         // 13 种状态
-ProgressEventType     // 17 种事件类型
-ProgressEvent         // SSE 事件载荷
-UserInterventionPayload  // 干预提交体
-AIWritingRequest      // 启动写作的请求
-CompletedIntervention // 已完成的干预记录
-
-// 流式视图
-StreamingDraftSection
-StreamingReviewItem
-RevisionSummary
-
-// Hook 状态
-AIWritingState        // useAIWriting 的完整状态
-```
-
----
-
-## 附录 B：常见踩坑
-
-| 现象 | 原因 | 解决 |
-|---|---|---|
-| 前端类型 camelCase 但拿到 undefined | 后端 snake_case 没 normalize | 在 `api/ai-writing.ts` 的 normalize 函数里加字段 |
-| 进度卡住不动 | SSE 断了或落到错的 worker | 刷新页面，看 `ai-writing-说明.md` 多 worker 部分 |
-| 历史会话回显时间线缺失 | transcript 保存失败 | DB 列容量 / 后端日志查 `save_transcript` |
-| 修改大纲后没生效 | 用户 PATCH editedOutline 但没勾选 confirm | InterventionCard 大纲分支检查 action 字段 |
-| 草稿渲染换行错乱 | LLM 输出包含奇怪 markdown | `DraftStreamingView` 里 markdown parser 设置 |
-
----
-
-如需补充内容，请直接编辑本文件，并在 git commit message 里注明改动原因。

frontend-web/docs/ai-writing-frontend-refactor-checklist.md

@@ -1,472 +0,0 @@
-# AI 写作前端改造清单
-
-## 1. 目标
-
-在不新增第二套页面的前提下，基于现有 `open-canvas` 页面，把左侧从“单轮聊天输入框”升级为“多 Agent 写作工作台”，右侧继续沿用当前 `artifact` 编辑与流式预览能力。
-
-当前核心文件：
-
-- [CanvasResizableLayout.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/layout/CanvasResizableLayout.tsx)
-- [CanvasChatPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/chat/CanvasChatPanel.tsx)
-- [CanvasArtifactPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/artifact/CanvasArtifactPanel.tsx)
-- [CanvasGraphContext.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/contexts/CanvasGraphContext.tsx)
-- [CanvasStreamContext.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/contexts/CanvasStreamContext.tsx)
-- [useCanvasThreadStream.ts](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/hooks/useCanvasThreadStream.ts)
-- [runs.ts](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/api/runs.ts)
-
----
-
-## 2. 改造原则
-
-- 不改右侧主编辑器交互心智
-- 不复制新页面
-- 不破坏现有普通 chat 模式
-- 新增“写作工作流模式”时尽量以增量状态字段和新组件完成
-- 所有 workflow 能力都应允许逐步灰度
-
----
-
-## 3. 推荐前端结构
-
-建议在 `frontend-web/src/open-canvas` 下新增以下目录：
-
-```text
-frontend-web/src/open-canvas/
-  workflow/
-    api/
-      writing-workflow.ts
-    components/
-      WritingWorkflowEntryForm.tsx
-      WritingWorkflowTimeline.tsx
-      WritingWorkflowEventList.tsx
-      WritingWorkflowArtifactDrawer.tsx
-      WritingWorkflowConfirmCard.tsx
-      WritingWorkflowHeader.tsx
-    contexts/
-      WritingWorkflowContext.tsx
-    hooks/
-      useWritingWorkflow.ts
-      useWritingWorkflowEvents.ts
-    types/
-      workflow.ts
-    utils/
-      workflow-event.ts
-```
-
-说明：
-
-- `open-canvas` 原有聊天、artifact、editor 目录不重构
-- 以 `workflow/` 作为新能力边界，减少对既有文件的侵入
-
----
-
-## 4. 状态设计
-
-## 4.1 新增的核心状态
-
-建议新增：
-
-- `workflowMode: "chat" | "writing_pipeline"`
-- `workflowRunId: string | null`
-- `workflowStage`
-- `workflowStatus: "idle" | "running" | "waiting_user" | "completed" | "failed"`
-- `workflowEvents: WritingWorkflowEvent[]`
-- `workflowArtifacts: WritingWorkflowArtifact[]`
-- `workflowPendingAction: WritingPendingAction | null`
-
-## 4.2 推荐类型定义
-
-建议在 `workflow/types/workflow.ts` 中先定义：
-
-```ts
-export type WritingWorkflowStage =
-  | "idle"
-  | "collecting_materials"
-  | "generating_outline"
-  | "await_outline_confirmation"
-  | "writing_draft"
-  | "reviewing_draft"
-  | "rewriting_draft"
-  | "completed"
-  | "failed";
-
-export type WritingWorkflowEventType =
-  | "workflow_started"
-  | "stage_changed"
-  | "agent_started"
-  | "agent_output_chunk"
-  | "artifact_generated"
-  | "human_confirmation_required"
-  | "retry_scheduled"
-  | "workflow_completed"
-  | "workflow_failed";
-```
-
-第一版把类型先收紧，后续再扩展。
-
----
-
-## 5. 组件拆分建议
-
-## 5.1 左侧主面板改造
-
-当前 `CanvasChatPanel` 建议只承担“模式路由”和布局容器职责，不继续无限堆逻辑。
-
-建议改造为：
-
-- `chat` 模式继续渲染现有消息列表 + 输入框
-- `writing_pipeline` 模式渲染新的工作流视图
-
-建议拆分出：
-
-- `CanvasChatConversation.tsx`
-- `CanvasChatInputBox.tsx`
-- `CanvasWorkflowPanel.tsx`
-
-这样后续不会把 `CanvasChatPanel.tsx` 变成一个过大的组件。
-
-## 5.2 新增组件职责
-
-### `WritingWorkflowEntryForm.tsx`
-
-负责采集：
-
-- 主题
-- 文章类型
-- 目标读者
-- 语气风格
-- 目标篇幅
-- 是否需要引用资料
-- 禁写项
-- 补充说明
-
-### `WritingWorkflowTimeline.tsx`
-
-负责显示阶段：
-
-- 研究中
-- 提纲生成中
-- 等待确认提纲
-- 正在写初稿
-- 正在审稿
-- 正在重写
-- 已完成
-
-### `WritingWorkflowEventList.tsx`
-
-负责显示细粒度事件：
-
-- 哪个 Agent 开始执行
-- 当前在处理哪一步
-- 当前产生了什么中间结果
-- 是否重试
-
-### `WritingWorkflowArtifactDrawer.tsx`
-
-负责展示中间产物：
-
-- 素材卡片
-- 提纲
-- 初稿
-- 编辑意见
-- 重写稿
-
-### `WritingWorkflowConfirmCard.tsx`
-
-负责展示用户确认点：
-
-- 确认提纲
-- 驳回提纲并附带修改意见
-- 继续写稿
-- 指定重写章节
-
----
-
-## 6. Context 与 Hook 改造建议
-
-## 6.1 `CanvasGraphContext`
-
-当前它只维护：
-
-- `messages`
-- `artifact`
-- `streamingArtifact`
-- `isStreaming`
-
-建议不要把 workflow 状态直接塞进现有 `CanvasGraphContext`，否则会让语义过重。
-
-推荐做法：
-
-- 保留 `CanvasGraphContext` 继续服务右侧 artifact 和通用流式状态
-- 新增 `WritingWorkflowContext`
-
-## 6.2 `WritingWorkflowContext`
-
-建议承载：
-
-- 当前 workflow 运行状态
-- 中间产物列表
-- 待确认操作
-- workflow 事件缓存
-- 启动 / 取消 / 确认 / 重写等 action
-
-## 6.3 `useCanvasThreadStream`
-
-当前这个 hook 已经负责：
-
-- 创建 thread
-- 提交消息
-- 接收 thread stream
-- 将 `update_artifact` 同步到右侧
-
-建议不要把“多 Agent workflow 状态机”也硬塞进去。
-
-推荐方案：
-
-- 保留 `useCanvasThreadStream` 给普通 chat 或兼容旧能力使用
-- 新增 `useWritingWorkflow`
-- 新增 `useWritingWorkflowEvents`
-
-分工如下：
-
-- `useCanvasThreadStream`：普通对话流
-- `useWritingWorkflow`：创建 workflow、提交表单、触发确认动作
-- `useWritingWorkflowEvents`：订阅 workflow 事件流
-
----
-
-## 7. API 接入建议
-
-## 7.1 前端 API 文件
-
-新增：
-
-- `workflow/api/writing-workflow.ts`
-
-建议暴露方法：
-
-- `createWorkflow(payload)`
-- `startWorkflow(id)`
-- `getWorkflow(id)`
-- `subscribeWorkflowEvents(id, handlers)`
-- `confirmOutline(id, payload)`
-- `rewriteSection(id, payload)`
-- `approveFinal(id)`
-
-## 7.2 事件流形式
-
-优先级建议：
-
-1. `SSE`
-2. 流式 HTTP chunk
-3. 轮询兜底
-
-理由：
-
-- 事件驱动比整段消息流更适合 workflow UI
-- 可以更方便映射到时间线和事件列表
-
----
-
-## 8. 与右侧 Artifact 的衔接
-
-## 8.1 现有优势
-
-当前 `CanvasArtifactPanel` 已具备：
-
-- 流式展示内容
-- 最终 artifact 渲染
-- 右侧编辑体验成熟
-
-这意味着多 Agent 工作流不需要再做第二套文章渲染，只要把最终阶段结果推成 artifact 即可。
-
-## 8.2 建议接法
-
-工作流各阶段结果按两类处理：
-
-- 中间产物：进入左侧 `workflowArtifacts`
-- 可阅读正文：同步一份到右侧 `artifact`
-
-推荐映射：
-
-- 提纲：可选同步到右侧，供用户预览
-- 初稿：同步到右侧
-- 重写稿：覆盖或新增版本到右侧
-- 终稿：作为最终右侧主版本
-
-## 8.3 版本策略
-
-建议右侧版本保留：
-
-- `outline`
-- `draft_v1`
-- `draft_v2`
-- `final`
-
-如果现有 artifact 数据结构不方便承载完整版本树，第一版可先保留在 workflowArtifacts 中，右侧只展示当前激活版本。
-
----
-
-## 9. 页面交互流程
-
-## 9.1 用户首次进入
-
-- 默认仍是现有 chat 模式
-- 在左侧增加一个显眼切换入口：`普通对话` / `写作工作流`
-
-## 9.2 启动写作工作流
-
-- 用户填写写作任务表单
-- 点击“开始生成”
-- 左侧切换到时间线 + 事件流视图
-- 右侧进入 loading 或素材 / 提纲预览态
-
-## 9.3 等待提纲确认
-
-- 时间线停在 `await_outline_confirmation`
-- 左侧出现确认卡片
-- 用户可执行：
-  - 通过提纲
-  - 要求调整提纲
-  - 追加要求
-
-## 9.4 生成初稿与审稿
-
-- 左侧显示 Agent 事件
-- 右侧展示初稿内容
-- 审稿意见在左侧展示，同时高亮需要重写的章节
-
-## 9.5 完成
-
-- 左侧显示“终稿已完成”
-- 右侧进入可继续局部 AI 编辑状态
-
----
-
-## 10. 分步开发清单
-
-## Step 1：类型与假数据
-
-目标：
-
-- 先把 workflow 的类型、mock 数据、组件骨架搭好
-
-任务：
-
-- 新建 `workflow/types/workflow.ts`
-- 新建 `workflow/components/*`
-- 用本地 mock 事件驱动时间线和事件流
-
-验收：
-
-- 不接后端也能在页面中演示完整流程
-
-## Step 2：模式切换
-
-目标：
-
-- 在 `CanvasChatPanel` 中接入 `chat / writing_pipeline` 双模式
-
-任务：
-
-- 拆出 `CanvasWorkflowPanel`
-- 增加模式切换 UI
-- 保证旧 chat 不回归
-
-验收：
-
-- 现有功能不受影响
-- 新模式可进入表单页
-
-## Step 3：接入 workflow API
-
-目标：
-
-- 从 mock 切到真实 API
-
-任务：
-
-- 接 `create/start/get/events`
-- 实现基础错误态和重试态
-
-验收：
-
-- 前后端可联调跑一条主链路
-
-## Step 4：接入确认节点
-
-目标：
-
-- 支持提纲确认和指定章节重写
-
-任务：
-
-- 做确认卡片
-- 做动作回传
-
-验收：
-
-- 用户能在流程中介入
-
-## Step 5：打通右侧版本
-
-目标：
-
-- 让 workflow 产物稳定进入右侧编辑器
-
-任务：
-
-- 约定 artifact 映射
-- 接入版本切换或当前版本覆盖
-
-验收：
-
-- 终稿稳定显示在右侧
-
----
-
-## 11. 建议修改点位
-
-优先涉及文件：
-
-- [CanvasChatPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/chat/CanvasChatPanel.tsx)
-- [CanvasGraphContext.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/contexts/CanvasGraphContext.tsx)
-- [useCanvasThreadStream.ts](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/hooks/useCanvasThreadStream.ts)
-- [CanvasArtifactPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/artifact/CanvasArtifactPanel.tsx)
-
-建议新增，不建议重写原有：
-
-- `open-canvas/workflow/api/writing-workflow.ts`
-- `open-canvas/workflow/contexts/WritingWorkflowContext.tsx`
-- `open-canvas/workflow/hooks/useWritingWorkflow.ts`
-- `open-canvas/workflow/hooks/useWritingWorkflowEvents.ts`
-- `open-canvas/workflow/components/*`
-
----
-
-## 12. 联调约定
-
-前后端需要尽早统一：
-
-- workflow id 命名
-- stage 枚举
-- event type 枚举
-- artifact type 枚举
-- user action payload
-- 错误码与可恢复动作
-
-建议先由前端与后端共同确认一份 `workflow.ts` 契约文档，再开工。
-
----
-
-## 13. 最终建议
-
-前端最重要的不是“把 Agent 结果展示出来”，而是把“工作流过程可视化并允许人工介入”做清楚。
-
-第一版建议先保证三件事：
-
-1. 左侧能看见阶段进展
-2. 用户能确认提纲
-3. 右侧能稳定收到初稿和终稿
-
-只要这三件事稳定，后续再继续加章节重写、评分展示、素材卡片增强，风险会小很多。

frontend-web/docs/ai-writing-weak-model-multi-agent-prd.md

@@ -1,718 +0,0 @@
-# AI 写作弱模型多 Agent 编排需求文档
-
-## 1. 背景与目标
-
-当前 `open-canvas` 页面右侧的成品展示与编辑体验已经比较成熟，但左侧模型直接生成文章的质量还不稳定。对于内网部署的弱性能大模型，单轮直出通常会出现以下问题：
-
-- 结构松散，长文容易跑题
-- 素材不足，内容空泛
-- 事实依据弱，容易幻觉
-- 润色能力有限，语言风格不统一
-- 一次生成失败后缺少可控的纠偏机制
-
-因此本次需求的核心目标不是继续优化“单个模型一次写完”，而是在内网用代码编排一个“小型杂志社工作流”，让弱模型通过多角色分工协作，产出明显优于单模型直出的文章质量。
-
-建议的角色分工：
-
-- `Agent A 研究员`：负责搜集内网素材、归纳事实、提取观点
-- `Agent B 作家`：基于选题、素材和结构写初稿
-- `Agent C 严苛编辑`：负责挑错、质检、润色、打回重写
-- `Supervisor / Orchestrator`：负责流程调度、状态记录、重试与终止判断
-
----
-
-## 2. 本次建设边界
-
-### 2.1 前端边界
-
-前端继续使用现有 `open-canvas` 页面，不新开第二套编辑器页面。
-
-当前相关入口：
-
-- [CanvasResizableLayout.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/layout/CanvasResizableLayout.tsx)
-- [CanvasChatPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/chat/CanvasChatPanel.tsx)
-- [CanvasArtifactPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/artifact/CanvasArtifactPanel.tsx)
-- [CanvasStreamContext.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/contexts/CanvasStreamContext.tsx)
-- [runs.ts](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/api/runs.ts)
-
-前端本期只做以下增强：
-
-- 在左侧聊天区增加“写作工作流模式”
-- 让用户能看到多 Agent 阶段进度，而不是只看到最终回答
-- 支持结构化输入：主题、体裁、目标读者、篇幅、语气、参考资料、禁写项
-- 支持查看中间产物：提纲、素材卡片、初稿、编辑意见、终稿
-- 支持人工介入：确认提纲、确认初稿、接受编辑建议、手动重跑某一步
-
-### 2.2 后端边界
-
-后端必须单开新路线，不影响其他同事当前功能开发。
-
-建议原则：
-
-- 不直接改现有 DeerFlow 主流程
-- 不把多 Agent 逻辑硬塞进当前通用对话链路
-- 以独立服务或独立模块形式建设
-- 通过清晰 API 与当前前端页面对接
-
-推荐落地位置：
-
-- 基于仓库中的 `offline-backend-20260512` 单独开一条 `ai-writing-orchestrator` 路线
-- 或在后端新建独立目录，例如 `offline-backend-20260512/apps/ai_writing_orchestrator`
-
----
-
-## 3. 为什么多 Agent 对弱模型更合适
-
-弱模型最怕“一个 prompt 做完所有事”，因为这要求模型同时完成：
-
-- 选题理解
-- 信息检索
-- 信息筛选
-- 结构规划
-- 长文写作
-- 自我校验
-- 风格润色
-
-把这些任务拆开后，每个 Agent 只处理一个更短、更清晰、更容易被弱模型完成的子任务，通常会带来以下收益：
-
-- 降低单次上下文复杂度
-- 降低一次性长输出失败率
-- 把“写得不好”变成“某一步做得不好”，便于重试
-- 可以在关键节点插入规则校验与人工确认
-- 可以用程序补足模型短板，而不是完全依赖模型智力
-
-这套方案的本质不是“让模型变聪明”，而是“让系统更会组织模型工作”。
-
----
-
-## 4. 可借鉴的开源项目
-
-以下项目适合借鉴，但不建议整套照搬。建议以“借鉴状态机、角色协作、阶段拆分、重试与审稿机制”为主。
-
-### 4.1 第一优先级：LangGraph
-
-推荐原因：
-
-- 天然适合把写作流程建模成状态图
-- 支持多步骤、条件分支、重试、人工介入
-- 便于把“研究 -> 提纲 -> 初稿 -> 评审 -> 重写”固化成可控流程
-- 对“弱模型 + 强流程控制”很友好
-
-可借鉴点：
-
-- `StateGraph` 的状态驱动编排
-- 每一步单独定义输入、输出、失败处理
-- 可视化地表达“通过 / 打回 / 重试 / 终止”
-
-参考：
-
-- [langchain-ai/langgraph](https://github.com/langchain-ai/langgraph)
-- [langgraph supervisor pattern](https://github.com/langchain-ai/langgraph-supervisor-py)
-
-### 4.2 第二优先级：STORM
-
-推荐原因：
-
-- 它本身就是“研究 + 提纲 + 成文 + 打磨”的长文系统
-- 对“先研究后写作”的思路非常契合
-- 很适合借鉴其“问题驱动研究”和“分阶段生成”的思想
-
-根据其 GitHub README，STORM 将长文生成拆成两个大阶段：先研究并产出提纲，再基于提纲与资料写长文；其引擎进一步拆成知识整理、提纲生成、正文生成、文章润色四个模块。
-
-这和我们的目标高度一致，尤其适合借鉴：
-
-- 提纲先行
-- 素材引用先行
-- 分模块写作
-- 后置润色
-
-参考：
-
-- [stanford-oval/storm](https://github.com/stanford-oval/storm)
-
-### 4.3 第三优先级：Deep Research Agent
-
-推荐原因：
-
-- 明确支持本地模型与云模型混用
-- 已经包含研究、写作、质量校验、缓存、重试等能力
-- 很适合借鉴“研究阶段如何约束弱模型”
-
-根据其 README，这个项目采用四个专职 Agent，并且带有可信度评分、质量验证、重试逻辑、缓存和 checkpoint。
-
-特别适合借鉴：
-
-- 素材缓存
-- 分阶段质量评分
-- 节点失败重试
-- 研究结果结构化存储
-
-参考：
-
-- [tarun7r/deep-research-agent](https://github.com/tarun7r/deep-research-agent)
-
-### 4.4 可选借鉴：CrewAI
-
-推荐原因：
-
-- 角色扮演表达自然
-- 写“研究员 / 作家 / 编辑”这种协作关系很直观
-- Flow + Crew 的组织方式适合做 demo 和快速验证
-
-不建议作为首选底座的原因：
-
-- 更偏“Agent 角色编排体验”
-- 若要做企业内网稳定落地，状态管理和流程可控性通常不如 LangGraph 路线清晰
-
-适合借鉴：
-
-- 角色定义写法
-- Task 模板
-- 多角色协作 prompt 结构
-
-参考：
-
-- [crewAIInc/crewAI](https://github.com/crewAIInc/crewAI)
-
-### 4.5 不建议新项目优先采用：AutoGen
-
-原因：
-
-- 截至最近公开信息，`microsoft/autogen` 已进入 maintenance mode
-- 官方建议新项目优先采用 `Microsoft Agent Framework`
-
-如果要借鉴，只建议借鉴早期多 Agent 对话模式，不建议作为本项目主框架。
-
-参考：
-
-- [microsoft/autogen](https://github.com/microsoft/autogen)
-- [microsoft/agent-framework](https://github.com/microsoft/agent-framework)
-
-### 4.6 结论
-
-综合本项目需求，建议技术选型优先级如下：
-
-1. `LangGraph` 作为主编排框架
-2. `STORM` 借鉴研究-提纲-成文-润色的模块划分
-3. `Deep Research Agent` 借鉴缓存、评分、重试、可观测性
-4. `CrewAI` 借鉴角色 prompt 设计与任务模板
-
----
-
-## 5. 目标产品形态
-
-用户在当前 `open-canvas` 页面中，不再只是“向模型提问写文章”，而是启动一个可视化的写作流水线。
-
-理想交互流程：
-
-1. 用户输入主题、用途、风格、读者、篇幅要求
-2. 系统先进入“研究阶段”
-3. 系统给出资料卡片与候选提纲
-4. 用户确认提纲或调整
-5. 系统生成初稿
-6. 严苛编辑给出问题清单
-7. 系统自动重写问题段落
-8. 系统输出终稿到右侧编辑区
-9. 用户可继续局部改写、扩写、精简
-
-核心体验目标：
-
-- 左侧像“编辑部工作台”
-- 右侧像“成文编辑器”
-- 用户知道系统现在进行到哪一步
-- 用户可以在关键节点接管，而不是只能等待最终结果
-
----
-
-## 6. 多 Agent 流程设计
-
-## 6.1 建议的最小可用流程 MVP
-
-第一版不要一上来做很复杂，建议先做 4 步闭环：
-
-1. `Research`
-   - 输入：主题、用户要求、内网资料源
-   - 输出：素材卡片列表、可引用事实列表、风险点列表
-
-2. `Outline`
-   - 输入：用户要求 + 素材卡片
-   - 输出：结构化提纲
-
-3. `Draft`
-   - 输入：提纲 + 素材卡片
-   - 输出：初稿
-
-4. `ReviewAndRewrite`
-   - 输入：初稿 + 用户要求 + 素材卡片
-   - 输出：问题清单、改写稿、终稿
-
-MVP 终止条件：
-
-- 编辑评分达标则结束
-- 不达标最多重写 2 次
-- 超过次数则返回“需要人工介入”
-
-## 6.2 第二阶段增强流程
-
-在 MVP 跑通后，再增加：
-
-- `Planner`：根据文章类型动态规划流程
-- `SectionWriter`：按章节分别写作，避免长文崩坏
-- `FactChecker`：逐段核对素材来源
-- `StyleEditor`：统一语气、标题风格、句式节奏
-- `ComplianceReviewer`：内网场景下做敏感词、保密、术语规范检查
-
-## 6.3 建议的状态机
-
-建议将流程状态固定为：
-
-- `idle`
-- `collecting_materials`
-- `generating_outline`
-- `await_outline_confirmation`
-- `writing_draft`
-- `reviewing_draft`
-- `rewriting_draft`
-- `completed`
-- `failed`
-- `human_intervention_required`
-
-这样前端和后端都可以围绕统一状态通信。
-
----
-
-## 7. Agent 角色定义建议
-
-## 7.1 Agent A 研究员
-
-职责：
-
-- 搜集内网知识库、文档库、FAQ、历史稿件中的相关信息
-- 输出结构化素材，而不是长篇自然语言
-- 对每条素材标注来源、可信度、适用角度
-
-输出格式建议：
-
-- `facts[]`
-- `quotes[]`
-- `examples[]`
-- `risks[]`
-- `source_refs[]`
-
-约束建议：
-
-- 禁止直接生成整篇文章
-- 不做风格化表达
-- 每条结论必须可回溯到来源
-
-## 7.2 Agent B 作家
-
-职责：
-
-- 严格基于提纲和素材写稿
-- 按章节写，而不是一次写完整篇
-- 对每段附带素材引用 ID，便于后续审核
-
-约束建议：
-
-- 无素材不发挥
-- 每段只服务一个小节目标
-- 段落长度控制
-- 输出结构化草稿数据，而不仅是纯文本
-
-## 7.3 Agent C 严苛编辑
-
-职责：
-
-- 检查逻辑跳跃、素材不足、事实不稳、表述空泛、风格不统一
-- 输出明确的“问题清单”和“改写指令”
-- 必要时打回指定章节，而不是整篇推翻
-
-输出格式建议：
-
-- `issues[]`
-- `severity`
-- `rewrite_instructions[]`
-- `accept/reject`
-
-编辑原则建议：
-
-- 优先挑事实问题，再挑结构问题，最后才是文风问题
-- 问题描述必须可执行，不能只说“写得不够好”
-
-## 7.4 Supervisor
-
-职责：
-
-- 负责流程启动、状态流转、失败重试、记录日志
-- 判断是否需要回到上一步
-- 控制最大重试次数
-- 对外提供统一 API 与流式事件
-
----
-
-## 8. 前端需求
-
-## 8.1 保持当前页面结构不变
-
-继续沿用当前左右布局：
-
-- 左侧：聊天 + 流程进度 + 中间产物
-- 右侧：最终文章编辑与局部 AI 改写
-
-不建议再复制一套新页面，以免造成维护分叉。
-
-## 8.2 左侧新增 UI 模块
-
-建议在 `CanvasChatPanel` 基础上新增：
-
-- 写作任务表单
-- 工作流阶段时间线
-- Agent 执行日志面板
-- 中间产物抽屉
-- 人工确认卡片
-
-建议新增的前端概念：
-
-- `workflowMode`: `chat | writing_pipeline`
-- `workflowStage`
-- `workflowRunId`
-- `workflowEvents[]`
-- `workflowArtifacts[]`
-
-## 8.3 需要展示的中间产物
-
-至少支持展示：
-
-- 素材卡片
-- 提纲
-- 初稿
-- 编辑问题单
-- 重写结果
-- 最终定稿
-
-这些内容建议不仅显示在消息区，也保存到右侧可选版本中，便于回看。
-
-## 8.4 人工介入节点
-
-至少提供两个确认点：
-
-- 提纲确认
-- 初稿确认或编辑后重跑
-
-后续可扩展：
-
-- 指定重写某个章节
-- 锁定某段不允许再改
-- 替换某条素材后重新生成
-
----
-
-## 9. 后端需求
-
-## 9.1 架构原则
-
-后端新路线必须满足：
-
-- 与现有通用对话链路解耦
-- 与现有 Agent 运行时解耦
-- 独立维护 Prompt、状态机、数据结构
-- 可以单独部署、单独回滚、单独压测
-
-## 9.2 推荐模块划分
-
-建议后端拆分为以下模块：
-
-- `workflow_orchestrator`
-- `agent_registry`
-- `material_retriever`
-- `outline_generator`
-- `draft_writer`
-- `editor_reviewer`
-- `rewrite_engine`
-- `workflow_store`
-- `stream_event_adapter`
-
-## 9.3 API 建议
-
-建议最小 API：
-
-- `POST /api/ai-writing/workflows`
-  - 创建写作任务
-
-- `POST /api/ai-writing/workflows/{id}/start`
-  - 启动流程
-
-- `GET /api/ai-writing/workflows/{id}`
-  - 查询当前状态
-
-- `GET /api/ai-writing/workflows/{id}/events`
-  - 获取事件流或轮询事件
-
-- `POST /api/ai-writing/workflows/{id}/confirm-outline`
-  - 用户确认提纲
-
-- `POST /api/ai-writing/workflows/{id}/rewrite-section`
-  - 指定章节重写
-
-- `POST /api/ai-writing/workflows/{id}/approve-final`
-  - 确认终稿
-
-## 9.4 流式事件建议
-
-为了与当前 `CanvasStreamContext` 风格兼容，建议后端输出结构化事件流，例如：
-
-- `workflow_started`
-- `stage_changed`
-- `agent_started`
-- `agent_output_chunk`
-- `artifact_generated`
-- `human_confirmation_required`
-- `retry_scheduled`
-- `workflow_completed`
-- `workflow_failed`
-
-前端只要订阅事件，就能把左侧工作台做出来。
-
----
-
-## 10. 弱模型优化策略
-
-这是本项目成功的关键，不能只靠“多 Agent”这四个字。
-
-## 10.1 强约束输出格式
-
-每个 Agent 尽量输出 JSON 或结构化对象，不要自由发挥。
-
-原因：
-
-- 便于程序消费
-- 便于后续 Agent 接续
-- 便于失败重试
-- 便于质量评估
-
-## 10.2 长文拆成章节生成
-
-不要让弱模型一次生成整篇长文，建议：
-
-- 先出提纲
-- 再按章节逐段写
-- 最后统一润色
-
-## 10.3 把检索和写作分离
-
-研究员只负责找资料，作家只负责组织表达。不要让写作 Agent 同时去“边搜边编”。
-
-## 10.4 程序兜底而不是模型兜底
-
-程序需要承担：
-
-- 去重
-- 引用格式化
-- 章节拼接
-- 长度控制
-- 评分阈值判断
-- 重试路由
-
-## 10.5 小步快跑、失败可回退
-
-每步都要能独立失败、独立重试、独立回放。
-
-## 10.6 引入可量化评分
-
-编辑 Agent 输出不能只是一段文字，建议给出评分维度：
-
-- 相关性
-- 事实性
-- 结构完整度
-- 语言流畅度
-- 风格一致性
-
-系统据此决定是否进入下一步。
-
----
-
-## 11. 分阶段实施计划
-
-## Phase 1：需求冻结与技术验证
-
-目标：
-
-- 确认文章类型范围
-- 确认内网资料来源
-- 选定主框架
-- 跑通最小多 Agent demo
-
-交付物：
-
-- 技术选型说明
-- 角色与状态机设计
-- 1 个主题的端到端 demo
-
-验收标准：
-
-- 弱模型可完成“研究 -> 提纲 -> 初稿 -> 编辑 -> 重写”闭环
-
-## Phase 2：后端新路线搭建
-
-目标：
-
-- 建立独立 orchestrator
-- 建立 workflow state store
-- 建立事件流输出
-- 建立可配置 prompt 模板
-
-交付物：
-
-- 独立服务目录
-- 基础 API
-- 状态机运行骨架
-
-验收标准：
-
-- 不依赖现有主流程改造即可独立跑通
-
-## Phase 3：前端接入当前页面
-
-目标：
-
-- 在 `CanvasChatPanel` 接入工作流模式
-- 增加阶段展示与人工确认
-- 中间产物可视化
-
-交付物：
-
-- 左侧工作流时间线
-- 中间产物展示面板
-- 流程控制按钮
-
-验收标准：
-
-- 用户可以在当前页面完成一次全流程写作
-
-## Phase 4：质量优化
-
-目标：
-
-- 强化素材检索质量
-- 提高提纲质量
-- 引入章节级重写
-- 引入评分与回退机制
-
-交付物：
-
-- 质量评估规则
-- 重试策略
-- Prompt 调优包
-
-验收标准：
-
-- 弱模型效果明显优于单轮直出
-
-## Phase 5：生产化
-
-目标：
-
-- 加缓存
-- 加日志
-- 加监控
-- 加失败告警
-- 加审计记录
-
-交付物：
-
-- 可观测性方案
-- 运行日志与回放
-- 配置中心或 prompt 管理机制
-
-验收标准：
-
-- 可长期维护并可定位问题
-
----
-
-## 12. 团队协作与隔离方案
-
-为了不影响其他同事，建议采用以下协作原则：
-
-- 新后端目录独立开发
-- 新接口使用独立路由前缀
-- 前端只在 `open-canvas` 内增量开发
-- 不修改现有公共线程协议，必要时增加新事件类型
-- Prompt、Agent 配置、评分规则独立存放
-
-推荐分工：
-
-- 前端 1 人：负责左侧工作流 UI 与右侧版本接入
-- 后端 1-2 人：负责 orchestrator、Agent 执行、事件流
-- 算法/Prompt 1 人：负责角色 prompt、评分规则、失败样本调优
-
----
-
-## 13. 风险与规避
-
-### 风险 1：Agent 太多，成本和耗时暴涨
-
-规避：
-
-- MVP 只保留 3 个业务 Agent + 1 个 Supervisor
-- 长文按章节写，失败只重写局部
-
-### 风险 2：弱模型在自由对话场景中失控
-
-规避：
-
-- 全流程结构化
-- 每步只做一件事
-- 强约束输入输出格式
-
-### 风险 3：内网检索质量不足，导致垃圾进垃圾出
-
-规避：
-
-- 先把资料源治理好
-- 对素材做来源、可信度、去重处理
-
-### 风险 4：前后端协议频繁变化影响联调
-
-规避：
-
-- 先定义事件模型和 artifact 模型
-- 先 mock 数据，再并行开发
-
-### 风险 5：影响现有功能稳定性
-
-规避：
-
-- 新路线、新接口、新状态机
-- 不侵入现有主链路
-
----
-
-## 14. 推荐结论
-
-本项目推荐的总体策略：
-
-1. 前端继续基于当前 `open-canvas` 页面开发，不复制新页面
-2. 后端单独开 `ai-writing-orchestrator` 新路线，避免影响现有同事
-3. 主框架优先采用 `LangGraph`
-4. 流程设计借鉴 `STORM`
-5. 质量控制借鉴 `Deep Research Agent`
-6. 角色设计与任务模板可参考 `CrewAI`
-7. 第一版只做 4 步 MVP：研究、提纲、初稿、编辑重写
-
-一句话总结：
-
-不是继续“调一个更强的 prompt”，而是把弱模型放进一个可控的编辑部流水线，让系统帮它把复杂写作拆开完成。
-
----
-
-## 15. 参考链接
-
-- [LangGraph](https://github.com/langchain-ai/langgraph)
-- [LangGraph Supervisor](https://github.com/langchain-ai/langgraph-supervisor-py)
-- [STORM](https://github.com/stanford-oval/storm)
-- [Deep Research Agent](https://github.com/tarun7r/deep-research-agent)
-- [CrewAI](https://github.com/crewAIInc/crewAI)
-- [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)
-- [AutoGen](https://github.com/microsoft/autogen)

frontend-web/docs/ai-writing-优化.md

@@ -1,501 +0,0 @@
-# AI 写作 — 迁移到 LangGraph Server 的分步实现方案
-
-> **文档目的**：彻底解决 AI 写作在多 worker 部署下"SSE 时断时续 / resume 偶发 404"的根因，参照主聊天（`/workspace/chats/new`）的实现，把 AI 写作的 graph 注册成 LangGraph Server 上的一个 assistant，让 Server 接管线程、checkpoint、SSE、interrupt/resume 的全部协议。
->
-> **配套文档**：[ai-writing-说明.md](./ai-writing-说明.md) 里描述了为什么会出问题、当前已落地的兜底方案，以及方案 B/C/F 三条"绕过"路径。本文档是其中"长期方案"的具体实现路线 —— 不是绕过多 worker，而是从架构层面让它**天然不受 worker 数影响**。
->
-> **更新日期**：2026-05-20
-
----
-
-## 一、为什么走这条路
-
-主聊天和 AI 写作功能形态几乎一致（多步流式、可中断/恢复、有持久化），但**主聊天完全不受多 worker 影响**。差别在于：
-
-| 维度 | 主聊天（现状） | AI 写作（现状） | AI 写作（迁移后） |
-|---|---|---|---|
-| 前端流接入 | `useStream` (SDK) | `fetch` + 自写 `EventSource` | `useStream` (SDK) |
-| 后端运行时 | **LangGraph Server**（独立进程，端口 2024 / 经 nginx 走 `/api/langgraph`） | 嵌在 FastAPI Gateway 路由里直接跑 | **LangGraph Server**（同主聊天） |
-| 线程状态 | Server 自带持久化 checkpointer | 自管 sqlite + 一堆模块级 dict | Server 自带持久化 checkpointer |
-| SSE 通道 | Server ↔ SDK 协议层 | 自写 `asyncio.Queue` per session_id | Server ↔ SDK 协议层 |
-| 多 worker | 任何 worker 都能查 Server | per-worker 内存 dict 隔离 | 任何 worker 都能查 Server |
-| Interrupt/Resume | Server 协议（`Command(resume=...)`）| 自写 `_session_pending_pause` + `/resume` 路由 | Server 协议 |
-
-**核心收益**：迁完后 `_event_queues`、`_session_pending_pause`、`_session_repos`、`_session_user_ids`、`_session_interventions`、`_session_article_types`、`_session_error_flags`、`_session_pending_pause`、`_inflight_graph_tasks`、`_recover_session()`、自管 sqlite checkpointer 这一整套"per-process 内存状态"全部可以删掉 —— 不是"绕过"问题，是**让问题消失**。
-
-**代价**：节点要改造（流式 chunk 改走 LangGraph 原生 `StreamWriter`/state update）、前端干预卡的交互要重写、业务表写入路径要从"路由里写"挪到"节点里写"。约 **6 人日**核心改造 + 50% buffer，建议按 **9 人日**排期。
-
----
-
-## 二、现状盘点：要删 / 要留 / 要改
-
-### 2.1 要删的（迁完即可移除）
-
-| 位置 | 内容 | 备注 |
-|---|---|---|
-| `app/gateway/routers/ai_writing.py` | `POST /start`、`GET /{id}/stream`、`POST /{id}/resume`、`GET /{id}/state` | 由 LangGraph Server 的 `runs.stream / threads.create / runs.wait` 替代 |
-| 同上 | `_event_queues`、`_session_pending_pause`、`_session_model_names`、`_session_repos`、`_session_user_ids`、`_session_interventions`、`_session_error_flags`、`_session_article_types` 这 8 个模块级 dict | 状态全部交给 LangGraph Server |
-| 同上 | `_recover_session()`、`_inflight_graph_tasks`、`_spawn_graph_task()`、`wait_for_inflight_graph_tasks()` | 跨 worker 恢复 / drain 都由 Server 内建机制处理 |
-| 同上 | `_make_config()` 里注入 `sse_queue` / `sse_session_id` 的逻辑 | 流式输出改走 LangGraph 原生通道 |
-| `packages/harness/deerflow/agents/ai_writing/graph.py` | `_get_async_checkpointer()`、`get_ai_writing_checkpointer()`、`shutdown_ai_writing_graph()`、`AI_WRITING_GRAPH` 单例、`_async_checkpointer_singleton` | checkpoint 由 langgraph.json 的全局 checkpointer 接管 |
-| `app/gateway/ai_writing_cleanup.py` | "联动清理 sqlite checkpointer thread" 那一段 | 改成调 `langgraph_sdk` 的 `threads.delete()` |
-| `offline-backend-20260512/config.yaml` | `checkpointer:` 段里 AI 写作专用的 sqlite 路径（如果跟主 checkpointer 不同） | 共用主配置 |
-
-### 2.2 要保留的
-
-| 位置 | 内容 | 理由 |
-|---|---|---|
-| `packages/harness/deerflow/persistence/ai_writing_sessions/` | MySQL 业务表（标题、最终 draft、completed_interventions、transcript、article_type、status…） | 列表页 / 历史回显 / 全文搜索都依赖业务表，**不能让 LangGraph checkpoint 取代它** —— checkpoint 是流程状态，业务表是产品形态 |
-| `GET/PATCH/DELETE /api/ai-writing/sessions[/{id}]` | 列表 / 重命名 / 删除 | 只查业务表，不碰 graph |
-| `PUT /api/ai-writing/sessions/{id}/transcript` | 时间线持久化 | 维持锦上添花的回显方案 |
-| `GET/POST/PATCH/DELETE /api/ai-writing/article-types[/{id}]` | 文章类型 CRUD | 纯业务路由，跟 graph 无关 |
-| `POST /api/ai-writing/admin/cleanup` | admin 清理入口 | 路由保留，内部实现改 |
-| 4 个 interrupt 暂停点 + 5 个节点 + 全部 state 字段 | 业务逻辑零改动 | `pause_material_confirm` / `pause_outline_confirm` / `pause_section_help` / `pause_draft_confirm` / `pause_review_confirm` 用的就是 LangGraph 原生 `interrupt()`，直接吃迁移红利 |
-
-### 2.3 要改的
-
-| 位置 | 改造点 |
-|---|---|
-| `graph.py` | 删自管 checkpointer，导出 `make_ai_writing_graph(config) → CompiledStateGraph`，由 Server 注入 checkpointer |
-| `langgraph.json` | `graphs` 里增加 `"ai_writing": "deerflow.agents.ai_writing.graph:make_ai_writing_graph"` |
-| 各 node（`researcher.py` / `writer_outline.py` / `writer_draft.py` / `editor.py`） | 流式输出从 `sse_queue.put_nowait(...)` 改成 LangGraph 原生 `get_stream_writer()` 推 custom 事件 |
-| 各 node | DB 写入（草稿、审核结果、status）从「路由里调 repo」改成「节点里通过 `RunnableConfig` 拿 `thread_id` 调 repo」 |
-| 各 node | "创建 session 行"从 `/start` 路由里挪到 `intent_parser_node`（或前端 `onCreated` 回调里调一个轻量级 upsert API） |
-| `langgraph_auth.py` | 给 `ai_writing` assistant 加授权规则（保证只能访问自己的 thread） |
-| 前端 `frontend-web/src/open-canvas/` | 完全弃用现有 `api/ai-writing.ts` 的 `fetch + EventSource`，新写 `useAIWritingStream` hook（基于 `@langchain/langgraph-sdk/react` 的 `useStream`） |
-| 前端 4 个干预卡 | 提交回调从 `POST /resume` 改为 `thread.submit(new Command({ resume: payload }))` |
-| 前端"启动写作"按钮 | 从 `POST /start` + 拿 session_id + 建 EventSource 改成 `thread.submit({...args})` 触发 `onCreated` 回调 |
-| `tests/test_ai_writing_session_recovery.py` | 整体删除 —— 跨 worker 恢复由 LangGraph Server 接管，不再是 AI 写作自己的事 |
-| 新增 `tests/test_ai_writing_assistant.py` | 通过 LangGraph SDK in-process 跑一遍 graph，覆盖 interrupt / resume / custom stream / state 持久化 |
-
----
-
-## 三、分步实施
-
-### 阶段 0：可行性预演（0.5 d）
-
-**目标**：在不动现有代码的前提下，验证"把 ai_writing graph 注册到 LangGraph Server 并通过 SDK 跑通"这条路完全可行。
-
-1. 临时在 `langgraph.json` 的 `graphs` 里加一条 `"ai_writing_probe": "deerflow.agents.ai_writing.graph:build_ai_writing_graph"`（直接复用现有 `build_ai_writing_graph`，不传 checkpointer 让 Server 注入）。
-2. 起 `make dev`，确认 LangGraph Server 把 `ai_writing_probe` 列入 assistant 列表。
-3. 用 Python SDK 客户端（`langgraph_sdk.get_client()`）：
-   ```python
-   from langgraph_sdk import get_client
-   client = get_client(url="http://localhost:8001/api/langgraph")
-   thread = await client.threads.create()
-   async for chunk in client.runs.stream(
-       thread["thread_id"], "ai_writing_probe",
-       input={"user_intent": "测试", "article_type": "analysis", ...},
-       stream_mode=["values", "messages-tuple", "custom"],
-   ): print(chunk)
-   # 跑到 pause_material_confirm 应该收到 interrupt 事件
-   await client.runs.stream(thread["thread_id"], "ai_writing_probe",
-       command={"resume": {"action": "confirm", "approvedMaterialIds": [...]}})
-   ```
-4. 验证：interrupt 能正确暂停、`Command(resume=...)` 能续跑、state 能持久化到 Server checkpoint。
-5. 跑通后**回滚 langgraph.json** —— 这一步只是"摸路"。
-
-**通过条件**：4 个 pause 点全部能用 SDK 跑通 interrupt + resume。如果某个 pause 点的 payload 结构跟 SDK 协议不兼容（例如用了非 JSON 可序列化的对象），阶段 0 就要解决，否则会在阶段 2 翻车。
-
----
-
-### 阶段 1：graph 注册为 assistant（0.5 d）
-
-**改动文件**：`packages/harness/deerflow/agents/ai_writing/graph.py`、`offline-backend-20260512/backend/langgraph.json`
-
-1. `graph.py` 顶部新增：
-   ```python
-   from langchain_core.runnables import RunnableConfig
-
-   def make_ai_writing_graph(config: RunnableConfig | None = None):
-       """LangGraph Server 入口：不接收 checkpointer，由 Server 注入。"""
-       g = StateGraph(AIWritingState)
-       # ... 跟现在 build_ai_writing_graph 完全一样的节点 / 边定义 ...
-       return g.compile()   # 注意：不传 checkpointer
-   ```
-2. 旧的 `build_ai_writing_graph(checkpointer=None)`、`get_ai_writing_graph()`、`_get_async_checkpointer()`、`get_ai_writing_checkpointer()`、`shutdown_ai_writing_graph()` 全部**先标 `@deprecated` 暂留** —— 阶段 7 再删，避免阶段 2/3 出错时无法快速回退。
-3. `langgraph.json`：
-   ```json
-   {
-     "graphs": {
-       "lead_agent": "deerflow.agents:make_lead_agent",
-       "canvas_agent": "deerflow.agents.canvas_agent:make_canvas_agent",
-       "ai_writing": "deerflow.agents.ai_writing.graph:make_ai_writing_graph"
-     }
-   }
-   ```
-4. `checkpointer.path` 已经指向 `make_checkpointer`（看 `langgraph.json:15-17`），AI 写作直接共享主 checkpointer 即可，**不要**重新搞一套。
-
-**通过条件**：启动 LangGraph Server 后 `GET /api/langgraph/assistants` 能列出 `ai_writing`，state schema 字段齐全。
-
----
-
-### 阶段 2：节点改造 —— 流式输出走原生通道（1.5 d）
-
-**核心问题**：现在的 `writer_draft_node` / `writer_outline_node` / `researcher_node` 通过 `config["configurable"]["sse_queue"]` 把 LLM token chunk 推给前端。LangGraph Server 不会再注入 `sse_queue`，必须改用原生流通道。
-
-**选型**：用 `langgraph.config.get_stream_writer()` 推 `custom` 事件（保留现有"非聊天消息、自定义协议"的形态）。
-
-> 不选 `messages-tuple` 模式的原因：草稿生成不是聊天消息流，而是大段 markdown；硬塞成 `AIMessage` 会让前端渲染逻辑变得很别扭。custom 通道改动最小、契合度最高。
-
-**改造模板**（每个节点都按这个模板改）：
-```python
-# 旧：
-from .nodes._utils import push_sse_event
-async def writer_draft_node(state, config):
-    sse_queue = config["configurable"].get("sse_queue")
-    sse_queue.put_nowait({"event": "progress", "data": {...}})
-    async for chunk in llm.astream(...):
-        sse_queue.put_nowait({"event": "draft_chunk", "data": {"text": chunk}})
-
-# 新：
-from langgraph.config import get_stream_writer
-async def writer_draft_node(state, config):
-    writer = get_stream_writer()   # 注意：必须在 async 函数体内调，不能模块级缓存
-    writer({"type": "progress", "agent": "writer", "message": "开始写作"})
-    async for chunk in llm.astream(...):
-        writer({"type": "draft_chunk", "text": chunk})
-```
-
-**业务表写入改造**：现在 `writer_draft_node` 收尾时通过 `config["configurable"]["sse_session_id"]` + `_session_repos[sid]` 调 `repo.save_draft()`。新方案：
-```python
-async def writer_draft_node(state, config):
-    thread_id = config["configurable"]["thread_id"]   # LangGraph Server 注入
-    # 从 thread metadata / state 里拿到 user_id（在阶段 4 写入）
-    user_id = state.get("_user_id") or config["configurable"].get("user_id")
-    repo = get_ai_writing_session_store()  # 进程内全局，无 per-session 字典
-    try:
-        await repo.save_draft(thread_id, user_id, state["current_draft"])
-    except Exception:
-        logger.exception("save_draft failed (non-fatal)")
-```
-
-**注意事项**：
-- `get_stream_writer()` 在子图 / 工具函数里会拿到当前 graph 的 writer，**不要**在模块 import 时缓存。
-- 节点要兼容"测试场景下没有 LangGraph runtime"：包一层 `try: writer = get_stream_writer() except ...`，单测里 writer 是 no-op。
-- progress_events 字段保留写入 state（现在节点都已经 return `{"progress_events": [...]}`），这样 history / 回放仍然能在 state 里看到完整轨迹；custom stream 只是为了**实时推送**。
-
-**通过条件**：手动跑一次 `make dev`，用 SDK 客户端从前一阶段验证脚本流式拿到 `draft_chunk` 事件。
-
----
-
-### 阶段 3：前端接入 LangGraph SDK（1 d）
-
-**核心改动**：`frontend-web/src/open-canvas/api/ai-writing.ts` 整文件作废，改写 `frontend-web/src/open-canvas/hooks/useAIWritingStream.ts`。
-
-**新 hook 骨架**（参考 `frontend-web/src/core/threads/hooks.ts:207` 现有主聊天写法）：
-```ts
-import { useStream } from "@langchain/langgraph-sdk/react";
-import { Command } from "@langchain/langgraph-sdk";
-import { getAPIClient } from "@/core/api/api-client";
-
-interface AIWritingValues {
-  user_intent: string;
-  article_type: string;
-  status: string;
-  material_package?: MaterialPackage;
-  current_outline?: Outline;
-  current_draft?: DraftArticle;
-  review_result?: ReviewResult;
-  progress_events: any[];
-}
-
-export function useAIWritingStream(sessionId: string | "new") {
-  const stream = useStream<AIWritingValues, { CustomEventType: AIWritingCustomEvent }>({
-    client: getAPIClient(),
-    assistantId: "ai_writing",
-    threadId: sessionId === "new" ? undefined : sessionId,
-    reconnectOnMount: true,
-    onCreated(meta) {
-      // 后端会用同一个 thread_id 做 ai_writing_sessions.id；通知 UI 写入 URL
-      navigateTo(`/workspace/ai-writing/${meta.thread_id}`);
-    },
-    onCustomEvent(event) {
-      // 节点 push 来的 draft_chunk / progress / notice
-      pushUIEvent(event);
-    },
-  });
-  return stream;
-}
-```
-
-**4 个干预卡的提交逻辑**（旧 → 新）：
-```ts
-// 旧（自写 fetch）：
-await fetch(`/api/ai-writing/${sessionId}/resume`, {
-  method: "POST",
-  body: JSON.stringify({ action: "confirm", approvedMaterialIds: [...] }),
-});
-
-// 新（SDK 原生 Command）：
-stream.submit(undefined, {
-  command: { resume: { action: "confirm", approvedMaterialIds: [...] } },
-});
-```
-
-**启动写作**：
-```ts
-// 旧：POST /start → 返回 session_id → 建 EventSource
-// 新：
-stream.submit({
-  user_intent, article_type, target_audience, word_count_target, keyword_count, writing_mode,
-}, {
-  config: { configurable: { model_name } },
-  metadata: { feature: "ai_writing", article_type },   // 走业务表筛选
-});
-```
-
-**列表页 / 历史回显**：仍然走 `GET /api/ai-writing/sessions` 业务 API，**无改动**。点进某条历史记录时：
-- 拿到 `sessionId` (== LangGraph `thread_id`)
-- `useAIWritingStream(sessionId)` 自动调 `client.threads.getState()` 拉最新 state，渲染最后一次草稿 / 干预点 / interrupt 等待
-- 已结束的会话 (`status == "done"`) 直接读业务表的 `draft_markdown` 字段，**不挂 SDK stream**（省 Server 资源）
-
-**通过条件**：手动跑完一个完整流程（启动 → 4 次干预 → 拿到草稿），过程中刷新页面 / 切 worker，进度都不丢。
-
----
-
-### 阶段 4：业务表写入解耦（0.5 d）
-
-**问题**：现在 `/start` 路由先 INSERT 一行 `ai_writing_sessions(id=session_id, ...)`，再启动 graph。迁移后前端用 `stream.submit(...)` 直接触发 LangGraph 建 thread + 跑 graph，业务表行没人建 → 列表页查不到。
-
-**两个方案二选一**：
-
-**方案 4A（推荐）**：节点里建业务表行
-- `intent_parser_node` 开头：`await repo.upsert_session(thread_id, user_id, user_intent, article_type, status="researching")`
-- 优点：单一数据源（节点），不依赖前端做"双写"。
-- 缺点：用户从前端点"启动" → 看到列表里出现这条 → 之间有 200~500ms 延迟（intent_parser 跑完才入库），需要前端 onCreated 后乐观插入一条临时行。
-
-**方案 4B**：前端 onCreated 时调一个轻量 upsert API
-- 新增 `POST /api/ai-writing/sessions/{thread_id}/init`：只插业务表行，不碰 graph。
-- 前端 `onCreated(meta)` 回调里立刻 fire-and-forget 调它。
-- 优点：列表瞬间出现新行。
-- 缺点：前端要多调一次 API，且失败要兜底；多了一条"双方都能建行"的路径。
-
-**推荐 4A** —— 单一数据源比 UI 响应更重要，200ms 延迟用 loading skeleton 即可。
-
-**用户身份传递**：节点要拿到 `user_id` 写入业务表。两条路：
-- LangGraph Server 已有 `langgraph_auth.py` 注入 auth context，在节点里 `config["configurable"].get("langgraph_auth_user")` 取（具体字段名以现有实现为准）。
-- 或者前端 `submit()` 时 metadata 里带上 `user_id`，节点从 `config["configurable"]["metadata"]` 拿。
-
-**通过条件**：从启动到列表显示新行，延迟 < 1s；多用户场景下不会出现"A 用户的 thread 落到 B 的业务表行"。
-
----
-
-### 阶段 5：transcript 持久化（0.2 d）
-
-**当前**：前端 `PUT /api/ai-writing/sessions/{id}/transcript` 全量覆盖 `ai_writing_sessions.transcript` 列。
-
-**改造选择**：
-- **维持现状**（推荐）：transcript 是前端组装的时间线 blob，让前端继续 fire-and-forget PUT 即可，跟迁移正交。
-- 或者完全弃用 transcript 列，直接从 `client.threads.getHistory()` + `getState()` 还原 —— 工作量大且需要重写回显逻辑，**不推荐第一版做**。
-
-**通过条件**：原 PUT 接口照常工作；新建会话也能落库。
-
----
-
-### 阶段 6：admin 清理改造（0.3 d）
-
-**改动文件**：`app/gateway/ai_writing_cleanup.py`
-
-```python
-# 旧：
-saver = get_ai_writing_checkpointer()
-await saver.adelete_thread(sid)   # 自管 sqlite
-
-# 新：
-from langgraph_sdk import get_client
-lg_client = get_client(url=internal_langgraph_url())
-await lg_client.threads.delete(sid)
-```
-
-**活跃保护**：旧逻辑是看 `sid in _event_queues`。新逻辑：
-```python
-state = await lg_client.threads.get_state(sid)
-is_active = (
-    state.get("next")                   # graph 还有未执行的节点
-    or state.get("tasks")               # 当前有 pending task
-    or state.get("metadata", {}).get("interrupted")  # 卡在 interrupt 上
-)
-if is_active:
-    skipped_active += 1
-    continue
-```
-
-**通过条件**：admin cleanup 接口照常返回 `deleted_db / deleted_checkpoints / skipped_active`，且能正确跳过仍在 interrupt 等待用户的会话。
-
----
-
-### 阶段 7：删冗余代码（0.3 d）
-
-按 §2.1 列表逐项删除。建议**单独开一个 PR**，跟阶段 1~6 解耦：
-- 前 6 个 PR 全部上线、灰度验证至少 1 周
-- 确认旧代码路径再无流量后，再走清理 PR
-- 这样万一灰度阶段需要回滚，旧路径还在
-
-**通过条件**：`make test` 全绿，`grep -r "_event_queues\|_session_pending_pause\|_recover_session" app/ packages/` 零命中。
-
----
-
-### 阶段 8：测试 + 灰度（1 d）
-
-**新增测试**：
-- `tests/test_ai_writing_assistant.py` —— 用 `langgraph_sdk` 客户端打 LangGraph Server，覆盖：
-  - 完整流程：start → 4 个 interrupt → resume → done
-  - state 持久化：跑到 pause_outline 后重建客户端，能 `getState` 看到 outline
-  - custom stream：能收到 `draft_chunk` 等事件
-  - 错误兜底：节点抛错时 status 落 error、业务表 status 同步
-- 保留 `tests/test_portable_long_text.py` / `tests/test_ai_writing_transcript_endpoint.py` / `tests/test_ai_writing_session_repo.py` —— 这几个跟业务表强相关，不受迁移影响。
-
-**删除测试**：
-- `tests/test_ai_writing_session_recovery.py` —— 跨 worker 恢复改由 LangGraph Server 提供，不再是 AI 写作自己的能力。
-- `tests/test_ai_writing_cleanup.py` 里关于"drain + checkpointer 降级 + SSE 序列化"的几个用例 —— 这些机制已删，对应用例失效。
-
-**灰度策略**：
-- **前端开关**：`VITE_AI_WRITING_BACKEND` = `legacy | langgraph`，默认 `legacy`
-  - `legacy` → 走老的 `fetch + EventSource + /resume`
-  - `langgraph` → 走新 `useAIWritingStream`
-- **后端**：旧路由（`/start /stream /resume /state`）保留两个发版周期，逐步下线
-- **数据兼容**：业务表 schema 完全不变，两条路径都用同一张表
-- **回滚成本**：改回 `VITE_AI_WRITING_BACKEND=legacy` 重新部署即可，无 DB migration
-
-**通过条件**：
-- 灰度环境跑 100+ 写作流程，对比新旧两条路径的成功率、SSE 中断率、resume 成功率
-- 新路径在 worker=4 部署下 SSE 中断率 = 0（旧路径基线约 5~15%）
-
----
-
-## 四、关键设计决策与权衡
-
-### 4.1 为什么不让 LangGraph checkpoint 替代业务表？
-
-LangGraph checkpoint 存的是"图执行状态"，业务表存的是"产品形态"。两者职责不同：
-- **会话列表筛选/排序**：业务表 `WHERE user_id = ? AND status = ? ORDER BY updated_at` —— LangGraph checkpoint 没法这样查（它是 `(thread_id, checkpoint_ns)` 主键）
-- **全文搜索 draft**：业务表 `LIKE '%关键词%'` —— checkpoint 是序列化 blob
-- **transcript 自定义 UI 协议**：前端组装的时间线 JSON，跟 graph state 不一一对应
-
-**结论**：两者**并存**，`thread_id` 作为外键。这是主聊天的做法（`threads_meta` + LangGraph checkpoint），AI 写作迁完后也是同样的形态。
-
-### 4.2 为什么 graph 节点里直接调 repo，不发到外面消费？
-
-考虑过"节点只 emit custom event，路由层订阅事件后写业务表" —— 但这又把状态分散回路由层了。
-
-直接在节点里调 `await repo.save_draft(...)`：
-- 节点拿得到 `thread_id`（== session_id == business id），主键一致
-- `repo` 是单例（DB 连接池），不依赖 per-session 字典
-- 写入失败包 try/except 即可（草稿落 state 比落 DB 更关键，DB 失败不阻断流程）
-
-### 4.3 为什么用 custom stream 而不是 messages-tuple？
-
-writer_draft 输出是大段 markdown，强行包成 `AIMessage` 后：
-- 前端要把它从消息列表里拎出来当草稿渲染（混杂）
-- 大纲 / 审核结果是结构化 JSON，更不像聊天消息
-- progress_events / notice / draft_chunk / outline_chunk 几种事件类型，全塞 message 通道得发明 metadata convention
-
-custom stream 是为这种"非聊天但需要流式 push"场景设计的，匹配度更高。
-
-### 4.4 在 Server 进程里跑 graph，资源够用吗？
-
-LangGraph Server 是独立 Python 进程，跟 Gateway 共享同一台机器但不共享内存。新增一个 assistant 的常驻开销 ~10 MB（graph 编译后的 schema 缓存），每个并发会话峰值 ~50 MB（LLM client + state）。
-
-实测建议：在阶段 0 之后跑一次 10 个并发的压测，观察 Server RSS 增量。若一台机器 4 GB 内存，理论支撑 60~80 并发 AI 写作，足够 50 人规模团队使用。
-
----
-
-## 五、风险清单
-
-| # | 风险 | 缓解 |
-|---|---|---|
-| R1 | LangGraph Server 升级版本时 `interrupt()` / `Command(resume=...)` 协议有 breaking change | 在 `pyproject.toml` 里 pin `langgraph` minor 版本；升级前先在阶段 0 那个 probe 跑一遍冒烟 |
-| R2 | 前端 `useStream` 的 `reconnectOnMount` 行为跟自写 EventSource 不完全一致，刷新页面后某些情况下不会自动续接 SSE | 阶段 3 手动测刷新场景；如不达预期，配合 `client.threads.getState()` 拉一次 state 兜底 |
-| R3 | 节点里 `get_stream_writer()` 在单测里没有 LangGraph runtime → 抛错 | 节点 wrap `try: writer = get_stream_writer() except: writer = lambda x: None` |
-| R4 | 多用户场景下 `langgraph_auth.py` 没对 ai_writing assistant 做隔离，可能跨用户拿到别人的 thread state | 阶段 4 一并配置 auth；新增专项测试 |
-| R5 | `client.threads.delete()` 是异步删，admin 清理脚本调完后立即查 state 还能短暂查到 → `skipped_active` 误判 | 删之前先 lock thread 或调用 `client.runs.cancel()` 强制收敛 |
-| R6 | LangGraph Server 自带 checkpoint 仍然是 sqlite（`langgraph.json` 里配的），在容器重启时跟 AI 写作原有的 `.deer-flow/data/checkpoints.db` 是同一个文件 → schema 共用 | 阶段 1 之前先确认主 checkpointer 配置路径，避免双开 sqlite 文件锁竞争 |
-| R7 | 现有用户在迁移窗口期发起的会话，灰度切到新路径后无法续跑（state 在旧 sqlite，新路径查不到） | 迁移前 1 小时禁止新会话；或写一个一次性脚本把旧 checkpointer 的 thread 复制到主 checkpointer |
-
----
-
-## 六、工时与里程碑
-
-| 阶段 | 工时 | 可独立交付 |
-|---|---|---|
-| 阶段 0：可行性预演 | 0.5 d | ✅ |
-| 阶段 1：graph 注册 | 0.5 d | ❌（后端只生效，前端没接） |
-| 阶段 2：节点改造 | 1.5 d | ❌ |
-| 阶段 3：前端接入 | 1 d | ✅（带开关上灰度） |
-| 阶段 4：业务表写入解耦 | 0.5 d | ❌（跟阶段 3 合并发） |
-| 阶段 5：transcript | 0.2 d | ✅ |
-| 阶段 6：admin 清理改造 | 0.3 d | ✅ |
-| 阶段 7：删冗余 | 0.3 d | ✅（独立 PR，灰度后再发） |
-| 阶段 8：测试 + 灰度 | 1 d | ✅ |
-| **核心工时** | **5.8 d** | |
-| **+ 50% buffer** | **8.7 d ≈ 9 d** | |
-
-**建议排期**：
-- 第 1 周：阶段 0 + 1 + 2（后端完整、本地能跑通）
-- 第 2 周：阶段 3 + 4 + 5 + 6（前端 + 业务集成）
-- 第 3 周：阶段 8（测试 + 灰度）
-- 灰度 1~2 周后：阶段 7（删冗余）
-
----
-
-## 七、回滚预案
-
-每个阶段都设计为可独立回滚：
-
-| 场景 | 回滚动作 |
-|---|---|
-| 阶段 3 上线后发现 SSE 不稳 | 前端开关 `VITE_AI_WRITING_BACKEND=legacy`，重新部署，0 dataloss |
-| 阶段 7 删冗余代码后发现新路径有问题 | 从 git revert 删除 commit，恢复旧路由代码；业务表/checkpoint 不受影响 |
-| 阶段 1 注册 assistant 后 LangGraph Server 起不来 | 从 `langgraph.json` 移除 `ai_writing` 那一行，重启 Server，回到迁移前状态 |
-
-**数据兼容承诺**：
-- 业务表 schema 完全不变
-- `thread_id` (== `ai_writing_sessions.id`) 含义保持一致
-- transcript 列含义不变
-
-**最坏回滚**：把 `VITE_AI_WRITING_BACKEND` 改回 `legacy`、`langgraph.json` 删 `ai_writing` 那行，回到迁移前的"方案 C/F/B 路径"。已经走完的会话留在新 checkpoint 里成"孤儿"，但业务表里的草稿和审核结果**完整无损**。
-
----
-
-## 八、迁移成功后能享受的"免费红利"
-
-1. **完整 history API**：`client.threads.getHistory(thread_id)` 拿到每一步 checkpoint，做"回到某一步重试"非常便宜
-2. **time travel**：用户能从任意 checkpoint 分叉重写
-3. **跟主聊天共享基础设施**：升级 LangGraph 版本时一并升级，不用维护两套 SSE / checkpoint 协议
-4. **天然支持水平扩容**：哪天上 K8s 多副本部署，AI 写作跟主聊天一样开箱即用
-5. **天然支持 IM 渠道接入**：`app/channels/` 那套 Feishu / Slack 实现是 `langgraph-sdk` 的，迁完后 AI 写作也能在 IM 里用，零额外代码
-
----
-
-## 九、相关文件索引（迁移前后参照）
-
-### 现状（迁前）
-- `app/gateway/routers/ai_writing.py:148-176` —— 8 个模块级 dict + drain task
-- `packages/harness/deerflow/agents/ai_writing/graph.py:370-538` —— 自管 checkpointer
-- `frontend-web/src/open-canvas/api/ai-writing.ts` —— 自写 fetch + EventSource
-
-### 参照（主聊天迁后形态）
-- `frontend-web/src/core/threads/hooks.ts:207` —— `useStream` 用法
-- `frontend-web/src/core/api/api-client.ts` —— LangGraph SDK Client 初始化
-- `offline-backend-20260512/backend/langgraph.json` —— assistant 注册位置
-- `offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/` —— graph 工厂参考写法
-- `offline-backend-20260512/backend/packages/harness/deerflow/runtime/checkpointer/async_provider.py` —— 共享 checkpointer 入口
-
-### 目标（迁后）
-- 新增：`packages/harness/deerflow/agents/ai_writing/graph.py:make_ai_writing_graph`
-- 新增：`frontend-web/src/open-canvas/hooks/useAIWritingStream.ts`
-- 删除：`app/gateway/routers/ai_writing.py` 中的 `/start /stream /resume /state` 路由 + 8 个 dict
-- 删除：`frontend-web/src/open-canvas/api/ai-writing.ts` 中的 `startWriting / streamSession / resume` 全部 fetch 调用
-- 简化：`app/gateway/ai_writing_cleanup.py`（改用 SDK client 删 thread）
-
----
-
-## 十、决策摘要（给 PM / 维护者）
-
-> **TL;DR**
-> 1. 主聊天不受多 worker 影响，是因为它把状态托管给了独立的 LangGraph Server 进程，前端直接通过 SDK 跟 Server 通信。AI 写作要做同样的事。
-> 2. 改造范围：后端 graph 注册 + 节点流通道改造 + 前端 hook 换 SDK + 业务表写入解耦。**核心约 6 人日，含 buffer 9 人日**。
-> 3. 业务表、节点逻辑、4 个干预点、UI 形态全部保留，**用户感知层面零变化**。
-> 4. 改造完一次性获得"刷新不丢进度、多 worker 不裂、跟主聊天共享基础设施、IM 渠道免费支持"等长期红利。
-> 5. 建议跟"方案 C"并行：先按 [ai-writing-说明.md](./ai-writing-说明.md) 上方案 C 应急止血，本方案作为长期改造按周排期。两者不冲突，方案 C 上线即受益，本方案完工后可下线方案 C 的双进程配置。

frontend-web/docs/ai-writing-右侧编辑器-滑词与段落菜单.md

@@ -0,0 +1,228 @@
+# AI 写作 · 右侧文本编辑器（滑词 / 段落菜单）
+
+> 说明 AI 写作页、开放画布中文稿右侧编辑器的实现方式：**编辑器本体基于 Tiptap v3**；选中文本浮层（「滑词」）与段落悬停按钮为**自研 React 组件**，未使用 `@tiptap/extension-bubble-menu` 官方 BubbleMenu。
+
+---
+
+## 一、功能概览
+
+| 交互 | 用户感知 | 组件 | 触发方式 |
+|------|----------|------|----------|
+| **滑词** | 拖选一段文字后，选区上方出现工具条（AI 改写、加粗、斜体、下划线、H1、复制） | `WritingBubbleMenu` | Tiptap `selectionUpdate` + 浏览器 `window.getSelection()` |
+| **段落菜单** | 鼠标移入某段/标题/引用块时，段落左侧出现 ✨ 按钮，点击可 AI 改写整段 | `WritingParagraphMenu` | 编辑器 DOM `mousemove` + ProseMirror `posAtCoords` |
+| **AI 改写面板** | 点击「AI 改写」后弹出润色/扩写等操作与预览 | `WritingAiMenu` / `WritingRewritePreview` | 由 `TextArtifactRenderer` + `useWritingRewrite` 串联 |
+
+画布线程页（`/page/canvas/:thread_id`）与 AI 写作页（`/page/workspace/ai-writing`）右侧草稿**共用同一套** `TextArtifactRenderer` 与菜单组件。
+
+---
+
+## 二、在 AI 写作中的挂载路径
+
+```mermaid
+flowchart TB
+  AIWritingPage --> CanvasResizableLayout
+  CanvasResizableLayout --> AIWritingDraftPanel
+  AIWritingDraftPanel --> DraftStreamingPreview
+  AIWritingDraftPanel --> TextArtifactRenderer
+  DraftStreamingPreview["DraftStreamingPreview<br/>（流式只读 Markdown）"]
+  TextArtifactRenderer --> WritingBubbleMenu
+  TextArtifactRenderer --> WritingParagraphMenu
+  TextArtifactRenderer --> TiptapEditor
+  TextArtifactRenderer --> WritingAiMenu
+```
+
+| 阶段 | 右侧展示 | 滑词 / 段落菜单 |
+|------|----------|-----------------|
+| 草稿流式生成中（`writing_draft` / `revising` 且有 section 流） | `DraftStreamingPreview`（ReactMarkdown 只读） | **不可用** |
+| 成稿可编辑（`isDraftEditable === true`） | `TextArtifactRenderer` + Tiptap | **可用** |
+| 流式结束但尚未 editable | `TextArtifactRenderer` 且 `isStreaming={true}` | **不可用**（`editable: false`） |
+
+相关状态由 [CanvasUIContext.tsx](../src/open-canvas/contexts/CanvasUIContext.tsx) 的 `isDraftStreaming`、`isDraftEditable` 控制；注释中「禁用编辑/润色/滑词」即指生成完成前不进入可编辑渲染器。
+
+入口文件：
+
+- [AIWritingDraftPanel.tsx](../src/open-canvas/components/ai-writing/AIWritingDraftPanel.tsx) — 决定流式预览 vs `TextArtifactRenderer`
+- [TextArtifactRenderer.tsx](../src/open-canvas/components/artifact/TextArtifactRenderer.tsx) — 挂载编辑器与两套浮层菜单
+
+---
+
+## 三、技术栈：编辑器 vs 浮层
+
+### 3.1 Tiptap 编辑器（有使用）
+
+| 包 | 用途 |
+|----|------|
+| `@tiptap/react` | `useEditor`、`EditorContent` |
+| `@tiptap/starter-kit` | 段落、标题、加粗、斜体、下划线等 |
+| `@tiptap/extension-placeholder` | 空文档占位符 |
+| `tiptap-markdown` | Markdown ↔ 文档互转 |
+| 自研 `AiHighlightExtension` | AI 改写前高亮选区（ProseMirror Decoration） |
+
+扩展注册见 [TiptapExtensions.ts](../src/open-canvas/editor/TiptapExtensions.ts)；实例创建见 [useWritingEditor.ts](../src/open-canvas/hooks/useWritingEditor.ts)。
+
+### 3.2 浮层菜单（自研，非 Tiptap 官方插件）
+
+| 包 | 是否用于滑词/段落菜单 |
+|----|----------------------|
+| `@tiptap/extension-bubble-menu` | **未使用**（`package.json` 中有依赖，代码未 import） |
+| `@tiptap/react` 的 `<BubbleMenu>` | **未使用** |
+
+两套菜单均采用：
+
+1. 监听 Tiptap / DOM 事件更新位置与选区；
+2. `createPortal(..., document.body)` 挂到 `document.body`，避免被右侧滚动容器 `overflow` 裁切；
+3. `position: fixed` + `getBoundingClientRect()` 定位。
+
+命名上的 `WritingBubbleMenu` 仅表示「气泡式选区工具条」，实现上与 Tiptap 官方 Bubble Menu 扩展无关。
+
+---
+
+## 四、核心文件索引
+
+| 文件 | 职责 |
+|------|------|
+| [TiptapEditor.tsx](../src/open-canvas/editor/TiptapEditor.tsx) | `EditorContent` 渲染容器 |
+| [TiptapExtensions.ts](../src/open-canvas/editor/TiptapExtensions.ts) | StarterKit、Placeholder、Markdown、AiHighlight |
+| [AiHighlightExtension.ts](../src/open-canvas/editor/AiHighlightExtension.ts) | `setAiHighlight` / `clearAiHighlight` 命令 |
+| [useWritingEditor.ts](../src/open-canvas/hooks/useWritingEditor.ts) | 创建 editor、同步外部 markdown、editable |
+| [WritingBubbleMenu.tsx](../src/open-canvas/components/artifact/WritingBubbleMenu.tsx) | **滑词** 选区浮层 |
+| [WritingParagraphMenu.tsx](../src/open-canvas/components/artifact/WritingParagraphMenu.tsx) | **段落** 左侧 ✨ 按钮 |
+| [WritingAiMenu.tsx](../src/open-canvas/components/artifact/WritingAiMenu.tsx) | AI 改写操作菜单 |
+| [WritingRewritePreview.tsx](../src/open-canvas/components/artifact/WritingRewritePreview.tsx) | 改写结果预览 |
+| [useWritingRewrite.ts](../src/open-canvas/hooks/useWritingRewrite.ts) | 调用润色 API、写回编辑器 |
+| [apply-rewrite.ts](../src/open-canvas/utils/apply-rewrite.ts) | 将改写结果应用到 ProseMirror 选区 |
+| [CanvasUIContext.tsx](../src/open-canvas/contexts/CanvasUIContext.tsx) | `writingSelection` 全局状态 |
+| [selection.ts](../src/open-canvas/types/selection.ts) | `WritingSelection` 类型定义 |
+
+---
+
+## 五、滑词：`WritingBubbleMenu`
+
+### 5.1 行为
+
+- 用户在编辑器内拖选非空文本时显示浮层；选区为空或位于 `codeBlock` 内时隐藏。
+- 浮层按钮：`AI 改写`、`B` / `I` / `U`、`H1`、复制。
+- 按钮 `onMouseDown` 使用 `e.preventDefault()`，避免点击时编辑器失焦导致选区丢失。
+
+### 5.2 实现要点
+
+```text
+editor.on("selectionUpdate") 
+  → 读取 editor.state.selection (from, to, empty)
+  → window.getSelection() + Range.getBoundingClientRect() 算屏幕坐标
+  → setWritingSelection({ from, to, text }) 写入 CanvasUIContext
+  → createPortal 渲染工具条，useLayoutEffect 做贴边 / 上方空间不足时翻到选区下方
+```
+
+关键代码位置：[WritingBubbleMenu.tsx](../src/open-canvas/components/artifact/WritingBubbleMenu.tsx) 中 `useEffect` 监听 `selectionUpdate` 与 `blur`。
+
+点击「AI 改写」时：
+
+1. `editor.commands.setAiHighlight(from, to)` 高亮选区；
+2. 调用父组件传入的 `onAiRewrite()`，由 `TextArtifactRenderer` 打开 `WritingAiMenu`。
+
+---
+
+## 六、段落菜单：`WritingParagraphMenu`
+
+### 6.1 行为
+
+- 鼠标在编辑器内移动时，检测光标下的**块级节点**；
+- 仅对 `paragraph`、`heading`、`blockquote` 且文本非空时，在块左侧显示 ✨ 按钮；
+- 鼠标离开编辑器或移出可改写块后，延迟约 **380ms** 隐藏（`HIDE_DELAY`），并在按钮与正文之间留有 hover 桥接区，避免移向按钮时闪烁消失。
+
+### 6.2 实现要点
+
+```text
+editor.view.dom mousemove
+  → editor.view.posAtCoords({ left, top })
+  → doc.resolve(pos).before(depth) 定位块起点
+  → editor.view.nodeDOM(nodeStart) 取 DOM 矩形
+  → createPortal 固定定位按钮在块左侧 (BTN_SIZE=24, BTN_GAP=6)
+```
+
+点击 ✨ 时：
+
+1. `setTextSelection` 选中整段 ProseMirror 范围（`nodeFrom` ~ `nodeTo`）；
+2. `setAiHighlight` + `setWritingSelection`；
+3. 触发与滑词相同的 `onAiRewrite()` 流程。
+
+关键代码位置：[WritingParagraphMenu.tsx](../src/open-canvas/components/artifact/WritingParagraphMenu.tsx)。
+
+---
+
+## 七、AI 改写数据流
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Menu as BubbleMenu / ParagraphMenu
+  participant Ctx as CanvasUIContext
+  participant Renderer as TextArtifactRenderer
+  participant API as rewrite API
+
+  User->>Menu: 选中文本或点段落 ✨
+  Menu->>Ctx: setWritingSelection
+  Menu->>Renderer: onAiRewrite()
+  Renderer->>Renderer: phase = menu, WritingAiMenu
+  User->>Renderer: 选择润色/扩写等
+  Renderer->>API: useWritingRewrite.rewrite
+  API-->>Renderer: 流式结果
+  Renderer->>Renderer: WritingRewritePreview
+  User->>Renderer: 接受改写
+  Renderer->>Renderer: applyReplace / applyInsert
+```
+
+- 选区信息类型：`WritingSelection`（`from`、`to`、`text`），见 [selection.ts](../src/open-canvas/types/selection.ts)。
+- 与画布聊天侧选区 `CanvasTextSelection` 分离；后者用于快捷操作栏等，不用于 Tiptap 改写。
+
+---
+
+## 八、与顶部工具栏、目录栏的关系
+
+同一 `TextArtifactRenderer` 编辑模式下还包含：
+
+| 组件 | 作用 |
+|------|------|
+| [WritingToolbar.tsx](../src/open-canvas/components/artifact/WritingToolbar.tsx) | 顶部固定格式栏、导出等 |
+| [DraftOutlineSidebar.tsx](../src/open-canvas/components/artifact/DraftOutlineSidebar.tsx) | 左侧标题目录，点击滚动到对应 heading |
+
+滑词 / 段落菜单与工具栏互不替代：工具栏面向全局格式；浮层面向**当前选区或当前段落**的快捷操作与 AI 改写入口。
+
+---
+
+## 九、开发与改造建议
+
+### 9.1 若要改用官方 Bubble Menu
+
+1. 在 [TiptapExtensions.ts](../src/open-canvas/editor/TiptapExtensions.ts) 或组件层引入 `@tiptap/react` 的 `BubbleMenu`（或注册 `@tiptap/extension-bubble-menu`）；
+2. 将 [WritingBubbleMenu.tsx](../src/open-canvas/components/artifact/WritingBubbleMenu.tsx) 内手写 `selectionUpdate` + Portal 逻辑替换为官方组件的 `shouldShow` / `tippyOptions`（v3 API 以官方文档为准）；
+3. **段落左侧按钮**仍建议保留自研 `WritingParagraphMenu`（官方 Bubble Menu 只覆盖选区，不覆盖 hover 段落场景）。
+
+### 9.2 新增浮层按钮
+
+- **滑词**：在 `WritingBubbleMenu` 的 `BubbleButton` 列表中增加，使用 `editor.chain().focus()....run()`。
+- **段落**：在 `WritingParagraphMenu` 的 `handleClick` 或拆出多按钮布局；注意 `REWRITABLE_TYPES` 与 hover 延迟逻辑。
+
+### 9.3 流式阶段禁止交互
+
+不要在 `DraftStreamingPreview` 中挂载 Tiptap 菜单：流式阶段 token 高频更新，挂载 `useWritingEditor` 易引发更新风暴（见 [DraftStreamingPreview.tsx](../src/open-canvas/components/ai-writing/DraftStreamingPreview.tsx) 文件头注释）。应等 `isDraftEditable` 后再走 `TextArtifactRenderer`。
+
+---
+
+## 十、相关文档
+
+- [前端开发.md](./前端开发.md) §25.4 — Canvas / AI 写作路由与组件总表
+- [ai-writing-用户自带大纲-测试用例.md](./ai-writing-用户自带大纲-测试用例.md) — AI 写作业务流程测试（含右侧草稿层级校验）
+
+---
+
+## 十一、依赖版本（摘录）
+
+以 [package.json](../package.json) 为准，编辑器相关主要为：
+
+- `@tiptap/core`、`@tiptap/react`、`@tiptap/starter-kit`：`^3.23.4`
+- `@tiptap/extension-bubble-menu`：已安装但未接入滑词实现
+- `tiptap-markdown`：Markdown 扩展
+
+升级 Tiptap 大版本前，请对照官方迁移指南，并重点回归：`WritingBubbleMenu` 选区坐标、`WritingParagraphMenu` 的 `posAtCoords`、以及 `AiHighlightExtension` 与 StarterKit 扩展名冲突（勿重复注册 `underline`）。

frontend-web/docs/ai-writing-用户自带大纲-测试用例.md

@@ -0,0 +1,274 @@
+# AI 写作 ·「用户自带大纲」手动测试用例
+
+> 功能：用户在 AI 写作表单粘贴已有大纲后，系统**完全按用户大纲生成正文**，兼容一/二/三级目录。
+> 入口页面：`http://localhost:5173/#/page/workspace/ai-writing`（或 `2026` 端口经 nginx）
+
+---
+
+## 一、测试目标
+
+验证三件事：
+1. **识别**——用户粘贴的各种格式大纲，能被正确解析成 章节(##) → 小节(###) → 子要点(####) 三级结构。
+2. **保真**——生成的大纲标题、层级**与用户粘贴的完全一致**，不增、不删、不改写。
+3. **兼容**——只有一级 / 一+二级 / 一+二+三级 三种深度都能正确生成对应层级的正文。
+
+---
+
+## 二、前置条件
+
+| 项 | 要求 |
+|----|------|
+| 服务 | 后端（Gateway 8001）+ 前端（Vite 5174/5173）均已启动，可正常发起一次普通 AI 写作 |
+| 模型 | 写作模型已在表单可选、能正常输出（先用不带大纲的普通流程跑通一次作为基线） |
+| 账号 | 已登录（或无鉴权模式） |
+| 入口 | 进入 `/page/workspace/ai-writing`，能看到「写作配置选项」表单 |
+
+---
+
+## 三、通用操作步骤
+
+除非用例另有说明，每条用例都按以下步骤执行：
+
+1. 进入 AI 写作页面，点开**「已有大纲（可选）」** 旁的「我已有大纲，直接粘贴 ▾」。
+2. 在「写作意图」填一句话（如：`写一篇关于新能源汽车出口的分析文章`）。
+3. 把用例里的**「输入大纲」**整段粘贴进「已有大纲」输入框。
+4. 文章类型 / 目标字数 / 素材来源保持默认即可。
+5. 点击「开始 AI 写作」。
+6. 等待流程走到 **PAUSE-2「大纲确认」**，对照**「预期大纲结构」**核对左侧/卡片里的大纲。
+7. 点「确认」继续，等正文生成完，对照**「预期正文层级」**核对右侧草稿的标题层级。
+
+> 关键校验点都在第 6 步（大纲确认卡）。正文层级（第 7 步）作为二次确认。
+
+---
+
+## 四、测试用例
+
+### TC-01　Markdown 三级 + 文章标题
+
+**输入大纲：**
+```
+# 新能源汽车出口为何高速增长
+## 引言
+### 出口数据创新高
+#### 同比增幅
+#### 全球排名变化
+### 市场背景
+## 增长动因
+### 成本优势
+```
+
+**预期大纲结构：**
+- 文章标题 = `新能源汽车出口为何高速增长`（首个孤立 `#` 被识别为标题，不作为章节）
+- 章节1 `引言`
+  - 小节 `出口数据创新高` → 子要点：`同比增幅`、`全球排名变化`
+  - 小节 `市场背景`（无子要点）
+- 章节2 `增长动因`
+  - 小节 `成本优势`
+
+**预期正文层级：** `#` 文章标题 → `##` 引言/增长动因 → `###` 小节 → `####` 同比增幅/全球排名变化，各级都有正文。
+
+---
+
+### TC-02　中文编号三级（一、/（一）/ 1.）
+
+**输入大纲：**
+```
+一、引言
+（一）背景
+（二）意义
+二、现状分析
+（一）市场数据
+1. 国内市场
+2. 海外市场
+```
+
+**预期大纲结构：**
+- 章节1 `引言` → 小节 `背景`、`意义`
+- 章节2 `现状分析` → 小节 `市场数据` → 子要点 `国内市场`、`海外市场`
+- 标题留空 → 用「写作意图」兜底（卡片标题约等于意图前 30 字）
+
+**校验重点：** `一、` > `（一）` > `1.` 的层级顺序正确（符合中文公文惯例）。
+
+---
+
+### TC-03　阿拉伯小数点编号（1. / 1.1 / 1.1.1）
+
+**输入大纲：**
+```
+1. 引言
+1.1 研究背景
+1.2 研究意义
+2. 现状
+2.1 行业概况
+```
+
+**预期大纲结构：**
+- 章节1 `引言` → 小节 `研究背景`、`研究意义`
+- 章节2 `现状` → 小节 `行业概况`
+
+---
+
+### TC-04　缩进 bullet 表示层级
+
+**输入大纲：**
+```
+- 引言
+  - 背景
+  - 意义
+- 现状
+  - 数据
+    - 细节展开
+```
+
+**预期大纲结构：**
+- 章节1 `引言` → 小节 `背景`、`意义`
+- 章节2 `现状` → 小节 `数据` → 子要点 `细节展开`
+
+**校验重点：** 缩进深度正确映射成层级。
+
+---
+
+### TC-05　只有一级目录（平铺 Markdown）
+
+**输入大纲：**
+```
+## 引言
+## 现状
+## 对策
+## 结论
+```
+
+**预期大纲结构：** 4 个章节 `引言/现状/对策/结论`，**均无小节**。
+**预期正文层级：** 每个章节 `##` 标题下是一整段连贯正文（不出现 `###`）。
+
+**校验重点：** 一级目录场景不报错、不被强行拆出多余小节。
+
+---
+
+### TC-06　只有一级目录（中文编号）
+
+**输入大纲：**
+```
+一、引言
+二、现状
+三、结论
+```
+
+**预期大纲结构：** 3 个章节 `引言/现状/结论`，无小节。与 TC-05 等价，验证另一种一级写法。
+
+---
+
+### TC-07　纯文本平铺（无任何标记）
+
+**输入大纲：**
+```
+引言
+现状
+对策
+总结
+```
+
+**预期大纲结构：** 4 个章节 `引言/现状/对策/总结`（每行一个短标题 → 一级章节）。
+
+**校验重点：** 无编号无缩进的短标题列表也能识别为一级大纲。
+
+---
+
+### TC-08　格式混乱 / 散文化（走 LLM 兜底）
+
+**输入大纲：**
+```
+我想写一篇分析今年AI大模型发展趋势的文章，重点关注国内企业的布局。
+希望先讲背景，再讲现状，最后给出展望。
+```
+
+**预期行为：**
+- 确定性解析判定为「散文」→ 自动走 **LLM 归一兜底**，整理成一份结构化大纲。
+- 大纲确认卡能正常显示一份大纲（不报错、不卡死）。
+- 大纲内容应贴近原意（背景 / 现状 / 展望之类），**但不要求逐字一致**（这一条是兜底鲁棒性，不是保真用例）。
+
+**校验重点：** 流程不崩、能产出可用大纲。
+
+---
+
+### TC-09　保真校验（标题原样保留）
+
+**输入大纲：**
+```
+一、A股市场2024年回顾与展望
+（一）宏观经济（GDP/CPI）影响
+（二）流动性与利率
+二、行业轮动主线
+```
+
+**预期大纲结构：** 标题文本**逐字保留**，仅编号被剥离：
+- 章节1 `A股市场2024年回顾与展望`
+  - 小节 `宏观经济（GDP/CPI）影响`、`流动性与利率`
+- 章节2 `行业轮动主线`
+
+**校验重点：** 标题里的中文括号、英文缩写、年份等**不被改写**。
+
+---
+
+### TC-10　大纲确认卡里再编辑 / 重新规划
+
+**前置：** 先用 TC-02 的大纲跑到「大纲确认」卡。
+
+**操作：**
+1. 在确认卡里**手动改一个小节标题**（如把 `背景` 改成 `行业背景`）→ 点「确认」。
+2. 或点「重新规划」并填修改要求（如 `给"现状分析"再加一个小节`）。
+
+**预期行为：**
+- 手动改后确认：正文按改后的大纲生成。
+- 重新规划：基于**用户这份大纲**做编辑式调整（在原结构上加/改），而不是从零另起一份无关大纲。
+
+**校验重点：** 自带大纲 → 确认 → 编辑 这条回路正常，不会丢掉用户原始结构。
+
+---
+
+### TC-11　回归：不填大纲（默认流程不受影响）
+
+**操作：** 「已有大纲」**留空**，只填写作意图，正常发起。
+
+**预期行为：** 与功能上线前完全一致——系统自动检索素材、**自动规划大纲**（大纲由 AI 生成，非用户提供）。
+
+**校验重点：** 增量功能不污染老流程。
+
+---
+
+### TC-12　素材关联（仍走检索）
+
+**前置：** 素材来源选「知识库」，用 TC-02 的大纲发起，等检索出素材并确认。
+
+**预期行为：**
+- 走到大纲时，用户的章节会被**关联上检索到的素材**（正文里能体现素材中的事实/数据）。
+- 关联**只填素材、不改大纲标题与结构**。
+
+**校验重点：** 「自带大纲」与「检索素材」能共存——大纲是用户的，正文有素材支撑。
+
+---
+
+## 五、缺陷记录模板
+
+| 用例 | 输入大纲（摘要） | 预期 | 实际 | 是否通过 | 备注 |
+|------|------------------|------|------|----------|------|
+| TC-01 | Markdown 三级 | 标题+2章节+子要点 | | ☐ | |
+| TC-02 | 一、/（一）/1. | 中文三级 | | ☐ | |
+| TC-03 | 1./1.1/1.1.1 | 阿拉伯三级 | | ☐ | |
+| TC-04 | 缩进 bullet | 缩进三级 | | ☐ | |
+| TC-05 | 平铺 ## | 4 章节无小节 | | ☐ | |
+| TC-06 | 平铺 一、 | 3 章节无小节 | | ☐ | |
+| TC-07 | 纯文本平铺 | 4 章节 | | ☐ | |
+| TC-08 | 散文 | LLM 兜底产出大纲 | | ☐ | |
+| TC-09 | 带括号/缩写标题 | 标题逐字保留 | | ☐ | |
+| TC-10 | 确认卡编辑/重规划 | 在原大纲上调整 | | ☐ | |
+| TC-11 | 留空 | 走自动规划 | | ☐ | |
+| TC-12 | 检索+自带大纲 | 素材关联不改结构 | | ☐ | |
+
+---
+
+## 六、备注
+
+- TC-01~07、09 的解析逻辑已有**自动化单测**覆盖（`backend/tests/test_ai_writing_outline_parser.py`，19 个用例），本文档侧重**端到端真机表现**（流式展示、确认卡渲染、正文层级、素材关联）。
+- 若某条解析结果与预期不符，先看大纲确认卡里的**结构**是否正确（定位是解析问题还是正文生成问题）。
+- 相关后端实现：`packages/harness/deerflow/agents/ai_writing/outline_parser.py`（解析）、`nodes/writer_outline.py`（自带大纲分支 + 素材关联）。

frontend-web/docs/ai-writing-说明.md

@@ -1,787 +0,0 @@
-# AI 写作 — 故障排查与解决方案说明
-
-> **本文档目的**：完整记录 AI 写作子系统在内网 Docker 部署后出现的问题、根因、已落地的修复、剩余风险、以及未来的解决方案路径。
->
-> **适用读者**：维护 AI 写作功能的前端/后端开发者、内网部署运维。
->
-> **更新日期**：2026-05-20
-
----
-
-## 一、问题背景
-
-### 起因
-内网 Docker 部署后，AI 写作出现两类报错：
-
-| 接口 | 报错 | 频率 |
-|---|---|---|
-| `PUT /api/ai-writing/sessions/{id}/transcript` | HTTP 500 | 经常 |
-| `POST /api/ai-writing/{id}/resume` | HTTP 4xx（用户记忆为 400，实际可能是 404） | 经常，且没有 Docker 重启时也发生 |
-
-### 这两个接口的作用
-
-#### 1. `PUT /sessions/{id}/transcript` — 对话时间线持久化
-- **职责**：保存前端组装的完整对话时间线（progressEvents + completedInterventions）到 MySQL
-- **调用时机**：前端在写作过程中**反复 PUT**（事件累计、干预完成、草稿生成等节点全量覆盖）
-- **存到哪**：MySQL 的 `ai_writing_sessions.transcript` 列（LONGTEXT）
-- **用途**：用户**关闭页面后再回来 / 刷新 / 看历史会话**时，从 DB 拉回这段时间线，UI 上回显出「跟实时一样的对话历史」
-- **定位**：**纯锦上添花** — 失败了用户当下写作完全不受影响，只是历史回显会缺失/不完整
-
-#### 2. `POST /{id}/resume` — 写作流程的核心控制接口
-- **职责**：提交用户在干预点的决策，让 LangGraph 从挂起的 interrupt 点继续推进
-- **调用时机**：用户在 4 个 interrupt 点（素材确认 / 大纲确认 / 草稿确认 / 审核确认）做出决定后
-- **传什么**：用户的决策内容（确认的素材 id、修改后的大纲、用户的修订意见、章节求助决策…）
-- **定位**：**流程主干** — 它失败，用户就**真的卡死**在干预点
-
----
-
-## 二、根因分析
-
-### 根因 1：`transcript` 列容量不足 + 路由层无兜底
-- MySQL `TEXT` 列上限 64 KB
-- 用户写作过程中累计 `progressEvents`（含每个流式 chunk）+ `completedInterventions` 后，JSON blob 经常超过 64 KB
-- `session.commit()` 抛 `DataError: Data too long for column 'transcript'`
-- 原路由没有 try/except，异常直接冒泡成 HTTP 500
-
-### 根因 2：内存中的会话状态在多 worker 部署下隔离
-后端用了大量模块级 dict 维护会话状态：
-
-```python
-_event_queues:          dict[str, asyncio.Queue]  # SSE 事件队列
-_session_pending_pause: dict[str, tuple]          # 挂起的 await_user 事件
-_session_model_names:   dict[str, str]            # 用户选的模型
-_session_interventions: dict[str, list]           # 累计干预历史
-_session_repos:         dict[str, repo]           # DB 仓库引用
-_session_user_ids:      dict[str, str]            # 用户 id
-_session_article_types: dict[str, list]           # 文章类型列表
-```
-
-**uvicorn / gunicorn 多 worker 是多进程共享 socket**，OS 内核决定哪个 worker 接到请求，应用层和 nginx 都管不着。所以：
-
-```
-T0: POST /start → worker A 创建 _event_queues[sid] = QueueA
-                  graph 推进任务跑在 worker A
-T1: GET /stream → 落 worker B，没有 QueueA 的引用
-                  → 触发 _recover_session，从 sqlite 重建 QueueB
-                  → SSE 推 QueueB 但事件都在 QueueA 里
-T2: POST /resume → 落 worker C，同样无法看到 A/B 的状态
-```
-
-**结果**：SSE 时断时续、resume 偶发 404「会话状态已丢失」。
-
-### 根因 3：Graph 用了内存 checkpointer
-原代码：
-```python
-# ai_writing/graph.py
-checkpointer = MemorySaver()
-```
-进程内的 `MemorySaver` 重启即丢，**容器重启或单 worker 进程被回收**后所有进行中会话都拿不到。
-
-### 根因 4：路径配错
-`config.yaml` 里 sqlite 路径写成了 Windows 绝对路径 `D:\cursor-work\...`，Linux 容器里根本无法解析。
-
----
-
-## 三、已落地的修复（已合入 dhk-1 分支）
-
-### 修复 1：`transcript` 列改 LONGTEXT + 路由兜底
-
-| 文件 | 改动 |
-|---|---|
-| `packages/harness/deerflow/persistence/types.py` | 新增 `PortableLongText` 类型（MySQL→LONGTEXT，SQLite/PG→TEXT） |
-| `packages/harness/deerflow/persistence/ai_writing_sessions/model.py` | `transcript` 列改成 `PortableLongText` |
-| `packages/harness/deerflow/persistence/migrations/versions/20260519_02_ai_writing_transcript_longtext.py` | Alembic 迁移：MySQL 上 `ALTER ... type_=LONGTEXT()` |
-| `app/gateway/routers/ai_writing.py` | `save_transcript` 整段 try/except 包裹，**任何异常都返回 `{success: false, reason}`，永远不抛 5xx** |
-
-**结果**：transcript 500 永远不会再发生。前端已经做了 fire-and-forget 容错，失败只 `console.warn`，写作流程不阻断。
-
-### 修复 2：Checkpointer 改为持久化 SQLite
-
-| 文件 | 改动 |
-|---|---|
-| `packages/harness/deerflow/agents/ai_writing/graph.py` | `MemorySaver()` → 懒加载 `AsyncSqliteSaver` |
-| 同上 | 新增 `get_ai_writing_graph()` / `get_ai_writing_checkpointer()` / `shutdown_ai_writing_graph()` |
-| `offline-backend-20260512/config.yaml` | sqlite 路径改成相对路径 `.deer-flow/data/checkpoints.db` |
-
-**关键容错**：sqlite 初始化失败（磁盘满 / 权限 / aiosqlite 未装 / 损坏）会**自动降级 InMemorySaver**，写作流程能跑完，但跨重启不可恢复。
-
-### 修复 3：跨 worker / 进程重启会话恢复
-
-| 文件 | 改动 |
-|---|---|
-| `app/gateway/routers/ai_writing.py` | 新增 `_recover_session(session_id, request)` |
-
-当 worker 内存里没有该 session 时，从 sqlite checkpointer 读快照，重建 `_event_queues`、重新注入 `await_user` 事件。
-
-**效果**：worker B 收到的 resume 请求，能从 sqlite 找到 worker A 写下的 checkpoint，**resume 接口本身能跑通**（但 SSE 事件流仍隔离 — 见下文剩余风险）。
-
-### 修复 4：多层失败兜底，保证写作流程能继续
-
-| 改动 | 作用 |
-|---|---|
-| `_sse(event, data)` 加 `default=str` + notice 帧降级 | JSON 序列化失败不会让 SSE 断开 |
-| 所有 DB 写入（草稿/审核/干预/status）已包 try/except | DB 异常吞掉，graph 继续推 |
-| 文章类型加载失败 → 退回 `[]` | intent_parser 仍能跑 |
-| `/start` 加 503 兜底 | graph 构建失败时给前端可读错误而不是 500 |
-
-### 修复 5：定期清理 + admin 触发接口
-
-| 文件 | 改动 |
-|---|---|
-| `app/gateway/ai_writing_cleanup.py` | 新文件：cron 调度 + 联动清理（MySQL 行 + sqlite checkpointer thread） |
-| `packages/harness/deerflow/persistence/ai_writing_sessions/sql.py` | 新增 `list_older_than()` / `delete_by_ids()` |
-| `app/gateway/app.py` | lifespan 启动/停止清理任务 |
-| `app/gateway/routers/ai_writing.py` | 新增 `POST /api/ai-writing/admin/cleanup` 手动触发接口（admin only） |
-| `config.yaml` | 新增 `ai_writing.cleanup` 段（默认每天凌晨 3 点跑，保留 7 天） |
-
-**关键安全机制**：清理永远跳过 `_event_queues` 里仍在跑的会话（**活跃保护**），即使 admin 手动传 `retention_days: 0` 也不会秒杀正在写作的用户。
-
-### 修复 6：优雅关闭 — In-flight Drain
-
-| 文件 | 改动 |
-|---|---|
-| `app/gateway/routers/ai_writing.py` | 新增 `_inflight_graph_tasks` + `_spawn_graph_task()` + `wait_for_inflight_graph_tasks(timeout)` |
-| `app/gateway/app.py` | lifespan shutdown 顺序：取消清理 → **等 in-flight 写作 task 收尾（30s 超时）** → 关 checkpointer connection |
-
-容器收到 SIGTERM 时，给正在跑的写作 30 秒窗口跑到下一个 interrupt / END，已生成的 checkpoint 都安全落盘。
-
-### 修复 7：多 worker 配置陷阱检测
-
-| 文件 | 改动 |
-|---|---|
-| `app/gateway/app.py` | lifespan startup 检测 `WEB_CONCURRENCY > 1` 或 `/proc` 里同名 uvicorn 进程数 > 1 → 打 ERROR 日志 |
-
-下次启动容器看 docker logs 第一屏就能看到强提醒。
-
----
-
-## 四、当前状态评估
-
-### transcript 500
-✅ **彻底修复**，跟 worker 数无关。LONGTEXT 列 + 路由兜底双保险。
-
-### resume 报错
-⚠️ **大幅缓解**：
-- 接口本身（在 worker > 1 下）能跑通
-- sqlite 共享让 worker B 也能恢复 worker A 创建的 session
-
-❌ **未彻底解决**：
-- SSE 事件流仍 per-worker 隔离
-- 用户可能看到「进度时有时无、需要刷新页面才能看到草稿」
-- 但**草稿、审核结果**都落到 MySQL，刷新 `/sessions/{id}` 总能看到最终成品
-
-### 「写作流程能不能跑完」
-✅ **能**。最坏情况下：
-- 用户感受：进度断断续续，需要刷新几次
-- 数据保证：草稿和审核都落 MySQL，**写出来的内容不会丢**
-
----
-
-## 五、剩余风险
-
-### 风险 A：多 worker 下 SSE 事件流隔离 ⚠️ 最重要
-
-**症状**：用户 SSE 长连接绑在 worker B，但 graph 推进任务跑在 worker A，事件 put 进 A 的 queue → SSE 收不到。
-
-**为什么不能用 `--workers 1` 解决**：业务团队反馈其他业务功能需要多 worker。
-
-**解决方案见第六章**。
-
-### 风险 B：容器优雅关闭时 in-flight 写作进度
-
-**当前缓解**：30 秒 drain timeout 让 graph 跑到下一个 checkpoint。
-
-**完美方案**（如有需求）：无法 100% 防护，只能尽量缩短「未落 checkpoint」窗口。
-
-### 风险 C：节点级别 LLM 抽风
-
-某个写作节点调用 LLM 时网络抖动 / 限流 → astream 抛错 → session 结束。
-
-**当前缓解**：astream level 已 try/except，推 error 事件。用户从 checkpoint 重试。
-
-**改进方向**（不在本次修复范围）：
-- 给节点加 `tenacity.retry` 重试装饰器
-- 节点抛错时把已生成的部分塞进 progress_events
-
-### 风险 D：跨 worker 恢复时降级丢失
-
-worker B 从 sqlite 恢复 worker A 的 session 时，以下数据回退到默认：
-
-| 数据 | 默认值 | 影响 |
-|---|---|---|
-| `_session_model_names` | `""` | 退回默认模型 |
-| `_session_interventions` | `[]` | 本次 resume 之前的干预历史从内存里丢（MySQL 里有副本，但内存累计不全） |
-| `_session_article_types` | `[]` | 没影响（graph 早过了 intent_parser） |
-
-**改进方向**：恢复时从 MySQL 反向填充内存元数据（约 20 行代码）。
-
----
-
-## 六、Worker > 1 限制下的解决方案路径
-
-### 三条路径对比
-
-| 方案 | 是否引入新依赖 | 代码改动 | 运维改动 | 适用场景 |
-|---|---|---|---|---|
-| **B. Redis Pub/Sub 共享状态** | ⚠️ 需 Redis | ~150 行 | docker-compose 加 redis | 已有 Redis 或愿意上 |
-| **C. AI 写作独立单 worker 进程** | 无 | ~30 行 | docker-compose 加一个容器 / 进程 + nginx 转发 | 不想上 Redis |
-| **F. 多容器单 worker + nginx sticky** | 无 | ~5 行（nginx config） | 把 1 个多 worker 容器拆成 N 个单 worker 容器 | 已经在做容器编排 |
-
-### 方案 B：Redis Pub/Sub（最彻底）
-
-**改造点**：
-
-```
-之前（per-worker memory dict）            之后（Redis 共享）
-─────────────────────────                ─────────────────────
-_event_queues[sid] = asyncio.Queue()  →  Redis Pub/Sub channel "ai_writing:events:{sid}"
-_session_pending_pause                →  Redis Hash "ai_writing:pause"
-_session_model_names                  →  Redis Hash "ai_writing:meta:model"
-_session_interventions                →  Redis Hash + JSON
-_session_repos / _session_user_ids    →  Redis Hash
-```
-
-**关键设计**：
-1. `/start` 在 worker A：graph 推进任务跑在 A，事件 publish 到 Redis channel
-2. `/stream` 在 worker B：subscribe Redis channel，把消息转 SSE 推前端
-3. `/resume` 在 worker C：用 Redis 分布式锁保证「同一 session 同时只有一个 worker 驱动 graph」
-
-**优点**：根治。任何 worker 数、任何部署形态都能跑。
-
-**缺点**：
-- 引入 Redis 依赖（运维负担）
-- 代码改动较大（约 150 行）
-- 需要处理 Redis 断连 / 分布式锁释放等边缘情况
-
-### 方案 C：AI 写作独立服务（次推荐）
-
-**做法**：在同一个容器里多起一个 uvicorn 进程，专门处理 `/api/ai-writing/*`，**显式 `--workers 1`**。
-
-```bash
-# 主 gateway（多 worker，处理其他业务）
-uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --workers 4
-
-# AI 写作专用单 worker
-uvicorn app.gateway.app:app --host 0.0.0.0 --port 8002 --workers 1
-```
-
-nginx 配置：
-```nginx
-location /api/ai-writing/ {
-    proxy_pass http://localhost:8002;
-    proxy_buffering off;
-    proxy_read_timeout 3600s;
-}
-
-location / {
-    proxy_pass http://localhost:8001;
-}
-```
-
-**优点**：
-- 零代码改动
-- 不引入新依赖
-- AI 写作彻底单 worker，问题根除
-
-**缺点**：
-- 容器内多一个进程
-- 内存占用 +1 份 Python runtime（约 200 MB）
-
-### 方案 F：多容器单 worker + nginx sticky
-
-**做法**：把当前 1 个 4 worker 容器，拆成 4 个 1 worker 容器，nginx 用 `ip_hash` 做 sticky。
-
-```yaml
-# docker-compose.yml
-services:
-  gateway-1: { ports: ["8001:8001"], command: ["...", "--workers", "1"] }
-  gateway-2: { ports: ["8002:8001"], command: ["...", "--workers", "1"] }
-  gateway-3: { ports: ["8003:8001"], command: ["...", "--workers", "1"] }
-  gateway-4: { ports: ["8004:8001"], command: ["...", "--workers", "1"] }
-
-  nginx:
-    # upstream 配 ip_hash，让同一个客户端粘到同一个容器
-```
-
-```nginx
-upstream gateway_pool {
-    ip_hash;
-    server gateway-1:8001;
-    server gateway-2:8001;
-    server gateway-3:8001;
-    server gateway-4:8001;
-}
-```
-
-**优点**：零代码改动，标准做法
-
-**缺点**：
-- 改动 docker-compose
-- 客户端 IP 不均匀时负载不均衡（但 AI 写作低并发场景影响小）
-
-### 推荐顺序
-
-1. **方案 C（AI 写作独立单 worker 进程）** — 改动最小、风险最低、立刻可上
-2. **方案 F（多容器 sticky）** — 如果你们已经在做多容器编排
-3. **方案 B（Redis）** — 长期方案，等真正需要水平扩容时再上
-
----
-
-## 六-A、方案 C 在 Docker 容器内的详细实施指南
-
-> **目标**：在不引入新依赖、不动业务代码、不拆容器的前提下，让 AI 写作走专门的单 worker 进程，其它业务继续走多 worker。
->
-> **基础设施**：本项目镜像基于 `python:3.12-slim-bookworm`，用 `uv` 管理依赖，Dockerfile 位于 `offline-backend-20260512/backend/Dockerfile`，默认入口是
->
-> ```
-> CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
-> ```
-
-### 总览：单容器双 uvicorn 进程
-
-```
-                       ┌─────────────── nginx (容器外或前置) ───────────────┐
-                       │                                                    │
-   /api/ai-writing/  ──┼──►  container:8002  (uvicorn --workers 1)   ───►  AI 写作专用
-   其余  /api/*      ──┼──►  container:8001  (uvicorn --workers N)   ───►  其他业务
-                       └────────────────────────────────────────────────────┘
-                                          ▲
-                                          │  (两个进程跑在同一个容器里，共享 .deer-flow 卷
-                                          │   ／同一个 MySQL ／同一个 sqlite checkpoints.db)
-```
-
-两进程都用 **同一个 `app.gateway.app:app`**，区别只在：
-- `8002` 单 worker，专门接 `/api/ai-writing/*`
-- `8001` 多 worker，接其他所有路由
-- 容器内用 `supervisord` 同时托管这两个 uvicorn
-
-### 步骤 1：在镜像里加 supervisord
-
-编辑 `offline-backend-20260512/backend/Dockerfile`，给 **runtime stage**（第 67 行 `FROM python:3.12-slim-bookworm` 之后）补一段：
-
-```dockerfile
-# 安装 supervisord（约 4 MB，纯 Python，无需编译）
-RUN apt-get update \
-    && apt-get install -y --no-install-recommends supervisor \
-    && rm -rf /var/lib/apt/lists/*
-```
-
-如果内网无法访问 debian 源，可用现有的 `APT_MIRROR` build-arg：
-
-```bash
-docker build \
-  --build-arg APT_MIRROR=mirrors.aliyun.com \
-  -f offline-backend-20260512/backend/Dockerfile \
-  -t deerflow-gateway:dual .
-```
-
-### 步骤 2：写 supervisord 配置
-
-新建 `offline-backend-20260512/backend/deploy/supervisord.conf`：
-
-```ini
-[supervisord]
-nodaemon=true               ; 容器主进程，必须前台
-user=root
-logfile=/dev/null           ; 让子进程日志直接走 stdout/stderr，由 docker logs 接管
-logfile_maxbytes=0
-pidfile=/tmp/supervisord.pid
-
-; ─── 主 Gateway：多 worker，处理除 ai-writing 以外的所有业务 ───
-[program:gateway-main]
-command=uv run --no-sync uvicorn app.gateway.app:app
-        --host 0.0.0.0 --port 8001
-        --workers %(ENV_GATEWAY_MAIN_WORKERS)s
-        --proxy-headers --forwarded-allow-ips=*
-directory=/app/backend
-environment=PYTHONPATH=".",AI_WRITING_DEDICATED_PORT="8002"
-autostart=true
-autorestart=true
-stopasgroup=true
-killasgroup=true
-stopsignal=TERM
-stopwaitsecs=35              ; 给 lifespan 的 30s drain 留点余量
-stdout_logfile=/dev/stdout
-stdout_logfile_maxbytes=0
-stderr_logfile=/dev/stderr
-stderr_logfile_maxbytes=0
-
-; ─── AI 写作专用：单 worker，处理 /api/ai-writing/* ───
-[program:gateway-aiwriting]
-command=uv run --no-sync uvicorn app.gateway.app:app
-        --host 0.0.0.0 --port 8002
-        --workers 1
-        --proxy-headers --forwarded-allow-ips=*
-directory=/app/backend
-environment=PYTHONPATH=".",DEER_FLOW_ROLE="ai-writing"
-autostart=true
-autorestart=true
-stopasgroup=true
-killasgroup=true
-stopsignal=TERM
-stopwaitsecs=35
-stdout_logfile=/dev/stdout
-stdout_logfile_maxbytes=0
-stderr_logfile=/dev/stderr
-stderr_logfile_maxbytes=0
-```
-
-**几个关键点**：
-- `nodaemon=true` 让 supervisord 自己变成 PID 1，docker stop 发的 SIGTERM 才能正确传给它，它再传给两个 uvicorn 子进程
-- `stopasgroup=true` + `killasgroup=true` 确保 uvicorn 多 worker 模式下所有子进程一起退
-- `stopwaitsecs=35` 必须大于 lifespan 的 30s drain 超时，否则 in-flight 写作会被 SIGKILL
-- `%(ENV_GATEWAY_MAIN_WORKERS)s` 让主进程 worker 数走环境变量，下面会传
-
-把这个配置文件 COPY 进镜像（在 Dockerfile runtime stage `COPY --from=builder /app/backend ./backend` 之后加）：
-
-```dockerfile
-COPY backend/deploy/supervisord.conf /etc/supervisor/conf.d/deerflow.conf
-```
-
-### 步骤 3：把 Dockerfile 入口换成 supervisord
-
-把 Dockerfile **runtime stage 最后一行** 改成：
-
-```dockerfile
-# 之前
-CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
-
-# 之后
-EXPOSE 8001 8002 2024
-CMD ["supervisord", "-c", "/etc/supervisor/conf.d/deerflow.conf"]
-```
-
-> **`dev` stage 不用改**：开发环境本来就是单 worker、reload 模式，方案 C 是为生产准备的，dev stage 维持原 CMD。
-
-### 步骤 4：暴露端口 / 挂卷 / 环境变量
-
-启动容器时：
-
-```bash
-docker run -d --name deerflow-gateway \
-  -p 8001:8001 \
-  -p 8002:8002 \
-  -e GATEWAY_MAIN_WORKERS=4 \
-  -e DEER_FLOW_CONFIG_PATH=/app/config.yaml \
-  -v /your/host/path/.deer-flow:/app/.deer-flow \
-  -v /your/host/path/config.yaml:/app/config.yaml:ro \
-  -v /your/host/path/extensions_config.json:/app/extensions_config.json:ro \
-  deerflow-gateway:dual
-```
-
-**两个进程必须共享 `.deer-flow` 卷** —— 因为 `checkpoints.db` 在里面（`offline-backend-20260512/config.yaml` 里配的是相对路径 `.deer-flow/data/checkpoints.db`）。两个进程跑在同一个容器内，天然共享文件系统，**这一步不用做任何额外配置**，只要确认数据卷挂出去就行。
-
-> ⚠️ 即便 8002 是单 worker，仍然推荐把 checkpointer 持久化到磁盘，因为：① 容器重启会重建进程；② 如果哪天临时改回多容器/多 worker，数据不丢；③ 跟主 gateway 共享 checkpoint，未来想做读副本也方便。
-
-### 步骤 5：nginx 路由
-
-如果你前面已经有 nginx（容器外或者另一个容器），把 AI 写作的路由独立出来：
-
-```nginx
-upstream gateway_main      { server gateway-host:8001; }
-upstream gateway_aiwriting { server gateway-host:8002; }
-
-server {
-    listen 80;
-    server_name deerflow.example.com;
-
-    # SSE 长连接必须关 buffering
-    proxy_buffering off;
-    proxy_request_buffering off;
-    proxy_http_version 1.1;
-    proxy_set_header Connection "";
-
-    # AI 写作 → 单 worker 后端
-    location /api/ai-writing/ {
-        proxy_pass http://gateway_aiwriting;
-        proxy_read_timeout 3600s;        # graph 跑得久，给足时间
-        proxy_send_timeout 3600s;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # 其它一切 API → 多 worker 后端
-    location /api/ {
-        proxy_pass http://gateway_main;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # 前端静态资源不变
-    location / {
-        proxy_pass http://frontend:5174;
-    }
-}
-```
-
-**`proxy_buffering off` 是必须的** —— 不关 buffering，nginx 会把 SSE 流缓冲到响应结束才一次性吐给前端，等于把流式写作变成「等几分钟啥都看不到 → 一下吐一整篇」。
-
-如果前端是 Vite 直连后端（开发态没走 nginx），就只需要把 `frontend-web` 里 AI 写作相关的 `fetch`/`EventSource` 改成 `:8002`，但更推荐 **始终走 nginx**，对前端透明。
-
-### 步骤 6：如果你用 docker-compose
-
-完整 compose 示例：
-
-```yaml
-services:
-  gateway:
-    image: deerflow-gateway:dual
-    container_name: deerflow-gateway
-    restart: unless-stopped
-    environment:
-      GATEWAY_MAIN_WORKERS: "4"
-      DEER_FLOW_CONFIG_PATH: /app/config.yaml
-    ports:
-      - "8001:8001"
-      - "8002:8002"   # 如果有外层 nginx，且 nginx 跟 gateway 同网段，可去掉这行只走内网
-    volumes:
-      - ./data/deer-flow:/app/.deer-flow
-      - ./config.yaml:/app/config.yaml:ro
-      - ./extensions_config.json:/app/extensions_config.json:ro
-    healthcheck:
-      test: ["CMD", "sh", "-c", "curl -fsS http://localhost:8001/health && curl -fsS http://localhost:8002/health"]
-      interval: 30s
-      timeout: 5s
-      retries: 3
-      start_period: 30s
-    stop_grace_period: 45s   # 给 supervisord 的 35s + 余量，让两路 drain 跑完
-
-  nginx:
-    image: nginx:1.27-alpine
-    depends_on: [gateway]
-    ports: ["80:80"]
-    volumes:
-      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
-```
-
-`stop_grace_period: 45s` 这一行很关键 —— docker-compose 默认只给 10s，到点直接 SIGKILL，in-flight 写作会全部丢。设到 45s 等于 supervisord 的 35s + 10s 余量。
-
-### 步骤 7：验证（按这个清单逐项过）
-
-```bash
-# 1) 两个进程都起来了
-docker exec deerflow-gateway sh -c 'ps -ef | grep -E "uvicorn|supervisord" | grep -v grep'
-# 期望看到：
-#   1 root   supervisord -c /etc/supervisor/conf.d/deerflow.conf
-#   N root   uvicorn app.gateway.app:app --port 8001 --workers 4
-#   M root   uvicorn app.gateway.app:app --port 8002 --workers 1
-#   (8001 那一行会有 N 个 worker 子进程，8002 那一行只有 1 个)
-
-# 2) 8002 只有 1 个 worker（这是方案 C 的命脉）
-docker exec deerflow-gateway sh -c 'pgrep -f "port 8002" | wc -l'
-# 期望 = 2（1 个 master + 1 个 worker）；如果 > 2，单 worker 没生效
-
-# 3) 8001 不再警告多 worker
-docker logs deerflow-gateway 2>&1 | grep -i 'WEB_CONCURRENCY'
-# 期望：没有 ERROR 警告（因为 8001 走的是其他业务，8002 走的是单 worker）
-
-# 4) 8002 进程能看到 ai_writing 持久化日志
-docker logs deerflow-gateway 2>&1 | grep 'AsyncSqliteSaver'
-# 期望至少 1 行：ai_writing: 使用 AsyncSqliteSaver (...)
-
-# 5) /api/ai-writing/* 走 8002，其他走 8001
-curl -sI http://deerflow.example.com/api/ai-writing/health   # 看 nginx access log 落到 gateway_aiwriting
-curl -sI http://deerflow.example.com/api/models              # 看落到 gateway_main
-
-# 6) 真跑一次 AI 写作，确认全程没有「resume 404 / 进度断流」
-```
-
-### 步骤 8：监控两个进程的健康
-
-supervisord 自带 `unix_http_server` + `supervisorctl`，但对容器化场景更直接的是看 docker logs：
-
-```bash
-# 实时看两个进程的日志
-docker logs -f deerflow-gateway 2>&1 | grep -E '(gateway-main|gateway-aiwriting)'
-
-# 进程级状态
-docker exec deerflow-gateway supervisorctl -c /etc/supervisor/conf.d/deerflow.conf status
-# 期望：
-#   gateway-main         RUNNING   pid 7,  uptime 0:05:12
-#   gateway-aiwriting    RUNNING   pid 18, uptime 0:05:12
-
-# 单独重启 AI 写作进程（不影响主业务，前端只是 AI 写作页几秒不可用）
-docker exec deerflow-gateway supervisorctl -c /etc/supervisor/conf.d/deerflow.conf restart gateway-aiwriting
-```
-
-### 资源开销（实测预估）
-
-| 项 | 单 worker 镜像 | 双进程镜像 | 增量 |
-|---|---|---|---|
-| 镜像大小 | 基线 | +约 5 MB | supervisord 依赖 |
-| 启动时 RSS | ~250 MB | ~450 MB | 多一份 Python runtime + 模型客户端预加载 |
-| 稳态 RSS | 视业务而定 | +约 200 MB | 第二个 worker 的常驻内存 |
-| CPU | 不变 | 不变 | 单 worker 进程空闲基本不占 CPU |
-
-**结论**：内存额外占用约 200 MB，对 4 GB 以上的部署机基本无压力。
-
-### 常见坑位
-
-1. **`stop_grace_period` 没改大 → 重启时 in-flight 写作被秒杀**
-   表现：每次 `docker compose restart` 都有用户报告「写到一半没了」。修复见步骤 6。
-
-2. **8002 没暴露 / nginx 没改 → 所有请求还是落 8001**
-   表现：症状跟没做方案 C 一样。验证步骤 5 的 curl 即可发现。
-
-3. **两路用了不同的 `config.yaml`**
-   表现：8001 跟 8002 行为不一致。务必让两个进程**只读同一个文件**（在 compose 里只挂一次卷）。
-
-4. **`.deer-flow` 卷没挂 → 8002 重启后会话全丢**
-   表现：用户刷新页面，AI 写作历史空白。修复：步骤 4 的 `-v` 必须有。
-
-5. **AI 写作进程崩溃后 supervisord 反复重启 → 日志爆炸**
-   表现：`gateway-aiwriting` 状态在 RUNNING/EXITED/BACKOFF 间反复。
-   修复：先 `supervisorctl tail gateway-aiwriting stderr` 看真正原因（多半是 sqlite 权限或配置文件路径），再修，**别盲目调 `autorestart=false`**。
-
-6. **想做 K8s 部署但还想用方案 C**
-   不要把两个进程塞一个 Pod，应该直接拆成两个 Deployment、共享 PVC（checkpoints.db）。这种情况下方案 C 已经变形成方案 F 的子集，建议直接走方案 F。
-
-### 回滚方案
-
-如果上线后发现问题，回滚只需要 1 步：
-
-```bash
-# 把 Dockerfile 最后一行换回原来的 CMD，重新 build + 重启
-CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
-```
-
-数据完全兼容（checkpoints.db、MySQL 表结构都跟单进程模式一致），**不会丢任何用户数据**，只是回到「resume 偶发 404、SSE 断断续续」的旧体验。
-
----
-
-## 七、运维操作清单
-
-### 部署前验证
-
-```bash
-# 1) 确认 .deer-flow 数据卷挂出来了（持久化的命脉）
-docker exec <gateway> ls -la /app/.deer-flow/data/
-# 应该能看到 checkpoints.db 文件（首次启动后会自动创建）
-
-# 2) 确认 alembic 迁移跑完了
-docker exec <gateway> sh -c "cd /app/backend && PYTHONPATH=. uv run alembic current"
-# 应该看到包含 20260519_02 的 head
-
-# 3) 确认 transcript 列已扩容
-docker exec <mysql> mysql -uroot -p<pwd> deerflow -e \
-  "SHOW COLUMNS FROM ai_writing_sessions LIKE 'transcript';"
-# Type 列应该是 longtext
-
-# 4) 查 worker 数
-docker exec <gateway> ps -ef | grep -E 'uvicorn|gunicorn'
-# 如果 > 1，且没做任何方案 C/F/B，启动日志会打 ERROR 警告
-```
-
-### 启动时关注的日志
-
-```bash
-docker logs <gateway> 2>&1 | head -100 | grep -iE 'ai_writing|checkpointer|worker'
-```
-
-期望看到：
-- `ai_writing: 使用 AsyncSqliteSaver (xxx.db)` — 持久化生效
-- `ai_writing_cleanup: 已启动 cron=...` — 清理任务起来了
-
-警告：
-- `⚠ 检测到 WEB_CONCURRENCY=N` — 多 worker 配置警告
-- `ai_writing: 持久化 checkpointer 不可用，退回 InMemorySaver` — sqlite 初始化失败，需立刻排查
-
-### 用户报告「会话丢失」时的排查
-
-```bash
-# 1) 查 sqlite 里这个 session 的快照
-docker exec <gateway> sh -c "sqlite3 /app/.deer-flow/data/checkpoints.db \
-  \"SELECT thread_id, checkpoint_ns FROM checkpoints WHERE thread_id='<session_id>' LIMIT 5;\""
-
-# 2) 查 MySQL 里这条会话
-docker exec <mysql> mysql -uroot -p<pwd> deerflow -e \
-  "SELECT id, status, draft_title, updated_at FROM ai_writing_sessions WHERE id='<session_id>';"
-
-# 3) 看 gateway 日志里这个 session 的活动轨迹
-docker logs <gateway> 2>&1 | grep '<session_id>' | tail -50
-
-# 4) 看是否有 recover_session 调用
-docker logs <gateway> 2>&1 | grep 'ai_writing: recovered' | tail -20
-
-# 5) 看是否有节点异常
-docker logs <gateway> 2>&1 | grep -E 'ai_writing graph segment failed|ai_writing.*error' | tail -20
-```
-
-### 手动触发清理（admin only）
-
-```bash
-# 用 admin 账号登录后，取 cookie，调清理接口
-curl -X POST 'http://<gateway>/api/ai-writing/admin/cleanup' \
-  -H 'Content-Type: application/json' \
-  -H 'Cookie: <admin session cookie>' \
-  -d '{"retention_days": 7}'
-```
-
-返回：
-```json
-{
-  "deleted_db": 12,
-  "deleted_checkpoints": 12,
-  "skipped_active": 1,
-  "elapsed_seconds": 0.234,
-  "params": { "retention_days": 7, "only_finished": false, "batch_size": 500 }
-}
-```
-
-`skipped_active` > 0 表示有正在跑的会话被活跃保护拦下来，不会被误删。
-
----
-
-## 八、相关文件索引
-
-### 后端
-- `offline-backend-20260512/backend/app/gateway/routers/ai_writing.py` — 路由 + 内存状态字典 + drain
-- `offline-backend-20260512/backend/app/gateway/ai_writing_cleanup.py` — 定期清理
-- `offline-backend-20260512/backend/app/gateway/app.py` — lifespan / 多 worker 检测
-- `offline-backend-20260512/backend/packages/harness/deerflow/agents/ai_writing/graph.py` — Graph 定义 + 持久化 checkpointer
-- `offline-backend-20260512/backend/packages/harness/deerflow/persistence/ai_writing_sessions/` — MySQL repo
-- `offline-backend-20260512/backend/packages/harness/deerflow/persistence/types.py` — `PortableLongText`
-- `offline-backend-20260512/backend/packages/harness/deerflow/persistence/migrations/versions/20260519_02_*.py` — LONGTEXT 迁移
-- `offline-backend-20260512/config.yaml` — `checkpointer:` + `ai_writing.cleanup:` 配置
-
-### 前端
-- `frontend-web/src/open-canvas/pages/AIWritingPage.tsx` — 页面顶部有快速排查注释
-- `frontend-web/src/open-canvas/api/ai-writing-sessions.ts` — transcript 保存（已做 fire-and-forget 容错）
-- `frontend-web/src/open-canvas/api/ai-writing.ts` — resume / stream
-
-### 测试
-- `tests/test_ai_writing_cleanup.py` — 清理 + drain + checkpointer 降级 + SSE 序列化（21 个测试）
-- `tests/test_ai_writing_session_recovery.py` — 跨 worker 会话恢复（8 个测试）
-- `tests/test_ai_writing_session_repo.py` — Repo（7 个测试）
-- `tests/test_ai_writing_transcript_endpoint.py` — transcript 兜底（5 个测试）
-- `tests/test_portable_long_text.py` — LONGTEXT 列类型（5 个测试）
-
-总测试：**51 个，全过**。
-
----
-
-## 九、变更历史
-
-| 日期 | Commit | 内容 |
-|---|---|---|
-| 2026-05-19 | c3d0c82 | 报错兜底（transcript LONGTEXT 迁移 + 路由 try/except + session 恢复） |
-| 2026-05-20 | （本次） | checkpointer 持久化 + 定期清理 + admin 接口 + 多层兜底 + drain + 多 worker 检测 |
-
----
-
-## 十、决策摘要（给未来的你/同事）
-
-> **如果你现在第一次接手这个问题**，按这个清单往下走：
->
-> 1. ✅ **transcript 500 不用管** — 已彻底修复
-> 2. ⚠️ **resume 报错的根因是多 worker** — sqlite 持久化已减轻，但 SSE 事件流仍隔离
-> 3. ⚠️ **写作能跑完，但用户体验断断续续** — 草稿数据安全，刷新就能看到
-> 4. 🎯 **要彻底解决，从方案 C / F / B 选一个**（建议从 C 开始）
-> 5. 🚨 **务必确认 `.deer-flow` 数据卷挂出来了** — 否则 sqlite 持久化白做
-> 6. 📊 **关注的日志关键字**：`ai_writing:`、`checkpointer`、`AsyncSqliteSaver`、`WEB_CONCURRENCY`
-
-如有疑问，先看本文件的「七、运维操作清单」做基础排查，再问当前维护者。

frontend-web/docs/embed-iframe-chat.md

@@ -0,0 +1,436 @@
+# 工作台问答 · iframe 嵌入开发说明
+
+本文档说明如何将 DeerFlow **通用工作台问答**（与 `/page/workspace/chats/*` 同一套 LangGraph 流式能力）以**普通 iframe** 形式嵌入第三方页面，并在**父页面无法读取子 frame 内 `thread_id`** 的前提下，轮询「本次问答是否已结束」。
+
+后端公开 API 实现见：`offline-backend-20260512/backend/app/gateway/routers/public_embed.py`  
+数据表：`embed_sessions`（迁移 `20260602_01`）
+
+---
+
+## 0. 速读
+
+| 角色 | 要做的事 |
+|------|----------|
+| **父页面** | 自己生成 `sessionId`（UUID），拼进 iframe `src`；用 `sessionId` 调公开 API 轮询 `finished` |
+| **iframe（DeerFlow）** | 打开 `/embed/chats/...`，自动登录、自动发问、登记 `sessionId → thread_id` |
+| **不需要** | 无界（wujie）、父页面拿 `thread_id`、DeerFlow 登录态 Cookie |
+
+**完成条件**：`GET .../sessions/{sessionId}/status` 返回 `finished === true`（且无进行中的 run，非澄清中断）。
+
+---
+
+## 1. 背景与约束
+
+### 1.1 业务目标
+
+- 第三方系统用 **iframe** 嵌 DeerFlow 问答 UI。
+- 传入：**问题文案**、**用户名**（走现有 `login/username`）、**主题色**。
+- 展示：**消息列表** + **沙箱/产物侧栏**（与主聊天相同的 `ChatBox`）；**隐藏**页面左侧栏、Workspace 侧栏、底部输入框。
+- 进入后 **自动发送** 首条用户消息并走流式问答。
+
+### 1.2 为何需要 `sessionId`
+
+iframe 与父页面通常 **跨域**，父页面 **不能** 读取子应用 URL 里的 `thread_id`（hash 路由在子 frame 内）。  
+因此约定：
+
+1. **父页面**在打开 iframe 前生成全局唯一的 `sessionId`；
+2. **子页面**在创建/确定 `thread_id` 后，调用后端 **登记接口** 写入 `session_id → thread_id`；
+3. **父页面**只凭 `sessionId` 查询状态，必要时响应里会带上 `thread_id`（可选使用）。
+
+---
+
+## 2. 端到端流程
+
+```mermaid
+sequenceDiagram
+  participant Parent as 父页面
+  participant Iframe as DeerFlow iframe
+  participant API as Gateway /api/public/embed
+
+  Parent->>Parent: sessionId = crypto.randomUUID()
+  Parent->>Iframe: iframe src 含 sessionId、message、username、theme
+  Iframe->>Iframe: loginByUsername + 自动 sendMessage
+  Iframe->>API: POST /sessions { session_id, thread_id }
+  loop 每 1–3s
+    Parent->>API: GET /sessions/{sessionId}/status
+    API-->>Parent: registered, finished, thread_id
+  end
+```
+
+---
+
+## 3. 前端路由与页面
+
+### 3.1 路由（独立于 `/page/*`）
+
+在 `App.tsx` 注册，**不经过** `PageRoutes` / `PageSidebar`，因此无外层导航与 Workspace 侧栏。
+
+| 路由 | 组件 | 说明 |
+|------|------|------|
+| `/embed/chats/:thread_id` | `EmbedChatPage`（外包 `ChatRuntime`） | `thread_id` 可为 `new` 或已有 UUID |
+
+示例（HashRouter，注意 `#`）：
+
+```
+http://localhost:5173/#/embed/chats/new?sessionId=...&message=...&username=guest&theme=red
+```
+
+开发环境端口以本地 Vite 为准（如 5173 / 5174）。
+
+### 3.2 URL 查询参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `sessionId` 或 `session_id` | **是** | 父页面生成的关联 id，8–128 位，仅字母数字 `_` `-` |
+| `message` / `question` / `text` | 建议 | 首条用户问题；有则进入后自动发送 |
+| `username` / `userName` | 否 | 默认 `guest`，对应 `POST /api/v1/auth/login/username` |
+| `theme` | 否 | `dark-blue` → 深色；`red` 等 → 浅色（与 `LoginPage` 一致） |
+
+缺少 `sessionId` 时，嵌入页会提示错误，不会发起登记。
+
+### 3.3 相关源码
+
+| 路径 | 职责 |
+|------|------|
+| [src/pages/EmbedChatPage.tsx](../src/pages/EmbedChatPage.tsx) | 嵌入页：登录、自动发问、登记 session、仅消息列表 + ChatBox |
+| [src/core/embed/params.ts](../src/core/embed/params.ts) | 从 URL 解析嵌入参数 |
+| [src/core/embed/status-api.ts](../src/core/embed/status-api.ts) | 登记 / 轮询 API 封装 |
+| [src/App.tsx](../src/App.tsx) | 路由注册 |
+
+### 3.4 UI 行为说明
+
+- **隐藏**：`PageSidebar`、`WorkspaceSidebar`、`InputBox`、顶栏标题栏等（相对完整 `ChatPage`）。
+- **保留**：`MessageList`、流式指示、澄清卡片（若 agent 触发 `ask_clarification`）、右侧 **产物/沙箱**（`ChatBox` 内 60/40 分栏逻辑与主聊天一致）。
+- **线程 id**：新建会话时客户端先分配 UUID，`onStart` 后 `history.replaceState` 更新 hash 为 `/embed/chats/{真实id}`（与主聊天 `ChatPage` 相同手法，避免整页重载）。
+
+---
+
+## 4. 公开 HTTP API（无需鉴权）
+
+前缀：`/api/public/embed/`（走 Gateway，与 `VITE_BACKEND_BASE_URL` 一致，默认 `http://127.0.0.1:8001`）。
+
+CSRF / Auth 中间件对 `/api/public/` 放行；请求 **不需要** Cookie。
+
+### 4.1 登记映射（iframe 内自动调用）
+
+```http
+POST /api/public/embed/sessions
+Content-Type: application/json
+
+{
+  "session_id": "parent-generated-uuid",
+  "thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b"
+}
+```
+
+**响应：**
+
+```json
+{
+  "session_id": "parent-generated-uuid",
+  "thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b",
+  "registered": true
+}
+```
+
+同一 `session_id` 再次 POST 会 **更新** `thread_id`（例如 `onStart` 后 id 变化）。
+
+### 4.2 轮询状态（父页面使用）
+
+```http
+GET /api/public/embed/sessions/{session_id}/status
+```
+
+**尚未登记**（iframe 仍在加载或未 POST）：
+
+```json
+{
+  "session_id": "parent-generated-uuid",
+  "registered": false,
+  "thread_id": null,
+  "finished": false,
+  "thread_status": "pending",
+  "has_active_run": false,
+  "latest_run_status": null
+}
+```
+
+**已登记且问答进行中：**
+
+```json
+{
+  "session_id": "parent-generated-uuid",
+  "registered": true,
+  "thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b",
+  "finished": false,
+  "thread_status": "idle",
+  "has_active_run": true,
+  "latest_run_status": "running"
+}
+```
+
+**已登记且已结束：**
+
+```json
+{
+  "session_id": "parent-generated-uuid",
+  "registered": true,
+  "thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b",
+  "finished": true,
+  "thread_status": "idle",
+  "has_active_run": false,
+  "latest_run_status": "success"
+}
+```
+
+#### 字段说明
+
+| 字段 | 含义 |
+|------|------|
+| `registered` | 是否已收到 iframe 的 POST 登记 |
+| `finished` | **父页面应以此为准**：无 inflight run，且线程非 running/busy，且非 `interrupted`（澄清等待用户） |
+| `thread_status` | 从 checkpoint 推导：`idle` / `interrupted` / `error` 等 |
+| `has_active_run` | 是否存在 pending/running 的 LangGraph run |
+| `latest_run_status` | 该线程最近一次 run 的状态：`success` / `error` / … |
+| `thread_id` | 解析出的 DeerFlow 线程 id（父页面可选用，非必须） |
+
+### 4.3 获取生成结果（父页面使用）
+
+问答结束后（建议先确认 `finished === true`），拉取本次模型输出：
+
+```http
+GET /api/public/embed/sessions/{session_id}/result
+```
+
+**尚未登记：**
+
+```json
+{
+  "session_id": "parent-generated-uuid",
+  "registered": false,
+  "thread_id": null,
+  "finished": false,
+  "thread_status": "pending",
+  "has_active_run": false,
+  "latest_run_status": null,
+  "messages": [],
+  "generated_text": "",
+  "generated_files": []
+}
+```
+
+**已登记且已有内容：**
+
+```json
+{
+  "session_id": "parent-generated-uuid",
+  "registered": true,
+  "thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b",
+  "finished": true,
+  "thread_status": "idle",
+  "has_active_run": false,
+  "latest_run_status": "success",
+  "messages": [
+    { "type": "human", "content": "请总结要点", "id": "..." },
+    { "type": "ai", "content": "根据分析，要点如下：...", "id": "..." }
+  ],
+  "generated_text": "根据分析，要点如下：...",
+  "generated_files": [
+    "/mnt/user-data/outputs/summary.md",
+    "/mnt/user-data/outputs/chart.png"
+  ]
+}
+```
+
+#### 结果字段说明
+
+| 字段 | 含义 |
+|------|------|
+| `messages` | 完整消息列表（与 checkpoint 中序列化结构一致，含 human / ai / tool 等） |
+| `generated_text` | 所有 `ai` / `assistant` 消息正文按顺序拼接（段落间空一行） |
+| `generated_files` | 本次会话产物的虚拟路径列表（与 UI 产物栏 `artifacts` 一致） |
+
+未结束时也可调用，会返回当前已有内容；`finished` 仍为 false 表示可能还会继续生成。
+
+### 4.4 按 thread_id 查询（可选）
+
+调试或父页面已持有 thread_id 时：
+
+```http
+GET /api/public/embed/threads/{thread_id}/status
+GET /api/public/embed/threads/{thread_id}/result
+```
+
+状态接口响应不含 `messages` / `generated_text` / `generated_files`；结果接口字段与 §4.3 相同（无 `session_id` / `registered`）。
+
+### 4.5 前端封装
+
+```ts
+import {
+  getEmbedSessionResult,
+  getEmbedSessionStatus,
+  registerEmbedSession,
+} from "@/core/embed/status-api";
+
+// 父页面（或你们自己的脚本）
+const status = await getEmbedSessionStatus(sessionId);
+if (status.registered && status.finished) {
+  const result = await getEmbedSessionResult(sessionId);
+  console.log(result.generated_text, result.generated_files);
+}
+
+// 仅 iframe 内需要
+await registerEmbedSession(sessionId, threadId);
+```
+
+`fetch` 使用 `credentials: "omit"`，不携带 DeerFlow 会话。
+
+---
+
+## 5. 父页面集成示例
+
+### 5.1 拼接 iframe
+
+```html
+<iframe
+  id="deerflow-embed"
+  title="DeerFlow 问答"
+  style="width:100%;height:600px;border:0"
+></iframe>
+```
+
+```javascript
+const sessionId = crypto.randomUUID();
+const base = "http://localhost:5173"; // 换成你们部署的前端 origin
+const params = new URLSearchParams({
+  sessionId,
+  message: "请根据附件总结要点",
+  username: "guest",
+  theme: "red",
+});
+document.getElementById("deerflow-embed").src =
+  `${base}/#/embed/chats/new?${params.toString()}`;
+```
+
+### 5.2 轮询直到结束
+
+```javascript
+const API = "http://127.0.0.1:8001"; // VITE_BACKEND_BASE_URL
+
+async function pollUntilFinished(sessionId) {
+  const res = await fetch(
+    `${API}/api/public/embed/sessions/${encodeURIComponent(sessionId)}/status`,
+    { credentials: "omit" },
+  );
+  if (!res.ok) throw new Error(`status HTTP ${res.status}`);
+  const data = await res.json();
+  if (!data.registered) return { done: false, reason: "pending" };
+  if (data.finished) return { done: true, data };
+  return { done: false, reason: "running" };
+}
+
+const timer = setInterval(async () => {
+  try {
+    const poll = await pollUntilFinished(sessionId);
+    if (poll.done) {
+      clearInterval(timer);
+      const output = await fetch(
+        `${API}/api/public/embed/sessions/${encodeURIComponent(sessionId)}/result`,
+        { credentials: "omit" },
+      ).then((r) => r.json());
+      console.log("问答已结束", output.generated_text, output.generated_files);
+    }
+  } catch (e) {
+    console.error(e);
+  }
+}, 2000);
+```
+
+### 5.3 跨域注意
+
+父页面从浏览器 `fetch` Gateway（如 `http://127.0.0.1:8001`）时，**Origin 必须是后端 CORS 白名单里的完整地址**（含协议、主机、端口），与 API 地址是否写 `localhost` / `127.0.0.1` 无关。
+
+**本地开发**（前端默认 `5174`）请在 Gateway 环境变量中配置：
+
+```bash
+# offline-backend-20260512/.env 或启动脚本注入
+GATEWAY_CORS_ORIGINS=http://localhost:5174,http://127.0.0.1:5174,http://localhost:5173,http://127.0.0.1:5173
+```
+
+修改后**重启 Gateway**（`make dev` / `make gateway`）。若父页面部署在其它域名，把该域名的 origin 一并加入逗号分隔列表。
+
+临时调试（勿用于公网生产）：
+
+```bash
+GATEWAY_CORS_ALLOW_ALL=1
+```
+
+常见报错：`No 'Access-Control-Allow-Origin' header` → 当前页面的 origin 未出现在 `GATEWAY_CORS_ORIGINS` 中。
+
+### 5.4 其它部署注意
+
+---
+
+## 6. 部署与数据库
+
+1. **跑迁移**（SQL 持久化后端）：
+
+   ```bash
+   cd offline-backend-20260512/backend
+   # 按项目惯例执行 alembic upgrade head
+   ```
+
+   表：`embed_sessions(session_id PK, thread_id, created_at, updated_at)`。
+
+2. **重启 Gateway**，确认路由已挂载：`public_embed.router`（`app/gateway/app.py`）。
+
+3. **前端构建** 后，将嵌入地址配给第三方；`VITE_BACKEND_BASE_URL` 指向可达的 Gateway。
+
+无 SQL 时开发环境会退化为 **内存** `MemoryEmbedSessionStore`（进程重启后映射丢失）；生产请使用持久化库。
+
+---
+
+## 7. 安全说明
+
+- `sessionId` 与 `thread_id` 均视为 **不透明能力令牌**：知晓即可查询状态（公开 API **无登录**）。
+- 建议：父系统自行生成不可猜测的 UUID；敏感场景在贵司 API 网关再加鉴权或 IP 限制。
+- 登记接口为 **POST upsert**，不校验「session 是否属于某租户」——若需多租户隔离，请在业务层约定 `sessionId` 命名空间或增加网关校验。
+
+---
+
+## 8. 与主聊天 `/page/workspace/chats` 的差异
+
+| 项目 | 主聊天 | iframe 嵌入 |
+|------|--------|-------------|
+| 路由 | `/page/workspace/chats/:id` | `/embed/chats/:id` |
+| 布局 | 完整 Workspace + 输入框 | 仅消息区 + 产物栏 |
+| 登录 | 常规登录流 | URL `username` 自动 `login/username` |
+| 首条消息 | 用户输入 | URL `message` 自动发送 |
+| 完成态查询 | 无公开 API | `sessionId` + `/api/public/embed/sessions/.../status` |
+
+能力上仍走同一 `useThreadStream` + `lead_agent` 流式链路，沙箱与产物行为与主聊天一致。
+
+---
+
+## 9. 常见问题
+
+**Q：`registered` 一直为 false？**  
+A：检查 iframe URL 是否带 `sessionId`；子页是否登录成功；Network 里是否有 `POST /api/public/embed/sessions` 且 200。
+
+**Q：`finished` 一直 false？**  
+A：可能仍在流式生成（`has_active_run: true`），或 agent 进入澄清（`thread_status: interrupted`）。嵌入模式无底部输入框，澄清需产品侧另行处理或避免触发澄清类工具。
+
+**Q：父页面能否不用轮询？**  
+A：当前标准方案为公开 GET 轮询。若同源可考虑 `postMessage` 扩展（未默认实现）。
+
+**Q：能否继续用已有 thread_id 嵌入？**  
+A：可以：`#/embed/chats/{thread_id}?sessionId=...`，可选再带 `message` 追加一轮；登记会在已知 id 上 upsert。
+
+---
+
+## 10. 变更记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-06-02 | 初版：iframe 嵌入路由、`sessionId` 映射表、公开登记与状态 API |
+| 2026-06-02 | 新增 `GET /sessions/{session_id}/result`：返回 messages、generated_text、generated_files |

frontend-web/docs/hebing.md

@@ -1,140 +0,0 @@
-# App.tsx 路由与页面结构重构需求（首页与业务页分离）
-
-## 一、需求背景
-
-当前 `frontend-web/src/App.tsx` 同时承载了：
-
-1. 登录/首页相关路由（如 `/login`、`/landing`）
-2. 工作台业务相关路由（如 `/workspace/chats`、`/workspace/agents`、`/workspace/scheduled/*`）
-3. 业务页所需布局与运行时包装（`WorkspaceLayout`、`ChatRuntime`）
-
-这会导致 `App.tsx` 过重，职责不够单一，不利于后续维护和扩展。
-
----
-
-## 二、目标（你提出的核心诉求）
-
-你希望：
-
-1. **除了登录与首页入口内容外**，将 `App.tsx` 中其余业务页面路由整体迁移到 `pages` 下一个新组件中。
-2. 再创建一个“承接导航/入口”的页面（或路由容器），用于放置这些导航逻辑。
-3. `App.tsx` 最终只保留顶层路由分发和基础 Provider，变得更薄。
-
-> 你提到“`App.tsx 74-75 login`”，可理解为：保留登录/首页相关入口，其他工作台内容抽离。
-
----
-
-## 三、重构范围
-
-### 1）保留在 `App.tsx` 的内容
-
-- 全局 Provider：`HashRouter`、`AppProviders`
-- 登录/首页路由：
-  - `/`
-  - `/login`
-  - `/login/:username`
-  - `/landing`
-- 404 路由（可留在 `App.tsx` 或交给新路由容器统一处理，二选一）
-
-### 2）迁移出 `App.tsx` 的内容
-
-将以下与工作台有关的路由从 `App.tsx` 抽离：
-
-- `/workspace`（重定向）
-- `/workspace/chats`
-- `/workspace/chats/:thread_id`
-- `/workspace/agents`
-- `/workspace/agents/new`
-- `/workspace/agents/:agent_id/chats`（重定向）
-- `/workspace/agents/:agent_id/chats/:thread_id`
-- `/workspace/scheduled`
-- `/workspace/scheduled/tasks`
-- `/workspace/scheduled/runs/:run_id`
-
-以及配套的包装组件职责：
-
-- `WorkspaceLayout`
-- `ChatRuntime`
-
----
-
-## 四、建议的新结构（方案）
-
-## 方案 A（推荐）：新增“业务路由容器组件”
-
-在 `pages` 下新增一个路由容器组件，例如：
-
-- `src/pages/WorkspaceRoutes.tsx`（或 `src/pages/AppWorkspaceRoutes.tsx`）
-
-职责：
-- 专门维护 `/workspace/*` 相关路由
-- 内部统一使用 `WorkspaceLayout` 与 `ChatRuntime`
-- 输出一个可被 `App.tsx` 挂载的路由节点
-
-同时在 `App.tsx` 里只保留：
-- 登录/首页/404
-- 一个 `Route path="/workspace/*" element={<WorkspaceRoutes />} />`
-
----
-
-## 五、“再建立一个页面放置导航”的落地解释
-
-你说的“建立一个页面放置这些导航”，可以有两种理解：
-
-1. **路由容器页（推荐）**：
-   - 不强调视觉 UI，重点是集中管理导航与路由跳转规则。
-   - 即上面的 `WorkspaceRoutes.tsx`。
-
-2. **可见的导航页（可选）**：
-   - 例如新建 `WorkspaceHomePage.tsx`，展示聊天/Agents/定时任务入口按钮。
-   - 路由上把 `/workspace` 指向该页，而不是直接重定向到 `/workspace/chats/new`。
-
-当前从你的描述看，优先建议第 1 种（先做结构整理），之后若有产品需求再做第 2 种可见导航页。
-
----
-
-## 六、实施步骤（开发任务拆解）
-
-1. 新建 `WorkspaceRoutes` 组件（`pages` 目录下）。
-2. 把所有 `/workspace/*` 路由从 `App.tsx` 搬入该组件。
-3. 把 `WorkspaceLayout` 与 `ChatRuntime` 移入该组件（或抽到共享 layout/runtime 文件）。
-4. 在 `App.tsx` 中保留登录/首页路由，并挂载 `/workspace/*` 到新组件。
-5. 校验以下访问路径行为一致：
-   - `/workspace` 重定向
-   - chats/agents/scheduled 各页面可正常进入
-   - 动态参数路由（`thread_id`、`agent_id`、`run_id`）正常
-   - 404 不受影响
-6. 运行前端并做手工回归。
-
----
-
-## 七、验收标准
-
-1. `App.tsx` 明显瘦身，主要负责顶层入口路由。
-2. `/workspace/*` 全部由新建组件统一管理。
-3. 功能行为与改造前一致（或符合新定义）。
-4. 代码可读性提升：登录入口与业务入口职责分离。
-
----
-
-## 八、注意事项
-
-1. 当前项目使用 `HashRouter`，路由写法需保持兼容。
-2. `Navigate` 重定向逻辑要完整迁移，避免出现死循环或空白页。
-3. `WorkspaceLayout` 与 `ChatRuntime` 的包裹层级不能错，否则可能影响侧边栏、输入区、子任务/Artifacts 状态。
-4. 若后续再加模块（例如 `/workspace/settings`），优先在 `WorkspaceRoutes` 中扩展。
-
----
-
-## 九、建议的命名（可直接采用）
-
-- 新增组件文件：`src/pages/WorkspaceRoutes.tsx`
-- （可选）可见导航页：`src/pages/WorkspaceHomePage.tsx`
-
----
-
-## 十、后续可选优化
-
-1. 将 `WorkspaceLayout` 抽到 `src/layouts/WorkspaceLayout.tsx`。
-2. 将 `ChatRuntime` 抽到 `src/runtime/ChatRuntime.tsx`。
-3. 把路由常量集中到 `src/core/router/paths.ts`，减少硬编码路径。

frontend-web/docs/multi-agent-api.md

@@ -0,0 +1,265 @@
+# 多智能体协调 API 接口文档
+
+后端路由：`offline-backend-20260512/backend/app/gateway/routers/multi_agent.py`
+路由前缀：`/api/multi-agent`
+
+## 概览
+
+提供一个"总控 + 多个子智能体"的协调编排接口。
+
+- **总控（leader）** 智能体：通过 `agent_orchestration` 技能给子智能体派活
+- **子智能体（special）**：执行被派到的具体任务，完成后把交付内容广播给其他线程
+
+调用方按下面顺序使用：
+
+1. 调 `POST /api/multi-agent/init` 一次性创建协调智能体 + 给每个子智能体建 `thread`，拿到 `thread_ids` 映射
+2. 客户端把 `thread_ids` 保管好，后续每次调 `POST /api/multi-agent/run/stream` 时回传
+3. 先调用 `agent_type="leader"` 拿派活清单，再针对清单里每个子智能体调用 `agent_type="special"`
+
+
+## 1. 初始化多智能体集群
+
+### `POST /api/multi-agent/init`
+
+创建协调智能体并为列表中的每个子智能体建立独立的 `thread`，同时把"职责说明"广播到所有子智能体线程作为初始上下文。
+
+#### 请求体
+
+```json
+{
+  "agent_names": ["taiwan-intelligence-gathering-agent", "us-intelligence-gathering-agent"],
+  "main_agent_name": "main-controller",
+  "model": "deepseek-chat"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `agent_names` | `string[]` | 是 | 已有子智能体的 id 列表（kebab-case，区分大小写不敏感，自动转小写） |
+| `main_agent_name` | `string` | 否 | 要创建的协调智能体名，默认 `main-agent`。重名时会复用已存在的同名智能体 |
+| `model` | `string` | 否 | 协调智能体使用的模型名。不传则用后端默认模型 |
+
+#### 响应（200）
+
+```json
+{
+  "status": "success",
+  "main_agent_name": "main-controller",
+  "thread_ids": {
+    "main-controller": "thread-uuid-xxx",
+    "taiwan-intelligence-gathering-agent": "thread-uuid-yyy",
+    "us-intelligence-gathering-agent": "thread-uuid-zzz"
+  }
+}
+```
+
+`thread_ids` 是一个 `{agent_name: thread_id}` 字典。**前端必须把这个对象完整保管下来**，后续调用 stream 接口需要原样回传。
+
+#### 错误
+
+| 状态码 | 触发条件 |
+|---|---|
+| `400` | `agent_names` 为空 |
+| `401` | 未携带 `Authorization` 头 |
+| `500` | 协调智能体创建失败且不是"已存在"错误 |
+
+---
+
+## 2. 流式调度
+
+### `POST /api/multi-agent/run/stream`
+
+通过 SSE（Server-Sent Events）流式驱动一个 leader 或 special 智能体跑一轮对话。
+
+#### 请求体
+
+```json
+{
+  "agent_type": "leader",
+  "d_agent_thread_id": {
+    "main-controller": "thread-uuid-xxx",
+    "taiwan-intelligence-gathering-agent": "thread-uuid-yyy"
+  },
+  "agent_name": "main-controller",
+  "new_message": "请分析特朗普的支持率",
+  "skill_stop_names": [],
+  "model": "deepseek-chat"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `agent_type` | `"leader"` \| `"special"` | 否 | 默认 `leader`。`leader` 调用协调智能体，`special` 调用子智能体 |
+| `d_agent_thread_id` | `object` | 是 | 由 `/init` 接口返回的 `thread_ids` 映射，原样回传 |
+| `agent_name` | `string` | 是 | 本轮要驱动的智能体名（必须存在于 `d_agent_thread_id` 中） |
+| `new_message` | `string` | 是 | 这轮发给智能体的用户消息 |
+| `skill_stop_names` | `string[]` | 否 | 触发后中断执行的技能名列表（默认空） |
+| `model` | `string` | 否 | 本轮 LLM 模型名，默认 `deepseek-chat` |
+
+#### 响应
+
+`Content-Type: text/event-stream` 的 SSE 长连接，按到达顺序产出多种数据：
+
+##### a. 透传上游事件
+
+原样转发底层 `POST /api/threads/{thread_id}/runs/stream` 的事件帧（LangGraph 协议），包含 `event:`、`data:` 等行。前端按 LangGraph SDK 既有方式渲染即可。
+
+##### b. 最后一帧：调度状态
+
+流结束前会额外产出一帧 `data:` 行，结构因 `agent_type` 而异：
+
+**`agent_type == "leader"`：**
+
+```
+data: {"status": [["us-intelligence-gathering-agent", "收集美国民众对特朗普的看法"], ["taiwan-intelligence-gathering-agent", "..."]]}
+```
+
+`status` 是一个 `[agent_name, task_text]` 二元组数组，代表协调智能体本轮派出去的任务清单。**前端拿到后应当对每个元素再调用一次本接口（`agent_type="special"`）来执行子智能体**。如果数组为空，说明 leader 觉得已有信息足够，不再派活，可以直接展示 leader 的最终文本回答。
+
+**`agent_type == "special"`：**
+
+```
+data: {"status": "子智能体xxx完成yyy工作"}
+```
+
+代表子智能体完成本轮工作并已把交付内容广播给其他线程。
+
+#### 副作用（重要）
+
+- **leader 调用**：自动把"总控智能体收到用户消息: …"广播到所有非自己的线程；派活后再把"总控智能体给 X 派活, 内容为: …"广播到所有非派活双方的线程
+- **special 调用**：完成后把"子智能体 X 完成 Y 工作, 交付内容为: …"广播到所有非自己的线程
+
+这意味着每个线程的对话历史里会逐步累积出全局上下文，无需前端再做合并。
+
+#### 错误
+
+| 状态码 | 触发条件 |
+|---|---|
+| `400` | `agent_name` 缺失或未在 `d_agent_thread_id` 中 |
+| `401` | 未携带 `Authorization` 头 |
+| `502` | 上游 `runs/stream` 返回非 200 / SSE 解析失败 |
+
+---
+
+## 3. 前端调用流程示例
+
+```ts
+// 1. 拿 token
+const loginResp = await fetch("/api/v1/auth/login/username", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ username: "yourname" }),
+});
+const { access_token } = await loginResp.json();
+const authHeaders = {
+  Authorization: `Bearer ${access_token}`,
+  "Content-Type": "application/json",
+};
+
+// 2. 初始化
+const initResp = await fetch("/api/multi-agent/init", {
+  method: "POST",
+  headers: authHeaders,
+  body: JSON.stringify({
+    agent_names: [
+      "taiwan-intelligence-gathering-agent",
+      "us-intelligence-gathering-agent",
+    ],
+    main_agent_name: "main-controller",
+    model: "deepseek-chat",
+  }),
+});
+const { thread_ids } = await initResp.json();
+
+// 3. 流式调用 leader
+async function streamLeader(message: string, model = "deepseek-chat") {
+  const resp = await fetch("/api/multi-agent/run/stream", {
+    method: "POST",
+    headers: authHeaders,
+    body: JSON.stringify({
+      agent_type: "leader",
+      d_agent_thread_id: thread_ids,
+      agent_name: "main-controller",
+      new_message: message,
+      skill_stop_names: [],
+      model,
+    }),
+  });
+  const reader = resp.body!.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  let dispatched: [string, string][] = [];
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    const lines = buf.split("\n");
+    buf = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.startsWith("data:")) continue;
+      try {
+        const payload = JSON.parse(line.slice(5).trim());
+        if (Array.isArray(payload.status)) {
+          dispatched = payload.status;
+        }
+        // 其余事件按 LangGraph SDK 协议自行渲染
+      } catch {
+        /* 非 JSON 帧，可忽略或交给现有渲染器 */
+      }
+    }
+  }
+  return dispatched;
+}
+
+// 4. 对派活清单逐个调用 special
+async function streamSpecial(agentName: string, task: string, model = "deepseek-chat") {
+  return fetch("/api/multi-agent/run/stream", {
+    method: "POST",
+    headers: authHeaders,
+    body: JSON.stringify({
+      agent_type: "special",
+      d_agent_thread_id: thread_ids,
+      agent_name: agentName,
+      new_message: task,
+      skill_stop_names: [],
+      model,
+    }),
+  });
+  // 同样按 SSE 解析
+}
+
+// 5. 编排：先 leader 派活 → 依次执行 special → 再让 leader 汇总
+const dispatched = await streamLeader("请分析特朗普的支持率");
+for (const [agentName, task] of dispatched) {
+  await streamSpecial(agentName, task);
+}
+const next = await streamLeader("根据上面收集到的信息出最终结论");
+// 当 leader 返回 status: [] 时，意味着汇报完毕，可结束循环
+```
+
+---
+
+## 4. 注意事项
+
+- **`model` 字段的取值**：必须是后端 `config.yaml` 中 `models[]` 已配置的模型名（如 `deepseek-chat`、`glm-4`、`gpt-4o` 等）。传错会导致上游 502
+- **`thread_ids` 必须每次回传**：后端不存储这个映射，是无状态接口
+- **协调智能体必须装有 `agent_orchestration` 技能**：`/init` 创建时会自动指定 `skills=["agent_orchestration"]`。后端 `skills/` 目录里必须存在该技能定义，否则 leader 无法派活
+- **同名协调智能体冲突**：`main_agent_name` 重名时后端不会报错（"already exists" 走兼容分支），会复用既有智能体——所以同一个用户多次 init 用同一个名字是安全的，但 SOUL 不会被覆盖
+- **SSE 断连**：本接口底层 `on_disconnect: "continue"`，断连后上游 run 会继续跑到结束（不会取消）
+- **并发广播**：广播消息使用 `asyncio.gather` 并发更新所有线程 state，性能上不会随子智能体数线性变慢
+
+---
+
+## 5. 相关接口（底层依赖）
+
+本接口内部转发以下 Gateway 原生接口，了解细节可查：
+
+| 接口 | 路由 | 用途 |
+|---|---|---|
+| 创建 thread | `POST /api/threads` | 为每个智能体建立独立会话 |
+| 读 thread state | `GET /api/threads/{id}/state` | 广播前取当前消息列表 |
+| 写 thread state | `POST /api/threads/{id}/state` | 把广播消息追加到 messages |
+| 取 agent 详情 | `GET /api/agents/{id}` | init 时读取子智能体的 name/description |
+| 建 agent | `POST /api/agents` | init 时创建协调智能体 |
+| 流式 run | `POST /api/threads/{id}/runs/stream` | leader/special 的实际执行 |

frontend-web/docs/multi-agent-business-chain-dev.md

@@ -0,0 +1,400 @@
+# 业务链条模式 · 需求与分步实现文档
+
+> 面向「智能体推荐弹窗」的扩展：在现有**智能推荐**之外，新增**业务链条选择**与**业务链条配置**两块能力；选定业务链条后，Step 2 圆桌研讨**按链条内的固定顺序**逐个发言（而非现在的总控派活）。
+>
+> 配套阅读：
+> - 前端总览：`multi-agent-frontend-dev.md`（推荐弹窗 §6.2、Step 2 编排 §5.4、草稿持久化 §5.7）
+> - 后端总览：`multi-agent-backend-dev.md`（Step 2 §6、草稿/历史持久化 §7A）
+>
+> 本文档约定：**「席位 / 智能体」**指一个 agent；**「业务链条 / chain」**指一组有序排列的 agent 配置，是可命名、可复用、可持久化的实体。
+
+---
+
+## 0. 需求原文拆解
+
+用户原始诉求逐条拆成可实现条目：
+
+| # | 原始诉求 | 拆解 |
+|---|----------|------|
+| 1 | 推荐弹窗要有「模式选择」 | 弹窗顶部加模式切换（智能推荐 / 业务链条），两种模式互斥，确认后都产出**有序**的 `SelectedAgent[]` |
+| 2 | 「智能推荐」就是现在这个 | 现有 `RecommendAgentsDialog` 整体收进「智能推荐」模式，行为不变 |
+| 3 | 「业务链条选择」是卡片列表 | 卡片 = 标题 + 一排智能体名 tag；tag 不同颜色；tag 之间有**向左箭头**连接，表达链条次序 |
+| 4 | 业务链条需要一个**配置页面** | 左侧智能体列表（复用 `GET /api/agents`），右侧有序长条卡片（名称 + 描述）；支持右侧内部拖拽排序、左→右拖入指定位置 |
+| 5 | 配置页用弹窗还是新页面？ | **本文档决策：独立路由页面**（理由见 §2.1） |
+| 6 | 选定链条后，Step 2 用链条内智能体研讨 | 复用既有 Step 2 init/stream；**总控（leader）按链条顺序逐个派活**（§6） |
+| 7 | 规划成分步可实现的需求文档 | 见 §7 分阶段实现 |
+
+---
+
+## 1. 目标与非目标
+
+### 1.1 目标
+- 推荐弹窗成为「**席位来源选择器**」：无论智能推荐还是业务链条，最终都向 `onConfirm` 交付一个**有序的 `{ agent_id, name }[]`** + 一个 `orchestrationMode`。
+- 业务链条是**用户可创建、命名、保存、复用、删除**的有序智能体编排模板。
+- Step 2 支持两种编排：
+  - `recommend` 模式 → 现有总控**自由派活**循环（不动）。
+  - `chain` 模式 → 总控仍是派活方，但**被约束按链条顺序逐个派活**（新增）。
+
+### 1.2 非目标（本期不做，留扩展点）
+- 链条内每个席位的 per-seat prompt/temperature 真实覆盖（仍仅前端记录，沿用现状）。
+- 链条的分支 / 条件流转（只做线性顺序链）。
+- 链条跨用户共享 / 市场（先做「本人私有链条」）。
+- 链条版本管理 / 协作编辑。
+
+---
+
+## 2. 关键设计决策
+
+### 2.1 决策 A：配置页面用「独立路由页面」而非弹窗 ✅
+
+**结论：业务链条的「编辑/管理」用独立路由页面 `/page/workspace/roundtable/chains`；业务链条的「选择」仍内嵌在推荐弹窗里（卡片列表）。**
+
+理由：
+
+| 维度 | 弹窗 | 独立页面 ✅ |
+|------|------|------------|
+| 双栏 + 拖拽 + 长条卡片 | 弹窗宽度（`sm:max-w-3xl`）+ `max-h-[85vh]` 拖拽空间局促，左右栏挤 | 整屏宽度，拖拽手感好 |
+| 复用入口 | 只能从推荐弹窗进 | 可从侧栏、推荐弹窗「管理链条」按钮、深链接进入 |
+| 可深链接/刷新 | 不可 | `/roundtable/chains` 可直达、可分享 |
+| 推荐弹窗内嵌编辑器 | 弹窗套弹窗 / 模式套编辑，状态复杂 | 关注点分离：弹窗只「选」，页面只「编」 |
+
+**分工**：
+- **推荐弹窗**：模式选择 + 业务链条**选择**（只读卡片列表，可点「去配置」跳到页面）。
+- **配置页面**：业务链条的**增删改**（双栏拖拽编辑器 + 链条列表管理）。
+
+> 备选：若产品坚持不加路由，可改为**全屏 Dialog（`max-w-[90vw] h-[90vh]`）**承载编辑器，从推荐弹窗内打开。结构与页面版一致，仅外壳不同。本文档按「独立页面」实现，§7 标注了切换成本。
+
+### 2.2 决策 B：链条持久化 —— 后端 MySQL（确定） ✅
+
+**结论：业务链条存后端 MySQL，仿 `roundtable_drafts`（§7A）新建 `roundtable_chains` 表 + `/api/roundtable-chains` 路由，按登录用户隔离、跨设备保留。** 不走 localStorage。
+
+理由：链条是可复用、需跨设备/会话保留的模板，与草稿/推荐历史性质一致；草稿当年正是因 localStorage 换设备即丢才迁后端（§7A），链条不重复踩坑。
+
+落地：
+- 表/路由设计见 §5.2，是「复制 §7A 草稿持久化、把字段换成 chain」的机械工作。
+- 前端 `api/chains.ts` 直接打后端接口（snake_case↔camelCase 在这层收口，仿 `api/drafts.ts`），**不提供 localStorage 实现**。
+- 后端表必须先于前端 UI 落地（§7 阶段 0 即包含后端表/路由）。
+
+### 2.3 决策 C：拖拽库选型 —— `@dnd-kit`
+
+仓库**当前无任何拖拽库**（`package.json` 无 `@dnd-kit` / `react-dnd` / `sortablejs`；`@xyflow/react` 是节点图，不适合列表排序）。
+
+| 方案 | 取舍 |
+|------|------|
+| **`@dnd-kit/core` + `@dnd-kit/sortable`**（推荐） | React 19 友好、可访问性好、跨容器拖入 + 列表排序 + 插入指示器开箱即用；新增 ~30KB gzip 依赖 |
+| 原生 HTML5 DnD（零依赖兜底） | 不加依赖，但跨容器插入位置指示、键盘可达性都要手写，易出 bug |
+
+**建议**：新增 `@dnd-kit/core`、`@dnd-kit/sortable`、`@dnd-kit/utilities`。若产品方禁止新增依赖，退回原生 HTML5 DnD（§7 阶段 2 标注差异）。
+
+### 2.4 决策 D：Step 2「总控按链条顺序派活」，后端零改动 ✅
+
+**形态：总控（leader）仍是唯一派活方，但每一轮被前端约束「只能派给链条里的下一个席位」，逐个走完整条链，最后由总控收口。** 区别于 recommend 模式的「总控自由决定派给谁」。
+
+为什么后端无需改动：
+- Step 2 后端 `streamMultiAgent({ agentType: "leader" })` 每轮返回 `dispatched = [[agent, task], ...]`；`agentType: "special"` 单独驱动某席位跑一轮。这两个原语已足够。
+- 每个 special 跑完，后端 `_broadcast` 会把「子智能体 X 完成…交付内容为:…」append 进**其它所有席位 + 总控 thread** 的历史（后端 §6.4），所以链路上下文天然累积。
+- chain 模式只是**改变前端怎么提示 leader、以及怎么校验它的派活**——把每轮 leader 的提示词约束成「请向链条第 i 位【X】派活」，并对返回的 `dispatched` 做「必须命中链条下一席位」的校验/纠偏。**后端路由、SOUL、表结构都不动。**
+
+→ chain 模式 = 在 `useStep2Orchestration` 里新增 `runChainOrchestration`：按链条游标逐位调 leader（约束派给该位）→ 拿到 task → 调 special → 下一位 → 链尾后调一次 leader 收口。详见 §6。
+
+> 与「前端绕过 leader 直接顺序 special」的区别：本方案**保留总控在每一步的协调/串接职责**（leader 结合前序进展为下一席位编写针对性任务、并在派活说明里承上启下），更符合「总控按链条顺序派活」的语义，圆桌可视化里总控气泡也照常出现。
+
+---
+
+## 3. 数据模型与类型
+
+新增前端类型，建议放 `frontend-web/src/roundtable-planning/lib/business-chain.ts`：
+
+```ts
+/** 业务链条里的一个有序席位。 */
+export interface ChainSeat {
+  agent_id: string;
+  /** 落库时的快照名/描述，避免 agent 改名后链条显示错乱；展示优先用实时 agent 数据，回退到快照。 */
+  name: string;
+  description?: string;
+}
+
+/** 一条可复用的业务链条。 */
+export interface BusinessChain {
+  id: string;
+  title: string;
+  description?: string;
+  /** 有序席位列表；seats[0] 是第一个发言者。 */
+  seats: ChainSeat[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/** 推荐弹窗确认后回传给主页面的统一结果。 */
+export interface SeatSelectionResult {
+  /** 有序席位（与现有 handleConfirmAgents 入参兼容）。 */
+  agents: Array<{ agent_id: string; name: string }>;
+  /** 决定 Step 2 走哪种编排。 */
+  mode: "recommend" | "chain";
+  /** chain 模式下带上来源链条（用于草稿快照 / Step 2 展示链名）。 */
+  chain?: Pick<BusinessChain, "id" | "title">;
+}
+```
+
+**约束**：链条席位数沿用圆桌的 `2 ≤ N ≤ 8`（`MIN_SELECTED`/`MAX_SELECTED`），配置页保存时校验。
+
+**tag 配色**：复用 `roundtable-constants.ts::getAvatarTypeFor(agentId, index)`，得到 `blue|purple|emerald|amber|pink|human`，再映射到已有的 avatar 配色 token（与圆桌可视化、Step 2 气泡同一套色板，视觉统一）。
+
+---
+
+## 4. 现有代码改动点速查
+
+| 位置 | 改动 | 说明 |
+|------|------|------|
+| `components/RecommendAgentsDialog.tsx` | 包一层「模式选择」外壳，现有内容收进「智能推荐」Tab | `onConfirm` 签名从 `agents[]` 升级为 `SeatSelectionResult`（或加可选第二参 `mode`，见 §7 阶段 3 的兼容策略） |
+| `pages/RoundtablePlanningPage.tsx` | `handleConfirmAgents` 接收 `mode`，存到新状态 `orchestrationMode` | 透传给 `useStep2Orchestration` |
+| `hooks/useStep2Orchestration.ts` | 新增 `runChainOrchestration` + `orchestrationMode` 分支 | init effect 里按 mode 选择 `runOrchestration` 或 `runChainOrchestration` |
+| `lib/roundtable-constants.ts` | 复用 `getAvatarTypeFor` / `SelectedAgent` | 不改，仅引用 |
+| `hooks/useDraftPersistence.ts` + `api/drafts.ts` | Step2 快照新增 `orchestrationMode` + `chain` 字段 | 草稿能记住「这次是链条模式」 |
+| `pages/WorkspaceRoutes.tsx` | 注册 `roundtable/chains` 路由 | 仿 `roundtable/planning` |
+| `components/page-sidebar.tsx`（如有侧栏入口） | 加「业务链条」入口（可选） | 也可只从推荐弹窗进 |
+| `api/chains.ts`（新增） | 链条 CRUD 客户端 | 直接打后端 `/api/roundtable-chains` |
+| 后端 `roundtable_chains` | 表 + 路由（MySQL） | 仿 `roundtable_drafts`，**必做** |
+
+---
+
+## 5. 链条持久化 API 设计
+
+### 5.1 前端客户端 `api/chains.ts`（直接打后端）
+
+```ts
+listChains(): Promise<BusinessChain[]>          // 当前用户全部链条
+getChain(id: string): Promise<BusinessChain>
+createChain(input: Omit<BusinessChain,"id"|"createdAt"|"updatedAt">): Promise<BusinessChain>
+updateChain(id: string, patch: Partial<BusinessChain>): Promise<BusinessChain>
+deleteChain(id: string): Promise<void>
+```
+
+- 实现用 `apiFetch` 打 `/api/roundtable-chains`（§5.2），snake_case↔camelCase 在这层收口（仿 `api/drafts.ts`）。
+- 不提供 localStorage 实现；后端表是前端 UI 的硬依赖。
+
+### 5.2 后端表 + 路由（仿 §7A `roundtable_drafts`）
+
+- 表 `roundtable_chains`：`id`(PK) / `user_id`(idx) / `title`(512) / `description`(text) / `seats`(`PortableLongText`，存 `ChainSeat[]` JSON) / `created_at` / `updated_at`(`BeijingDateTime`)。
+- 路由 `app/gateway/routers/roundtable_chains.py`，前缀 `/api/roundtable-chains`：`GET ``（列表）/ `POST ``（建）/ `GET /{id}` / `PUT /{id}`（partial，`exclude_unset`）/ `DELETE /{id}`。
+- 鉴权/属主：`_current_user_id(request)`，跨用户访问一律 404，与 `roundtable_drafts` 完全一致。
+- 启动 `Base.metadata.create_all` 自动建表（MySQL 生产 / sqlite 本地走同一套 SQLAlchemy 代码，`PortableLongText` 各自降级），登记进 `persistence/models/__init__.py`，store 接到 `app.state` 并 `include_router`。
+
+> 整体是「复制 §7A 的草稿持久化、把字段换成 chain」的机械工作，风险低。
+
+---
+
+## 6. Step 2 链条模式编排设计（`runChainOrchestration`）
+
+### 6.1 与现有 `runOrchestration` 的差异
+
+| 维度 | `runOrchestration`（recommend） | `runChainOrchestration`（chain，新增） |
+|------|--------------------------------|----------------------------------------|
+| 谁派活 | 总控 leader | 总控 leader（**不变**） |
+| 派给谁由谁定 | leader 自由决定 | 前端按链条游标**约束 leader 只能派给下一席位** |
+| 发言顺序 | leader 每轮自由派 | **链条数组的固定顺序** |
+| 循环结构 | `while` 直到 leader 返回 `[]` 共识 / MAX_CYCLES | 按链条游标走一趟（每位：leader 派活 → special 交付） |
+| 收口 | leader 返回 `[]` 即共识 | 链尾后再调一次 leader 做总结收口，产出 `lastLeaderContent` + `hasConsensus` |
+
+> **核心**：leader 始终在场，只是**每轮的派活目标被前端钉死成链条的下一席位**——前端在 leader 的 `newMessage` 里写明「本轮请通过 `agent_orchestration` 仅向【X】派活」，并对 `leaderRes.dispatched` 做命中校验/纠偏。
+
+### 6.2 伪代码
+
+```
+runChainOrchestration(seedMessage, ids, coord, chainSeats):
+  isOrchestrating = true
+  cancel = false
+  N = chainSeats.length
+
+  for (let i = 0; i < N; i++):           // 链条游标，逐位推进
+    if cancel: break
+    seat = chainSeats[i]
+    seatMeta = agentNameToRole[seat.agent_id]
+
+    // ── (a) 总控派活给「链条下一席位」──────────────────────────
+    highlightSpeaker(null)               // leader 阶段不高亮任何 sub
+    leaderBubble = appendStreamingDialogue("总控协调", confidence:"链条派活中")
+    leaderTask = buildChainLeaderTask({
+      seedMessage,                       // 任务目标/约束（首轮）
+      position: i, total: N,
+      nextSeat: seat,                    // 「本轮请仅向【X(seat.agent_id)】派活」
+      isFirst: i === 0,
+    })
+    leaderRes = await streamMultiAgent(leader, ids, coord, leaderTask, model=globalModel)
+
+    // 约束/纠偏：取 dispatched 中命中 seat.agent_id 的那条 task；
+    // 若 leader 没派或派错（派给非 seat、或派给多个），前端兜底：
+    //   - 命中就用它给出的 task 文本（保留总控的承上启下措辞）；
+    //   - 没命中则用 leader 的正文 content 作为兜底 task，或回退到模板 task。
+    task = pickChainTask(leaderRes, seat) 
+    // leader 若返回 clarification → 暂停链条，走与现状一致的澄清条（§6.3）
+    finalizeDialogue(leaderBubble, leaderRes.content, "派活说明")
+
+    // ── (b) 被派席位交付（special，顺序、不并行）──────────────────
+    markSpeakerStreaming(seatMeta.speakerId)
+    seatBubble = appendStreamingDialogue(seatMeta.displayName, confidence:"调度中")
+    perSeatModel = agentConfigs[seatMeta.speakerId]?.model || globalModel
+    specRes = await streamMultiAgent(special, ids, seat.agent_id, task, model=perSeatModel)
+    finalizeDialogue(seatBubble, specRes.content, "子智能体交付")
+    markSpeakerIdle(seatMeta.speakerId)
+    // 后端 _broadcast 已把本席位交付注入其余 thread 历史 → 下一席位天然可见
+
+  if cancel: return
+
+  // ── (c) 总控收口：综合全链交付，产出最终结论 ──────────────────
+  leaderBubble = appendStreamingDialogue("总控协调", confidence:"汇总链条结论")
+  leaderRes = await streamMultiAgent(leader, ids, coord,
+                "各链条席位已按顺序完成发言，请综合所有交付，输出最终方案，不要再派活。")
+  finalizeDialogue(leaderBubble, leaderRes.content, "全案盖印")
+  setLastLeaderContent(leaderRes.content)
+  setHasConsensus(true); setConsensusPercentage(100)
+  isOrchestrating = false
+```
+
+要点：
+- **派活方仍是总控**，符合「总控按链条顺序派活」的语义；圆桌可视化里每位席位前都先出现一个总控派活气泡，再出现该席位交付气泡。
+- **约束手段是 prompt + 前端校验，不动后端**：`buildChainLeaderTask` 把「本轮只能派给【X】」写进 leader 的 `newMessage`；`pickChainTask` 对 `leaderRes.dispatched` 做命中校验，派错/未派时兜底，保证链条游标严格推进。
+- **复用现有三段式气泡 / 高亮 / abort 基建**（`appendStreamingDialogue` / `finalizeDialogue` / `markSpeakerStreaming` / `activeAbortersRef` / `orchestrationCancelRef`），只是驱动顺序不同。
+- **special 仍是顺序**（不并行），与现状不变量一致（文件顶部注释 §1）。
+- **收口 leader 调用默认开**（产出 Step 3 结论）；若链条末位本身是「总结陈述」类，可关掉收口，直接拿末位交付当 `lastLeaderContent`。配置位 `chainNeedsLeaderSummary`（默认 true）。
+
+### 6.3 澄清 / 挂起 / 恢复 / 干预
+- **澄清**：链条中途某轮 leader 返回 `clarification` → 与现状一致，暂停链条、底部弹澄清条；用户回答后从**当前游标**继续（需记录 `chainCursor`）。
+- **挂起/恢复**：`isRoundTableRunning` toggle 复用现有机制；恢复时从 `chainCursor` 续跑。MVP 若不做断点续跑，可先只支持「整体停止 / 从头重跑」，UI 文案说明（扩展点，§7 阶段 4 标注）。
+- **干预**：可在两席位之间插入一条用户指令，由下一轮 leader 派活前消化。MVP 同上可后置。
+
+### 6.4 多轮链条（扩展点，非 MVP）
+单趟遍历是 MVP。若要「链条跑完后总控判断是否再来一轮」，可在收口 leader 处复用 `dispatched===[]?` 判定：收口 leader 若仍派活则回到链条头再跑一轮，直到共识或 MAX_CYCLES。MVP 不做，避免复杂度。
+
+### 6.5 init 复用
+chain 模式的 Step 2 init **完全复用** `initMultiAgent`：`agentNames = chainSeats.map(s => s.agent_id)`（**按链条顺序**传入，使 `buildRoleTemplates` 的 seat id 顺序 = 链条顺序，且后端注入 coordinator 的「可调度席位清单」也按此序）。init effect 里按 `orchestrationMode` 决定 init 完成后调 `runOrchestration` 还是 `runChainOrchestration`。
+
+---
+
+## 7. 分阶段实现计划
+
+> 每阶段都可独立交付、独立验收。建议顺序：**数据层 → 配置页 → 弹窗模式 → 链条选择 → Step2 编排 → 持久化兼容与收尾**。
+
+### 阶段 0 · 后端链条表 + 脚手架（1.5 天） ✅ 已完成
+**目标**：打地基（含后端持久化），不含前端 UI。
+- [x] **后端**：仿 §7A `roundtable_drafts` 新建 `roundtable_chains` 表 + `/api/roundtable-chains` 路由（§5.2）：
+  - [x] `persistence/roundtable_chains/`（model + sql repo + `make_roundtable_chain_store`），登记进 `persistence/models/__init__.py`。
+  - [x] `app/gateway/routers/roundtable_chains.py`（GET 列表 / POST / GET{id} / PUT{id} / DELETE），鉴权属主同 `roundtable_drafts`；席位 2–8 + 去重校验。
+  - [x] `deps.py` 接 `app.state.roundtable_chain_store`，`app.py` `include_router`。
+  - [x] 后端测试 `tests/test_roundtable_chains.py`：CRUD + 部分更新 + 跨用户隔离（5 用例全过）。
+- [x] **前端**：新增 `lib/business-chain.ts`（`ChainSeat` / `BusinessChain` / `SeatSelectionResult`，§3）+ `api/chains.ts`（直接打后端，§5.1）。
+- [x] （决策 C）安装 `@dnd-kit/core` `@dnd-kit/sortable` `@dnd-kit/utilities`。
+- **验收**：✅ 后端 5 用例通过；✅ 表注册进 `Base.metadata`、路由 `/api/roundtable-chains` 加载正常；✅ ruff 0 错；✅ 前端 typecheck 新增文件 0 错。
+
+### 阶段 1 · 业务链条配置页面（2–3 天） ✅ 已完成
+**目标**：能创建/编辑/保存/删除链条。
+- [x] 路由：`WorkspaceRoutes.tsx` 注册 `roundtable/chains`（套 `WorkspaceLayout`；本页**不需要** `ChatRuntime`，无沙箱依赖）。
+- [x] 页面 `roundtable-planning/pages/BusinessChainEditorPage.tsx`：
+  - [x] 顶部：链条列表下拉（`<select>` 列出已存链条 + 新建项）/ 新建按钮 / 标题+描述输入 / 保存 / 删除（`window.confirm`）。
+  - [x] **左栏**：候选智能体（`listAgents()` + `filterRecommendCandidates`），竖排卡片，可拖、可点「＋」快捷加入；已加入的置灰「已加入」。
+  - [x] **右栏**：有序长条卡片（序号 tag + 名称 + 描述 + 移除），`SortableContext` 内拖拽排序；空态有占位提示。
+  - [x] 拖拽用 `@dnd-kit`：左栏 `useDraggable`，右栏 `useDroppable` + `SortableContext`/`useSortable`，`onDragEnd` 计算插入 index（pool→右栏按落点插入；seat→seat `arrayMove`）；`DragOverlay` 跟手卡片。
+  - [x] 校验：`2 ≤ seats ≤ 8`（前端禁用保存 + toast，后端 `_validate_seats` 兜底），重复 agent 去重提示。
+- [x] 保存走 `api/chains.ts`（create 用 `nanoid()` 客户端 id，update 走同一 id）。
+- **验收**：✅ typecheck 0 新增错误（76 个预存量错误均在无关模块）。**人工验收待跑**：新建「情报→方案→风险→总结」链保存 → 刷新后下拉重载 → 右栏拖拽排序 → 左栏拖入指定位 → 2–8 边界禁用保存。
+- **切换成本备注**：若改全屏 Dialog 方案，编辑器组件原样复用，仅去掉路由、外面套 `Dialog`。
+- **入口说明**：圆桌本身未在侧栏（`sidebar-menu.ts` 入口被注释），本页暂经直链 `/page/workspace/roundtable/chains` 或顶栏「返回圆桌」往返；阶段 3 推荐弹窗「去配置」按钮会导航到此。
+- **视觉（后续重画）**：本页**不**套圆桌 `roundtable-planning` scope，直接遵循《浅红色/深蓝色 UI 规范》——用 app 语义 token（光 `--primary` 红 hue27 / 暗 蓝 hue259，已内置自适应）+ 规范小圆角（输入/按钮/tag/卡片内项 2px = `R_CTRL`，分栏/面板 4px = `R_CARD`）+ 克制阴影（`PANEL_SHADOW`）。筛选框复用通用 `TagSearchBar`，配色随 app 中性 token，不再被红 scope 染色。
+
+### 阶段 2 · 推荐弹窗「模式选择」外壳（1 天） ✅ 已完成
+**目标**：弹窗顶部模式切换，智能推荐行为不变。
+- [x] `RecommendAgentsDialog` 顶部加**分段按钮**模式切换：`智能推荐 | 业务链条`（active 态品牌色 + 卡底；DialogDescription 随模式切换文案）。
+- [x] 现有全部内容原样收进「智能推荐」面板（`{mode === "recommend" && (<>…</>)}` 包裹，**零行为变更**）。
+- [x] 「业务链条」面板放占位：居中提示 + 「去配置业务链条」按钮（`handleGoConfig` → 关弹窗 + 跳 `roundtable/chains`）。
+- [x] `onConfirm` 统一升级为回传 `SeatSelectionResult`（含 `mode`）：智能推荐确认回传 `{ agents, mode: "recommend" }`；主页面 `handleConfirmAgents` 同步改签名取 `result.agents`（`result.mode` 预留给阶段 4）。
+- **验收**：✅ typecheck 0 新增错误（总数仍 76）；智能推荐分支 JSX/逻辑原样保留（流式/勾选/进入研讨未改）；模式切换只切显示、`state`/`selectedIds` 不卸载 → 候选池不丢。**人工验收待跑**：切到业务链条→再切回，推荐结果与勾选仍在。
+
+### 阶段 3 · 业务链条选择卡片列表（1.5 天） ✅ 已完成
+**目标**：弹窗「业务链条」面板里选链条。新增 `components/BusinessChainPicker.tsx`，替换阶段 2 的占位。
+- [x] 进入该 Tab 时 `listChains()` 拉本人链条 + `listAgents()` 取存活 id/名称，渲染**卡片列表**：
+  - [x] 卡片标题（链条 title）+ 「N 席」徽章 + 选中 ✓；描述行。
+  - [x] 标题下一排**智能体名 tag**：按链条顺序**从左到右**、不同颜色（`getAvatarTypeFor`→`chainTagClasses`），tag 之间插 `→`（`ArrowRightIcon`）箭头连接（`seats[0]` 最左、先发言）。
+  - [x] 底部「配置链条」按钮（跳 `roundtable/chains`）。
+- [x] 空态：无链条时引导「去配置页面创建第一条业务链条」+ 按钮。
+- [x] 选中一条 → 高亮（`ring-primary`）；底部「进入研讨」`onConfirm({ agents: 存活席位有序, mode:"chain", chain:{id,title} })`。
+- [x] 链条里有 agent 已不存在（被删）→ 该 tag 置灰删除线 + `title` 提示 + 卡片下方 amber 警告；confirm 按**存活席位**过滤；存活 < `CHAIN_MIN_SEATS` 则禁用「进入研讨」并提示。agent 列表加载失败时 `existingIds=null` → 不误判删除。
+- **验收**：✅ typecheck 0 新增错误（总数仍 76）。卡片渲染标题 + 彩色 tag + ← 箭头；选链 → `onConfirm(mode:"chain")` → `handleConfirmAgents` 按链条顺序 `setSelectedAgents` → Step 2 左侧「参与角色」顺序 = 链条顺序（**按顺序派活在阶段 4**）。**人工 UI 验收待跑**。
+- **箭头方向**（已确认）：tag 左→右排列、`→`（`ArrowRightIcon`）连接，`seats[0]` 最左、先发言，箭头顺读即链条研讨顺序。
+
+### 阶段 4 · Step 2 链条顺序编排（2–3 天） ✅ 已完成
+**目标**：chain 模式按链顺序逐席发言。**后端零改动。**
+- [x] 主页面新增 `orchestrationMode` 状态，`handleConfirmAgents` 从 `SeatSelectionResult.mode` 写入（chain 模式 toast 带链名）；`handleStartNewTask` 复位为 `recommend`；透传给 `useStep2Orchestration`。chain 顺序 = `selectedAgents`（确认时已按链条顺序写入），无需单独 `chainSeats`。
+- [x] `useStep2Orchestration` 新增 `runChainOrchestration`（§6.2）+ `orchestrationModeRef`/`selectedAgentsRef`；复用现有三段式气泡/高亮/abort 基建。
+- [x] 新增 `runActiveOrchestration` 分发器：init / 恢复 / 干预 / 澄清回复 4 处调用点统一改走它，按 `orchestrationModeRef` 选 `runOrchestration`（recommend）或 `runChainOrchestration`（chain）。
+- [x] `runChainOrchestration`：按 `selectedAgents` 游标，每位先 leader 约束派活（`buildChainLeaderTask` 钉死目标席位 + `pickChainTask` 命中校验/纠偏，派错/未派都兜底推进）→ 再对**该席位**跑 special；中途 leader 若 `clarification` 则暂停（MVP 回复后整链重跑）。
+- [x] `initMultiAgent` 的 `agentNames` 即 `roundtableAgentIds`（由 `selectedAgents` 派生，已是链条顺序，§6.5）。
+- [x] 收口 leader（`finishedAllSeats` 时触发），产出 `lastLeaderContent` + `hasConsensus=true` + `consensusPercentage=100` 解锁 Step 3。
+- **验收**：✅ typecheck 0 新增错误（总数仍 76）；✅ 唯一直接引用 `runOrchestration` 的是 dispatcher。逻辑层：每席「总控派活气泡 → 席位交付气泡」、严格顺序、单 special 在跑、`_broadcast` 注入前序上下文、leader 纠偏推进、跑完解锁 Step 3、abort 可中断。**人工 UI 验收待跑**。
+- **MVP 边界**：chain 模式的「挂起→断点续跑」「逐席间干预」未做断点续跑，`clarification`/恢复/干预当前为**整链重跑**（`chainCursor` 列为扩展点）。
+
+### 阶段 5 · 草稿持久化兼容 + 收尾（1 天） ✅ 已完成
+**目标**：草稿记住模式，回归不破。
+- [x] `Step2Snapshot`（`useStep2Orchestration.ts`）+ `DraftStep2Snapshot`（`api/drafts.ts`）新增 `orchestrationMode?: "recommend"|"chain"` 与 `chain?: {id,title}|null`。
+- [x] 恢复路径：`orchestrationMode`/`chainMeta` 是**主页面 state**，`getStep2Snapshot` 写入；**包裹版 `hydrateStep2`** 在加载时 `setOrchestrationMode(snapshot.orchestrationMode ?? "recommend")` + `setChainMeta(snapshot.chain ?? null)` 再调 `step2.hydrateFromDraft`；老草稿无字段 → 默认 `recommend`（向后兼容）。`handleStartNewTask` 复位两者。
+- [x] 文档回写：`multi-agent-frontend-dev.md` §5.7（快照形状 + `orchestrationMode/chain` 说明）、§6.2（席位来源选择器导语）；`multi-agent-backend-dev.md` 新增 §7B（`roundtable_chains` 表/路由）。
+- **验收**：✅ `pnpm typecheck` 0 新增错误（总数仍 76）。逻辑：chain 会话保存草稿 → 重载 `orchestrationMode="chain"` + 链信息恢复；老草稿（无字段）默认 recommend 照常加载。**人工 UI 验收 + `pnpm build` 待跑**。
+
+### 工期粗估
+| 阶段 | 估时 |
+|------|------|
+| 0 后端链条表 + 脚手架 | 1.5d |
+| 1 配置页 | 2–3d |
+| 2 弹窗模式壳 | 1d |
+| 3 链条选择卡片 | 1.5d |
+| 4 Step2 链编排 | 2–3d |
+| 5 持久化兼容收尾 | 1d |
+| **合计** | **约 9–11 人日**（含后端 `roundtable_chains` 表/路由） |
+
+---
+
+## 8. 验收清单（端到端）
+
+1. 推荐弹窗顶部有「智能推荐 / 业务链条」切换；智能推荐与现状逐像素一致。
+2. 配置页 `/page/workspace/roundtable/chains` 左栏列出智能体、右栏有序长条卡片；左→右拖入指定位、右栏内拖拽排序均生效；2–8 校验生效；保存/重载/删除正常。
+3. 业务链条卡片：标题 + 彩色智能体 tag + ← 箭头连接，渲染正确。
+4. 选定链条 → Step 2 席位顺序 = 链条顺序，并**按顺序逐个发言**，后序能看到前序交付。
+5. chain 跑完解锁 Step 3；草稿记住 chain 模式并可重载。
+6. 删除链条中引用的 agent 后，选择端有降级提示，不崩。
+
+---
+
+## 9. 风险与开放问题
+
+| # | 项 | 说明 / 建议 |
+|---|----|-------------|
+| 1 | 配置页：弹窗 vs 页面 | 本文档定为**独立页面**（§2.1）。若产品要弹窗，编辑器组件可复用，仅换外壳。**请确认。** |
+| 2 | 链条持久化 | **已定：后端 MySQL `roundtable_chains`**（§2.2 / §5.2），仿草稿持久化。 |
+| 3 | Step 2 链编排 | **已定：总控按链条顺序派活**（§2.4 / §6），后端零改动。 |
+| 4 | 新增 `@dnd-kit` 依赖 | 若禁止新增依赖，退原生 HTML5 DnD（手感与可达性下降）。**请确认。** |
+| 5 | ← 箭头方向 / tag 阅读顺序 | 默认 `seats[0]` 在最左、先发言；箭头仅作视觉连接。**请确认是否要「从右往左读」。** |
+| 6 | chain 模式是否需要收口 leader 总结 | 默认需要（产出 Step 3 结论）。若末位席位自带总结可关掉。 |
+| 7 | leader 派活纠偏策略 | leader 派错/未派时前端兜底推进游标（§6.2 `pickChainTask`）；可加 toast 提示「已按链条强制推进」。 |
+| 8 | chain 模式断点续跑 / 逐席干预 | MVP 不做，列为扩展点（§6.3 / §7 阶段 4）。 |
+| 9 | 链条是否私有 | 本期仅本人私有（仿草稿按 `user_id` 隔离）。共享/市场留扩展。 |
+
+---
+
+## 10. 路径速查（新增/改动）
+
+| 资源 | 路径 | 状态 |
+|------|------|------|
+| 链条类型 | `frontend-web/src/roundtable-planning/lib/business-chain.ts` | 新增 |
+| 链条 API 客户端 | `frontend-web/src/roundtable-planning/api/chains.ts` | 新增 |
+| 配置页 | `frontend-web/src/roundtable-planning/pages/BusinessChainEditorPage.tsx` | 新增 |
+| 链条选择面板 | `frontend-web/src/roundtable-planning/components/BusinessChainPicker.tsx` | 新增 |
+| 链条卡片 | `frontend-web/src/roundtable-planning/components/BusinessChainCard.tsx` | 新增 |
+| 推荐弹窗（加模式壳） | `frontend-web/src/roundtable-planning/components/RecommendAgentsDialog.tsx` | 改 |
+| 主页面（mode 透传） | `frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx` | 改 |
+| Step2 编排（加 chain） | `frontend-web/src/roundtable-planning/hooks/useStep2Orchestration.ts` | 改 |
+| 草稿快照（加 mode） | `hooks/useDraftPersistence.ts` + `api/drafts.ts` | 改 |
+| 路由注册 | `frontend-web/src/pages/WorkspaceRoutes.tsx` | 改 |
+| 后端链条持久化 | `offline-backend-20260512/backend/packages/harness/deerflow/persistence/roundtable_chains/` | 新增 |
+| 后端链条路由 | `offline-backend-20260512/backend/app/gateway/routers/roundtable_chains.py` | 新增 |
+| 后端 store 接线 | `offline-backend-20260512/backend/app/gateway/deps.py`（`app.state.roundtable_chain_store`）+ `app.py` | 改 |
+</content>
+</invoke>

frontend-web/docs/multi-agent-frontend-dev.md

@@ -0,0 +1,781 @@
+# 多智能体圆桌研讨 · 前端开发文档
+
+本文档面向维护 `frontend-web` 圆桌规划功能的开发者。后端实现见 `multi-agent-backend-dev.md`；HTTP 字段速查见 `multi-agent-api.md`；推荐弹窗专项进度见 `recommend-agents-progress.md`（若不存在则为待补文件）。
+
+> ⚠️ 历史版本曾引用 `multi-agent-step1-api.md`、`multi-agent-step3-api.md`，当前仓库未提供这两份文件；Step 1（intent）/ Step 3（artifacts）的接口签名直接参考本页第 4 节即可。
+
+---
+
+## 0. 速读：你需要先知道的事
+
+- **三步 UI 通过 `currentStep ∈ {1,2,3}` 切换**，不使用 React Router 子路由。主页面 `RoundtablePlanningPage.tsx`（≈ 1 150 行）只负责组合 + 编排，业务状态全部下沉到三个 hook（见下面）。
+- **业务状态分三块**：`useStep1Intent`（任务理解 + 澄清）、`useStep2Orchestration`（编排循环 + 对话流 + Persona）、`useDraftPersistence`（草稿）。改 Step X 的逻辑请直接进对应 hook，不要回到主页面里写。
+- **消息气泡有共享件**：Step 1 / Step 2 的对话气泡共用 `MessageBubble.tsx` 里的 `MessageBubble` + `MessageLoadingPlaceholder` + `StreamingCursor` + `MarkdownContent`。改气泡通用样式（头像、header、loading、流式 cursor、Markdown 渲染配置）请改这里,不要在两个 Panel 各改一遍。
+- **步骤折叠卡与主聊天对齐**：思考过程 / 工具调用展示走 `MessageStepsCard`,**always-show-last-tool + 折叠 "查看其他 N 个步骤"** 的视觉与主聊天 `chats/new` 的 `MessageGroup` 一致。工具图标 / 文案映射在 `lib/step-display.tsx`,新增工具时与 `src/core/i18n/locales/zh-CN.ts` 的 `toolCalls` 字段对齐。
+- **`<think>` 标签自动提取为「思考过程」**：`lib/reasoning.ts::splitInlineReasoning(text)` 把 `<think>...</think>`(含未闭合的流式中段)抽离成 `reasoning`,正文走 markdown;由 `MessageBubble.tsx::ReasoningBlock` 渲染一个折叠卡。Step 1 / Step 2 气泡和推荐弹窗的 rationale 都走这一套,与主聊天 `Reasoning` 元素的视觉对齐。
+- **不使用 LangGraph SDK**：所有 API 都是自研的 `apiFetch` + `ReadableStream` SSE 解析（见 `api/intent.ts`、`api/recommend.ts`、`api/multi-agent.ts`）。
+- **草稿/历史持久化在后端（2026-06）**：草稿不再存浏览器 `localStorage`，改走后端 MySQL（`/api/roundtable-drafts`，按登录用户隔离、跨设备保留）。`api/drafts.ts` 封装 CRUD，`useDraftPersistence` 异步对接、对外接口不变。**推荐弹窗带「会话级推荐历史」**：每个草稿一串历史，重开弹窗先显示上次推荐结果，可「重新分析」重跑（详见 §5.7 / §6.2）。后端实现见 backend doc 的「圆桌草稿持久化」一节。
+- **不写死模型名**：与 `/page/canvas/ai-writing` 同样的策略 —— 全局选中模型由 `selectedModel` state 维护，首次 `useModels()` 完成后初始化为 `availableModels[0].name`，顶栏「模型」下拉可切换。所有 API 调用统一传 `model: selectedModel || undefined`；后端缺省由 `lead_agent._resolve_model_name()` 回退到 `config.yaml` 的 `models[0]`。**内网部署只需在 `config.yaml` 配自家模型即可，前后端均无需改动**。
+- **席位区间硬约束**：推荐弹窗要求 **2 ≤ 选中数 ≤ 8**（`MIN_SELECTED` / `MAX_SELECTED`）。
+- **协调智能体单例（2026-05）**：`COORDINATOR_AGENT_ID = "roundtable-coordinator"` 是固定常量，不再每会话生成新 id。后端 seeder 自动落地，「本次席位列表」改由后端通过 thread 历史 human 消息注入，前端无感。`newCoordinatorName()` 仅作为兼容性壳保留。
+- **总控编排循环上限**：`MAX_CYCLES = 8`，超出后强制停止并 toast。
+- **席位派活策略**：**顺序**（不是并行）。旧实现并行触发多路 SSE 会让浏览器卡顿，现已改为顺序。
+- **调试开关**：`window.__MULTI_AGENT_INIT_TIMING__` 与 `window.__MULTI_AGENT_DEBUG__`（**不是** `__MULTI_AGENT_STREAM_DEBUG__`，文档历史版本有误）。
+
+---
+
+## 1. 功能定位
+
+**页面路由**：`/page/workspace/roundtable/planning`（侧栏「圆桌规划」）
+
+**入口组件**：`src/roundtable-planning/pages/RoundtablePlanningPage.tsx`
+
+**核心能力**：
+
+| 步骤 | 用户目标 | 真实后端对接 |
+|------|----------|--------------|
+| 1 | 与「任务理解智能体」多轮澄清，得到结构化意图 | `intent.ts` |
+| 1→2 | 从候选池选 2–8 个研讨席位 | `recommend.ts` + `RecommendAgentsDialog` |
+| 2 | 总控派活、子智能体顺序交付、可澄清/挂起 | `multi-agent.ts` + 编排循环 |
+| 3 | 查看总控结论、席位交付、产出文件下载 | `HighFidelityReport` + `listSessionArtifacts` |
+
+**步骤门禁**：
+
+- **Step 2**：`intentReady` 非空才可点击（顶栏按钮禁用 + toast 提示）。
+- **Step 3**：`hasConsensus === true` 才可点击。Leader 派活返回空数组才会自然收敛触发 `hasConsensus`，手动跳转的「达成共识生成全案成果」按钮也会校验。
+
+---
+
+## 2. 目录结构
+
+```
+frontend-web/src/roundtable-planning/
+├── index.ts                            # 导出 RoundtablePlanningPage、HighFidelityReport
+├── pages/
+│   └── RoundtablePlanningPage.tsx      # 主页面：组合 hook + 顶栏/侧栏 + 三步路由（≈1 150 行）
+├── api/
+│   ├── intent.ts                       # Step 1：initIntent、streamIntent
+│   ├── recommend.ts                    # 推荐：streamRecommend、filterRecommendCandidates、parseRecommendStreamContent；**+ 推荐历史 listRecommendHistory / saveRecommendHistory**
+│   ├── drafts.ts                       # **草稿后端 CRUD**：listDrafts / getDraft / createDraft / updateDraft / deleteDraft / deriveDraftName（替代旧 localStorage utils/drafts.ts）
+│   └── multi-agent.ts                  # Step 2/3：initMultiAgent、streamMultiAgent、listSessionArtifacts、buildArtifactDownloadUrl
+├── components/
+│   ├── Avatars.tsx                     # 所有 SVG 头像 + getAvatar 选择器
+│   ├── MessageBubble.tsx               # Step 1/2 共享:消息壳 + loading 占位 + 流式 cursor + MD 配置
+│   ├── MessageStepsCard.tsx            # Step 1/2 共享:工具调用 + 思考过程的折叠卡(对齐主聊天 MessageGroup)
+│   ├── Step1Panel.tsx                  # Step 1 对话面板（不含状态,只读 props）
+│   ├── Step2Panel.tsx                  # Step 2 主面板（圆桌对话流 + 澄清条 + 干预输入）
+│   ├── Step3Panel.tsx                  # Step 3 薄壳,内部仍是 HighFidelityReport
+│   ├── PersonaDrawer.tsx               # Step 2 Persona 抽屉（System Prompt / Temp / Model）
+│   ├── IntentClarificationCard.tsx     # Step 1 选项卡片（单选/多选）+ formatIntentClarificationAnswer
+│   ├── RecommendAgentsDialog.tsx       # Step 1→2 推荐弹窗（含流式 rationale + 候选筛选）
+│   ├── HighFidelityReport.tsx          # Step 3 报告 + 文件清单
+│   ├── ArtifactPreviewModal.tsx        # Markdown/纯文本/JSON/CSV/YAML 等文本类文件 in-app 预览
+│   └── ScrollToBottomButton.tsx        # 对话区「回到底部」浮动按钮
+├── hooks/
+│   ├── useAutoScroll.ts                # 滚动跟随 + 用户上滑暂停跟随
+│   ├── useStep1Intent.ts               # Step 1 状态机:init、send、stream、abort、INTENT_READY 同步
+│   ├── useStep2Orchestration.ts        # Step 2 状态机:initMultiAgent + 编排循环 + 对话流管理 + Persona
+│   └── useDraftPersistence.ts          # 草稿(后端版):异步走 api/drafts;自动保存(前进切换)/手动保存/加载/重命名/删除/ensureDraft
+├── lib/
+│   ├── clarification.ts                # resolveAllowMultiple（单选/多选解析）,与主聊天 ClarificationCard 对齐
+│   ├── reasoning.ts                    # splitInlineReasoning:从模型流式文本里提取 `<think>...</think>` 思考过程
+│   ├── roundtable-constants.ts         # 类型(RoleEntry / SelectedAgent) + 常量 + 纯工具函数(buildRoleTemplates / splitIntentReadyBlock 等)
+│   └── step-display.tsx                # Step 2 ChainOfThought 折叠卡图标 + 文案 + 子节点渲染
+├── utils/                              # （旧 drafts.ts 已删除 —— 草稿改走后端 api/drafts.ts）
+└── styles/
+    └── roundtable-planning.css         # 页面主题变量（浅红品牌色 + 深色覆盖）
+```
+
+**模块依赖方向（自上而下）**：
+
+```
+pages/RoundtablePlanningPage
+   ├─ uses → hooks/useStep1Intent
+   ├─ uses → hooks/useStep2Orchestration
+   ├─ uses → hooks/useDraftPersistence  (依赖 step1 / step2 的 getSnapshot + hydrate)
+   ├─ uses → components/Step{1,2,3}Panel  (纯 props 驱动)
+   ├─ uses → components/RecommendAgentsDialog
+   └─ uses → components/Avatars
+
+hooks/useStep1Intent     → api/intent
+hooks/useStep2Orchestration → api/multi-agent + components/PersonaDrawer 的类型
+hooks/useDraftPersistence → utils/drafts + step1/step2 的 Snapshot 类型
+```
+
+主页面通过 ref 桥接两个 hook 之间的依赖（`buildInitialIntent` 在 Step 2 init 时从 Step 1 状态读取），避免 hook 互相引用造成的循环导入。
+
+**路由注册**（`src/pages/WorkspaceRoutes.tsx`）：
+
+```tsx
+<Route path="roundtable/planning" element={<WorkspaceLayout><RoundtablePlanningPage /></WorkspaceLayout>} />
+```
+
+侧栏入口：`src/components/page-sidebar.tsx` → `/page/roundtable/planning`。
+
+**环境变量**（由 `scripts/start-frontend.sh` 注入）：
+
+- `VITE_BACKEND_BASE_URL` → `getBackendBaseURL()`，所有 API 前缀
+- `VITE_LANGGRAPH_BASE_URL` → 本功能**不**直接用 LangGraph SDK，全部走 Gateway 封装
+
+---
+
+## 3. 三步数据流（前端视角）
+
+```
+[进入 Step 1]
+  useEffect → runStep1Init()
+    initIntent(model) → { agent_id, thread_id }
+    setIntentThreadId、setTimelineEntries
+    interactiveMessages seed 欢迎语（本地 seed，非 API）
+
+[用户发送 / 选项卡片提交]
+  sendIntentMessage(text)
+    追加 user 气泡 + agent 占位（streaming + phase）
+    streamIntent({ onTextDelta, onPhaseChange, signal })
+    终态：
+      done + summary       → setIntentReady，解锁 Step 2 / 推荐弹窗
+      clarification        → IntentClarificationCard + pendingIntentClarificationMsgId
+      asking               → 继续对话
+      error                → toast + 红色 (错误) 文案
+
+[点击「进入多智能体研讨」且 intentReady]
+  setIsRecommendDialogOpen(true)
+  RecommendAgentsDialog
+    listAgents() → filterRecommendCandidates()
+    streamRecommend({ onRationaleUpdate, onPicksUpdate, onPhaseChange })
+    用户勾选 2–8 个 → onConfirm(agentIds)
+  handleConfirmAgents
+    setSelectedAgents(agentIds.map(...))
+    step2InitRef.current = false      // 复位 Step 2 init 闸门
+    setCurrentStep(2)
+
+[进入 Step 2]
+  useEffect（step2InitRef 闸门）→ initMultiAgent(SSE)
+    onSeatReady：右侧席位面板逐个「在线」
+    onCoordinatorReady / init_done → threadIds + coordinatorName
+  runOrchestration(buildInitialIntent(), threadIds, coordinatorName)
+    while !cancelled && cycles<8:
+      leader stream → 若 clarification：暂停循环，展示 Step 2 底部澄清条
+      否则 dispatched[] → **顺序** streamMultiAgent(special) → 再 leader 综合…
+      dispatched.length === 0 → hasConsensus = true，可进 Step 3
+
+[进入 Step 3]
+  HighFidelityReport
+      consensusText ← lastLeaderContent
+      seatDeliveries ← step2RoundtableDialogues.filter(d => d.confidence === "子智能体交付")
+      Object.entries(threadIds).filter(name !== coordinatorName).map → listSessionArtifacts(threadId)
+      文本类文件 → ArtifactPreviewModal；其它 → window.open(downloadUrl)
+  ```
+
+  ---
+
+  ## 4. API 层
+
+  ### 4.1 `api/intent.ts` — Step 1
+
+| 函数 | 说明 |
+|------|------|
+| `initIntent(model?)` | `POST /api/intent/init` → `{ status, agent_id, thread_id }` |
+| `streamIntent(req)` | `POST /api/intent/stream`，读 SSE 至终态帧 |
+
+**`StreamIntentRequest` 重要字段**：
+
+- `threadId`：必填，跨多轮对话保持
+- `signal`：必填（页面通过 `intentAborterRef` 控制暂停 / 切步取消）
+- `onTextDelta(text, messageId)`：每个 AI 文本增量
+- `onPhaseChange(phase, toolName?)`：`connecting → connected → streaming|tool_calling`
+- **`onClarification(clarification, index)`（2026-06）**：每解析到一条 `ask_clarification` 工具结果帧就回调一次，让前端**实时**逐个渲染澄清卡。任务理解智能体**一轮可能问多个问题**，这是「实时接收显示协助过程」的关键入口。
+
+**`StreamIntentResult`**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | `"asking" \| "clarification" \| "done" \| "error"` | 终态分支 |
+| `content` | `string` | 完整 AI 文本（含 `[INTENT_READY]` 块） |
+| `summary` | `IntentSummary \| null` | 仅 `done` 有；前端 fallback 也会从 `content` 里用 `splitIntentReadyBlock` 解 |
+| `clarification` | `ClarificationPayload \| null` | **第一个**澄清（向后兼容字段） |
+| `clarifications` | `ClarificationPayload[]` | **本轮全部澄清问题**（2026-06）。来源是流式 `type:"tool"` 帧而非终态帧——**终态帧只带第 1 个**，多问题必须靠它。每条带 `id`（= `tool_call_id`）供前端按题维护选择。 |
+
+**SSE 解析要点**：
+
+- `event: metadata` → phase `connected`
+- `event: messages` + `extractAiTextDelta` → `onTextDelta`
+- `event: messages` + `type:"tool"` 且 `name==="ask_clarification"` → `extractClarificationToolMessage` 解出完整澄清（options 已是 `{id,label}`），按 `tool_call_id` 去重后 `onClarification` 实时回调并收进 `result.clarifications`
+- tool call 帧（`tool_calls` / `tool_call_chunks` 非空）→ phase `tool_calling`（含 `ask_clarification` 工具名）
+- 终态帧识别：`isFinalIntentFrame`（必须有 `status` + `content`）；`status==="clarification"` 且**未**收到任何流式 tool 澄清帧时，才用终态帧字段兜底合成单条澄清
+
+**Abort 行为**：
+
+- `sendIntentMessage` 内建 `AbortController`，保存到 `intentAborterRef`
+- `stopIntentStream()` 用于「暂停」按钮、`currentStep !== 1` 自动调用、`handleStartNewTask`、`handleLoadDraft`
+- 触发 AbortError 时不当作错误：在气泡尾部追加「(已暂停)」并 toast「⏸️ 已暂停任务理解回复」
+
+### 4.2 `api/recommend.ts` — 推荐弹窗
+
+| 函数 | 说明 |
+|------|------|
+| `filterRecommendCandidates(agents)` | 从 `GET /api/agents` 结果剔除 intent / recommender / `roundtable-coordinator-*` |
+| `streamRecommend(req)` | `POST /api/recommend/stream`，无 init（一次性、无状态） |
+| `parseRecommendStreamContent(raw)` | 将累计文本拆成 `{ rationale, picks[] }`，供边流边渲染 |
+
+**`EXCLUDED_AGENT_IDS`** 内置常量（仅 `recommend.ts` 内可见）：
+
+- `roundtable-intent`
+- `roundtable-recommender`
+- 任何以 `roundtable-coordinator-` 开头的 agent_id（动态创建的协调器壳）
+
+**流式 UI 拆分**（与主聊天的 `[RECOMMEND_READY]` 分界类似）：
+
+- 标记常量：`RECOMMEND_READY_MARKER = "[RECOMMEND_READY]"`
+- `parseRecommendStreamContent(raw)`：用 `PICK_OBJECT_PATTERN` 正则增量匹配出已完成的 `{agent_id, reason}` 对象
+- `onRationaleUpdate`：仅 marker 之前的自然语言（弹窗顶部展示）
+- `onPicksUpdate`：从部分 JSON 增量解析 `picks[]`（卡片边流边出，过滤已见 id）
+- 过滤 `TitleMiddleware` 产生的标题增量（`langgraph_node` 含 `TitleMiddleware` 或 `tags` 含 `middleware:title`）
+
+**终态语义**：
+
+- `status === "done"` 且 `picks.length >= 2` → 弹窗用 picks 作为默认勾选
+- 否则 → `phase: "fallback"`，使用 `FALLBACK_AGENT_IDS`（6 个内置 roundtable-* 席位）与候选池交集
+
+### 4.3 `api/multi-agent.ts` — Step 2 & Step 3 文件
+
+| 函数 | 说明 |
+|------|------|
+| `initMultiAgent(payload)` | SSE：`seat_ready`(N 次) → `coordinator_ready` → `init_done` |
+| `streamMultiAgent(req)` | leader / special 一轮 |
+| `listSessionArtifacts(threadId)` | `GET /api/threads/{id}/artifacts` |
+| `buildArtifactDownloadUrl(threadId, virtualPath, { download? })` | 预览或附件下载 URL |
+
+**`initMultiAgent` 事件**（`data:` JSON 的 `event` 字段）：
+
+```ts
+{ event: "seat_ready", agent_name, thread_id, display_name, description }
+{ event: "coordinator_ready", main_agent_name, thread_id }
+{ event: "init_done", main_agent_name, thread_ids }   // thread_ids: Record<agent_name, thread_id>
+{ event: "error", detail }
+```
+
+**`streamMultiAgent` 终态**（`isFinalStatusFrame`）：
+
+| `status` | 含义 | 前端处理 |
+|----------|------|----------|
+| `[["agent","task"], ...]` | 派活列表（数组形态） | **顺序**触发 special；最终用 `nextLeaderTask` 综合 |
+| `[]` | 共识达成（空数组） | `hasConsensus = true`，跳出循环 |
+| `"clarification"` | 总控追问 | `setPendingClarification`，暂停循环 |
+| `"子智能体 X 完成..."` | special 完成 | 更新对应对话气泡 confidence |
+| `"error"` | 失败 | toast + 红色气泡 |
+
+**为什么 special 是顺序而不是并行**：旧版并行触发多路 SSE，每路都在 token 级别对 `step2RoundtableDialogues` 整表 setState，N 个并行 stream 让浏览器卡顿明显。改为顺序后同一时刻只有一个 SSE 在跑，UX 平滑很多（详见 `RoundtablePlanningPage.tsx` 编排循环里的注释）。
+
+**`buildArtifactDownloadUrl` 路径编码**：将 `virtualPath` 按 `/` 切段后逐段 `encodeURIComponent` 再拼回，避免文件名里的中文 / 空格触发后端 404；`download=true` 加在 query string 上而非 path。
+
+**调试开关**：
+
+```js
+window.__MULTI_AGENT_INIT_TIMING__ = true;  // 默认开启；init 各阶段耗时（fetch.start / first-byte / seat_ready#n / coordinator_ready / init_done / total）
+window.__MULTI_AGENT_DEBUG__       = true;  // 默认开启；stream 帧计数 + lastEvent + bad JSON 提示，前缀 [stream:<agentType>:<agentName>]
+```
+
+> ⚠️ 文档历史版本曾写作 `__MULTI_AGENT_STREAM_DEBUG__`，**实际代码并不识别**这个名字。
+
+---
+
+## 5. 主页面状态（`RoundtablePlanningPage`）
+
+> **注意**：自 2026-05 重构后，绝大多数业务状态从主页面下沉到 3 个 hook。下面列出的 state 仍按"位置"分组以便对照原代码，实际所有者请看右列。
+
+| 维度 | 所有者 | 暴露给主页面的方式 |
+|------|--------|-------------------|
+| `currentStep`、`showToast`、`selectedModel`、`roles`、`isRecommendDialogOpen` | 主页面 | useState |
+| Step 1 全部 state + handler | `useStep1Intent` | hook 返回值 |
+| Step 2 全部 state + handler + 编排循环 | `useStep2Orchestration` | hook 返回值 |
+| 草稿(drafts / currentDraftId / 重命名 / 历史下拉) | `useDraftPersistence` | hook 返回值 |
+| `loadedFromDraftRef` 共享 latch | `useDraftPersistence` 拥有,Step 2 init effect 通过 options 读 | hook 间共享 ref |
+
+### 5.1 步骤与门禁
+
+- `currentStep`: `1 | 2 | 3`
+- **Step 2 锁定**：`intentReady == null` 时顶栏 Step 2 按钮禁用（visual + `aria-disabled`），同时点击「进入多智能体研讨」会 toast 「⚠️ 请先与任务理解智能体完成澄清…」
+- **Step 3**：`hasConsensus === false` 时顶栏 Step 3 与底部「达成共识生成全案成果」按钮均禁用
+
+### 5.2 Step 1 关键 state
+
+| 状态 | 用途 |
+|------|------|
+| `intentThreadId` | `/api/intent/init` 返回的线程 id；未就绪前发送按钮置灰 |
+| `intentReady` | `IntentSummary`，驱动 Step 2 初始 prompt + 右侧摘要面板 + 顶栏 step2 解锁 |
+| `interactiveMessages` | 问答气泡列表（user / agent，含 streaming/phase/clarification 元数据） |
+| `pendingIntentClarificationMsgId` | 当前可操作的 agent 消息 id（保证只有最新一条 clarification 展示可点卡片） |
+| `intentClarificationSelections` | `Map<msgId, {selectedIds, custom}>`，多选 / 多消息时各自维护 |
+| `isIntentSending` | 发送中（屏蔽双发 / 显示「暂停」按钮） |
+| `intentAborterRef` | 当前 stream 的 AbortController |
+| `intentInitError` | init 失败信息；驱动右侧角色面板「异常」状态与红色提示 |
+| `step1InitRef` | 闸门：true 即认为已 init 过 |
+| `step1InitGenRef` | **单调递增**的代数标记，详见下文 |
+| `timelineEntries` | 右侧「澄清记录」时间线（init / user 反馈 / 任务意图已明确） |
+
+**`step1InitGenRef` 的存在原因**：
+
+React 18 StrictMode 开发环境下，effect 会 mount → cleanup → mount 两次。早期实现用闭包 `cancelled` 标志做防抖，结果是：第二次 mount 因 `step1InitRef.current === true` 早返回，但第一次 mount 的 async 仍未完成；当它最终 resolve 时，`cancelled` 已被 cleanup 置 true，因此 `setIntentThreadId` 被跳过，右栏卡在「正在上线」。改为单调代数后：每次 `runStep1Init` 自增 `step1InitGenRef`；async 完成时检查 `myGen === step1InitGenRef.current`，等价于「我是当前最新一次 init」，否则丢弃结果。这也覆盖了「新建任务 / 加载草稿期间旧 init 晚归」的场景。
+
+**`splitIntentReadyBlock(text)`**（页面内工具函数，使用 `INTENT_READY_RE` 正则）：
+
+- 从气泡正文解析 `[INTENT_READY]\n```json\n{...}\n``` ` 块
+- 返回 `{ before, summary, after }`，前后文与结构化卡片分别渲染
+- 单独的 `useEffect` 监听 `interactiveMessages`：若已存在含 `[INTENT_READY]` 的 agent 消息但 `intentReady` 仍为 null（极少数终态帧丢 summary 的场景），主动 `setIntentReady`，与后端 "READY 优先" 对齐
+
+### 5.3 推荐与 Step 2 席位
+
+| 状态 | 用途 |
+|------|------|
+| `selectedAgents` | `{ agent_id, name }[]`，默认 `DEFAULT_SELECTED_AGENTS`（6 内置） |
+| `roleTemplates` / `roles` | 右侧席位面板（`buildRoleTemplates`，commander 占 id=1，agents 从 id=2 开始） |
+| `agentNameToRole` | 流式输出时根据 `agent_name`（小写）反查 speakerId、avatarType、displayName |
+| `roundtableAgentIds` | `selectedAgents.map(a => a.agent_id)`，传给 `/api/multi-agent/init` 的 `agent_names` |
+| `threadIds` / `coordinatorName` | `/api/multi-agent/init` 结果；离开 Step 2 **不**清空，允许回来继续看 |
+| `step2RoundtableDialogues` | Step 2 对话流（含 `streaming` / `confidence` / `time` / `avatarType`） |
+| `lastLeaderContent` / `hasConsensus` | Step 3 总控结论 + 共识标记 |
+| `pendingClarification` | Step 2 总控澄清（复用 `ClarificationPayload`） |
+| `clarificationDraft` | 底部自定义回答输入框（受 `allowCustom` 控制） |
+| `isRoundTableRunning` | 用户挂起 / 恢复协商的 UI 开关 |
+| `isOrchestrating` | 编排循环正在 run（屏蔽并发触发） |
+| `orchestrationCancelRef` | 与 `abortAllInFlight` 配合中断当前循环 |
+| `activeAbortersRef` | 当前 Step 2 所有 in-flight stream 的 AbortController 集合 |
+| `activeSpeakerId` / `activeSpeakerSet` | 圆桌可视化高亮：单 leader 时用单值，多席位并行时用 Set |
+| `selectedAgentId` | 当前 Persona 抽屉所在的席位 id（点击圆桌头像打开） |
+| `agentConfigs` | `Map<seatId, {model, weight, prompt, temp}>` Persona 覆盖；下一轮该席位的派活会用此 model |
+| `isUpperPanelCollapsed` | 是否折叠圆桌可视化 + 调控台，给对话区让出垂直空间 |
+
+**协调智能体命名（2026-05 改造）**：现在是**固定单例 id** `roundtable-coordinator`（见 `lib/roundtable-constants.ts::COORDINATOR_AGENT_ID`）。`newCoordinatorName()` 函数为兼容性保留，内部直接返回这个常量字符串。后端 `ensure_roundtable_functional_agents()` 缺失自动落地，不再每次新建。`filterRecommendCandidates` 在 `EXCLUDED_AGENT_IDS` 集合里同时排除：
+
+- `roundtable-coordinator`（新版单例 id，永远过滤）；
+- `roundtable-coordinator-*` 前缀（历史残留，管理员清理之前先在 UI 隐藏）。
+
+> 历史草稿兼容性：用户加载 2026-05 前保存的草稿时，存储的 `coordinatorName` 仍是 `roundtable-coordinator-<ts36>` 形式。只要那个旧 agent 目录还在磁盘上（即运维没手动删过），加载后继续在 Step 2 干活就能正常工作；如果旧 agent 被清理掉了，需要让用户「重新起草」从头跑一遍 Step 1 → Step 2。
+
+### 5.4 编排循环 `runOrchestration(seedMessage, ids, coord)`
+
+伪代码：
+
+```
+isOrchestrating = true
+orchestrationCancelRef = false
+nextLeaderTask = seedMessage
+cycles = 0
+MAX_CYCLES = 8
+
+while !cancelled && cycles < MAX_CYCLES:
+  cycles += 1
+  highlight(speakerId=2)   // 总控
+  leaderBubble = appendStreamingDialogue("总控协调", confidence: "调度中")
+  res = streamMultiAgent(leader, ids, coord, nextLeaderTask, onTextDelta, onPhaseChange)
+
+  if res.clarification:
+    finalize(leaderBubble, content, "等待用户澄清")
+    setPendingClarification(res.clarification)
+    break        // 等用户回复后由 submitClarification 重启循环
+
+  finalize(leaderBubble, content, dispatched.length === 0 ? "全案盖印" : "派活说明")
+  if res.content: setLastLeaderContent(res.content)
+
+  if res.dispatched.length === 0:
+    setHasConsensus(true); setConsensusPercentage(100); break
+
+  for [subName, task] of res.dispatched:        // **顺序**，不是并行
+    meta = agentNameToRole[subName.toLowerCase()]
+    markSpeakerStreaming(meta.speakerId)
+    perSeatModel = agentConfigs[meta.speakerId]?.model || DEFAULT_MODEL
+    subBubble = appendStreamingDialogue(meta.displayName, confidence: "调度中")
+    specRes = streamMultiAgent(special, ..., perSeatModel, signal=subAborter)
+    finalize(subBubble, specRes.content, "子智能体交付")
+    markSpeakerIdle(meta.speakerId)
+    if cancelled: break
+
+  setConsensusPercentage(prev => min(95, prev + 8))
+  nextLeaderTask = "各子智能体已就上一轮派活完成交付,请你结合最新结论..."
+
+if cycles >= MAX_CYCLES:
+  toast("⏱️ 已达到最大研讨轮次,自动停止以避免循环")
+
+clearAllStreamingSpeakers()
+isOrchestrating = false
+```
+
+要点：
+
+- **`buildInitialIntent()`**：
+  - 有 `intentReady` → 拼装 `objective / 约束条件 / 关键假设` + 「不要再反问用户」终结语
+  - 无 `intentReady`（用户跳过澄清 / 顶栏直接切到 Step 2）→ 拼接 Step 1 内 `interactiveMessages` 里 sender==='user' 的内容，逐行 `用户#N: ...`，**绝不**注入 mock 的「预算 500 万 / 72 小时」数字
+  - 用户输入完全为空 → 让总控先调用 `ask_clarification` 而不是凭空派活
+- **用户「干预研审」**：`handleInjectToRoundtable` 追加一个「💡 (人工指令介入) ...」气泡，然后构造 `runOrchestration("用户人工干预新指令:...", ...)`
+- **挂起 / 恢复**：
+  - 挂起 = `setIsRoundTableRunning(false)` → `stopOrchestration()` → `orchestrationCancelRef = true` + `abortAllInFlight()`
+  - 恢复 = `setIsRoundTableRunning(true)`，effect 触发 `runOrchestration("用户已恢复研讨,请继续上一轮的协调工作。", ...)`
+- **澄清恢复**：`submitClarification` 把用户回答拼到 prompt 里再 `runOrchestration`，不会重建 thread
+
+### 5.5 Persona 抽屉（Step 2 圆桌可视化点击）
+
+- 点击圆桌头像 → `setSelectedAgentId(seatId)` → 在上半部分下方展开抽屉
+- 抽屉控件：
+  - **System Prompt**：仅前端记录（后端覆写未开放）
+  - **Temp**：仅前端记录
+  - **推理模型**：选项来自 `useModels()`；显示值优先级 `agentConfigs[seat]?.model > selectedModel`
+- 「参数覆盖并重启动算研讨」按钮 → `handleSaveAgentAndRecalculate`：
+  - 把新的 `(seatId, model)` 写入 `agentConfigs`
+  - 追加一条「⚡ [模型偏好已保存] ...」对话气泡
+  - **不**立即重启编排；下一轮该席位被派活时 `runOrchestration` 内会读 `agentConfigs[meta.speakerId]?.model || selectedModel || undefined` 作为 special 调用的 `model` 参数
+
+### 5.6 全局模型选择器（右侧 sidebar 顶部）
+
+- **位置**：右侧 sidebar `currentStep !== 3` 时显示的第一个面板 —— 在「当前意图摘要」**正上方**。Step 3 时整个 sidebar 切换成「最终共识结论 / 风险与预算摘要 / 导出与交付」，所以模型选择器仅在 Step 1 / Step 2 可见（此时也是唯一会发起新模型调用的阶段）
+- **state**：`const [selectedModel, setSelectedModel] = useState<string>("")`
+- **初始化**：`useEffect(() => ...)` 在 `availableModels` 首次返回后把 `selectedModel` 设为 `availableModels[0].name`；后端配置变化导致当前选中 model 不在列表里时也回退到首项
+- **传参规则**：所有 5 个 API 调用点（`initIntent` / `streamIntent` / `streamRecommend` / `initMultiAgent` / `streamMultiAgent` leader / `streamMultiAgent` special）都传 `selectedModel || undefined`；special 还会先看 `agentConfigs[seat]?.model` per-seat 覆盖
+- **禁用态**：`availableModels.length === 0` 或 `modelsLoading` → `disabled`，placeholder 显示「加载中…」或「未配置模型」
+- **可改换为 Radix Select**：当前用原生 `<select>` 与 Persona 抽屉保持一致；如需统一样式可改为 `@/components/ui/select`，行为不变
+
+### 5.7 草稿持久化（`api/drafts.ts` + 后端 MySQL，2026-06 改造）
+
+> **重大变更**：草稿从浏览器 `localStorage` 迁到**后端 MySQL**，按登录用户隔离、跨设备/会话保留。旧 `utils/drafts.ts` 已删除；`useDraftPersistence` 仍保持对外接口不变（列表项含 `name`，由后端 `title` 映射而来），主页面无需改动。后端表/路由见 backend doc「圆桌草稿持久化」。
+
+- **API 客户端 `api/drafts.ts`**：`listDrafts()`（轻量元数据）/ `getDraft(id)`（全量 step1+step2）/ `createDraft` / `updateDraft`（partial）/ `deleteDraft` / `deriveDraftName`。snake_case↔camelCase 映射在这一层收口（后端 `furthest_step/created_at/updated_at` ↔ 前端 `furthestStep/...`）。
+- **快照形状**：`DraftStep1Snapshot.{intentThreadId, intentReady, interactiveMessages, timelineEntries}`、`DraftStep2Snapshot.{selectedAgents, threadIds, coordinatorName, step2RoundtableDialogues, lastLeaderContent, hasConsensus, consensusPercentage, budgetLimit, seatStubMessages, orchestrationMode?, chain?}`；以 JSON 整存进后端 `step1`/`step2`（`PortableLongText`/LONGTEXT，避免大对话超 64KB）。
+  - **`selectedAgents`（2026-06 修复）**：本次研讨实际选中的席位。**不存的话加载草稿后 Step 2/3 左侧「参与角色」会回退到 `DEFAULT_SELECTED_AGENTS`（默认 6 个）而非当时真正选的那几个** —— `roleTemplates`/`agentNameToRole` 都由 `selectedAgents` 派生。`useStep2Orchestration.hydrateFromDraft` 在该字段非空时 `setSelectedAgents`，老草稿（无此字段）保持当前值不强行覆盖。
+  - **`orchestrationMode?` / `chain?`（2026-06 业务链条）**：Step 2 编排模式（`recommend`=总控自由派活 / `chain`=按业务链条顺序派活）+ 来源链条 `{id,title}`。是**主页面 state**，由页面在 `getStep2Snapshot` 写入、在**包裹版 `hydrateStep2`** 里读出后 `setOrchestrationMode`/`setChainMeta`（step2 hook 的 `hydrateFromDraft` 不直接消费）。老草稿无字段 → 默认 `recommend`。业务链条完整设计见 `multi-agent-business-chain-dev.md`。
+- `deriveDraftName({intentReady, interactiveMessages})`：优先 `intentReady.objective`，否则第一个 user 消息，否则 `未命名草稿 <时间>`，截断 40 字。**仅在 create 时写一次**（见下方 bug 修复）。
+- **列表加载**：挂载时 `useEffect` 调 `listDrafts()`；增删改后 `refreshList()` 重拉。
+- **自动保存策略**：仅在「前进」步骤切换时保存（1→2、2→3），后退不触发。
+- **手动保存 / `ensureDraft`**：`handleManualSave` 走同一条保存队列；`ensureDraft(furthestStep?)` 幂等保证后端有一条对应草稿并返回 id（**推荐弹窗打开前调用**，让推荐历史有 `draft_id` 归属）。
+- **加载草稿 `handleLoadDraft`**：
+  - 走 `getDraft(id)` **实时拉服务端最新全量**（不再读内存里可能过期的列表快照）；404 → toast「草稿已不存在」并刷新列表。
+  - **先**置 `loadedFromDraftRef.current = true`，再 `setCurrentStep(draft.furthestStep)`（顺序不能反）。
+  - `setStep2InitGate(draft.furthestStep >= 2)`：曾走到 Step 2 才跳过自动 init。
+  - 角色面板基线：被恢复时全部「在线」，否则 init 流程逐个「在线」。
+
+**本次随手修复的 4 个旧 localStorage 版 bug**（对接后端时一并解决）：
+
+1. **自动保存覆盖手动重命名** —— 现在所有 `updateDraft` 一律**不带 title**；标题只由 create（派生）与显式「重命名」改写。
+2. **快速连续前进（1→2→3）产生重复草稿** —— 所有保存经一条**串行队列**（`saveQueueRef`）+ 同步镜像 `currentDraftIdRef`，create 完成即写 id，后续保存读到 id 走 update 而非再 create。
+3. **加载读到内存旧列表快照** —— 改为 `getDraft(id)` 实时拉。
+4. **localStorage 配额静默写失败 / 数据丢失** —— 迁后端后不复存在。
+
+---
+
+## 6. 组件说明
+
+### 6.1 `IntentClarificationCard`
+
+- Props：`payload`（`ClarificationPayload`）、`selection`、`onSubmit(overrideSelection?)`、`disabled`、`submitting`、`fallbackContent`、**`deferSubmit?`（2026-06）**
+- **单选**（默认 `allowMultiple === false`）：`resolveAllowMultiple` 返回 false → 点击选项即 `onSubmit({selectedIds:[id], custom: ""})`，UI 不显示「发送回答」按钮（除非 `allowCustom`）
+- **多选**：勾选多个 + 输入补充，再点「发送回答」；答案格式见 `formatIntentClarificationAnswer`：
+  - 仅选项 → `我选择：A、B`
+  - 仅自定义 → 直接发自定义文本
+  - 同时存在 → `我选择：A、B；补充：…`
+- **单问题 vs 多问题的判断（2026-06）**：`Step1Message` 按 `clarifications.length` 分流，**默认单选**（后端 `allow_multiple` 缺省 false，`resolveAllowMultiple` 兜底）：
+  - **单问题（最常见）**：`deferSubmit={false}`，沿用原交互 —— 单选**点击选项即发送**；多选 / 允许自定义则走卡片自带的「发送回答」按钮。**不**显示合并按钮。
+  - **多问题**：`deferSubmit={true}` —— 连单选点击也只**记录**选择（不立即发送），卡片自身隐藏按钮；父组件在卡片下方渲染**一个**「发送全部回答」按钮，统一提交。
+  - 该判断纯在前端（不动工具/后端）：依据 `clarifications.length` + `allow_multiple`，后端 `ask_clarification` 本就默认单选。
+- **合并提交逻辑**：`submitIntentClarifications(msgId, clarifications, overrideByKey?)` 逐题取选择、格式化、拼成一条消息（多题带 `1. <问题>\n答:<答案>` 编号；单题直接发答案；至少答一题才发）。`overrideByKey` 供「单题单选点击即发送」用——此时选择还没写进 state map（setState 异步），把即时选择按 `clarificationKey` 传进去直接用。
+  - **逐题选择隔离**：选择 Map 改为 `Map<string, IntentClarificationSelection>`，key 由 `clarificationKey(msgId, clar.id, index)` 生成（`clar.id` = `tool_call_id`，缺省退化为 `idx-N`）。
+- 展示条件：`isAgent && clarifications.length>0 && !intentReady && !parts.summary`；**流式期也展示**（卡片 `disabled`，只读，体现「协助过程」实时出现），仅当终态且 `pendingIntentClarificationMsgId === msg.id && !streaming` 时才可交互。出现 `[INTENT_READY]` / summary 后隐藏。
+- **步骤链强化**：`onClarification` 同时往 `msg.steps` 追加一条 `追问 N:<问题>`，让 `MessageStepsCard` 把每个 `ask_clarification` 调用显示成独立步骤。
+
+### 6.2 `RecommendAgentsDialog`
+
+> **席位来源选择器（2026-06 业务链条）**：弹窗顶部加了**模式分段切换** `智能推荐 | 业务链条`。智能推荐 = 本节描述的现状（零行为变更，整体收进 `{mode==="recommend"}` 分支）；业务链条 = `BusinessChainPicker`（选一条已配置链条，卡片标题 + 彩色席位 tag + `→` 箭头）。`onConfirm` 统一回传 `SeatSelectionResult{ agents, mode, chain? }`；`mode==="chain"` 时 Step 2 由总控**按链条顺序派活**（`useStep2Orchestration.runChainOrchestration`）。配置页与编排详见 `multi-agent-business-chain-dev.md`。
+
+- **新增 `draftId` prop（2026-06）**：本次推荐归属的草稿/会话 id。由主页面在打开弹窗前 `await drafts.ensureDraft(1)` 拿到并传入（见 §6.6）。`null` 时退化为「直接推荐、不存历史」的旧行为。
+- 打开时管线（`start(forceFresh=false)`）：`listAgents() → filterRecommendCandidates()` → **若 `draftId` 有历史 → `listRecommendHistory()` 取最近一次直接展示（不重跑模型）**；否则 `streamRecommend()` 跑新推荐。
+- 阶段 UI（`InternalState.phase`）：
+  - `idle` → `loading_agents` → **`loading_history`** → **`history`**（展示上次推荐，可直接进入研讨或「重新分析」）
+  - 或 `loading_agents` → `recommending`（顶部「模型生成内容」流式；推荐卡 streaming=true）→ `ready` / `fallback` / `error`
+- **推荐历史（会话级）**：
+  - 打开时若该 `draftId` 有历史，进入 `history` 态：蓝色提示条标注上次推荐时间，picks 默认勾选、rationale 回显，**不**自动重跑模型。
+  - 「**重新分析**」按钮（`history` 态显示该文案，其它态为「重新推荐」）→ `start(true)` 强制跑新推荐，跳过历史。
+  - 每次**新推荐**完成（`ready`/`fallback`）后 `saveRecommendHistory(draftId, {objective,status,model,rationale,picks,candidates})` best-effort 追加一条（失败仅告警不阻断）。
+  - `history`/`fallback`/`ready` 三态都允许 `onConfirm`（用户可直接采纳历史 picks）。
+- **布局分两段**：
+  - **顶部「模型生成内容」**：`RecommenderOutput` —— 状态行（`spinner + 调度推荐 / 已连接 / 正在生成`）+ `MessageStepsCard` 步骤卡 + `ReasoningBlock`（从 `<think>` 拆出来）+ markdown rationale + 末尾 `StreamingCursor`。视觉与 Step 1/Step 2 气泡的内容区一致，参考主聊天 `chats/new`。
+  - **底部「推荐参会智能体」**：候选卡片(`AgentCard`),分「推荐参会 / 其他候选」两组。
+- 选择约束：`2 ≤ selected ≤ 8`；底部实时显示「至少再选 N 个」「已选 X / 8」
+- 失败兜底：候选为空 → error；status==="asking" 或 picks 不足 2 → `fallback`，自动用 `FALLBACK_AGENT_IDS` 与候选池交集勾选
+- 反竞态：内部 `generationRef`，每次 `start()` 自增，所有 setState（含历史读取/流式回调）都校验 `myGen === generationRef.current`，避免「重新分析」时旧 stream / 旧历史写脏 state
+- `onConfirm(agentIds)` → 父组件 `handleConfirmAgents`：复位 `step2InitRef` 并 `setCurrentStep(2)`，触发 Step 2 init
+
+### 6.3 `HighFidelityReport`（Step 3）
+
+- 输入：`threadIds`、`coordinatorName`、`consensusText`、`hasConsensus`、`seatDeliveries`、`seatNameMap`、`onReset`
+- `seatThreadEntries`：过滤掉 `coordinatorName`，给每个 sub-thread 拉一次 `listSessionArtifacts`（`Promise.all` 并行）
+- `reloadKey`：「刷新文件清单」按钮自增，触发 effect 重新拉
+- **文件预览策略**（`shouldPreviewInModal`）：
+  - 命中 → `ArtifactPreviewModal`（Markdown 用 react-markdown 渲染，其它当 plain text）
+  - 不命中（pdf / png / html / 二进制）→ `window.open(buildArtifactDownloadUrl)`，交给浏览器原生 viewer
+  - 命中规则：
+    - mimeType 是 `text/markdown` / `text/plain` / `text/csv` / `application/json` / `text/*`
+    - 或文件名后缀属于 `md / markdown / txt / json / csv / log / yml / yaml / xml`
+- 各席位最终交付（中段折叠区）数据源：父组件传入的 `seatDeliveries`，按发送者去重（后到的覆盖前者）
+- 「重新起草」→ 父组件 `handleStartNewTask`（清空并 `runStep1Init`）
+- 「打印 / 另存 PDF」→ `window.print()`，浏览器原生流程
+- **Step 3 不显示左侧栏（2026-06）**：`LeftSidebar` 在 `currentStep === 3` 时 `return null`（原「参与与结论贡献」列已移除），右侧栏在 Step !== 1 时本就 `return null`，因此中间 `middle-viewport`（`flex-1`）会自适应撑满整行，报告区获得最大宽度。
+
+### 6.4 `ArtifactPreviewModal`
+
+- 通过 `buildArtifactDownloadUrl(threadId, path)`（不带 `download=true`）GET 文件正文
+- Markdown 文件（mime===`text/markdown` 或后缀 `.md/.markdown`）→ react-markdown + remark-gfm
+- 其它文本类 → `<pre>` 直出
+- 头部「下载」按钮单独走 `download=true` URL，触发浏览器附件下载
+- 关闭：Esc / 点击外层遮罩（精确匹配 `e.target === e.currentTarget`，避免内部冒泡误关）
+
+### 6.5 共享 UI 模式与辅助
+
+- **三段式流式气泡**：`appendStreamingDialogue` → `appendToDialogue`（仅追加增量）→ `finalizeDialogue`（设最终 content + confidence + `streaming=false`）。三函数都通过 `id` 匹配，避免数组下标错位
+- **Phase 到中文文案**：`phaseLabel(phase, agentType, toolName)`：
+  - `connecting` → 「调度中」
+  - `connected` → 「已连接,等待响应」
+  - `tool_calling` 按 toolName：`agent_orchestration → 正在派活`、`ask_clarification → 正在提问`、`present_files → 正在交付文件`，其它 → 「调用工具:<name>」
+  - `tool_result` → 「处理工具结果」
+  - `streaming` → leader 时「正在派活说明」、special 时「正在输出」
+  - Step 1 的 `intentPhaseLabel`：`ask_clarification → 正在生成追问`、`streaming → 正在思考问题`
+- **Markdown 渲染**：Step 1 / 2 / 3 都用 `react-markdown` + `remark-gfm`，自定义紧凑间距的 `components`（`p` 用 `my-1 whitespace-pre-wrap` 等）
+- **自动滚动**：`useAutoScroll(ref, [list])` 跟随；用户上滑后停止跟随；`ScrollToBottomButton` 一键回底
+- **`activeSpeakerSet`**：圆桌可视化里多席位同时高亮需要 Set，单 leader 时仍可用 `activeSpeakerId`；两者均触发 ring 动画
+- **状态条颜色**：`研讨中` 红 / `在线` 绿 / `已完成` 绿勾 / `正在上线` 黄旋 / 其它灰
+
+---
+
+## 7. 澄清交互（与主聊天对齐）
+
+| 能力 | 实现位置 |
+|------|----------|
+| 结构化 payload 类型 | `multi-agent.ts` → `ClarificationPayload`（intent.ts 复用） |
+| 单选/多选 | `lib/clarification.ts` → `resolveAllowMultiple`（缺省单选） |
+| 答案拼接 | `formatIntentClarificationAnswer`（`IntentClarificationCard`） |
+| Step 1 卡片 | `IntentClarificationCard` + `submitIntentClarification` |
+| Step 2 卡片 | 页面底部 `pendingClarification` 区块 + `submitClarification` → 再 `runOrchestration` |
+| 主聊天参考 | `src/components/workspace/messages/message-list.tsx` → `ClarificationCard` |
+
+后端字段 `allow_multiple` 缺省为 **false**（单选、点击即发送）。
+
+**关键差异**：
+
+- Step 1 用 `IntentClarificationCard` 组件（嵌在气泡里），Step 2 直接在页面底部渲染 amber 色带（**没有**抽象成独立组件，紧贴对话区）。
+- Step 2 澄清回复后**不**重建 thread；新 prompt 自带「用户已回复你刚才的澄清问题。问题:... 用户回答:...」上下文。
+
+---
+
+## 8. 与主聊天的差异
+
+| 维度 | 主聊天 `/page/workspace/chats/new` | 圆桌规划 |
+|------|-----------------------------------|----------|
+| SDK | `@langchain/langgraph-sdk` 直连 | 自研 SSE 解析（`apiFetch` + ReadableStream） |
+| 澄清展示 | `message-list` ToolMessage `additional_kwargs` | 终态帧 `status: "clarification"` |
+| Agent | 用户可选 assistant | 内置 intent + 动态 coordinator + 可选席位 |
+| 线程 | 单 thread | Step 1 一线程；Step 2 每席位 + 协调各一线程 |
+| 终态语义 | LangGraph state | 自定义 `{status, content, ...}` 终态帧 |
+| 暂停 | LangGraph interrupt | `AbortController.abort()` |
+
+复用思路：澄清卡片交互、答案文案格式；**不要**假设能直接复用 LangGraph React hooks。
+
+---
+
+## 9. 关键交互清单
+
+| 交互 | 行为 |
+|------|------|
+| Step 1 发送 | Enter 发送（Shift+Enter 换行）；发送中显示「暂停」 |
+| Step 1 暂停 | `stopIntentStream()`，气泡尾部追加 `(已暂停)` 并 toast |
+| Step 1 进入 Step 2 | 需 `intentReady`；打开推荐弹窗而非直接切步 |
+| Step 1 跳过此项 | 仅本地追加「系统」气泡，不发请求；适合演示 |
+| Step 2 init | 首次进入自动 SSE init；离开 Step 2 **不**销毁 `threadIds`（可返回继续看，不会二次 init） |
+| Step 2 挂起/恢复 | `isRoundTableRunning` + `stopOrchestration` / 恢复时再 leader 一轮 |
+| Step 2 干预 | 底部输入框 → `runOrchestration` 新 seed，wrap 进「用户人工干预新指令:...」 prompt |
+| Step 2 Persona | 点圆桌头像打开抽屉；保存后下一轮该席位使用所选模型 |
+| 新建任务 | `handleStartNewTask`：abort 全部、清 state、`runStep1Init`，与 Step 3「重新起草」共用 |
+| 历史草稿 | 顶栏下拉：加载 / 重命名 / 删除（删除带 `window.confirm`） |
+| Step 3 预览 | 文本类 → 模态预览；其它 → 新窗口下载 |
+
+---
+
+## 10. 类型与常量速查
+
+```ts
+// Step 1 输出 → Step 2 输入
+interface IntentSummary {
+  objective: string;
+  constraints: string[];
+  assumptions?: string[];
+}
+
+// Step 2 线程映射（init_done.thread_ids）
+type ThreadIdMap = Record<string, string>;
+
+// 派活
+type LeaderDispatch = [string, string]; // [agent_name, task]
+
+// 当前选中的研讨席位
+type SelectedAgent = { agent_id: string; name: string };
+
+// Step 1 单条澄清问题
+interface ClarificationPayload {
+  question: string;
+  clarificationType: string;
+  context: string;
+  options: unknown[];
+  allowCustom: boolean;
+  allowMultiple?: boolean;
+}
+
+// Step 2 stream 终态
+interface StreamMultiAgentResult {
+  dispatched: LeaderDispatch[];
+  message: string | null;
+  content: string;
+  agentName: string | null;
+  clarification: ClarificationPayload | null;
+}
+```
+
+**核心常量**：
+
+| 常量 | 值 | 位置 |
+|------|----|------|
+| `COMMANDER_SEAT_ID` | `1` | RoundtablePlanningPage |
+| `MAX_CYCLES` | `8` | RoundtablePlanningPage（`runOrchestration` 内） |
+| `MIN_SELECTED` / `MAX_SELECTED` | `2` / `8` | RecommendAgentsDialog |
+| `FALLBACK_AGENT_IDS` | 6 内置 roundtable-* | RecommendAgentsDialog |
+| `BUILTIN_AGENT_META` | 6 内置头像/中文名 | RoundtablePlanningPage |
+| `FALLBACK_AVATAR_TYPES` | `[blue, purple, emerald, amber, pink]` | RoundtablePlanningPage |
+| ~~`STORAGE_KEY`~~ | 已废弃 —— 草稿改存后端 `/api/roundtable-drafts`，不再用 localStorage | （旧 utils/drafts.ts，已删除） |
+| `INTENT_READY_RE` | `/\[INTENT_READY\]\s*```json\s*(\{[\s\S]*?\})\s*```/` | RoundtablePlanningPage |
+| `RECOMMEND_READY_MARKER` | `"[RECOMMEND_READY]"` | recommend.ts |
+| `EXCLUDED_AGENT_IDS` / 前缀 | `roundtable-intent`、`roundtable-recommender`、`roundtable-coordinator-*` | recommend.ts |
+
+---
+
+## 11. 故障排查
+
+| 现象 | 可能原因 | 排查 |
+|------|----------|------|
+| Step 1 一直「等待澄清」但气泡里出现绿色 [INTENT_READY] 摘要 | 终态帧未带 `summary` | 看 `splitIntentReadyBlock` + 同步 `useEffect`，必要时手动刷新 |
+| Step 1 角色面板卡在「正在上线」 | StrictMode 双 mount 导致 init 异步被丢弃 | 已用 `step1InitGenRef` 修复；检查是否被改坏 |
+| 选项全是多选 | `allow_multiple` 未传或为 true | Network 终态帧；`resolveAllowMultiple` |
+| Step 2 init 卡住 | init SSE error / 代理 | Network `init`；控制台 `[init-timing]` |
+| Step 2 stream 看不到任何文字 | TitleMiddleware 过滤错杀 / phase 卡在 connecting | 控制台搜 `[stream:` 前缀（需 `__MULTI_AGENT_DEBUG__`） |
+| 总控不派活 | `dispatched` 一直 `[]` 且非 clarification | 看 leader 终态帧；模型 SOUL 配置 |
+| 推荐弹窗为空 | `filterRecommendCandidates` 把所有候选都过滤了 | `GET /api/agents` 列表；检查 `EXCLUDED_AGENT_IDS` |
+| 推荐弹窗一直「等待推荐结果」 | recommender 模型死循环 | 控制台看 `[stream:` 日志，或点「重新推荐」 |
+| Step 3 各席位文件为空 | 子 agent 未写 outputs 或 thread id 错 | 对应 thread 调 `listSessionArtifacts` |
+| Step 3 预览空白 | 文件不是文本类，但被错误命中 `shouldPreviewInModal` | 检查 mime + 后缀；不在白名单的应该跳 `window.open` |
+| Step 3 文件名乱码 / 404 | `buildArtifactDownloadUrl` 编码错 | 看 path 是否被分段 encode；不能整体 encode（会把 `/` 也编了） |
+| 草稿加载后重复 init | `loadedFromDraftRef` 未置位 | `handleLoadDraft` 流程，注意 ref 必须先于 `setCurrentStep` |
+| 顶栏 Step 2 / Step 3 一直灰 | `intentReady` / `hasConsensus` 没设上 | 看终态帧；leader.dispatched 是否真为 `[]` |
+| Persona 抽屉改模型不生效 | 下一轮才生效 / 抽屉 model 未传给 streamMultiAgent | 看 `agentConfigs[meta.speakerId]?.model` 的传递路径 |
+| 并行 SSE 卡顿 | 误改为 parallel 派活 | 保持顺序 dispatch，详见 §5.4 注释 |
+
+**本地调试开关**：
+
+```js
+window.__MULTI_AGENT_INIT_TIMING__ = true;  // init 各阶段耗时（默认开）
+window.__MULTI_AGENT_DEBUG__       = true;  // stream 帧计数（默认开）
+```
+
+---
+
+## 12. 扩展指南
+
+### 12.1 新增默认研讨席位
+
+1. 后端 `.deer-flow/agents/roundtable-xxx/`
+2. `BUILTIN_AGENT_META` + `DEFAULT_SELECTED_AGENTS` + `RecommendAgentsDialog` 的 `FALLBACK_AGENT_IDS`
+3. 无需改 API 层（`agent_names` 由推荐结果传入）
+
+### 12.2 调整 Step 1 澄清轮次上限
+
+逻辑在 agent SOUL，不在前端；前端只需处理任意轮 `asking` / `clarification` / `done`。
+
+### 12.3 调整 Step 2 编排上限
+
+`RoundtablePlanningPage.tsx` 内 `MAX_CYCLES = 8`，超出会 toast「⏱️ 已达到最大研讨轮次,自动停止以避免循环」。若放宽：注意 `step2RoundtableDialogues` 数组会线性增长，超长讨论需要考虑虚拟滚动。
+
+### 12.4 把 special 改回并行
+
+不推荐；若一定要做：
+
+- 把 `for ... of leaderRes.dispatched` 改成 `await Promise.all(leaderRes.dispatched.map(...))`
+- 评估浏览器性能：每 token 一次 `setStep2RoundtableDialogues(prev => prev.map(...))`，N=6 时实测明显掉帧
+- 用更高效的派发结构（如按 id 分桶 `Map<id, Bubble>` + ref 缓存）改善之后再启用
+
+### 12.5 接入真实 Persona 覆盖
+
+当前 prompt / temp 只在前端记录；要落地需：
+
+- 后端开放 per-agent override 接口或在 `streamMultiAgent` 新增 `prompt_override` / `temperature` 字段
+- 前端：`agentConfigs[meta.speakerId]` 一并传入
+
+### 12.6 拆分页面（已完成 · 2026-05）
+
+主页面早期是 4 000+ 行单文件,2026-05 重构按"hooks 抽逻辑、components 抽 UI"原则拆分:
+
+- `hooks/useStep1Intent.ts` —— Step 1 全部状态机、init effect、INTENT_READY 同步
+- `hooks/useStep2Orchestration.ts` —— Step 2 状态、编排循环、对话流、Persona、澄清
+- `hooks/useDraftPersistence.ts` —— 草稿自动保存 / 手动保存 / 加载 / 重命名 / 删除
+- `components/Step{1,2,3}Panel.tsx` —— 纯 UI,只接收 props,不持有业务状态
+- `components/PersonaDrawer.tsx` —— Persona 抽屉
+- `components/Avatars.tsx` —— 所有 SVG 头像 + getAvatar
+- `lib/roundtable-constants.ts` —— 常量、类型、纯工具函数(buildRoleTemplates 等)
+- `lib/step-display.tsx` —— ChainOfThought 折叠卡的图标 + 文案 + 子节点渲染
+
+**主页面只保留**:顶栏(StepNavigation / HistoryDropdown)、左右两侧栏(LeftSidebar / RightSidebar)、步骤路由、推荐弹窗,以及编排 hook 与跨步 handler(`handleConfirmAgents` / `handleStartNewTask`)。
+
+继续重构请遵守:
+
+1. **不要在 Panel 组件里写 fetch / setState 业务流程** —— Panel 只渲染,事件透传到 hook。
+2. **hook 之间不要互相 import** —— 跨 hook 的数据通过主页面的 ref / callback 桥接(参考 `buildInitialIntent` 与 `loadedFromDraftRef` 的实现)。
+3. **草稿 snapshot 形状**(Step 1 的 `Step1Snapshot` / Step 2 的 `Step2Snapshot`)与 `api/drafts.ts` 的 `DraftStep{1,2}Snapshot` 是同一份语义,改字段时两边都要改;后端以 JSON 整存,不强约束嵌套字段。
+4. **lint/typecheck**:重构后 `pnpm typecheck` 与 `pnpm build` 必须保持 0 个新增错误(预存量错误来自其它无关模块如 `strategy-components` / `next/link` shim,与本特性无关)。
+
+### 12.7 文档协同
+
+`@/roundtable-planning/` 内一切公共 API 都应当：
+
+1. 在 `api/*.ts` 文件级注释里说明 endpoint
+2. 在本页第 4 节 / 第 10 节同步对照
+3. 后端字段变化（如 `init_done` 字段名）需要同步改 `initMultiAgent` 解析逻辑 + `multi-agent-api.md`
+
+---
+
+## 13. 路径速查
+
+| 资源 | 路径 |
+|------|------|
+| 主页面（组合 + 顶栏 + 侧栏） | `frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx` |
+| Step 1 hook | `frontend-web/src/roundtable-planning/hooks/useStep1Intent.ts` |
+| Step 2 hook(含编排循环) | `frontend-web/src/roundtable-planning/hooks/useStep2Orchestration.ts` |
+| 草稿 hook | `frontend-web/src/roundtable-planning/hooks/useDraftPersistence.ts` |
+| Step 1 面板 | `frontend-web/src/roundtable-planning/components/Step1Panel.tsx` |
+| Step 2 面板 | `frontend-web/src/roundtable-planning/components/Step2Panel.tsx` |
+| Step 3 面板 | `frontend-web/src/roundtable-planning/components/Step3Panel.tsx` |
+| 消息气泡共享件 | `frontend-web/src/roundtable-planning/components/MessageBubble.tsx` |
+| 步骤折叠卡(工具/思考) | `frontend-web/src/roundtable-planning/components/MessageStepsCard.tsx` |
+| `<think>` 提取工具 | `frontend-web/src/roundtable-planning/lib/reasoning.ts` |
+| Persona 抽屉 | `frontend-web/src/roundtable-planning/components/PersonaDrawer.tsx` |
+| 头像集合 | `frontend-web/src/roundtable-planning/components/Avatars.tsx` |
+| 常量/工具函数 | `frontend-web/src/roundtable-planning/lib/roundtable-constants.ts` |
+| ChainOfThought 渲染 | `frontend-web/src/roundtable-planning/lib/step-display.tsx` |
+| Step 1 API | `frontend-web/src/roundtable-planning/api/intent.ts` |
+| 推荐 API（含推荐历史） | `frontend-web/src/roundtable-planning/api/recommend.ts` |
+| 草稿 API（后端 CRUD） | `frontend-web/src/roundtable-planning/api/drafts.ts` |
+| Step 2/3 API | `frontend-web/src/roundtable-planning/api/multi-agent.ts` |
+| 澄清卡片 | `frontend-web/src/roundtable-planning/components/IntentClarificationCard.tsx` |
+| 推荐弹窗 | `frontend-web/src/roundtable-planning/components/RecommendAgentsDialog.tsx` |
+| Step 3 报告 | `frontend-web/src/roundtable-planning/components/HighFidelityReport.tsx` |
+| 文件预览 | `frontend-web/src/roundtable-planning/components/ArtifactPreviewModal.tsx` |
+| 回底按钮 | `frontend-web/src/roundtable-planning/components/ScrollToBottomButton.tsx` |
+| 滚动跟随 | `frontend-web/src/roundtable-planning/hooks/useAutoScroll.ts` |
+| 澄清单选逻辑 | `frontend-web/src/roundtable-planning/lib/clarification.ts` |
+| 后端草稿/历史路由 | `offline-backend-20260512/backend/app/gateway/routers/roundtable_drafts.py` |
+| 路由 | `frontend-web/src/pages/WorkspaceRoutes.tsx` |
+| 样式 | `frontend-web/src/roundtable-planning/styles/roundtable-planning.css` |
+| 主聊天澄清参考 | `frontend-web/src/components/workspace/messages/message-list.tsx` |
+| 后端开发文档 | `frontend-web/docs/multi-agent-backend-dev.md` |
+| API 速查 | `frontend-web/docs/multi-agent-api.md` |

frontend-web/docs/openCanvas-progress.md

@@ -1,312 +0,0 @@
-# Open Canvas 集成进度文档
-
-> 最后更新：2026-05-16
-> 当前分支：dhk-1
-
----
-
-## 一、整体进度概览
-
-### Canvas 系统（双栏写作/编码工作区）
-
-| 阶段 | 名称 | 状态 |
-|------|------|------|
-| 阶段一 | 前端路由与目录骨架 | ✅ 已完成 |
-| 阶段二 | Canvas 双栏布局 | ✅ 已完成 |
-| 阶段三 | 前端 artifact 类型定义 | ✅ 已完成 |
-| 阶段四 | 后端 ThreadState 扩展 | ✅ 已完成 |
-| 阶段五 | canvas_agent 注册 + 最小节点闭环 | ✅ 已完成 |
-| 阶段六 | 前后端流式同步 | ✅ 已完成 |
-| 阶段七 | 版本历史导航 | ✅ 已完成 |
-| 阶段八 | 局部选区改写（Writing Editor 级） | ✅ 已完成 |
-| 阶段九 | 快捷动作系统 | ✅ 已完成 |
-| 阶段十 | 本地模型选择支持 | ✅ 已完成 |
-
-### AI Writing Editor（文本 artifact 编辑器内置 AI 改写）
-
-| 步骤 | 名称 | 状态 |
-|------|------|------|
-| Step 1 | Tiptap 编辑器核心 | ✅ 已完成 |
-| Step 2 | 写作工具栏 + 模型选择器 | ✅ 已完成 |
-| Step 3a | 气泡菜单（选区 AI 改写入口） | ✅ 已完成 |
-| Step 3b | 段落悬停按钮（整段 AI 改写入口） | ✅ 已完成 |
-| Step 4 | AI 改写菜单 + SSE 流式接口 | ✅ 已完成 |
-| Step 5 | 候选结果预览 + 替换/插入 | ✅ 已完成 |
-| Step 6 | 后端 `POST /api/writing/rewrite`（SSE，思考分离） | ✅ 已完成 |
-| Step 7 | 视觉精修（字体、间距、排版） | ✅ 已完成 |
-
-**当前状态：全部功能已完成 🎉**
-
----
-
-## 二、已完成工作详情
-
-### 2.1 前端核心文件结构
-
-```
-frontend-web/src/open-canvas/
-├── api/
-│   ├── client.ts          # LangGraph SDK 客户端实例
-│   ├── models.ts          # 模型列表 API
-│   ├── rewrite.ts         # AI 改写 SSE 流（streamRewrite，parseSse）
-│   ├── runs.ts            # streamCanvasRun（老的直接 API，已停用）
-│   └── threads.ts         # createCanvasThread、getCanvasThread
-├── components/
-│   ├── artifact/
-│   │   ├── CanvasArtifactHeader.tsx      # 右栏顶部：标题、语言、版本导航
-│   │   ├── CanvasArtifactPanel.tsx       # 右栏：流式预览 / 编辑器 / 空状态
-│   │   ├── CanvasArtifactVersionNav.tsx  # prev/next 版本切换
-│   │   ├── CanvasEmptyState.tsx          # 5 种快速开始模板
-│   │   ├── CanvasQuickActionBar.tsx      # 快捷动作按钮栏
-│   │   ├── CodeArtifactRenderer.tsx      # CodeMirror 代码编辑器
-│   │   ├── TextArtifactRenderer.tsx      # Tiptap 文本编辑器 + AI 改写流程
-│   │   ├── WritingAiMenu.tsx             # AI 改写动作菜单（polish/expand/shorten/tone）
-│   │   ├── WritingBubbleMenu.tsx         # 选区气泡菜单（portal 实现）
-│   │   ├── WritingParagraphMenu.tsx      # 段落悬停 AI 改写按钮
-│   │   ├── WritingRewritePreview.tsx     # 改写结果预览面板（含思考过程展开）
-│   │   └── WritingToolbar.tsx            # 格式工具栏（含模型选择器）
-│   ├── chat/
-│   │   └── CanvasChatPanel.tsx           # 左栏：消息列表 + 输入框
-│   ├── layout/
-│   │   ├── CanvasHeader.tsx              # 顶部栏：返回、折叠、流式指示
-│   │   ├── CanvasResizableLayout.tsx     # 左右可拖拽双栏（含 CanvasStreamProvider）
-│   │   └── CanvasShell.tsx               # 顶层壳：加载已有线程状态
-│   └── selectors/
-│       └── CanvasModelSelector.tsx       # 模型下拉选择器
-├── contexts/
-│   ├── CanvasGraphContext.tsx   # artifact、streamingArtifact、isStreaming
-│   ├── CanvasStreamContext.tsx  # 共享 useCanvasThreadStream 实例（sendMessage）
-│   ├── CanvasThreadContext.tsx  # threadId、modelName
-│   └── CanvasUIContext.tsx      # isChatCollapsed、writingSelection
-├── editor/
-│   ├── TiptapEditor.tsx         # EditorContent 包装器
-│   └── TiptapExtensions.ts      # StarterKit + Underline + Placeholder + Markdown
-├── hooks/
-│   ├── useCanvasArtifact.ts     # artifact 初始化工具
-│   ├── useCanvasQuickActions.ts # 快捷动作触发（走 CanvasStreamContext）
-│   ├── useCanvasSelection.ts    # 文字/代码选区状态
-│   ├── useCanvasStream.ts       # 旧直接 API 流（已停用，保留备用）
-│   ├── useCanvasThread.ts       # 线程加载工具
-│   ├── useCanvasThreadStream.ts # LangGraph SDK useStream hook（主流）
-│   ├── useWritingEditor.ts      # Tiptap editor 实例管理
-│   └── useWritingRewrite.ts     # AI 改写状态机（ThinkTagParser、AbortController）
-├── pages/
-│   ├── CanvasHomePage.tsx       # 欢迎页 + 快速开始
-│   └── CanvasThreadPage.tsx     # Provider 装配层
-├── routes/
-│   └── OpenCanvasRoutes.tsx     # /page/canvas/* 子路由
-├── types/
-│   ├── artifact.ts              # CanvasArtifact、CanvasArtifactText、CanvasArtifactCode
-│   ├── model.ts                 # CanvasModel
-│   ├── quick-action.ts          # QuickAction、QuickActionId
-│   ├── selection.ts             # CanvasTextSelection、CanvasCodeSelection
-│   └── thread.ts                # CanvasMessage、CanvasThreadValues
-└── utils/
-    ├── apply-rewrite.ts         # applyReplace、applyInsert（Tiptap 事务）
-    ├── artifact.ts              # getCurrentArtifactContent、setCurrentArtifactIndex 等
-    ├── quick-actions.ts         # buildQuickActionMessage（含 artifact 内容注入）
-    ├── selection.ts             # buildMessageWithSelection
-    ├── stream.ts                # 流式工具
-    └── thread.ts                # 线程工具
-```
-
-### 2.2 后端核心文件结构
-
-```
-offline-backend-20260512/backend/
-├── packages/harness/deerflow/agents/
-│   ├── canvas_agent/
-│   │   ├── __init__.py
-│   │   ├── agent.py      # make_canvas_agent()：LangGraph graph 工厂
-│   │   ├── prompt.py     # build_canvas_system_prompt()：含 selection_rewrite + quick_actions
-│   │   └── tools.py      # update_artifact_tool：创建/追加 artifact 版本
-│   └── thread_state.py   # ThreadState（含 artifact 字段、CanvasArtifact TypedDict）
-└── app/gateway/
-    ├── app.py            # 注册 writing router
-    └── routers/
-        └── writing.py    # POST /api/writing/rewrite（SSE 流式）
-```
-
-**langgraph.json** 注册了两个 graph：
-- `lead_agent` → 主聊天 Agent
-- `canvas_agent` → Canvas 写作 Agent
-
-### 2.3 关键 Context 层级
-
-```
-CanvasThreadPage
-  ├── CanvasThreadProvider      # threadId、modelName
-  │     ├── CanvasGraphProvider # artifact、streamingArtifact、isStreaming
-  │     │     └── CanvasUIProvider  # isChatCollapsed、writingSelection
-  │     │           └── CanvasShell
-  │     │                 └── CanvasResizableLayout
-  │     │                       └── CanvasStreamProvider  ← 持有 useCanvasThreadStream 单例
-  │     │                             ├── CanvasChatPanel      # 读 useCanvasStreamContext()
-  │     │                             └── CanvasArtifactPanel
-  │     │                                   └── CanvasQuickActionBar  # 读 useCanvasStreamContext()
-```
-
----
-
-## 三、关键架构决策与注意事项
-
-### 3.1 流式架构：单例流（重要）
-
-**问题**：原先 `CanvasChatPanel` 调 `useCanvasThreadStream()`，`CanvasQuickActionBar` 调 `useCanvasStream()`（旧的直接 API），两套流互不相通，快捷动作响应不出现在聊天面板。
-
-**解决方案**：新增 `CanvasStreamContext`，在 `CanvasResizableLayout` 中调用 `useCanvasThreadStream()` 一次，通过 Context 共享给所有子组件。`CanvasChatPanel` 和 `useCanvasQuickActions` 都从 `useCanvasStreamContext()` 取 `sendMessage`。
-
-```
-useCanvasStream（旧，已停用） ← 不再被调用，保留备用
-useCanvasThreadStream（新，LangGraph SDK） ← 通过 CanvasStreamContext 统一共享
-```
-
-### 3.2 artifact 内容注入机制（重要）
-
-**问题**：LangGraph `create_agent` 只把 `state.messages` 传给 LLM，`state.artifact` 字段不会自动可见。Agent 做 expand/shorten 等操作时看不到要改写的内容。
-
-**解决方案**：在每次 `sendMessage` 时，把当前 artifact 内容以 `<artifact>` 标签嵌入人类消息末尾。
-
-- 普通聊天：`sendMessage` 内部自动追加（仅当消息里还没有 `<artifact>` 时）
-- 快捷动作：`buildQuickActionMessage(id, content)` 在构建时就包含内容
-- 聊天面板显示时：`message-list-item.tsx` 调 `stripArtifactTag()` 剥掉标签，用户看不到
-
-```typescript
-// utils/quick-actions.ts
-export function buildQuickActionMessage(id, content) {
-  const body = isCodeArtifact(content) ? content.code : content.fullMarkdown;
-  return `${instruction}\n\n<artifact ${tag}>\n${body}\n</artifact>`;
-}
-
-// core/messages/utils.ts
-export function stripArtifactTag(content: string): string {
-  return content.replace(/<artifact[^>]*>[\s\S]*?<\/artifact>/g, "").trim();
-}
-```
-
-### 3.3 ThinkTagParser（AI 改写思考过程解析）
-
-后端支持两种思考格式：
-- Anthropic：独立 thinking block，以 `event: thinking` SSE 事件传输
-- DeepSeek：把思考过程内联在文本里：`<think>...</think>content`
-
-前端 `useWritingRewrite.ts` 的 `ThinkTagParser` 是流式状态机，处理跨 chunk 边界的 `<think>` 标签。
-
-### 3.4 版本历史：本地切换
-
-`CanvasArtifactVersionNav` 的 prev/next 只修改本地 `CanvasGraphContext.artifact.currentIndex`，不写回后端。刷新后 currentIndex 重置为后端存储的最新值（这是有意的简化设计）。
-
-### 3.5 Writing Editor 流程（三阶段状态机）
-
-```
-idle → menu → preview → idle
-         ↑              ↓
-     openAiMenu      closeAll
-```
-
-- **idle**：正常编辑
-- **menu**：显示 `WritingAiMenu`（选择 polish/expand/shorten/tone）
-- **preview**：显示 `WritingRewritePreview`（SSE 流式结果 + 思考过程 + 替换/插入按钮）
-
----
-
-## 四、已解决的技术难题
-
-| 问题 | 解法 |
-|------|------|
-| react-resizable-panels v4 API 变更（`orientation` 不是 `direction`，`groupRef` 不是 `ref`，`setLayout` 参数为 `{id: size}` 对象） | 参考 v4 文档，逐一修正 |
-| Flex 高度链底部裁剪 | 在 wrapper div 加 `min-h-0`，配合 `flex-1 overflow-hidden` |
-| Tiptap v3 BubbleMenu 已从 React 组件改为纯 Extension | 自定义 portal 实现：监听 `selectionUpdate`，手动计算位置 |
-| 段落悬停按钮鼠标桥接：鼠标经过 6px 间隙时按钮消失 | 文档级 `mousemove` 监听 + 380ms 延迟隐藏，判断鼠标是否在扩展热区内 |
-| 弹窗超出屏幕底部 | 检测 `spaceBelow` vs `spaceAbove`，空间不足时翻转到光标上方 |
-| DeepSeek 在文本流里混入 `<think>` 标签 | `ThinkTagParser` 状态机，保留最后 6/7 字节防止跨 chunk 分割 |
-| loading→success 状态转换检测（stale closure） | 用 `prevStatusRef` + `useEffect` 检测 status 变化，取代直接读 state |
-| 快捷动作响应不出现在聊天面板 | `CanvasStreamContext` 统一 `sendMessage` 入口 |
-| LLM 看不到 artifact 内容（只有 state.messages） | 消息里直接嵌入 `<artifact>` 标签，显示时剥离 |
-| `<artifact>` 标签在聊天面板里显示 | `message-list-item.tsx` 调 `stripArtifactTag()` |
-
----
-
-## 五、当前已知限制（非 bug，设计取舍）
-
-1. **版本切换不持久化**：切换 artifact 版本后刷新页面会回到最新版本
-2. **useCanvasStream 孤立**：旧的直接 API 流 hook 保留但未被调用，可后续清理
-3. **CanvasShell 的 setMessages 冗余**：加载旧线程时 `setMessages` 写入 CanvasGraphContext，但 `CanvasChatPanel` 读的是 `thread.messages`（来自 useStream + fetchStateHistory）。setArtifact 仍有效
-4. **artifact 内容随消息发送**：大文档每条消息都附带全文，token 消耗较大。当前规模可接受
-
----
-
-## 六、快速开始下一次工作
-
-### 启动服务
-
-```bash
-# 后端（从 offline-backend-20260512/backend/）
-make dev       # 启动 Gateway API on port 8001
-
-# 前端（从 frontend-web/）
-pnpm dev       # 启动 Vite on port 5174
-```
-
-### 访问路径
-
-- 主页：`http://localhost:5174`
-- Canvas 入口：点击左侧导航 → Canvas，或直接访问 `http://localhost:5174/page/canvas`
-
-### 类型检查
-
-```bash
-cd frontend-web && pnpm typecheck
-# 预期：只有 CodeArtifactRenderer.tsx 的 CodeMirror 版本冲突错误（预存 bug，不影响运行）
-```
-
----
-
-## 七、如需继续开发的潜在方向
-
-| 方向 | 描述 | 优先级 |
-|------|------|------|
-| 版本切换持久化 | 将 currentIndex 变更写回后端 ThreadState | 低 |
-| artifact 内容 token 优化 | 仅发送 diff 或用 summary 代替全文 | 低 |
-| 清理 useCanvasStream | 删除未被调用的旧 hook | 低 |
-| 代码 artifact 的 AI 改写 | CodeArtifactRenderer 也接入 WritingAiMenu 流程 | 中 |
-| Canvas 选区→聊天（高级） | 用户在右栏选中文字后在左栏输入指令，自动带选区上下文 | 中 |
-| Tiptap 扩展（表格、任务列表） | 增加 Table、TaskList extension | 低 |
-
----
-
-## 八、关键文件速查
-
-| 文件 | 说明 |
-|------|------|
-| `frontend-web/docs/openCanvas-progress.md` | **本文档** |
-| `frontend-web/src/open-canvas/contexts/CanvasStreamContext.tsx` | 流单例 Context |
-| `frontend-web/src/open-canvas/hooks/useCanvasThreadStream.ts` | 主流 hook（LangGraph SDK） |
-| `frontend-web/src/open-canvas/hooks/useWritingRewrite.ts` | AI 改写状态机 |
-| `frontend-web/src/open-canvas/api/rewrite.ts` | 改写 SSE 客户端 |
-| `frontend-web/src/open-canvas/utils/quick-actions.ts` | 快捷动作消息构建 |
-| `frontend-web/src/core/messages/utils.ts` | `stripArtifactTag` 在此 |
-| `frontend-web/src/components/workspace/messages/message-list-item.tsx` | 调用 stripArtifactTag 的位置 |
-| `frontend-web/src/styles/globals.css` | Tiptap 写作编辑器样式（`.tiptap-writing-editor`） |
-| `offline-backend-20260512/backend/packages/harness/deerflow/agents/canvas_agent/agent.py` | canvas_agent 工厂 |
-| `offline-backend-20260512/backend/packages/harness/deerflow/agents/canvas_agent/tools.py` | update_artifact_tool |
-| `offline-backend-20260512/backend/packages/harness/deerflow/agents/canvas_agent/prompt.py` | 系统提示词 |
-| `offline-backend-20260512/backend/app/gateway/routers/writing.py` | AI 改写后端接口 |
-| `offline-backend-20260512/backend/langgraph.json` | canvas_agent 注册 |
-
----
-
-## 九、开始新对话的推荐提示词
-
-```
-我们在开发 DeerFlow 的 Canvas 写作模式（open-canvas 集成）。
-详细进度见：frontend-web/docs/openCanvas-progress.md
-
-当前全部功能已完成，包括：
-- Canvas 双栏布局、canvas_agent、版本历史
-- AI Writing Editor（Tiptap + SSE 改写 + 思考过程展开）
-- 快捷动作（通过 CanvasStreamContext 统一流）
-- artifact 内容注入（消息里嵌入 <artifact> 标签，显示时剥离）
-
-请根据进度文档第七节"潜在开发方向"或我指定的任务继续开发。
-```

frontend-web/docs/openCanvas.md

@@ -1,950 +0,0 @@
-# Open Canvas 模式需求拆解文档
-
-## 1. 文档目标
-
-本文档用于指导 DeerFlow 在现有架构中新增一个 `open-canvas` 风格的 Canvas 模式。
-
-目标不是直接照搬 `langchain-ai/open-canvas` 的 Next.js + LangGraph.js 实现，而是在当前项目技术栈内完成一套等价能力的实现：
-
-- 前端：基于 `React 19 + Vite + react-router-dom`
-- 后端：基于 `Python + FastAPI + LangGraph`
-- 模型层：支持云模型与本地模型自由配置
-- 状态层：支持结构化 artifact、版本历史、局部改写、快速动作、画布编辑
-
-本文档重点是把需求拆成“可实现、可排期、可验收”的阶段性任务。
-
----
-
-## 2. 最终目标
-
-### 2.1 用户视角目标
-
-用户进入一个新的 Canvas 工作模式后，可以获得与 open-canvas 接近的体验：
-
-- 左侧是聊天区，右侧是 Canvas 编辑区
-- 可以从空白文本或代码模板快速开始
-- 可以通过聊天让 AI 生成一份结构化 artifact
-- 可以对 artifact 整体重写，也可以对选中的局部内容进行改写
-- artifact 支持版本历史切换
-- artifact 支持文本和代码两种主要类型
-- 支持快速动作，例如扩写、压缩、改风格、改语气、加注释、修 bug、换语言
-- 支持启用 Web 搜索增强
-- 支持切换模型
-- 支持使用本地模型，例如 Ollama 或 OpenAI-compatible 本地服务
-
-### 2.2 工程视角目标
-
-新增的 Canvas 模式需要满足以下工程原则：
-
-- 不破坏现有 DeerFlow 工作区
-- 不影响现有基于 `artifacts: string[]` 的文件产物功能
-- 可逐阶段上线
-- 前后端状态协议清晰
-- 可兼容现有 LangGraph 线程、消息流、认证和模型接口
-
----
-
-## 3. 范围定义
-
-### 3.1 本次需求包含
-
-- 前端新增 `open-canvas` 专用目录
-- 在 [PageRoutes.tsx](../src/pages/PageRoutes.tsx) 中引入新的 Canvas 路由
-- 前端新增 Canvas 页面、上下文、组件、状态管理
-- 后端新增 Canvas 专用线程状态字段
-- 后端新增 Canvas Agent 图或在现有 Agent 体系中新增 Canvas 模式分支
-- 模型配置统一为 DeerFlow 后端配置驱动
-- 支持本地大模型配置与模型列表动态下发
-- 支持结构化 artifact 的保存、读取、更新、版本切换
-
-### 3.2 本次需求不包含
-
-- 一次性复刻 open-canvas 全部 UI 细节
-- 完整照搬 Supabase 鉴权体系
-- 直接复用 open-canvas 的 Next.js API Route
-- 直接运行 open-canvas 的 LangGraph.js 后端
-- 首阶段就实现所有快捷动作、所有富文本效果、所有搜索增强能力
-
-### 3.3 迁移原则
-
-- 借鉴 open-canvas 的能力模型，不直接迁移其运行时架构
-- 前端尽量复用其交互设计和数据结构
-- 后端以 Python 实现同等能力
-- 配置以 DeerFlow 为真源，不以 open-canvas 的 TS 文件为真源
-
----
-
-## 4. 总体设计思路
-
-### 4.1 前端设计思路
-
-在现有 `frontend-web/src` 下新增一个专用目录，例如：
-
-```text
-src/
-  open-canvas/
-    pages/
-    routes/
-    components/
-    contexts/
-    hooks/
-    types/
-    api/
-    utils/
-    constants/
-```
-
-建议将 Canvas 模式作为一个独立的页面子系统接入，而不是把现有工作区页面强行改造成 Canvas。
-
-建议路由形式：
-
-- `/canvas`
-- `/canvas/:threadId`
-
-也可以挂在现有页面布局下，例如：
-
-- `/workspace/canvas`
-- `/workspace/canvas/:threadId`
-
-推荐优先采用独立一级功能路由：
-
-- 逻辑更清晰
-- 状态隔离更容易
-- 不容易污染现有 `workspace` 功能
-
-### 4.2 后端设计思路
-
-后端不建议直接改造现有通用 Agent 去同时承担全部 Canvas 行为，而是建议采用以下两种方案之一：
-
-#### 方案 A：新增独立 Canvas Assistant
-
-- 新增 `canvas_agent`
-- 使用单独的 LangGraph 状态定义
-- 前端调用时通过 `assistant_id=canvas_agent`
-
-优点：
-
-- 与现有 `lead_agent` 隔离
-- 风险更低
-- 更容易对齐 open-canvas 的图结构
-
-缺点：
-
-- 会产生一套新的 Agent 图维护成本
-
-#### 方案 B：在现有 Lead Agent 中增加 Canvas 模式分支
-
-- 在 thread metadata 或 configurable 中增加 `ui_mode=canvas`
-- Agent 根据模式进入 Canvas 路径
-
-优点：
-
-- 统一入口
-
-缺点：
-
-- 会显著增加现有 Agent 复杂度
-- 容易影响现有聊天和文件产物模式
-
-推荐先做方案 A。
-
-### 4.3 模型配置设计思路
-
-模型配置统一以 DeerFlow 后端 `config.yaml` 为真源。
-
-前端不维护固定模型常量列表，而是通过 `/api/models` 获取模型能力元数据。
-
-为了实现 open-canvas 风格体验，需要后端模型接口至少返回：
-
-- `name`
-- `display_name`
-- `provider`
-- `supports_thinking`
-- `supports_reasoning_effort`
-- `supports_vision`
-- `supports_tool_calling`
-- `supports_artifact_editing`
-- `supports_code_editing`
-- `temperature_range`
-- `max_tokens_range`
-- `base_url_source` 或 provider 标识
-- `is_local`
-
----
-
-## 5. 与当前项目的关键差异
-
-### 5.1 当前 DeerFlow 现状
-
-当前 DeerFlow 线程状态中的 artifact 主要是文件路径列表：
-
-- `artifacts: string[]`
-
-这更接近“生成文件产物”的工作模式。
-
-前端当前 artifact 面板也主要是：
-
-- 文件列表
-- 文件详情
-- 文件下载/预览
-
-### 5.2 open-canvas 的关键能力
-
-open-canvas 的核心不是“生成文件”，而是“维护一个结构化的当前文档对象”：
-
-- 一个 conversation 对应一个主 artifact
-- artifact 具有类型、标题、内容、版本
-- 用户可以选中部分内容让 AI 改写
-- 每次改写都会生成新版本
-
-### 5.3 需要新增的核心能力
-
-为支持 Canvas 模式，需要在 DeerFlow 中新增一套结构化 artifact 状态：
-
-- 当前 artifact
-- 当前版本索引
-- 历史版本列表
-- 选区信息
-- 当前编辑模式
-- 快速动作状态
-- Web 搜索结果状态
-
----
-
-## 6. 分阶段实施方案
-
-以下为推荐的 8 个阶段，每个阶段都可单独开发、联调和验收。
-
----
-
-## 7. 阶段一：前端路由与目录骨架
-
-### 7.1 目标
-
-在不影响现有页面的前提下，建立 Canvas 模式的前端骨架。
-
-### 7.2 需求
-
-- 新增 `src/open-canvas/` 目录
-- 新增 Canvas 页面路由
-- 将路由接入 [PageRoutes.tsx](../src/pages/PageRoutes.tsx)
-- 提供 Canvas 首页和 Canvas Thread 页
-- 支持空状态展示
-
-### 7.3 建议目录
-
-```text
-src/open-canvas/
-  api/
-    threads.ts
-    runs.ts
-    models.ts
-  components/
-    layout/
-    chat/
-    canvas/
-    artifacts/
-    quick-actions/
-    selectors/
-  contexts/
-    CanvasThreadContext.tsx
-    CanvasGraphContext.tsx
-    CanvasUIContext.tsx
-  hooks/
-    useCanvasThread.ts
-    useCanvasStream.ts
-    useCanvasArtifact.ts
-  pages/
-    CanvasHomePage.tsx
-    CanvasThreadPage.tsx
-  routes/
-    OpenCanvasRoutes.tsx
-  types/
-    artifact.ts
-    thread.ts
-    model.ts
-  utils/
-    artifact.ts
-    selection.ts
-    stream.ts
-  constants/
-    index.ts
-```
-
-### 7.4 路由建议
-
-- 在 `PageRoutes.tsx` 中新增 `canvas/*`
-- 在 `src/open-canvas/routes/OpenCanvasRoutes.tsx` 中维护子路由
-
-建议形式：
-
-```text
-/canvas
-/canvas/:threadId
-```
-
-### 7.5 验收标准
-
-- 能访问 Canvas 首页
-- 能访问指定 thread 的 Canvas 页面
-- 不影响现有 `workspace/*` 与 `strategy/*`
-- 页面有独立布局骨架
-
----
-
-## 8. 阶段二：前端 Canvas 布局与交互容器
-
-### 8.1 目标
-
-先做出“左聊天、右画布”的基础容器，不接真实 AI 改写逻辑。
-
-### 8.2 需求
-
-- 左侧聊天区
-- 右侧画布区
-- 支持面板拖拽或折叠
-- 初始空状态
-- 支持“快速开始”：
-  - 新建空白文本 artifact
-  - 新建代码 artifact
-
-### 8.3 组件拆分建议
-
-- `CanvasShell`
-- `CanvasSidebar`
-- `CanvasChatPanel`
-- `CanvasArtifactPanel`
-- `CanvasEmptyState`
-- `QuickStartActions`
-
-### 8.4 快速开始能力
-
-用户进入空线程时可以选择：
-
-- 开始写文章
-- 开始写代码
-- 从模板开始
-
-首版模板可只做最小集：
-
-- 空白文档
-- HTML 模板
-- React 组件模板
-- Python 脚本模板
-
-### 8.5 验收标准
-
-- 页面可稳定展示双栏布局
-- 快速开始能创建前端本地 artifact 状态
-- 代码和文本可分别进入不同渲染器
-
----
-
-## 9. 阶段三：结构化 Artifact 数据模型
-
-### 9.1 目标
-
-定义 DeerFlow 的 Canvas Artifact 协议，作为前后端统一契约。
-
-### 9.2 核心要求
-
-需要支持以下能力：
-
-- 文本 artifact
-- 代码 artifact
-- 标题
-- 当前版本索引
-- 版本历史
-- 当前选中版本切换
-- 后续支持局部高亮编辑
-
-### 9.3 建议数据结构
-
-```ts
-type CanvasArtifact = {
-  currentIndex: number;
-  contents: Array<CanvasArtifactText | CanvasArtifactCode>;
-};
-
-type CanvasArtifactText = {
-  index: number;
-  type: "text";
-  title: string;
-  fullMarkdown: string;
-};
-
-type CanvasArtifactCode = {
-  index: number;
-  type: "code";
-  title: string;
-  language: string;
-  code: string;
-};
-```
-
-### 9.4 线程状态建议新增字段
-
-前端与后端需共同支持：
-
-- `artifact`
-- `highlighted_text`
-- `highlighted_code`
-- `canvas_mode`
-- `web_search_enabled`
-- `web_search_results`
-- `quick_action_id`
-
-### 9.5 与现有 `artifacts: string[]` 的关系
-
-建议保留现有 `artifacts: string[]` 不动。
-
-新增字段：
-
-- `artifact` 用于 Canvas 主文档
-- `artifacts` 继续用于文件产物
-
-这样可以兼容未来“Canvas 生成网页文件、导出文件、保存文件”的场景。
-
-### 9.6 验收标准
-
-- 前端类型定义完成
-- 后端状态字段设计完成
-- 确认与现有线程状态兼容
-
----
-
-## 10. 阶段四：后端线程状态与 API 扩展
-
-### 10.1 目标
-
-让后端线程状态可以安全存储和返回 Canvas Artifact。
-
-### 10.2 需求
-
-- 扩展 Python `ThreadState`
-- 扩展状态序列化逻辑
-- 确保 `/api/threads/*` 返回结构化 `artifact`
-- 确保 LangGraph 流中可带上 `artifact` 更新
-
-### 10.3 后端改造点
-
-建议关注以下模块：
-
-- `packages/harness/deerflow/agents/thread_state.py`
-- 线程 state serializer
-- `app/gateway/routers/threads.py`
-- 流事件适配层
-
-### 10.4 注意事项
-
-- 旧线程没有 `artifact` 字段时必须兼容
-- 状态更新不能破坏现有消息结构
-- 必须确保 JSON 可序列化
-
-### 10.5 验收标准
-
-- 新建线程可写入 `artifact`
-- 读取线程时可返回 `artifact`
-- 不影响现有线程读取
-- 前端能从线程 state 中恢复 Canvas 内容
-
----
-
-## 11. 阶段五：Canvas 专用 Agent 图
-
-### 11.1 目标
-
-实现与 open-canvas 类似的 AI 路由能力。
-
-### 11.2 推荐方案
-
-新增 `canvas_agent`，单独维护图逻辑。
-
-### 11.3 节点拆分建议
-
-首版建议至少拆成这些节点：
-
-- `route_user_intent`
-- `reply_general_input`
-- `generate_artifact`
-- `rewrite_artifact`
-- `update_highlighted_text`
-- `update_highlighted_code`
-- `generate_followup`
-
-二期可加：
-
-- `rewrite_artifact_theme`
-- `rewrite_code_theme`
-- `change_length`
-- `change_reading_level`
-- `translate_artifact`
-- `add_comments`
-- `add_logs`
-- `fix_bugs`
-- `port_language`
-- `web_search_enrich`
-
-### 11.4 路由逻辑要求
-
-系统需要能判断：
-
-- 用户是在闲聊
-- 用户要新生成 artifact
-- 用户要整体重写当前 artifact
-- 用户要局部修改当前 artifact
-- 用户要执行某个快捷动作
-
-### 11.5 状态输入要求
-
-节点需要读取：
-
-- 当前消息历史
-- 当前 artifact
-- 当前选区
-- 当前模型配置
-- Web 搜索开关
-
-### 11.6 输出要求
-
-节点输出必须能更新：
-
-- `messages`
-- `artifact`
-- `web_search_results`
-- `followup`
-
-### 11.7 验收标准
-
-- 能根据输入创建新 artifact
-- 能根据输入整体改写 artifact
-- 能保留版本历史
-- 能在改写后返回自然语言 followup
-
----
-
-## 12. 阶段六：前端流式同步与版本管理
-
-### 12.1 目标
-
-让前端能像 open-canvas 一样在流式过程中更新画布与聊天。
-
-### 12.2 需求
-
-- 复用现有 LangGraph stream client
-- 在 Canvas 模式中解析 `artifact` 更新
-- 支持流式文本更新
-- 支持版本切换
-- 支持断线后恢复线程状态
-
-### 12.3 前端状态层建议
-
-- `CanvasThreadContext`：线程基础信息
-- `CanvasGraphContext`：消息、artifact、streaming 状态
-- `CanvasUIContext`：面板、编辑态、选中态
-
-### 12.4 关键能力
-
-- 当前版本切换
-- 新版本创建后自动定位到最新版本
-- 手动编辑内容后保存
-- 流结束后线程状态持久化
-
-### 12.5 验收标准
-
-- 发送消息时聊天和画布可同步更新
-- 版本数会增加
-- 切换历史版本稳定
-- 刷新页面后线程状态能恢复
-
----
-
-## 13. 阶段七：局部选区改写
-
-### 13.1 目标
-
-实现 Canvas 模式最关键的差异化能力之一：选中局部内容进行 AI 改写。
-
-### 13.2 文本选区需求
-
-- 支持在 Markdown 文本中选择一段文本
-- 记录选区位置与原始文本
-- 用户发出修改请求后，仅重写该选区
-- 将选区结果合并为新版本 artifact
-
-### 13.3 代码选区需求
-
-- 支持在代码编辑器中选择一段代码
-- 记录 start/end index 或行列信息
-- AI 只返回替换片段
-- 前端或后端负责将新片段拼接回完整代码
-
-### 13.4 实现建议
-
-首版建议：
-
-- 文本：前端记录纯文本字符位置
-- 代码：使用 CodeMirror selection 信息
-
-不建议首版就做复杂块级富文本局部编辑。
-
-### 13.5 风险
-
-- Markdown 渲染态与源码态位置映射复杂
-- 富文本块级位置难维护
-- 流式更新中选区同步容易错位
-
-### 13.6 首版折中方案
-
-首版文本只基于 `fullMarkdown` 纯文本改写，不做 BlockNote 富文本块定位。
-
-### 13.7 验收标准
-
-- 文本局部改写成功
-- 代码局部改写成功
-- 原内容未改动部分保持不变
-- 新版本正确入历史
-
----
-
-## 14. 阶段八：快捷动作系统
-
-### 14.1 目标
-
-实现 open-canvas 风格的快捷动作体系。
-
-### 14.2 首批推荐动作
-
-文本类：
-
-- 扩写
-- 精简
-- 改正式语气
-- 改口语语气
-- 改阅读难度
-- 翻译
-
-代码类：
-
-- 加注释
-- 加日志
-- 修复 bug
-- 优化代码
-- 转换语言
-
-### 14.3 设计方式
-
-快捷动作不要直接写死在 UI，建议配置化：
-
-- `id`
-- `label`
-- `type`
-- `applicable_to`
-- `prompt_template`
-
-### 14.4 后端设计
-
-快捷动作可通过：
-
-- 前端传 `quick_action_id`
-- 后端路由节点根据动作 id 选择 prompt
-
-### 14.5 验收标准
-
-- 文本动作可执行
-- 代码动作可执行
-- 结果进入新版本
-- 不同动作提示词可扩展
-
----
-
-## 15. 阶段九：模型配置统一与本地模型支持
-
-### 15.1 目标
-
-让 Canvas 模式支持和主系统统一的模型选择，并且能自由配置本地大模型。
-
-### 15.2 原则
-
-- 后端 `config.yaml` 为真源
-- 前端只展示后端暴露的模型信息
-- 不维护一份脱离后端的前端常量模型表
-
-### 15.3 本地模型支持范围
-
-建议优先支持两类：
-
-- `Ollama`
-- OpenAI-compatible 本地服务
-  - LM Studio
-  - vLLM
-  - LocalAI
-  - one-api 风格代理
-
-### 15.4 后端配置建议
-
-后端模型配置应至少支持：
-
-- `name`
-- `display_name`
-- `use`
-- `model`
-- `api_key`
-- `base_url`
-- `supports_vision`
-- `supports_thinking`
-- `supports_tool_calling`
-- `is_local`
-- `canvas_capabilities`
-
-### 15.5 Canvas 模式额外要求
-
-由于不是所有模型都适合 Canvas 改写任务，建议增加能力标识：
-
-- `supports_canvas_generation`
-- `supports_canvas_rewrite`
-- `supports_canvas_code_edit`
-- `supports_streaming_text`
-- `supports_streaming_tool_calls`
-
-### 15.6 与 open-canvas 的关系
-
-可以借鉴其命名习惯和能力分层，但不建议直接依赖其 `packages/shared/src/models.ts` 作为配置源。
-
-### 15.7 验收标准
-
-- 前端模型选择器可显示后端返回模型
-- 可切换本地模型
-- Canvas 模式能用本地模型生成和改写
-
----
-
-## 16. 阶段十：Web 搜索增强
-
-### 16.1 目标
-
-实现类似 open-canvas 的可选 Web 搜索增强。
-
-### 16.2 需求
-
-- UI 提供 Web 搜索开关
-- 后端在需要时走搜索节点
-- 搜索结果写入线程状态
-- 结果可在画布旁侧栏展示
-
-### 16.3 首版建议
-
-只做：
-
-- 开关
-- 搜索结果列表
-- 搜索结果用于生成 artifact
-
-暂不做复杂网页抓取编辑链路。
-
-### 16.4 验收标准
-
-- 打开搜索后可返回搜索结果
-- 搜索结果可参与 artifact 生成
-- 结果展示不阻塞主画布
-
----
-
-## 17. 阶段十一：持久化、导出与文件产物联动
-
-### 17.1 目标
-
-让 Canvas 文档与 DeerFlow 原有文件能力协同。
-
-### 17.2 需求
-
-- artifact 持久化在线程 state 中
-- 可手动导出为文件
-- 可生成真实 HTML/Markdown/代码文件到现有 outputs
-- Canvas artifact 与 `artifacts: string[]` 可双向关联
-
-### 17.3 推荐能力
-
-- 导出 Markdown
-- 导出代码文件
-- 另存为 artifact file
-- 从 artifact file 回填到 Canvas
-
-### 17.4 验收标准
-
-- 当前版本可导出
-- 导出文件可在现有文件面板查看
-- 文件型 artifact 和 Canvas artifact 能共存
-
----
-
-## 18. 推荐开发顺序
-
-建议严格按以下顺序推进：
-
-1. 路由和目录骨架
-2. Canvas 页面布局
-3. 前端 artifact 数据模型
-4. 后端线程状态扩展
-5. 新建 Canvas Agent 图
-6. 前后端流式同步
-7. 整体生成与整体改写
-8. 局部选区改写
-9. 快捷动作
-10. 本地模型支持完善
-11. Web 搜索增强
-12. 导出与文件联动
-
-不要先做局部改写和快捷动作，否则前面的状态与路由契约不稳定，返工会很多。
-
----
-
-## 19. 里程碑定义
-
-### M1：页面可进入
-
-- 路由接通
-- 双栏布局完成
-- 本地 mock artifact 可渲染
-
-### M2：后端状态打通
-
-- 线程可保存结构化 artifact
-- 页面刷新后能恢复
-
-### M3：AI 生成可用
-
-- 可新建文本/代码 artifact
-- 可整体改写
-- 可产生版本历史
-
-### M4：核心体验可用
-
-- 选区改写可用
-- 快捷动作可用
-- 模型切换可用
-
-### M5：增强能力完整
-
-- 本地模型支持完善
-- Web 搜索增强
-- 导出和文件联动
-
----
-
-## 20. 风险与难点
-
-### 20.1 最大难点
-
-- 结构化 artifact 状态从无到有
-- 局部选区改写的精确性
-- 流式状态与版本管理的一致性
-- 不破坏现有 DeerFlow 文件型 artifact 体系
-
-### 20.2 技术风险
-
-- 线程 state JSON 结构过大
-- 大模型对局部改写指令遵循不稳定
-- 本地模型 tool calling 与流式能力差异大
-- 文本渲染态与源码态位置映射复杂
-
-### 20.3 规避建议
-
-- 首版只支持 Markdown 源码态编辑，不做复杂富文本编辑
-- 首版只支持文本和代码两种 artifact 类型
-- 首版先做整体生成和整体改写，再做局部改写
-- 本地模型先支持“能生成、能重写”的最小能力，不强求与顶级闭源模型完全同效
-
----
-
-## 21. 验收总清单
-
-### 21.1 前端
-
-- 有独立 Canvas 路由
-- 有专用目录和模块边界
-- 双栏布局可用
-- 文本和代码两类 artifact 可渲染
-- 历史版本可切换
-- 选区改写可交互
-- 快捷动作可触发
-- 模型可切换
-
-### 21.2 后端
-
-- 线程状态支持 `artifact`
-- 新增 `canvas_agent` 或等价模式
-- 生成、重写、局部改写可用
-- 流式返回稳定
-- 模型列表接口支持 Canvas 能力元数据
-
-### 21.3 本地模型
-
-- 可配置 Ollama
-- 可配置 OpenAI-compatible 本地服务
-- 前端可见并可切换
-- 至少能完成文本生成和整体改写
-
----
-
-## 22. 推荐首版最小可交付范围
-
-如果要控制风险，建议首版只交付以下内容：
-
-- 新增 `canvas/*` 路由
-- 双栏布局
-- 结构化 `artifact`
-- `canvas_agent`
-- 文本/代码 artifact 新建
-- 整体生成
-- 整体改写
-- 历史版本切换
-- 后端模型动态加载
-- Ollama 或本地 OpenAI-compatible 至少一种可用
-
-先不要把以下内容放进首版强制目标：
-
-- 富文本块级精确编辑
-- 全量快捷动作
-- 复杂 Web 搜索增强
-- 多 artifact 并行管理
-
----
-
-## 23. 后续实施建议
-
-建议下一步基于本文档继续输出两份落地文档：
-
-### 23.1 前端实施清单
-
-逐文件列出：
-
-- 要新建哪些文件
-- 哪些组件可复用
-- 哪些页面要接入路由
-- 哪些状态要从现有 hooks 抽离
-
-### 23.2 后端实施清单
-
-逐模块列出：
-
-- 要改哪些 Python 文件
-- 新增哪些状态字段
-- 新增哪些 Agent 节点
-- 哪些 API 需要扩展
-
----
-
-## 24. 结论
-
-这个需求很大，但完全可拆。
-
-正确做法不是“先抄 UI”，而是按下面的主线推进：
-
-- 先建前端 Canvas 子系统
-- 再建结构化 artifact 状态
-- 再建 Canvas Agent 图
-- 再补局部改写和快捷动作
-- 最后统一本地模型能力
-
-只要按本文档阶段推进，这个需求是可以落地的，而且能和你现在的 DeerFlow 架构保持长期兼容。

frontend-web/docs/roundtable-step2-sandbox-progress.md

@@ -0,0 +1,207 @@
+# 圆桌 Step 2 沙箱预览 · 开发进度
+
+> 最后更新：2026-05-27
+> 关联文档：`multi-agent-frontend-dev.md`（总览）、`multi-agent-backend-dev.md`（后端）、`multi-agent-api.md`（接口）
+> 对照参考：主聊天 `/page/workspace/chats/:threadId`（`ChatBox` + `ArtifactsProvider` + `message-group.tsx`）
+
+---
+
+## 1. 目标
+
+在 Step 2「多智能体圆桌研讨」中，当子智能体调用 `write_file` / `str_replace` / `present_files` 时，**行为与主聊天一致**：
+
+| 能力 | 主聊天 | Step 2 目标 |
+|------|--------|-------------|
+| `write_file` 流式期间自动打开右侧沙箱 | ✅ | ✅ 虚拟 URL |
+| 步骤卡里点击文件路径打开沙箱 | ✅ | ✅ |
+| 消息下方文件卡片（`present_files`）点击打开 | ✅ | ✅ `PresentFilesRow` |
+| 沙箱打开时收起 workspace 左侧栏 | ✅（`ArtifactsProvider.select`） | ✅ Step 2 左栏联动 |
+| 60/40 对话 \| 产物预览分栏 | ✅ `ChatBox` | ✅ `Step2SandboxLayout` |
+| 流式 MD 从 tool_call.args.content 预览 | ✅ 虚拟 URL + stub messages | ✅ `seatStubMessages`（双通道：`onPhaseChange` + `onUpstreamFrame`） |
+| 落盘后 HTTP 拉取真实文件 | ✅ artifacts API | ✅ `present_files` 卡片走 HTTP |
+| 草稿 reload 后历史文件可预览 | ✅ | ✅ `seatStubMessages` 一并入草稿 |
+
+---
+
+## 2. 已完成
+
+### 2.1 Step 2 布局调整
+
+| 项 | 状态 | 说明 |
+|----|------|------|
+| 推理模型下拉 | ✅ | 从右侧栏迁至 Step 2 顶栏「多智能体圆桌会商中心」右侧 |
+| 意图理解 | ✅ | 移至左侧栏顶部，支持展开/收起；收起时仅显示「目标」 |
+| 任务概览 | ✅ | 放在「人工参与」下方 |
+| 右侧栏 Step 2/3 隐藏 | ✅ | `RightSidebar` 仅在 `currentStep === 1` 渲染 |
+| 左侧栏整体收起 | ✅ | 宽度 56px；展开按钮在顶部；研讨中角色 ring + ping 动画 |
+| 沙箱打开 → 左栏收起 | ✅ | `Step2SandboxSidebarSync` 监听 `useArtifacts().open` |
+
+**主要文件**：`RoundtablePlanningPage.tsx`（`step2SidebarExpanded`、`LeftSidebar`、`Step2SandboxSidebarSync`）
+
+### 2.2 沙箱基础设施（Phase 1）
+
+| 项 | 状态 | 说明 |
+|----|------|------|
+| 路由包 `ChatRuntime` | ✅ | `WorkspaceRoutes.tsx` → `roundtable/planning` 外包 `ArtifactsProvider` |
+| 60/40 分栏壳 | ✅ | `Step2SandboxLayout.tsx`，对齐 `chat-box.tsx` |
+| `ArtifactFileDetail` / `ArtifactFileList` | ✅ | 嵌在右栏 ResizablePanel |
+| `ThreadContext` stub | ✅ | 最小 `BaseStream` stub，供 `useArtifactContent` 工作 |
+
+### 2.3 沙箱打开逻辑（Phase 2）
+
+| 项 | 状态 | 说明 |
+|----|------|------|
+| `write_file` 自动打开 | ✅ | `handleArtifactToolPhase` 在 `tool_calling` + 完整 `args.path` 时触发 |
+| 步骤卡点击打开 | ✅ | `MessageStepsCard` → `openArtifactFromStep` |
+| 虚拟 URL 机制 | ✅ | `write-file:<path>?message_id=...&tool_call_id=...`（对齐主聊天） |
+| Stub messages 注入 | ✅ | `seatStubMessages` + `upsertSeatToolCall` → `loadArtifactContentFromToolCall` |
+| 重置清理 | ✅ | `resetStep2State` 清空 artifacts / stub / deselect |
+| `present_files` 步骤点击 | ✅ | 走真实路径 `openArtifactPreview`（HTTP API） |
+
+### 2.4 上游帧兜底注入（Phase 3）
+
+| 项 | 状态 | 说明 |
+|----|------|------|
+| `onPhaseChange` 主通道 | ✅ | `tool_calling` 阶段每帧把完整 `args` 喂进 stub；首次出现 `path` 即触发自动打开 |
+| `onUpstreamFrame` 兜底通道 | ✅ | `handleUpstreamFrame` 扫描 messages-tuple 帧的 `tool_calls[]`，对 `write_file`/`str_replace` 持续 upsert `args.content`；覆盖 phase 已切走但 tool_calls 又回包的边界 |
+| 双通道幂等 | ✅ | `upsertSeatToolCall` 按 `(toolName, path)` 去重，两个通道并发写入安全 |
+
+### 2.5 `present_files` 文件卡（Phase 4）
+
+| 项 | 状态 | 说明 |
+|----|------|------|
+| 气泡下方文件卡行 | ✅ | `Step2Message` → `collectPresentedFiles` → `PresentFilesRow` |
+| 卡片样式 | ✅ | 文件名 + 扩展名徽章（FILE_EXT_LABELS），最小宽度 30/最大 50（hover 边框亮色） |
+| 点击 → HTTP 预览 | ✅ | `openArtifactPreview(agentThreadId, path)`，与步骤卡 `present_files` 走同一通道 |
+| 席位 thread 缺失保护 | ✅ | 没有 `agentThreadId` 时 disabled + tooltip |
+| 同气泡多次 present_files | ✅ | `filepaths` 顺序去重，全部聚合到一行卡片 |
+
+### 2.6 草稿持久化（Phase 5）
+
+| 项 | 状态 | 说明 |
+|----|------|------|
+| `seatStubMessages` 进 `Step2Snapshot` | ✅ | `useStep2Orchestration.ts` Step2Snapshot 新增字段 |
+| `seatStubMessages` 进 `DraftStep2Snapshot` | ✅ | `drafts.ts` 加 optional 字段，老草稿 reload 时回退到 `{}` |
+| `hydrateFromDraft` 还原 stub | ✅ | 同步写 `seatStubMessagesRef` + state，加载草稿后点击历史 write_file 步骤可直接预览 |
+| `getStep2Snapshot` 透出 stub | ✅ | `RoundtablePlanningPage.tsx` 给 `useDraftPersistence` 的 getter 加上该字段 |
+
+**主要文件**：
+
+```
+frontend-web/src/pages/WorkspaceRoutes.tsx
+frontend-web/src/roundtable-planning/hooks/useStep2Orchestration.ts
+frontend-web/src/roundtable-planning/components/Step2SandboxLayout.tsx
+frontend-web/src/roundtable-planning/components/Step2Panel.tsx
+frontend-web/src/roundtable-planning/components/MessageStepsCard.tsx
+frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx
+frontend-web/src/roundtable-planning/utils/drafts.ts
+```
+
+### 2.7 与主聊天对齐的核心数据流
+
+```
+special seat SSE (streamMultiAgent)
+  ├── onPhaseChange("tool_calling", "write_file", args)
+  │     ↓
+  │   upsertSeatToolCall(seatThreadId, "write_file", args)
+  │     → seatStubMessages[seatThreadId] = [{ type:"ai", tool_calls:[{ id, name, args }] }]
+  │     ↓
+  │   buildWriteFileVirtualUrl(path, messageId, toolCallId)
+  │     → "write-file:/mnt/user-data/outputs/foo.md?message_id=...&tool_call_id=..."
+  │     ↓
+  │   openSeatVirtualArtifact(seatThreadId, virtualUrl, auto=true)
+  │     → selectArtifact(virtualUrl) + setArtifactsOpen(true)
+  │
+  └── onUpstreamFrame(frame)         ← 兜底通道
+        ↓
+      handleUpstreamFrame —— 持续 upsert tool_calls 里完整的 args（不打开沙箱）
+
+Step2SandboxLayout
+  ThreadContext.thread.messages = seatStubMessages[activeThreadId]
+  ArtifactFileDetail(filepath=virtualUrl, threadId=seatThreadId)
+    ↓
+  useArtifactContent → loadArtifactContentFromToolCall
+    → 从 thread.messages 读 tool_call.args.content（不发 HTTP）
+```
+
+**为何不用真实 path 直接预览**：流式期间文件可能尚未落盘，直接调 `/api/threads/:id/artifacts/...` 会返回 `404 {"detail":"Not Found"}`。主聊天同样用虚拟 URL 绕过此问题。
+
+---
+
+## 3. 未完成 / 待验证
+
+### 3.1 功能缺口（按优先级）
+
+| 优先级 | 项 | 状态 | 说明 |
+|--------|----|------|------|
+| P0 | 端到端回归 | ⚠️ 待验证 | 虚拟 URL + 双通道 + 文件卡 + 草稿持久化全链路尚未在浏览器里跑一遍 |
+| P2 | `str_replace` 流式编辑预览 | ❌ | 主聊天 `applyPendingTextEdit` 依赖完整 message 链；stub 未模拟 tool result / 多轮 str_replace 累加 |
+| P2 | 沙箱 `artifacts[]` 列表与虚拟 URL 混排 | ❌ | 虚拟 URL 不写入 `setArtifacts([])`；多文件切换、文件名下拉体验未完全对齐主聊天 |
+| P3 | Step 3 与沙箱衔接 | ❌ | Step 3 仍用 `HighFidelityReport` + `listSessionArtifacts`；与 Step 2 沙箱选中态无联动 |
+| P3 | 文档同步 | ❌ | `multi-agent-frontend-dev.md` 仍描述旧布局（右侧栏模型选择器等），需更新 § 布局 + 沙箱章节 |
+
+### 3.2 已知风险 / 边界
+
+1. **打开时机**：仅在 SSE 进入 `tool_calling` 且 `tool_calls[0].args` 为完整对象时触发自动打开（`multi-agent.ts` 刻意忽略 `tool_call_chunks` 的拼接 args）。若模型只发 chunks、迟迟不发完整 tool_calls，自动打开会延迟到 args 完整那一帧——与主聊天一致。
+2. **多 write_file 同气泡**：`upsertSeatToolCall` 按 `(toolName, path)` 幂等；同 path 多次 write 会更新 args，不会新建多条 stub tool_call。
+3. **leader 席位**：当前仅 special 流绑定 `agentThreadId` 并接 `onUpstreamFrame`；总控若直接 write_file，需单独接 thread id 与帧回调。
+4. **`present_files` 文件大小**：流式期间 backend 尚未给出真实大小；卡片只显示扩展名徽章，不显示 size。落盘后用户点开走 HTTP API 自然能看到完整内容。
+5. **调试日志**：控制台 `[roundtable-sandbox]` 前缀；生产环境可考虑加 `window.__ROUNDTABLE_SANDBOX_DEBUG__` 门控。
+
+---
+
+## 4. 分阶段计划（原始规划 vs 现状）
+
+| 阶段 | 内容 | 状态 |
+|------|------|------|
+| Phase 1 | `ChatRuntime` + 分栏壳 + 侧栏联动 | ✅ 完成 |
+| Phase 2 | `write_file` 自动/点击打开 + 虚拟 URL 预览 | ✅ 完成 |
+| Phase 3 | `onUpstreamFrame` 注入完整 LangGraph messages | ✅ 完成（双通道兜底） |
+| Phase 4 | `present_files` 卡片 + Step 3 文件区衔接 | ⚠️ 卡片完成；Step 3 衔接遗留 |
+| Phase 5 | 草稿 stub 持久化 + 文档更新 | ✅ stub 完成；本文档同步更新 |
+
+---
+
+## 5. 测试清单
+
+在 `/page/workspace/roundtable/planning` Step 2 下逐项勾选：
+
+- [ ] 子智能体 `write_file` 进入 `tool_calling` 后，右侧沙箱 **自动** 打开（约 100ms 延迟，对齐主聊天）
+- [ ] 沙箱标题为文件名（如 `sample-paper.md`），**不是** `{"detail":"Not Found"}`
+- [ ] 流式期间 MD 内容随 `args.content` 更新（双通道：phase 切换帧 + 兜底帧）
+- [ ] 点击 ChainOfThought 步骤「写入文件」/ 路径 chip → 手动打开同一文件
+- [ ] `present_files` 后气泡下方出现文件卡（带扩展名徽章），点击 → HTTP 预览
+- [ ] 沙箱打开时左侧「意图理解」栏 **自动收起**
+- [ ] 关闭沙箱（X）后对话区恢复全宽
+- [ ] 「新建任务」后 artifacts / 沙箱 / `seatStubMessages` 全部清空
+- [ ] 「保存草稿」→「加载草稿」后，点击历史 `write_file` 步骤可立即预览（stub 已还原）
+- [ ] 与主聊天 `/page/workspace/chats/:threadId` 对比：同一 write_file 行为一致
+
+**调试**：DevTools Console 过滤 `[roundtable-sandbox]` 或 `[stream:special:...]`。
+
+---
+
+## 6. 关键代码索引
+
+| 用途 | 路径 |
+|------|------|
+| 主聊天 write_file 虚拟 URL + 自动打开 | `src/components/workspace/messages/message-group.tsx` |
+| 主聊天 `RichFileCard`（present_files） | `src/components/workspace/messages/message-list-item.tsx` |
+| 主聊天 60/40 分栏 | `src/components/workspace/chats/chat-box.tsx` |
+| 虚拟 URL 内容加载 | `src/core/artifacts/loader.ts` → `loadArtifactContentFromToolCall` |
+| Artifacts 上下文 | `src/components/workspace/artifacts/context.tsx` |
+| Step 2 编排 + 沙箱状态 + 草稿快照 | `src/roundtable-planning/hooks/useStep2Orchestration.ts` |
+| Step 2 沙箱布局 | `src/roundtable-planning/components/Step2SandboxLayout.tsx` |
+| Step 2 文件卡 + 步骤渲染 | `src/roundtable-planning/components/Step2Panel.tsx` |
+| SSE phase 推断 + `onUpstreamFrame` | `src/roundtable-planning/api/multi-agent.ts` → `setPhase` |
+| 主页面侧栏 + 联动 | `src/roundtable-planning/pages/RoundtablePlanningPage.tsx` |
+| 草稿持久化 | `src/roundtable-planning/utils/drafts.ts`、`hooks/useDraftPersistence.ts` |
+
+---
+
+## 7. 下一步建议（给接续开发者）
+
+1. **先跑通 P0 测试清单**，确认 Phase 3/4/5 改造后无回归；重点观察双通道并发写入 stub 时 args 是否被旧帧覆盖（理论上 LangGraph 完整 tool_calls 是单调累积的，应该没问题）。
+2. **Phase 4 收尾**：把 Step 3 的 `listSessionArtifacts` / `HighFidelityReport` 接进沙箱选中态——Step 3 进入时复用 Step 2 的 `ArtifactsProvider`，让用户在 Step 3 也能预览 Step 2 留下的产物。
+3. **Phase 2 边界**：`str_replace` 多轮编辑的 stub 模拟（追加 tool result 消息让 `applyPendingTextEdit` 能 replay edit 序列），优先级低。
+4. **更新** `multi-agent-frontend-dev.md`：Step 2 布局、沙箱架构、`seatStubMessages` 数据流，避免与本文档重复——可在总览文档加一节「见 `roundtable-step2-sandbox-progress.md`」。

frontend-web/docs/ui规范-深蓝/00-基础-色彩字体间距.md

@@ -0,0 +1,580 @@
+# 深蓝色 UI 规范 · 00 基础（色彩 / 字体 / 阴影 / 圆角 / 间距 / 分割线）
+
+> 本文件是《深蓝色 UI 规范》拆分后的**基础篇（§1–§7）**，是全站设计令牌的唯一来源。
+> 其余分册见同目录 `README.md`；可直接 import 的变量见 `tokens.css`。
+> 跨章节 `§N` 编号全局唯一，所属文件见 README 的「§ 索引」。
+
+**本篇目录（§1–§7）**：`1` 色彩 · `2` 字体 · `3` 阴影 · `4` 圆角 · `5` 按钮 · `6` 分割线 · `7` 间距
+
+---
+
+## 1. 色彩
+
+### 1.1 标准色
+
+色彩体系由四个色系构成，每个色系分主色与辅色两组，每组按明度从浅到深编号（01 最浅，数字越大越深）。
+
+---
+
+#### 1.1.1 色系总览
+
+| 色系 | 用途定位 | 代码前缀 |
+|------|----------|----------|
+| 渐红系 | 警示、错误、强调操作 | ZS-001 |
+| 渐蓝系 | 信息、链接、次级操作 | ZS-002 |
+| 渐青系 | 成功、在线状态、数据高亮 | ZS-003 |
+| 深蓝系 | 页面背景、容器、导航底色 | ZS-004 |
+
+---
+
+#### 1.1.2 渐红系（ZS-001）
+
+用于错误提示、危险操作、重要告警。
+
+| 编号 | 色值 | 说明 |
+|------|------|------|
+| ZS-001-01 | `#FFF1F0` | 极浅红，错误背景底色 |
+| ZS-001-02 | `#FFCCC7` | 浅红，输入框错误边框 |
+| ZS-001-03 | `#FFA39E` | — |
+| ZS-001-04 | `#FF7875` | — |
+| ZS-001-05 | `#FF4D4F` | 标准红，Tag / Badge |
+| ZS-001-06 | `#F5222D` | 主色红，按钮 / 图标 |
+| ZS-001-07 | `#CF1322` | 深红，Hover 状态 |
+| ZS-001-08 | `#A8071A` | 深红，Active / Press |
+| ZS-001-09 | `#820014` | 极深红 |
+| ZS-001-10 | `#5C0011` | 最深红 |
+
+---
+
+#### 1.1.3 渐蓝系（ZS-002）
+
+用于信息提示、链接、次级按钮。
+
+| 编号 | 色值 | 说明 |
+|------|------|------|
+| ZS-002-01 | `#E6F4FF` | 极浅蓝，信息背景底色 |
+| ZS-002-02 | `#BAE0FF` | 浅蓝 |
+| ZS-002-03 | `#91CAFF` | — |
+| ZS-002-04 | `#69B1FF` | — |
+| ZS-002-05 | `#4096FF` | 标准蓝，链接 / 信息 Tag |
+| ZS-002-06 | `#1677FF` | 主色蓝，主操作按钮 |
+| ZS-002-07 | `#0958D9` | 深蓝，Hover |
+| ZS-002-08 | `#003EB3` | 深蓝，Active |
+| ZS-002-09 | `#002C8C` | 极深蓝 |
+| ZS-002-10 | `#001D6C` | 最深蓝 |
+
+---
+
+#### 1.1.4 渐青系（ZS-003）
+
+用于成功状态、在线标识、数据图表高亮。
+
+| 编号 | 色值 | 说明 |
+|------|------|------|
+| ZS-003-01 | `#E6FFFB` | 极浅青，成功背景 |
+| ZS-003-02 | `#B5F5EC` | 浅青 |
+| ZS-003-03 | `#87E8DE` | — |
+| ZS-003-04 | `#5CDBD3` | — |
+| ZS-003-05 | `#36CFC9` | 标准青，成功 Tag |
+| ZS-003-06 | `#13C2C2` | 主色青，在线点 / 图标 |
+| ZS-003-07 | `#08979C` | 深青，Hover |
+| ZS-003-08 | `#006D75` | 深青，Active |
+| ZS-003-09 | `#00474F` | 极深青 |
+| ZS-003-10 | `#002329` | 最深青 |
+
+---
+
+#### 1.1.5 深蓝系（ZS-004）
+
+用于页面背景、导航栏、侧边栏、卡片容器。这是深蓝主题的核心色系。
+
+| 编号 | 色值 | 说明 |
+|------|------|------|
+| ZS-004-01 | `#E8EDF5` | 极浅，分割线 / 禁用底色 |
+| ZS-004-02 | `#C5CFE0` | 浅，边框 |
+| ZS-004-03 | `#9BADC8` | — |
+| ZS-004-04 | `#6E88B0` | — |
+| ZS-004-05 | `#4A6491` | 中深蓝，次级文字 |
+| ZS-004-06 | `#2D4473` | 深蓝，卡片容器背景 |
+| ZS-004-07 | `#1A2F5A` | 深蓝，侧边栏背景 |
+| ZS-004-08 | `#122347` | 深蓝，导航栏背景 |
+| ZS-004-09 | `#0C1836` | 极深蓝，页面背景 |
+| ZS-004-10 | `#060E24` | 最深，全局底色 |
+
+---
+
+#### 1.1.6 功能色（主色 / 字体色 / 辅色 / 背景色）
+
+从标准色系中提取，用于具体 UI 角色指定。
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 主色（Primary） | `#1677FF` | ZS-002-06 |
+| 主色 Hover | `#0958D9` | ZS-002-07 |
+| 主色 Active | `#003EB3` | ZS-002-08 |
+| 正常字体色 | `#C5CFE0` | ZS-004-02 |
+| 次级字体色 | `#6E88B0` | ZS-004-04 |
+| 禁用字体色 | `#4A6491` | ZS-004-05 |
+| 辅色（Accent） | `#13C2C2` | ZS-003-06 |
+| 页面背景色 | `#0C1836` | ZS-004-09 |
+| 容器背景色 | `#1A2F5A` | ZS-004-07 |
+| 白色 | `#FFFFFF` | — |
+
+---
+
+#### 1.1.7 小面积装饰色
+
+用于图标点缀、徽标、少量强调，不用于大面积背景。
+
+| 色值 | 说明 |
+|------|------|
+| `#6388FF` | 紫蓝，图标装饰 |
+| `#F5222D` | 红色，危险徽标 |
+| `#12306C` | 深蓝，品牌点缀 |
+| `#478880` | 青绿，辅助点缀 |
+| `#950404` | 深红，重要告警点 |
+
+---
+
+#### 1.1.8 图表配色
+
+**通用图表色序**（面积较大，如柱状图、折线图、饼图）：
+
+| 序号 | 色值 |
+|------|------|
+| 1 | `#1677FF` |
+| 2 | `#13C2C2` |
+| 3 | `#4096FF` |
+| 4 | `#36CFC9` |
+| 5 | `#69B1FF` |
+| 6 | `#5CDBD3` |
+| 7 | `#91CAFF` |
+| 8 | `#87E8DE` |
+
+**小面积图表色序**（面积较小，如散点、小徽章、迷你图）：
+
+| 序号 | 色值 |
+|------|------|
+| 1 | `#4096FF` |
+| 2 | `#36CFC9` |
+| 3 | `#FF4D4F` |
+| 4 | `#FFA39E` |
+| 5 | `#6388FF` |
+| 6 | `#478880` |
+
+---
+
+#### 1.1.9 功能语义色（Functional / Status）
+
+承载「成功 / 警告 / 错误 / 信息 / 处理中」语义。其中**错误红、信息蓝、处理中青**直接复用标准色；**成功绿、警告橙**为标准色系之外的补充色（深色背景下 ZS-003 青偏冷、且无现成橙），在此正式收录。全站语义场景一律引用本表，不再各处自定义。
+
+| 语义 | 色值 | 来源 | 典型用途 |
+|------|------|------|----------|
+| 成功 / 已完成 | `#52C41A` | 补充色（绿） | 成功提示、完成状态、通过校验 |
+| 警告 / 进行中 | `#FAAD14` | 补充色（橙） | 警告提示、进行中、需注意 |
+| 错误 / 失败 | `#F5222D` | ZS-001-06 | 错误提示、删除、失败状态 |
+| 信息 / 默认 | `#1677FF` | ZS-002-06 | 信息提示、主操作、链接 |
+| 处理中 / 等待 | `#13C2C2` | ZS-003-06 | 处理中、排队、等待反馈 |
+
+> 浅底变体（Message / Alert / Tag 底色）：前景色取 16% 透明度，如成功底 `rgba(82,196,26,0.16)`、警告底 `rgba(250,173,20,0.16)`。
+> CSS Token 见 `tokens.css` 的 `--func-success / --func-warning / --func-error / --func-info / --func-processing`。
+
+---
+
+## 2. 字体
+
+### 2.1 全局样式 - 字体
+
+---
+
+#### 2.1.1 大屏页面字体规范
+
+##### 中文字体：Noto Sans S Chinese
+
+| 样式 | 使用场景 |
+|------|----------|
+| 24px Bold | 一级标题 |
+| 24px Medium | 次要一级标题 |
+| 22px Medium | 二级标题 |
+| 22px Regular | 正文 |
+| 20px Regular | 排版空间有限的正文 |
+
+##### 数字字体：D-DIN
+
+| 样式 | 使用场景 |
+|------|----------|
+| 32px Bold | 重要数据展示 |
+| 32px Regular | 普通数据展示 |
+| 26px Bold | 常规数据展示 |
+| 26px Regular | 常规数据展示 |
+
+##### 特殊数字：DS-Digital
+
+| 样式 | 使用场景 |
+|------|----------|
+| 50px Bold | 大屏主数据展示 |
+
+##### 表格字体：Arial
+
+| 样式 | 使用场景 |
+|------|----------|
+| 20px Regular | 表格横纵轴数字 |
+
+---
+
+#### 2.1.2 后台系统字体规范
+
+##### 中文字体：Noto Sans S Chinese
+
+| 样式 | 使用场景 |
+|------|----------|
+| 18px Bold | 导航、一级标题 |
+| 18px Medium | 次要一级标题 |
+| 16px Bold | 二级标题 |
+| 16px Medium | 次要二级标题 |
+| 16px Regular | 正文、按钮内部文字等 |
+| 16px Light | 次要正文 |
+
+##### 数字字体：D-DIN
+
+| 样式 | 使用场景 |
+|------|----------|
+| 26px Bold | 重要数据展示 |
+| 26px Regular | 普通数据展示 |
+| 24px Bold | 常规数据展示（小） |
+| 24px Regular | 常规数据展示（小） |
+
+##### LOGO 字体：DOUYUFont
+
+| 样式 | 使用场景 |
+|------|----------|
+| 20px 文字样式 | 页面顶部系统名称 |
+
+##### 表格数字：Arial
+
+| 样式 | 使用场景 |
+|------|----------|
+| 16px Regular | 表格横纵轴数字 |
+| 14px Regular | 表格横轴数字（空间有限） |
+
+---
+
+## 3. 阴影
+
+### 3.1 容器与卡片配色
+
+阴影组通过深浅层级叠加形成空间感：外层容器最深，内层卡片次之，边框与高亮文字使用主色或字体色。
+
+#### 3.1.1 外层容器
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 页面 / 最外层背景 | `#060E24` | ZS-004-10 |
+| 分栏容器背景 | `#0C1836` | ZS-004-09 |
+
+#### 3.1.2 卡片（标题 + 操作）
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 卡片背景 | `#122347` | ZS-004-08 |
+| 卡片边框 | `#1A2F5A` | ZS-004-07 |
+| 卡片阴影（外发光） | `rgba(22, 119, 255, 0.12)` | 基于 ZS-002-06 主色蓝 12% 透明度 |
+| 标题文字（16px Bold） | `#C5CFE0` | ZS-004-02（正常字体色） |
+| 操作按钮文字 | `#4096FF` | ZS-002-05（标准蓝，链接） |
+| 次级操作图标（✏️ / ⋯） | `#6E88B0` | ZS-004-04（次级字体色） |
+
+#### 3.1.3 卡片新增（占位卡片）
+
+虚线描边的"新增入口"卡片，用于引导用户添加内容。
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 卡片背景 | `#0C1836` | ZS-004-09（与外层同色，营造凹陷感） |
+| 虚线边框 | `#4096FF` | ZS-002-05 |
+| 加号图标 | `#4096FF` | ZS-002-05 |
+
+#### 3.1.4 阴影投影规则
+
+| 层级 | 阴影值 | 使用场景 |
+|------|--------|----------|
+| 一级阴影（卡片悬浮） | `0 2px 8px rgba(22, 119, 255, 0.12)` | 普通卡片 |
+| 二级阴影（hover / 强调） | `0 4px 16px rgba(22, 119, 255, 0.24)` | 卡片 hover、弹出层 |
+| 三级阴影（弹窗 / Modal） | `0 8px 32px rgba(6, 14, 36, 0.6)` | Dialog、Drawer |
+
+---
+
+## 4. 圆角
+
+### 4.1 圆角统一规范
+
+| 元素 | 圆角值 | 说明 |
+|------|--------|------|
+| 按钮 | `2px` | 所有按钮（主按钮 / 次按钮 / 文本按钮）统一使用 |
+| 卡片 | `4px` | 内容卡片、标题+操作卡片、卡片新增占位 |
+| 页面分栏框 | `4px` | 外层容器、分栏区域 |
+| 输入框 / 选择器 | `2px` | 与按钮一致，保持表单内对齐 |
+| Tag / Badge | `2px` | 与按钮一致 |
+| Modal / Drawer | `4px` | 与卡片一致 |
+
+### 4.2 按钮配色（圆角 2px）
+
+#### 4.2.1 主按钮（Primary）
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 背景 | `#1677FF` | ZS-002-06 |
+| 文字 | `#FFFFFF` | — |
+| Hover 背景 | `#0958D9` | ZS-002-07 |
+| Active 背景 | `#003EB3` | ZS-002-08 |
+| 禁用背景 | `#4A6491` | ZS-004-05 |
+| 禁用文字 | `#6E88B0` | ZS-004-04 |
+
+#### 4.2.2 次按钮（Outline / Default）
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 背景 | `transparent` | — |
+| 边框 | `#6E88B0` | ZS-004-04 |
+| 文字 | `#C5CFE0` | ZS-004-02 |
+| Hover 边框 | `#4096FF` | ZS-002-05 |
+| Hover 文字 | `#4096FF` | ZS-002-05 |
+| Active 边框 | `#1677FF` | ZS-002-06 |
+
+### 4.3 卡片与分栏（圆角 4px）
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 卡片背景 | `#122347` | ZS-004-08 |
+| 卡片边框 | `#1A2F5A` | ZS-004-07 |
+| 分栏框背景 | `#0C1836` | ZS-004-09 |
+| 分栏框边框 | `#1A2F5A` | ZS-004-07 |
+
+---
+
+## 5. 按钮
+
+> 全部圆角 `2px`，文字字号 14px（小尺寸）/ 14px（正常尺寸），字体 Noto Sans S Chinese Regular。
+
+### 5.1 按钮尺寸
+
+| 规格 | 高度 | 内边距 | 使用场景 |
+|------|------|--------|----------|
+| 小 | `28px` | `0 10px` | 空间小的板块内部，如表格中、卡片标题等 |
+| 正常 | `32px` | `0 14px` | 默认尺寸，所有常用按钮 |
+
+### 5.2 按钮类型与配色
+
+#### 5.2.1 主按钮（Primary）
+
+> 一个操作区域只能有一个主按钮。
+
+| 状态 | 背景 | 边框 | 文字 |
+|------|------|------|------|
+| 默认 | `#1677FF` (ZS-002-06) | — | `#FFFFFF` |
+| Hover | `#0958D9` (ZS-002-07) | — | `#FFFFFF` |
+| Active | `#003EB3` (ZS-002-08) | — | `#FFFFFF` |
+| 失效 | `rgba(22, 119, 255, 0.35)` | — | `#6E88B0` (ZS-004-04) |
+
+#### 5.2.2 默认按钮（Default / Outline）
+
+用于"取消 / 返回"等次要操作，与主按钮成对出现时主按钮在右。
+
+| 状态 | 背景 | 边框 | 文字 |
+|------|------|------|------|
+| 默认 | `transparent` | `#6E88B0` (ZS-004-04) | `#C5CFE0` (ZS-004-02) |
+| Hover | `rgba(22, 119, 255, 0.08)` | `#4096FF` (ZS-002-05) | `#4096FF` (ZS-002-05) |
+| Active | `rgba(22, 119, 255, 0.16)` | `#1677FF` (ZS-002-06) | `#1677FF` (ZS-002-06) |
+| 失效 | `transparent` | `#4A6491` (ZS-004-05) | `#4A6491` (ZS-004-05) |
+
+#### 5.2.3 文本按钮（Text）
+
+用于表格操作、文件下载等。无背景与边框，靠文字色识别。
+
+| 状态 | 文字 | 装饰 |
+|------|------|------|
+| 默认 | `#4096FF` (ZS-002-05) | 无下划线 |
+| Hover | `#1677FF` (ZS-002-06) | 显示下划线（与文字同色） |
+| Active | `#0958D9` (ZS-002-07) | 下划线 |
+| 失效 | `#4A6491` (ZS-004-05) | 无装饰 |
+
+#### 5.2.4 图标按钮（Icon-only）
+
+用于增强辨识度或节省空间。仅图标，无文字。
+
+| 变体 | 背景 | 图标颜色 |
+|------|------|----------|
+| 主色（常用） | `#1677FF` (ZS-002-06) | `#FFFFFF` |
+| 主色 Hover | `#0958D9` (ZS-002-07) | `#FFFFFF` |
+| 危险（删除等） | `#F5222D` (ZS-001-06) | `#FFFFFF` |
+| 危险 Hover | `#CF1322` (ZS-001-07) | `#FFFFFF` |
+| 透明（仅图标） | `transparent` | `#6E88B0` (ZS-004-04) → hover `#4096FF` (ZS-002-05) |
+
+### 5.3 按钮组合
+
+#### 5.3.1 文字 + 下拉按钮（含 ▾）
+
+两种填充：
+
+| 形态 | 配色规则 |
+|------|----------|
+| 默认（Outline） | 沿用 §5.2.2 默认按钮，箭头 ▾ 与文字同色 `#C5CFE0` |
+| 主色（Filled） | 沿用 §5.2.1 主按钮，箭头 ▾ 同步白色 `#FFFFFF` |
+
+#### 5.3.2 图标 + 文字按钮（如 `+ 正常`）
+
+| 形态 | 配色规则 |
+|------|----------|
+| 默认（Outline） | 沿用 §5.2.2，左侧图标颜色与文字一致 `#C5CFE0` |
+| 主色（Filled） | 沿用 §5.2.1，左侧图标与文字一致 `#FFFFFF` |
+
+#### 5.3.3 文本按钮 + 图标（"更多 »"、"展开 ⌄"、"下一页 »"、"« 上一页"）
+
+| 角色 | 色值 |
+|------|------|
+| 文字 + 图标（默认） | `#4096FF` (ZS-002-05) |
+| 文字 + 图标（Hover） | `#1677FF` (ZS-002-06) |
+| 失效 | `#4A6491` (ZS-004-05) |
+
+> 图标可在文字前或后；多个文本按钮排成一行时，间距 `16px`，无分隔符。
+
+#### 5.3.4 主按钮 + 默认按钮组合（如"确定 / 取消 / 返回"）
+
+- **排列顺序**：默认按钮在左，主按钮在右（最右侧为主操作）
+- **按钮间距**：`8px`
+- **示例**：`[ 返回 ] [ 取消 ] [ 确定 ]`
+- **配色**：主按钮沿用 §5.2.1，其余沿用 §5.2.2
+
+### 5.4 其他按钮
+
+#### 5.4.1 悬浮状态（Floating）
+
+用于 Banner / 登录 / 视觉冲击强等展示场景。配色与主按钮一致，叠加阴影抬升。
+
+| 状态 | 阴影 |
+|------|------|
+| 默认 | `0 2px 8px rgba(22, 119, 255, 0.12)`（§3.1.4 一级阴影） |
+| Hover | `0 4px 16px rgba(22, 119, 255, 0.24)`（§3.1.4 二级阴影） |
+| Active | 阴影消失，按下感 |
+
+#### 5.4.2 加载中（Loading）
+
+用于异步操作等待反馈。点击瞬间将按钮锁定，文字前显示旋转图标。
+
+| 角色 | 色值 |
+|------|------|
+| 背景 | `#1677FF` (ZS-002-06) |
+| 文字 | `#FFFFFF` |
+| 加载图标 | `#FFFFFF`，旋转动画 `1.2s linear infinite` |
+| 不可点击 | 鼠标 `cursor: not-allowed` |
+
+> 与失效态的区别：失效是"不可操作"，加载是"操作进行中"——保留品牌主色，只是不可再次触发。
+
+---
+
+## 6. 分割线
+
+> 统一线宽 `1px`，颜色全部从 ZS-004 深蓝系取色，与深色背景保持低对比度但仍可识别。
+
+### 6.1 水平分割线
+
+水平分割线常用来对不同元素内容进行分割。
+
+| 类型 | 色值 | 来源 | 样式 | 使用场景 |
+|------|------|------|------|----------|
+| 实线（默认） | `#4A6491` | ZS-004-05 | `border-top: 1px solid` | 模块间、列表项间分割 |
+| 实线（强调） | `#6E88B0` | ZS-004-04 | `border-top: 1px solid` | 主区块标题下方、卡片头部分割 |
+| 实线（弱化） | `#2D4473` | ZS-004-06 | `border-top: 1px solid` | 卡片内部、密集列表分隔 |
+| 虚线 | `#4A6491` | ZS-004-05 | `border-top: 1px dashed` | 次级 / 层级内分割，提示"非主结构" |
+| 主色实线（高亮） | `#1677FF` | ZS-002-06 | `border-top: 1px solid` | 强调分隔，少量使用（如当前激活区块底边） |
+
+### 6.2 垂直分割线
+
+垂直分割线常用来做行内分割（如导航项之间、状态指示之间、表格列头之间）。
+
+| 类型 | 色值 | 来源 | 样式 | 使用场景 |
+|------|------|------|------|----------|
+| 实线（默认） | `#4A6491` | ZS-004-05 | `border-left: 1px solid` | 行内 inline 元素分割（面包屑、操作按钮组） |
+| 实线（弱化） | `#2D4473` | ZS-004-06 | `border-left: 1px solid` | 表格列分割、紧凑布局 |
+| 虚线 | `#4A6491` | ZS-004-05 | `border-left: 1px dashed` | 多列对齐辅助、辅助参考线 |
+
+### 6.3 规格与间距
+
+| 规则 | 取值 |
+|------|------|
+| 线宽 | `1px` |
+| 水平分割线与上下元素间距 | `≥ 8px`（紧凑布局可用 `4px`） |
+| 垂直分割线与左右元素间距 | `≥ 8px`（行内紧凑 `4px`） |
+| 垂直分割线高度 | 与文字行高一致，约 `12–14px`（也可全高跟随容器） |
+| 透明度 | 必要时叠 `opacity: 0.6` 实现"更弱"层级 |
+
+### 6.4 CSS 参考
+
+```css
+/* 默认水平分割线 */
+.divider-h        { border-top: 1px solid #4A6491; }
+.divider-h-strong { border-top: 1px solid #6E88B0; }
+.divider-h-weak   { border-top: 1px solid #2D4473; }
+.divider-h-dashed { border-top: 1px dashed #4A6491; }
+.divider-h-accent { border-top: 1px solid #1677FF; }
+
+/* 垂直分割线 */
+.divider-v        { border-left: 1px solid #4A6491; height: 14px; display: inline-block; vertical-align: middle; }
+.divider-v-weak   { border-left: 1px solid #2D4473; height: 14px; display: inline-block; vertical-align: middle; }
+.divider-v-dashed { border-left: 1px dashed #4A6491; height: 14px; display: inline-block; vertical-align: middle; }
+```
+
+---
+
+## 7. 间距
+
+> 全站以 `8px (0.5rem)` 为对照基准单位，划分"密 / 疏"两个层次。所有间距取值均来自下列阶梯，禁止使用非阶梯值（如 5px、13px）。
+
+### 7.1 间距阶梯
+
+| 阶 | px | rem | 分组 | 典型场景 |
+|----|------|--------|------|----------|
+| 1 | `4px` | `0.25rem` | 密 | 图标与文字间距、Tag 内边距、紧凑徽标 |
+| 2 | `8px` | `0.5rem` | 密 | 行内元素相邻、按钮组间距、表单 label 与控件 |
+| 3 | `12px` | `0.75rem` | 密 | 表单项垂直间距、列表项内边距 |
+| 4 | `16px` | `1rem` | 密 | 卡片内容内边距、模块内分隔 |
+| 5 | `24px` | `1.5rem` | 疏 | 模块之间、Section 内边距 |
+| 6 | `32px` | `2rem` | 疏 | 卡片之间、表单组之间 |
+| 7 | `40px` | `2.5rem` | 疏 | 主区块之间、页面 Header / Footer 内边距 |
+| 8 | `56px` | `3.5rem` | 疏 | 页面段落级隔断、Banner 区域 |
+
+> "密"对应紧凑信息密度（表格、表单、卡片内部）；"疏"对应视觉呼吸（模块之间、页面整体留白）。**16px 是"密"的上限，24px 是"疏"的下限**，两者之间不应再插入自定义值。
+
+### 7.2 使用原则
+
+- **同层级一致**：同一布局层级内的间距必须使用同一阶值；多种取值会破坏节奏。
+- **就近取阶**：相邻区块的间距尽量从相邻阶梯取值（如 `16px → 24px`），跨越过多阶（如 `8px → 56px`）会让视觉断裂。
+- **密疏不混用**：一个组件内部全部用"密"，外部用"疏"，避免内/外间距颠倒。
+- **优先 8 的倍数**：除最小阶 `4px` 外，所有阶皆为 8 的倍数，方便 4/8 网格对齐。
+- **响应式按比例衰减**：移动端可整体降一阶（如 `24px → 16px`），但仍在阶梯内。
+
+### 7.3 CSS Token 建议
+
+```css
+:root {
+  --spacing-1: 4px;   /* 0.25rem */
+  --spacing-2: 8px;   /* 0.5rem  */
+  --spacing-3: 12px;  /* 0.75rem */
+  --spacing-4: 16px;  /* 1rem    */
+  --spacing-5: 24px;  /* 1.5rem  */
+  --spacing-6: 32px;  /* 2rem    */
+  --spacing-7: 40px;  /* 2.5rem  */
+  --spacing-8: 56px;  /* 3.5rem  */
+}
+```
+
+### 7.4 与已有规范的对齐
+
+| 已有规则 | 对应阶 |
+|----------|--------|
+| §4.x 卡片圆角内边距 | `--spacing-4` (16px) |
+| §5.3.4 主+默认按钮组合间距 `8px` | `--spacing-2` |
+| §5.3.3 文本按钮间距 `16px` | `--spacing-4` |
+| §6.3 分割线与上下元素间距 `≥ 8px` | `--spacing-2` 起 |
+
+---
+

frontend-web/docs/ui规范-深蓝/01-导航.md

@@ -0,0 +1,780 @@
+# 深蓝色 UI 规范 · 01 导航（§8–§13）
+
+> 《深蓝色 UI 规范》分册之一。基础令牌见 `00-基础-色彩字体间距.md`，可 import 的变量见 `tokens.css`，总目录与 §索引见 `README.md`。`§N` 编号全局唯一。
+
+**本篇目录**：`8` 导航组件 · `9` 锚点与页签 · `10` 步骤条 · `11` 面包屑 · `12` 页头 · `13` 分页
+
+---
+
+## 8. 导航组件
+
+> 适用于"大屏后台 / 控制台"类深蓝主题界面。整体结构 = 顶部导航 + 左侧分级菜单 + 多级下拉。所有颜色取自 ZS-002 / ZS-004 两个色系。
+
+### 8.1 整体结构
+
+```
+┌─ 顶部导航（Header）─ 高 56px ──────────────────────────────────────────────┐
+│ ≡ 二级菜单 二级菜单 二级菜单  〈一级菜单〉〈一级菜单〉  ⟪ XXXX系统 ⟫  〈一级菜单〉  ⟳ 时间  ⌂ 返回首页 │
+├──┬──────────────────────────────────────────────────────────────────────────┤
+│ 三│  ┌─ 四级菜单（下拉面板）──┐                                              │
+│ 级│  │ ▾ 四级菜单             │                                              │
+│ 菜│  │   ▾ 五级菜单           │                                              │
+│ 单│  │     - 六级菜单 (active)│                                              │
+│ 三│  │     - 六级菜单         │                                              │
+│ 级│  │   ▸ 五级菜单           │                                              │
+│ 菜│  │ ▸ 四级菜单             │                                              │
+│ 单│  └────────────────────────┘                                              │
+│ …│                                                                          │
+└──┴──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 8.2 顶部导航（Header）
+
+#### 8.2.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 高度 | `56px` |
+| 左右 padding | `--spacing-4` (16px) |
+| 背景 | 渐变 `linear-gradient(180deg, #122347 0%, #0C1836 100%)`（ZS-004-08 → ZS-004-09） |
+| 底边 | `border-bottom: 1px solid #1A2F5A` (ZS-004-07) |
+| 阴影 | `0 2px 8px rgba(6, 14, 36, 0.6)`（§3.1.4 一级阴影变体） |
+| 文字基线 | `Noto Sans S Chinese`，垂直居中 |
+
+#### 8.2.2 二级菜单（左侧 Tabs，小号 14px）
+
+| 状态 | 文字 | 背景 | 装饰 |
+|------|------|------|------|
+| 默认 | `#6E88B0` (ZS-004-04) | `transparent` | — |
+| Hover | `#C5CFE0` (ZS-004-02) | `rgba(22,119,255,0.08)` | — |
+| 激活 | `#4096FF` (ZS-002-05) | `transparent` | 底部 `2px solid #4096FF` 高亮线 |
+
+- 字号 `14px Regular`，间距 `--spacing-3` (12px)
+- 与最左侧的"折叠菜单 ≡"图标间距 `--spacing-4` (16px)
+
+#### 8.2.3 一级菜单（中部主导航，16px 带切角装饰）
+
+| 状态 | 文字 | 装饰 |
+|------|------|------|
+| 默认 | `#C5CFE0` (ZS-004-02) | 两端切角斜边，`border: 1px solid #1A2F5A` |
+| Hover | `#4096FF` (ZS-002-05) | 切角线变 `#4096FF` |
+| 激活 | `#FFFFFF` | 切角线 `#1677FF` (ZS-002-06)，背景 `rgba(22,119,255,0.16)` |
+
+- 字号 `16px Medium`
+- 切角推荐 `clip-path: polygon(8px 0, calc(100% - 8px) 0, 100% 100%, 0 100%)`
+- 项间距 `--spacing-2` (8px)
+
+#### 8.2.4 系统标题（XXXX系统）
+
+- 字号 `20px Bold`，颜色 `#FFFFFF`
+- 字体 `DOUYUFont` 或 Noto Sans Medium
+- 左右装饰用主色蓝渐变线条：`linear-gradient(90deg, transparent 0%, #1677FF 50%, transparent 100%)`，线宽 `1px`
+- 居中相对 Header 几何中心，左右最少留 `--spacing-6` (32px) 间距给一级菜单
+
+#### 8.2.5 右侧工具区（时间 / 图标 / 返回首页）
+
+| 元素 | 字号/尺寸 | 颜色 |
+|------|----------|------|
+| 更新时间文字 | `12px Regular` | `#6E88B0` (ZS-004-04) |
+| 时间数值（数字） | `12px D-DIN Regular` | `#C5CFE0` (ZS-004-02) |
+| 工具图标（刷新/上/家） | `16px` | `#6E88B0`，hover → `#4096FF` |
+| 返回首页文字 | `14px Regular` | `#C5CFE0`，hover → `#4096FF` |
+
+- 元素间距 `--spacing-3` (12px)
+- 整体右 padding `--spacing-4` (16px)
+
+### 8.3 侧边栏（三级菜单）
+
+#### 8.3.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 宽度 | `64px`（仅图标 / 竖排文字） |
+| 背景 | `#0C1836` (ZS-004-09) |
+| 右边界 | `border-right: 1px solid #1A2F5A` (ZS-004-07) |
+| 项高度 | `64px`（与宽度一致，呈正方形） |
+| 项内间距 | 上下 `--spacing-3` (12px) |
+| 字号 | `14px Medium`，竖排（`writing-mode: vertical-rl`）或正常排两行 |
+
+#### 8.3.2 状态配色
+
+| 状态 | 背景 | 文字 | 左侧指示条 |
+|------|------|------|-----------|
+| 默认 | `transparent` | `#6E88B0` (ZS-004-04) | 无 |
+| Hover | `rgba(22,119,255,0.08)` | `#C5CFE0` (ZS-004-02) | 无 |
+| 激活 | `#1A2F5A` (ZS-004-07) | `#FFFFFF` | 左侧 `2px solid #1677FF` (ZS-002-06) |
+
+### 8.4 下拉菜单面板（四级 / 五级 / 六级）
+
+#### 8.4.1 面板规格
+
+| 属性 | 取值 |
+|------|------|
+| 背景 | `#122347` (ZS-004-08) |
+| 边框 | `1px solid #1A2F5A` (ZS-004-07) |
+| 阴影 | `0 4px 16px rgba(6, 14, 36, 0.6)`（§3.1.4 三级阴影变体） |
+| 圆角 | `4px` |
+| 内边距 | 上下 `--spacing-2` (8px) |
+| 最小宽度 | `150px` |
+
+#### 8.4.2 菜单项规格
+
+| 层级 | 缩进（padding-left） | 字号 | 展开图标 | 前缀 |
+|------|---------------------|------|----------|------|
+| 四级菜单 | `--spacing-3` (12px) | `14px Medium` | `▾ / ▸` | — |
+| 五级菜单 | `--spacing-5` (24px) | `14px Regular` | `▾ / ▸` | — |
+| 六级菜单 | `--spacing-6` (32px) | `14px Regular` | — | `-` 短横线 |
+
+- 行高 `32px`
+- 项之间无分割线（靠缩进与图标区分层级）
+
+#### 8.4.3 菜单项配色
+
+| 状态 | 背景 | 文字 | 展开图标 |
+|------|------|------|----------|
+| 默认 | `transparent` | `#C5CFE0` (ZS-004-02) | `#6E88B0` (ZS-004-04) |
+| Hover | `rgba(22,119,255,0.08)` | `#4096FF` (ZS-002-05) | `#4096FF` |
+| 激活（当前选中） | `rgba(22,119,255,0.16)` | `#4096FF` (ZS-002-05) | `#1677FF` (ZS-002-06) |
+| 父级（含激活子项） | `transparent` | `#FFFFFF` | `#1677FF` |
+| 失效 | `transparent` | `#4A6491` (ZS-004-05) | `#4A6491` |
+
+### 8.5 交互与动画
+
+| 行为 | 动效 |
+|------|------|
+| 下拉面板展开 | `transform-origin: top; transform: scaleY(0.95) → scaleY(1); opacity 0 → 1`，`200ms ease-out` |
+| 展开图标旋转 | `transform: rotate(0 → 90deg)`，`200ms ease-out` |
+| Hover 背景过渡 | `background-color 120ms ease-out` |
+| 激活底部高亮线（二级菜单） | `width 0% → 100%`，`240ms ease-out` |
+
+### 8.6 间距引用
+
+| 位置 | 取值 |
+|------|------|
+| Header 内部元素间距 | `--spacing-2 / --spacing-3` |
+| Header 与下方内容间距 | `0`（贴合，靠底边线与阴影区分） |
+| 侧边栏与下拉面板间距 | `--spacing-1` (4px) |
+| 下拉面板与触发元素间距 | `--spacing-1` (4px) |
+| 同级菜单项之间 | `0`（紧贴排列，靠 hover/active 背景区分） |
+
+---
+
+## 9. 锚点与页签
+
+> 对应"4.2 导航组件-锚点"。三类组件共用主色蓝指示当前位置：**页签 / 锚点 / 回到顶部**。
+>
+> 视觉参考：标签横向 / 标签纵向 / 锚点的三联图见设计稿「选项卡.png」——三种形态在本节均已规范化（§9.1 = 标签横纵向、§9.2 = 锚点）。
+
+### 9.1 页签（Tabs）
+
+#### 9.1.1 横向页签（下划线-横向）
+
+| 状态 | 文字 | 下划线 |
+|------|------|--------|
+| 默认 | `#C5CFE0` (ZS-004-02) | 无 |
+| Hover | `#4096FF` (ZS-002-05) | 无 |
+| 激活 | `#4096FF` (ZS-002-05) | `2px solid #4096FF`，宽度与文字齐 |
+| 失效 | `#4A6491` (ZS-004-05) | 无 |
+
+- 字号 `14px Medium`
+- 项间距 `--spacing-5` (24px)
+- 下划线与文字底部间距 `--spacing-2` (8px)
+- 容器底边可叠一条 `1px solid #1A2F5A` (ZS-004-07) 作为基线，激活态的高亮线压在上面
+
+#### 9.1.2 纵向页签（下划线-纵向）
+
+| 状态 | 文字 | 右侧指示线 |
+|------|------|-----------|
+| 默认 | `#C5CFE0` (ZS-004-02) | 无 |
+| Hover | `#4096FF` (ZS-002-05) | 无 |
+| 激活 | `#4096FF` (ZS-002-05) | 右侧 `2px solid #4096FF`，高度与文字齐 |
+| 失效 | `#4A6491` (ZS-004-05) | 无 |
+
+- 字号 `14px Medium`，项高度 `32px`
+- 项间距 `--spacing-2` (8px)
+- 容器右边可叠一条 `1px solid #1A2F5A` 基线，激活指示线压在上面
+
+### 9.2 锚点（Anchor）
+
+用于长内容页（如详情页、文档页）的章节快速跳转。
+
+#### 9.2.1 结构
+
+```
+│ 一级
+│ 一级          (active)
+│    二级
+│    二级
+│ 一级
+│ 一级
+```
+
+#### 9.2.2 规格
+
+| 属性 | 取值 |
+|------|------|
+| 容器背景 | `#122347` (ZS-004-08) 或 `transparent`（嵌入页面侧栏时） |
+| 左侧基线 | `1px solid #1A2F5A` (ZS-004-07) 通栏 |
+| 项高度 | `32px` |
+| 一级项左 padding | `--spacing-3` (12px) |
+| 二级项左 padding | `--spacing-5` (24px) |
+| 项间距 | `0`（贴合排列） |
+| 字号 | `14px Regular` |
+
+#### 9.2.3 状态配色
+
+| 状态 | 一级文字 | 二级文字 | 左侧指示条 |
+|------|----------|----------|-----------|
+| 默认 | `#C5CFE0` (ZS-004-02) | `#6E88B0` (ZS-004-04) | 无 |
+| Hover | `#4096FF` (ZS-002-05) | `#4096FF` (ZS-002-05) | 无 |
+| 激活 | `#4096FF` (ZS-002-05) | — | 左侧 `2px solid #4096FF`，覆盖容器基线 |
+| 父级（含激活子项） | `#FFFFFF` | — | — |
+
+- 激活态指示条与基线重合，宽 `2px`，色压主色蓝 `#4096FF`
+- 二级项**不单独支持激活态**：当二级被点中时，其父级一级显示激活态，左侧指示条按父级位置渲染
+
+#### 9.2.4 滚动同步
+
+| 行为 | 规则 |
+|------|------|
+| 页面滚动 | 监听锚点对应区块进入视口的相对位置，自动切换激活态 |
+| 点击锚点 | `behavior: smooth` 滚动到目标，激活指示条 `top` 过渡 `200ms ease-out` |
+| 边界处理 | 滚动到页面顶部 → 第一个锚点激活；到页尾 → 最后一个锚点激活 |
+
+### 9.3 回到顶部（BackToTop）
+
+固定在视口右下角的悬浮按钮，向上滚动到页面顶部。
+
+#### 9.3.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 形状 | 圆形 `40px × 40px`（`border-radius: 50%`） |
+| 图标 | `↑` 上箭头，`16px`，`#FFFFFF` |
+| 距视口右边 | `--spacing-5` (24px) |
+| 距视口下边 | `--spacing-6` (32px) |
+| 出现时机 | 页面 `scrollTop > 200px` 时淡入；回到顶部后淡出 |
+| 淡入/淡出 | `opacity 0 → 1` / `1 → 0`，`200ms ease-out` |
+
+#### 9.3.2 状态配色
+
+| 状态 | 背景 | 阴影 | 图标 |
+|------|------|------|------|
+| 正常（默认） | `#1677FF` (ZS-002-06) | `0 2px 8px rgba(22,119,255,0.12)` (§3.1.4 一级阴影) | `#FFFFFF` |
+| 悬停（Hover） | `#0958D9` (ZS-002-07) | `0 4px 16px rgba(22,119,255,0.24)` (§3.1.4 二级阴影) | `#FFFFFF` |
+| 点按（Active） | `#003EB3` (ZS-002-08) | 阴影消失，按下感 | `#FFFFFF` |
+| 失效 / 不显示 | — | — | 整体 `opacity: 0`，`pointer-events: none` |
+
+#### 9.3.3 悬停 Tooltip
+
+Hover 状态下方显示 `回到顶部` 提示气泡：
+
+| 属性 | 取值 |
+|------|------|
+| 文字 | `回到顶部`，`12px Regular` |
+| 文字颜色 | `#C5CFE0` (ZS-004-02) |
+| 背景 | `#1677FF` (ZS-002-06) |
+| 圆角 | `2px` |
+| 内边距 | 上下 `4px`，左右 `--spacing-2` (8px) |
+| 与按钮间距 | `--spacing-2` (8px) |
+| 出现时机 | Hover 进入 `300ms` 后显示，离开立即消失 |
+
+### 9.4 三者的差异与选用
+
+| 组件 | 主要用途 | 视觉特征 |
+|------|----------|---------|
+| 页签 | 同层级内容切换（多 Tab 互斥） | 文字 + 下划线（横/纵） |
+| 锚点 | 长页面内章节跳转 | 文字 + 左侧指示条 + 层级缩进 |
+| 回到顶部 | 长页面快速返回起点 | 圆形悬浮按钮 + 上箭头 |
+
+---
+
+## 10. 步骤条
+
+> 对应「4.7 导航组件-步骤条」。用于多步流程的进度指引，按布局方向分**横向**与**纵向**两类，按使用场景分**弹窗步骤条**、**页面步骤条**、**纵向步骤条**三种。所有颜色取自 ZS-002 主色蓝与 ZS-004 深蓝系。
+
+### 10.1 步骤节点（公共）
+
+每个步骤由「指示圆 + 标题（可选描述）」组成。指示圆按状态切换三种形态：
+
+| 状态 | 圆形外观 | 圆内符号 | 来源 |
+|------|----------|----------|------|
+| 已完成（Completed） | 描边圆，`2px solid #1677FF`，背景 `transparent` | `✓`（对勾，`#1677FF`） | ZS-002-06 |
+| 当前（Current / Active） | 实心圆，背景 `#1677FF` | 步骤数字，`#FFFFFF` | ZS-002-06 / 白 |
+| 未开始（Upcoming） | 描边圆，`1px solid #4A6491`，背景 `transparent` | 步骤数字，`#6E88B0` | ZS-004-05 / ZS-004-04 |
+| 失效（Disabled） | 描边圆，`1px solid #2D4473`，背景 `transparent` | 步骤数字，`#4A6491` | ZS-004-06 / ZS-004-05 |
+
+**指示圆规格**：
+
+| 属性 | 取值 |
+|------|------|
+| 直径 | `24px` |
+| 圆内字号 | `12px Bold`（D-DIN 或 Noto Sans Bold） |
+| 对勾图标 | `12px`，居中 |
+| 字体水平居中 | 数字 / 对勾 在圆几何中心 |
+
+**标题与描述文字**：
+
+| 元素 | 状态 | 字号 / 颜色 | 来源 |
+|------|------|-------------|------|
+| 标题 | 已完成 / 当前 | `14px Medium`，`#FFFFFF` | — |
+| 标题 | 未开始 | `14px Medium`，`#6E88B0` | ZS-004-04 |
+| 标题 | 失效 | `14px Medium`，`#4A6491` | ZS-004-05 |
+| 描述 | 已完成 / 当前 | `12px Regular`，`#C5CFE0` | ZS-004-02 |
+| 描述 | 未开始 / 失效 | `12px Regular`，`#6E88B0` → `#4A6491` | ZS-004-04 → ZS-004-05 |
+
+**连接线（步骤之间）**：
+
+| 类型 | 色值 | 来源 | 样式 |
+|------|------|------|------|
+| 已完成段（前一节点已完成） | `#1677FF` | ZS-002-06 | `1px dashed`（弹窗）/ `1px solid`（页面） |
+| 未完成段 | `#4A6491` | ZS-004-05 | `1px dashed` |
+
+> 连接线在指示圆**两侧水平居中**（横向）或**正下方垂直**（纵向）；线两端与圆外缘留 `--spacing-1` (4px) 间隙，避免线穿圆。
+
+### 10.2 弹窗步骤条（横向 · 描边圆为主）
+
+用于 Modal / Drawer 内引导多步操作的紧凑步骤条。指示圆**完成态用描边 + 对勾**而非实心，避免在弹窗背景上过于抢眼。
+
+#### 10.2.1 布局
+
+```
+( ✓ ) ┄┄┄┄┄ (●2) ┄┄┄┄┄ ( 3 ) ┄┄┄┄┄ ( 4 ) ┄┄┄┄┄ ( 5 )
+ 标题         标题         标题         标题         标题
+(描述)      (描述)       (描述)       (描述)       (描述)
+```
+
+#### 10.2.2 规格
+
+| 属性 | 取值 |
+|------|------|
+| 容器水平 padding | `--spacing-5` (24px) |
+| 指示圆 → 标题间距 | `--spacing-2` (8px) |
+| 标题 → 描述间距 | `--spacing-1` (4px) |
+| 节点之间水平间距 | 节点间距自适应等分；连接线占用中间空间 |
+| 连接线 | `1px dashed`，已完成段 `#1677FF`，未完成段 `#4A6491` |
+| 文字对齐 | 标题、描述居中对齐于指示圆下方 |
+
+#### 10.2.3 两种变体
+
+| 变体 | 适用 |
+|------|------|
+| **仅标题** | 步骤含义已经清晰（如「填写信息 / 确认 / 完成」），节省垂直空间 |
+| **标题 + 描述** | 步骤名抽象需要一行小字补充时使用 |
+
+### 10.3 页面步骤条（横向 · 实心圆 + 自定义首项标题）
+
+用于页面级流程（如「新建集群」类向导）。和弹窗步骤条相比，**已完成态指示圆改为实心填充 + 白色对勾**，视觉权重更高；首步标题可显示具体名称（如「新建集群」）而非「标题」占位。
+
+#### 10.3.1 布局
+
+```
+(✓) ────── (●2) ┄┄┄┄┄ ( 3 ) ┄┄┄┄┄ ( 4 ) ┄┄┄┄┄ ( 5 )
+新建集群     标题       标题       标题       标题
+(描述文本)  (描述文本) (描述文本) (描述文本) (描述文本)
+```
+
+#### 10.3.2 与 §10.2 弹窗步骤条的差异
+
+| 维度 | 弹窗步骤条 | 页面步骤条 |
+|------|-----------|-----------|
+| 完成态圆形 | 描边圆 + 蓝色对勾 | 实心蓝圆 + 白色对勾 |
+| 完成段连接线样式 | `1px dashed #1677FF` | `1px solid #1677FF` |
+| 标题文字号 | `14px Medium` | `14px Medium`（同） |
+| 第一项 | 通用「标题」占位 | 可显示具体名称（自定义文案） |
+
+#### 10.3.3 完成态指示圆补充
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 已完成圆背景 | `#1677FF` | ZS-002-06 |
+| 已完成圆内对勾 | `#FFFFFF` | — |
+| 已完成圆边框 | 无（实心） | — |
+
+### 10.4 纵向步骤条
+
+用于侧栏 / 详情页内的纵向流程指引。两种变体——「仅标题」与「标题 + 描述」。
+
+#### 10.4.1 布局
+
+```
+仅标题:                       标题 + 描述:
+
+(✓) 新建集群                   (✓) 新建集群
+ ┊                                  描述文本描述
+(●2) 标题                      ┊
+ ┊                             (●2) 标题
+( 3 ) 标题                          描述文本描述
+ ┊                             ┊
+( 4 ) 标题                     ( 3 ) 标题
+                                    描述文本描述
+                               ┊
+                               ( 4 ) 标题
+                                    描述文本描述
+```
+
+#### 10.4.2 规格
+
+| 属性 | 取值 |
+|------|------|
+| 指示圆 → 标题水平间距 | `--spacing-2` (8px) |
+| 节点垂直间距（仅标题） | `--spacing-5` (24px)，圆心到圆心 |
+| 节点垂直间距（标题 + 描述） | `--spacing-6` (32px)，圆心到圆心 |
+| 标题 → 描述间距 | `--spacing-1` (4px) |
+| 连接线位置 | 上下两个指示圆**正下方垂直**，居中于圆心 |
+| 连接线样式 | `1px dashed`，已完成段 `#1677FF`，未完成段 `#4A6491` |
+| 文字左对齐 | 标题与描述左对齐，与指示圆右侧对齐基线 |
+
+#### 10.4.3 与横向步骤条共用规则
+
+- 指示圆三态规格沿用 §10.1
+- 已完成态默认用**描边 + 对勾**（与 §10.2 弹窗一致）；若纵向步骤条用于页面级主流程，可切换为 §10.3 的实心圆变体
+
+### 10.5 交互与动画
+
+| 行为 | 动效 |
+|------|------|
+| 步骤切换（next） | 当前圆 `background: transparent → #1677FF`，`200ms ease-out`；同时上一步圆 `border-color: #4A6491 → #1677FF`，再用 `200ms` 切换为对勾图标淡入 |
+| 步骤切换（prev / 回退） | 反向，未完成态恢复 `#4A6491` 边框，圆内数字淡入 |
+| 连接线高亮 | 完成段 `border-color: #4A6491 → #1677FF`，`240ms ease-out` |
+| Hover 节点（可点击） | 圆边框色暂时变 `#4096FF` (ZS-002-05)，标题文字 `#4096FF`，`120ms ease-out`；不可点击节点（未来步骤）无 hover |
+| 点击节点 | 节点必须**已完成**才能点（回看），否则视为禁用；点击合法节点触发 `step:change` 事件 |
+
+### 10.6 状态机与可达性
+
+| 当前步 = N | 节点 i 的状态 |
+|-----------|----------------|
+| `i < N` | Completed（已完成，可点回看） |
+| `i === N` | Current（当前，不可点） |
+| `i > N` | Upcoming（未开始，不可点） |
+| `i.disabled` | Disabled（被显式禁用，例如条件未满足） |
+
+**键盘导航**：
+- `Tab` 顺序在「已完成」节点之间流转，跳过 `Current / Upcoming / Disabled`
+- 焦点节点圆外加 `2px solid #4096FF` 焦点环（`outline`，`offset 2px`）
+
+**屏幕阅读器**：
+- 指示圆 `role="img"`，`aria-label="已完成第 N 步"` / `"当前第 N 步"` / `"未开始第 N 步"`
+- 容器 `role="list"`，节点 `role="listitem"`
+- 当前节点额外 `aria-current="step"`
+
+### 10.7 CSS Token 参考
+
+```css
+:root {
+  /* 步骤条节点 */
+  --step-circle-size: 24px;
+  --step-circle-current-bg: #1677FF;       /* ZS-002-06 */
+  --step-circle-current-text: #FFFFFF;
+  --step-circle-done-border: #1677FF;      /* ZS-002-06 */
+  --step-circle-done-icon: #1677FF;        /* 弹窗变体 */
+  --step-circle-done-bg-page: #1677FF;     /* 页面变体:实心 */
+  --step-circle-done-icon-page: #FFFFFF;
+  --step-circle-upcoming-border: #4A6491;  /* ZS-004-05 */
+  --step-circle-upcoming-text: #6E88B0;    /* ZS-004-04 */
+  --step-circle-disabled-border: #2D4473;  /* ZS-004-06 */
+  --step-circle-disabled-text: #4A6491;    /* ZS-004-05 */
+
+  /* 连接线 */
+  --step-line-done: #1677FF;               /* 已完成段 */
+  --step-line-upcoming: #4A6491;           /* 未完成段:ZS-004-05 */
+
+  /* 文字 */
+  --step-title-active: #FFFFFF;
+  --step-title-inactive: #6E88B0;          /* ZS-004-04 */
+  --step-desc-active: #C5CFE0;             /* ZS-004-02 */
+  --step-desc-inactive: #6E88B0;           /* ZS-004-04 */
+}
+```
+
+### 10.8 三种步骤条的选用决策
+
+| 场景 | 选择 |
+|------|------|
+| Modal / Drawer 内多步表单 | §10.2 弹窗步骤条（描边圆，紧凑） |
+| 页面级向导（独占大区域） | §10.3 页面步骤条（实心圆，视觉重） |
+| 侧栏 / 详情页纵向流程 | §10.4 纵向步骤条 |
+| 步骤数 ≤ 3 且无描述 | 优先「仅标题」变体 |
+| 步骤名抽象需补充说明 | 用「标题 + 描述」变体 |
+| 步骤数 > 7 | 不推荐用步骤条，改用「锚点」（§9.2）或分页 |
+
+---
+
+## 11. 面包屑
+
+> 对应「4.3 导航组件-面包屑」。用于显示当前位置在整个站点层级中的路径，配合「← 返回」按钮支持逐级回溯。颜色取自 ZS-002 主色蓝与 ZS-004 深蓝系。
+
+### 11.1 标准形态
+
+容器顶部带一个独立的容器 / 边框包裹：
+
+```
+🏠 | 概况 / 总概况
+```
+
+带「返回」按钮的层级形态（一级到四级）：
+
+```
+一级:   ← 返回 │ 现在位置
+二级:   ← 返回 │ 上一级位置 / 现在位置
+三级:   ← 返回 │ 上二级位置 / 上一级位置 / 现在位置
+四级:   ← 返回 │ 上三级位置 / 上二级位置 / 上一级位置 / 现在位置
+```
+
+### 11.2 规格
+
+| 属性 | 取值 |
+|------|------|
+| 容器高度 | `40px` |
+| 容器背景 | `#0C1836` (ZS-004-09) |
+| 容器底边 | `1px solid #1A2F5A` (ZS-004-07) |
+| 容器水平 padding | `--spacing-4` (16px) |
+| 字号 | `14px Regular` |
+| 元素间距（图标 / 文字 / 分隔符之间） | `--spacing-2` (8px) |
+| 「返回」与首段路径之间分隔符 `│` | `1px solid #4A6491`，高度 `14px` |
+
+### 11.3 配色
+
+| 角色 | 色值 | 来源 | 备注 |
+|------|------|------|------|
+| Home 图标 🏠 | `#4096FF` | ZS-002-05 | 默认主色，hover → `#1677FF` (ZS-002-06) |
+| 「← 返回」图标 + 文字 | `#4096FF` | ZS-002-05 | 链接样式，hover 显示下划线 |
+| 历史路径文字（可点击） | `#4096FF` | ZS-002-05 | 同链接配色 |
+| 当前位置文字（最后一段） | `#FFFFFF` | — | 加粗 `14px Medium`，不可点击 |
+| 分隔符 `/` | `#4A6491` | ZS-004-05 | 静态、不可点 |
+| 分隔符 `│`（返回按钮与路径之间） | `#4A6491` | ZS-004-05 | 同上 |
+| Hover 路径项 | `#1677FF` | ZS-002-06 | 文字色 + 下划线 |
+| 失效路径项（无对应页） | `#4A6491` | ZS-004-05 | `cursor: not-allowed` |
+
+### 11.4 交互规则
+
+- **点击「← 返回」**：逐步向上返回一级（等同浏览器 back）
+- **点击文字路径**：快速跳回到对应任意上级页面
+- **当前位置**（最后一段）：不响应点击，仅作展示
+- **层级建议**：尽可能不超过 **4 级**；超过 4 级会让面包屑过长，应改用侧栏 / 锚点辅助
+
+### 11.5 与导航的关系
+
+面包屑**不替代**主导航（§8）：
+
+- 主导航 = 「我能去哪些地方」（站点结构）
+- 面包屑 = 「我当前在哪里」（路径回溯）
+
+两者并存时，面包屑紧贴页面主内容区顶部，位于主导航下方、页头（§12）上方。
+
+### 11.6 CSS 参考
+
+```css
+.breadcrumb {
+  display: flex;
+  align-items: center;
+  height: 40px;
+  padding: 0 var(--spacing-4);
+  background: #0C1836;
+  border-bottom: 1px solid #1A2F5A;
+  font-size: 14px;
+  gap: var(--spacing-2);
+}
+.breadcrumb-back     { color: #4096FF; cursor: pointer; }
+.breadcrumb-back:hover { color: #1677FF; text-decoration: underline; }
+.breadcrumb-sep-bar  { width: 1px; height: 14px; background: #4A6491; }
+.breadcrumb-sep      { color: #4A6491; }
+.breadcrumb-link     { color: #4096FF; cursor: pointer; }
+.breadcrumb-link:hover { color: #1677FF; text-decoration: underline; }
+.breadcrumb-current  { color: #FFFFFF; font-weight: 500; }
+```
+
+---
+
+## 12. 页头
+
+> 对应「4.6 导航组件-分页」上半段示意。用于页面主内容区顶部、面包屑下方，承载页面标题与可选的说明 / Tabs。共有 4 种变体。
+
+### 12.1 通用规格
+
+| 属性 | 取值 |
+|------|------|
+| 容器高度 | `56px`（仅标题）/ `64px`（含 Tabs） |
+| 背景 | `#0C1836` (ZS-004-09) |
+| 底边 | `1px solid #1A2F5A` (ZS-004-07) |
+| 水平 padding | `--spacing-5` (24px) |
+| 文字基线 | 垂直居中 |
+
+### 12.2 四种变体
+
+#### 12.2.1 基础页头
+
+只有标题：
+
+```
+页头标题
+```
+
+| 角色 | 色值 / 字号 | 来源 |
+|------|-------------|------|
+| 标题 | `18px Bold`，`#FFFFFF` | — |
+
+#### 12.2.2 页头 + 说明
+
+标题后跟一段灰色说明文字：
+
+```
+页头标题  （这是一句简要说明）
+```
+
+| 角色 | 色值 / 字号 | 来源 |
+|------|-------------|------|
+| 标题 | `18px Bold`，`#FFFFFF` | — |
+| 说明文字 | `14px Regular`，`#6E88B0` | ZS-004-04 |
+| 标题 → 说明间距 | `--spacing-3` (12px) | — |
+
+说明用半角圆括号包裹，颜色与括号一致（不要让括号比文字更醒目）。
+
+#### 12.2.3 页头 + 说明 icon
+
+标题后跟一个可悬停查看说明的图标：
+
+```
+页头标题  ⓘ
+```
+
+| 角色 | 色值 / 字号 | 来源 |
+|------|-------------|------|
+| 标题 | `18px Bold`，`#FFFFFF` | — |
+| 说明 icon `ⓘ` 或 `?` | `16px`，`#6E88B0` | ZS-004-04 |
+| Icon hover | `#4096FF` | ZS-002-05 |
+| 标题 → 图标间距 | `--spacing-2` (8px) | — |
+
+Hover 弹出 Tooltip（沿用 §9.3.3 Tooltip 配色），承载完整说明文字。
+
+#### 12.2.4 分 Tabs 页头
+
+标题位置直接放横向页签（沿用 §9.1.1 横向页签配色），点击切换右侧主内容区：
+
+```
+标题   标题   标题
+─────
+```
+
+| 复用规则 | 说明 |
+|----------|------|
+| Tab 配色 | 完全沿用 §9.1.1 横向页签 |
+| Tab 字号 | `16px Medium`（页头位置比一般 tab 略大） |
+| Tab 间距 | `--spacing-5` (24px) |
+| 激活态下划线 | `2px solid #4096FF`，宽与文字齐 |
+
+### 12.3 与右侧操作区的组合
+
+页头右侧常承载主操作按钮（「+ 新建」、「导出」等）。规则：
+
+- 按钮组靠右对齐，右 padding 与左 padding 一致 (`--spacing-5`)
+- 多按钮排列顺序参照 §5.3.4（默认按钮在左、主按钮在右），按钮间距 `--spacing-2`
+- Tabs 页头中右侧操作区与 Tabs 同高居中
+
+---
+
+## 13. 分页
+
+> 对应「4.6 导航组件-分页」下半段。三种形态——**正常分页 / 精简分页 / 导航式分页**——按页面信息量与可用空间选用。
+
+### 13.1 正常分页
+
+承载大列表，提供页码、跳转、每页条数选择：
+
+```
+共 240 项   < ① 2 3 4 5 … 24 >   每页 [10▾] 条   前往 [   ] 页
+```
+
+#### 13.1.1 元素配色与规格
+
+| 元素 | 字号 / 色值 | 来源 / 说明 |
+|------|-------------|-------------|
+| 「共 N 项」总数文字 | `14px Regular`，`#6E88B0` | ZS-004-04 |
+| 页码按钮（默认） | `14px Regular`，`#C5CFE0`，背景 `transparent` | ZS-004-02 |
+| 页码按钮（hover） | `#4096FF`，背景 `rgba(22,119,255,0.08)` | ZS-002-05 |
+| 页码按钮（激活/当前页） | `#FFFFFF`，背景 `#1677FF`（实心圆） | ZS-002-06 |
+| 页码按钮（失效） | `#4A6491`，背景 `transparent` | ZS-004-05 |
+| 左右翻页箭头 `<` `>` | `14px`，`#6E88B0`，hover → `#4096FF` | ZS-004-04 → ZS-002-05 |
+| 翻页箭头失效（首/末页） | `#4A6491` | ZS-004-05 |
+| 省略号 `…` | `#6E88B0` | ZS-004-04，静态展示，不可点 |
+| 每页条数下拉 `[10▾]` | 沿用 §14.1 输入框规格 | 高度 `28px`，宽 `60px` |
+| 「前往 N 页」输入框 | 沿用 §14.1 输入框规格 | 高度 `28px`，宽 `48px` |
+
+#### 13.1.2 页码按钮规格
+
+| 属性 | 取值 |
+|------|------|
+| 形状 | 圆形 `28px × 28px`（`border-radius: 50%`） |
+| 默认背景 | `transparent` |
+| 当前页背景 | `#1677FF` (ZS-002-06)，实心圆，白色数字 |
+| 字号 | `14px Regular`（数字 D-DIN 或 Noto Sans） |
+| 项间距 | `--spacing-1` (4px) |
+
+#### 13.1.3 元素间距
+
+| 区段 | 间距 |
+|------|------|
+| 「共 N 项」→ 翻页区 | `--spacing-4` (16px) |
+| 翻页区内（箭头 / 页码） | `--spacing-1` (4px) |
+| 翻页区 → 每页下拉 | `--spacing-5` (24px) |
+| 每页下拉 → 前往输入 | `--spacing-4` (16px) |
+
+### 13.2 精简分页
+
+承载弹窗 / 表格紧凑场景，只暴露「当前页 / 总页数」与左右翻页：
+
+```
+共 1 项   < [ 1 ] / 10 >
+```
+
+#### 13.2.1 规格
+
+| 元素 | 配色 / 备注 |
+|------|------------|
+| 「共 N 项」 | 同 §13.1.1 |
+| `<` `>` 翻页箭头 | 同 §13.1.1 |
+| `[ 1 ]` 当前页输入框 | 沿用 §14.1 输入框规格，高 `28px`，宽 `40px`，居中文字 |
+| `/ N` 总页数 | `14px Regular`，`#6E88B0` (ZS-004-04) |
+| 元素间距 | `--spacing-2` (8px) |
+
+#### 13.2.2 与正常分页的差异
+
+| 维度 | 正常分页 | 精简分页 |
+|------|----------|----------|
+| 页码 | 点击式数字列表 | 输入框 + 总页数文字 |
+| 跳转方式 | 点击数字 / 前往输入 | 直接修改输入框 |
+| 每页条数 | 暴露下拉 | 不暴露（默认值由调用方决定） |
+| 适用 | 列表 / 表格主内容区 | 弹窗、抽屉、卡片内嵌列表 |
+
+### 13.3 导航式分页
+
+承载长文 / 详情页的「上一篇 / 下一篇」式翻页，只有方向，不暴露页码：
+
+```
+下一页  »
+«   上一页
+```
+
+#### 13.3.1 规格
+
+| 元素 | 配色 / 备注 |
+|------|------------|
+| 「下一页」/「上一页」文字 + 箭头 | `14px Regular`，`#4096FF` (ZS-002-05) |
+| Hover | `#1677FF` (ZS-002-06) + 下划线 |
+| 失效（首/末篇） | `#4A6491` (ZS-004-05)，`cursor: not-allowed` |
+| 箭头位置 | `下一页 »`（箭头在后）/ `« 上一页`（箭头在前） |
+| 文字 → 箭头间距 | `--spacing-2` (8px) |
+| 两个按钮纵向排列时项间距 | `--spacing-3` (12px) |
+
+### 13.4 三种分页的选用决策
+
+| 场景 | 选择 |
+|------|------|
+| 后台列表 / 表格 | §13.1 正常分页 |
+| Modal / Drawer 内嵌列表 | §13.2 精简分页 |
+| 详情页前后翻 | §13.3 导航式分页 |
+| 列表少于 1 页（项数 ≤ pageSize） | **不显示**分页 |
+| 项数明确但页码可能很多（>50 页） | 用正常分页 + 隐藏中间页码（`...` 省略） |
+
+---
+

frontend-web/docs/ui规范-深蓝/04-图表.md

@@ -0,0 +1,573 @@
+# 深蓝色 UI 规范 · 04 图表（§35–§41）
+
+> 《深蓝色 UI 规范》分册之一。基础令牌见 `00-基础-色彩字体间距.md`，可 import 的变量见 `tokens.css`，总目录与 §索引见 `README.md`。`§N` 编号全局唯一。
+
+**本篇目录**：`35` 图表通用规范 · `36` 柱状图 · `37` 折线图 · `38` 甘特图 · `39` 环形图 · `40` 关系图/散点图 · `41` 图表色值
+
+---
+
+## 35. 图表通用规范（Chart 基础）
+
+> 对应设计稿「8. 图表」系列（柱状图 / 折线图 / 甘特图）。本节先约定**所有图表共用**的容器、标题、坐标轴、网格、图例、Tooltip、配色与空状态；§36 起按图表类型补充各自细则。配色一律取自 §1.1.8 图表配色与 §1.1.5 深蓝系，不另造色。
+
+### 35.1 图表容器
+
+| 属性 | 取值 | 来源 |
+|------|------|------|
+| 背景 | `#0C1836` (ZS-004-09)，嵌入卡片时随 §22 卡片 `#122347` | §3.1 |
+| 圆角 | `4px` | §4.1 |
+| 内边距 | `--spacing-5` (24px) | §7.1 |
+| 多图并排间距 | `--spacing-6` (32px) | §7.1 |
+| 边框（可选） | `1px solid #1A2F5A` (ZS-004-07) | — |
+
+### 35.2 图表标题
+
+设计稿中标题统一为「**主色蓝竖条 ▌ + 文字**」的小标题样式。
+
+| 元素 | 规格 | 来源 |
+|------|------|------|
+| 左侧竖条 | `3px × 14px`，`#1677FF` (ZS-002-06)，圆角 `1px` | §1.1.6 |
+| 竖条 → 文字间距 | `--spacing-2` (8px) | §7.1 |
+| 标题文字 | `16px Bold`，`#FFFFFF`（或 `#C5CFE0`） | §2.1.2 |
+| 标题 → 图表区间距 | `--spacing-4` (16px) | §7.1 |
+| 副标题 / 单位 | `12px Regular`，`#6E88B0` (ZS-004-04) | — |
+
+> 部分卡片标题不带竖条（如「标题（BW）」「数据采集XXX」），此时直接用 `16px Bold #C5CFE0`，与 §22 卡片标题一致。
+
+### 35.3 坐标轴
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 轴线（X / Y 基线） | `1px solid #2D4473` (ZS-004-06) | §6.1 |
+| 刻度文字（轴标签） | `12px Regular`，`#6E88B0` (ZS-004-04) | — |
+| 轴标题 / 类目名（如「类型」「2012」） | `12px Regular`，`#4096FF` (ZS-002-05) 或 `#6E88B0` | — |
+| 刻度线（tick） | 通常隐藏，仅留网格线 | — |
+| 轴名称单位 | `12px`，`#6E88B0`，置于轴末端 | — |
+
+### 35.4 网格线（splitLine）
+
+| 类型 | 色值 | 样式 | 使用场景 |
+|------|------|------|----------|
+| 主网格（默认） | `#2D4473` (ZS-004-06) | `1px dashed` | 柱状 / 折线的 Y 向参考线 |
+| 弱化网格 | `#1A2F5A` (ZS-004-07) | `1px dashed` | 密集图表、次要参考 |
+
+> 深色背景下网格一律用**虚线**且低对比，避免抢戏；纵向类目方向通常不画网格。
+
+### 35.5 图例（Legend）
+
+| 属性 | 取值 | 来源 |
+|------|------|------|
+| 位置 | 右上角（多数）或顶部居中 | — |
+| 色块（marker） | `10px` 方块 / 圆点，取系列色 | §1.1.8 |
+| 色块 → 文字间距 | `--spacing-1` (4px) | §7.1 |
+| 图例文字 | `12px Regular`，`#C5CFE0` (ZS-004-02) | — |
+| 项间距 | `--spacing-3` (12px) | §7.1 |
+| 未选中态（点击隐藏系列） | 色块 + 文字置灰 `#4A6491` (ZS-004-05) | §1.1.5 |
+
+### 35.6 Tooltip（悬浮提示）
+
+鼠标悬停时跟随的浮层（如折线图「1月10日 异常率12.9%」、「5.32」）。
+
+| 属性 | 取值 | 来源 |
+|------|------|------|
+| 背景 | `rgba(12,24,54,0.92)`（ZS-004-09 92%） | §3.1 |
+| 边框 | `1px solid #1A2F5A` (ZS-004-07) | — |
+| 圆角 | `4px` | §4.1 |
+| 阴影 | `0 4px 16px rgba(6,14,36,0.6)` | §3.1.4 |
+| 内边距 | 上下 `--spacing-2`，左右 `--spacing-3` | §7.1 |
+| 标题行（日期 / 类目） | `12px Medium`，`#FFFFFF` | — |
+| 数值行 | `12px Regular`，色块（系列色）+ 名称 `#6E88B0` + 数值 `#C5CFE0` | — |
+| 指示线（axisPointer） | `1px dashed #4096FF` (ZS-002-05)，或半透明竖向高亮带 `rgba(22,119,255,0.12)` | §6.1 |
+
+> 设计稿中数据点 hover 常显示一个**实心小标签**（如圆点 + 数值 `5.32`）：标签背景 `#122347`，文字 `#FFFFFF`，圆点取系列色，圆角 `2px`。
+
+### 35.7 数据点与标记
+
+| 元素 | 规格 | 来源 |
+|------|------|------|
+| 折线拐点（默认） | 不显示或 `2px` 实心点 | — |
+| 折线拐点（hover / 强调） | `空心圆`，描边 `2px` 系列色，填充 `#0C1836`，直径 `6px` | — |
+| 高亮竖带（选中区间） | `rgba(22,119,255,0.12)` 矩形，无边框 | §3.1 |
+
+### 35.8 图表配色引用
+
+| 用途 | 色序 | 来源 |
+|------|------|------|
+| 多系列（面积大：柱 / 折线 / 饼） | `#1677FF → #13C2C2 → #4096FF → #36CFC9 → #69B1FF → #5CDBD3 → #91CAFF → #87E8DE` | §1.1.8 通用图表色序 |
+| 小面积（散点 / 迷你图 / 徽标） | `#4096FF → #36CFC9 → #FF4D4F → #FFA39E → #6388FF → #478880` | §1.1.8 小面积色序 |
+| 语义系列（成功 / 警告 / 错误） | 绿 `--func-success` / 橙 `--func-warning` / 红 `#F5222D` | §27.4 / §1.1.2 |
+
+> 设计稿柱状图出现的「绿(Paper) / 橙(Project) / 蓝(Book)」三系列，对应**语义化分类**：绿取 §27.4 成功绿、橙取 §27.4 警告橙、蓝取主色 `#1677FF`；若为无语义的并列分类，应改用通用图表色序避免误读。
+
+### 35.9 空状态 / 加载
+
+| 状态 | 表现 |
+|------|------|
+| 加载中 | 图表区居中显示旋转图标 `#4096FF` + 文字「加载中…」`12px #6E88B0`（沿用 §5.4.2） |
+| 无数据 | 居中占位插画 / 文字「暂无数据」`14px #6E88B0` |
+
+---
+
+## 36. 柱状图（Column / Bar）
+
+> 对应设计稿「8.1 图表-柱状图」。涵盖**堆叠柱 / 分组柱 / 条形图（横向）/ 排行进度条**四种形态。容器、坐标轴、网格、图例、Tooltip 全部沿用 §35。
+
+### 36.1 通用规格
+
+| 属性 | 取值 | 来源 |
+|------|------|------|
+| 柱体圆角 | 顶部 `2px`（堆叠柱仅最顶段圆角） | §4.1 |
+| 柱宽 | 类目宽度的 `40%~60%` |  — |
+| 同组柱间距 | `--spacing-1` (4px) | §7.1 |
+| 类目（组）间距 | 自适应等分 | — |
+| 数值标签（可选） | `12px Regular`，`#C5CFE0`，置柱顶上方 `--spacing-1` | — |
+
+### 36.2 堆叠柱状图（如「标题」Paper/Project/Book）
+
+| 元素 | 配色 | 来源 |
+|------|------|------|
+| 系列 1（Book / 底段） | `#69B1FF` (ZS-002-04) 或主色 `#1677FF` | §1.1.3 |
+| 系列 2（Project / 中段） | `--func-warning`（橙） | §27.4 |
+| 系列 3（Paper / 顶段） | `--func-success`（绿） | §27.4 |
+| 段间分隔 | `1px` 容器底色 `#0C1836` 描边，制造堆叠缝隙 | — |
+| Y 轴类目标签「类型」 | `12px`，`#4096FF` (ZS-002-05) | §35.3 |
+
+### 36.3 分组柱状图（如「标题（BW）」「标题」双系列）
+
+| 元素 | 配色 | 来源 |
+|------|------|------|
+| 系列依次取色 | 通用图表色序 `#1677FF / #13C2C2 / #4096FF …` | §1.1.8 |
+| 设计稿 BW 三色变体 | 蓝 `#69B1FF` / 绿 `--func-success` / 橙 `--func-warning` | §35.8 |
+| 双系列变体 | 蓝 `#69B1FF`(ZS-002-04) + 橙 `--func-warning` | — |
+
+### 36.4 条形图（横向，如「标题」x 轴 0–400）
+
+| 属性 | 取值 | 来源 |
+|------|------|------|
+| 方向 | 水平，类目在 Y 轴、数值在 X 轴 | — |
+| 条体颜色 | `#69B1FF` (ZS-002-04)（单系列）或图表色序 | §1.1.3 |
+| 条体圆角 | 右端 `2px` | §4.1 |
+| 类目标签「类型」 | 左对齐，`12px #6E88B0` | §35.3 |
+| X 轴刻度 | `0 / 100 / 200 / 300 / 400`，`12px #6E88B0` | §35.3 |
+
+### 36.5 排行进度条（如「数据采集XXX」TOP1–5）
+
+横向「标签 + 渐变进度条 + 数值」的榜单形态。
+
+```
+TOP1  项目任务名称一                          15,465
+■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■▓▓▓▓▓▓▓▓
+TOP2  项目任务名称二                          15,234
+■■■■■■■■■■■■■■■■■■■■■■■■■▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
+```
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 排名 + 名称（TOPn 项目任务名称） | `14px Regular`，`#C5CFE0` (ZS-004-02) | — |
+| 数值（右对齐） | `16px D-DIN Regular`，`#FFFFFF` | §2.1.2 |
+| 进度条高度 | `8px`，圆角 `4px` | §4.1 |
+| 进度填充 | 渐变 `linear-gradient(90deg, #1677FF 0%, #13C2C2 100%)`（主色蓝→主色青） | §1.1.8 |
+| 进度轨道（底槽） | `#1A2F5A` (ZS-004-07) | §1.1.5 |
+| 行间距 | `--spacing-4` (16px) | §7.1 |
+| 名称行 → 进度条间距 | `--spacing-2` (8px) | §7.1 |
+
+### 36.6 交互
+
+| 行为 | 动效 |
+|------|------|
+| 入场 | 柱体由 `0` 向目标高度 / 长度增长，`scaleY/scaleX 0→1`，`400ms ease-out`，按系列依次 `60ms` 错峰 |
+| Hover 柱 | 该柱亮度 `+8%`，弹出 §35.6 Tooltip，axisPointer 高亮该类目竖带 | 
+| Hover 进度条 | 数值放大或显示绝对值 Tooltip | 
+
+---
+
+## 37. 折线图（Line / Area）
+
+> 对应设计稿「8.2 图表-折线图」与「8.3 多系列折线」。涵盖**迷你面积图 / 单线（含异常点 Tooltip）/ 长时序面积图（带缩略轴）/ 多系列折线**。容器、轴、网格、图例、Tooltip 沿用 §35。
+
+### 37.1 线条与面积
+
+| 元素 | 规格 | 来源 |
+|------|------|------|
+| 线宽 | `2px` | — |
+| 线条颜色 | 取图表色序，单线默认 `#1677FF` (ZS-002-06) | §1.1.8 |
+| 平滑 | `smooth`（曲线）或折线，按数据性质选用 | — |
+| 面积填充（单线） | 自顶向下渐变 `rgba(22,119,255,0.32) → rgba(22,119,255,0)` | §3.1 |
+| 拐点 | 默认隐藏，hover 显示空心圆（§35.7） | — |
+
+### 37.2 迷你面积图（如左上「图表标题」+ 已选/未选 标签）
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 顶部切换标签（已选 / 未选） | §29 标签：选中 `#1677FF` 实心白字 / 未选 `transparent` + `1px #6E88B0` 边、`#6E88B0` 字 | §29 |
+| 线条 | `2px #4096FF` (ZS-002-05) | — |
+| 面积渐变 | `rgba(64,150,255,0.32) → 0` | — |
+| 当前值标签（如 `59.32`） | 实心小牌 `#122347` 背景 / `#FFFFFF` 文字，圆角 `2px`，定位于末端点 | §35.6 |
+| 轴标签（日期） | `12px #6E88B0` | §35.3 |
+
+### 37.3 单线异常点图（如中部「5-1…5-12」+「1月10日 异常率12.9%」）
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 主线 | `2px #1677FF` | — |
+| 面积渐变 | `rgba(22,119,255,0.32) → 0` | — |
+| 选中竖带 | `rgba(22,119,255,0.12)` 矩形高亮当前 X 区间 | §35.7 |
+| 异常点标记 | 空心圆 `6px`，描边 `#FAAD14`（警告橙），填充 `#0C1836` | §27.4 |
+| Tooltip（日期 + 指标） | §35.6；指标行如「异常率 12.9%」用 `--func-warning` 橙强调 | §35.6 |
+| Y 轴（0–2500） | `12px #6E88B0`，虚线网格 `#2D4473` | §35.3 / §35.4 |
+
+### 37.4 长时序面积图 + 缩略轴（如底部「图表标题」1986–2024）
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 主线 | `2px #36CFC9`（标准青）或 `#4096FF` | §1.1.4 |
+| 面积渐变 | `rgba(54,207,201,0.24) → 0` | — |
+| 数据点标签（如 `2.43`） | 实心小牌（§35.6），定位于选中点上方 | — |
+| 缩略轴（dataZoom，右下迷你图） | 缩略折线 `#4A6491`；滑窗手柄 `#1677FF`，选中区 `rgba(22,119,255,0.16)` | §1.1.5 / §1.1.6 |
+| X 轴年份 | `12px #6E88B0`，密集时隔项显示 | §35.3 |
+
+### 37.5 多系列折线图（如「图表标题」XXX/XXX/都是/无反应）
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 图例（顶部居中） | 方块 marker + 文字，项间距 `--spacing-3` | §35.5 |
+| 系列 1（XXX） | 红 `#FF4D4F` (ZS-001-05) | §1.1.2 |
+| 系列 2（XXX） | 蓝 `#1677FF` (ZS-002-06) | §1.1.3 |
+| 系列 3（都是） | 橙 `--func-warning` | §27.4 |
+| 系列 4（无反应） | 绿 `--func-success` 或青 `#36CFC9` | §27.4 / §1.1.4 |
+| 线宽 | `2px`，多系列**不填充面积**（避免互相遮挡） | — |
+| 拐点 | 全程显示 `4px` 空心圆（描边系列色，填充 `#0C1836`） | §35.7 |
+| 选中竖带 + Tooltip | hover 竖带 `rgba(22,119,255,0.12)`，Tooltip 列出各系列值（如 `5.32`） | §35.6 |
+| Y 轴（0–10） / X 轴（年份） | `12px #6E88B0`，横向虚线网格 `#2D4473` | §35.3 / §35.4 |
+
+### 37.6 交互
+
+| 行为 | 动效 |
+|------|------|
+| 入场 | 线条沿路径绘制 `stroke-dashoffset` 动画，`600ms ease-out`；面积同步淡入 |
+| Hover | 显示 §35.6 Tooltip + 竖向 axisPointer 高亮带；对应拐点放大为空心圆 |
+| 图例点击 | 切换系列显隐，隐藏态图例置灰 `#4A6491`（§35.5） |
+| 缩略轴拖拽 | 主图 X 轴范围实时联动，`100ms` 节流 |
+
+---
+
+## 38. 甘特图（Gantt）
+
+> 对应设计稿「甘特图」。以时间为横轴、任务行为纵轴的进度条排期图。深蓝背景上以**交替行底纹 + 渐变任务条 + 箭头收尾**呈现，配色取 §1.1.8 图表色序与语义色。
+
+### 38.1 结构
+
+```
+        1  2  3 … 15 16 17 …            31     ← 时间刻度表头
+ Jan  ▐▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▶                      ← 任务条（带箭头收尾）
+ Feb         ▐▓▓▓▓▓▓▓▓▓▶
+ Mar      ▐▓▓▓▓▓▓▓▶
+ …
+ Dec               ▐▓▓▓▓▓▓▓▓▓▓▓▶
+ ● Lorem ipsum 1   ● Lorem ipsum 2   …          ← 底部图例
+```
+
+### 38.2 表格框架
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 容器背景 | `#0C1836` (ZS-004-09) | §35.1 |
+| 时间刻度表头（1–31 / 月） | `12px Regular`，`#C5CFE0` (ZS-004-02) | §35.3 |
+| 行标签（Jan…Dec） | `14px Regular`，`#C5CFE0` | — |
+| 行高 | `28px`，行间距 `--spacing-1` (4px) | §7.1 |
+| 行底纹（轨道） | `#122347` (ZS-004-08)，整行通栏，圆角 `2px` | §1.1.5 |
+| 行底纹（隔行可选） | 奇偶交替 `#122347` / `#0F1C3D` | — |
+| 列分隔（可选） | `1px dashed #1A2F5A` (ZS-004-07) | §6.2 |
+
+### 38.3 任务条
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 条高 | `16px`，垂直居中于行内 | — |
+| 圆角 | `2px`（左端）；右端收**箭头**三角表示方向 | §4.1 |
+| 填充 | 沿条向右渐变（系列色 `0%` → 同色 70% 透明 `100%`），叠加斜纹/点纹理增强层次 | §1.1.8 |
+| 纹理 | `repeating-linear-gradient(45deg, rgba(255,255,255,0.06) 0 4px, transparent 4px 8px)` | — |
+| 箭头收尾 | 与条同色实心三角，`6px`，指向时间推进方向 | — |
+| 进度（可选） | 条内再叠一段高饱和系列色表示完成比例 | — |
+
+### 38.4 任务分类配色（对应底部图例 Lorem ipsum 1–5）
+
+| 图例 | 圆点 / 任务条主色 | 来源 |
+|------|------------------|------|
+| Lorem ipsum 1 | 橙 `--func-warning` | §27.4 |
+| Lorem ipsum 2 | 红 `#FF4D4F` (ZS-001-05) | §1.1.2 |
+| Lorem ipsum 3 | 青绿 `#36CFC9` (ZS-003-05) | §1.1.4 |
+| Lorem ipsum 4 | 浅蓝 `#91CAFF` (ZS-002-03) | §1.1.3 |
+| Lorem ipsum 5 | 主色蓝 `#1677FF` (ZS-002-06) | §1.1.3 |
+
+### 38.5 图例与表头
+
+| 元素 | 规格 | 来源 |
+|------|------|------|
+| 底部图例圆点 | `10px` 圆形，取 §38.4 分类色 | §35.5 |
+| 图例文字 | `14px Regular`，`#C5CFE0` | — |
+| 图例项间距 | `--spacing-5` (24px) | §7.1 |
+| 表头 → 首行间距 | `--spacing-3` (12px) | §7.1 |
+
+### 38.6 交互
+
+| 行为 | 动效 |
+|------|------|
+| 入场 | 任务条由左端起点向右展开 `scaleX 0→1`（`transform-origin:left`），`400ms ease-out`，按行错峰 `60ms` |
+| Hover 任务条 | 整条亮度 `+8%`，弹出 §35.6 Tooltip（任务名 / 起止日期 / 进度） |
+| Hover 行 | 行底纹由 `#122347` → `#1A2F5A` (ZS-004-07) | 
+| 今日线（可选） | 一条 `1px dashed #4096FF` (ZS-002-05) 竖线标注当前日期 | §6.2 |
+
+### 38.7 CSS Token 参考（§35–§38 共用）
+
+```css
+:root {
+  /* 图表容器与标题 */
+  --chart-bg:            #0C1836;   /* ZS-004-09 */
+  --chart-title-bar:     #1677FF;   /* ZS-002-06 标题竖条 */
+  --chart-title-text:    #FFFFFF;
+  --chart-subtitle:      #6E88B0;   /* ZS-004-04 */
+
+  /* 坐标轴与网格 */
+  --chart-axis-line:     #2D4473;   /* ZS-004-06 */
+  --chart-axis-label:    #6E88B0;   /* ZS-004-04 */
+  --chart-axis-cat:      #4096FF;   /* ZS-002-05 类目名 */
+  --chart-grid:          #2D4473;   /* ZS-004-06 虚线网格 */
+  --chart-grid-weak:     #1A2F5A;   /* ZS-004-07 */
+
+  /* 图例 / Tooltip */
+  --chart-legend-text:   #C5CFE0;   /* ZS-004-02 */
+  --chart-legend-off:    #4A6491;   /* ZS-004-05 未选中 */
+  --chart-tooltip-bg:    rgba(12,24,54,0.92);
+  --chart-tooltip-border:#1A2F5A;   /* ZS-004-07 */
+  --chart-tooltip-title: #FFFFFF;
+  --chart-tooltip-value: #C5CFE0;
+  --chart-axispointer:   #4096FF;   /* ZS-002-05 */
+  --chart-highlight-band:rgba(22,119,255,0.12);
+
+  /* 通用图表色序（面积大） */
+  --chart-c1: #1677FF;  --chart-c2: #13C2C2;  --chart-c3: #4096FF;  --chart-c4: #36CFC9;
+  --chart-c5: #69B1FF;  --chart-c6: #5CDBD3;  --chart-c7: #91CAFF;  --chart-c8: #87E8DE;
+
+  /* 小面积图表色序 */
+  --chart-s1: #4096FF;  --chart-s2: #36CFC9;  --chart-s3: #FF4D4F;
+  --chart-s4: #FFA39E;  --chart-s5: #6388FF;  --chart-s6: #478880;
+
+  /* 排行进度条（§36.5） */
+  --rank-bar-fill:   linear-gradient(90deg, #1677FF 0%, #13C2C2 100%);
+  --rank-bar-track:  #1A2F5A;       /* ZS-004-07 */
+  --rank-value:      #FFFFFF;
+
+  /* 甘特图（§38） */
+  --gantt-track:     #122347;       /* ZS-004-08 行底纹 */
+  --gantt-row-hover: #1A2F5A;       /* ZS-004-07 */
+  --gantt-c1: #FAAD14;  /* 警告橙 */
+  --gantt-c2: #FF4D4F;  /* ZS-001-05 */
+  --gantt-c3: #36CFC9;  /* ZS-003-05 */
+  --gantt-c4: #91CAFF;  /* ZS-002-03 */
+  --gantt-c5: #1677FF;  /* ZS-002-06 */
+  --gantt-today:     #4096FF;       /* ZS-002-05 今日线 */
+}
+```
+
+> 项目当前未引入图表库；若后续接入 ECharts，可将以上 token 注入主题（`backgroundColor` / `axisLine.lineStyle.color` / `splitLine.lineStyle` / `color[]` 色序 / `tooltip.backgroundColor` 等），保持与本规范一致。
+>
+> **关于多系列填充色**：§36–§38 表格中标注的系列色用于说明语义映射；**实际多系列图表的系列填充色一律以 §41 图表色值（设计稿 8.7）为准**——即淡色系 `#FA9196 / #FFCC80 / #97EBCD / #A2E1F9 / #80BCFF …`，按系列数量取对应色序。§1.1.8 的高彩度色序仅用于需要强对比的强调场景（如单色进度条渐变、KPI 高亮）。
+
+---
+
+## 39. 环形图（Donut / Ring）
+
+> 对应设计稿「8.3 图表-环形图」。中心带总量数字的占比环图，按分类数量分**三环 / 四环 / 五环 / 六环 / 七环 / 八环**等变体。环段配色取 §41 图表色值（淡色系列），中心总量与引导标签取深蓝系字体色。
+
+### 39.1 结构
+
+```
+        三环 / 四环 …（标题）
+        ╭──────────╮
+   Media│          │Social
+   28%  │  34801   │ 36%
+        │ XXX总量  │
+        ╰──────────╯
+          News 28%
+```
+
+### 39.2 环体规格
+
+| 属性 | 取值 | 来源 |
+|------|------|------|
+| 外径 | 容器短边的 `60%~70%` | — |
+| 内径（中空比） | 外径的 `62%`（环宽约 `38%`） | — |
+| 环段间隙 | `2px`（用容器底色 `#0C1836` 描边分隔） | §35.1 |
+| 环段圆角 | `2px`（段端微圆角，可选） | §4.1 |
+| 环段配色 | 按分类数取 §41 对应「N 色」色序 | §41 |
+| 起始角 / 方向 | 顶部 `90°` 起，顺时针 | — |
+
+### 39.3 中心与标签
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 中心主数值（如 `34801`） | `26px Bold D-DIN`，`#FFFFFF` | §2.1.2 |
+| 中心说明（如 `XXX总量`） | `12px Regular`，`#6E88B0` (ZS-004-04) | — |
+| 引导标签名（如 `Social`） | `12px Regular`，`#C5CFE0` (ZS-004-02) | — |
+| 引导标签占比（如 `36%`） | `12px Regular`，`#FFFFFF` 或对应环段色 | — |
+| 引导线 | `1px solid #4A6491` (ZS-004-05) 折线，从环段引至外侧标签 | §6.1 |
+| 变体标题（三环 / 四环…） | `14px Medium`，`#C5CFE0`，居中于图上方 | §35.2 |
+
+### 39.4 交互
+
+| 行为 | 动效 |
+|------|------|
+| 入场 | 环段沿顺时针扫出 `0°→终值`，`600ms ease-out`，按段错峰 `60ms` |
+| Hover 环段 | 该段沿半径外扩 `4px`（`offset`），中心数值切换为该段值 + 占比，弹出 §35.6 Tooltip |
+| 图例点击 | 切换分类显隐，其余环段占比按比例重算 |
+
+---
+
+## 40. 关系图 / 散点图（Network / Scatter）
+
+> 对应设计稿「8.6 图表-散点图」「关系图」。用于展示账号、节点间关系的力导向网络图与散点分布。深蓝背景上以**发光节点 + 渐隐连线 + 平台聚类**呈现，节点配色取主色蓝 / 警告橙 / 危险红做分类，节点尺寸映射权重。
+
+### 40.1 节点（Node）
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 形状 | 圆形（普通节点）/ 头像圆（账号节点，`2px` 描边）/ 六边形（聚合节点） | — |
+| 直径 | `8px ~ 40px`，按权重（连接数 / 数值）线性映射 | — |
+| 分类色 A（本方 / 主） | `#1677FF` (ZS-002-06) | §1.1.3 |
+| 分类色 B（异常 / 外部） | `--func-warning`（橙） | §27.4 |
+| 分类色 C（高危 / 标红） | `#FF4D4F` (ZS-001-05) | §1.1.2 |
+| 节点发光（重点节点） | `0 0 12px` 同色 40% 透明外发光 | §3.1 |
+| 节点文字（数值 / 名称） | `12px Regular`，`#FFFFFF`（节点内）/ `#C5CFE0`（节点外） | — |
+| 中心 / 焦点节点 | 加大直径 + 强发光，橙色 `--func-warning` 高亮 | — |
+
+### 40.2 连线（Edge）
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 线宽 | `1px`（普通）/ `2px`（强关系） | — |
+| 颜色 | `#4A6491` (ZS-004-05) 半透明，或取**起点节点分类色** 40% 透明 | §1.1.5 |
+| 渐隐 | 由中心向外渐隐（`opacity 0.6 → 0.15`），弱化边缘视觉噪声 | — |
+| 方向（有向） | 末端箭头 `4px`，同线色 | — |
+| 高亮态（hover 节点时） | 关联边升为节点分类色满饱和、`2px`，无关边降至 `opacity 0.08` | — |
+
+### 40.3 散点图（Scatter，纯坐标分布）
+
+| 元素 | 规格 / 配色 | 来源 |
+|------|-------------|------|
+| 散点 | 实心圆 `6px ~ 16px`（尺寸可映射第三维） | — |
+| 配色 | 小面积色序（§41 或 §1.1.8 小面积），分类着色 | §41 |
+| 坐标轴 / 网格 | 沿用 §35.3 / §35.4 | §35 |
+| 气泡变体 | 半透明填充 `35%` + `1px` 同色描边，避免重叠遮挡 | — |
+
+### 40.4 平台聚类与图例（如 Facebook / Twitter / 微博 / TikTok）
+
+| 元素 | 规格 | 来源 |
+|------|------|------|
+| 聚类标签 | 平台名 `14px Medium`，对应聚类主色（如蓝 / 橙 / 红） | — |
+| 聚类辅文 | 数值 `12px Regular`，`#6E88B0` | — |
+| 图例（XXX / XXX） | 方块 marker + 文字，置右下角 | §35.5 |
+| 更新提示（如「近30分钟更新数据」） | `12px Regular`，`#6E88B0`，右下角 | — |
+
+### 40.5 控制区（关系图侧栏）
+
+设计稿左侧含「选择目标」下拉 + 分类勾选列表（主页发帖 / 群组发帖 / 私信 / 点赞 / 转发 / 帖子评论 / Pages内容 / 目标的主页帖子）+「添加账号 / 全选账号」按钮。
+
+| 元素 | 规格 | 来源 |
+|------|------|------|
+| 「选择目标」下拉 | 沿用 §15 选择器 | §15 |
+| 分类列表项 | `14px Regular`，前缀分类色圆点 `8px`，沿用 §16 多选 | §16 |
+| 「添加账号」 | §5.2.2 默认按钮（含 `+` 图标） | §5.3.2 |
+| 「全选账号」 | §5.2.3 文本按钮 | §5.2.3 |
+| 刷新图标（右上 ⟳） | `16px`，`#6E88B0`，hover `#4096FF` | §8.2.5 |
+
+### 40.6 交互
+
+| 行为 | 动效 |
+|------|------|
+| 力导向布局 | 节点入场后力导向收敛，`tick` 动画 `~800ms` 后静止 |
+| Hover 节点 | 高亮关联边与邻接节点（§40.2），其余降透明；弹出 §35.6 Tooltip（节点名 / 类型 / 指标） |
+| 点击节点 | 居中聚焦该节点并展开其一度关系；可下钻 |
+| 缩放 / 平移 | 滚轮缩放 `0.5×~3×`，拖拽平移画布 |
+| 拖拽节点 | 可手动拖拽固定节点位置 |
+
+---
+
+## 41. 图表色值（Chart Palette · 多系列色序）
+
+> 对应设计稿「8.7 图表-色值」。这是**全站图表多系列填充的权威色序**（淡色系，深蓝背景上柔和、区分度高）。按系列数量从「三色」到「十色」各有固定取色顺序——系列数为 N 时直接取「N 色」整行，**不要自行截取或乱序**。如需超过十色或特殊场景，由 UI 设计师按整体风格补充。
+
+### 41.1 基础色板
+
+| 色名 | 色值 | 色相 |
+|------|------|------|
+| 粉红 | `#FA9196` | 红 |
+| 橙红 | `#FCA58F` | 橙红 |
+| 橙 | `#FDB887` | 橙 |
+| 浅橙 | `#FFCC80` | 黄橙 |
+| 黄绿 | `#DCD69A` | 黄绿 |
+| 浅绿 | `#BAE1B3` | 绿 |
+| 青绿 | `#97EBCD` | 青绿 |
+| 浅青 | `#9EE4EA` | 青 |
+| 浅蓝 | `#A2E1F9` | 天蓝 |
+| 蓝 | `#80BCFF` | 蓝 |
+
+### 41.2 按系列数取色序
+
+| 系列数 | 取色顺序 |
+|--------|----------|
+| 三色 | `#FA9196` · `#97EBCD` · `#80BCFF` |
+| 四色 | `#FA9196` · `#FFCC80` · `#97EBCD` · `#A2E1F9` |
+| 五色 | `#FA9196` · `#FFCC80` · `#97EBCD` · `#A2E1F9` · `#80BCFF` |
+| 六色 | `#FA9196` · `#FFCC80` · `#BAE1B3` · `#97EBCD` · `#A2E1F9` · `#80BCFF` |
+| 七色 | `#FA9196` · `#FCA58F` · `#FFCC80` · `#BAE1B3` · `#97EBCD` · `#A2E1F9` · `#80BCFF` |
+| 八色 | `#FA9196` · `#FCA58F` · `#FDB887` · `#FFCC80` · `#BAE1B3` · `#97EBCD` · `#A2E1F9` · `#80BCFF` |
+| 九色 | `#FA9196` · `#FCA58F` · `#FDB887` · `#FFCC80` · `#DCD69A` · `#BAE1B3` · `#97EBCD` · `#A2E1F9` · `#80BCFF` |
+| 十色 | `#FA9196` · `#FCA58F` · `#FDB887` · `#FFCC80` · `#DCD69A` · `#BAE1B3` · `#97EBCD` · `#9EE4EA` · `#A2E1F9` · `#80BCFF` |
+
+> 规律：色序整体沿「红 → 橙 → 黄绿 → 绿 → 青 → 蓝」色相环渐变铺开；系列数增加时在中间插入过渡色，**首色恒为 `#FA9196`、末色恒为 `#80BCFF`**，保证冷暖两端锚定不变。
+
+### 41.3 与既有规范的关系
+
+| 色序 | 用途 | 来源 |
+|------|------|------|
+| §41 淡色系列（本节） | 图表**多系列填充**（柱 / 折线 / 环形 / 散点分类）默认色序 | 设计稿 8.7 |
+| §1.1.8 通用图表色序（高彩度） | 强对比强调：单色渐变进度条、KPI 高亮、需要醒目的单系列 | §1.1.8 |
+| §27.4 / §1.1.2 语义色 | 带语义的系列（成功 / 警告 / 错误 / 信息） | §27.4 |
+
+> 三者优先级：**有语义 → 用语义色；多分类并列 → 用 §41；需强调单值 → 用 §1.1.8 高彩度**。§36–§40 中标注的具体系列色为语义示例，实际并列分类应回落到本节色序。
+
+### 41.4 CSS Token 参考
+
+```css
+:root {
+  /* §41 图表多系列色板（淡色系，设计稿 8.7） */
+  --chart-p-red:      #FA9196;
+  --chart-p-redorange:#FCA58F;
+  --chart-p-orange:   #FDB887;
+  --chart-p-amber:    #FFCC80;
+  --chart-p-olive:    #DCD69A;
+  --chart-p-green:    #BAE1B3;
+  --chart-p-teal:     #97EBCD;
+  --chart-p-cyan:     #9EE4EA;
+  --chart-p-skyblue:  #A2E1F9;
+  --chart-p-blue:     #80BCFF;
+}
+```
+
+```js
+// 按系列数取色序（接入 ECharts 时用作 option.color）
+export const CHART_PALETTES = {
+  3:  ['#FA9196', '#97EBCD', '#80BCFF'],
+  4:  ['#FA9196', '#FFCC80', '#97EBCD', '#A2E1F9'],
+  5:  ['#FA9196', '#FFCC80', '#97EBCD', '#A2E1F9', '#80BCFF'],
+  6:  ['#FA9196', '#FFCC80', '#BAE1B3', '#97EBCD', '#A2E1F9', '#80BCFF'],
+  7:  ['#FA9196', '#FCA58F', '#FFCC80', '#BAE1B3', '#97EBCD', '#A2E1F9', '#80BCFF'],
+  8:  ['#FA9196', '#FCA58F', '#FDB887', '#FFCC80', '#BAE1B3', '#97EBCD', '#A2E1F9', '#80BCFF'],
+  9:  ['#FA9196', '#FCA58F', '#FDB887', '#FFCC80', '#DCD69A', '#BAE1B3', '#97EBCD', '#A2E1F9', '#80BCFF'],
+  10: ['#FA9196', '#FCA58F', '#FDB887', '#FFCC80', '#DCD69A', '#BAE1B3', '#97EBCD', '#9EE4EA', '#A2E1F9', '#80BCFF'],
+}
+```
+
+---
+

frontend-web/docs/ui规范-深蓝/05-页面范例.md

@@ -0,0 +1,320 @@
+# 深蓝色 UI 规范 · 05 页面范例（§42–§44）
+
+> 《深蓝色 UI 规范》分册之一。基础令牌见 `00-基础-色彩字体间距.md`，可 import 的变量见 `tokens.css`，总目录与 §索引见 `README.md`。`§N` 编号全局唯一。
+
+**本篇目录**：`42` 表单弹窗范例 · `43` 卡片列表页 · `44` 数据概览仪表盘
+
+---
+
+## 42. 表单弹窗范例（添加 / 编辑标题）
+
+> 对应设计稿「添加/编辑标题」弹窗（截图 ui-25）。这是 §21 弹出式窗口在「专项 / 标题录入」场景下的落地范例：容器 / 遮罩 / 标题栏 / 底部按钮全部沿用 §21，本节补充截图中出现而 §21 未单列的两个原子——**复合输入行**（输入框 + 行内下拉 + 行内按钮）与**行内「添加项」实心按钮**（+ 类别一 / + 类别二），并给出完整表单项清单。配色从 §1.1.2 渐红系（必填星号）、§1.1.3 渐蓝系（ZS-002，主色 / 下拉 / 按钮）、§1.1.5 深蓝系（ZS-004，label / 边框 / 容器）取。
+
+### 42.1 整体布局
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     添加/编辑标题                          ✕    │  ← 标题居中 + 关闭
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │  ← 发光分割线
+│                                                                │
+│ * 专项名称  [请输入内容         ] [一键导入历史专项模板▾] [预览] │  ← 复合输入行
+│ * 专项简介  [请输入内容                                      ]  │
+│ * 国家地区  [                                             ▾ ]  │
+│ * 涉及类别  [ + 类别一 ]  [ + 类别二 ]                          │  ← 行内添加按钮
+│ * 显示指数  [请选择                                       ▾ ]  │
+│                                                                │
+│                      [ 取消 ]   [ 保存 ]                        │  ← 底部居中
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 42.2 容器与标题（沿用 §21）
+
+| 元素 | 取值 | 来源 |
+|------|------|------|
+| 遮罩 / 容器 / 圆角 / 阴影 | 全部沿用 §21.1 | §21.1 |
+| 容器宽度 | 大档 `800px`（复合输入行需要横向空间） | §21.1 |
+| 标题文字 | `添加/编辑标题`，`20px Bold`，`#FFFFFF`，居中 | §21.2 |
+| 标题发光分割线 | `linear-gradient(90deg, transparent, #1677FF, transparent)`，`1px` 高 | §8.2.4 / §21.2 |
+| 关闭 `✕` | `16px`，`#6E88B0` (ZS-004-04)，hover `#4096FF` (ZS-002-05) | §21.2 |
+
+### 42.3 表单项（左 label + 右控件，沿用 §21.4）
+
+| 行 | label | 控件 | 复用 |
+|----|-------|------|------|
+| 1 | `* 专项名称` | 复合输入行（见 §42.4） | §42.4 |
+| 2 | `* 专项简介` | 单行输入框，占位「请输入内容」 | §14.1 |
+| 3 | `* 国家地区` | 选择器（▾，空态占位） | §15.1 |
+| 4 | `* 涉及类别` | 行内「添加项」实心按钮组（见 §42.5） | §42.5 |
+| 5 | `* 显示指数` | 选择器（▾，占位「请选择」） | §15.1 |
+
+- label `14px Regular`，`#C5CFE0` (ZS-004-02)，右对齐；必填星号 `*` `#F5222D` (ZS-001-06) 置于 label 前（§21.4）
+- 表单项纵向间距 `--spacing-4` (16px)（§7.1）
+
+### 42.4 复合输入行（输入框 + 行内下拉 + 行内按钮）
+
+「专项名称」行把主输入框、「一键导入历史专项模板」下拉、「预览」主按钮拼在同一行。
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 主输入框 | 沿用 §14.1，弹性撑满左侧剩余宽 | §14.1 |
+| 行内下拉「一键导入历史专项模板 ▾」 | 沿用 §15.1 选择器触发器，固定宽（约 `200px`），占位文字 `#6E88B0` | §15.1 |
+| 行内按钮「预览」 | §5.2.1 主按钮（实心 `#1677FF` + 白字） | §5.2.1 |
+| 元素间水平间距 | `--spacing-2` (8px) | §7.1 |
+| 三者垂直对齐 | 统一 `32px` 高，基线居中 | §5.1 |
+
+### 42.5 行内「添加项」实心按钮（+ 类别一 / + 类别二）
+
+「涉及类别」用一排实心主色蓝按钮，左侧 `+` 图标，点击进入对应类别的添加 / 编辑流程。
+
+| 状态 | 背景 | 文字 / 图标 | 来源 |
+|------|------|-------------|------|
+| 默认 | `#1677FF` (ZS-002-06) | `#FFFFFF` | §5.2.1 / §5.3.2 |
+| Hover | `#0958D9` (ZS-002-07) | `#FFFFFF` | §5.2.1 |
+| Active | `#003EB3` (ZS-002-08) | `#FFFFFF` | §5.2.1 |
+
+- 高度 `32px`，圆角 `2px`（§4.1），内边距 `0 14px`（§5.1）
+- `+` 图标与文字同色 `#FFFFFF`，间距 `--spacing-1` (4px)（§5.3.2）
+- 按钮之间间距 `--spacing-2` (8px)
+- 与 §21.5.1 分段按钮组的区别：分段组是**互斥单选**（选中才高亮）；此处每个按钮都是**独立的添加入口**，常驻主色实心。
+
+### 42.6 底部操作（沿用 §21.6）
+
+| 元素 | 规格 | 来源 |
+|------|------|------|
+| 对齐 | 居中（跟随截图） | §21.6 |
+| 「取消」 | §5.2.2 默认按钮（Outline） | §5.2.2 |
+| 「保存」 | §5.2.1 主按钮（实心蓝） | §5.2.1 |
+| 顺序 / 间距 | 取消在左、保存在右；间距 `--spacing-2` (8px) | §5.3.4 |
+
+### 42.7 CSS Token 参考
+
+```css
+:root {
+  /* 复合输入行 */
+  --field-row-gap:        8px;        /* --spacing-2 元素间距 */
+  --field-addon-select-w: 200px;      /* 行内下拉固定宽 */
+  --field-row-h:          32px;       /* 统一高度 */
+
+  /* 行内添加按钮（沿用主按钮） */
+  --addbtn-bg:            #1677FF;    /* ZS-002-06 */
+  --addbtn-bg-hover:      #0958D9;    /* ZS-002-07 */
+  --addbtn-bg-active:     #003EB3;    /* ZS-002-08 */
+  --addbtn-text:          #FFFFFF;
+}
+```
+
+---
+
+## 43. 卡片列表页（监测任务卡片）
+
+> 对应设计稿「监测任务卡片列表」（截图 ui-26）。这是 §22 卡片在「监测任务管理」场景下的整页范例：顶部导航沿用 §8、左侧三级菜单沿用 §8.3、卡片容器沿用 §22，本节补充**页面工具条**（搜索 + 添加 + 排序）与**监测任务卡片**的专用布局（头部 + 总量 KPI + 平台统计矩阵 + 底部操作 + 空态）。配色从 §1.1.3 渐蓝系（ZS-002，主色 / KPI 数字）与 §1.1.5 深蓝系（ZS-004，容器 / 文字）取。
+
+### 43.1 整体布局
+
+```
+┌─ Header（§8.2）──────────────────────────────────────────────┐
+├──┬────────────────────────────────────────────────────────────┤
+│三│ [🔍 搜索关键词/任务名称  ] [+ 添加任务]   排序: 创建时间▾ ↑升序 │  ← 工具条
+│级│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
+│菜│ │ 莫某某 10247│ │ 冯某某 10247│ │ 钱某艺 10247│ │ 赵磊   12 │ │  ← 卡片网格
+│单│ │ 社交媒体(52)│ │ 社交媒体(52)│ │ 社交媒体(52)│ │  ...      │ │
+│  │ │ [开始监测] │ │ [开始监测] │ │ [开始监测] │ │           │ │
+│  │ └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
+└──┴────────────────────────────────────────────────────────────┘
+```
+
+### 43.2 页面工具条
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 搜索框 | 沿用 §14.2 基本搜索框，占位「搜索关键词 / 任务名称」 | §14.2 |
+| 「+ 添加任务」 | §5.3.2 图标 + 文字主按钮（实心 `#1677FF` + 白字 + `+`） | §5.3.2 |
+| 排序标签「排序」 | `14px Regular`，`#6E88B0` (ZS-004-04) | — |
+| 排序字段「创建时间 ▾」 | §15.1 选择器触发器（小号） | §15.1 |
+| 升 / 降序切换「↑ 升序 / ↓ 降序」 | §5.2.3 文本按钮，激活向 `#4096FF` (ZS-002-05) | §5.2.3 |
+| 工具条 → 卡片区间距 | `--spacing-5` (24px) | §7.1 |
+| 工具条内元素间距 | `--spacing-3` (12px) | §7.1 |
+
+### 43.3 监测任务卡片
+
+```
+┌──────────────────────────────────────┐
+│ 👤 莫某某                       10247  │  ← 头部：头像+名称 / 右上总量
+│    2023-09-09 09:13:00          总数量 │
+│ ────────────────────────────────────  │
+│ 社交媒体 (52)                          │  ← 统计区标题
+│ 微博  16    推特   8   facebook 16     │  ← 平台统计矩阵
+│ 抖音  12    土豆   6   大牛网    9     │
+│ ────────────────────────────────────  │
+│ url: t.djxqbjhgf9y.cn   也方开夫某利地址│
+│              [ 开始监测 ]              │  ← 底部操作
+└──────────────────────────────────────┘
+```
+
+#### 43.3.1 结构与配色
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 卡片容器 | 同 §22.1（背景 `#122347` / 边框 `#1A2F5A` / 圆角 `4px` / 一级阴影） | §22.1 |
+| 头像占位 | 圆 `40px`，底 `#1A2F5A` (ZS-004-07)，图标 `#6E88B0` | §22.3 |
+| 任务名（莫某某） | `16px Medium`，`#FFFFFF` | §22.3 |
+| 创建时间 | `12px Regular`（D-DIN 数字），`#6E88B0` (ZS-004-04) | §8.2.5 |
+| 总量数值（10247） | `26px Bold`（D-DIN），`#4096FF` (ZS-002-05) | §2.1.2 / §1.1.3 |
+| 总量标签「总数量」 | `12px Regular`，`#6E88B0` (ZS-004-04) | — |
+| 头部底分割线 | `1px solid #1A2F5A` (ZS-004-07) | §6.1 |
+
+#### 43.3.2 平台统计矩阵
+
+统计区为「平台名 + 数值」多列网格（如 社交媒体 (52) 下的 微博 / 推特 / facebook…）。
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 区标题「社交媒体 (52)」 | `14px Medium`，`#C5CFE0` (ZS-004-02)；括号计数 `#6E88B0` | — |
+| 平台名 | `14px Regular`，`#6E88B0` (ZS-004-04) | — |
+| 平台数值（数字） | `16px Bold`（D-DIN），`#C5CFE0` (ZS-004-02) | §2.1.2 |
+| 矩阵列数 | 3 列等分，行间距 `--spacing-2` (8px) | §7.1 |
+| 名 / 值间距 | `--spacing-1` (4px) | §7.1 |
+
+#### 43.3.3 底部操作
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 「开始监测」 | §5.2.1 主按钮（实心 `#1677FF`）；运行中切 §5.4.2 加载态 | §5.2.1 / §5.4.2 |
+| 次要链接（如 url / 地址） | §5.2.3 文本按钮 `#4096FF` (ZS-002-05) | §5.2.3 |
+| 操作区上分割线 | `1px solid #2D4473`（弱化） | §6.1 |
+
+#### 43.3.4 空态卡片变体
+
+部分卡片暂无数据（总量 `0` + 占位）：
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 总量数值 | `0`，`26px Bold`，`#6E88B0` (ZS-004-04，弱化非主色) | — |
+| 占位文字「暂无数据」 | `14px Regular`，`#6E88B0` (ZS-004-04)，居中 | §35.9 |
+| 占位插画 | 灰度线性图标，`#4A6491` (ZS-004-05) | §35.9 |
+
+### 43.4 卡片栅格（沿用 §22.4）
+
+| 规则 | 取值 | 来源 |
+|------|------|------|
+| 列数 | 自适应，常用 3~4 列 | — |
+| 卡片横 / 纵间距 | `--spacing-6` (32px) | §22.4 |
+| 卡片内边距 | `--spacing-4` (16px) | §22.4 |
+
+### 43.5 CSS Token 参考
+
+```css
+:root {
+  /* 监测任务卡片 */
+  --task-card-name:     #FFFFFF;
+  --task-card-time:     #6E88B0;   /* ZS-004-04 */
+  --task-kpi-num:       #4096FF;   /* ZS-002-05 总量数字 */
+  --task-kpi-label:     #6E88B0;   /* ZS-004-04 */
+  --task-stat-name:     #6E88B0;   /* ZS-004-04 平台名 */
+  --task-stat-num:      #C5CFE0;   /* ZS-004-02 平台数值 */
+  --task-divider:       #1A2F5A;   /* ZS-004-07 头部分割 */
+  --task-divider-weak:  #2D4473;   /* ZS-004-06 操作区分割 */
+  --task-empty-text:    #6E88B0;   /* ZS-004-04 空态 */
+}
+```
+
+---
+
+## 44. 数据概览仪表盘（KPI 指标条 + 综合图表）
+
+> 对应设计稿「资源使用率概览大屏」（截图 ui-27）。这是一张把 §35–§41 各图表与 §28 表格、§9.1 页签组合在一起的概览页。本节补充截图顶部出现而前文未单列的新原子——**KPI 指标卡条**（图标 + 标签 + 大数值 + 已用 + 迷你环 + 同比 / 环比箭头徽标），其余区块均引用既有章节。配色从 §1.1.3 渐蓝系（ZS-002，主色 / 数值）、§1.1.4 渐青系（ZS-003，辅色）、§1.1.5 深蓝系（ZS-004，容器 / 文字）取；涨跌语义色见 §44.2。
+
+### 44.1 整体布局
+
+```
+┌──┬────────────────────────────────────────────────────────────┐
+│三│ ▓ KPI 指标条（账号/设备/浏览器/代理IP/VPS/邮箱/手机卡/链卡服 使用率）▓│
+│级│ ┌─ ▌XXX标题 ───────────────┐ ┌─ ▌XXX标题（资源列表）────────┐│
+│菜│ │ [全部|账号资源|设备指标…]  │ │ 🔍搜索   排序                ││
+│单│ │  ◐异常率40%  ╱╲折线异常点 │ │ 资源资料  关联设备  2024-…   ││
+│  │ │  总量300 正常270 异常30   │ │ …（§28 表格行）              ││
+│  │ └───────────────────────────┘ └──────────────────────────────┘│
+│  │ ┌─ ▌XXX标题 ───────────────────────┐ ┌─ ▌XXX标题 ──────────┐│
+│  │ │ 异常分析 饼 + 折线（§37 / §39）    │ │ ◐300/270 + 趋势饼    ││
+│  │ └────────────────────────────────────┘ └─────────────────────┘│
+└──┴────────────────────────────────────────────────────────────┘
+```
+
+### 44.2 涨跌语义色
+
+| 语义 | 色值 | 来源 |
+|------|------|------|
+| 上升 / 正向（▲） | `#13C2C2` (ZS-003-06，辅色青) | §1.1.4 |
+| 下降 / 负向（▼） | `#F5222D` (ZS-001-06，主色红) | §1.1.2 |
+| 持平 | `#6E88B0` (ZS-004-04) | §1.1.5 |
+
+> 涨跌仅用语义色，不混入图表多系列色；正向用辅色青（ZS-003）而非主色蓝，避免与 KPI 数值蓝撞色。
+
+### 44.3 KPI 指标卡条
+
+横向一排等宽指标卡，每张承载一个使用率指标（如「账号使用率 139 已用」+ 迷你环 + 同比箭头）。
+
+```
+┌────────────────────────┐
+│ 🅰  账号使用率           │  ← 图标 + 标签
+│ 139       ◐ 45% ▲       │  ← 大数值 + 迷你环 + 同比
+│ 已用              同比   │
+└────────────────────────┘
+```
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 卡片容器 | 背景 `#122347` (ZS-004-08)，边框 `1px solid #1A2F5A`，圆角 `4px`，一级阴影 | §22.1 |
+| 指标图标 | `20px`，主色 `#4096FF` (ZS-002-05) 单色化 | §1.1.6 |
+| 指标标签（账号使用率） | `14px Regular`，`#C5CFE0` (ZS-004-02) | — |
+| 大数值（139） | `26px Bold`（D-DIN），`#FFFFFF` | §2.1.2 |
+| 单位 / 说明「已用」 | `12px Regular`，`#6E88B0` (ZS-004-04) | — |
+| 迷你环（mini-donut） | 直径 `32px`，环宽 `4px`，已用段 `#1677FF` (ZS-002-06)，底环 `#2D4473` (ZS-004-06) | §39.2 |
+| 环内百分比 | `12px Bold`（D-DIN），`#FFFFFF` | §39.3 |
+| 同比 / 环比箭头徽标 | `12px`，▲ 用 `#13C2C2`、▼ 用 `#F5222D`（见 §44.2） | §44.2 |
+| 卡片宽度 | 等分横排（8 张则各占 1/8），最小宽 `160px` | — |
+| 卡片间距 | `--spacing-4` (16px) | §7.1 |
+| 卡片内边距 | `--spacing-4` (16px) | §7.1 |
+
+### 44.4 区块组合引用
+
+| 区块 | 复用 | 备注 |
+|------|------|------|
+| 区块标题（▌XXX标题） | §35.2 图表标题（主色蓝竖条 + 文字） | — |
+| 分类页签（全部 / 账号资源 / …） | §9.1.1 横向页签 | 激活 `#4096FF` + `2px` 下划线 |
+| 日期筛选（右上 `2023-02`） | §17.1 日期触发器 | — |
+| 异常率环形图（40% / 总量300 / 正常270 / 异常30） | §39 环形图 | 正常段主色蓝、异常段 `#F5222D`（§44.2） |
+| 折线异常点图（1月10日 异常率12.9%） | §37.3 单线异常点图 + §35.6 Tooltip | 异常点用红 `#F5222D` 强调 |
+| 资源列表表格 | §28 表格 + §14.2 搜索 + §13 分页 | — |
+| 异常分析饼 / 趋势饼 | §39 环形图 | 多系列回落 §41 色序 |
+| 容器 / 内边距 / 多图间距 | §35.1 图表容器 | `--spacing-5` / `--spacing-6` |
+
+### 44.5 交互
+
+| 行为 | 规则 |
+|------|------|
+| KPI 卡 hover | 卡片阴影升二级（§3.1.4），迷你环高亮，弹出 §35.6 Tooltip（已用 / 总量 / 同比明细） |
+| 页签切换 | 切换分类后下方图表与表格联动刷新（§9.1.1） |
+| 图表 hover | 沿用各图表节交互（§37.6 / §39.4 等） |
+| 日期筛选变更 | 重新拉取区块数据，图表入场动画重放 |
+
+### 44.6 CSS Token 参考
+
+```css
+:root {
+  /* KPI 指标卡 */
+  --kpi-card-bg:     #122347;   /* ZS-004-08 */
+  --kpi-card-border: #1A2F5A;   /* ZS-004-07 */
+  --kpi-icon:        #4096FF;   /* ZS-002-05 */
+  --kpi-label:       #C5CFE0;   /* ZS-004-02 */
+  --kpi-value:       #FFFFFF;
+  --kpi-sub:         #6E88B0;   /* ZS-004-04 已用 */
+  --kpi-ring-used:   #1677FF;   /* ZS-002-06 迷你环已用段 */
+  --kpi-ring-track:  #2D4473;   /* ZS-004-06 迷你环底 */
+
+  /* 涨跌语义 */
+  --trend-up:        #13C2C2;   /* ZS-003-06 上升（辅色青） */
+  --trend-down:      #F5222D;   /* ZS-001-06 下降（红） */
+  --trend-flat:      #6E88B0;   /* ZS-004-04 持平 */
+}
+```

frontend-web/docs/ui规范-深蓝/README.md

@@ -0,0 +1,82 @@
+# 深蓝色 UI 规范（拆分版）
+
+面向开发的深蓝主题设计规范。原单文件 `../ui修改-深蓝.md`（约 5200 行）已按模块拆分到本目录，便于按需查阅、减少 diff 冲突，也方便配合 AI 只加载相关分册。
+
+> **颜色唯一来源**：所有色值以 **§1 色彩**（见 [`00-基础-色彩字体间距.md`](./00-基础-色彩字体间距.md)）为准，可执行变量见 [`tokens.css`](./tokens.css)。业务代码 **import `tokens.css` 并用 `var(--token)`**，不要硬编码 HEX。
+
+## 分册
+
+| 文件 | 章节 | 内容 |
+|------|------|------|
+| [`00-基础-色彩字体间距.md`](./00-基础-色彩字体间距.md) | §1–§7 | 色彩 / 字体 / 阴影 / 圆角 / 按钮 / 分割线 / 间距 |
+| [`01-导航.md`](./01-导航.md) | §8–§13 | 导航组件 / 锚点页签 / 步骤条 / 面包屑 / 页头 / 分页 |
+| [`02-表单.md`](./02-表单.md) | §14–§21 | 输入框 / 选择器 / 单复选 / 日期 / 穿梭框 / 树选择 / 上传 / 弹窗 |
+| [`03-数据展示.md`](./03-数据展示.md) | §22–§34 | 卡片 / 折叠 / 描述列表 / 列表 / 时间轴 / 进度条 / 表格 / 标签 / 树 / 对话框 / 提示 / 气泡确认 |
+| [`04-图表.md`](./04-图表.md) | §35–§41 | 图表通用 / 柱状 / 折线 / 甘特 / 环形 / 关系散点 / 图表色值 |
+| [`05-页面范例.md`](./05-页面范例.md) | §42–§44 | 表单弹窗 / 卡片列表页 / 数据概览仪表盘 |
+| [`tokens.css`](./tokens.css) | — | 全量 CSS 变量（颜色 / 间距 / 圆角 / 阴影 / 字体），可直接 import |
+
+## § 索引（编号 → 所在文件）
+
+章节编号 `§N` 全局唯一、跨文件不变；文中 `§N` / `§N.x` 引用按下表定位。
+
+| § | 标题 | 文件 |
+|---|------|------|
+| §1 | 色彩 | 00 |
+| §2 | 字体 | 00 |
+| §3 | 阴影 | 00 |
+| §4 | 圆角 | 00 |
+| §5 | 按钮 | 00 |
+| §6 | 分割线 | 00 |
+| §7 | 间距 | 00 |
+| §8 | 导航组件 | 01 |
+| §9 | 锚点与页签 | 01 |
+| §10 | 步骤条 | 01 |
+| §11 | 面包屑 | 01 |
+| §12 | 页头 | 01 |
+| §13 | 分页 | 01 |
+| §14 | 输入框（搜索框） | 02 |
+| §15 | 选择器 | 02 |
+| §16 | 单选与多选 | 02 |
+| §17 | 日期选择器 | 02 |
+| §18 | 穿梭框 | 02 |
+| §19 | 树选择 | 02 |
+| §20 | 上传 | 02 |
+| §21 | 弹出式窗口（Modal） | 02 |
+| §22 | 卡片 | 03 |
+| §23 | 折叠面板 | 03 |
+| §24 | 描述列表 | 03 |
+| §25 | 列表 | 03 |
+| §26 | 时间轴（节点型） | 03 |
+| §27 | 进度条 | 03 |
+| §28 | 表格 | 03 |
+| §29 | 标签 | 03 |
+| §30 | 树形控件 | 03 |
+| §31 | 时间轴（长文本） | 03 |
+| §32 | 对话框（确认框） | 03 |
+| §33 | 全局提示 | 03 |
+| §34 | 气泡确认 | 03 |
+| §35 | 图表通用规范 | 04 |
+| §36 | 柱状图 | 04 |
+| §37 | 折线图 | 04 |
+| §38 | 甘特图 | 04 |
+| §39 | 环形图 | 04 |
+| §40 | 关系图 / 散点图 | 04 |
+| §41 | 图表色值 | 04 |
+| §42 | 表单弹窗范例 | 05 |
+| §43 | 卡片列表页 | 05 |
+| §44 | 数据概览仪表盘 | 05 |
+
+## 约定
+
+- **颜色**：以 §1 为准，代码用 `tokens.css` 的 `var(--token)`。功能语义色（成功/警告/错误/信息/处理中）见 §1.1.9 / `--func-*`。
+- **间距**：仅用 §7 的 8px 阶梯（`--spacing-1..8`），禁用 5px / 13px 等非阶梯值。
+- **圆角**：按钮/输入/标签 `2px`，卡片/分栏/弹窗 `4px`（`--radius-*`）。
+- **跨节引用**：保留 `§N` 编号，用上方「§ 索引」定位文件。
+- **名称易混点**：§26 时间轴(节点型) ↔ §31 时间轴(长文本)；§21 弹出式窗口(Modal) ↔ §32 对话框(确认框)。
+- **图表两套色板**：§1.1.8（高彩度，强调单值）与 §41（淡色系，多分类并列）并存，优先级见 §41.3。
+
+## 维护
+
+- 改色 / 改间距 → 先改 **`tokens.css` + §1/§7**，组件分册回落引用，不在分册里另立硬编码。
+- 新增整页范例 → 进 `05-页面范例.md`，沿用既有组件 § 与 `tokens.css`。

frontend-web/docs/ui规范-深蓝/tokens.css

@@ -0,0 +1,211 @@
+/* =============================================================================
+ * 深蓝色 UI 规范 · 设计令牌（tokens.css）
+ * -----------------------------------------------------------------------------
+ * 这是《深蓝色 UI 规范》全站颜色 / 间距 / 圆角 / 阴影 / 字体的唯一可执行来源。
+ * 开发时优先 import 本文件并使用 var(--token)，不要在业务代码里硬编码 HEX。
+ *
+ * 文档对应：
+ *   §1 色彩  → 原始色阶 --zs-*、功能语义 --func-*、装饰/图表色板
+ *   §2 字体  → --font-* / --fs-*
+ *   §3 阴影  → --shadow-*
+ *   §4 圆角  → --radius-*
+ *   §7 间距  → --spacing-*
+ * 组件级 token（--card-* / --modal-* / --kpi-* 等）保留在各分册的「CSS Token 参考」
+ * 小节中，均回落到本文件的原始/语义 token。
+ * ========================================================================== */
+
+:root {
+  /* ---------------------------------------------------------------------------
+   * 1. 原始色阶（§1.1.2–§1.1.5）—— 01 最浅 → 10 最深
+   * ------------------------------------------------------------------------ */
+
+  /* 渐红系 ZS-001 —— 警示 / 错误 / 强调 */
+  --zs-001-01: #FFF1F0;
+  --zs-001-02: #FFCCC7;
+  --zs-001-03: #FFA39E;
+  --zs-001-04: #FF7875;
+  --zs-001-05: #FF4D4F;
+  --zs-001-06: #F5222D;
+  --zs-001-07: #CF1322;
+  --zs-001-08: #A8071A;
+  --zs-001-09: #820014;
+  --zs-001-10: #5C0011;
+
+  /* 渐蓝系 ZS-002 —— 信息 / 链接 / 次级操作（含主色） */
+  --zs-002-01: #E6F4FF;
+  --zs-002-02: #BAE0FF;
+  --zs-002-03: #91CAFF;
+  --zs-002-04: #69B1FF;
+  --zs-002-05: #4096FF;
+  --zs-002-06: #1677FF;
+  --zs-002-07: #0958D9;
+  --zs-002-08: #003EB3;
+  --zs-002-09: #002C8C;
+  --zs-002-10: #001D6C;
+
+  /* 渐青系 ZS-003 —— 成功 / 在线 / 数据高亮（含辅色） */
+  --zs-003-01: #E6FFFB;
+  --zs-003-02: #B5F5EC;
+  --zs-003-03: #87E8DE;
+  --zs-003-04: #5CDBD3;
+  --zs-003-05: #36CFC9;
+  --zs-003-06: #13C2C2;
+  --zs-003-07: #08979C;
+  --zs-003-08: #006D75;
+  --zs-003-09: #00474F;
+  --zs-003-10: #002329;
+
+  /* 深蓝系 ZS-004 —— 背景 / 容器 / 导航 / 文字（主题核心） */
+  --zs-004-01: #E8EDF5;
+  --zs-004-02: #C5CFE0;
+  --zs-004-03: #9BADC8;
+  --zs-004-04: #6E88B0;
+  --zs-004-05: #4A6491;
+  --zs-004-06: #2D4473;
+  --zs-004-07: #1A2F5A;
+  --zs-004-08: #122347;
+  --zs-004-09: #0C1836;
+  --zs-004-10: #060E24;
+
+  /* ---------------------------------------------------------------------------
+   * 2. 功能角色色（§1.1.6）—— 从色阶提取的语义别名
+   * ------------------------------------------------------------------------ */
+  --color-primary:         var(--zs-002-06);  /* #1677FF 主操作 */
+  --color-primary-hover:   var(--zs-002-07);  /* #0958D9 */
+  --color-primary-active:  var(--zs-002-08);  /* #003EB3 */
+  --color-link:            var(--zs-002-05);  /* #4096FF 链接 / 文本按钮 */
+  --color-accent:          var(--zs-003-06);  /* #13C2C2 辅色 */
+
+  --color-text:            var(--zs-004-02);  /* #C5CFE0 正文字体 */
+  --color-text-secondary:  var(--zs-004-04);  /* #6E88B0 次级字体 */
+  --color-text-disabled:   var(--zs-004-05);  /* #4A6491 禁用字体 */
+  --color-text-strong:     #FFFFFF;           /* 标题 / 强调 */
+
+  --color-bg-page:         var(--zs-004-09);  /* #0C1836 页面背景 */
+  --color-bg-container:    var(--zs-004-07);  /* #1A2F5A 容器背景 */
+  --color-bg-card:         var(--zs-004-08);  /* #122347 卡片背景 */
+  --color-bg-deepest:      var(--zs-004-10);  /* #060E24 全局底色 */
+  --color-border:          var(--zs-004-07);  /* #1A2F5A 容器边框 */
+  --color-border-strong:   var(--zs-004-04);  /* #6E88B0 控件边框 */
+  --color-white:           #FFFFFF;
+
+  /* ---------------------------------------------------------------------------
+   * 3. 功能语义色（§1.1.9）—— 成功/警告/错误/信息/处理中
+   *    成功绿、警告橙为标准色系外补充色；其余复用色阶。
+   * ------------------------------------------------------------------------ */
+  --func-success:          #52C41A;           /* 补充色 · 成功绿 */
+  --func-warning:          #FAAD14;           /* 补充色 · 警告橙 */
+  --func-error:            var(--zs-001-06);  /* #F5222D */
+  --func-info:             var(--zs-002-06);  /* #1677FF */
+  --func-processing:       var(--zs-003-06);  /* #13C2C2 */
+
+  /* 浅底变体（Message / Alert / Tag 背景，16% 透明度） */
+  --func-success-bg:       rgba(82, 196, 26, 0.16);
+  --func-warning-bg:       rgba(250, 173, 20, 0.16);
+  --func-error-bg:         rgba(245, 34, 45, 0.16);
+  --func-info-bg:          rgba(22, 119, 255, 0.16);
+
+  /* ---------------------------------------------------------------------------
+   * 4. 小面积装饰色（§1.1.7）—— 仅点缀 / 徽标，勿做大面积背景
+   * ------------------------------------------------------------------------ */
+  --deco-violet:           #6388FF;
+  --deco-danger:           #F5222D;
+  --deco-brand-blue:       #12306C;
+  --deco-teal:             #478880;
+  --deco-alert:            #950404;
+
+  /* ---------------------------------------------------------------------------
+   * 5. 字体（§2）
+   * ------------------------------------------------------------------------ */
+  --font-zh:     'Noto Sans S Chinese', 'Noto Sans SC', system-ui, sans-serif;
+  --font-num:    'D-DIN', 'Noto Sans S Chinese', sans-serif;   /* 数据数字 */
+  --font-digital:'DS-Digital', 'D-DIN', sans-serif;            /* 大屏特殊数字 */
+  --font-logo:   'DOUYUFont', 'Noto Sans S Chinese', sans-serif;
+  --font-table:  'Arial', 'Noto Sans S Chinese', sans-serif;   /* 表格数字 */
+
+  /* 常用字号（后台系统，§2.1.2） */
+  --fs-12: 12px;
+  --fs-14: 14px;
+  --fs-16: 16px;
+  --fs-18: 18px;
+  --fs-20: 20px;
+  --fs-24: 24px;
+  --fs-26: 26px;
+
+  /* ---------------------------------------------------------------------------
+   * 6. 间距（§7）—— 8px 基准，密(≤16) / 疏(≥24)，禁用非阶梯值
+   * ------------------------------------------------------------------------ */
+  --spacing-1: 4px;
+  --spacing-2: 8px;
+  --spacing-3: 12px;
+  --spacing-4: 16px;
+  --spacing-5: 24px;
+  --spacing-6: 32px;
+  --spacing-7: 40px;
+  --spacing-8: 56px;
+
+  /* ---------------------------------------------------------------------------
+   * 7. 圆角（§4）
+   * ------------------------------------------------------------------------ */
+  --radius-button: 2px;
+  --radius-input:  2px;
+  --radius-tag:    2px;
+  --radius-card:   4px;
+  --radius-panel:  4px;
+  --radius-modal:  4px;
+
+  /* ---------------------------------------------------------------------------
+   * 8. 阴影（§3.1.4）
+   * ------------------------------------------------------------------------ */
+  --shadow-1: 0 2px 8px rgba(22, 119, 255, 0.12);   /* 卡片悬浮 */
+  --shadow-2: 0 4px 16px rgba(22, 119, 255, 0.24);  /* hover / 弹出层 */
+  --shadow-3: 0 8px 32px rgba(6, 14, 36, 0.6);      /* Dialog / Drawer */
+  --shadow-modal-mask: rgba(6, 14, 36, 0.6);        /* 遮罩 */
+
+  /* 常用渐变 */
+  --gradient-header: linear-gradient(180deg, #122347 0%, #0C1836 100%);          /* 顶栏 §8.2.1 */
+  --gradient-title-line: linear-gradient(90deg, transparent 0%, #1677FF 50%, transparent 100%); /* 标题发光线 §8.2.4 */
+}
+
+/* =============================================================================
+ * 图表多系列色板
+ * ========================================================================== */
+:root {
+  /* 通用图表色序（§1.1.8，面积大：柱/折线/饼，高彩度） */
+  --chart-g-1: #1677FF;
+  --chart-g-2: #13C2C2;
+  --chart-g-3: #4096FF;
+  --chart-g-4: #36CFC9;
+  --chart-g-5: #69B1FF;
+  --chart-g-6: #5CDBD3;
+  --chart-g-7: #91CAFF;
+  --chart-g-8: #87E8DE;
+
+  /* 小面积图表色序（§1.1.8，散点/迷你图/徽标） */
+  --chart-s-1: #4096FF;
+  --chart-s-2: #36CFC9;
+  --chart-s-3: #FF4D4F;
+  --chart-s-4: #FFA39E;
+  --chart-s-5: #6388FF;
+  --chart-s-6: #478880;
+
+  /* 多系列填充色板（§41，淡色系，分类并列默认色序） */
+  --chart-p-red:       #FA9196;
+  --chart-p-redorange: #FCA58F;
+  --chart-p-orange:    #FDB887;
+  --chart-p-amber:     #FFCC80;
+  --chart-p-olive:     #DCD69A;
+  --chart-p-green:     #BAE1B3;
+  --chart-p-teal:      #97EBCD;
+  --chart-p-cyan:      #9EE4EA;
+  --chart-p-skyblue:   #A2E1F9;
+  --chart-p-blue:      #80BCFF;
+}
+
+/*
+ * 图表配色优先级（§41.3）：
+ *   有语义 → 用 --func-*；多分类并列 → 用 --chart-p-*（§41 色板）；
+ *   需强调单值 → 用 --chart-g-* / --chart-s-*（§1.1.8 高彩度）。
+ *
+ * 接入 ECharts 时按系列数取 option.color，见 §41.4 的 CHART_PALETTES。
+ */

frontend-web/docs/上游升级对比与建议.md

@@ -0,0 +1,156 @@
+# DeerFlow 上游升级对比与回合建议
+
+> 对比对象：`bytedance/deer-flow`（上游，HEAD `9f3be2a` @ 2026-05-30）vs 本仓库 fork。
+> 生成日期：2026-05-31。
+> 说明：按用户要求，**多语言 (i18n)** 与 **播客 / TTS (podcast)** 不在本次升级范围内，已剔除。
+
+---
+
+## 0. 背景与对比结论
+
+| 项 | 结论 |
+|---|---|
+| fork 切出时间 | **≈ 2026-05-12**（与目录名 `offline-backend-20260512` 吻合） |
+| 上游当前 HEAD | `9f3be2a` @ 2026-05-30，完整历史 2186 提交 |
+| fork 之后上游新增 | **95 个提交**（7 feat / 1 perf / 60 fix / 依赖与文档若干） |
+| 后端核心框架 `packages/harness/deerflow/` | **高度同源、目录结构完全一致**，差异主要来自这 95 个提交 |
+| 前端 | 技术栈已分道扬镳：上游仍是 **Next.js**，本仓库已迁到 **Vite + React Router**，文件几乎全不同 |
+
+「升级」分两类，本文都覆盖：
+- **A 类**：fork 之后上游真正新增的（95 提交）——同源、可 cherry-pick，**优先回合**。
+- **B 类**：fork 时就裁掉/换了路线、上游一直保留的能力——成本高、按业务取舍。
+
+---
+
+## 1. 后端升级（A 类：fork 后上游新增）
+
+### 1.1 新能力（feat / perf）
+
+| 日期 | 升级 | 提交 | 说明 |
+|---|---|---|---|
+| 05-29 | ToolOutputBudgetMiddleware | #3303 | 给超大工具输出做预算保护，防止单个结果撑爆上下文 |
+| 05-28 | MiMo reasoning 支持 | #3298 | 兼容小米 MiMo 模型思维链回传 |
+| 05-21 | 链路追踪命名优化 | #3101 | 图名改 `lead_agent`、用自定义 agent 名作 run_name |
+| 05-21 | 循环检测延迟告警 | #2752 | 警告延迟注入，减少对正常多轮对话的误打断 |
+| 05-20 | Sandbox 下载文件接口 | #3038 | 可把沙箱内产物取回 |
+| 05-15 | Discord 渠道增强 | #2842 | 仅@提及、thread 路由、typing 指示 |
+| 05-13 | 子代理 token 用量流式上报 | #2882 | subagent 消耗实时汇总到 header，利于展示/计费 |
+| 05-12 | perf：线程元数据过滤下推 SQL | #2865 | 线程列表筛选走 SQL，性能提升 |
+
+能力性增强（fix 前缀实为增强）：MCP 跨调用持久化会话、支持有状态 server（#3089 / #3203）；摘要触发阈值调优（#3174）。
+
+### 1.2 重要稳定性修复
+
+| 主题 | 提交 | 价值 |
+|---|---|---|
+| 摘要压缩后保留消息 | #3280 | 数据正确性关键 |
+| 重启后从持久化恢复 runs / interrupted 状态 | #2932(破坏性)、#2989、#3152、#3155 | 网关重启不丢运行 |
+| JWT secret 持久化、多 worker 共享网关 token | #2933、#3184 | 重启/多进程登录态不失效 |
+| memory 更新按 agent 隔离 + 包裹 JSON 解析健壮性 | #2941、#3252 | 记忆串号/解析修复 |
+| MCP 配置接口脱敏 | #2667 | 防密钥泄露 |
+| 阻塞 IO 移出事件循环 | #3311、#2822（+检测门禁 #3229） | 消除事件循环阻塞 |
+
+### 1.3 依赖升级
+- Python：`langsmith 0.7.36 → 0.8.0`、`idna 3.13 → 3.15`
+
+### 1.4 怎么做（回合 A 类后端升级）
+
+> 前提：本仓库 `packages/harness/deerflow/` 与上游高度同源，cherry-pick 冲突面小。
+
+1. **加上游为远程并拉取历史**（在后端所在 git 仓库根执行）：
+   ```bash
+   git remote add upstream https://github.com/bytedance/deer-flow.git
+   git fetch upstream
+   ```
+2. **逐条预览某个提交的改动范围**：
+   ```bash
+   git show <commit_hash> --stat
+   git show <commit_hash> -- backend/packages/harness/deerflow/...
+   ```
+3. **单条回合**（推荐用 `-x` 记录来源；如路径前缀不一致需先确认）：
+   ```bash
+   git cherry-pick -x <commit_hash>
+   # 冲突时：解决后
+   git cherry-pick --continue
+   ```
+   > 注意：上游后端在 `backend/` 子目录，本仓库后端在 `offline-backend-20260512/backend/`。若 cherry-pick 因路径不匹配失败，改用按文件打补丁：
+   > ```bash
+   > git show <hash> -- backend/<path> | git apply --directory=offline-backend-20260512/backend -p2 -3
+   > ```
+4. **回合后必跑校验**（在 `offline-backend-20260512/backend/`）：
+   ```bash
+   make test     # PYTHONPATH=. uv run pytest tests/ -v
+   make lint
+   ```
+   重点确认 `tests/test_harness_boundary.py`（harness→app 防火墙）与中间件链顺序未被破坏。
+5. **依赖升级**：同步上游 `pyproject.toml` 对应行后执行 `uv lock && make install`；离线环境需同步更新 `requirements-offline.txt` / `wheelhouse`。
+
+---
+
+## 2. 前端升级（B 类：上游有、本仓库缺）
+
+> 已剔除多语言、播客。下表为关键词核验结果（本仓库 vs 上游命中文件数）。
+
+| 功能 | 本仓库 | 上游 | 状态 |
+|---|---|---|---|
+| Prose 文本润色 | 0 | 8 | 上游独有 |
+| Replay 研究回放 | 2 | 29 | 上游完整，本仓库近乎无 |
+| PPT / PPTX 生成 | 2 | 14 | 上游完整，本仓库近乎无 |
+| Landing 落地页 | 0 | 11 | 上游独有（营销/介绍页，按需） |
+| 静态 demo 模式 | 无 | #3170 | fork 后上游新增 |
+
+前端体验类修复（可参考实现）：流式渲染、消息去重、历史消息 Mermaid 预览、新建会话即时入侧栏。
+前端依赖升级：`brace-expansion 1.x → 5.0.5`（安全）、`uuid 10 → 14`。
+
+### 2.1 怎么做（前端能力移植）
+
+> 前端技术栈已不同（Next.js → Vite + React Router），**不能直接 cherry-pick**，需按"读上游实现 → 适配到本仓库"的方式重写。
+
+通用步骤：
+1. 在上游 `frontend/src/` 定位目标功能的页面/组件/hook 与对应的后端 API 调用。
+2. 后端能力是否具备：Prose / PPT / Replay 依赖后端相应接口，先确认本仓库后端有无对应路由（多为 deep_research/skills 相关），**没有则前端无法独立完成**，需连带回合后端。
+3. 适配差异点：
+   - 路由：上游 app router (`src/app/...`) → 本仓库 `src/pages/` + `PageRoutes.tsx` / `WorkspaceRoutes.tsx`。
+   - 导航 API：用本仓库 `src/shims/`（`next/link`、`next/navigation` 已 polyfill）。
+   - 数据流：沿用本仓库 TanStack Query + `@langchain/langgraph-sdk` 流式。
+4. 验证：`pnpm typecheck` + `pnpm dev` 实测。
+
+---
+
+## 3. 推荐升级清单（按优先级）
+
+### P0 — 强烈建议（低风险、高价值，A 类）
+- **摘要压缩后保留消息 #3280** —— 数据正确性，直接影响长对话可用性。
+- **重启后恢复 runs / interrupted #2932 #2989 #3152 #3155** —— 生产稳定性核心。
+- **JWT secret 持久化 / 多 worker 共享 token #2933 #3184** —— 否则重启或多进程部署会掉登录态。
+- **阻塞 IO 移出事件循环 #3311 #2822** —— 并发吞吐与响应延迟改善。
+
+### P1 — 建议（实用增强）
+- **ToolOutputBudgetMiddleware #3303** —— 防超大工具输出拖垮上下文，对 agent 稳定性有实际帮助。
+- **MCP 持久化会话 / 有状态 server #3089 #3203** —— 若用到有状态 MCP server 则必需。
+- **MCP 配置接口脱敏 #2667** —— 安全加固。
+- **子代理 token 用量流式上报 #2882** —— 计费/可观测。
+- **线程元数据过滤下推 SQL #2865（perf）** —— 列表性能。
+
+### P2 — 按需（看是否用到对应模型/渠道）
+- MiMo reasoning #3298（用小米模型才需要）
+- Discord 渠道增强 #2842（用 Discord 才需要）
+- Sandbox 下载文件接口 #3038、追踪命名 #3101、循环检测延迟告警 #2752
+
+### 前端（按业务价值）
+- **Replay 研究回放** —— 对"深研/写作"类产品体验提升明显，建议优先（需后端配合）。
+- **Prose 文本润色** —— 与写作工作台契合，建议评估接入。
+- **PPT 生成** —— 若有汇报/导出诉求再做。
+- **Landing 落地页** —— 仅当面向外部用户时考虑。
+
+### 暂不做
+- 多语言 i18n（本次明确排除）
+- 播客 / TTS（本次明确排除）
+
+---
+
+## 4. 建议执行节奏
+1. 先做 **P0 后端 4 项** + 跑全量测试，单独提交一个"上游稳定性回合"分支。
+2. 再做 **P1**，逐条 cherry-pick、逐条验证。
+3. 前端 **Replay / Prose** 立项评估（确认后端依赖），单独排期重写适配。
+4. 依赖升级随回合同步，离线包 (`wheelhouse` / `requirements-offline.txt`) 一并更新。

frontend-web/docs/浅红色UI规范/01-基础样式.md

@@ -0,0 +1,514 @@
+# 浅红色 UI 规范 · 一、基础样式
+
+> 返回 [规范目录](README.md)　|　本篇：色彩 · 字体 · 阴影 · 圆角 · 间距 · 语义状态色
+
+---
+
+## 1. 色彩
+
+### 1.1 标准色
+
+色彩体系分为**主色**与**辅色**两大类。
+
+- **主色**：渐红系（ZS-001）、渐蓝系（ZS-002），用于品牌表达与核心交互。
+- **辅色**：渐橙系（FS-001）、渐绿系（FS-002）、渐青系（FS-003）、中性灰系（FS-004），用于状态提示、数据可视化与文字 / 背景 / 分割线。
+
+每个色系按明度从浅到深编号（`-01` 最浅，数字越大越深），并附两种渐变色（`-14` 线性渐变、`-15` 径向渐变）。本主题为**浅色主题**：以白 / 浅灰作大面积背景，以深色作正文，红色为品牌强调主色。
+
+---
+
+#### 1.1.1 色系总览
+
+| 类别 | 色系 | 用途定位 | 代码前缀 |
+|------|------|----------|----------|
+| 主色 | 渐红系 | 品牌主色、强调操作、警示与错误 | ZS-001 |
+| 主色 | 渐蓝系 | 信息、链接、次级操作 | ZS-002 |
+| 辅色 | 渐橙系 | 警告、进行中、提示标签 | FS-001 |
+| 辅色 | 渐绿系 | 成功、在线、通过状态 | FS-002 |
+| 辅色 | 渐青系 | 数据高亮、图表、辅助信息 | FS-003 |
+| 辅色 | 中性灰系 | 背景、文字、图标、分割线 | FS-004 |
+
+> 每个色系内：`-01 ~ -03` 为**浅色**（用于大面积底色）；`-04 ~ -09` 为**中亮色**（用于标签、图表、提示等）；`-10` 及以后为**深色**（用于小面积按钮、图标等）；`-14 / -15` 为渐变色（用于特殊装饰性小面积底色）。
+
+---
+
+#### 1.1.2 主色 · 渐红系（ZS-001）
+
+品牌主色系。用于主操作按钮、重要强调、错误与危险告警。
+
+| 编号 | 色值 | 明度分组 | 说明 |
+|------|------|----------|------|
+| ZS-001 | `#CF1322` | 深色 | 品牌代表红（默认主色基准） |
+| ZS-001-01 | `#FEFAFA` | 浅色 | 极浅红，大面积底色 |
+| ZS-001-02 | `#FEF6F6` | 浅色 | 浅红底色 |
+| ZS-001-03 | `#FEEDED` | 浅色 | 浅红底色 / 错误背景 |
+| ZS-001-04 | `#FDDADC` | 中亮色 | — |
+| ZS-001-05 | `#FCB5B9` | 中亮色 | — |
+| ZS-001-06 | `#FA9196` | 中亮色 | — |
+| ZS-001-07 | `#F86C73` | 中亮色 | 浅红 Tag / 图表 |
+| ZS-001-08 | `#F74750` | 中亮色 | — |
+| ZS-001-09 | `#F5222D` | 中亮色 | **标准红**，主按钮 / 图标 |
+| ZS-001-10 | `#BC0D1E` | 深色 | 深红，Hover |
+| ZS-001-11 | `#A8071A` | 深色 | 深红，Active / Press |
+| ZS-001-12 | `#820014` | 深色 | 极深红 |
+| ZS-001-13 | `#5C0011` | 深色 | 最深红 |
+| ZS-001-14 | `#F5222D → #A8071A` | 线性渐变 | 装饰底色 |
+| ZS-001-15 | `#F86C73 → #F5222D` | 径向渐变 | 装饰底色 |
+
+---
+
+#### 1.1.3 主色 · 渐蓝系（ZS-002）
+
+用于信息提示、链接、次级按钮与图表。
+
+| 编号 | 色值 | 明度分组 | 说明 |
+|------|------|----------|------|
+| ZS-002 | `#0062D9` | 深色 | 蓝色代表色（基准） |
+| ZS-002-01 | `#F9FCFF` | 浅色 | 极浅蓝，大面积底色 |
+| ZS-002-02 | `#F4F9FF` | 浅色 | 浅蓝底色 |
+| ZS-002-03 | `#EAF4FF` | 浅色 | 浅蓝底色 / 信息背景 |
+| ZS-002-04 | `#D4E9FF` | 中亮色 | — |
+| ZS-002-05 | `#AAD2FF` | 中亮色 | — |
+| ZS-002-06 | `#80BCFF` | 中亮色 | — |
+| ZS-002-07 | `#55A6FE` | 中亮色 | 浅蓝 Tag / 图表 |
+| ZS-002-08 | `#2B8FFE` | 中亮色 | — |
+| ZS-002-09 | `#0079FE` | 中亮色 | **标准蓝**，链接 / 信息主色 |
+| ZS-002-10 | `#0056C6` | 深色 | 深蓝，Hover |
+| ZS-002-11 | `#004AB3` | 深色 | 深蓝，Active |
+| ZS-002-12 | `#00368C` | 深色 | 极深蓝 |
+| ZS-002-13 | `#002466` | 深色 | 最深蓝 |
+| ZS-002-14 | `#0079FE → #004AB3` | 线性渐变 | 装饰底色 |
+| ZS-002-15 | `#55A6FE → #0079FE` | 径向渐变 | 装饰底色 |
+
+---
+
+#### 1.1.4 辅色 · 渐橙系（FS-001）
+
+用于警告、进行中、待处理等中性偏提醒状态。
+
+| 编号 | 色值 | 明度分组 | 说明 |
+|------|------|----------|------|
+| FS-001 | `#D97B00` | 深色 | 橙色代表色（基准） |
+| FS-001-01 | `#FFFCF9` | 浅色 | 极浅橙，大面积底色 |
+| FS-001-02 | `#FFFAF4` | 浅色 | 浅橙底色 |
+| FS-001-03 | `#FFF6EA` | 浅色 | 浅橙底色 / 警告背景 |
+| FS-001-04 | `#FFEED4` | 中亮色 | — |
+| FS-001-05 | `#FFDDAA` | 中亮色 | — |
+| FS-001-06 | `#FFCC80` | 中亮色 | — |
+| FS-001-07 | `#FFBB55` | 中亮色 | 浅橙 Tag / 图表 |
+| FS-001-08 | `#FFAA2B` | 中亮色 | — |
+| FS-001-09 | `#FF9900` | 中亮色 | **标准橙**，警告主色 |
+| FS-001-10 | `#C66D00` | 深色 | 深橙，Hover |
+| FS-001-11 | `#B35F00` | 深色 | 深橙，Active |
+| FS-001-12 | `#8C4600` | 深色 | 极深橙 |
+| FS-001-13 | `#663000` | 深色 | 最深橙 |
+| FS-001-14 | `#FF9900 → #B35F00` | 线性渐变 | 装饰底色 |
+| FS-001-15 | `#FFBB55 → #FF9900` | 径向渐变 | 装饰底色 |
+
+---
+
+#### 1.1.5 辅色 · 渐绿系（FS-002）
+
+用于成功、在线、通过、已完成等正向状态。
+
+| 编号 | 色值 | 明度分组 | 说明 |
+|------|------|----------|------|
+| FS-002 | `#1EB07F` | 深色 | 绿色代表色（基准） |
+| FS-002-01 | `#FAFEFD` | 浅色 | 极浅绿，大面积底色 |
+| FS-002-02 | `#F6FDFB` | 浅色 | 浅绿底色 |
+| FS-002-03 | `#EEFCF7` | 浅色 | 浅绿底色 / 成功背景 |
+| FS-002-04 | `#DCF8EE` | 中亮色 | — |
+| FS-002-05 | `#BAF1DD` | 中亮色 | — |
+| FS-002-06 | `#97EBCD` | 中亮色 | — |
+| FS-002-07 | `#74E4BC` | 中亮色 | 浅绿 Tag / 图表 |
+| FS-002-08 | `#52DDAB` | 中亮色 | — |
+| FS-002-09 | `#2FD69A` | 中亮色 | **标准绿**，成功主色 |
+| FS-002-10 | `#189D72` | 深色 | 深绿，Hover |
+| FS-002-11 | `#118A65` | 深色 | 深绿，Active |
+| FS-002-12 | `#07634B` | 深色 | 极深绿 |
+| FS-002-13 | `#043D30` | 深色 | 最深绿 |
+| FS-002-14 | `#2FD69A → #118A65` | 线性渐变 | 装饰底色 |
+| FS-002-15 | `#74E4BC → #2FD69A` | 径向渐变 | 装饰底色 |
+
+---
+
+#### 1.1.6 辅色 · 渐青系（FS-003）
+
+用于数据高亮、图表配色、辅助信息标识。
+
+| 编号 | 色值 | 明度分组 | 说明 |
+|------|------|----------|------|
+| FS-003 | `#2F9ACC` | 深色 | 青色代表色（基准） |
+| FS-003-01 | `#FBFDFE` | 浅色 | 极浅青，大面积底色 |
+| FS-003-02 | `#F7FCFE` | 浅色 | 浅青底色 |
+| FS-003-03 | `#EFFAFE` | 浅色 | 浅青底色 |
+| FS-003-04 | `#E0F5FD` | 中亮色 | — |
+| FS-003-05 | `#C1EBFB` | 中亮色 | — |
+| FS-003-06 | `#A2E1F9` | 中亮色 | — |
+| FS-003-07 | `#83D7F7` | 中亮色 | 浅青 Tag / 图表 |
+| FS-003-08 | `#64CDF5` | 中亮色 | — |
+| FS-003-09 | `#45C3F3` | 中亮色 | **标准青**，数据高亮主色 |
+| FS-003-10 | `#2788B9` | 深色 | 深青，Hover |
+| FS-003-11 | `#1E76A6` | 深色 | 深青，Active |
+| FS-003-12 | `#115580` | 深色 | 极深青 |
+| FS-003-13 | `#0B3959` | 深色 | 最深青 |
+| FS-003-14 | `#45C3F3 → #1E76A6` | 线性渐变 | 装饰底色 |
+| FS-003-15 | `#83D7F7 → #45C3F3` | 径向渐变 | 装饰底色 |
+
+---
+
+#### 1.1.7 辅色 · 中性灰系（FS-004）
+
+承载页面背景、正文、备注文字、图标与分割线。浅色主题的核心承载色系。
+
+| 编号 | 色值 | 明度分组 | 说明 |
+|------|------|----------|------|
+| FS-004 | `#222222` | 深色 | 中性代表色（基准） |
+| FS-004-01 | `#FFFFFF` | 浅色 | 纯白，页面 / 容器背景、白色文字 |
+| FS-004-02 | `#FAFAFA` | 浅色 | 浅灰背景 |
+| FS-004-03 | `#F5F5F5` | 浅色 | 浅灰背景 / 分割区底 |
+| FS-004-04 | `#E8E8E8` | 中亮色 | 分割线 / 边框 |
+| FS-004-05 | `#DBDBDB` | 中亮色 | 边框 / 禁用底 |
+| FS-004-06 | `#C1C1C1` | 中亮色 | 禁用文字 / 占位符 |
+| FS-004-07 | `#A6A6A6` | 中亮色 | 备注文字 / 图标 |
+| FS-004-08 | `#7F7F7F` | 中亮色 | 次级文字 |
+| FS-004-09 | `#575757` | 中亮色 | 次要正文 |
+| FS-004-10 | `#3D3D3D` | 深色 | 正文加强 |
+
+> 灰系用途分层：`01 ~ 03` 背景 / 白色文字 / 分割线；`04 ~ 09` 备注文字及图标；`10` 与基准 `#222222` 用于正文。
+
+---
+
+#### 1.1.8 功能色（主色 / 字体色 / 辅色 / 背景色）
+
+从标准色系中提取，用于具体 UI 角色指定。
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 主色（Primary） | `#F5222D` | ZS-001-09 |
+| 主色 Hover | `#CF1322` | ZS-001 |
+| 主色 Active | `#A8071A` | ZS-001-11 |
+| 信息 / 链接色 | `#0079FE` | ZS-002-09 |
+| 成功色 | `#2FD69A` | FS-002-09 |
+| 警告色 | `#FF9900` | FS-001-09 |
+| 错误色 | `#F5222D` | ZS-001-09 |
+| 正文字体色 | `#222222` | FS-004 |
+| 次级字体色 | `#575757` | FS-004-09 |
+| 备注 / 占位字体色 | `#A6A6A6` | FS-004-07 |
+| 禁用字体色 | `#C1C1C1` | FS-004-06 |
+| 页面背景色 | `#FAFAFA` | FS-004-02 |
+| 容器背景色 | `#FFFFFF` | FS-004-01 |
+| 分割线 | `#E8E8E8` | FS-004-04 |
+
+---
+
+#### 1.1.9 小面积装饰色
+
+用于图标点缀、徽标、少量强调，不用于大面积背景。
+
+| 色值 | 来源 | 说明 |
+|------|------|------|
+| `#F5222D` | ZS-001-09 | 红色，危险 / 品牌徽标 |
+| `#0079FE` | ZS-002-09 | 蓝色，信息点缀 |
+| `#FF9900` | FS-001-09 | 橙色，提醒点缀 |
+| `#2FD69A` | FS-002-09 | 绿色，在线点 |
+| `#45C3F3` | FS-003-09 | 青色，数据点缀 |
+
+---
+
+#### 1.1.10 图表配色
+
+> **以 §25.1 图表通用色序为准**。本小节给出的是从主 / 辅色提取的强调型色序，适用于需要突出对比的少量序列；柱状 / 饼 / 环 / 面积等多分类图表的标准柔和色序见 [05-图表](05-图表.md)（§25）。
+
+**通用图表色序**（面积较大，如柱状图、折线图、饼图）：
+
+| 序号 | 色值 | 来源 |
+|------|------|------|
+| 1 | `#F5222D` | ZS-001-09 |
+| 2 | `#0079FE` | ZS-002-09 |
+| 3 | `#FF9900` | FS-001-09 |
+| 4 | `#2FD69A` | FS-002-09 |
+| 5 | `#45C3F3` | FS-003-09 |
+| 6 | `#FA9196` | ZS-001-06 |
+| 7 | `#55A6FE` | ZS-002-07 |
+| 8 | `#FFBB55` | FS-001-07 |
+
+**小面积图表色序**（面积较小，如散点、小徽章、迷你图）：
+
+| 序号 | 色值 | 来源 |
+|------|------|------|
+| 1 | `#F86C73` | ZS-001-07 |
+| 2 | `#55A6FE` | ZS-002-07 |
+| 3 | `#74E4BC` | FS-002-07 |
+| 4 | `#FFBB55` | FS-001-07 |
+| 5 | `#83D7F7` | FS-003-07 |
+| 6 | `#A6A6A6` | FS-004-07 |
+
+---
+
+#### 1.1.11 CSS Token 建议
+
+```css
+:root {
+  /* 主色 · 渐红系 ZS-001 */
+  --zs-001:    #CF1322;
+  --zs-001-01: #FEFAFA; --zs-001-02: #FEF6F6; --zs-001-03: #FEEDED;
+  --zs-001-04: #FDDADC; --zs-001-05: #FCB5B9; --zs-001-06: #FA9196;
+  --zs-001-07: #F86C73; --zs-001-08: #F74750; --zs-001-09: #F5222D;
+  --zs-001-10: #BC0D1E; --zs-001-11: #A8071A; --zs-001-12: #820014;
+  --zs-001-13: #5C0011;
+
+  /* 主色 · 渐蓝系 ZS-002 */
+  --zs-002:    #0062D9;
+  --zs-002-01: #F9FCFF; --zs-002-02: #F4F9FF; --zs-002-03: #EAF4FF;
+  --zs-002-04: #D4E9FF; --zs-002-05: #AAD2FF; --zs-002-06: #80BCFF;
+  --zs-002-07: #55A6FE; --zs-002-08: #2B8FFE; --zs-002-09: #0079FE;
+  --zs-002-10: #0056C6; --zs-002-11: #004AB3; --zs-002-12: #00368C;
+  --zs-002-13: #002466;
+
+  /* 辅色 · 渐橙系 FS-001 */
+  --fs-001:    #D97B00;
+  --fs-001-01: #FFFCF9; --fs-001-02: #FFFAF4; --fs-001-03: #FFF6EA;
+  --fs-001-04: #FFEED4; --fs-001-05: #FFDDAA; --fs-001-06: #FFCC80;
+  --fs-001-07: #FFBB55; --fs-001-08: #FFAA2B; --fs-001-09: #FF9900;
+  --fs-001-10: #C66D00; --fs-001-11: #B35F00; --fs-001-12: #8C4600;
+  --fs-001-13: #663000;
+
+  /* 辅色 · 渐绿系 FS-002 */
+  --fs-002:    #1EB07F;
+  --fs-002-01: #FAFEFD; --fs-002-02: #F6FDFB; --fs-002-03: #EEFCF7;
+  --fs-002-04: #DCF8EE; --fs-002-05: #BAF1DD; --fs-002-06: #97EBCD;
+  --fs-002-07: #74E4BC; --fs-002-08: #52DDAB; --fs-002-09: #2FD69A;
+  --fs-002-10: #189D72; --fs-002-11: #118A65; --fs-002-12: #07634B;
+  --fs-002-13: #043D30;
+
+  /* 辅色 · 渐青系 FS-003 */
+  --fs-003:    #2F9ACC;
+  --fs-003-01: #FBFDFE; --fs-003-02: #F7FCFE; --fs-003-03: #EFFAFE;
+  --fs-003-04: #E0F5FD; --fs-003-05: #C1EBFB; --fs-003-06: #A2E1F9;
+  --fs-003-07: #83D7F7; --fs-003-08: #64CDF5; --fs-003-09: #45C3F3;
+  --fs-003-10: #2788B9; --fs-003-11: #1E76A6; --fs-003-12: #115580;
+  --fs-003-13: #0B3959;
+
+  /* 辅色 · 中性灰系 FS-004 */
+  --fs-004:    #222222;
+  --fs-004-01: #FFFFFF; --fs-004-02: #FAFAFA; --fs-004-03: #F5F5F5;
+  --fs-004-04: #E8E8E8; --fs-004-05: #DBDBDB; --fs-004-06: #C1C1C1;
+  --fs-004-07: #A6A6A6; --fs-004-08: #7F7F7F; --fs-004-09: #575757;
+  --fs-004-10: #3D3D3D;
+
+  /* 功能色（语义别名） */
+  --color-primary:        var(--zs-001-09); /* #F5222D */
+  --color-primary-hover:  var(--zs-001);    /* #CF1322 */
+  --color-primary-active: var(--zs-001-11); /* #A8071A */
+  --color-link:           var(--zs-002-09); /* #0079FE */
+  --color-success:        var(--fs-002-09); /* #2FD69A */
+  --color-warning:        var(--fs-001-09); /* #FF9900 */
+  --color-error:          var(--zs-001-09); /* #F5222D */
+  --color-text:           var(--fs-004);    /* #222222 */
+  --color-text-secondary: var(--fs-004-09); /* #575757 */
+  --color-text-tertiary:  var(--fs-004-07); /* #A6A6A6 */
+  --color-text-disabled:  var(--fs-004-06); /* #C1C1C1 */
+  --color-bg-page:        var(--fs-004-02); /* #FAFAFA */
+  --color-bg-container:   var(--fs-004-01); /* #FFFFFF */
+  --color-border:         var(--fs-004-04); /* #E8E8E8 */
+}
+```
+
+---
+
+## 2. 字体
+
+字体规范分**大屏页面**与**后台系统**两套，分别对应可视化大屏与管理后台两类场景。
+
+### 2.1 大屏页面字体规范
+
+#### 2.1.1 中文字体：Noto Sans S Chinese
+
+| 样式 | 使用场景 |
+|------|----------|
+| 24px Bold | 一级标题 |
+| 24px Medium | 次要一级标题 |
+| 22px Medium | 二级标题 |
+| 22px Regular | 正文 |
+| 20px Regular | 排版空间有限的正文 |
+
+#### 2.1.2 数字字体：D-DIN
+
+| 样式 | 使用场景 |
+|------|----------|
+| 32px Bold | 重要数据展示 |
+| 32px Regular | 普通数据展示 |
+| 26px Bold | 常规数据展示 |
+| 26px Regular | 常规数据展示 |
+
+#### 2.1.3 特殊数字：DS-Digital
+
+| 样式 | 使用场景 |
+|------|----------|
+| 50px Bold | 大屏主数据展示 |
+
+#### 2.1.4 表格数字：Arial
+
+| 样式 | 使用场景 |
+|------|----------|
+| 20px Regular | 表格横纵轴数字 |
+
+---
+
+### 2.2 后台系统字体规范
+
+#### 2.2.1 中文字体：Noto Sans S Chinese
+
+| 样式 | 使用场景 |
+|------|----------|
+| 18px Bold | 导航、一级标题 |
+| 18px Medium | 次要一级标题 |
+| 16px Bold | 二级标题 |
+| 16px Medium | 次要二级标题 |
+| 16px Regular | 正文、按钮内部文字等 |
+| 16px Light | 次要正文 |
+
+#### 2.2.2 数字字体：D-DIN
+
+| 样式 | 使用场景 |
+|------|----------|
+| 26px Bold | 重要数据展示 |
+| 26px Regular | 普通数据展示 |
+| 24px Bold | 常规数据展示（小） |
+| 24px Regular | 常规数据展示（小） |
+
+#### 2.2.3 LOGO 字体：DOUYUFont
+
+| 样式 | 使用场景 |
+|------|----------|
+| 20px 文字样式 | 页面顶部系统名称 |
+
+#### 2.2.4 表格数字：Arial
+
+| 样式 | 使用场景 |
+|------|----------|
+| 16px Regular | 表格横纵轴数字 |
+| 14px Regular | 表格横纵轴的数字（空间有限） |
+
+---
+
+## 3. 阴影
+
+> 浅色主题采用**中性投影**（基于 FS-004 `#222222`）营造层级，避免使用彩色外发光。卡片以纯白 `#FFFFFF` 浮于浅灰页面背景 `#FAFAFA` 之上，靠投影与边框区分。
+
+### 3.1 容器与卡片配色
+
+#### 3.1.1 卡片（标题 + 操作）
+
+白底卡片，标题在左、操作区在右（文字操作或图标操作）。
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 卡片背景 | `#FFFFFF` | FS-004-01 |
+| 卡片边框 | `#E8E8E8` | FS-004-04 |
+| 卡片阴影 | `0 2px 8px rgba(34, 34, 34, 0.08)` | 基于 FS-004 中性投影 |
+| 标题文字（16px Bold） | `#222222` | FS-004（正文色） |
+| 操作按钮文字 | `#F5222D` | ZS-001-09（主色红，链接型操作） |
+| 次级操作图标（✏️ / ⋯） | `#A6A6A6` | FS-004-07（备注图标色） |
+
+#### 3.1.2 卡片新增（占位卡片）
+
+虚线描边的"新增入口"卡片，用于引导用户添加内容。
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 卡片背景 | `#FFFFFF` | FS-004-01 |
+| 虚线边框 | `#DBDBDB` | FS-004-05 |
+| 加号图标 | `#A6A6A6` | FS-004-07 |
+| Hover 边框 | `#F5222D` | ZS-001-09（悬停时提示可点击） |
+| Hover 加号 | `#F5222D` | ZS-001-09 |
+
+#### 3.1.3 阴影投影规则
+
+| 层级 | 阴影值 | 使用场景 |
+|------|--------|----------|
+| 一级阴影（卡片浮起） | `0 2px 8px rgba(34, 34, 34, 0.08)` | 普通卡片 |
+| 二级阴影（hover / 强调） | `0 4px 16px rgba(34, 34, 34, 0.12)` | 卡片 hover、悬浮按钮、弹出层 |
+| 三级阴影（弹窗 / Modal） | `0 8px 32px rgba(34, 34, 34, 0.16)` | Dialog、Drawer |
+
+---
+
+## 4. 圆角
+
+### 4.1 圆角统一规范
+
+| 元素 | 圆角值 | 说明 |
+|------|--------|------|
+| 按钮 | `2px` | 所有按钮（主 / 次要 / 默认 / 文本）统一使用 |
+| 卡片 | `4px` | 内容卡片、标题+操作卡片、卡片新增占位 |
+| 页面分栏框 | `4px` | 外层容器、分栏区域 |
+| 输入框 / 选择器 | `2px` | 与按钮一致，保持表单内对齐 |
+| Tag / Badge | `2px` | 与按钮一致 |
+| Modal / Drawer | `4px` | 与卡片一致 |
+
+---
+
+## 6. 间距
+
+> 全站以 `8px (0.5rem)` 为对照基准单位，划分"密 / 疏"两个层次。所有间距取值均来自下列阶梯，禁止使用非阶梯值（如 5px、13px）。
+
+### 6.1 间距阶梯
+
+| 阶 | px | rem | 分组 | 典型场景 |
+|----|------|--------|------|----------|
+| 1 | `4px` | `0.25rem` | 密 | 图标与文字间距、Tag 内边距、紧凑徽标 |
+| 2 | `8px` | `0.5rem` | 密 | 行内元素相邻、按钮组间距、表单 label 与控件 |
+| 3 | `12px` | `0.75rem` | 密 | 表单项垂直间距、列表项内边距 |
+| 4 | `16px` | `1rem` | 密 | 卡片内容内边距、模块内分隔 |
+| 5 | `24px` | `1.5rem` | 疏 | 模块之间、Section 内边距 |
+| 6 | `32px` | `2rem` | 疏 | 卡片之间、表单组之间 |
+| 7 | `40px` | `2.5rem` | 疏 | 主区块之间、页面 Header / Footer 内边距 |
+| 8 | `56px` | `3.5rem` | 疏 | 页面段落级隔断、Banner 区域 |
+
+> "密"对应紧凑信息密度（表格、表单、卡片内部）；"疏"对应视觉呼吸（模块之间、页面整体留白）。**16px 是"密"的上限，24px 是"疏"的下限**，两者之间不应再插入自定义值。
+
+### 6.2 使用原则
+
+- **同层级一致**：同一布局层级内的间距必须使用同一阶值；多种取值会破坏节奏。
+- **就近取阶**：相邻区块的间距尽量从相邻阶梯取值（如 `16px → 24px`），跨越过多阶（如 `8px → 56px`）会让视觉断裂。
+- **密疏不混用**：一个组件内部全部用"密"，外部用"疏"，避免内 / 外间距颠倒。
+- **优先 8 的倍数**：除最小阶 `4px` 外，所有阶皆为 8 的倍数，方便 4/8 网格对齐。
+- **响应式按比例衰减**：移动端可整体降一阶（如 `24px → 16px`），但仍在阶梯内。
+
+### 6.3 CSS Token 建议
+
+```css
+:root {
+  --spacing-1: 4px;   /* 0.25rem */
+  --spacing-2: 8px;   /* 0.5rem  */
+  --spacing-3: 12px;  /* 0.75rem */
+  --spacing-4: 16px;  /* 1rem    */
+  --spacing-5: 24px;  /* 1.5rem  */
+  --spacing-6: 32px;  /* 2rem    */
+  --spacing-7: 40px;  /* 2.5rem  */
+  --spacing-8: 56px;  /* 3.5rem  */
+}
+```
+
+---
+
+## 20. 语义状态色（统一约定）
+
+> 进度、状态标签、表格状态、时间轴等大量组件共用同一套语义色。后续章节直接引用本表。
+
+| 语义 | 文字色 | 浅底背景 | 实填背景 | 来源 |
+|------|--------|----------|----------|------|
+| 成功 / 完成（绿） | `#189D72` (FS-002-10) | `#EEFCF7` (FS-002-03) | `#2FD69A` (FS-002-09) | 渐绿系 |
+| 警告 / 进行中（橙） | `#FF9900` (FS-001-09) | `#FFF6EA` (FS-001-03) | `#FF9900` (FS-001-09) | 渐橙系 |
+| 错误 / 失败（红） | `#F5222D` (ZS-001-09) | `#FEEDED` (ZS-001-03) | `#F5222D` (ZS-001-09) | 渐红系 |
+| 信息 / 等待（蓝） | `#0079FE` (ZS-002-09) | `#EAF4FF` (ZS-002-03) | `#0079FE` (ZS-002-09) | 渐蓝系 |
+| 待更新（青） | `#45C3F3` (FS-003-09) | `#EFFAFE` (FS-003-03) | `#45C3F3` (FS-003-09) | 渐青系 |
+| 未开始 / 中性（灰） | `#7F7F7F` (FS-004-08) | `#F5F5F5` (FS-004-03) | `#A6A6A6` (FS-004-07) | 中性灰系 |
+
+---
+
+
+---
+
+> 返回 [规范目录](README.md)

frontend-web/docs/浅红色UI规范/02-按钮与表单.md

@@ -0,0 +1,314 @@
+# 浅红色 UI 规范 · 二、按钮与表单输入
+
+> 返回 [规范目录](README.md)　|　本篇：按钮 · 表单 · 输入框 · 选择按钮 · 标签输入框 · 上传
+
+---
+
+## 5. 按钮
+
+> 全部圆角 `2px`，文字字号 `14px`，字体 Noto Sans S Chinese Regular。配色取自 ZS-001 主色红与 FS-004 中性灰。
+
+### 5.1 按钮尺寸
+
+| 规格 | 高度 | 内边距 | 使用场景 |
+|------|------|--------|----------|
+| 小 | `24px` | `0 8px` | 空间小的板块内部，如表格中、卡片标题等 |
+| 正常 | `32px` | `0 14px` | 默认尺寸，所有常用按钮 |
+
+### 5.2 按钮类型与配色
+
+#### 5.2.1 主按钮（Primary）
+
+> 一个操作区域只能有一个主按钮。
+
+| 状态 | 背景 | 边框 | 文字 |
+|------|------|------|------|
+| 默认 | `#F5222D` (ZS-001-09) | — | `#FFFFFF` |
+| Hover | `#CF1322` (ZS-001) | — | `#FFFFFF` |
+| Active | `#A8071A` (ZS-001-11) | — | `#FFFFFF` |
+| 失效 | `#A6A6A6` (FS-004-07) | — | `#FFFFFF` |
+
+#### 5.2.2 次要按钮（Secondary / Outline-Primary）
+
+重要度低于主按钮、高于默认按钮。红色描边 + 红色文字。
+
+| 状态 | 背景 | 边框 | 文字 |
+|------|------|------|------|
+| 默认 | `#FFFFFF` | `#F5222D` (ZS-001-09) | `#F5222D` (ZS-001-09) |
+| Hover | `#FEEDED` (ZS-001-03) | `#CF1322` (ZS-001) | `#CF1322` (ZS-001) |
+| Active | `#FDDADC` (ZS-001-04) | `#A8071A` (ZS-001-11) | `#A8071A` (ZS-001-11) |
+| 失效 | `#FFFFFF` | `#FCB5B9` (ZS-001-05) | `#FCB5B9` (ZS-001-05) |
+
+#### 5.2.3 默认按钮（Default）
+
+用于"取消 / 返回"等次要操作，与主按钮成对出现时主按钮在右。中性描边。
+
+| 状态 | 背景 | 边框 | 文字 |
+|------|------|------|------|
+| 默认 | `#FFFFFF` | `#DBDBDB` (FS-004-05) | `#222222` (FS-004) |
+| Hover | `#FAFAFA` (FS-004-02) | `#F5222D` (ZS-001-09) | `#F5222D` (ZS-001-09) |
+| Active | `#F5F5F5` (FS-004-03) | `#CF1322` (ZS-001) | `#CF1322` (ZS-001) |
+| 禁用 | `#F5F5F5` (FS-004-03) | `#E8E8E8` (FS-004-04) | `#C1C1C1` (FS-004-06) |
+
+#### 5.2.4 文本按钮（Text）
+
+用于表格操作、文件下载等。无背景与边框，靠文字色识别。
+
+| 状态 | 文字 | 装饰 |
+|------|------|------|
+| 默认 | `#F5222D` (ZS-001-09) | 无下划线 |
+| Hover | `#CF1322` (ZS-001) | 显示下划线（与文字同色） |
+| Active | `#A8071A` (ZS-001-11) | 下划线 |
+| 失效 | `#C1C1C1` (FS-004-06) | 无装饰 |
+
+#### 5.2.5 图标按钮（Icon-only）
+
+用于增强辨识度或节省空间。仅图标，无文字。
+
+| 变体 | 背景 | 边框 | 图标颜色 |
+|------|------|------|----------|
+| 描边（默认） | `#FFFFFF` | `#DBDBDB` (FS-004-05) | `#575757` (FS-004-09) |
+| 描边 Hover | `#FAFAFA` | `#F5222D` (ZS-001-09) | `#F5222D` (ZS-001-09) |
+| 主色（填充） | `#F5222D` (ZS-001-09) | — | `#FFFFFF` |
+| 主色 Hover | `#CF1322` (ZS-001) | — | `#FFFFFF` |
+| 浅色（弱填充） | `#FEEDED` (ZS-001-03) | — | `#F5222D` (ZS-001-09) |
+
+### 5.3 按钮组合
+
+#### 5.3.1 文字 + 下拉按钮（含 ⌄）
+
+| 形态 | 配色规则 |
+|------|----------|
+| 默认（Outline） | 沿用 §5.2.3 默认按钮，箭头 ⌄ 与文字同色 `#222222` |
+| 主色（Filled） | 沿用 §5.2.1 主按钮，箭头 ⌄ 同步白色 `#FFFFFF` |
+
+#### 5.3.2 图标 + 文字按钮（如 `+ 正常`）
+
+| 形态 | 配色规则 |
+|------|----------|
+| 默认（Outline） | 沿用 §5.2.3，左侧图标颜色与文字一致 `#222222` |
+| 主色（Filled） | 沿用 §5.2.1，左侧图标与文字一致 `#FFFFFF` |
+
+#### 5.3.3 文本按钮 + 图标（"更多 »"、"展开 ⌄"、"下一页 »"、"« 上一页"、"收起 ^"）
+
+| 角色 | 色值 |
+|------|------|
+| 文字 + 图标（默认） | `#F5222D` (ZS-001-09) |
+| 文字 + 图标（Hover） | `#CF1322` (ZS-001) |
+| 失效 | `#C1C1C1` (FS-004-06) |
+
+> 图标可在文字前或后；多个文本按钮排成一行时，间距 `16px`，无分隔符。
+
+#### 5.3.4 主按钮 + 默认按钮组合（如"确定 / 取消 / 返回"）
+
+- **排列顺序**：默认按钮在左，主按钮在右（最右侧为主操作）
+- **按钮间距**：`8px`
+- **示例**：`[ 返回 ] [ 取消 ] [ 确定 ]`
+- **配色**：主按钮沿用 §5.2.1，其余沿用 §5.2.3
+
+### 5.4 其他按钮
+
+#### 5.4.1 悬浮状态（Floating）
+
+用于 Banner / 登录 / 视觉冲击强等展示场景。配色与主按钮一致，叠加阴影抬升。
+
+| 状态 | 阴影 |
+|------|------|
+| 默认 | `0 2px 8px rgba(34, 34, 34, 0.08)`（§3.1.3 一级阴影） |
+| Hover | `0 4px 16px rgba(34, 34, 34, 0.12)`（§3.1.3 二级阴影） |
+| Active | 阴影消失，按下感 |
+
+#### 5.4.2 加载中（Loading）
+
+用于异步操作等待反馈。点击瞬间将按钮锁定，文字前显示旋转图标。
+
+| 角色 | 色值 |
+|------|------|
+| 背景 | `#F5222D` (ZS-001-09) |
+| 文字 | `#FFFFFF` |
+| 加载图标 | `#FFFFFF`，旋转动画 `1.2s linear infinite` |
+| 不可点击 | 鼠标 `cursor: not-allowed` |
+
+> 与失效态的区别：失效是"不可操作"，加载是"操作进行中"——保留品牌主色，只是不可再次触发。
+
+---
+
+## 12. 表单（Form）
+
+> 页面级表单可参照弹窗表单，**操作按钮置于左下角**。容器为白底卡片，标题下叠 `1px solid #E8E8E8` 分割线。
+
+### 12.1 基础表单结构
+
+| 元素 | 规格 / 配色 |
+|------|-------------|
+| 容器背景 | `#FFFFFF` (FS-004-01)，圆角 `4px` |
+| 表单标题 | `16px Bold`，`#222222` (FS-004)，下叠 `1px solid #E8E8E8` |
+| 字段标签（label） | `14px Regular`，`#575757` (FS-004-09)，左对齐 |
+| 字段垂直间距 | `--spacing-3` (12px) |
+| 输入控件 | 见 §13 输入框 |
+| 操作按钮区 | 置于左下角，主按钮 + 默认按钮（§5.3.4），间距 `--spacing-2` (8px) |
+
+### 12.2 开关（Switch）
+
+| 状态 | 轨道背景 | 滑块 | 文字 |
+|------|----------|------|------|
+| 开（ON） | `#F5222D` (ZS-001-09) | `#FFFFFF` 圆点 | "开" `#FFFFFF` |
+| 关（OFF） | `#DBDBDB` (FS-004-05) | `#FFFFFF` 圆点 | "关" `#A6A6A6` (FS-004-07) |
+| 禁用 | `#E8E8E8` (FS-004-04) | `#FFFFFF` | `#C1C1C1` |
+
+- 轨道高 `20px`，圆角全圆；切换过渡 `transform 160ms ease-out`
+
+### 12.3 表格内报错（Table 报错）
+
+行内可编辑表格的校验错误态。
+
+| 元素 | 配色 |
+|------|------|
+| 表头背景 | `#FEEDED` (ZS-001-03) |
+| 表头文字 | `#222222` (FS-004)，`14px Medium` |
+| 行（默认） | 背景 `#FFFFFF`，底边 `1px solid #F5F5F5` (FS-004-03) |
+| 行（hover / 选中） | 背景 `#FEF6F6` (ZS-001-02) |
+| 正文文字 | `#222222` (FS-004) |
+| 错误输入框边框 | `1px solid #F5222D` (ZS-001-09) |
+| 单位后缀（如 `M`） | addon 背景 `#FAFAFA`，边框 `#DBDBDB`，文字 `#575757` |
+| 错误提示气泡 | 背景 `#F5222D`，文字 `#FFFFFF` `12px`，圆角 `2px`，带向上箭头，定位于出错输入框下方 |
+| 复选框（选中） | 勾选填充 `#F5222D`，对勾 `#FFFFFF` |
+
+---
+
+## 13. 输入框（Input）
+
+> 字号 `16px`，高度 `32px`，圆角 `2px`，内边距 `0 12px`，背景 `#FFFFFF`。
+
+### 13.1 基础状态
+
+| 状态 | 边框 | 背景 | 文字 / 占位符 |
+|------|------|------|--------------|
+| 未填（默认） | `1px solid #DBDBDB` (FS-004-05) | `#FFFFFF` | 占位符 `#A6A6A6` (FS-004-07) |
+| 聚焦（Focus） | `1px solid #F5222D` (ZS-001-09) | `#FFFFFF` | 文字 `#222222` |
+| 已填 | `1px solid #DBDBDB` | `#FFFFFF` | 文字 `#222222` (FS-004) |
+| 未填 · 禁用 | `1px solid #E8E8E8` (FS-004-04) | `#F5F5F5` (FS-004-03) | 占位符 `#C1C1C1` (FS-004-06)，`cursor: not-allowed` |
+| 已填 · 禁用 | `1px solid #E8E8E8` | `#F5F5F5` | 文字 `#A6A6A6` |
+| 错误（Error） | `1px solid #F5222D` | `#FFFFFF` | 文字 `#222222`，下方红色提示文字 `12px #F5222D` |
+
+### 13.2 带操作 / 特殊输入框
+
+| 类型 | 说明 | 配色 |
+|------|------|------|
+| 未填 / 已填 · 操作 | 尾部带操作图标（如 ⚙） | 图标 `#A6A6A6`，hover `#F5222D` |
+| 密码 · 不可见 | 尾部带可见性切换 👁 | 图标 `#A6A6A6`，点击切换明 / 密文 |
+| 前置标签 | 头部下拉（如 `http:// ▾`） | addon 背景 `#FAFAFA`，边框 `#DBDBDB`，文字 `#575757` |
+| 后置标签 | 尾部下拉（如 `.com ▾`） | 同前置标签 |
+| 前后置标签 | 头尾各一段 addon | 同上；输入区与 addon 共用一条外边框 |
+
+---
+
+## 14. 选择按钮（单选 / 多选式）
+
+> 以按钮形态替代传统单选 / 复选，提升点击区域与辨识度。每组提供三种"已选"填充强度，可按对比需要选用；布局分**相连**（segmented）与**分离**两种。
+
+### 14.1 选择按钮（基础）
+
+| 状态 / 变体 | 背景 | 边框 | 文字 |
+|------|------|------|------|
+| 未选 | `#FFFFFF` | `1px solid #DBDBDB` (FS-004-05) | `#222222` (FS-004) |
+| 已选 · 描边 | `#FFFFFF` | `1px solid #F5222D` (ZS-001-09) | `#F5222D` (ZS-001-09) |
+| 已选 · 浅填 | `#FEEDED` (ZS-001-03) | `1px solid #FCB5B9` (ZS-001-05) | `#F5222D` (ZS-001-09) |
+| 已选 · 实填 | `#F5222D` (ZS-001-09) | — | `#FFFFFF` |
+| 禁用 | `#F5F5F5` (FS-004-03) | `1px solid #E8E8E8` | `#C1C1C1` (FS-004-06) |
+
+- 高度 `32px`，内边距 `0 14px`，圆角 `2px`，字号 `14px`
+- **相连布局**：按钮紧贴，仅最外两端圆角，相邻共用边框
+- **分离布局**：按钮间距 `--spacing-2` (8px)，各自独立圆角
+
+### 14.2 选择按钮（带统计）
+
+在文案后附计数，如 `已选(230)`。配色完全沿用 §14.1，计数文字与主文字同色（实填态为 `#FFFFFF`）。
+
+### 14.3 按钮式页签（带图标）
+
+文案前带图标（如 `田`），用于视图 / 模式切换。
+
+| 状态 / 变体 | 背景 | 边框 | 图标 + 文字 |
+|------|------|------|-------------|
+| 正常（未激活） | `#FFFFFF` | `1px solid #DBDBDB` | `#222222` |
+| 激活 · 描边 | `#FFFFFF` | `1px solid #F5222D` | `#F5222D` |
+| 激活 · 实填 | `#F5222D` (ZS-001-09) | — | `#FFFFFF` |
+
+- 图标与文字间距 `--spacing-1` (4px)，其余规格同 §14.1
+
+---
+
+## 15. 标签输入框（Tag Input）
+
+> 在输入框内以"标签 + 自由输入"混合录入，支持单行 / 多行，含字数统计。
+
+### 15.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 容器边框 | `1px solid #DBDBDB` (FS-004-05)，圆角 `2px` |
+| 聚焦边框 | `1px solid #F5222D` (ZS-001-09) |
+| 容器背景 | `#FFFFFF` |
+| 内边距 | `--spacing-2` (8px) |
+| 标签与标签间距 | `--spacing-1` (4px) |
+| 右下角支持拖拽缩放（多行） | `resize: vertical` |
+
+### 15.2 标签（Tag）配色
+
+| 元素 | 色值 | 来源 |
+|------|------|------|
+| 标签背景 | `#F5F5F5` (FS-004-03) | — |
+| 标签文字 | `#575757` (FS-004-09) | — |
+| 关闭图标 `×` | `#A6A6A6` (FS-004-07) | hover `#F5222D` |
+| 占位符（请输入） | `#A6A6A6` (FS-004-07) | — |
+| 字数统计（如 `2/100`） | `#A6A6A6` (FS-004-07) | 超限时变 `#F5222D` |
+
+> 折叠多标签时可用 `+N` 形式聚合（如 `+1 ×`），样式同普通标签。
+
+---
+
+## 16. 上传（Upload）
+
+> 含单文件、批量上传、拖拽上传三种形态。操作按钮中"开始上传 / 上传"为主按钮，"取消"为默认按钮。
+
+### 16.1 上传触发器
+
+| 形态 | 配色 |
+|------|------|
+| 上传按钮（⬆ 上传文件） | 默认按钮（§5.2.3），含上传图标 |
+| 选择文件输入 | 只读输入框（§13）+ 右侧"选择文件"默认按钮 |
+| 提示文字 | `12px Regular`，`#A6A6A6` (FS-004-07)，如"支持 DOCX/ZIP/PDF，文件大小不超过 2MB" |
+| 示例文件链接（下载 / 查看示例文件） | 文本按钮 `#F5222D` (ZS-001-09)，hover `#CF1322` |
+
+### 16.2 拖拽区（Drop Zone）
+
+| 属性 | 取值 |
+|------|------|
+| 背景 | `#FAFAFA` (FS-004-02) |
+| 边框 | `1px dashed #DBDBDB` (FS-004-05) |
+| 拖入高亮 | 边框 `1px dashed #F5222D` (ZS-001-09)，背景 `#FEF6F6` (ZS-001-02) |
+| 提示文字（释放鼠标） | `#A6A6A6` (FS-004-07) |
+
+### 16.3 文件列表与状态
+
+列表表头：文件名 / 大小 / 状态 / 操作。各状态配色：
+
+| 状态 | 图标 | 文字色 |
+|------|------|--------|
+| 上传成功 | ✓ 圆形，`#2FD69A` (FS-002-09) | `#189D72` (FS-002-10) |
+| 文件格式有误 / 失败 | ❗ 圆形，`#F5222D` (ZS-001-09) | `#F5222D` |
+| 上传中（如 上传 40%） | ⟳ 旋转，`#F5222D` (ZS-001-09) | `#575757` (FS-004-09) |
+| 待上传 | 🕐 时钟，`#A6A6A6` (FS-004-07) | `#A6A6A6` |
+| 操作列「删除」 | — | 文本按钮 `#A6A6A6`，hover `#F5222D` |
+
+### 16.4 底部操作
+
+`[ 取消 ]（默认按钮） [ 开始上传 ]（主按钮 #F5222D）`，间距 `--spacing-2` (8px)，右对齐。
+
+---
+
+
+---
+
+> 返回 [规范目录](README.md)

frontend-web/docs/浅红色UI规范/03-导航.md

@@ -0,0 +1,495 @@
+# 浅红色 UI 规范 · 三、导航
+
+> 返回 [规范目录](README.md)　|　本篇：导航组件 · 面包屑 · 页头与分页 · 步骤条 · 页签与锚点
+
+---
+
+## 7. 导航组件
+
+> 适用于"后台 / 控制台"类浅红主题界面。整体结构 = 顶部导航（红底）+ 二级导航（白底）+ 左侧分级菜单 + 多级下拉。颜色取自 ZS-001 主色红与 FS-004 中性灰。
+
+### 7.1 顶部导航（Header · 红底）
+
+#### 7.1.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 高度 | `56px` |
+| 左右 padding | `--spacing-4` (16px) |
+| 背景 | `linear-gradient(90deg, #A8071A 0%, #CF1322 100%)`（ZS-001-11 → ZS-001） |
+| LOGO 区切角装饰 | 叠深红斜切块 `#A8071A` (ZS-001-11)，`clip-path` 斜边 |
+| 底边 | 无（与二级导航白底直接相接） |
+| 文字基线 | `Noto Sans S Chinese`，垂直居中 |
+
+#### 7.1.2 系统标题（LOGO + ******系统）
+
+- 字号 `20px Bold`，颜色 `#FFFFFF`，字体 `DOUYUFont` 或 Noto Sans Medium
+- LOGO 图标 `#FFFFFF`，置于左侧切角块上
+
+#### 7.1.3 一级导航（中部主导航，红底白字）
+
+| 状态 | 文字 | 背景 / 装饰 |
+|------|------|------------|
+| 默认 | `#FFFFFF` | `transparent` |
+| Hover | `#FFFFFF` | 背景 `rgba(255, 255, 255, 0.12)` |
+| 激活 | `#FFFFFF` | 底部 `2px solid #FFFFFF` 高亮线，背景 `rgba(255, 255, 255, 0.16)` |
+
+- 字号 `16px Medium`，项间距 `--spacing-5` (24px)
+
+#### 7.1.4 右侧工具区（图标 / 用户 / 退出）
+
+| 元素 | 字号/尺寸 | 颜色 |
+|------|----------|------|
+| 工具图标（消息 / 通知等） | `16px` | `#FFFFFF`，hover `rgba(255,255,255,0.7)` |
+| 用户名（如"李向前"） | `14px Regular` | `#FFFFFF` |
+| 用户头像 | `28px` 圆形 | — |
+| 退出图标 | `16px` | `#FFFFFF` |
+
+- 元素间距 `--spacing-3` (12px)，整体右 padding `--spacing-4` (16px)
+
+#### 7.1.5 用户下拉菜单（右上角）
+
+白底面板，规格同 §7.4 下拉面板。
+
+| 状态 | 背景 | 文字 / 图标 |
+|------|------|-------------|
+| 默认 | `transparent` | `#575757` (FS-004-09) |
+| Hover / 激活 | `#FEEDED` (ZS-001-03) | `#F5222D` (ZS-001-09) |
+
+> 项示例：用户中心 / 修改密码 / 退出；每项左侧带 16px 图标，图标色与文字同步。
+
+### 7.2 二级导航（白底 Tab 行）
+
+紧贴顶部导航下方的白底标签行。
+
+#### 7.2.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 高度 | `48px` |
+| 背景 | `#FFFFFF` (FS-004-01) |
+| 底边 | `border-bottom: 1px solid #E8E8E8` (FS-004-04) |
+| 项间距 | `--spacing-6` (32px) |
+| 字号 | `16px Medium` |
+
+#### 7.2.2 状态配色
+
+| 状态 | 文字 | 下划线 / 装饰 |
+|------|------|--------------|
+| 默认 | `#222222` (FS-004) | 无 |
+| Hover | `#F5222D` (ZS-001-09) | 无 |
+| 激活 | `#F5222D` (ZS-001-09) | 底部 `2px solid #F5222D`，含下拉箭头 `▾` 同色 |
+| 失效 | `#C1C1C1` (FS-004-06) | 无 |
+
+### 7.3 侧边栏（分级菜单）
+
+#### 7.3.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 宽度 | `200px`（展开）/ `64px`（折叠仅图标） |
+| 背景 | `#FFFFFF` (FS-004-01) |
+| 右边界 | `border-right: 1px solid #E8E8E8` (FS-004-04) |
+| 项高度 | `40px` |
+| 项左 padding | 二级 `--spacing-4` (16px)；三级 `--spacing-6` (32px) |
+| 字号 | `16px Regular`（二级）/ `14px Regular`（三级） |
+
+#### 7.3.2 二级菜单项配色
+
+| 状态 | 背景 | 文字 | 图标 | 左侧指示条 |
+|------|------|------|------|-----------|
+| 默认 | `transparent` | `#222222` (FS-004) | `#A6A6A6` (FS-004-07) | 无 |
+| Hover | `#FAFAFA` (FS-004-02) | `#F5222D` (ZS-001-09) | `#F5222D` | 无 |
+| 激活 | `#FEEDED` (ZS-001-03) | `#F5222D` (ZS-001-09) | `#F5222D` | 左侧 `2px solid #F5222D` |
+
+#### 7.3.3 三级菜单项配色（前缀 `-` 短横线）
+
+| 状态 | 背景 | 文字 | 左侧指示条 |
+|------|------|------|-----------|
+| 默认 | `transparent` | `#575757` (FS-004-09) | 无 |
+| Hover | `#FAFAFA` (FS-004-02) | `#F5222D` (ZS-001-09) | 无 |
+| 激活 | `#FEEDED` (ZS-001-03) | `#F5222D` (ZS-001-09) | 左侧 `2px solid #F5222D` |
+
+### 7.4 下拉菜单面板
+
+#### 7.4.1 列表型面板（如二级导航的"浏览器容器 / 手机板卡容器…"）
+
+| 属性 | 取值 |
+|------|------|
+| 背景 | `#FFFFFF` (FS-004-01) |
+| 边框 | `1px solid #E8E8E8` (FS-004-04) |
+| 阴影 | `0 4px 16px rgba(34, 34, 34, 0.12)`（§3.1.3 二级阴影） |
+| 圆角 | `4px` |
+| 内边距 | 上下 `--spacing-2` (8px) |
+| 最小宽度 | `150px` |
+| 行高 | `36px` |
+
+| 状态 | 背景 | 文字 |
+|------|------|------|
+| 默认 | `transparent` | `#575757` (FS-004-09) |
+| Hover / 激活 | `#FEEDED` (ZS-001-03) | `#F5222D` (ZS-001-09) |
+| 失效 | `transparent` | `#C1C1C1` (FS-004-06) |
+
+#### 7.4.2 卡片宫格型面板（一级导航的图标宫格下拉）
+
+白底大面板内以网格陈列"图标 + 二级导航名"卡片。
+
+| 角色 | 背景 | 图标 / 文字 |
+|------|------|-------------|
+| 卡片（默认） | `#FEF6F6` (ZS-001-02) | 图标 `#F5222D`，文字 `#575757` |
+| 卡片（Hover） | `#FEEDED` (ZS-001-03) | 图标 / 文字 `#F5222D` |
+| 卡片（激活 / 当前） | `#F5222D` (ZS-001-09) | 图标 / 文字 `#FFFFFF` |
+
+| 属性 | 取值 |
+|------|------|
+| 卡片尺寸 | `80px × 72px`（自适应等分） |
+| 卡片圆角 | `4px` |
+| 卡片间距 | `--spacing-2` (8px) |
+| 面板内边距 | `--spacing-4` (16px) |
+| 面板阴影 | `0 8px 32px rgba(34, 34, 34, 0.16)`（§3.1.3 三级阴影） |
+
+### 7.5 交互与动画
+
+| 行为 | 动效 |
+|------|------|
+| 下拉面板展开 | `transform-origin: top; scaleY(0.95) → scaleY(1); opacity 0 → 1`，`200ms ease-out` |
+| 展开箭头旋转 | `rotate(0 → 180deg)`，`200ms ease-out` |
+| Hover 背景过渡 | `background-color 120ms ease-out` |
+| 激活底部高亮线 | `width 0% → 100%`，`240ms ease-out` |
+
+### 7.6 侧边栏布局变体
+
+> 侧边栏宽度通常固定，按"是否分级 / 是否展开"分为四种形态。关键区分：**叶子节点选中**用实心红填充 + 白字 + 左侧红指示条；**父级（含子项的可展开项）选中**仅用红字 + 红图标，不填充。
+
+#### 7.6.1 上下分级 · 收起（仅图标）
+
+| 属性 | 取值 |
+|------|------|
+| 宽度 | `64px`，仅图标 |
+| 图标项（默认） | 图标 `#A6A6A6`，背景 `transparent` |
+| 图标项（激活） | 图标 `#FFFFFF`，背景 `#F5222D` (ZS-001-09) 圆角方块 `4px` |
+| Hover 弹出浮层 | **深色浮层**：背景 `#3D3D3D` (FS-004-10)，圆角 `4px`，阴影 §3.1.3 三级 |
+| 浮层内二级标题 | `14px Medium`，`#FFFFFF` |
+| 浮层内三级项（前缀 `-`） | `14px Regular`，`#FFFFFF`；hover 背景 `rgba(255,255,255,0.1)` |
+
+#### 7.6.2 上下分级 · 展开
+
+完整宽度列表，二级为可展开组（`^ / ▾`），其下挂三级项。
+
+| 层级 / 状态 | 背景 | 文字 / 图标 | 左侧指示条 |
+|------|------|-------------|-----------|
+| 二级（默认） | `transparent` | 文字 `#222222`、图标 `#A6A6A6` | 无 |
+| 二级（展开 / 当前父级） | `transparent` | 文字 `#F5222D`、图标 `#F5222D` | 无 |
+| 三级（默认，前缀 `-`） | `transparent` | `#575757` (FS-004-09) | 无 |
+| 三级（选中 · 叶子） | `#F5222D` (ZS-001-09) | `#FFFFFF` | 左侧 `2px solid #F5222D` |
+
+#### 7.6.3 只有二级标题 · 不分级
+
+扁平列表，二级即叶子节点，无三级。
+
+| 状态 | 背景 | 文字 / 图标 | 左侧指示条 |
+|------|------|-------------|-----------|
+| 默认 | `transparent` | 文字 `#222222`、图标 `#A6A6A6` | 无 |
+| Hover | `#FAFAFA` (FS-004-02) | 文字 `#F5222D`、图标 `#F5222D` | 无 |
+| 选中 | `#F5222D` (ZS-001-09) | `#FFFFFF` | 左侧 `2px solid #F5222D` |
+
+#### 7.6.4 二级选中 · 分级（含四级浮层）
+
+二级展开后选中三级，三级再向右弹出**白底四级浮层**。
+
+| 角色 | 配色 |
+|------|------|
+| 三级选中（叶子） | 背景 `#F5222D`，文字 `#FFFFFF`，左侧 `2px solid #F5222D` |
+| 四级浮层背景 | `#FFFFFF`，边框 `1px solid #E8E8E8`，阴影 §3.1.3 二级 |
+| 四级项（默认） | `#575757` (FS-004-09) |
+| 四级项（Hover） | 背景 `#FEEDED` (ZS-001-03)，文字 `#F5222D` |
+| 四级项（选中） | 文字 `#F5222D`，左侧 `2px solid #F5222D` |
+
+---
+
+## 8. 面包屑（Breadcrumb）
+
+> 用于标识当前页面在层级结构中的位置，并提供逐级返回与跳转。建议层级**不超过四级**。
+
+### 8.1 顶部路径式（🏠 | 概况 / 总概况）
+
+页面顶部的简版面包屑，靠 `/` 分隔。
+
+| 元素 | 色值 | 来源 | 说明 |
+|------|------|------|------|
+| 首页图标 🏠 | `#A6A6A6` (FS-004-07) | — | hover `#F5222D` |
+| 竖分隔 `\|` | `#E8E8E8` | FS-004-04 | 首页图标与路径间 |
+| 父级路径文字 | `#575757` (FS-004-09) | — | 可点击，hover `#F5222D` |
+| 路径分隔 `/` | `#C1C1C1` | FS-004-06 | — |
+| 当前页文字 | `#222222` (FS-004) | — | `Medium`，不可点击 |
+
+### 8.2 返回 + 路径式（含 ← 返回）
+
+左侧"← 返回"按钮 + 竖分隔 + 文字路径。按层级展开：
+
+```
+一级:  ← 返回 │ 现在位置
+二级:  ← 返回 │ 上一级位置 / 现在位置
+三级:  ← 返回 │ 上二级位置 / 上一级位置 / 现在位置
+四级:  ← 返回 │ 上三级位置 / 上二级位置 / 上一级位置 / 现在位置
+```
+
+| 元素 | 色值 | 来源 | 说明 |
+|------|------|------|------|
+| 返回箭头 ← + "返回" | `#F5222D` (ZS-001-09) | — | hover `#CF1322`，文本按钮态 |
+| 竖分隔 `\|` | `#E8E8E8` | FS-004-04 | 返回与路径间 |
+| 历史层级文字 | `#575757` (FS-004-09) | — | 可点击，hover `#F5222D` |
+| 路径分隔 `/` | `#C1C1C1` | FS-004-06 | — |
+| 当前位置文字 | `#222222` (FS-004) | — | `Medium`，不可点击 |
+
+### 8.3 行为规则
+
+- 点击「返回」按钮逐步向上返回一级。
+- 点击文字路径，快速返回到该层级页面。
+- 层级尽可能不超过四级；超出时中间层折叠为 `…`。
+- 字号 `14px Regular`，元素间距 `--spacing-2` (8px)，竖分隔高度约 `12–14px`。
+
+---
+
+## 9. 页头与分页
+
+### 9.1 页头（Page Header）
+
+内容区顶部的标题区，底部叠一条 `1px solid #E8E8E8` (FS-004-04) 分割线。
+
+| 变体 | 构成 | 配色 |
+|------|------|------|
+| 基础页头 | 页头标题 | 标题 `16px Bold #222222` (FS-004) |
+| 页头 + 说明 | 标题 +（简要说明） | 说明 `14px Regular #A6A6A6` (FS-004-07) |
+| 页头 + 说明 icon | 标题 + `?` 帮助图标 | 图标 `#A6A6A6`，hover `#F5222D` |
+| 分 Tabs 页头 | 多个标题 Tab | 见 §9.2 |
+
+### 9.2 分 Tabs 页头
+
+横向页签形态，激活态红色下划线。
+
+| 状态 | 文字 | 下划线 |
+|------|------|--------|
+| 默认 | `#222222` (FS-004) | 无 |
+| Hover | `#F5222D` (ZS-001-09) | 无 |
+| 激活 | `#F5222D` (ZS-001-09) | `2px solid #F5222D`，宽度与文字齐 |
+| 失效 | `#C1C1C1` (FS-004-06) | 无 |
+
+- 字号 `14px Medium`，项间距 `--spacing-5` (24px)，下划线与文字底部间距 `--spacing-2` (8px)
+
+### 9.3 分页（Pagination）
+
+#### 9.3.1 正常分页
+
+`共 240 项  [1] 2 3 4 5 … 24 >  每页 [10 ▾] 条  前往 [ ] 页`
+
+| 元素 | 默认 | Hover | 激活 | 失效 |
+|------|------|-------|------|------|
+| 总数 / 辅助文字（共N项 / 每页 / 条 / 前往 / 页） | `#575757` (FS-004-09) | — | — | — |
+| 页码数字 | `#222222` (FS-004) | `#F5222D` (ZS-001-09) | 背景 `#F5222D` + 文字 `#FFFFFF` | `#C1C1C1` (FS-004-06) |
+| 翻页箭头 `< >` | `#575757` (FS-004-09) | `#F5222D` | — | `#C1C1C1` |
+| 省略号 `…` | `#A6A6A6` (FS-004-07) | — | — | — |
+| 每页选择器 / 跳转输入框 | 边框 `#DBDBDB` (FS-004-05) | 边框 `#F5222D` | — | 边框 `#E8E8E8` |
+
+- 页码项尺寸 `28px × 28px`，圆角 `2px`，激活态为实心红方块；项间距 `--spacing-1` (4px)
+
+#### 9.3.2 精简分页
+
+`共 1 项  <  [1] / 10  >`
+
+| 元素 | 色值 |
+|------|------|
+| 总数文字 | `#575757` (FS-004-09) |
+| 当前页输入框 | 边框 `#DBDBDB`，文字 `#222222` |
+| 总页数 `/ N` | `#A6A6A6` (FS-004-07) |
+| 翻页箭头 `< >` | `#575757`，hover `#F5222D`，失效 `#C1C1C1` |
+
+#### 9.3.3 导航式分页
+
+仅"下一页 » / « 上一页"文本按钮，无页码。配色沿用 §5.3.3 文本按钮 + 图标：
+
+| 状态 | 色值 |
+|------|------|
+| 默认 | `#F5222D` (ZS-001-09) |
+| Hover | `#CF1322` (ZS-001) |
+| 失效 | `#C1C1C1` (FS-004-06) |
+
+---
+
+## 10. 步骤条（Steps）
+
+> 用于多步流程的进度指引。按布局分**横向**（弹窗 / 页面）与**纵向**两类。颜色取自 ZS-001 主色红与 FS-004 中性灰。
+
+### 10.1 步骤节点（公共）
+
+每个步骤由「指示圆 + 标题（可选描述）」组成。指示圆按状态切换形态：
+
+| 状态 | 圆形外观 | 圆内符号 | 来源 |
+|------|----------|----------|------|
+| 已完成（Completed） | 描边圆 `2px solid #F5222D`，背景 `transparent` | `✓`（对勾，`#F5222D`） | ZS-001-09 |
+| 当前（Current） | 实心圆，背景 `#F5222D` | 步骤数字，`#FFFFFF` | ZS-001-09 / 白 |
+| 未开始（Upcoming） | 描边圆 `1px solid #C1C1C1`，背景 `transparent` | 步骤数字，`#A6A6A6` | FS-004-06 / FS-004-07 |
+| 失效（Disabled） | 描边圆 `1px solid #E8E8E8`，背景 `transparent` | 步骤数字，`#C1C1C1` | FS-004-04 / FS-004-06 |
+
+**指示圆规格**：
+
+| 属性 | 取值 |
+|------|------|
+| 直径 | `24px` |
+| 圆内字号 | `12px Bold`（D-DIN 或 Noto Sans Bold） |
+| 对勾图标 | `12px`，居中 |
+
+**标题与描述文字**：
+
+| 元素 | 状态 | 字号 / 颜色 | 来源 |
+|------|------|-------------|------|
+| 标题 | 已完成 / 当前 | `14px Medium`，`#222222` | FS-004 |
+| 标题 | 未开始 / 失效 | `14px Medium`，`#A6A6A6` → `#C1C1C1` | FS-004-07 → FS-004-06 |
+| 描述 | 已完成 / 当前 | `12px Regular`，`#575757` | FS-004-09 |
+| 描述 | 未开始 / 失效 | `12px Regular`，`#A6A6A6` → `#C1C1C1` | FS-004-07 → FS-004-06 |
+
+**连接线（步骤之间）**：
+
+| 类型 | 色值 | 来源 | 样式 |
+|------|------|------|------|
+| 已完成段 | `#F5222D` | ZS-001-09 | `1px dashed`（弹窗）/ `1px solid`（页面） |
+| 未完成段 | `#C1C1C1` | FS-004-06 | `1px dashed` |
+
+> 连接线在指示圆两侧水平居中（横向）或正下方垂直（纵向）；线两端与圆外缘留 `--spacing-1` (4px) 间隙。
+
+### 10.2 弹窗步骤条（横向 · 描边圆为主）
+
+用于 Modal / Drawer 内的紧凑步骤条。完成态用**描边 + 红色对勾**，避免在弹窗内过于抢眼。
+
+```
+( ✓ ) ┄┄┄ (●2) ┄┄┄ ( 3 ) ┄┄┄ ( 4 ) ┄┄┄ ( 5 )
+ 标题        标题       标题       标题       标题
+(描述)     (描述)      (描述)     (描述)     (描述)
+```
+
+| 属性 | 取值 |
+|------|------|
+| 容器水平 padding | `--spacing-5` (24px) |
+| 指示圆 → 标题间距 | `--spacing-2` (8px) |
+| 标题 → 描述间距 | `--spacing-1` (4px) |
+| 连接线 | `1px dashed`，完成段 `#F5222D`，未完成段 `#C1C1C1` |
+| 文字对齐 | 标题、描述居中于指示圆下方 |
+| 两种变体 | 仅标题 / 标题 + 描述 |
+
+### 10.3 页面步骤条（横向 · 实心圆 + 自定义首项标题）
+
+用于页面级向导（如「新建集群」）。完成态连接线改为**实线**，首步标题可显示具体名称。
+
+```
+(✓) ──── (●2) ┄┄┄ ( 3 ) ┄┄┄ ( 4 ) ┄┄┄ ( 5 )
+新建集群   标题       标题       标题       标题
+(描述文本) (描述文本) (描述文本) (描述文本) (描述文本)
+```
+
+| 维度 | 弹窗步骤条 | 页面步骤条 |
+|------|-----------|-----------|
+| 完成态圆形 | 描边圆 + 红色对勾 | 描边圆 + 红色对勾（同） |
+| 完成段连接线 | `1px dashed #F5222D` | `1px solid #F5222D` |
+| 第一项 | 通用「标题」占位 | 可显示具体名称（自定义文案） |
+
+### 10.4 纵向步骤条
+
+用于侧栏 / 详情页内的纵向流程指引。两种变体——「仅标题」与「标题 + 描述」。
+
+```
+仅标题:              标题 + 描述:
+
+(✓) 新建集群         (✓) 新建集群
+ ┊                       描述文本描述
+(●2) 标题            ┊
+ ┊                  (●2) 标题
+( 3 ) 标题               描述文本描述
+ ┊                  ┊
+( 4 ) 标题          ( 3 ) 标题
+                         描述文本描述
+```
+
+| 属性 | 取值 |
+|------|------|
+| 指示圆 → 标题水平间距 | `--spacing-2` (8px) |
+| 节点垂直间距（仅标题） | `--spacing-5` (24px)，圆心到圆心 |
+| 节点垂直间距（标题 + 描述） | `--spacing-6` (32px)，圆心到圆心 |
+| 标题 → 描述间距 | `--spacing-1` (4px) |
+| 连接线位置 | 上下指示圆正下方垂直，居中于圆心 |
+| 连接线样式 | `1px dashed`，完成段 `#F5222D`，未完成段 `#C1C1C1` |
+| 文字对齐 | 标题与描述左对齐 |
+
+### 10.5 交互与动画
+
+| 行为 | 动效 |
+|------|------|
+| 步骤切换（next） | 当前圆 `background: transparent → #F5222D`，`200ms ease-out`；上一步圆 `border-color: #C1C1C1 → #F5222D`，再 `200ms` 切换为对勾图标淡入 |
+| 连接线进度 | 完成段 `width 0% → 100%`，`240ms ease-out` |
+
+---
+
+## 11. 页签与锚点
+
+> 共用主色红指示当前位置：页签用于同层级内容切换，锚点用于长页面内章节跳转。
+
+### 11.1 页签（Tabs）
+
+#### 11.1.1 横向页签（下划线 · 横向）
+
+| 状态 | 文字 | 下划线 |
+|------|------|--------|
+| 默认 | `#222222` (FS-004) | 无 |
+| Hover | `#F5222D` (ZS-001-09) | 无 |
+| 激活 | `#F5222D` (ZS-001-09) | `2px solid #F5222D`，宽度与文字齐 |
+| 失效 | `#C1C1C1` (FS-004-06) | 无 |
+
+- 字号 `14px Medium`，项间距 `--spacing-5` (24px)，下划线与文字底部间距 `--spacing-2` (8px)
+- 容器底边叠一条 `1px solid #E8E8E8` (FS-004-04) 基线，激活高亮线压在其上
+
+#### 11.1.2 纵向页签（下划线 · 纵向）
+
+| 状态 | 文字 | 右侧指示线 |
+|------|------|-----------|
+| 默认 | `#222222` (FS-004) | 无 |
+| Hover | `#F5222D` (ZS-001-09) | 无 |
+| 激活 | `#F5222D` (ZS-001-09) | 右侧 `2px solid #F5222D`，高度与文字齐 |
+| 失效 | `#C1C1C1` (FS-004-06) | 无 |
+
+- 字号 `14px Medium`，项高度 `32px`，项间距 `--spacing-2` (8px)
+- 容器右边叠一条 `1px solid #E8E8E8` 基线，激活指示线压在其上
+
+### 11.2 锚点（Anchor）
+
+用于长内容页的章节快速跳转，支持一 / 二级缩进。
+
+```
+│ 一级
+│ 一级          (active)
+│    二级
+│    二级
+│ 一级
+│ 一级
+```
+
+| 属性 | 取值 |
+|------|------|
+| 左侧基线 | `1px solid #E8E8E8` (FS-004-04) 通栏 |
+| 项高度 | `32px` |
+| 一级项左 padding | `--spacing-3` (12px) |
+| 二级项左 padding | `--spacing-5` (24px) |
+| 字号 | `14px Regular` |
+
+| 状态 | 一级文字 | 二级文字 | 左侧指示条 |
+|------|----------|----------|-----------|
+| 默认 | `#222222` (FS-004) | `#A6A6A6` (FS-004-07) | 无 |
+| Hover | `#F5222D` (ZS-001-09) | `#F5222D` (ZS-001-09) | 无 |
+| 激活 | `#F5222D` (ZS-001-09) | — | 左侧 `2px solid #F5222D`，覆盖容器基线 |
+
+- 二级项不单独支持激活态：选中二级时其父级一级显示激活态，指示条按父级位置渲染
+
+---
+
+
+---
+
+> 返回 [规范目录](README.md)

frontend-web/docs/浅红色UI规范/04-数据展示.md

@@ -0,0 +1,308 @@
+# 浅红色 UI 规范 · 四、数据展示
+
+> 返回 [规范目录](README.md)　|　本篇：弹出式窗口 · 卡片 · 折叠面板 · 进度条 · 表格 · 标签 · 时间轴
+
+---
+
+## 17. 弹出式窗口（Modal / Dialog）
+
+> 用于聚焦的多步表单 / 确认操作。内部可承载页签、步骤条、表单控件。
+
+### 17.1 容器规格
+
+| 属性 | 取值 |
+|------|------|
+| 背景 | `#FFFFFF` (FS-004-01)，圆角 `4px` |
+| 阴影 | `0 8px 32px rgba(34, 34, 34, 0.16)`（§3.1.3 三级阴影） |
+| 遮罩层 | `rgba(34, 34, 34, 0.45)`（基于 FS-004） |
+| 标题区 | 左侧 `3px` 主色红竖条 `#F5222D` + 标题 `16px Bold #222222` |
+| 关闭按钮 `×` | `#A6A6A6` (FS-004-07)，hover `#F5222D` |
+| 内边距 | `--spacing-5` (24px) |
+| 底部操作区 | 右对齐，主按钮在最右（§5.3.4） |
+
+### 17.2 内部页签与步骤条
+
+- 顶部页签沿用 §11.1 横向页签（Tab 激活红字 + 红下划线，基线 `#E8E8E8`）。
+- 步骤条沿用 §10.2 弹窗步骤条（完成态红描边对勾、当前态红实心、未开始灰描边，连接线 `1px dashed`）。
+
+### 17.3 表单控件补充（Modal 内常用）
+
+| 控件 | 配色 |
+|------|------|
+| 必填星号 `*` | `#F5222D` (ZS-001-09)，置于 label 前 |
+| 下拉选择（Select，`请选择 ▾`） | 同输入框（§13），箭头 `#A6A6A6`，聚焦边框 `#F5222D` |
+| 日期 / 时间选择器（📅） | 输入框 + 日历图标 `#A6A6A6`；区间用"起 至 止"两段 |
+| 文本区域（Textarea） | 同输入框，`resize: vertical`，最小高度约 `80px` |
+| 数值 + 单位（如 `100 天`） | 输入框 + 尾部 addon（背景 `#FAFAFA`，边框 `#DBDBDB`，文字 `#575757`） |
+| 复选框（Checkbox） | 未选边框 `#DBDBDB`；选中背景 `#F5222D` + 对勾 `#FFFFFF` |
+| 错误态 | 控件边框 `1px solid #F5222D`，下方红色提示文字 `12px #F5222D`（如"输入表单内容报错"） |
+
+---
+
+## 18. 数据展示 · 卡片（Card）
+
+> 用于陈列结构化信息（人物 / 媒体 / 群组等档案）。在 §3 卡片基础上扩展"分级信息卡片"。
+
+### 18.1 卡片头部
+
+| 元素 | 配色 |
+|------|------|
+| 类目竖条（标题前） | `3px` 主色红 `#F5222D` (ZS-001-09) |
+| 标题（如「个体」「媒体」） | `16px Bold`，`#222222` (FS-004) |
+| 关闭 `×` | `#A6A6A6` (FS-004-07)，hover `#F5222D` |
+| 右上操作（查看档案） | 小尺寸主按钮 `#F5222D` + 白字（§5.1 小，含图标） |
+
+### 18.2 标签 / 属性 Tag
+
+| 类型 | 背景 | 文字 | 来源 |
+|------|------|------|------|
+| 人物属性 / 红色标签 | `#FEEDED` (ZS-001-03) | `#F5222D` (ZS-001-09) | 主色红 |
+| 立场 / 成功类（绿） | `#EEFCF7` (FS-002-03) | `#189D72` (FS-002-10) | 渐绿系 |
+| 状态签（右上角强调） | `transparent` | `#F5222D` (ZS-001-09) | 主色红 |
+| 话题标签（#话题） | `transparent` | `#F5222D` (ZS-001-09) | 主色红，`#` 前缀 |
+
+- Tag 圆角 `2px`，内边距 `0 8px`，字号 `12px`
+
+### 18.3 卡片内页签与信息行
+
+| 元素 | 配色 |
+|------|------|
+| 页签（基本信息 / 线下活动 / 线上发声） | 激活 `#F5222D` + 红下划线；默认 `#222222`（§11.1.1） |
+| 页签红点提示（•） | `#F5222D` (ZS-001-09)，标识有更新 |
+| 信息项标签（国家/地区、职务…） | `#A6A6A6` (FS-004-07) |
+| 信息项取值 | `#222222` (FS-004) |
+| 来源平台图标（如 Facebook） | 平台原色（蓝 `#0079FE` 近似），不纳入主题强调色 |
+
+---
+
+## 19. 数据展示 · 折叠面板（Collapse）
+
+> 用于长内容的收起 / 展开。含列表概览折叠、带图标折叠、手风琴折叠、信息流折叠四类。
+
+### 19.1 列表概览折叠（含 + 图标变体）
+
+| 状态 | 构成 | 配色 |
+|------|------|------|
+| 收起 | 标题 + 描述 + 右侧 `▾` | 标题 `#222222` (FS-004)、描述 `#A6A6A6` (FS-004-07)、箭头 `#A6A6A6` |
+| 展开 | 上述 + 下方内容区 | 内容区背景 `#FAFAFA` (FS-004-02)，箭头旋转为 `^` |
+
+| 属性 | 取值 |
+|------|------|
+| 容器边框 | `1px solid #DBDBDB` (FS-004-05)，圆角 `4px` |
+| 头部内边距 | `--spacing-4` (16px) |
+| 左侧图标（带图标变体） | 占位 `40px`，图标 `#A6A6A6` |
+
+### 19.2 手风琴折叠（Accordion）
+
+多面板同列堆叠，同一时刻通常仅展开一项。
+
+| 元素 | 配色 |
+|------|------|
+| 项分隔 | `1px solid #E8E8E8` (FS-004-04) |
+| 标题 | `#222222` (FS-004)，前置 `▾ / >` 箭头 `#A6A6A6` |
+| 收起 / 展开 链接 | 文本按钮 `#F5222D` (ZS-001-09) |
+| 展开正文 | `#575757` (FS-004-09)，背景 `#FFFFFF` |
+
+### 19.3 信息流折叠（Feed）
+
+用于资讯流条目的展开详情。
+
+| 元素 | 配色 |
+|------|------|
+| 前置「标签」Tag | 背景 `#FEEDED` (ZS-001-03)，文字 `#F5222D` (ZS-001-09) |
+| 条目标题 | `#222222` (FS-004)，`14px Medium` |
+| 热度计数（🔥 6405） | 火苗图标 `#FF9900` (FS-001-09)，数字 `#575757` (FS-004-09) |
+| 收起 / 展开 链接 + 箭头 | `#F5222D` (ZS-001-09) |
+| 分节标题（【热点首发】/【应对建议】） | `#F5222D` (ZS-001-09)，`Medium` |
+| 来源 / 作者行（社交媒体 \| 平台 \| @用户） | `#A6A6A6` (FS-004-07) |
+| 外链 URL | `#0079FE` (ZS-002-09)，hover 下划线 |
+| 日期 | `#A6A6A6` (FS-004-07) |
+| 正文 | `#575757` (FS-004-09) |
+| 缩略图 | 圆角 `2px`，间距 `--spacing-1` (4px) |
+
+---
+
+## 21. 数据展示 · 进度条（Progress）
+
+### 21.1 标准进度条
+
+| 属性 | 取值 |
+|------|------|
+| 轨道背景 | `#F5F5F5` (FS-004-03) |
+| 轨道高度 | `8px`，圆角全圆 |
+| 已完成段 | 按语义取色（§20）：成功绿 / 失败红 / 警告橙 |
+| 百分比文字 | `#222222` (FS-004)，置于条右侧 |
+| 末端状态图标 | 成功 ✓ `#2FD69A`；失败 ✗ `#F5222D`（橙色进行态可不带图标） |
+
+### 21.2 小型进度条
+
+放在较窄区域内（如表格单元格）。规格同 §21.1，仅尺寸缩小：
+
+| 属性 | 取值 |
+|------|------|
+| 轨道高度 | `4px` |
+| 百分比 / 图标 | 字号缩至 `12px`，图标 `12px` |
+
+### 21.3 环形进度条
+
+| 属性 | 取值 |
+|------|------|
+| 轨道环 | `#F5F5F5` (FS-004-03) |
+| 进度环 | 按语义取色（§20），线宽 `6px`，圆头端点 |
+| 中心主数字（如 `82.0%`） | `#222222` (FS-004)，D-DIN |
+| 中心名称 | `12px Regular`，`#A6A6A6` (FS-004-07) |
+
+> 进度环颜色按阈值映射（如低→绿、中→橙、高→红）由业务自定义，但必须取自 §20 语义色。
+
+---
+
+## 22. 数据展示 · 表格（Table）
+
+### 22.1 结构规格
+
+| 属性 | 取值 |
+|------|------|
+| 表头背景 | `#FFFFFF`（或浅红 `#FEF6F6` ZS-001-02 强调首行） |
+| 表头文字 | `14px Medium`，`#222222` (FS-004) |
+| 单元格文字 | `14px Regular`，`#222222` |
+| 行高 | `48px` |
+| 行分隔 | `1px solid #F5F5F5` (FS-004-03) |
+| 行 Hover | 背景 `#FAFAFA` (FS-004-02) |
+| 斑马纹（可选） | 偶数行 `#FAFAFA` (FS-004-02) |
+| 复选框（选中） | 填充 `#F5222D` + 对勾 `#FFFFFF` |
+
+### 22.2 状态列（圆点 + 文字）
+
+| 文字 | 圆点色 | 来源 |
+|------|--------|------|
+| 普通 | `#2FD69A`（成功绿） | FS-002-09 |
+| 异常 | `#F5222D`（错误红） | ZS-001-09 |
+| 特殊 | `#FF9900`（警告橙） | FS-001-09 |
+
+- 文字统一 `#222222` (FS-004)，圆点直径 `6px`，与文字间距 `--spacing-1` (4px)
+
+### 22.3 整体状态列（状态标签）
+
+使用 §23 浅底状态标签：进行中（橙）/ 已完成（绿）/ 已失败（红）。
+
+### 22.4 操作列
+
+文本按钮 + 图标，沿用 §5.3.3：查看 / 配置 等均为 `#F5222D` (ZS-001-09)，hover `#CF1322`，按钮间距 `--spacing-3` (12px)。
+
+### 22.5 单元格内编辑报错
+
+可编辑单元格（如 `100 [M]`）校验失败：输入框边框 `1px solid #F5222D`，红色气泡提示"Table 内输入报错"（背景 `#F5222D`、白字 `12px`，§12.3 同款）。
+
+---
+
+## 23. 数据展示 · 标签（Tag / Badge）
+
+### 23.1 标签形式
+
+| 形式 | 用途 | 配色 |
+|------|------|------|
+| 文字按钮标签 | 重点突出标记属性 | 三种强度：灰底 `#F5F5F5`/`#575757`；浅红底 `#FEEDED`/`#F5222D`；实红 `#F5222D`/`#FFFFFF` |
+| 图标 + 文字按钮标签 | 增强辨识度 | 灰底 + 平台原色图标（如 Twitter 蓝）；或实红 `#F5222D` + 白字 + ✓ |
+| 圆点 + 文字标签 | 属性多 / 复杂、无需突出 | 圆点按语义色（普通绿 / 特殊橙 / 异常红），文字 `#222222` |
+| 动态标签 | 可增删（筛选列表、关键词） | 已加：灰底 `#F5F5F5` + `×`；新增入口：虚线框 `#DBDBDB` + "+ 标签" |
+
+- 标签圆角 `2px`，高度 `24px`，内边距 `0 8px`，字号 `12px`
+
+### 23.2 状态标签（Status Badge）
+
+四种呈现风格，颜色全部取自 §20 语义状态色：
+
+| 风格 | 说明 |
+|------|------|
+| ① 浅底彩字 | 浅底背景 + 语义文字色（默认推荐，弱干扰） |
+| ② 实填白字 | 语义实填背景 + 白字（强调态，用于重点状态） |
+| ③ 图标 + 浅底彩字 | ① 基础上前置语义图标 |
+| ④ 图标 + 彩字（无底） | 仅图标 + 文字，最轻量 |
+
+常见状态与语义映射：
+
+| 状态 | 语义 / 取色 |
+|------|-------------|
+| 未开始 / 就绪 | 中性灰 |
+| 等待中 / 等待 | 信息蓝 |
+| 进行中 / 进行 | 警告橙 |
+| 已完成 / 成功 | 成功绿 |
+| 已失败 / 失败 | 错误红 |
+| 待更新 / 待更 | 青 |
+
+- 图标（②④ 风格）：就绪 ⊖、等待 ⊗、进行 🕐、成功 ✓、失败 ✗、待更 🕐，颜色与文字同步
+
+---
+
+## 24. 数据展示 · 时间轴（Timeline）
+
+> 用于按时间顺序陈列事件。分纵向（基础 / 卡片 / 长文本）与横向两种主轴方向，另含全局缩略时间轴。
+
+### 24.1 纵向时间轴点（基础）
+
+| 元素 | 配色 |
+|------|------|
+| 轴线 | `1px solid #E8E8E8` (FS-004-04) 或虚线 |
+| 最新 / 当前节点 | 空心红圆环 `2px solid #F5222D` (ZS-001-09)，背景 `#FFFFFF` |
+| 历史节点 | 实心红点 `#F5222D` (ZS-001-09)，直径 `8px` |
+| 事件标题 | `14px Medium`，`#222222` (FS-004) |
+| 时间文字 | `12px Regular`，`#A6A6A6` (FS-004-07) |
+
+### 24.2 卡片式时间轴点
+
+节点内容置于浅灰卡片中。
+
+| 元素 | 配色 |
+|------|------|
+| 卡片背景 | `#FAFAFA` (FS-004-02)，圆角 `4px` |
+| 卡片内分隔 | `1px solid #E8E8E8` |
+| 正文标签（如"安全状况："） | `#575757` (FS-004-09) |
+| 正向取值（如"今日无安全风险"） | `#189D72`（成功绿，FS-002-10） |
+
+### 24.3 横向长文本时间轴
+
+横轴双向箭头，节点上下交错分布。
+
+| 元素 | 配色 |
+|------|------|
+| 主轴线 + 双向箭头 | `#222222` (FS-004) |
+| 上方节点标记 + 日期 | 红色 `#F5222D` (ZS-001-09)，`▼` 标记 |
+| 下方节点标记 + 日期 | 橙色 `#FF9900` (FS-001-09)，`▲` 标记 |
+| 节点正文 | `#575757` (FS-004-09)，`14px Regular` |
+
+> 上 / 下用红 / 橙双色区分两类事件或交替排布，避免拥挤。
+
+### 24.4 纵向长文本时间轴
+
+带头像、状态标签、富文本与附件的纵向时间流。
+
+| 元素 | 配色 |
+|------|------|
+| 轴线 | `1px dashed #DBDBDB` (FS-004-05) |
+| 日期分组吸顶标签 | 背景 `#A6A6A6`(FS-004-07) 或 `#F5F5F5`，文字 `#FFFFFF` / `#575757`，圆角 `2px` |
+| 节点圆点 | 红 `#F5222D`（重点）/ 浅红 `#FCB5B9`（次要） |
+| 状态标签 | 浅底状态标签：计划（橙 `#FFF6EA`/`#FF9900`）、已成行（红 `#FEEDED`/`#F5222D`）（§23.2 ①） |
+| 人物名 | `14px Regular`，`#222222` |
+| 时间 | `12px`，`#A6A6A6` (FS-004-07) |
+| 正文 | `#575757` (FS-004-09) |
+| 地址（📍 地址） | 图标 + 文字 `#A6A6A6` |
+| 缩略图 | 圆角 `2px`，间距 `--spacing-1` (4px) |
+
+### 24.5 全局时间轴（缩略 / 范围选择）
+
+页面顶部用于框选时间范围的缩略轴。
+
+| 元素 | 配色 |
+|------|------|
+| 刻度轴背景 | 灰阶渐变 `linear-gradient(90deg, #7F7F7F, #DBDBDB)`（FS-004-08 → FS-004-05） |
+| 刻度文字（如 04-03） | `#FFFFFF`，`12px` |
+| 拖拽游标（handle） | `#FFFFFF` 竖条，带轻微阴影 |
+| 选区刷选框（brush） | 边框 `1px solid #F5222D`，填充 `rgba(245, 34, 45, 0.08)`（浅红 ZS-001-09 8%） |
+| 选区内迷你面积图 | 描边 `#F5222D`，填充浅红渐变 |
+
+---
+
+
+---
+
+> 返回 [规范目录](README.md)

frontend-web/docs/浅红色UI规范/05-图表.md

@@ -0,0 +1,90 @@
+# 浅红色 UI 规范 · 五、图表
+
+> 返回 [规范目录](README.md)　|　本篇：图表通用色序 · 公共元素 · 柱状/折线/甘特/饼环
+
+---
+
+## 25. 图表（Charts）
+
+> 图表配色以**柔和色系**为主（保证大面积色块不刺眼），强调线 / 排行榜可叠加主色红渐变。多分类图表的色序按"用几色取几色"，从下表对应行从左到右取用。
+
+### 25.1 图表通用色序（权威）
+
+> 如需更多色值，请 UI 设计师按系统整体风格在同色系内扩展。
+
+| 分类数 | 色序（从左到右） |
+|--------|------------------|
+| 三色 | `#FA9196` `#97EBCD` `#80BCFF` |
+| 四色 | `#FA9196` `#FFCC80` `#97EBCD` `#A2E1F9` |
+| 五色 | `#FA9196` `#FFCC80` `#97EBCD` `#A2E1F9` `#80BCFF` |
+| 六色 | `#FA9196` `#FFCC80` `#BAE1B3` `#97EBCD` `#A2E1F9` `#80BCFF` |
+| 七色 | `#FA9196` `#FCA58F` `#FFCC80` `#BAE1B3` `#97EBCD` `#A2E1F9` `#80BCFF` |
+| 八色 | `#FA9196` `#FCA58F` `#FDB887` `#FFCC80` `#BAE1B3` `#97EBCD` `#A2E1F9` `#80BCFF` |
+| 九色 | `#FA9196` `#FCA58F` `#FDB887` `#FFCC80` `#DCD69A` `#BAE1B3` `#97EBCD` `#A2E1F9` `#80BCFF` |
+| 十色 | `#FA9196` `#FCA58F` `#FDB887` `#FFCC80` `#DCD69A` `#BAE1B3` `#97EBCD` `#9EE4EA` `#A2E1F9` `#80BCFF` |
+
+- 色值映射：`#FA9196`(ZS-001-06 浅红) / `#FCA58F`·`#FDB887`(橙红过渡) / `#FFCC80`(FS-001-06 浅橙) / `#DCD69A`(黄绿过渡) / `#BAE1B3`·`#97EBCD`(FS-002-06 浅绿) / `#9EE4EA`·`#A2E1F9`(FS-003-06 浅青) / `#80BCFF`(ZS-002-06 浅蓝)
+- 取色原则：序列从暖（红）到冷（蓝）渐变排布，相邻类别对比清晰
+
+### 25.2 图表公共元素
+
+| 元素 | 配色 |
+|------|------|
+| 坐标轴线 | `1px solid #E8E8E8` (FS-004-04) |
+| 网格线 | `1px dashed #F5F5F5` (FS-004-03) |
+| 轴刻度文字 | `12px`，`#A6A6A6` (FS-004-07) |
+| 图例文字 | `12px`，`#575757` (FS-004-09)，前置色块圆角 `2px` |
+| Tooltip 浮层 | 背景 `rgba(34,34,34,0.85)`（FS-004），文字 `#FFFFFF` `12px`，圆角 `4px` |
+| 数值标注气泡 | 背景 `#7F7F7F` (FS-004-08)，白字（如悬停值 `59.32`） |
+| 高亮选区（band） | 填充 `rgba(245,34,45,0.08)`，中线 `1px dashed #F5222D` (ZS-001-09) |
+
+### 25.3 柱状图（Bar）
+
+| 形态 | 配色 |
+|------|------|
+| 堆叠柱 / 分组柱 | 各序列按 §25.1 取色（如 Paper 绿 `#97EBCD`、Project 橙 `#FFCC80`、Book 红 `#FA9196`） |
+| 单序列柱 / 条形 | 主序列 `#FA9196`（浅红） |
+| 排行榜（TOP 渐变条） | 进度条填充 `linear-gradient(90deg, #F5222D 0%, #FF9900 100%)`（红→橙），轨道 `#F5F5F5`，名称 `#222222`、数值 `#222222` 右对齐 |
+
+- 柱体圆角 `2px`，柱间距按类目自适应
+
+### 25.4 折线图（Line / Area）
+
+| 元素 | 配色 |
+|------|------|
+| 主折线 | `#F5222D` (ZS-001-09)，线宽 `2px` |
+| 面积填充 | `linear-gradient(180deg, rgba(245,34,45,0.15), rgba(245,34,45,0))` |
+| 数据点 | 描边 `#F5222D` + 白色填充，悬停放大并实心 |
+| 多序列线 | 用饱和主色保证细线可辨：红 `#F5222D` / 蓝 `#0079FE` / 橙 `#FF9900` / 绿 `#2FD69A` |
+| 涨跌双色线 | 上行 `#F5222D`（红）/ 下行 `#2FD69A`（绿） |
+| 堆叠面积 | 各层按 §25.1 柔和色 + 各自浅色渐变填充 |
+| 悬停辅助线 + tooltip | 竖虚线 `#F5222D`，tooltip 见 §25.2（如"异常率 12.3%"） |
+
+### 25.5 甘特图（Gantt）
+
+| 元素 | 配色 |
+|------|------|
+| 行背景斑马纹 | 浅红 `#FEF6F6` (ZS-001-02) 与 `#FFFFFF` 交替 |
+| 任务条 | 按 §25.1 取色（每类任务一色），圆角 `2px`，末端可带箭头 |
+| 网格线 | `1px solid #F5F5F5` (FS-004-03) |
+| 时间轴 / 月份标签 | `12px`，`#A6A6A6` (FS-004-07) |
+| 图例 | 圆点 + 文字，圆点取对应任务色，文字 `#575757` |
+
+### 25.6 饼图 / 环形图（Pie / Donut）
+
+支持三环至八环（即 3~8 个分类），扇区按 §25.1 对应行取色。
+
+| 元素 | 配色 |
+|------|------|
+| 扇区 | §25.1 通用色序 |
+| 中心主数字（如 `34801`） | `#222222` (FS-004)，D-DIN |
+| 中心说明（XXX总数） | `12px`，`#A6A6A6` (FS-004-07) |
+| 引导线 + 标签 | 引导线同扇区色，标签文字 `#575757` (FS-004-09)，百分比同行 |
+| 扇区间隙 | `2px` 白色描边分隔，环宽适中（甜甜圈留中心空 ≥ 50%） |
+
+---
+
+
+---
+
+> 返回 [规范目录](README.md)

frontend-web/docs/浅红色UI规范/06-页面与布局.md

@@ -0,0 +1,121 @@
+# 浅红色 UI 规范 · 六、页面与布局
+
+> 返回 [规范目录](README.md)　|　本篇：统计与汇总卡 · 实体卡片 · 综合页面布局示例
+
+---
+
+## 26. 统计与汇总卡（Dashboard）
+
+> 仪表盘顶部的指标卡与汇总卡，用于一屏概览关键数据。
+
+### 26.1 指标卡（已用 / 可用 + 迷你环）
+
+横向排列的使用率卡，左侧数值、右侧迷你环形进度。
+
+| 元素 | 配色 |
+|------|------|
+| 卡标题（如"账号使用率"） | `14px Regular`，`#575757` (FS-004-09) |
+| 主数值（已用，如 `139`） | D-DIN `26px Bold`，`#222222` (FS-004) |
+| 次数值（可用，如 `2`） | D-DIN，`#FF9900`（警告橙，FS-001-09） |
+| 数值下标签（已用 / 可用） | `12px`，`#A6A6A6` (FS-004-07) |
+| 迷你环 + 中心百分比 | 按使用率阈值取语义色（§20）：低→绿、中→橙、高→红；轨道 `#F5F5F5` |
+| 卡间竖分隔 | `1px solid #E8E8E8` (FS-004-04) |
+
+### 26.2 汇总卡（总量 + 正常 / 异常 + 环形）
+
+| 元素 | 配色 |
+|------|------|
+| 总量数值（如 `300`） | D-DIN，`#222222` (FS-004) |
+| 正常数值（如 `270`） | `#FF9900`（橙）或成功绿，按业务定 |
+| 异常数值（如 `30`） | `#F5222D`（错误红，ZS-001-09） |
+| 标签（总量 / 正常 / 异常） | `#575757` (FS-004-09) |
+| 环形图 | 正常段绿 `#97EBCD`、异常段红 `#FA9196`（§25.1 色序）；中心主数（如 `40%`）`#222222`、说明（异常率）`#A6A6A6` |
+
+### 26.3 时间范围切换（今日 / 近7日）
+
+分段选择，沿用 §14.3 按钮式页签：
+
+| 状态 | 配色 |
+|------|------|
+| 选中（今日） | 背景 `#F5222D` (ZS-001-09)，文字 `#FFFFFF` |
+| 未选（近7日） | 背景 `#FFFFFF`，边框 `#DBDBDB`，文字 `#222222` |
+
+### 26.4 资源检索条
+
+`[资源类型 ▾]  [请输入关键词]  [搜索]`：下拉 + 输入框沿用 §13；搜索为主按钮（§5.2.1 红）。配合右侧表格（§22），表头含排序箭头（默认 `#A6A6A6`，激活 `#F5222D`）。
+
+---
+
+## 27. 实体卡片（列表卡 / 任务集卡）
+
+> 卡片网格陈列实体（任务集 / 人物 / 项目等），含主数据、属性表、负责人操作按钮与空状态。
+
+### 27.1 卡片结构
+
+| 元素 | 配色 |
+|------|------|
+| 卡片背景 / 边框 / 阴影 | `#FFFFFF` / `1px solid #E8E8E8` / §3.1.3 一级阴影，圆角 `4px` |
+| 主标题（如人名） | `16px Bold`，`#222222` (FS-004) |
+| 副标题（项目名） | `14px Regular`，`#575757` (FS-004-09) |
+| 创建时间 | `12px`，`#A6A6A6` (FS-004-07) |
+| 主指标（目标数量，如 `10247`） | D-DIN `26px Bold`，`#F5222D` (ZS-001-09)；标签"目标数量" `#A6A6A6` |
+| 属性面板（社交媒体(52)） | 背景 `#FEF6F6` (ZS-001-02)；条目名 `#575757`、数值 `#F5222D` (ZS-001-09) |
+| 联系/备注行 | `#575757` (FS-004-09)，时间后缀 `#A6A6A6` |
+| 底部负责人按钮 | 通栏主按钮：背景 `#F5222D`、文字 `#FFFFFF`（§5.2.1） |
+
+### 27.2 卡片 Hover 操作菜单
+
+卡片右上 `⋯` 触发**深色下拉**：
+
+| 元素 | 配色 |
+|------|------|
+| 菜单背景 | `#3D3D3D` (FS-004-10)，圆角 `4px`，阴影 §3.1.3 二级 |
+| 菜单项（修改 / 删除） | 文字 + 图标 `#FFFFFF`；hover 背景 `rgba(255,255,255,0.1)` |
+
+### 27.3 空状态（暂无任务）
+
+| 元素 | 配色 |
+|------|------|
+| 空状态插图 / 图标 | 中性灰 `#C1C1C1` (FS-004-06) |
+| 空状态文字（暂无任务） | `14px`，`#A6A6A6` (FS-004-07) |
+| 主指标归零 | 数值显示 `0`，颜色同 §27.1（红） |
+
+---
+
+## 28. 综合页面布局示例
+
+> 标准后台页面 = 顶部红底导航（§7.1）+ 左侧分级侧边栏（§7.3 / §7.6）+ 右侧内容区。
+
+### 28.1 仪表盘页
+
+```
+┌ Header（红底，§7.1）────────────────────────────────────────────┐
+├──────┬───────────────────────────────────────────────────────────┤
+│ 侧栏  │ 面包屑（§8.1）                                            │
+│(§7.3)│ ┌ 指标卡 × N（§26.1，横向等分，竖线分隔）───────────────┐ │
+│      │ ├ 汇总卡(§26.2) │ 折线图(§25.4) │ 资源表(§22 + 检索§26.4)│ │
+│      │ └ 异常分布图 …                                            │ │
+└──────┴───────────────────────────────────────────────────────────┘
+```
+
+- 内容区背景 `#FAFAFA` (FS-004-02)，卡片白底浮起；模块间距 `--spacing-5` (24px)，卡内边距 `--spacing-4` (16px)
+
+### 28.2 列表卡片页
+
+```
+┌ Header（红底）─────────────────────────────────────────────────┐
+├──────┬───────────────────────────────────────────────────────────┤
+│ 侧栏  │ [搜索框] [搜索] [+ 添加任务集]            排序 [创建时间 ▾]│
+│      │ ┌实体卡┐ ┌实体卡┐ ┌实体卡┐ ┌实体卡┐   （§27，等宽网格） │
+│      │ └─────┘ └─────┘ └─────┘ └─────┘                          │
+│      │ ┌实体卡┐ ┌空状态┐ …                                       │
+└──────┴───────────────────────────────────────────────────────────┘
+```
+
+- 卡片网格列间距 / 行间距 `--spacing-5` (24px)
+- 顶部工具条：搜索输入（§13）+ 搜索主按钮（§5.2.1）+ "添加"主按钮；右侧排序下拉（§13）
+- "+ 添加任务集"为主按钮（红 `#F5222D` + 白字 + 加号图标，§5.3.2）
+
+---
+
+> 返回 [规范目录](README.md)

frontend-web/docs/浅红色UI规范/README.md

@@ -0,0 +1,85 @@
+# 浅红色 UI 规范
+
+浅色主题设计规范：以白 / 浅灰作大面积背景、深色作正文、**红色（`#F5222D`）为品牌强调主色**。
+
+> 全文按主题拆分为 6 篇，章节号（§1 ~ §28）全局唯一，跨篇引用（如"沿用 §5.2.1"）按下表定位即可。
+
+## 篇目导航
+
+| 篇 | 文件 | 内容 |
+|----|------|------|
+| 一、基础样式 | [01-基础样式.md](01-基础样式.md) | §1 色彩 · §2 字体 · §3 阴影 · §4 圆角 · §6 间距 · §20 语义状态色 |
+| 二、按钮与表单 | [02-按钮与表单.md](02-按钮与表单.md) | §5 按钮 · §12 表单 · §13 输入框 · §14 选择按钮 · §15 标签输入框 · §16 上传 |
+| 三、导航 | [03-导航.md](03-导航.md) | §7 导航组件 · §8 面包屑 · §9 页头与分页 · §10 步骤条 · §11 页签与锚点 |
+| 四、数据展示 | [04-数据展示.md](04-数据展示.md) | §17 弹窗 · §18 卡片 · §19 折叠面板 · §21 进度条 · §22 表格 · §23 标签 · §24 时间轴 |
+| 五、图表 | [05-图表.md](05-图表.md) | §25 图表（通用色序 / 柱 / 折线 / 甘特 / 饼环） |
+| 六、页面与布局 | [06-页面与布局.md](06-页面与布局.md) | §26 统计与汇总卡 · §27 实体卡片 · §28 综合页面布局示例 |
+
+## 章节速查（§ → 篇）
+
+| § | 章节 | 所在篇 |
+|---|------|--------|
+| 1 | 色彩 | [一](01-基础样式.md) |
+| 2 | 字体 | [一](01-基础样式.md) |
+| 3 | 阴影 | [一](01-基础样式.md) |
+| 4 | 圆角 | [一](01-基础样式.md) |
+| 5 | 按钮 | [二](02-按钮与表单.md) |
+| 6 | 间距 | [一](01-基础样式.md) |
+| 7 | 导航组件 | [三](03-导航.md) |
+| 8 | 面包屑 | [三](03-导航.md) |
+| 9 | 页头与分页 | [三](03-导航.md) |
+| 10 | 步骤条 | [三](03-导航.md) |
+| 11 | 页签与锚点 | [三](03-导航.md) |
+| 12 | 表单 | [二](02-按钮与表单.md) |
+| 13 | 输入框 | [二](02-按钮与表单.md) |
+| 14 | 选择按钮 | [二](02-按钮与表单.md) |
+| 15 | 标签输入框 | [二](02-按钮与表单.md) |
+| 16 | 上传 | [二](02-按钮与表单.md) |
+| 17 | 弹出式窗口 | [四](04-数据展示.md) |
+| 18 | 卡片 | [四](04-数据展示.md) |
+| 19 | 折叠面板 | [四](04-数据展示.md) |
+| 20 | 语义状态色 | [一](01-基础样式.md) |
+| 21 | 进度条 | [四](04-数据展示.md) |
+| 22 | 表格 | [四](04-数据展示.md) |
+| 23 | 标签 | [四](04-数据展示.md) |
+| 24 | 时间轴 | [四](04-数据展示.md) |
+| 25 | 图表 | [五](05-图表.md) |
+| 26 | 统计与汇总卡 | [六](06-页面与布局.md) |
+| 27 | 实体卡片 | [六](06-页面与布局.md) |
+| 28 | 综合页面布局示例 | [六](06-页面与布局.md) |
+
+## 颜色速查
+
+完整色板与编号见 [§1 色彩](01-基础样式.md)。最常用的功能色：
+
+| 角色 | 色值 | 编号 |
+|------|------|------|
+| 主色 Primary | `#F5222D` | ZS-001-09 |
+| 主色 Hover | `#CF1322` | ZS-001 |
+| 主色 Active | `#A8071A` | ZS-001-11 |
+| 链接 / 信息 | `#0079FE` | ZS-002-09 |
+| 正文 | `#222222` | FS-004 |
+| 次级文字 | `#575757` | FS-004-09 |
+| 备注 / 占位 | `#A6A6A6` | FS-004-07 |
+| 禁用文字 | `#C1C1C1` | FS-004-06 |
+| 页面背景 | `#FAFAFA` | FS-004-02 |
+| 容器背景 | `#FFFFFF` | FS-004-01 |
+| 分割线 | `#E8E8E8` | FS-004-04 |
+
+**语义状态色**（成功 / 警告 / 错误 / 信息 / 待更新 / 中性，详见 [§20](01-基础样式.md)）：
+
+| 语义 | 文字 | 浅底 | 实填 |
+|------|------|------|------|
+| 成功（绿） | `#189D72` | `#EEFCF7` | `#2FD69A` |
+| 警告（橙） | `#FF9900` | `#FFF6EA` | `#FF9900` |
+| 错误（红） | `#F5222D` | `#FEEDED` | `#F5222D` |
+| 信息（蓝） | `#0079FE` | `#EAF4FF` | `#0079FE` |
+| 待更新（青） | `#45C3F3` | `#EFFAFE` | `#45C3F3` |
+| 中性（灰） | `#7F7F7F` | `#F5F5F5` | `#A6A6A6` |
+
+## 通用约定速记
+
+- **圆角**：按钮 / 输入框 / Tag `2px`；卡片 / 分栏 / Modal `4px`（§4）
+- **间距阶梯**：4 / 8 / 12 / 16（密）· 24 / 32 / 40 / 56（疏），16 是密的上限、24 是疏的下限（§6）
+- **按钮尺寸**：小 `24px` / 正常 `32px`（§5.1）
+- **字体**：中文 Noto Sans S Chinese，数字 D-DIN（§2）

frontend-web/docs/浅红色ui修改.md

@@ -0,0 +1,14 @@
+# 浅红色 UI 规范（已拆分）
+
+本规范已按主题拆分到文件夹 **[`浅红色UI规范/`](浅红色UI规范/README.md)**，请从目录进入：
+
+👉 **[浅红色UI规范 / README.md](浅红色UI规范/README.md)**
+
+| 篇 | 文件 |
+|----|------|
+| 一、基础样式（色彩 / 字体 / 阴影 / 圆角 / 间距 / 语义色） | [01-基础样式.md](浅红色UI规范/01-基础样式.md) |
+| 二、按钮与表单 | [02-按钮与表单.md](浅红色UI规范/02-按钮与表单.md) |
+| 三、导航 | [03-导航.md](浅红色UI规范/03-导航.md) |
+| 四、数据展示 | [04-数据展示.md](浅红色UI规范/04-数据展示.md) |
+| 五、图表 | [05-图表.md](浅红色UI规范/05-图表.md) |
+| 六、页面与布局 | [06-页面与布局.md](浅红色UI规范/06-页面与布局.md) |

frontend-web/docs/素材专家检索.md

@@ -1,243 +0,0 @@
-# 素材专家检索 —— 内网接口对接说明
-
-本文档说明 AI 智能写作中「素材收集专家」的检索机制、内网知识库接口的对接逻辑、
-涉及的代码文件，以及常见错误的排查方式。
-
----
-
-## 1. 检索来源切换
-
-素材专家支持多种检索来源，通过**后端配置文件**统一切换，**无需改动任何代码**。
-
-配置位置：`offline-backend-20260512/backend/config.yaml`
-
-```yaml
-ai_writing:
-  # 检索来源开关：internet=互联网检索（默认）/ intranet=内网知识库 / tavily / demo
-  search_provider: internet
-  # 以下两项仅在 search_provider=intranet 时生效
-  intranet_search_url: http://10.106.57.180:7863/knowledge_base/search_docs_es
-  intranet_knowledge_base: samples
-```
-
-| `search_provider` 取值 | 含义 |
-|---|---|
-| `internet` | 互联网检索（DuckDuckGo），失败时回退到 demo 演示素材。**当前默认值** |
-| `intranet`  | 内网知识库检索（调用 `search_docs_es` 接口） |
-| `tavily`    | Tavily 互联网检索 |
-| `demo`      | 内置演示素材，仅用于本地调试 |
-
-> 内网接口联通后，把 `search_provider` 改为 `intranet` 即可切换。
-> 配置文件支持热加载（`get_app_config()` 按 mtime 自动重载），改完一般无需重启后端。
-
----
-
-## 1.5 检索关键词数量
-
-素材专家的检索词数量由**用户在写作表单中指定**（「检索关键词数量」输入框，
-范围 `1~10`，默认 `6`）。数量越多素材越全面，但检索与排序更耗时。
-
-- 该参数随 `POST /api/ai-writing/start` 的 `keyword_count` 字段传入，写入 `AIWritingState.keyword_count`。
-- `researcher_node` 用它决定让 LLM 生成多少个检索词、并发检索多少个方向
-  （`EXTRACT_KEYWORDS_USER` prompt 按该数量格式化，`search_keywords = keywords[:keyword_count]`）。
-- 非法值（缺省 / 越界 / 非数字）由前后端双重兜底：后端 `_resolve_keyword_count()`
-  规整到 `[1, 10]`，越界回退默认 `6`。
-- 补充搜索（`re_search`）时用户额外添加的关键词不会被该上限截断。
-
----
-
-## 1.6 素材总量上限
-
-素材收集专家最终保留的素材**总条数**由后端配置文件统一控制，并按检索词数**均分**到每个词。
-
-配置位置：`offline-backend-20260512/backend/config.yaml` 的 `ai_writing` 段：
-
-```yaml
-ai_writing:
-  # 素材总量上限，范围 1~100，非法值回退 20
-  max_materials: 20
-```
-
-均分规则 —— `每个检索词的检索条数 = ⌈ max_materials / 实际检索词数 ⌉`（向上取整）：
-
-| `max_materials` | 检索词数 | 每词检索条数 |
-|---|---|---|
-| 20 | 1 | 20 |
-| 20 | 2 | 10 |
-| 20 | 3 | 7（共 21，合并后截断到 20） |
-| 20 | 5 | 4 |
-
-- 各检索词按上表条数检索 → 合并去重 → 最终统一截断到 `max_materials`。
-- 向上取整是为了保证去重后素材数仍能接近上限；去重后实际条数可能略少于上限（不同词命中同一篇），属正常。
-- 与 [1.5](#15-检索关键词数量) 的关系：`keyword_count` 决定**搜几个词**，`max_materials` 决定**总共要多少条**，两者相除得到每词条数。
-- 涉及代码：`researcher.py` 的 `_resolve_max_materials()`（读配置 + 规整）与 `_per_keyword_limit()`（均分计算）。
-
-> `config.yaml` 支持热加载，改完一般无需重启后端。
-
----
-
-## 2. 内网接口规格
-
-- **地址**：`http://10.106.57.180:7863/knowledge_base/search_docs_es`
-- **方法**：`POST`
-- **请求体**：
-
-  ```json
-  {
-    "query": "检索关键词",
-    "knowledge_base_name": "samples",
-    "ts": "yes"
-  }
-  ```
-
-- **响应体**：一个数组，每个元素结构如下：
-
-  ```json
-  [
-    {
-      "page_content": "正文片段",
-      "metadata": {
-        "m_title":  "标题",
-        "content":  "内容",
-        "recUuid":  "原文id",
-        "m_publish":"发布时间",
-        "source1":  "来源"
-      }
-    }
-  ]
-  ```
-
-  我们需要的字段都在 `metadata` 里。
-
-### 字段映射
-
-后端把内网响应映射为统一的 `SearchResult` 结构：
-
-| 内网响应字段              | SearchResult 字段 | 说明 |
-|--------------------------|--------------------|------|
-| `metadata.m_title`        | `title`            | 标题，缺省为「（无标题）」 |
-| `metadata.content`        | `content`          | 内容，截断到 500 字 |
-| `metadata.source1`        | `source`           | 来源，缺省为「内网知识库」 |
-| `metadata.m_publish`      | `published_at`     | 发布时间 |
-| `metadata.recUuid`        | `recUuid`          | 原文 id，用于前端拼接「查看原文」链接 |
-| —                         | `url`              | 固定为空，原文地址由前端依据 `recUuid` 拼接 |
-| —                         | `relevance_score`  | 接口不返回分值，按返回顺序赋递减分以保留 ES 排序 |
-| —                         | `source_type`      | 固定为 `"intranet"` |
-
----
-
-## 3. 对接逻辑与涉及文件
-
-### 后端
-
-| 文件 | 作用 |
-|------|------|
-| `packages/harness/deerflow/agents/ai_writing/search/intranet_stub.py` | **内网检索适配器** `IntranetSearchProvider`。发起 POST 请求、解析响应、映射为 `SearchResult` |
-| `packages/harness/deerflow/agents/ai_writing/search/__init__.py` | `get_search_provider()` 工厂函数，依据 `search_provider` 配置返回对应 provider |
-| `packages/harness/deerflow/agents/ai_writing/search/base.py` | `SearchResult` 数据结构 + `BaseSearchProvider` 抽象基类 |
-| `packages/harness/deerflow/agents/ai_writing/nodes/researcher.py` | 素材收集专家节点，调用 provider 检索并把结果合并、排序为素材包 |
-| `app/gateway/routers/ai_writing.py` | `_ai_writing_config()` 读取 `config.yaml` 的 `ai_writing` 段，经 `_make_config()` 注入运行时 |
-| `config.yaml` | `ai_writing` 段，检索来源开关与内网接口地址 |
-
-调用链：
-
-```
-ai_writing.py(_make_config 注入 ai_writing_config)
-  → researcher_node
-    → get_search_provider(ai_writing_config)   # 依据 search_provider 选择
-      → IntranetSearchProvider.search()         # POST search_docs_es
-        → SearchResult[]                        # 字段映射
-```
-
-### 前端
-
-| 文件 | 作用 |
-|------|------|
-| `src/core/config/index.ts` | `INTRANET_SOURCE_URL_BASE` 原文详情页地址前缀 + `buildIntranetSourceUrl()` 构造函数 |
-| `src/open-canvas/components/ai-writing/MaterialItem.tsx` | 素材卡片，`recUuid` 非空时显示「查看原文」按钮 |
-| `src/open-canvas/components/ai-writing/CompletedInterventionCard.tsx` | 历史回显的素材卡，「原文」链接同样基于 `recUuid` |
-| `src/open-canvas/api/ai-writing.ts` | `normalizeMaterial()` 把后端 snake_case 字段转为前端 camelCase（含 `recUuid`） |
-
-「查看原文」链接拼接规则：
-
-```
-INTRANET_SOURCE_URL_BASE + recUuid
-= https://chlib.b.uat.4.cn/knowlibrary/#/knowledge/mid_detail?recUuid={recUuid}
-```
-
-- 仅当素材的 `recUuid` **非空**时才显示「查看原文」按钮。
-- 点击直接 `window.open(...)` 新标签页打开，不做站内跳转。
-
----
-
-## 4. 错误处理与排查
-
-### 4.1 内网检索返回空 / 调不通
-
-**现象**：切到 `intranet` 后，素材专家时间线出现琥珀色告警「ES 波动导致检索异常」，
-下方显示真实报错原因；若完全无结果，再提示「未检索到任何素材」。
-
-`IntranetSearchProvider.search()` 对所有异常（连接失败、超时、非 2xx、JSON 解析失败）
-都做了兜底：**捕获后记录 warning 日志、把原因收集到 `provider.errors`，并返回空列表**，
-不会让整个写作流程崩溃。`researcher_node` 在检索结束后取出 `provider.errors`，
-以非致命的 `notice` 事件推送到前端时间线（标题「ES 波动导致检索异常」+ 真实原因），
-**接口报错不影响写作流程继续**。
-
-> 容错相关代码：
-> - 检索异常收集：`intranet_stub.py` / `duckduckgo_search.py` 的 `errors` 列表
-> - 告警事件发出：`researcher.py` 的 `_notice()` 与 `progress_events`
-> - 模型调用异常：`researcher.py`（检索词/排序）、`writer_outline.py` / `writer_draft.py` /
->   `editor.py` 均会发出「模型错误」事件（致命错误用 `error`，可兜底的用 `notice`）
-> - 前端展示：`TimelineStep.tsx` 渲染 `notice`（琥珀）/ `error`（红色）的标题 + 真实原因
-
-排查步骤：
-
-1. **确认网络可达**：在后端所在机器执行
-   `curl -X POST http://10.106.57.180:7863/knowledge_base/search_docs_es -H "Content-Type: application/json" -d "{\"query\":\"测试\",\"knowledge_base_name\":\"samples\",\"ts\":\"yes\"}"`
-2. **查看后端日志**：搜索关键字 `intranet search failed`，会打印具体异常（连接超时 / DNS / 401 等）。
-3. **确认配置**：`config.yaml` 的 `intranet_search_url`、`intranet_knowledge_base` 是否正确。
-
-空结果时前端已有兜底：素材确认卡会弹出「未检索到任何素材，是否在无素材的情况下继续写作」，
-用户可以选择「重新搜索」或「无数据继续写作」。
-
-### 4.2 字段缺失 / 响应结构变化
-
-`search()` 对每个字段都用 `or` 兜底（如 `m_title` 缺失时回退为「（无标题）」），
-单条数据字段缺失不会导致整批失败。
-
-若内网接口改为「数组外包一层 `data`/`results`」的结构，适配器已兼容；
-若改成其它结构，需修改 `intranet_stub.py` 中解析 `items` 的逻辑。
-
-### 4.3 「查看原文」按钮不显示
-
-**原因**：该素材的 `recUuid` 为空。这是预期行为 —— 只有内网知识库素材才带 `recUuid`，
-互联网检索（`internet`/`tavily`/`demo`）的素材没有 `recUuid`，不显示「查看原文」。
-
-如需让互联网素材也能跳转，需另行调整 `MaterialItem.tsx` 的显示条件。
-
-### 4.4 原文链接打不开 / 地址不对
-
-「查看原文」地址前缀写在 `src/core/config/index.ts` 的 `INTRANET_SOURCE_URL_BASE`。
-若内网原文详情页地址有变，只改这一个常量即可。
-
-### 4.5 检索到的素材全是无关内容
-
-**现象**：素材卡片内容与写作意图完全不沾边。
-
-**排查**：检查后端日志里素材专家实际用的检索词。常见原因是模型把关键词提取
-提示词模板里的占位符（如「关键词1」「...」）当成真关键词去检索了。
-
-`researcher.py` 的 `_clean_keywords()` 已对此做防御：剔除 `关键词\d*` / `keyword\d*` /
-`...` 等占位符，全部被滤掉时回退为写作意图本身。若仍出现，检查
-`researcher_prompts.py` 的 `EXTRACT_KEYWORDS` 提示词是否又引入了易被误抄的示例占位符。
-
----
-
-## 5. 联调上线步骤
-
-1. 确认后端机器能访问 `10.106.57.180:7863`。
-2. 把 `config.yaml` 的 `ai_writing.search_provider` 改为 `intranet`。
-3. 后端配置热加载生效（或重启后端）。
-4. 进入 AI 智能写作页面，发起一次写作，观察素材收集专家是否返回内网素材。
-5. 校验素材卡片的标题/来源/时间显示正确，「查看原文」能跳到内网详情页。
-6. 如检索为空，按 [4.1](#41-内网检索返回空--调不通) 排查。

frontend-web/index.html

@@ -1,7 +1,18 @@
 <!doctype html>
-<html lang="en-US">
+<html lang="en-US" suppressHydrationWarning>
   <head>
     <meta charset="UTF-8" />
+    <script>
+      (function () {
+        try {
+          var t = localStorage.getItem("strategy-theme");
+          var root = document.documentElement;
+          root.classList.remove("dark", "light");
+          if (t === "light") return;
+          root.classList.add("dark");
+        } catch (e) {}
+      })();
+    </script>
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>CM 助手</title>
   </head>

frontend-web/package.json

@@ -6,6 +6,8 @@
   "scripts": {
     "dev": "vite",
     "build": "node --max-old-space-size=8192 ./node_modules/vite/bin/vite.js build",
+    "build:sit": "node --max-old-space-size=8192 ./node_modules/vite/bin/vite.js build --mode sit",
+    "build:network": "node --max-old-space-size=8192 ./node_modules/vite/bin/vite.js build --mode network",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit"
   },
@@ -17,6 +19,9 @@
     "@codemirror/lang-markdown": "^6.5.0",
     "@codemirror/lang-python": "^6.2.1",
     "@codemirror/language-data": "^6.5.2",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@langchain/core": "^1.1.15",
     "@langchain/langgraph-sdk": "^1.5.3",
     "@radix-ui/react-avatar": "^1.1.11",
@@ -57,6 +62,7 @@
     "cmdk": "^1.1.1",
     "codemirror": "^6.0.2",
     "date-fns": "^4.1.0",
+    "dayjs": "^1.11.21",
     "docx": "^9.5.1",
     "dotenv": "^17.2.3",
     "embla-carousel-react": "^8.6.0",

frontend-web/src/App.tsx

@@ -2,7 +2,9 @@ import { useMemo } from "react";
 import { Navigate, Route, Routes } from "react-router-dom";
 import { ThemeProvider as NextThemesProvider } from "next-themes";
 
+import { FontScaleApplier } from "@/components/font-scale";
 import { QueryClientProvider } from "@/components/query-client-provider";
+import { AuthSyncWatcher } from "@/core/auth/sync";
 import { I18nProvider } from "@/core/i18n/context";
 import { detectLocale } from "@/core/i18n/locale";
 import { ChatProvider } from "@/contexts/ChatContext";
@@ -15,27 +17,37 @@ import LoginPage from "./pages/LoginPage";
 import PageRoutes from "./pages/PageRoutes";
 import PublicScheduledTaskPage from "./pages/PublicScheduledTaskPage";
 import PublicSharePage from "./pages/PublicSharePage";
+import EmbedChatPage from "./pages/EmbedChatPage";
+import { ChatRuntime } from "./pages/WorkspaceRoutes";
 import { NotFoundPage } from "./pages/NotFoundPage";
 
 function AppProviders({ children }: { children: React.ReactNode }) {
   const locale = useMemo(() => detectLocale(), []);
   const location = useLocation();
-  const forcedTheme = location.pathname === "/landing" ? "dark" : undefined;
+  const forcedTheme = location.pathname === "/landing" ? "light" : undefined;
 
   return (
     <NextThemesProvider
       attribute="class"
-      enableSystem
+      storageKey="strategy-theme"
+      defaultTheme="light"
+      enableSystem={false}
       disableTransitionOnChange
       forcedTheme={forcedTheme}
     >
-      <I18nProvider initialLocale={locale}>
-        <ThemeProvider>
-          <ChatProvider>
-            <QueryClientProvider>{children}</QueryClientProvider>
-          </ChatProvider>
-        </ThemeProvider>
-      </I18nProvider>
+      {/* QueryClientProvider must wrap ThemeProvider because the custom
+          ThemeProvider reads the admin-configured default via useQuery. */}
+      <QueryClientProvider>
+        <I18nProvider initialLocale={locale}>
+          <ThemeProvider>
+            <ChatProvider>
+              <AuthSyncWatcher />
+              <FontScaleApplier />
+              {children}
+            </ChatProvider>
+          </ThemeProvider>
+        </I18nProvider>
+      </QueryClientProvider>
     </NextThemesProvider>
   );
 }
@@ -56,6 +68,15 @@ export function App() {
             path="/public/scheduled-tasks/:taskId"
             element={<PublicScheduledTaskPage />}
           />
+          {/* Embedded workspace Q&A — no page/workspace sidebars; parent passes message/username/theme */}
+          <Route
+            path="/embed/chats/:thread_id"
+            element={
+              <ChatRuntime>
+                <EmbedChatPage />
+              </ChatRuntime>
+            }
+          />
           <Route path="/page/*" element={<PageRoutes />} />
           <Route path="*" element={<NotFoundPage />} />
         </Routes>

frontend-web/src/assets/icon/down-logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="16" height="16" viewBox="0 0 16 16"><defs><style>.a{fill:#fff;opacity:0;}.b{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><g transform="translate(-128.5 -117)"><rect class="a" width="16" height="16" transform="translate(128.5 117)"/><path class="b" d="M4,0,8,5H0Z" transform="translate(140.5 128) rotate(180)"/></g></svg>

frontend-web/src/assets/icon/nav-active.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="84.499" height="70" viewBox="0 0 84.499 70"><defs><style>.a{fill:url(#a);}</style><linearGradient id="a" x1="0.043" x2="0.978" y2="1.016" gradientUnits="objectBoundingBox"><stop offset="0" stop-color="#0062d9" stop-opacity="0.6"/><stop offset="1" stop-color="#0062d9" stop-opacity="0.302"/></linearGradient></defs><path class="a" d="M8855.277-1940.39l-.054-70h78v31.183l6.5,5.257-6.5,5.259v28.3Z" transform="translate(-8855.224 2010.389)"/></svg>

frontend-web/src/assets/icon/nav-line-logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="77" height="45" viewBox="0 0 77 45"><defs><style>.a{fill:url(#a);}</style><pattern id="a" preserveAspectRatio="none" width="100%" height="100%" viewBox="0 0 340 45"><image width="340" height="45" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVQAAAAtCAYAAADxyJMIAAAABHNCSVQICAgIfAhkiAAAIABJREFUeF7tnd2O5MZ1x5vdPTO7WkmGhMiQDQS5NODbvEBeIgbygcRwjOQur+D1K+QiQC4CBMld8hJ+CgO+DpAIcixblvZjZnqG+f/PqcM6Vawii+zuda+0XLSaXawvFos//s85xVHX9/3mXFvXdeeq+htSb/9mB4iX+vlmfZu/PKLs1BX7/ET1fndznsn8w5X1Pkc5jvfPV5ZfPcu784zD6v683QWXMLJbknnpsHy7gXpmWP5sIYRaYHgqsC2dKG97/haQL4Xy2SH8Drqt024JI98BtXVUi/nOBM0pWLaAkX09JRx/sBDe+Vj99sjyR10jV/ijI5Xir44s78+jBcLMPwXis0H3HWz9pXoH1FPdgFLPCaF5DCjXAvLrALM/rQzKuWH36QnH7xTX9bMzw2IO2muhPAfgNwbeM4/fKa7xiet4B9RVAzq4ndb7GL3nquSrnFKXrcBcqhbngHlO4P3+Qp3oH54xcDAH7Dng5nO3FcBTwC3Blv5d29bPeNfbby5o3wF1EVBH/vtl0+tn0ti4TA2ex4JzDpD5uc8B81TQe3FhSnTRHEDmZycCwhys54Cb97sG4GNBW1O0R7sRTjSOS6/fGfO/A2pxcJsDnykcFZjlLYdmGZZj2JZUZisof4iufJHBaykUW+D38QJ1+fIth6ld3fcWwOCLTOUSyPm4zkHa4MvrVwNxK4BL4F0L3bO4DxaM7RnhuKbqd0BdEzuo+TdLSnNOZY6B2W3mgFlSki2grMFxCoinAOBtBbg3ATS14zajP3FT+/WJgPzE3bS/XnPruDJ2HsdUUwL0/6DC78tDsfyEb4Vw3q858K4B7tiN0CNI5rd4Dj+fHajC+S4zBmdbOFOGbxlQm5VnHO4SPH85HNar/Pno6kwrzTZgah05KKlO8rQSKEuQXArHGugIuBawEVot+fzw3U5E+W/w9Js67utZkrd0c7H8kq31XJmvBvClYC5BuATfHLylOWSq92P0L87v8gh44I6V7XjcctiWVG0K2caxvzzIfguA2nht8qkzDVLNXVef3eYHSYVUnbaNZ0GuOBWY5dmSw/M18lLF+C0Hp4GxdMPWoPnBCZRgK/xmwPXRswUuhSUQDHl/+2JF4KkE7KUQLvX1q4q5O3Xt8mM5aKl0nxTcDrWxyl0KU4o2wlVvtCnXQTtYV9y0lwHXbyhQF16PHJ7+Ca3qs361vMk+pTw9NKPCTOtNYanHcqU5pTJPBccZELYC7vFEQF3ByDdSZBsAaudpv+canwX4UjAvgbB1Lodui7K1sh64Ebbjm25ayVptWu67btRyBbs4+PWHg+s3AKiL4ZnOd+/3HJvuqao01VkDZ6o0O5jmaXn75cGpwNSMY1imM6MEzDklWYNaTfUh/3fQFcLh5EC8v5BF+3PEaz1+tdAt0Fjvl1NAranpOQiXoDvnYvDQ9cBNXQjpDViGLc885jPQ/koGpH4De0Wb+mM3y1/RfTOQfQuBugCgpah7C0BT1elvA70qn2brUBWcZbX5x6H4i2C2KjTHV/e22yb3WwRleSaUQFmA5HeOUYmNAOyfnsA90Aibty7bl7jY141R6yMAXYRwCb5LwVuDrsH2Wf8o1+S/8RkHyfRGmXch9JuP3JWtuQ2mAEswzwe7XCPnAexbBNRGkFq25xi7sXO9KwSQNhP+TsJzPPI+KGRqk+A0aD5DJ14EyHrV6RXmJw6qMXAT24og1LQMlgZKb2bOKsoaIClJC1t/dxpQ9nfjB0h3rcqkdEyeTuH4VJ5TwbWlran++vLH9KkKXkC5uM0AuDQ3RuDNoVsCbm1FxE2AKTsXAYslYWEaP4PflqDV+Rtv4AjYmOb9tPkqA1WyMhWGPe8isES6Cp6HH828bM7YdGkvHKiNEOWp5mrUYDq1bGnKhDcVOl6O1GENoQ1uBx+n7kdwlsx0TUvN81Z4Sr4mpTmjKE+pJGsgbJp1LlN/OG/AaWl/avm7/YrAVaGyU8GXVXevZpRvg+IdAZaK9Ius4zVV+1Wn6pRbVLLpTWugVZeBHist9zLIlgJg0UUw5R7Qfoz9rwumwPFwvVCgNoLUQ3QcSJI5N4xmhOd4gE2FlnyeCk8LEOV+Tk3PfZs1c11VZ644c2DmVzX+rgDzGFC2gHE19J4UFO5XGIEPFszxS83K87DNzud1o2mfnVMLrI8BcRW8a4DrFe3NJgJVz0lv3NRf2zvY2pn3ULS2vnYtZLW9qF7jqNYCXM0ugfVgvSCgNtw5BtDclC8Fk8wPGpcraQPe/xkBqsfSYBFTOihP65jBU9O5jddjhjwO5GqqT0EzB+bwO4By8dWdguQiOJaA2HCZzpWlb/TptrbfNQClta6j8xHQV21AngPwWviOwDs9Pn2ibhW0erNERRuVUVx/G/Ikil8By/JfqCdI6nkW0mxwP3THPstuizTQlV6O8XItPX4GwF42UOtm/Hj++nWfPgofAcpF8ikczXS3pUlT8PzAKVWrxfyc0b85D84IBZ0tGtCpq1J3rAbKWUieAYwnhdvNhUf/b08XzT8LxGeUcQ3AS8BbgG1ZnWIyB9BGmBpsU9fBWM3mboMcsgrYuNVWFKQBLl9C2zQFO145MOZKkjKvbS4XqK0wTU35eMbRB5oO0liFjpcrmQk/XpLU4U0dbonZnvk3/ah3m1RVdc48T/OlvewyeEbV2uJzPAFAVwHz0sE4c7uc/PAKEJ8EuA2uh2MhC8CmQL1KzP/EZwfAat7oLoAbYPSQ6gdXQe1FhXTpluiR4Zqpet1sch+swTVforUaqvH2L82XywNqbtaXzXk9F2/Opwvn47nWVaiOzG1gVWk9p19yFFRogOdYUdbBmV8BVaYa+U6g6pRmWbEeCcpmSP4BwDirsk9Ou7YK58zrtloW5KKZ/XVb/qPhu0LZOlWbBzrUhNNAWTxWAe2gYvX+rLsKzB9bh6yW9+o1Va5xMCNcx0GaHLAr3QGXA9Tn4bxjdD6dVbWgEpXo+N12vmGk5cevYarvkzB77ca1Dk/rh1a4AJwllRnAYcCM4FRYjtO19aqtMQvJM8BxNfyusyCV+Qzvj1ue1T9Muwy63elM9mRS3rX5PHM8ngXSM2p4NXwr0MU5jEz+AmxjACIFbb9J/bOSb/DJpko2AteWb/FvIUwBtuR7bfW5rlKu8fa8HKD+WT7t8JsQrQeVIkjjMiYFafSFxgi8+kB1K8NzDC7n74Spnh8f4Adw+mOqQKNpHiEZFWbN3E+A6mA5BuqJQNkExxyEhUuVJ81BrqGKtzrLIog3gPlkEJ4A70Lo4g/fDA+UCM4UtHrT6Jpirwptv098swrZJF8Bsj7oFVcU3AzFbAVBBLGpV3ML8IgCNrZF9Tq1YsD7WyfU65LFdef9f0oZUPn9v+FeSk16TfSRefpDoxKNNyDNeKrQX0O5GEjp+/yYMO0677MeFsN75akL3eHHTCE6Y6ZzOVAEYqq6cuU5AmqAZ0x/H3VlAaylhKnC8pmrqUEdrobjIVOOT9HuHpM4T6+dWK48qTRn1OjG1OhcvrzNNSr2VVYJz23F1gRfvwLgRbmRo6FbcDdMQLYESK5UMOUKn+jQz971LcLUvbxBuA0vNnyZuAwkv3tJoRcs2HrZG2mD/le757lMKw6QD2ylbgHNk75QoGnfw+cX2RinS7H0YAGslwPUf3AnYCAtReipRhWiCh9To+YLZZpF5DWApBsGs7A4ntCSrRIsGvk6R8ozNdVjvzL/qLRxv/Gvl6aQVcU5p1yzq5wo4dGxTYOyXA1L35oHJKGZb0vhFsr3rt4uwMqnFVratObLy1q5Up3FtDkAe9iuBK1vtwm6E0p3NWzrirZ3sC2qT7uM8q1qNsI0fVECMI3H3HlHBVtzEUTrlIEu3fw6WINr+ncJbEkWX4uVW1PKmVugtkqgAaqXA9QfuWFUv2g6jw2kClA9GANKMa9F4fk08kC1MgGgUoea8VLfhxzV7BXJzN/JP4FWU5oJCAumuh5PoVmC51i5qutgbPLPwPJoUJYgOQHGOdClF3PBr+s39CbV3ZJbob3/k6A2KJ9I6cpEngN9BborgMu/TTsAMoyI3pyp6V6HbR2yg6vg91qx1uHfDIuAjfVz5YAB1q8ioHqV+89dY32xIILV2iBgvb81XSWg9UwEsJbMovOa/P84AVGeRFSi0Yy3eU1wKkBT8JThKdec//nA+T4BzyHdgTOmlRWnh11s+2ZCiWaBp2qQ6rovqVmdXUsV35yJfT0G9ipAtsDv0BiAemIX9w1/v25sb98QkFoB6SKA72ZcCQsV8CR024FbB6WCdgTbgqItAtmrWe8q+OrawVUvUw/I6je3q+w4FSsDXKZcrQwBG5WrpipcU5eNh2tJtRYCWP3zxvlDCC2JYLVXqzm7H4cScZlTHlyK78Kb8jSfiFei5nd06pM1B3hKUwGesg94WleL5nbm2/RKU8uH7le+hzxoMwWkgqXbvKen78arC8Csmf/joa0B81hQ1gC5EIr9Q6PKfFgIW6t3h5uG+/y2jWC8Cmk+H4+XoLnDzZS3z7SGrbN2j4XxAgAvAu8pgPsyDER8kKiKVNO9DMZxOouYsk3KzKpap2a9mgZk07YNsApX3Uyt5urVg5X54uuwXrmqWyBLine truncated

frontend-web/src/components/ai-elements/artifact.tsx

@@ -16,7 +16,7 @@ export type ArtifactProps = HTMLAttributes<HTMLDivElement>;
 export const Artifact = ({ className, ...props }: ArtifactProps) => (
   <div
     className={cn(
-      "flex flex-col overflow-hidden rounded-[1.35rem] border border-[#ece7dd] bg-white shadow-[0_24px_60px_-28px_rgba(15,23,42,0.16)] ring-1 ring-black/3",
+      "flex flex-col overflow-hidden rounded-[1.35rem] border border-border bg-background shadow-[0_24px_60px_-28px_rgba(15,23,42,0.16)] ring-1 ring-black/3",
       className,
     )}
     {...props}
@@ -31,7 +31,7 @@ export const ArtifactHeader = ({
 }: ArtifactHeaderProps) => (
   <div
     className={cn(
-      "flex items-center justify-between border-b border-[#efe9de] bg-white px-4 py-3",
+      "flex items-center justify-between border-b border-border bg-background px-4 py-3",
       className,
     )}
     {...props}
@@ -147,7 +147,7 @@ export const ArtifactContent = forwardRef<HTMLDivElement, ArtifactContentProps>(
     <div
       ref={ref}
       className={cn(
-        "min-h-0 flex-1 overflow-auto bg-white p-4",
+        "min-h-0 flex-1 overflow-auto bg-background p-4",
         className,
       )}
       {...props}

frontend-web/src/components/font-scale.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { useEffect } from "react";
+
+import { useLocalSettings } from "@/core/settings";
+
+/**
+ * 基准字号 = 16px，对应《深蓝色 UI 规范》§2.1.2 后台系统正文字号（16px Regular）。
+ * 用户在「外观 → 字号」里选择的倍数通过 CSS 变量 `--ui-font-scale` 生效：globals.css
+ * 只把 Tailwind 的 `--text-*` 字号 token 乘以该倍数，**不动间距 token**，所以放大 / 缩小
+ * 的只有文字本身，padding / margin / 宽高等布局尺寸保持不变，不会把页面挤错位。
+ * `fontScale === 1` 即默认 16px。
+ */
+export const BASE_FONT_PX = 16;
+
+export const FONT_SCALE_OPTIONS: { value: number; label: string; px: number }[] =
+  [
+    { value: 0.875, label: "小", px: 14 },
+    { value: 1, label: "标准", px: 16 },
+    { value: 1.125, label: "大", px: 18 },
+    { value: 1.25, label: "特大", px: 20 },
+  ];
+
+/**
+ * 把用户选择的字号倍数写到 <html> 的 `--ui-font-scale` CSS 变量。挂在应用根部，
+ * 保证刷新后即时生效、全局统一。只设变量、不直接改 font-size，因此布局不受影响。
+ * 不渲染任何 DOM。
+ */
+export function FontScaleApplier() {
+  const [settings] = useLocalSettings();
+  const { fontScale } = settings.display;
+
+  useEffect(() => {
+    const scale =
+      typeof fontScale === "number" && Number.isFinite(fontScale) && fontScale > 0
+        ? fontScale
+        : 1;
+    const root = document.documentElement;
+    root.style.setProperty("--ui-font-scale", String(scale));
+    // 清掉旧实现可能残留的根级 font-size 内联样式（旧版用它做整页缩放）。
+    root.style.removeProperty("font-size");
+  }, [fontScale]);
+
+  return null;
+}

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

@@ -0,0 +1,322 @@
+.sidebar-contnet {
+    position: fixed;
+    left: 0;
+    top: 4rem;
+    z-index: 40;
+    width: 98px;
+    height: calc(100vh - 4rem);
+    flex-shrink: 0;
+}
+
+.sidebar-contents {
+    width: 98px;
+    min-height: calc(100% - 20px);
+    background: rgba(3, 38, 80, 0.8);
+    border: 1px solid;
+    border-color: rgba(43, 143, 254, 0.6);
+    border-radius: 4px;
+    backdrop-filter: blur(2px);
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    padding: 12px 10px;
+    position: relative;
+    height: calc(100% - 20px);
+    box-sizing: border-box;
+    transform: translate(10px, 10px);
+}
+
+.item-nav-group {
+    width: 100%;
+}
+
+.item-nav-wrap {
+    position: relative;
+    width: 100%;
+}
+
+.item-nav-group:first-child .item-nav {
+    margin-top: 0;
+}
+
+.item-nav {
+    width: 100%;
+    height: 75px;
+    margin-top: 13px;
+    font-family: Noto Sans S Chinese;
+    font-weight: 500;
+    color: #fff;
+    font-size: 20px;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    cursor: pointer;
+    background: #000c1c26;
+    border: 1px solid;
+    border-color: #55a6fe33;
+    box-shadow: 0 0 20px #00b9ff26 inset;
+    position: relative;
+}
+
+.item-nav:hover,
+.item-nav-active,
+.item-nav-hovered {
+    color: #ffffff;
+    background: linear-gradient(134.25deg,
+            rgba(0, 98, 217, 0.59) 2.28%,
+            rgba(0, 98, 217, 0.3) 99.59%) !important;
+    background-size: cover;
+    border: 1px solid;
+    border-color: rgba(255, 255, 255, 0.2);
+    position: relative;
+}
+
+.item-nav:hover::before,
+.item-nav-active::before,
+.item-nav-hovered::before {
+    content: '';
+    position: absolute;
+    right: -10px;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 0;
+    height: 0;
+    border-top: 8px solid transparent;
+    border-bottom: 8px solid transparent;
+    border-left: 10px solid rgba(0, 98, 217, 0.45);
+    pointer-events: none;
+}
+
+.item-nav:hover::after,
+.item-nav-active::after,
+.item-nav-hovered::after {
+    content: '';
+    position: absolute;
+    left: 0;
+    top: 29px;
+    width: 77px;
+    height: 45px;
+    background: url('../assets/icon/nav-line-logo.svg') no-repeat;
+    background-size: cover;
+}
+
+.item-nav__label {
+    display: block;
+    width: 3em;
+    margin: 0 auto;
+    padding-left: 6px;
+    box-sizing: border-box;
+    letter-spacing: 6px;
+    word-break: break-all;
+}
+
+.item-nav-content {
+    width: 155px;
+    height: calc(100vh - 4rem - 20px);
+    min-height: calc(100vh - 4rem - 20px);
+    background: rgba(3, 38, 80, 0.8);
+    border: 1px solid;
+    border-color: rgba(43, 143, 254, 0.6);
+    border-radius: 4px;
+    backdrop-filter: blur(2px);
+    position: absolute;
+    left: 108px;
+    top: 0;
+    z-index: 1000;
+    padding: 14px 13px 18px 16px;
+    overflow-y: auto;
+    opacity: 0;
+    visibility: hidden;
+    pointer-events: none;
+    transition: opacity 0.2s ease, visibility 0.2s ease;
+}
+
+.item-nav-content::before {
+    content: '';
+    position: absolute;
+    left: -30px;
+    top: 0;
+    width: 30px;
+    height: 100%;
+}
+
+.item-nav-hover-bridge {
+    position: absolute;
+    right: -30px;
+    top: 0;
+    width: 30px;
+    height: 100%;
+    z-index: 999;
+}
+
+.item-nav-content--visible {
+    opacity: 1;
+    visibility: visible;
+    pointer-events: auto;
+}
+
+.sidebar-flyout-list {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    position: relative;
+}
+
+.sidebar-flyout-list--level-1,
+.sidebar-flyout-list--level-2,
+.sidebar-flyout-list--level-3 {
+    margin-left: 19px;
+    padding-left: 14px;
+}
+
+.sidebar-flyout-node {
+    position: relative;
+}
+
+.sidebar-flyout-node--has-children.sidebar-flyout-node--expanded>.sidebar-flyout-list::before {
+    content: '';
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 1px;
+    height: 100%;
+    background: rgba(43, 143, 254, 0.22);
+}
+
+.sidebar-flyout-item {
+    width: 100%;
+    min-height: 34px;
+    display: flex;
+    align-items: center;
+    gap: 9px;
+    border: 0;
+    background: transparent;
+    padding: 3px 0;
+    font-family: Noto Sans S Chinese;
+    font-size: 18px;
+    line-height: 16px;
+    font-weight: 500;
+    letter-spacing: 0;
+    color: rgba(255, 255, 255, 0.8);
+    text-align: left;
+    cursor: pointer;
+    transition: color 0.2s ease, text-shadow 0.2s ease;
+}
+
+.sidebar-flyout-item:hover,
+.sidebar-flyout-item--active {
+    color: #48ddff;
+    text-shadow: 0 0 8px rgba(72, 221, 255, 0.25);
+}
+
+.sidebar-flyout-item--leaf {
+    justify-content: center;
+    padding-left: 0;
+}
+
+.sidebar-flyout-list--level-1>.sidebar-flyout-node>.sidebar-flyout-item--leaf,
+.sidebar-flyout-list--level-2>.sidebar-flyout-node>.sidebar-flyout-item--leaf,
+.sidebar-flyout-list--level-3>.sidebar-flyout-node>.sidebar-flyout-item--leaf {
+    padding-left: 0;
+}
+
+.sidebar-flyout-arrow {
+    width: 9px;
+    height: 9px;
+    flex: 0 0 9px;
+    background: url('../assets/icon/down-logo.svg') center / contain no-repeat;
+    transform: rotate(-90deg);
+    transition: transform 0.2s ease;
+}
+
+.sidebar-flyout-node--expanded>.sidebar-flyout-item>.sidebar-flyout-arrow {
+    transform: rotate(0deg);
+}
+
+.sidebar-flyout-label {
+    flex: 1;
+    white-space: nowrap;
+}
+
+.sidebar-collapse-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    border-radius: 8px;
+    cursor: pointer;
+}
+
+.sidebar-collapse-btn__icon {
+    width: 16px;
+    height: 16px;
+    flex: 0 0 16px;
+    color: #80e9ff;
+}
+
+.sidebar-collapse-btn__label {
+    font-size: 14px;
+    line-height: 1;
+    white-space: nowrap;
+}
+
+.sidebar-collapse-btn--inline {
+    width: calc(100% - 6px);
+    min-height: 58px;
+    margin-top: auto;
+    margin-bottom: 2px;
+    flex-direction: column;
+    gap: 6px;
+    border: 1px solid #55a6fe33;
+    background: #000c1c26;
+    color: rgba(255, 255, 255, 0.9);
+    box-shadow: inset 0 0 16px #00b9ff1f;
+    transition: background-color 0.2s ease, border-color 0.2s ease;
+}
+
+.sidebar-collapse-btn--inline .sidebar-collapse-btn__label {
+    font-size: 16px;
+    line-height: 1.1;
+}
+
+.sidebar-collapse-btn--inline:hover {
+    background: rgba(0, 98, 217, 0.3);
+    border-color: rgba(255, 255, 255, 0.25);
+}
+
+.sidebar-collapse-btn--floating {
+    position: fixed;
+    left: 10px;
+    bottom: 10px;
+    z-index: 60;
+    width: 36px;
+    height: 36px;
+    min-height: 36px;
+    padding: 0 10px;
+    border: 1px solid rgba(128, 233, 255, 0.35);
+    background: rgba(3, 38, 80, 0.82);
+    color: rgba(205, 245, 255, 0.95);
+    backdrop-filter: blur(2px);
+    transition: width 0.22s ease, opacity 0.2s ease, background-color 0.2s ease, border-color 0.2s ease;
+    overflow: hidden;
+}
+
+.sidebar-collapse-btn--floating:hover {
+    width: 104px;
+    background: rgba(7, 52, 110, 0.9);
+    border-color: rgba(128, 233, 255, 0.65);
+}
+
+.sidebar-collapse-btn--floating .sidebar-collapse-btn__label {
+    max-width: 0;
+    opacity: 0;
+    transform: translateX(-4px);
+    transition: max-width 0.22s ease, opacity 0.16s ease, transform 0.22s ease;
+}
+
+.sidebar-collapse-btn--floating:hover .sidebar-collapse-btn__label {
+    max-width: 64px;
+    opacity: 1;
+    transform: translateX(0);
+}

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

@@ -0,0 +1,237 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useNavigate, useLocation } from "react-router-dom";
+import { PanelLeftOpen, PanelLeftClose } from "lucide-react";
+
+import { getStoredAuth } from "@/core/auth";
+import {
+  defaultExpandedIds,
+  filterMenuItemsByRole,
+  sidebarMenuItems,
+  type MenuItem,
+} from "@/core/page-layout/sidebar-menu";
+import './page-sdebar.css'
+
+type PageSidebarDarkProps = {
+  /** 是否收起（true 时只渲染左下角浮动入口，sidebar 主体隐藏） */
+  collapsed: boolean;
+  onToggleCollapsed: () => void;
+};
+
+export function PageSidebarDark({ collapsed, onToggleCollapsed }: PageSidebarDarkProps) {
+  const isAdmin = getStoredAuth()?.system_role === "admin";
+  const visibleMenuItems = useMemo(
+    () => filterMenuItemsByRole(sidebarMenuItems, !!isAdmin),
+    [isAdmin],
+  );
+  // defaultExpandedIds 是共享的 ReadonlySet，复制一份给 useState（避免外部突变）
+  const [expandedIds, setExpandedIds] = useState<Set<string>>(() => new Set(defaultExpandedIds));
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+
+  // pathname 变化时取消任何未触发的 hover 关闭计时（cleanup 在卸载时也跑）
+  useEffect(() => {
+    return () => {
+      if (hoverCloseTimerRef.current !== null) {
+        window.clearTimeout(hoverCloseTimerRef.current);
+      }
+    };
+  }, []);
+
+  const handleNavHoverEnter = (id: string) => {
+    if (hoverCloseTimerRef.current !== null) {
+      window.clearTimeout(hoverCloseTimerRef.current);
+      hoverCloseTimerRef.current = null;
+    }
+    setHoveredTopId(id);
+  };
+
+  const scheduleNavPanelClose = () => {
+    if (hoverCloseTimerRef.current !== null) {
+      window.clearTimeout(hoverCloseTimerRef.current);
+    }
+    hoverCloseTimerRef.current = window.setTimeout(() => {
+      setHoveredTopId(null);
+      hoverCloseTimerRef.current = null;
+    }, 180);
+  };
+
+  const closeNavPanel = () => {
+    if (hoverCloseTimerRef.current !== null) {
+      window.clearTimeout(hoverCloseTimerRef.current);
+      hoverCloseTimerRef.current = null;
+    }
+    setHoveredTopId(null);
+  };
+
+  const hasActiveChild = (item: MenuItem): boolean => {
+    if (item.path && pathname === item.path) {
+      return true;
+    }
+
+    return item.children?.some(hasActiveChild) ?? false;
+  };
+
+  // lazy init：仅在首次 render 计算一次 active id；之后由下面的 useEffect 跟随 pathname 同步
+  const [activeTopId, setActiveTopId] = useState<string>(
+    () => visibleMenuItems.find(hasActiveChild)?.id ?? visibleMenuItems[0]?.id ?? "qa-center",
+  );
+  const [hoveredTopId, setHoveredTopId] = useState<string | null>(null);
+  const hoverCloseTimerRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    const matchedTopItem = visibleMenuItems.find(hasActiveChild);
+    if (matchedTopItem) {
+      setActiveTopId(matchedTopItem.id);
+    }
+    closeNavPanel();
+  }, [pathname, visibleMenuItems]);
+
+  const toggleExpanded = (id: string) => {
+    setExpandedIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+  };
+
+  const findFirstRoutePath = (items?: MenuItem[]): string | null => {
+    if (!items?.length) {
+      return null;
+    }
+
+    for (const child of items) {
+      if (child.path) {
+        return child.path;
+      }
+      const nestedPath = findFirstRoutePath(child.children);
+      if (nestedPath) {
+        return nestedPath;
+      }
+    }
+
+    return null;
+  };
+
+  const handleTopItemClick = (item: MenuItem) => {
+    setActiveTopId(item.id);
+
+    if (item.children?.length) {
+      const firstPath = findFirstRoutePath(item.children);
+      if (firstPath) {
+        closeNavPanel();
+        navigate(firstPath);
+      }
+      return;
+    }
+
+    if (item.path) {
+      closeNavPanel();
+      navigate(item.path);
+    }
+  };
+
+  const handleMenuItemClick = (item: MenuItem) => {
+    if (item.children?.length) {
+      toggleExpanded(item.id);
+      return;
+    }
+
+    if (item.path) {
+      closeNavPanel();
+      navigate(item.path);
+    }
+  };
+
+  const renderFlyoutMenu = (items: MenuItem[], level = 0) => (
+    <div className={`sidebar-flyout-list sidebar-flyout-list--level-${level}`}>
+      {items.map((item) => {
+        const hasChildren = !!item.children?.length;
+        const isExpanded = expandedIds.has(item.id);
+        const isSelected = item.path ? pathname === item.path : hasActiveChild(item);
+
+        return (
+          <div
+            key={item.id}
+            className={`sidebar-flyout-node sidebar-flyout-node--level-${level} ${hasChildren ? "sidebar-flyout-node--has-children" : ""} ${isExpanded ? "sidebar-flyout-node--expanded" : ""}`}
+          >
+            <button
+              type="button"
+              className={`sidebar-flyout-item ${isSelected ? "sidebar-flyout-item--active" : ""} ${hasChildren ? "sidebar-flyout-item--parent" : "sidebar-flyout-item--leaf"}`}
+              onClick={() => handleMenuItemClick(item)}
+            >
+              {hasChildren ? <span className="sidebar-flyout-arrow" aria-hidden="true" /> : null}
+              <span className="sidebar-flyout-label">{item.label}</span>
+            </button>
+            {hasChildren && isExpanded ? renderFlyoutMenu(item.children ?? [], level + 1) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+  // collapsed 状态：sidebar 主体完全消失（包括占据的宽度），只渲染左下角浮动入口
+  if (collapsed) {
+    return (
+      <button
+        type="button"
+        title="展开侧边栏"
+        aria-label="展开侧边栏"
+        className="sidebar-collapse-btn sidebar-collapse-btn--floating"
+        onClick={onToggleCollapsed}
+      >
+        <PanelLeftOpen className="sidebar-collapse-btn__icon" aria-hidden="true" />
+        <span className="sidebar-collapse-btn__label">收起面板</span>
+      </button>
+    );
+  }
+
+  return (
+    <aside className="sidebar-contnet">
+      <div className="sidebar-contents">
+        {visibleMenuItems.map((item) => (
+          <div
+            key={item.id}
+            className="item-nav-group"
+            onMouseEnter={() => handleNavHoverEnter(item.id)}
+            onMouseLeave={scheduleNavPanelClose}
+          >
+            {item.children?.length ? (
+              <div
+                className={`item-nav-content ${hoveredTopId === item.id ? "item-nav-content--visible" : ""}`}
+              >
+                {renderFlyoutMenu(item.children)}
+              </div>
+            ) : null}
+            <div className="item-nav-wrap">
+              <button
+                type="button"
+                className={`item-nav ${item.id === activeTopId ? "item-nav-active" : ""} ${hoveredTopId === item.id ? "item-nav-hovered" : ""}`}
+                onClick={() => handleTopItemClick(item)}
+              >
+                <span className="item-nav__label">{item.label}</span>
+              </button>
+              {item.children?.length && hoveredTopId === item.id ? (
+                <span className="item-nav-hover-bridge" aria-hidden="true" />
+              ) : null}
+            </div>
+          </div>
+        ))}
+
+        {/* 底部"收起面板"按钮：独立样式，mt-auto 推到底 */}
+        <button
+          type="button"
+          title="收起侧边栏"
+          aria-label="收起侧边栏"
+          className="sidebar-collapse-btn sidebar-collapse-btn--inline"
+          onClick={onToggleCollapsed}
+        >
+          <PanelLeftClose className="sidebar-collapse-btn__icon" aria-hidden="true" />
+          <span className="sidebar-collapse-btn__label">收起面板</span>
+        </button>
+      </div>
+    </aside>
+  );
+}

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

@@ -1,39 +1,14 @@
 import { useEffect, useState } from "react";
-import type { ElementType } from "react";
 import { useNavigate, useLocation } from "react-router-dom";
 import {
   Bell,
-  Bot,
-  Brain,
-  CalendarClock,
   ChevronLeft,
   ChevronRight,
   ChevronsUpDown,
-  CircleHelp,
-  Database,
-  FileBox,
-  FileText,
   Folder,
   FolderOpen,
-  Gauge,
-  Grid3X3,
-  HelpCircle,
-  History,
-  Layout,
-  Library,
-  List,
-  ListChecks,
-  ListTodo,
-  MessageSquareCode,
-  MessageSquarePlus,
-  Network,
-  NotebookPen,
-  Plus,
   Settings,
-  Sparkles,
-  Target,
   User,
-  Users,
   Wrench,
 } from "lucide-react";
 
@@ -49,14 +24,12 @@ import { useTheme } from "@/contexts/ThemeContext";
 import { getStoredAuth } from "@/core/auth";
 import { useI18n } from "@/core/i18n/hooks";
 import { useUnreadCount } from "@/core/notifications";
-type MenuItem = {
-  id: string;
-  label: string;
-  icon: ElementType;
-  path?: string;
-  adminOnly?: boolean;
-  children?: MenuItem[];
-};
+import {
+  defaultExpandedIds,
+  filterMenuItemsByRole,
+  sidebarMenuItems,
+  type MenuItem,
+} from "@/core/page-layout/sidebar-menu";
 
 type PageSidebarProps = {
   collapsed: boolean;
@@ -65,180 +38,6 @@ type PageSidebarProps = {
 
 type SettingsSection = "account" | "appearance" | "memory" | "tools" | "about";
 
-const menuItems: MenuItem[] = [
-  {
-    id: "qa-center",
-    label: "问答中心",
-    icon: HelpCircle,
-    children: [
-      { id: "general-qa", label: "通用问答", icon: CircleHelp, path: "/page/workspace/chats/new" },
-      { id: "qa-zzjc", label: "zzjc支持", icon: Bot },
-      { id: "qa-zzxd", label: "zzXD应用", icon: Layout },
-      { id: "qa-research", label: "课题研究", icon: FileText, path: "/page/canvas/ai-writing" },
-    ],
-  },
-  {
-    id: "light-app-center",
-    label: "轻应用",
-    icon: Grid3X3,
-    children: [
-      {
-        id: "light-app-note-management",
-        label: "笔记管理",
-        icon: NotebookPen,
-        children: [
-          {
-            id: "light-app-new-note",
-            label: "新建笔记",
-            icon: Plus,
-            path: "/page/strategy/light-app/new-note",
-          },
-          {
-            id: "light-app-note-list",
-            label: "笔记列表",
-            icon: List,
-            path: "/page/strategy/light-app/notes",
-          },
-        ],
-      },
-      { id: "light-app-square", label: "应用广场", icon: Layout },
-      { id: "light-app-records", label: "运行记录", icon: History },
-    ],
-  },
-  {
-    id: "task-management",
-    label: "任务管理",
-    icon: Target,
-    children: [
-      {
-        id: "xk-center-task",
-        label: "XK中任务",
-        icon: Folder,
-        children: [
-          { id: "xk-task-jc", label: "任务JC", icon: ListTodo },
-          { id: "xk-task-dispatch", label: "任务调度", icon: ListTodo },
-        ],
-      },
-      {
-        id: "coh-center-task",
-        label: "COH中任务",
-        icon: Folder,
-        children: [
-          { id: "coh-task-3qfx", label: "3QFX", icon: ListTodo },
-          { id: "coh-task-fx", label: "任务FX", icon: ListTodo },
-          { id: "coh-task-xdfx", label: "XDFX", icon: ListTodo },
-        ],
-      },
-      {
-        id: "pg-center-task",
-        label: "PG中任务",
-        icon: Folder,
-        children: [
-          { id: "pg-task-pg", label: "任务PG", icon: ListTodo },
-          { id: "pg-task-xdpg", label: "XDPG", icon: ListTodo },
-          { id: "pg-task-info-pg", label: "信息PG", icon: ListTodo },
-        ],
-      },
-      {
-        id: "ty-center-task",
-        label: "TY中任务",
-        icon: Folder,
-        children: [
-          { id: "ty-task-xdty", label: "XDTY任务", icon: ListTodo },
-          { id: "ty-task-plan", label: "方案TY任务", icon: ListTodo },
-          { id: "ty-task-xxty", label: "XXTY任务", icon: ListTodo },
-        ],
-      },
-    ],
-  },
-  {
-    id: "comprehensive-management",
-    label: "综合管理",
-    icon: Settings,
-    children: [
-      { id: "mgmt-agents", label: "智能体管理", icon: Bot, path: "/page/strategy/agents" },
-      { id: "mgmt-skills", label: "技能管理", icon: Sparkles, path: "/page/strategy/skills" },
-      { id: "mgmt-memory", label: "记忆管理", icon: Brain, path: "/page/strategy/memory" },
-      {
-        id: "mgmt-tasks",
-        label: "任务管理",
-        icon: ListChecks,
-        path: "/page/strategy/scheduled/tasks",
-      },
-      {
-        id: "mgmt-recommended-questions",
-        label: "推荐问题配置",
-        icon: MessageSquarePlus,
-        path: "/page/strategy/settings/recommended-questions",
-        adminOnly: true,
-      },
-      {
-        id: "mgmt-prompt-prefix",
-        label: "问答前缀配置",
-        icon: MessageSquareCode,
-        path: "/page/strategy/settings/prompt-prefix",
-        adminOnly: true,
-      },
-      {
-        id: "mgmt-llm-metrics",
-        label: "大模型调用统计",
-        icon: Gauge,
-        path: "/page/strategy/settings/llm-metrics",
-        adminOnly: true,
-      },
-      {
-        id: "mgmt-users",
-        label: "用户管理",
-        icon: Users,
-        path: "/page/strategy/admin/users",
-        adminOnly: true,
-      },
-      {
-        id: "mgmt-admin-scheduled-tasks",
-        label: "定时任务管理",
-        icon: CalendarClock,
-        path: "/page/strategy/admin/scheduled-tasks",
-        adminOnly: true,
-      },
-      {
-        id: "mgmt-user-activity",
-        label: "用户活动审计",
-        icon: History,
-        path: "/page/strategy/admin/user-activity",
-        adminOnly: true,
-      },
-    ],
-  },
-  {
-    id: "resource-management",
-    label: "资源管理",
-    icon: Database,
-    children: [
-      { id: "resource-network-xwt", label: "网络xwt资源管理", icon: Network },
-      { id: "resource-knowledge-base", label: "知识库资源管理", icon: Library },
-      { id: "resource-zz", label: "ZZ资源管理", icon: FileBox },
-    ],
-  },
-];
-
-const defaultExpandedIds = new Set([
-  "qa-center",
-  "light-app-center",
-  "light-app-note-management",
-  "task-management",
-  "xk-center-task",
-]);
-
-function filterMenuItemsByRole(items: MenuItem[], isAdmin: boolean): MenuItem[] {
-  return items
-    .filter((item) => !item.adminOnly || isAdmin)
-    .map((item) =>
-      item.children
-        ? { ...item, children: filterMenuItemsByRole(item.children, isAdmin) }
-        : item,
-    );
-}
-
 export function PageSidebar({
   collapsed,
   onToggleCollapsed,
@@ -246,10 +45,11 @@ export function PageSidebar({
   const { theme } = useTheme();
   const isDark = theme === "dark";
   const isAdmin = getStoredAuth()?.system_role === "admin";
-  const visibleMenuItems = filterMenuItemsByRole(menuItems, !!isAdmin);
+  const visibleMenuItems = filterMenuItemsByRole(sidebarMenuItems, !!isAdmin);
   const { t } = useI18n();
   const { data: unreadCount = 0 } = useUnreadCount();
-  const [expandedIds, setExpandedIds] = useState<Set<string>>(defaultExpandedIds);
+  // defaultExpandedIds 是共享的 ReadonlySet，复制一份给 useState（避免外部突变）
+  const [expandedIds, setExpandedIds] = useState<Set<string>>(() => new Set(defaultExpandedIds));
   const [settingsOpen, setSettingsOpen] = useState(false);
   const [settingsDefaultSection, setSettingsDefaultSection] =
     useState<SettingsSection>("appearance");
@@ -388,63 +188,26 @@ export function PageSidebar({
         onOpenChange={setNotificationOpen}
       />
       <aside
-        className={`fixed left-0 top-0 z-40 flex h-screen flex-col overflow-hidden shadow-sm theme-transition transition-all duration-300 ${
+        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 ${
           isDark
             ? "border-r border-blue-800/30 bg-slate-900"
             : "border-r border-red-100 bg-white"
         } ${collapsed ? "w-16" : "w-64"}`}
       >
-      <div
-        className={`flex h-16 items-center theme-transition ${
-          isDark ? "border-b border-blue-800/30" : "border-b border-red-100"
-        } ${collapsed ? "justify-center px-2" : "justify-between px-6"}`}
+      <button
+        type="button"
+        onClick={onToggleCollapsed}
+        title={collapsed ? "展开侧边栏" : "收起侧边栏"}
+        className={`absolute -right-3 top-6 z-50 flex h-6 w-6 items-center justify-center rounded-full shadow-md theme-transition ${
+          isDark
+            ? "bg-slate-700 text-slate-300 hover:bg-slate-600"
+            : "bg-white text-gray-500 hover:bg-red-50 hover:text-red-600 border border-red-100"
+        }`}
       >
-        <div className="flex min-w-0 items-center gap-3">
-          <div
-            className={`flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-lg transition-transform duration-300 ease-out ${
-              isDark
-                ? "bg-gradient-to-br from-blue-500 to-cyan-400"
-                : "bg-gradient-to-br from-red-500 to-red-400"
-            }`}
-          >
-            <FileText className="h-4 w-4 text-white" />
-          </div>
-          {!collapsed && (
-            <div className="overflow-hidden whitespace-nowrap animate-in fade-in-0 slide-in-from-left-2 duration-300">
-              <h1
-                className={`text-sm font-semibold theme-transition ${
-                  isDark ? "text-white" : "text-gray-900"
-                }`}
-              >
-                CM助手
-              </h1>
-            </div>
-          )}
-        </div>
-        {!collapsed && (
-          <button
-            type="button"
-            onClick={onToggleCollapsed}
-            className={iconButtonClass}
-            title="Collapse sidebar"
-          >
-            <ChevronLeft className="h-4 w-4" />
-          </button>
-        )}
-      </div>
+        {collapsed ? <ChevronRight className="h-3 w-3" /> : <ChevronLeft className="h-3 w-3" />}
+      </button>
 
       <nav className={`flex-1 overflow-y-auto ${collapsed ? "p-2" : "p-4"} space-y-2 transition-all duration-300 ease-out`}>
-        {collapsed && (
-          <button
-            type="button"
-            onClick={onToggleCollapsed}
-            className={`flex w-full items-center justify-center ${iconButtonClass}`}
-            title="Expand sidebar"
-          >
-            <ChevronRight className="h-5 w-5" />
-          </button>
-        )}
-
         {visibleMenuItems.map((item) =>
           item.children ? renderBranch(item) : renderLeaf(item),
         )}

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

@@ -1,6 +1,6 @@
-import * as React from "react";
-import { Slot } from "@radix-ui/react-slot";
-import { cva, type VariantProps } from "class-variance-authority";
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
 
 import { cn } from "@/lib/utils";
 
@@ -14,7 +14,7 @@ const buttonVariants = cva(
         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:
-          "cursor-pointer border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
+          "cursor-pointer border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:border-[#213D5E] dark:bg-[#022248] dark:text-[#CCD2DA] dark:hover:border-[#213D5E] dark:hover:bg-[#0a2f58] dark:hover:text-[#CCD2DA] dark:[&_svg]:text-[#CCD2DA]",
         secondary:
           "cursor-pointer bg-secondary text-secondary-foreground hover:bg-secondary/80",
         ghost:
@@ -37,27 +37,27 @@ const buttonVariants = cva(
   },
 );
 
-const Button = React.forwardRef<
-  HTMLButtonElement,
-  React.ComponentProps<"button"> &
-    VariantProps<typeof buttonVariants> & {
-      asChild?: boolean;
-    }
->(({ className, variant = "default", size = "default", asChild = false, ...props }, ref) => {
-  const Comp = asChild ? Slot : "button";
-
-  return (
-    <Comp
-      ref={ref}
-      data-slot="button"
-      {...(variant !== undefined && { "data-variant": variant })}
-      {...(size !== undefined && { "data-size": size })}
-      className={cn(buttonVariants({ variant, size, className }))}
-      {...props}
-    />
-  );
-});
-
-Button.displayName = "Button";
-
-export { Button, buttonVariants };
+const Button = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentProps<"button"> &
+    VariantProps<typeof buttonVariants> & {
+      asChild?: boolean;
+    }
+>(({ className, variant = "default", size = "default", asChild = false, ...props }, ref) => {
+  const Comp = asChild ? Slot : "button";
+
+  return (
+    <Comp
+      ref={ref}
+      data-slot="button"
+      {...(variant !== undefined && { "data-variant": variant })}
+      {...(size !== undefined && { "data-size": size })}
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+});
+
+Button.displayName = "Button";
+
+export { Button, buttonVariants };

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

@@ -7,7 +7,7 @@ function Card({ className, ...props }: React.ComponentProps<"div">) {
     <div
       data-slot="card"
       className={cn(
-        "bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm",
+        "bg-card text-card-foreground flex flex-col gap-6 rounded-[4px] border py-6 shadow-sm dark:border-[#0049A5] dark:bg-[#02244C]",
         className,
       )}
       {...props}
@@ -42,7 +42,7 @@ function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="card-description"
-      className={cn("text-muted-foreground text-sm", className)}
+      className={cn("text-muted-foreground text-sm dark:text-[#F2F3F5]", className)}
       {...props}
     />
   );
@@ -65,7 +65,7 @@ function CardContent({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="card-content"
-      className={cn("px-6", className)}
+      className={cn("px-6 ", className)}
       {...props}
     />
   );

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

@@ -34,7 +34,7 @@ const emptyMediaVariants = cva(
     variants: {
       variant: {
         default: "bg-transparent",
-        icon: "bg-muted text-foreground flex size-10 shrink-0 items-center justify-center rounded-lg [&_svg:not([class*='size-'])]:size-6",
+        icon: "bg-muted text-foreground flex size-10 shrink-0 items-center justify-center rounded-lg [&_svg:not([class*='size-'])]:size-6 dark:text-[#55A6FE]  dark:bg-[#022248]",
       },
     },
     defaultVariants: {
@@ -62,7 +62,7 @@ function EmptyTitle({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="empty-title"
-      className={cn("text-lg font-medium tracking-tight", className)}
+      className={cn("text-lg font-medium tracking-tight dark:text-[#AACEFF]", className)}
       {...props}
     />
   );
@@ -73,7 +73,7 @@ function EmptyDescription({ className, ...props }: React.ComponentProps<"p">) {
     <div
       data-slot="empty-description"
       className={cn(
-        "text-muted-foreground [&>a:hover]:text-primary text-sm/relaxed [&>a]:underline [&>a]:underline-offset-4",
+        "text-muted-foreground [&>a:hover]:text-primary text-sm/relaxed [&>a]:underline [&>a]:underline-offset-4 dark:text-[#55A6FE]",
         className,
       )}
       {...props}

frontend-web/src/components/ui/input-group.tsx

@@ -14,7 +14,7 @@ function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="input-group"
       role="group"
       className={cn(
-        "group/input-group border-input/50 dark:bg-background/80 relative flex w-full items-center rounded-md border bg-white/80 shadow-xs transition-[color,box-shadow] outline-none",
+        "group/input-group relative flex w-full items-center rounded-md border border-input/50 bg-white/80 shadow-xs transition-[color,box-shadow] outline-none dark:border-[#1B477E] dark:bg-[#022248]",
         "h-9 min-w-0 has-[>textarea]:h-auto",
 
         // Variants based on alignment.

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

@@ -3,14 +3,26 @@ import * as React from "react";
 import { cn } from "@/lib/utils";
 
 function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  const usesDarkNativePicker =
+    type === "number" ||
+    type === "date" ||
+    type === "datetime-local" ||
+    type === "time" ||
+    type === "month" ||
+    type === "week";
+
   return (
     <input
       type={type}
       data-slot="input"
       className={cn(
-        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
-        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
-        "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+        "h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base outline-none transition-[color,box-shadow] md:text-sm",
+        "border-input placeholder:text-muted-foreground",
+        "dark:border-[#1B477E] dark:bg-[#0D2D54] dark:text-[#AACEFF] dark:placeholder:text-[#566B7F] dark:rounded-[4px] dark:text-[16px] md:dark:text-[16px]",
+        usesDarkNativePicker && "dark:[color-scheme:dark]",
+        "file:text-foreground selection:bg-primary selection:text-primary-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50",
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] dark:focus-visible:border-[#3b82f6] dark:focus-visible:ring-[#3b82f6]/30",
+        "aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40",
         className,
       )}
       {...props}

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

@@ -24,69 +24,70 @@ function SelectValue({
   return <SelectPrimitive.Value data-slot="select-value" {...props} />;
 }
 
-const SelectTrigger = React.forwardRef<
-  React.ElementRef<typeof SelectPrimitive.Trigger>,
-  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> & {
-    size?: "sm" | "default";
-  }
->(({ className, size = "default", children, ...props }, ref) => {
-  return (
-    <SelectPrimitive.Trigger
-      ref={ref}
-      data-slot="select-trigger"
-      data-size={size}
-      className={cn(
-        "border-input data-[placeholder]:text-muted-foreground [&_svg:not([class*='text-'])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 dark:hover:bg-input/50 flex w-fit cursor-pointer items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
-        className,
-      )}
-      {...props}
-    >
-      {children}
-      <SelectPrimitive.Icon asChild>
-        <ChevronDownIcon className="size-4 opacity-50" />
-      </SelectPrimitive.Icon>
-    </SelectPrimitive.Trigger>
-  );
-});
-
-SelectTrigger.displayName = SelectPrimitive.Trigger.displayName;
+const SelectTrigger = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> & {
+    size?: "sm" | "default";
+  }
+>(({ className, size = "default", children, ...props }, ref) => {
+  return (
+    <SelectPrimitive.Trigger
+      ref={ref}
+      data-slot="select-trigger"
+      data-size={size}
+      className={cn(
+        "border-input data-[placeholder]:text-muted-foreground [&_svg:not([class*='text-'])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive flex w-fit cursor-pointer items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "dark:border-[#1B477E] dark:bg-[#022248] dark:text-[#AACEE2] dark:data-[placeholder]:text-[#566B7F] dark:hover:bg-[#022248] dark:[&_svg:not([class*='text-'])]:text-[#AACEFF] dark:focus-visible:border-[#3b82f6] dark:focus-visible:ring-[#3b82f6]/30",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon asChild>
+        <ChevronDownIcon className="size-4 opacity-50" />
+      </SelectPrimitive.Icon>
+    </SelectPrimitive.Trigger>
+  );
+});
 
-const SelectContent = React.forwardRef<
-  React.ElementRef<typeof SelectPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Content>
->(({ className, children, position = "item-aligned", align = "center", ...props }, ref) => {
-  return (
-    <SelectPrimitive.Portal>
-      <SelectPrimitive.Content
-        ref={ref}
-        data-slot="select-content"
-        className={cn(
-          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-50 max-h-(--radix-select-content-available-height) min-w-[8rem] origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border shadow-md",
-          position === "popper" &&
-            "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
-          className,
-        )}
-        position={position}
-        align={align}
-        {...props}
-      >
-        <SelectScrollUpButton />
-        <SelectPrimitive.Viewport
-          className={cn(
-            "p-1",
-            position === "popper" &&
-              "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)] scroll-my-1",
-          )}
-        >
-          {children}
-        </SelectPrimitive.Viewport>
-        <SelectScrollDownButton />
-      </SelectPrimitive.Content>
-    </SelectPrimitive.Portal>
-  );
-});
-
-SelectContent.displayName = SelectPrimitive.Content.displayName;
+SelectTrigger.displayName = SelectPrimitive.Trigger.displayName;
+
+const SelectContent = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Content>
+>(({ className, children, position = "item-aligned", align = "center", ...props }, ref) => {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Content
+        ref={ref}
+        data-slot="select-content"
+        className={cn(
+          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-50 max-h-(--radix-select-content-available-height) min-w-[8rem] origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border shadow-md dark:border-[#1B477E] dark:bg-[#022248] dark:text-[#AACEFF]",
+          position === "popper" &&
+            "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
+          className,
+        )}
+        position={position}
+        align={align}
+        {...props}
+      >
+        <SelectScrollUpButton />
+        <SelectPrimitive.Viewport
+          className={cn(
+            "p-1",
+            position === "popper" &&
+              "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)] scroll-my-1",
+          )}
+        >
+          {children}
+        </SelectPrimitive.Viewport>
+        <SelectScrollDownButton />
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Portal>
+  );
+});
+
+SelectContent.displayName = SelectPrimitive.Content.displayName;
 
 function SelectLabel({
   className,
@@ -95,40 +96,44 @@ function SelectLabel({
   return (
     <SelectPrimitive.Label
       data-slot="select-label"
-      className={cn("text-muted-foreground px-2 py-1.5 text-xs", className)}
+      className={cn(
+        "text-muted-foreground px-2 py-1.5 text-xs dark:text-[#566B7F]",
+        className,
+      )}
       {...props}
     />
   );
 }
 
-const SelectItem = React.forwardRef<
-  React.ElementRef<typeof SelectPrimitive.Item>,
-  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Item>
->(({ className, children, ...props }, ref) => {
-  return (
-    <SelectPrimitive.Item
-      ref={ref}
-      data-slot="select-item"
-      className={cn(
-        "focus:bg-accent focus:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-pointer items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
-        className,
-      )}
-      {...props}
-    >
-      <span
-        data-slot="select-item-indicator"
-        className="absolute right-2 flex size-3.5 items-center justify-center"
-      >
-        <SelectPrimitive.ItemIndicator>
-          <CheckIcon className="size-4" />
-        </SelectPrimitive.ItemIndicator>
-      </span>
-      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
-    </SelectPrimitive.Item>
-  );
-});
-
-SelectItem.displayName = SelectPrimitive.Item.displayName;
+const SelectItem = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Item>
+>(({ className, children, ...props }, ref) => {
+  return (
+    <SelectPrimitive.Item
+      ref={ref}
+      data-slot="select-item"
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-pointer items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        "dark:text-[#AACEFF] dark:focus:bg-[#0062D9] dark:focus:text-white dark:data-[highlighted]:bg-[#0062D9] dark:data-[highlighted]:text-white dark:[&_svg:not([class*='text-'])]:text-[#AACEFF] dark:focus:[&_svg:not([class*='text-'])]:text-white dark:data-[highlighted]:[&_svg:not([class*='text-'])]:text-white",
+        className,
+      )}
+      {...props}
+    >
+      <span
+        data-slot="select-item-indicator"
+        className="absolute right-2 flex size-3.5 items-center justify-center"
+      >
+        <SelectPrimitive.ItemIndicator>
+          <CheckIcon className="size-4" />
+        </SelectPrimitive.ItemIndicator>
+      </span>
+      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+    </SelectPrimitive.Item>
+  );
+});
+
+SelectItem.displayName = SelectPrimitive.Item.displayName;
 
 function SelectSeparator({
   className,
@@ -151,7 +156,7 @@ function SelectScrollUpButton({
     <SelectPrimitive.ScrollUpButton
       data-slot="select-scroll-up-button"
       className={cn(
-        "flex cursor-default items-center justify-center py-1",
+        "flex cursor-default items-center justify-center py-1 dark:text-[#AACEFF]",
         className,
       )}
       {...props}
@@ -169,7 +174,7 @@ function SelectScrollDownButton({
     <SelectPrimitive.ScrollDownButton
       data-slot="select-scroll-down-button"
       className={cn(
-        "flex cursor-default items-center justify-center py-1",
+        "flex cursor-default items-center justify-center py-1 dark:text-[#AACEFF]",
         className,
       )}
       {...props}

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

@@ -397,53 +397,53 @@ function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
-const SidebarGroupLabel = React.forwardRef<
-  HTMLDivElement,
-  React.ComponentProps<"div"> & { asChild?: boolean }
->(({ className, asChild = false, ...props }, ref) => {
-  const Comp = asChild ? Slot : "div";
-
-  return (
-    <Comp
-      ref={ref}
-      data-slot="sidebar-group-label"
-      data-sidebar="group-label"
-      className={cn(
-        "text-sidebar-foreground/70 ring-sidebar-ring flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium outline-hidden transition-[margin,opacity] duration-200 ease-linear focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
-        "group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0",
-        className,
-      )}
-      {...props}
-    />
-  );
-});
-
-SidebarGroupLabel.displayName = "SidebarGroupLabel";
+const SidebarGroupLabel = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<"div"> & { asChild?: boolean }
+>(({ className, asChild = false, ...props }, ref) => {
+  const Comp = asChild ? Slot : "div";
 
-const SidebarGroupAction = React.forwardRef<
-  HTMLButtonElement,
-  React.ComponentProps<"button"> & { asChild?: boolean }
->(({ className, asChild = false, ...props }, ref) => {
-  const Comp = asChild ? Slot : "button";
-
-  return (
-    <Comp
-      ref={ref}
-      data-slot="sidebar-group-action"
-      data-sidebar="group-action"
-      className={cn(
-        "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground absolute top-3.5 right-3 flex aspect-square w-5 items-center justify-center rounded-md p-0 outline-hidden transition-transform focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
-        // Increases the hit area of the button on mobile.
-        "after:absolute after:-inset-2 md:after:hidden",
-        "group-data-[collapsible=icon]:hidden",
-        className,
-      )}
-      {...props}
-    />
-  );
-});
-
-SidebarGroupAction.displayName = "SidebarGroupAction";
+  return (
+    <Comp
+      ref={ref}
+      data-slot="sidebar-group-label"
+      data-sidebar="group-label"
+      className={cn(
+        "text-sidebar-foreground/70 ring-sidebar-ring flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium outline-hidden transition-[margin,opacity] duration-200 ease-linear focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
+        "group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+SidebarGroupLabel.displayName = "SidebarGroupLabel";
+
+const SidebarGroupAction = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentProps<"button"> & { asChild?: boolean }
+>(({ className, asChild = false, ...props }, ref) => {
+  const Comp = asChild ? Slot : "button";
+
+  return (
+    <Comp
+      ref={ref}
+      data-slot="sidebar-group-action"
+      data-sidebar="group-action"
+      className={cn(
+        "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground absolute top-3.5 right-3 flex aspect-square w-5 items-center justify-center rounded-md p-0 outline-hidden transition-transform focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
+        // Increases the hit area of the button on mobile.
+        "after:absolute after:-inset-2 md:after:hidden",
+        "group-data-[collapsible=icon]:hidden",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+SidebarGroupAction.displayName = "SidebarGroupAction";
 
 function SidebarGroupContent({
   className,
@@ -503,99 +503,99 @@ const sidebarMenuButtonVariants = cva(
   },
 );
 
-const SidebarMenuButton = React.forwardRef<
-  HTMLButtonElement,
-  React.ComponentProps<"button"> & {
-    asChild?: boolean;
-    isActive?: boolean;
-    tooltip?: string | React.ComponentProps<typeof TooltipContent>;
-  } & VariantProps<typeof sidebarMenuButtonVariants>
->(
-  (
-    {
-      asChild = false,
-      isActive = false,
-      variant = "default",
-      size = "default",
-      tooltip,
-      className,
-      ...props
-    },
-    ref,
-  ) => {
-    const Comp = asChild ? Slot : "button";
-    const { isMobile, state } = useSidebar();
-
-    const button = (
-      <Comp
-        ref={ref}
-        data-slot="sidebar-menu-button"
-        data-sidebar="menu-button"
-        data-size={size}
-        data-active={isActive}
-        className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
-        {...props}
-      />
-    );
-
-    if (!tooltip) {
-      return button;
-    }
-
-    if (typeof tooltip === "string") {
-      tooltip = {
-        children: tooltip,
-      };
-    }
-
-    return (
-      <Tooltip>
-        <TooltipTrigger asChild>{button}</TooltipTrigger>
-        <TooltipContent
-          side="right"
-          align="center"
-          hidden={state !== "collapsed" || isMobile}
-          {...tooltip}
-        />
-      </Tooltip>
-    );
-  },
-);
-
-SidebarMenuButton.displayName = "SidebarMenuButton";
+const SidebarMenuButton = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentProps<"button"> & {
+    asChild?: boolean;
+    isActive?: boolean;
+    tooltip?: string | React.ComponentProps<typeof TooltipContent>;
+  } & VariantProps<typeof sidebarMenuButtonVariants>
+>(
+  (
+    {
+      asChild = false,
+      isActive = false,
+      variant = "default",
+      size = "default",
+      tooltip,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const Comp = asChild ? Slot : "button";
+    const { isMobile, state } = useSidebar();
 
-const SidebarMenuAction = React.forwardRef<
-  HTMLButtonElement,
-  React.ComponentProps<"button"> & {
-    asChild?: boolean;
-    showOnHover?: boolean;
-  }
->(({ className, asChild = false, showOnHover = false, ...props }, ref) => {
-  const Comp = asChild ? Slot : "button";
-
-  return (
-    <Comp
-      ref={ref}
-      data-slot="sidebar-menu-action"
-      data-sidebar="menu-action"
-      className={cn(
-        "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground peer-hover/menu-button:text-sidebar-accent-foreground absolute top-1.5 right-1 flex aspect-square w-5 items-center justify-center rounded-md p-0 outline-hidden transition-transform focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
-        // Increases the hit area of the button on mobile.
-        "after:absolute after:-inset-2 md:after:hidden",
-        "peer-data-[size=sm]/menu-button:top-1",
-        "peer-data-[size=default]/menu-button:top-1.5",
-        "peer-data-[size=lg]/menu-button:top-2.5",
-        "group-data-[collapsible=icon]:hidden",
-        showOnHover &&
-          "peer-data-[active=true]/menu-button:text-sidebar-accent-foreground group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 md:opacity-0",
-        className,
-      )}
-      {...props}
-    />
-  );
-});
-
-SidebarMenuAction.displayName = "SidebarMenuAction";
+    const button = (
+      <Comp
+        ref={ref}
+        data-slot="sidebar-menu-button"
+        data-sidebar="menu-button"
+        data-size={size}
+        data-active={isActive}
+        className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
+        {...props}
+      />
+    );
+
+    if (!tooltip) {
+      return button;
+    }
+
+    if (typeof tooltip === "string") {
+      tooltip = {
+        children: tooltip,
+      };
+    }
+
+    return (
+      <Tooltip>
+        <TooltipTrigger asChild>{button}</TooltipTrigger>
+        <TooltipContent
+          side="right"
+          align="center"
+          hidden={state !== "collapsed" || isMobile}
+          {...tooltip}
+        />
+      </Tooltip>
+    );
+  },
+);
+
+SidebarMenuButton.displayName = "SidebarMenuButton";
+
+const SidebarMenuAction = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentProps<"button"> & {
+    asChild?: boolean;
+    showOnHover?: boolean;
+  }
+>(({ className, asChild = false, showOnHover = false, ...props }, ref) => {
+  const Comp = asChild ? Slot : "button";
+
+  return (
+    <Comp
+      ref={ref}
+      data-slot="sidebar-menu-action"
+      data-sidebar="menu-action"
+      className={cn(
+        "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground peer-hover/menu-button:text-sidebar-accent-foreground absolute top-1.5 right-1 flex aspect-square w-5 items-center justify-center rounded-md p-0 outline-hidden transition-transform focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
+        // Increases the hit area of the button on mobile.
+        "after:absolute after:-inset-2 md:after:hidden",
+        "peer-data-[size=sm]/menu-button:top-1",
+        "peer-data-[size=default]/menu-button:top-1.5",
+        "peer-data-[size=lg]/menu-button:top-2.5",
+        "group-data-[collapsible=icon]:hidden",
+        showOnHover &&
+          "peer-data-[active=true]/menu-button:text-sidebar-accent-foreground group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 md:opacity-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+SidebarMenuAction.displayName = "SidebarMenuAction";
 
 function SidebarMenuBadge({
   className,
@@ -686,37 +686,37 @@ function SidebarMenuSubItem({
   );
 }
 
-const SidebarMenuSubButton = React.forwardRef<
-  HTMLAnchorElement,
-  React.ComponentProps<"a"> & {
-    asChild?: boolean;
-    size?: "sm" | "md";
-    isActive?: boolean;
-  }
->(({ asChild = false, size = "md", isActive = false, className, ...props }, ref) => {
-  const Comp = asChild ? Slot : "a";
-
-  return (
-    <Comp
-      ref={ref}
-      data-slot="sidebar-menu-sub-button"
-      data-sidebar="menu-sub-button"
-      data-size={size}
-      data-active={isActive}
-      className={cn(
-        "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground active:bg-sidebar-accent active:text-sidebar-accent-foreground [&>svg]:text-sidebar-accent-foreground flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 outline-hidden focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0",
-        "data-[active=true]:bg-sidebar-accent data-[active=true]:text-sidebar-accent-foreground",
-        size === "sm" && "text-xs",
-        size === "md" && "text-sm",
-        "group-data-[collapsible=icon]:hidden",
-        className,
-      )}
-      {...props}
-    />
-  );
-});
-
-SidebarMenuSubButton.displayName = "SidebarMenuSubButton";
+const SidebarMenuSubButton = React.forwardRef<
+  HTMLAnchorElement,
+  React.ComponentProps<"a"> & {
+    asChild?: boolean;
+    size?: "sm" | "md";
+    isActive?: boolean;
+  }
+>(({ asChild = false, size = "md", isActive = false, className, ...props }, ref) => {
+  const Comp = asChild ? Slot : "a";
+
+  return (
+    <Comp
+      ref={ref}
+      data-slot="sidebar-menu-sub-button"
+      data-sidebar="menu-sub-button"
+      data-size={size}
+      data-active={isActive}
+      className={cn(
+        "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground active:bg-sidebar-accent active:text-sidebar-accent-foreground [&>svg]:text-sidebar-accent-foreground flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 outline-hidden focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0",
+        "data-[active=true]:bg-sidebar-accent data-[active=true]:text-sidebar-accent-foreground",
+        size === "sm" && "text-xs",
+        size === "md" && "text-sm",
+        "group-data-[collapsible=icon]:hidden",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+SidebarMenuSubButton.displayName = "SidebarMenuSubButton";
 
 export {
   Sidebar,

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

@@ -13,7 +13,7 @@ function Switch({
     <SwitchPrimitive.Root
       data-slot="switch"
       className={cn(
-        "peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 dark:data-[state=unchecked]:bg-input/80 inline-flex h-[1.15rem] w-8 shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
+        "peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 dark:data-[state=unchecked]:bg-[#55A6FE] dark:data-[state=checked]:bg-[#0062D9] inline-flex h-[1.15rem] w-8 shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
         className,
       )}
       {...props}

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

@@ -30,8 +30,10 @@ const tabsListVariants = cva(
   {
     variants: {
       variant: {
-        default: "bg-muted",
-        line: "gap-1 bg-transparent",
+        default:
+          "bg-muted dark:group-data-[orientation=horizontal]/tabs:h-8! dark:items-stretch dark:gap-0 dark:overflow-hidden dark:rounded-[2px] dark:border dark:border-[#55A6FE] dark:bg-[#022248] dark:p-0",
+        line:
+          "gap-1 bg-transparent dark:group-data-[orientation=horizontal]/tabs:h-8! dark:items-stretch dark:gap-0 dark:overflow-visible dark:rounded-[2px] dark:border dark:border-[#55A6FE] dark:bg-[#022248] dark:p-0",
       },
     },
     defaultVariants: {
@@ -40,60 +42,68 @@ const tabsListVariants = cva(
   },
 );
 
-const TabsList = React.forwardRef<
-  React.ElementRef<typeof TabsPrimitive.List>,
-  React.ComponentPropsWithoutRef<typeof TabsPrimitive.List> &
-    VariantProps<typeof tabsListVariants>
->(({ className, variant = "default", ...props }, ref) => {
-  return (
-    <TabsPrimitive.List
-      ref={ref}
-      data-slot="tabs-list"
-      data-variant={variant}
-      className={cn(tabsListVariants({ variant }), className)}
-      {...props}
-    />
-  );
-});
-
-TabsList.displayName = TabsPrimitive.List.displayName;
+const TabsList = React.forwardRef<
+  React.ElementRef<typeof TabsPrimitive.List>,
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.List> &
+    VariantProps<typeof tabsListVariants>
+>(({ className, variant = "default", ...props }, ref) => {
+  return (
+    <TabsPrimitive.List
+      ref={ref}
+      data-slot="tabs-list"
+      data-variant={variant}
+      className={cn(tabsListVariants({ variant }), className)}
+      {...props}
+    />
+  );
+});
 
-const TabsTrigger = React.forwardRef<
-  React.ElementRef<typeof TabsPrimitive.Trigger>,
-  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>
->(({ className, ...props }, ref) => {
-  return (
-    <TabsPrimitive.Trigger
-      ref={ref}
-      data-slot="tabs-trigger"
-      className={cn(
-        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:outline-ring text-foreground/60 hover:text-foreground dark:text-muted-foreground dark:hover:text-foreground relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start focus-visible:ring-[3px] focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
-        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:border-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent",
-        "data-[state=active]:bg-background dark:data-[state=active]:text-foreground dark:data-[state=active]:border-input dark:data-[state=active]:bg-input/30 data-[state=active]:text-foreground",
-        "after:bg-foreground after:absolute after:opacity-0 after:transition-opacity group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-5px] group-data-[orientation=horizontal]/tabs:after:h-0.5 group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-right-1 group-data-[orientation=vertical]/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-[state=active]:after:opacity-100",
-        className,
-      )}
-      {...props}
-    />
-  );
-});
-
-TabsTrigger.displayName = TabsPrimitive.Trigger.displayName;
+TabsList.displayName = TabsPrimitive.List.displayName;
 
-const TabsContent = React.forwardRef<
-  React.ElementRef<typeof TabsPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Content>
->(({ className, ...props }, ref) => {
-  return (
-    <TabsPrimitive.Content
-      ref={ref}
-      data-slot="tabs-content"
-      className={cn("flex-1 outline-none", className)}
-      {...props}
-    />
-  );
-});
-
-TabsContent.displayName = TabsPrimitive.Content.displayName;
+const TabsTrigger = React.forwardRef<
+  React.ElementRef<typeof TabsPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>
+>(({ className, ...props }, ref) => {
+  return (
+    <TabsPrimitive.Trigger
+      ref={ref}
+      data-slot="tabs-trigger"
+      className={cn(
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:outline-ring text-foreground/60 hover:text-foreground relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "dark:text-muted-foreground dark:hover:text-foreground",
+        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent",
+        "data-[state=active]:bg-background data-[state=active]:text-foreground",
+        "dark:group-data-[variant=line]/tabs-list:relative dark:group-data-[variant=line]/tabs-list:!h-full dark:group-data-[variant=line]/tabs-list:self-stretch dark:group-data-[variant=line]/tabs-list:flex-none dark:group-data-[variant=line]/tabs-list:rounded-none dark:group-data-[variant=line]/tabs-list:border-0 dark:group-data-[variant=line]/tabs-list:bg-transparent dark:group-data-[variant=line]/tabs-list:px-4 dark:group-data-[variant=line]/tabs-list:!py-0 dark:group-data-[variant=line]/tabs-list:!leading-none dark:group-data-[variant=line]/tabs-list:text-[#CCD2DA] dark:group-data-[variant=line]/tabs-list:shadow-none dark:group-data-[variant=line]/tabs-list:hover:text-[#CCD2DA] dark:group-data-[variant=line]/tabs-list:focus-visible:ring-0 dark:group-data-[variant=line]/tabs-list:[&_svg]:text-[#CCD2DA]",
+        "dark:group-data-[variant=line]/tabs-list:not(:first-child):border-l dark:group-data-[variant=line]/tabs-list:not(:first-child):border-[#1d3961] dark:group-data-[variant=line]/tabs-list:data-[state=active]:border-l-0",
+        "dark:group-data-[variant=line]/tabs-list:data-[state=active]:rounded-none dark:group-data-[variant=line]/tabs-list:data-[state=active]:border-0 dark:group-data-[variant=line]/tabs-list:data-[state=active]:bg-[#0062D9] dark:group-data-[variant=line]/tabs-list:data-[state=active]:text-[#FFFFFF] dark:group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none dark:group-data-[variant=line]/tabs-list:data-[state=active]:[&_svg]:text-[#FFFFFF]",
+        "dark:group-data-[variant=default]/tabs-list:flex dark:group-data-[variant=default]/tabs-list:min-h-0 dark:group-data-[variant=default]/tabs-list:!h-full dark:group-data-[variant=default]/tabs-list:flex-1 dark:group-data-[variant=default]/tabs-list:self-stretch dark:group-data-[variant=default]/tabs-list:rounded-none dark:group-data-[variant=default]/tabs-list:border-0 dark:group-data-[variant=default]/tabs-list:bg-transparent dark:group-data-[variant=default]/tabs-list:px-4 dark:group-data-[variant=default]/tabs-list:!py-0 dark:group-data-[variant=default]/tabs-list:!leading-none dark:group-data-[variant=default]/tabs-list:text-[#CCD2DA] dark:group-data-[variant=default]/tabs-list:shadow-none dark:group-data-[variant=default]/tabs-list:hover:text-[#CCD2DA] dark:group-data-[variant=default]/tabs-list:focus-visible:ring-0 dark:group-data-[variant=default]/tabs-list:[&_svg]:text-[#CCD2DA]",
+        "dark:group-data-[variant=default]/tabs-list:not(:first-child):border-l dark:group-data-[variant=default]/tabs-list:not(:first-child):border-[#1d3961] dark:group-data-[variant=default]/tabs-list:data-[state=active]:border-l-0",
+        "dark:group-data-[variant=default]/tabs-list:data-[state=active]:rounded-none dark:group-data-[variant=default]/tabs-list:data-[state=active]:border-0 dark:group-data-[variant=default]/tabs-list:data-[state=active]:bg-[#0062D9] dark:group-data-[variant=default]/tabs-list:data-[state=active]:text-[#FFFFFF] dark:group-data-[variant=default]/tabs-list:data-[state=active]:shadow-none dark:group-data-[variant=default]/tabs-list:data-[state=active]:hover:text-[#FFFFFF] dark:group-data-[variant=default]/tabs-list:data-[state=active]:[&_svg]:text-[#FFFFFF]",
+        "group-data-[variant=line]/tabs-list:after:pointer-events-none group-data-[variant=line]/tabs-list:after:absolute group-data-[variant=line]/tabs-list:after:inset-x-2 group-data-[variant=line]/tabs-list:after:bottom-[-5px] group-data-[variant=line]/tabs-list:after:h-0.5 group-data-[variant=line]/tabs-list:after:bg-foreground group-data-[variant=line]/tabs-list:after:opacity-0 group-data-[variant=line]/tabs-list:after:transition-opacity group-data-[variant=line]/tabs-list:after:content-[''] group-data-[variant=line]/tabs-list:data-[state=active]:after:opacity-100",
+        "dark:group-data-[variant=line]/tabs-list:after:inset-x-0 dark:group-data-[variant=line]/tabs-list:after:bottom-0 dark:group-data-[variant=line]/tabs-list:after:z-[2] dark:group-data-[variant=line]/tabs-list:after:h-[2px] dark:group-data-[variant=line]/tabs-list:after:bg-[#FFFFFF]",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+TabsTrigger.displayName = TabsPrimitive.Trigger.displayName;
+
+const TabsContent = React.forwardRef<
+  React.ElementRef<typeof TabsPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Content>
+>(({ className, ...props }, ref) => {
+  return (
+    <TabsPrimitive.Content
+      ref={ref}
+      data-slot="tabs-content"
+      className={cn("flex-1 outline-none", className)}
+      {...props}
+    />
+  );
+});
+
+TabsContent.displayName = TabsPrimitive.Content.displayName;
 
 export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants };

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

@@ -7,7 +7,9 @@ function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
     <textarea
       data-slot="textarea"
       className={cn(
-        "border-input placeholder:text-muted-foreground/60 focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "border-input placeholder:text-muted-foreground/60 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "dark:border-[#1B477E] dark:bg-[#022248] dark:text-[#AACEFF] ",
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
         className,
       )}
       {...props}

frontend-web/src/components/workspace/admin/admin-memory-page.tsx

@@ -6,6 +6,7 @@ import { toast } from "sonner";
 
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
+import { useTheme } from "@/contexts/ThemeContext";
 import { Input } from "@/components/ui/input";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import {
@@ -29,7 +30,7 @@ import {
 } from "@/core/admin/hooks";
 import { useAllUsers } from "@/core/auth/hooks";
 
-function getEntries(data: Record<string, unknown>): string[] {
+export function getEntries(data: Record<string, unknown>): string[] {
   const raw = (data as { entries?: unknown }).entries;
   if (!Array.isArray(raw)) return [];
   return raw.filter((e): e is string => typeof e === "string" && e.trim().length > 0);
@@ -90,7 +91,7 @@ function V1SectionField({
   return (
     <div className="space-y-1">
       <div className="flex items-center justify-between">
-        <span className="text-xs font-medium text-muted-foreground">{label}</span>
+        <span className="text-xs font-medium text-muted-foreground dark:text-[#AACEE2]">{label}</span>
         {!editing && (
           <Button size="icon" variant="ghost" className="size-6" onClick={() => { setDraft(value); setEditing(true); }}>
             <Pencil className="size-3" />
@@ -154,7 +155,7 @@ function V1FactItem({
   }
 
   return (
-    <div className="rounded border p-2 space-y-1 group">
+    <div className="rounded border p-2 space-y-1 group ">
       {editing ? (
         <div className="space-y-2">
           <Textarea value={draftContent} onChange={(e) => setDraftContent(e.target.value)} className="min-h-[64px] text-sm" autoFocus />
@@ -196,7 +197,7 @@ function V1FactItem({
               </Button>
             </div>
           </div>
-          <p className="text-sm whitespace-pre-wrap">{String(fact.content ?? "")}</p>
+          <p className="text-sm whitespace-pre-wrap dark:text-[#AACEE2]">{String(fact.content ?? "")}</p>
           {fact.sourceError ? <p className="text-xs text-red-600 bg-red-50 rounded px-2 py-1">避免：{String(fact.sourceError)}</p> : null}
         </>
       )}
@@ -206,6 +207,7 @@ function V1FactItem({
 
 // 新增事实表单
 function V1AddFactForm({ agent, userId }: { agent: string | null; userId: string }) {
+  const { theme } = useTheme();
   const [open, setOpen] = useState(false);
   const [content, setContent] = useState("");
   const [category, setCategory] = useState("context");
@@ -222,7 +224,12 @@ function V1AddFactForm({ agent, userId }: { agent: string | null; userId: string
 
   if (!open) {
     return (
-      <Button variant="outline" size="sm" className="mt-1 w-full" onClick={() => setOpen(true)}>
+      <Button
+        variant={theme === "dark" ? "default" : "outline"}
+        size="sm"
+        className="mt-1 w-full"
+        onClick={() => setOpen(true)}
+      >
         <Plus className="size-3" />新增事实
       </Button>
     );
@@ -251,7 +258,7 @@ function V1AddFactForm({ agent, userId }: { agent: string | null; userId: string
   );
 }
 
-function V1BucketView({
+export function V1BucketView({
   data,
   agent,
   userId,
@@ -276,8 +283,8 @@ function V1BucketView({
   return (
     <div className="space-y-4">
       {/* 用户画像字段 */}
-      <div className="rounded-md border p-3 space-y-3">
-        <h4 className="text-xs font-semibold text-muted-foreground">用户画像</h4>
+      <div className="rounded-md border p-3 space-y-3 dark:border-[#213D5E] dark:bg-[#02244C] dark:text-white">
+        <h4 className="text-xs font-semibold text-muted-foreground dark:text-white">用户画像</h4>
         {allCtxFields.map((field) => (
           <V1SectionField
             key={field}
@@ -291,8 +298,8 @@ function V1BucketView({
       </div>
 
       {/* 历史摘要字段 */}
-      <div className="rounded-md border p-3 space-y-3">
-        <h4 className="text-xs font-semibold text-muted-foreground">历史摘要</h4>
+      <div className="rounded-md border p-3 space-y-3 dark:border-[#213D5E] dark:bg-[#02244C] dark:text-white">
+        <h4 className="text-xs font-semibold text-muted-foreground dark:text-white">历史摘要</h4>
         {allHistoryFields.map((field) => (
           <V1SectionField
             key={field}
@@ -306,8 +313,8 @@ function V1BucketView({
       </div>
 
       {/* 事实记录 */}
-      <div className="rounded-md border p-3 space-y-2">
-        <h4 className="text-xs font-semibold text-muted-foreground">事实记录（{factsRaw.length} 条）</h4>
+      <div className="rounded-md border p-3 space-y-2 dark:border-[#213D5E] dark:bg-[#022248]">
+        <h4 className="text-xs font-semibold text-muted-foreground dark:text-white">事实记录（{factsRaw.length} 条）</h4>
         {factsRaw.map((fact, i) => (
           <V1FactItem key={String(fact.id ?? i)} fact={fact} agent={agent} userId={userId} />
         ))}
@@ -319,7 +326,7 @@ function V1BucketView({
 
 // ── Memory entry list with inline editing ──────────────────────────────────
 
-function MemoryEntryList({
+export function MemoryEntryList({
   entries,
   userId,
   agent,
@@ -490,7 +497,7 @@ function MemoryEntryList({
 
 // ── Right panel: memory tabs for a selected user ───────────────────────────
 
-function UserMemoryPanel({ userId }: { userId: string }) {
+export function UserMemoryPanel({ userId }: { userId: string }) {
   const { data: memory, isLoading } = useUserMemory(userId);
   const [selectedAgent, setSelectedAgent] = useState<string | null>(null);
 

frontend-web/src/components/workspace/admin/admin-user-hub.tsx

@@ -0,0 +1,419 @@
+"use client";
+
+import { Loader2, MessageSquareIcon, SearchIcon, UserIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { Badge } from "@/components/ui/badge";
+import { Input } from "@/components/ui/input";
+import { ScrollArea } from "@/components/ui/scroll-area";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import type { AdminMessage } from "@/core/admin/api";
+import {
+  useUserMemory,
+  useUserThreadMessages,
+  useUserThreads,
+} from "@/core/admin/hooks";
+import type { UserListItem } from "@/core/auth/api";
+import { useAllUsers } from "@/core/auth/hooks";
+import { cn } from "@/lib/utils";
+
+import {
+  getEntries,
+  MemoryEntryList,
+  V1BucketView,
+} from "./admin-memory-page";
+
+// ── Helpers (shared with AdminUserActivityPage) ─────────────────────────────
+
+function extractText(content: unknown): string {
+  if (content == null) return "";
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((block) => {
+        if (typeof block === "string") return block;
+        if (block && typeof block === "object") {
+          const text = (block as Record<string, unknown>).text;
+          if (typeof text === "string") return text;
+        }
+        return "";
+      })
+      .join("");
+  }
+  if (typeof content === "object") {
+    const inner = (content as Record<string, unknown>).content;
+    if (inner !== undefined) return extractText(inner);
+  }
+  return "";
+}
+
+function roleOf(message: AdminMessage): "user" | "assistant" | null {
+  const type = (message.type ?? "").toLowerCase();
+  if (type === "human") return "user";
+  if (type === "ai" || type === "aimessagechunk") return "assistant";
+  return null;
+}
+
+function fmtTime(iso: string): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? iso : d.toLocaleString();
+}
+
+// ── UserInfoPanel ───────────────────────────────────────────────────────────
+
+function UserInfoPanel({ user }: { user: UserListItem }) {
+  return (
+    <div className="p-6">
+      <dl className="grid grid-cols-[max-content_1fr] gap-x-8 gap-y-3 text-sm">
+        <dt className="text-muted-foreground font-medium">邮箱</dt>
+        <dd className="break-all">{user.email}</dd>
+        <dt className="text-muted-foreground font-medium">角色</dt>
+        <dd>
+          {user.system_role === "admin" ? (
+            <Badge variant="default">管理员</Badge>
+          ) : (
+            <Badge variant="secondary">普通用户</Badge>
+          )}
+        </dd>
+        <dt className="text-muted-foreground font-medium">Skills</dt>
+        <dd className="tabular-nums">{user.skill_count}</dd>
+        <dt className="text-muted-foreground font-medium">Agents</dt>
+        <dd className="tabular-nums">{user.agent_count}</dd>
+        <dt className="text-muted-foreground font-medium">User ID</dt>
+        <dd className="font-mono text-xs text-muted-foreground break-all">{user.id}</dd>
+      </dl>
+    </div>
+  );
+}
+
+// ── MessageRow / MemoryBucketView (audit sub-components) ────────────────────
+
+function MessageRow({ message }: { message: AdminMessage }) {
+  const role = roleOf(message);
+  if (!role) return null;
+  const text = extractText(message.content).trim();
+  if (!text) return null;
+  return (
+    <div
+      className={cn(
+        "flex flex-col gap-1",
+        role === "user" ? "items-start" : "items-end",
+      )}
+    >
+      <span className="text-muted-foreground text-xs">
+        {role === "user" ? "用户提问" : "AI 回答"}
+      </span>
+      <div
+        className={cn(
+          "max-w-[85%] whitespace-pre-wrap rounded-lg border px-3 py-2 text-sm",
+          role === "user" ? "bg-muted" : "bg-primary/5 border-primary/20",
+        )}
+      >
+        {text}
+      </div>
+    </div>
+  );
+}
+
+// ── UserAuditPanel ──────────────────────────────────────────────────────────
+
+function UserAuditPanel({ userId }: { userId: string }) {
+  const [threadId, setThreadId] = useState<string | null>(null);
+
+  const { data: threads, isLoading: threadsLoading } = useUserThreads(userId);
+  const { data: messages, isLoading: messagesLoading } = useUserThreadMessages(
+    userId,
+    threadId,
+  );
+
+  return (
+    <div className="flex min-h-0 flex-1">
+      {/* Thread list */}
+      <div className="flex w-60 shrink-0 flex-col border-r">
+        <div className="text-muted-foreground border-b px-3 py-2 text-xs font-medium">
+          会话列表{threads ? `（${threads.length}）` : ""}
+        </div>
+        <ScrollArea className="min-h-0 flex-1">
+          {threadsLoading && (
+            <div className="text-muted-foreground flex items-center justify-center gap-2 py-8 text-sm">
+              <Loader2 className="size-4 animate-spin" /> 加载中
+            </div>
+          )}
+          {!threadsLoading && (threads?.length ?? 0) === 0 && (
+            <div className="text-muted-foreground py-8 text-center text-sm">
+              该用户暂无会话
+            </div>
+          )}
+          <div className="flex flex-col p-1">
+            {(threads ?? []).map((thread) => (
+              <button
+                key={thread.thread_id}
+                type="button"
+                onClick={() => setThreadId(thread.thread_id)}
+                className={cn(
+                  "flex flex-col gap-0.5 rounded-md px-2 py-2 text-left",
+                  thread.thread_id === threadId ? "bg-accent" : "hover:bg-muted",
+                )}
+              >
+                <span className="truncate text-sm">
+                  {thread.display_name || "未命名会话"}
+                </span>
+                <span className="text-muted-foreground text-xs">
+                  {fmtTime(thread.updated_at)}
+                </span>
+              </button>
+            ))}
+          </div>
+        </ScrollArea>
+      </div>
+
+      {/* Messages */}
+      <ScrollArea className="min-h-0 flex-1">
+        <div className="p-4">
+          {!threadId && (
+            <div className="text-muted-foreground flex flex-col items-center gap-2 py-16 text-sm dark:text-[#AACEF8]">
+              <MessageSquareIcon className="size-6" />
+              请从左侧选择一个会话
+            </div>
+          )}
+          {threadId && messagesLoading && (
+            <div className="text-muted-foreground flex items-center justify-center gap-2 py-16 text-sm">
+              <Loader2 className="size-4 animate-spin" /> 加载中
+            </div>
+          )}
+          {threadId && !messagesLoading && (
+            <div className="flex flex-col gap-3">
+              {(messages ?? []).map((m, i) => (
+                <MessageRow key={m.id ?? i} message={m} />
+              ))}
+              {(messages ?? []).every((m) => !roleOf(m)) && (
+                <div className="text-muted-foreground py-12 text-center text-sm">
+                  该会话暂无问答记录
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      </ScrollArea>
+    </div>
+  );
+}
+
+// ── AgentMemoryPanel ─────────────────────────────────────────────────────────
+
+function bucketLabel(name: string, displayName?: string): string {
+  if (name === "default") return "默认智能体";
+  return displayName || name;
+}
+
+function AgentMemoryPanel({ userId }: { userId: string }) {
+  const { data: memory, isLoading } = useUserMemory(userId);
+  // 默认选中"默认助手"（"default" 对应全局记忆文件）
+  const [selectedAgent, setSelectedAgent] = useState<string>("default");
+
+  if (isLoading) {
+    return (
+      <div className="text-muted-foreground flex flex-1 items-center justify-center gap-2 text-sm">
+        <Loader2 className="size-4 animate-spin" /> 加载中…
+      </div>
+    );
+  }
+
+  const isV1 = memory?.version === "v1";
+
+  // 非 global、非 default 的其他智能体 bucket
+  const otherBuckets = (memory?.buckets ?? []).filter(
+    (b) => b.name !== "global" && b.name !== "default",
+  );
+
+  // 当前选中的 bucket
+  const currentBucket = (memory?.buckets ?? []).find(
+    (b) => b.name === selectedAgent,
+  );
+
+  // "default" 对应 agent=null（全局记忆文件），与 _resolve_agent_name 的哨兵逻辑一致
+  const bucketAgentParam = selectedAgent === "default" ? null : selectedAgent;
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <ScrollArea className="min-h-0 flex-1">
+        <div className="space-y-4 p-4">
+          {/* 智能体下拉选择器 */}
+          <div className="flex items-center gap-2">
+            <span className="text-muted-foreground text-sm shrink-0">智能体：</span>
+            <Select value={selectedAgent} onValueChange={setSelectedAgent}>
+              <SelectTrigger className="h-8 w-48" size="sm">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent position="popper" side="bottom" sideOffset={4}>
+                {/* 默认助手始终显示，对应全局记忆文件 */}
+                <SelectItem value="default">默认助手</SelectItem>
+                {otherBuckets.map((b) => (
+                  <SelectItem key={b.name} value={b.name}>
+                    {bucketLabel(b.name, b.display_name)}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            {!isV1 && currentBucket && (
+              <span className="text-muted-foreground text-xs">
+                {getEntries(currentBucket.data).length} 条
+              </span>
+            )}
+          </div>
+
+          {/* 当前智能体记忆内容 */}
+          {!currentBucket ? (
+            <div className="text-muted-foreground rounded-md border border-dashed p-4 text-center text-sm">
+              暂无记忆数据
+            </div>
+          ) : isV1 ? (
+            <V1BucketView
+              data={currentBucket.data}
+              agent={bucketAgentParam}
+              userId={userId}
+            />
+          ) : (
+            <MemoryEntryList
+              entries={getEntries(currentBucket.data)}
+              userId={userId}
+              agent={bucketAgentParam}
+            />
+          )}
+        </div>
+      </ScrollArea>
+    </div>
+  );
+}
+
+// ── AdminUserHub (main) ─────────────────────────────────────────────────────
+
+export function AdminUserHub() {
+  const { data: users, isLoading: usersLoading } = useAllUsers(true);
+  const [selectedUserId, setSelectedUserId] = useState<string | null>(null);
+  const [userQuery, setUserQuery] = useState("");
+  const [activeTab, setActiveTab] = useState<"info" | "audit" | "memory">("info");
+
+  const filteredUsers = useMemo(() => {
+    const needle = userQuery.trim().toLowerCase();
+    const list = users ?? [];
+    return needle
+      ? list.filter((u) => u.email.toLowerCase().includes(needle))
+      : list;
+  }, [users, userQuery]);
+
+  const selectedUser = users?.find((u) => u.id === selectedUserId) ?? null;
+
+  function selectUser(id: string) {
+    setSelectedUserId(id);
+    setActiveTab("info");
+  }
+
+  return (
+    <div className="flex size-full flex-col">
+      <div className="border-b px-6 py-4">
+        <h1 className="text-xl font-semibold">Admin 用户中心</h1>
+        <p className="text-muted-foreground mt-0.5 text-sm">
+          管理用户信息、审计历史问答、编辑用户记忆。
+        </p>
+      </div>
+
+      <div className="flex min-h-0 flex-1">
+        {/* Left: user list */}
+        <div className="flex w-64 shrink-0 flex-col border-r">
+          <div className="relative p-2">
+            <SearchIcon className="text-muted-foreground absolute left-4 top-1/2 size-4 -translate-y-1/2" />
+            <Input
+              value={userQuery}
+              onChange={(e) => setUserQuery(e.target.value)}
+              placeholder="搜索用户邮箱"
+              className="pl-8"
+            />
+          </div>
+          <ScrollArea className="min-h-0 flex-1">
+            {usersLoading && (
+              <div className="text-muted-foreground flex items-center justify-center gap-2 py-8 text-sm">
+                <Loader2 className="size-4 animate-spin" /> 加载中
+              </div>
+            )}
+            {!usersLoading && filteredUsers.length === 0 && (
+              <div className="text-muted-foreground py-8 text-center text-sm">
+                无用户
+              </div>
+            )}
+            <div className="flex flex-col p-1">
+              {filteredUsers.map((u) => (
+                <button
+                  key={u.id}
+                  type="button"
+                  onClick={() => selectUser(u.id)}
+                  className={cn(
+                    "flex items-center gap-2 rounded-md px-2 py-2 text-left text-sm",
+                    u.id === selectedUserId
+                      ? "bg-accent font-medium"
+                      : "hover:bg-muted",
+                  )}
+                >
+                  <UserIcon className="text-muted-foreground size-4 shrink-0" />
+                  <span className="flex-1 truncate">{u.email}</span>
+                  {u.system_role === "admin" && (
+                    <Badge variant="outline" className="shrink-0 text-xs">
+                      管理员
+                    </Badge>
+                  )}
+                </button>
+              ))}
+            </div>
+          </ScrollArea>
+        </div>
+
+        {/* Right: tabs */}
+        {!selectedUserId ? (
+          <div className="text-muted-foreground flex flex-1 items-center justify-center text-sm">
+            从左侧选择一个用户
+          </div>
+        ) : (
+          <Tabs
+            value={activeTab}
+            onValueChange={(v) => setActiveTab(v as typeof activeTab)}
+            className="flex min-w-0 flex-1 flex-col overflow-hidden"
+          >
+            <div className="border-b px-4 pt-3 shrink-0">
+              <TabsList variant="line">
+                <TabsTrigger value="info">用户信息</TabsTrigger>
+                <TabsTrigger value="audit">活动审计</TabsTrigger>
+                <TabsTrigger value="memory">记忆管理</TabsTrigger>
+              </TabsList>
+            </div>
+
+            <TabsContent value="info" className="flex-1 overflow-auto p-0">
+              {selectedUser && <UserInfoPanel user={selectedUser} />}
+            </TabsContent>
+
+            <TabsContent
+              value="audit"
+              className="flex min-h-0 flex-1 flex-col p-0"
+            >
+              <UserAuditPanel key={selectedUserId} userId={selectedUserId} />
+            </TabsContent>
+
+            <TabsContent
+              value="memory"
+              className="flex min-h-0 flex-1 flex-col p-0"
+            >
+              <AgentMemoryPanel key={selectedUserId} userId={selectedUserId} />
+            </TabsContent>
+          </Tabs>
+        )}
+      </div>
+    </div>
+  );
+}

frontend-web/src/components/workspace/admin/tag-management-page.tsx

@@ -224,16 +224,16 @@ export function TagManagementPage() {
               <table className="w-full text-sm">
                 <thead className="bg-muted/50">
                   <tr>
-                    <th className="text-muted-foreground px-4 py-3 text-left font-medium">
+                    <th className="text-muted-foreground px-4 py-3 text-left font-medium dark:text-white">
                       {t.adminTags.name}
                     </th>
-                    <th className="text-muted-foreground px-4 py-3 text-left font-medium">
+                    <th className="text-muted-foreground px-4 py-3 text-left font-medium dark:text-white">
                       {t.adminTags.tagDescription}
                     </th>
-                    <th className="text-muted-foreground px-4 py-3 text-right font-medium">
+                    <th className="text-muted-foreground px-4 py-3 text-right font-medium dark:text-white">
                       {t.adminTags.usageCount}
                     </th>
-                    <th className="text-muted-foreground px-4 py-3 text-right font-medium">
+                    <th className="text-muted-foreground px-4 py-3 text-right font-medium dark:text-white">
                       {t.adminTags.actions}
                     </th>
                   </tr>

frontend-web/src/components/workspace/admin/tool-metrics-panel.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Download, Loader2 } from "lucide-react";
+import { AlertCircle,CheckCircle2, Download, Loader2 } from "lucide-react";
 import { useMemo, useState } from "react";
 import { toast } from "sonner";
 
@@ -29,6 +29,7 @@ import {
 } from "@/core/tool-metrics/api";
 import { useToolMetrics, useToolMetricsSummary } from "@/core/tool-metrics/hooks";
 import { cn } from "@/lib/utils";
+import { useTheme } from "@/contexts/ThemeContext";
 
 const PAGE_SIZE = 50;
 
@@ -66,6 +67,7 @@ function categoryLabel(category?: string | null): string {
 }
 
 export function ToolMetricsPanel() {
+  const { theme } = useTheme();
   const [page, setPage] = useState(0);
   const [tool, setTool] = useState("");
   const [user, setUser] = useState("");
@@ -79,6 +81,31 @@ export function ToolMetricsPanel() {
   const [until, setUntil] = useState("");
   const [exporting, setExporting] = useState(false);
   const [detailRow, setDetailRow] = useState<ToolMetric | null>(null);
+/** 成功 toast：仅暗色模式，浅色走 Sonner 默认 */
+const successToastDarkOptions = {
+  classNames: {
+    toast:
+      "!rounded-[2px] !border !border-[#106455] !bg-[#052934] !text-[#FFFFFF] shadow-md",
+    title: "!text-[#FFFFFF]",
+    description: "!text-[#FFFFFF]",
+  },
+  icon: <CheckCircle2 className="size-4 shrink-0 text-[#2FD69A]" />,
+} as const;
+
+/** 失败 toast：仅暗色模式，浅色走 Sonner 默认 */
+const errorToastDarkOptions = {
+  classNames: {
+    toast:
+      "!rounded-[2px] !border !border-[#7F1A2A] !bg-[#311629] !text-[#FFFFFF] shadow-md",
+    title: "!text-[#FFFFFF]",
+    description: "!text-[#FFFFFF]",
+  },
+  icon: <AlertCircle className="size-4 shrink-0 text-[#F5222D]" />,
+} as const;
+  const darkToastOpts =
+    theme === "dark"
+      ? { success: successToastDarkOptions, error: errorToastDarkOptions }
+      : { success: undefined, error: undefined };
 
   const filters = useMemo<ToolMetricsFilters>(() => {
     const out: ToolMetricsFilters = {};
@@ -117,9 +144,9 @@ export function ToolMetricsPanel() {
     setExporting(true);
     try {
       await downloadToolMetricsExcel(filters);
-      toast.success("已导出为 Excel");
+      toast.success("已导出为 Excel",darkToastOpts.success);
     } catch (e) {
-      toast.error(e instanceof Error ? e.message : "导出失败");
+      toast.error(e instanceof Error ? e.message : "导出失败",darkToastOpts.error);
     } finally {
       setExporting(false);
     }
@@ -167,7 +194,7 @@ export function ToolMetricsPanel() {
       </div>
 
       {/* Summary strip */}
-      <div className="flex flex-wrap items-center gap-2 rounded-xl border bg-white p-4">
+      <div className="flex flex-wrap items-center gap-2 rounded-xl border bg-white p-4 dark:border-[#213D5E] dark:bg-[#02244C] dark:text-white">
         <div className="mr-4 flex flex-col">
           <span className="text-muted-foreground text-xs">总调用</span>
           <span className="text-lg font-semibold tabular-nums">
@@ -213,7 +240,7 @@ export function ToolMetricsPanel() {
 
       {/* Per-skill breakdown — answers "was skill X invoked, and did it succeed". */}
       {summary && summary.by_skill.length > 0 && (
-        <div className="rounded-xl border bg-white p-4">
+        <div className="rounded-xl border bg-white p-4 ">
           <h3 className="mb-2 text-sm font-medium">各技能调用情况</h3>
           <div className="overflow-x-auto">
             <table className="w-full text-sm">
@@ -258,7 +285,7 @@ export function ToolMetricsPanel() {
         </div>
       )}
       {summary && kind === "skill" && summary.by_skill.length === 0 && (
-        <div className="text-muted-foreground rounded-xl border bg-white p-4 text-sm">
+        <div className="text-muted-foreground rounded-xl border bg-white p-4 text-sm dark:border-[#213D5E] dark:bg-[#02244C] dark:text-white">
           当前筛选范围内没有检测到任何技能调用记录。技能只有在被 Agent 通过
           <code className="bg-muted mx-1 rounded px-1">skill_view</code>
           读取(即真正"调用")时才会被记录;仅在系统提示里被列出、但未被读取的技能不会计入。
@@ -266,9 +293,9 @@ export function ToolMetricsPanel() {
       )}
 
       {/* Filters */}
-      <div className="grid gap-3 rounded-xl border bg-white p-4 md:grid-cols-3 lg:grid-cols-6">
+      <div className="grid gap-3 rounded-xl border bg-white p-4 md:grid-cols-3 lg:grid-cols-6 dark:border-[#213D5E] dark:bg-[#02244C] dark:text-white">
         <div className="flex flex-col gap-1">
-          <label className="text-muted-foreground text-xs">调用类型</label>
+          <label className="text-muted-foreground text-xs dark:text-white">调用类型</label>
           <Select
             value={kind}
             onValueChange={(value) => {
@@ -276,17 +303,17 @@ export function ToolMetricsPanel() {
               setPage(0);
             }}
           >
-            <SelectTrigger>
+            <SelectTrigger className="dark:bg-[#0D2D54] dark:hover:bg-[#0D2D54]">
               <SelectValue />
             </SelectTrigger>
-            <SelectContent>
+            <SelectContent position="popper" side="bottom" sideOffset={4}>
               <SelectItem value="skill">技能（Agent Skill）</SelectItem>
               <SelectItem value="all">全部工具调用</SelectItem>
             </SelectContent>
           </Select>
         </div>
         <div className="flex flex-col gap-1">
-          <label className="text-muted-foreground text-xs">技能名称</label>
+          <label className="text-muted-foreground text-xs dark:text-white">技能名称</label>
           <Input
             value={skill}
             placeholder="按技能名筛选"
@@ -297,7 +324,7 @@ export function ToolMetricsPanel() {
           />
         </div>
         <div className="flex flex-col gap-1">
-          <label className="text-muted-foreground text-xs">工具名</label>
+          <label className="text-muted-foreground text-xs dark:text-white">工具名</label>
           <Input
             value={tool}
             placeholder="按工具名筛选"
@@ -308,7 +335,7 @@ export function ToolMetricsPanel() {
           />
         </div>
         <div className="flex flex-col gap-1">
-          <label className="text-muted-foreground text-xs">用户名</label>
+          <label className="text-muted-foreground text-xs dark:text-white">用户名</label>
           <Input
             value={user}
             placeholder="@ 前部分"
@@ -319,7 +346,7 @@ export function ToolMetricsPanel() {
           />
         </div>
         <div className="flex flex-col gap-1">
-          <label className="text-muted-foreground text-xs">状态</label>
+          <label className="text-muted-foreground text-xs dark:text-white">状态</label>
           <Select
             value={status}
             onValueChange={(value) => {
@@ -327,10 +354,10 @@ export function ToolMetricsPanel() {
               setPage(0);
             }}
           >
-            <SelectTrigger>
+            <SelectTrigger className="w-full dark:bg-[#0D2D54] dark:hover:bg-[#0D2D54]">
               <SelectValue />
             </SelectTrigger>
-            <SelectContent>
+            <SelectContent position="popper" side="bottom" sideOffset={4}>
               <SelectItem value="all">全部</SelectItem>
               <SelectItem value="success">成功</SelectItem>
               <SelectItem value="error">失败</SelectItem>
@@ -338,7 +365,7 @@ export function ToolMetricsPanel() {
           </Select>
         </div>
         <div className="flex flex-col gap-1">
-          <label className="text-muted-foreground text-xs">错误类型</label>
+          <label className="text-muted-foreground text-xs dark:text-white">错误类型</label>
           <Select
             value={category}
             onValueChange={(value) => {
@@ -346,10 +373,10 @@ export function ToolMetricsPanel() {
               setPage(0);
             }}
           >
-            <SelectTrigger>
+            <SelectTrigger className="w-full dark:bg-[#0D2D54] dark:hover:bg-[#0D2D54]">
               <SelectValue />
             </SelectTrigger>
-            <SelectContent>
+            <SelectContent  position="popper" side="bottom" sideOffset={4}>
               <SelectItem value="all">全部</SelectItem>
               {TOOL_ERROR_CATEGORIES.map((cat) => (
                 <SelectItem key={cat} value={cat}>
@@ -360,7 +387,7 @@ export function ToolMetricsPanel() {
           </Select>
         </div>
         <div className="flex flex-col gap-1">
-          <label className="text-muted-foreground text-xs">开始时间</label>
+          <label className="text-muted-foreground text-xs dark:text-white">开始时间</label>
           <Input
             type="datetime-local"
             value={since}
@@ -371,7 +398,7 @@ export function ToolMetricsPanel() {
           />
         </div>
         <div className="flex flex-col gap-1">
-          <label className="text-muted-foreground text-xs">结束时间</label>
+          <label className="text-muted-foreground text-xs dark:text-white">结束时间</label>
           <Input
             type="datetime-local"
             value={until}
@@ -389,10 +416,10 @@ export function ToolMetricsPanel() {
       </div>
 
       {/* Table */}
-      <div className="rounded-xl border bg-white">
+      <div className="rounded-xl border bg-white dark:border-[#213D5E] dark:bg-[#02244C] dark:text-white">
         <div className="overflow-x-auto">
           <table className="w-full min-w-[960px] text-sm">
-            <thead className="bg-muted/60 text-muted-foreground">
+            <thead className="bg-muted/60 text-muted-foreground dark:text-white">
               <tr>
                 <Th>时间</Th>
                 <Th>用户</Th>

frontend-web/src/components/workspace/agent-welcome.tsx

@@ -3,6 +3,7 @@
 import { BotIcon } from "lucide-react";
 
 import { type Agent } from "@/core/agents";
+import { desensitize } from "@/lib/desensitize";
 import { cn } from "@/lib/utils";
 
 export function AgentWelcome({
@@ -14,8 +15,10 @@ export function AgentWelcome({
   agent: Agent | null | undefined;
   agentName: string;
 }) {
-  const displayName = agent?.name ?? agentName;
-  const description = agent?.description;
+  const displayName = desensitize(agent?.name ?? agentName);
+  const description = agent?.description
+    ? desensitize(agent.description)
+    : undefined;
 
   return (
     <div

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

@@ -2,12 +2,15 @@
 
 import {
   BotIcon,
+  CopyIcon,
   GlobeIcon,
   InfoIcon,
   LockIcon,
   MessageSquareIcon,
+  ShieldIcon,
   SparklesIcon,
   SquarePenIcon,
+  StarIcon,
   TagsIcon,
   Trash2Icon,
 } from "lucide-react";
@@ -40,14 +43,20 @@ import { SkillDetailDialog } from "@/components/workspace/skills/skill-detail-di
 import { TagChipList } from "@/components/workspace/tags/tag-chip";
 import { TagPickerDialog } from "@/components/workspace/tags/tag-picker-dialog";
 import {
+  useAgent,
+  useCreateAgent,
   useDeleteAgent,
   useSetAgentFeatured,
+  useSetAgentPrivate,
+  useToggleAgentFavorite,
   useUpdateAgent,
 } from "@/core/agents";
+import { getAgent } from "@/core/agents/api";
 import type { Agent } from "@/core/agents";
 import { getStoredAuth } from "@/core/auth";
 import { useI18n } from "@/core/i18n/hooks";
 import { useSkills } from "@/core/skills/hooks";
+import { desensitize } from "@/lib/desensitize";
 import { cn } from "@/lib/utils";
 
 interface AgentCardProps {
@@ -59,7 +68,10 @@ export function AgentCard({ agent }: AgentCardProps) {
   const router = useRouter();
   const deleteAgent = useDeleteAgent();
   const updateAgent = useUpdateAgent();
+  const createAgent = useCreateAgent();
   const setFeatured = useSetAgentFeatured();
+  const setPrivate = useSetAgentPrivate();
+  const toggleFavorite = useToggleAgentFavorite();
   const { skills, isLoading: isSkillsLoading } = useSkills();
   const [deleteOpen, setDeleteOpen] = useState(false);
   const [editOpen, setEditOpen] = useState(false);
@@ -68,11 +80,19 @@ export function AgentCard({ agent }: AgentCardProps) {
   const [editDescription, setEditDescription] = useState(agent.description ?? "");
   const [editSoul, setEditSoul] = useState(agent.soul ?? "");
   const [editPublished, setEditPublished] = useState(agent.published);
+  const [editIsPrivate, setEditIsPrivate] = useState(agent.is_private);
   const [selectedSkills, setSelectedSkills] = useState<string[]>(
     agent.skills ?? [],
   );
   const [detailSkillName, setDetailSkillName] = useState<string | null>(null);
 
+  // The /api/agents list response intentionally omits `soul` (perf optimization
+  // — SOUL.md is only read on demand). Fetch the detail row when the edit
+  // dialog opens so the SOUL textarea can be hydrated.
+  const { agent: agentDetail, isLoading: isAgentDetailLoading } = useAgent(
+    editOpen ? agent.id : null,
+  );
+
   const storedAuth = useMemo(() => getStoredAuth(), []);
   const currentUserId = storedAuth?.user_id ?? null;
   const isAdmin = storedAuth?.system_role === "admin";
@@ -80,11 +100,16 @@ export function AgentCard({ agent }: AgentCardProps) {
   const isOwned =
     !isBuiltin && agent.user_id !== null && agent.user_id === currentUserId;
   const isFromOthers = !isBuiltin && !isOwned;
-  // System admins are allowed to edit and delete built-in agents.
+  // System admins are allowed to edit and delete any agent (built-in or owned
+  // by another user) so the admin console can manage the full catalog.
   // Publish-toggle stays owner-only — built-ins are inherently visible to
   // everyone so toggling published is moot.
-  const canEdit = isOwned || (isBuiltin && isAdmin);
-  const canDelete = isOwned || (isBuiltin && isAdmin);
+  const canEdit = isOwned || isAdmin;
+  const canDelete = isOwned || isAdmin;
+  // Favoriting collects a square agent into "我的"; pointless for one you
+  // already own, so only offer it on built-in / others' agents.
+  const canFavorite = !isOwned;
+  const isFavorite = !!agent.is_favorite;
 
   useEffect(() => {
     if (!editOpen) {
@@ -92,18 +117,32 @@ export function AgentCard({ agent }: AgentCardProps) {
     }
     setEditName(agent.name);
     setEditDescription(agent.description ?? "");
-    setEditSoul(agent.soul ?? "");
     setEditPublished(agent.published);
+    setEditIsPrivate(agent.is_private);
     setSelectedSkills(agent.skills ?? []);
   }, [
     agent.description,
+    agent.is_private,
     agent.name,
     agent.published,
     agent.skills,
-    agent.soul,
     editOpen,
   ]);
 
+  useEffect(() => {
+    if (!editOpen) {
+      return;
+    }
+    // SOUL.md only ships on the detail endpoint; fall back to whatever the list
+    // happened to carry so older deployments (or cached objects that still
+    // include `soul`) keep working.
+    if (agentDetail) {
+      setEditSoul(agentDetail.soul ?? "");
+    } else {
+      setEditSoul(agent.soul ?? "");
+    }
+  }, [agent.soul, agentDetail, editOpen]);
+
   function handleChat() {
     router.push(`/page/workspace/agents/${agent.id}/chats/new`);
   }
@@ -118,12 +157,51 @@ export function AgentCard({ agent }: AgentCardProps) {
     }
   }
 
+  async function handleDuplicate() {
+    if (createAgent.isPending) {
+      return;
+    }
+    try {
+      // SOUL.md is omitted from the list payload (perf), so fetch the detail
+      // row to carry the source agent's personality into the copy. Fall back
+      // to whatever the list happened to include if the detail fetch fails.
+      let soul = agent.soul ?? "";
+      try {
+        const detail = await getAgent(agent.id);
+        soul = detail.soul ?? soul;
+      } catch {
+        // keep the list fallback
+      }
+      const created = await createAgent.mutateAsync({
+        name: `${agent.name} 副本`,
+        description: agent.description ?? "",
+        soul,
+        skills: agent.skills ?? [],
+        model: agent.model ?? null,
+        tool_groups: agent.tool_groups ?? null,
+        // A copy starts as a private, unpublished draft the owner can refine
+        // before sharing — never inherit the source's published/private state.
+        published: false,
+        is_private: false,
+      });
+      toast.success(
+        `已复制为「${desensitize(created.name)}」，可在「我的」中编辑`,
+      );
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
   async function handleSaveEdit() {
     const trimmedName = editName.trim();
     if (!trimmedName) {
       toast.error(t.agents.nameStepInvalidError ?? "名称不能为空");
       return;
     }
+    if (editIsPrivate && editPublished) {
+      toast.warning("私密广场与公开发布互斥，请只勾选其一");
+      return;
+    }
     try {
       await updateAgent.mutateAsync({
         id: agent.id,
@@ -131,7 +209,10 @@ export function AgentCard({ agent }: AgentCardProps) {
           name: trimmedName,
           description: editDescription,
           soul: editSoul,
-          published: editPublished,
+          // Private agents cannot also be published — force the value the
+          // backend will see, regardless of any stale state in editPublished.
+          published: editIsPrivate ? false : editPublished,
+          is_private: editIsPrivate,
           skills: selectedSkills,
         },
       });
@@ -143,6 +224,13 @@ export function AgentCard({ agent }: AgentCardProps) {
   }
 
   async function handleTogglePublished() {
+    // Private and public squares are mutually exclusive — a private agent
+    // can't simultaneously be published to everyone. Block the toggle
+    // instead of silently moving the agent between squares.
+    if (!agent.published && agent.is_private) {
+      toast.warning("该智能体已加入私密广场，不可发布");
+      return;
+    }
     try {
       await updateAgent.mutateAsync({
         id: agent.id,
@@ -154,6 +242,37 @@ export function AgentCard({ agent }: AgentCardProps) {
     }
   }
 
+  async function handleTogglePrivate() {
+    const turningOn = !agent.is_private;
+    try {
+      if (isOwned) {
+        // Owners can re-categorize their own agents through the normal update
+        // endpoint — keeps publish/private edits in one transaction.
+        await updateAgent.mutateAsync({
+          id: agent.id,
+          request: { is_private: turningOn },
+        });
+      } else {
+        // Admins can move any agent (built-in or other users') via the
+        // dedicated admin endpoint.
+        await setPrivate.mutateAsync({ id: agent.id, isPrivate: turningOn });
+      }
+      toast.success(turningOn ? "已加入私密广场" : "已移出私密广场");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async function handleToggleFavorite() {
+    const next = !isFavorite;
+    try {
+      await toggleFavorite.mutateAsync({ id: agent.id, favorite: next });
+      toast.success(next ? "已收藏到「我的」" : "已取消收藏");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
   async function handleToggleFeatured() {
     // One-click on/off — ordering is handled by the dedicated 管理 Agent 列表
     // dialog. Featured agents get appended to the end on add (Date.now() is a
@@ -187,20 +306,23 @@ export function AgentCard({ agent }: AgentCardProps) {
 
   return (
     <>
-      <Card className="group flex flex-col transition-shadow hover:shadow-md">
-        <CardHeader className="pb-3">
-          <div className="flex items-start justify-between gap-2">
-            <div className="flex items-center gap-2">
+      <Card className="group flex min-w-0 flex-col transition-shadow hover:shadow-md">
+        <CardHeader className="min-w-0 pb-3">
+          <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="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">
-                <CardTitle className="truncate text-base">
-                  {agent.name}
+              <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(agent.name)}
+                >
+                  {desensitize(agent.name)}
                 </CardTitle>
                 {agent.model && (
                   <Badge variant="secondary" className="mt-0.5 text-xs">
-                    {agent.model}
+                    {desensitize(agent.model)}
                   </Badge>
                 )}
               </div>
@@ -228,7 +350,7 @@ export function AgentCard({ agent }: AgentCardProps) {
                   来自他人
                 </Badge>
               )}
-              {isOwned && agent.published && (
+              {isOwned && agent.published && !agent.is_private && (
                 <Badge
                   variant="outline"
                   className="border-sky-500/30 text-sky-700 dark:text-sky-300 text-xs"
@@ -238,6 +360,16 @@ export function AgentCard({ agent }: AgentCardProps) {
                   已发布
                 </Badge>
               )}
+              {agent.is_private && (
+                <Badge
+                  variant="outline"
+                  className="border-purple-500/30 text-purple-700 dark:text-purple-300 text-xs"
+                  title="该智能体位于私密广场，需要密码才能查看"
+                >
+                  <ShieldIcon className="size-3" />
+                  私密
+                </Badge>
+              )}
               {agent.featured_order != null && (
                 <Badge
                   variant="outline"
@@ -252,7 +384,7 @@ export function AgentCard({ agent }: AgentCardProps) {
           </div>
           {agent.description && (
             <CardDescription className="mt-2 line-clamp-2 text-sm">
-              {agent.description}
+              {desensitize(agent.description)}
             </CardDescription>
           )}
         </CardHeader>
@@ -272,7 +404,7 @@ export function AgentCard({ agent }: AgentCardProps) {
                   variant="outline"
                   className="text-xs"
                 >
-                  {group}
+                  {desensitize(group)}
                 </Badge>
               ))}
               {agent.skills?.map((skill) => (
@@ -286,20 +418,33 @@ export function AgentCard({ agent }: AgentCardProps) {
                     setDetailSkillName(skill);
                   }}
                 >
-                  {skill}
+                  {desensitize(skill)}
                 </Badge>
               ))}
             </div>
           </CardContent>
         )}
 
-        <CardFooter className="mt-auto flex items-center justify-between gap-2 pt-3">
-          <Button size="sm" className="flex-1" onClick={handleChat}>
-            <MessageSquareIcon className="mr-1.5 h-3.5 w-3.5" />
-            {t.agents.chat}
-          </Button>
-          {(canEdit || canDelete || isOwned || isAdmin) && (
-            <div className="flex gap-1">
+        <CardFooter className="mt-auto flex flex-col items-stretch gap-2 pt-3">
+          {(canEdit || canDelete || isOwned || isAdmin || canFavorite) && (
+            <div className="flex flex-wrap items-center justify-end gap-1">
+              {canFavorite && (
+                <Button
+                  size="icon"
+                  variant="ghost"
+                  className={cn(
+                    "mr-auto h-8 w-8 shrink-0",
+                    isFavorite && "text-amber-500 hover:text-amber-600",
+                  )}
+                  onClick={() => void handleToggleFavorite()}
+                  disabled={toggleFavorite.isPending}
+                  title={isFavorite ? "取消收藏" : "收藏到「我的」"}
+                >
+                  <StarIcon
+                    className={cn("h-3.5 w-3.5", isFavorite && "fill-current")}
+                  />
+                </Button>
+              )}
               {isAdmin && (
                 <Button
                   size="icon"
@@ -347,6 +492,34 @@ export function AgentCard({ agent }: AgentCardProps) {
                   )}
                 </Button>
               )}
+              {(isOwned || isAdmin) && (
+                <Button
+                  size="icon"
+                  variant="ghost"
+                  className={cn(
+                    "h-8 w-8 shrink-0",
+                    agent.is_private &&
+                      "text-purple-600 hover:text-purple-700",
+                  )}
+                  onClick={() => void handleTogglePrivate()}
+                  disabled={updateAgent.isPending || setPrivate.isPending}
+                  title={
+                    agent.is_private ? "移出私密广场" : "放入私密广场"
+                  }
+                >
+                  <ShieldIcon className="h-3.5 w-3.5" />
+                </Button>
+              )}
+              <Button
+                size="icon"
+                variant="ghost"
+                className="h-8 w-8 shrink-0"
+                onClick={() => void handleDuplicate()}
+                disabled={createAgent.isPending}
+                title="复制为新智能体"
+              >
+                <CopyIcon className="h-3.5 w-3.5" />
+              </Button>
               {canEdit && (
                 <Button
                   size="icon"
@@ -371,13 +544,17 @@ export function AgentCard({ agent }: AgentCardProps) {
               )}
             </div>
           )}
+          <Button size="sm" className="w-full" onClick={handleChat}>
+            <MessageSquareIcon className="mr-1.5 h-3.5 w-3.5" />
+            {t.agents.chat}
+          </Button>
         </CardFooter>
       </Card>
 
       <Dialog open={editOpen} onOpenChange={setEditOpen}>
         <DialogContent className="max-h-[85vh] overflow-y-auto sm:max-w-2xl">
           <DialogHeader>
-            <DialogTitle>编辑智能体:{agent.name}</DialogTitle>
+            <DialogTitle>编辑智能体:{desensitize(agent.name)}</DialogTitle>
             <DialogDescription>
               可以修改名称、描述、技能白名单、SOUL 内容与发布状态。
             </DialogDescription>
@@ -407,7 +584,7 @@ export function AgentCard({ agent }: AgentCardProps) {
                   已选 {selectedSkills.length} 个
                 </span>
               </div>
-              <div className="rounded-md border p-2">
+              <div className="max-h-[240px] overflow-y-auto rounded-md border p-2">
                 {isSkillsLoading ? (
                   <p className="text-muted-foreground text-sm">技能加载中...</p>
                 ) : enabledSkills.length === 0 ? (
@@ -415,23 +592,23 @@ export function AgentCard({ agent }: AgentCardProps) {
                     当前没有可用技能
                   </p>
                 ) : (
-                  <div className="flex flex-wrap gap-2">
+                  <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
                     {enabledSkills.map((skill) => {
                       const checked = selectedSkills.includes(skill.name);
                       return (
                         <div
                           key={skill.name}
-                          className="inline-flex max-w-full items-center"
+                          className="flex w-full min-w-0 items-center"
                         >
                           <Button
                             type="button"
                             size="sm"
                             variant={checked ? "default" : "outline"}
                             onClick={() => toggleSkill(skill.name)}
-                            title={skill.description}
-                            className="h-8 max-w-[200px] rounded-r-none"
+                            title={desensitize(skill.description ?? "")}
+                            className="h-8 min-w-0 flex-1 rounded-r-none"
                           >
-                            <span className="truncate">{skill.name}</span>
+                            <span className="truncate">{desensitize(skill.name)}</span>
                           </Button>
                           <Button
                             type="button"
@@ -458,7 +635,11 @@ export function AgentCard({ agent }: AgentCardProps) {
               <Textarea
                 value={editSoul ?? ""}
                 onChange={(e) => setEditSoul(e.target.value)}
-                placeholder="输入 SOUL.md 内容"
+                placeholder={
+                  isAgentDetailLoading && !agentDetail
+                    ? "正在加载 SOUL.md..."
+                    : "输入 SOUL.md 内容"
+                }
                 className="min-h-40 font-mono text-xs"
               />
             </div>
@@ -466,12 +647,41 @@ export function AgentCard({ agent }: AgentCardProps) {
               <div>
                 <p className="text-sm font-medium">公开发布</p>
                 <p className="text-muted-foreground text-xs">
-                  打开后,该智能体对所有用户可见。
+                  {editIsPrivate
+                    ? "已加入私密广场，不可发布；请先关闭私密广场。"
+                    : "打开后,该智能体对所有用户可见。"}
                 </p>
               </div>
               <Switch
-                checked={editPublished}
-                onCheckedChange={setEditPublished}
+                checked={editPublished && !editIsPrivate}
+                disabled={editIsPrivate}
+                onCheckedChange={(v) => {
+                  if (editIsPrivate) {
+                    toast.warning("该智能体已加入私密广场，不可发布");
+                    return;
+                  }
+                  setEditPublished(v);
+                }}
+              />
+            </div>
+            <div className="flex items-center justify-between rounded-md border p-3">
+              <div>
+                <p className="text-sm font-medium">加入私密广场</p>
+                <p className="text-muted-foreground text-xs">
+                  打开后,该智能体仅在私密广场显示,需输入密码才能查看;与「公开发布」互斥。
+                </p>
+              </div>
+              <Switch
+                checked={editIsPrivate}
+                onCheckedChange={(v) => {
+                  setEditIsPrivate(v);
+                  if (v) {
+                    // Mutual-exclusion: switching the agent into the private
+                    // square automatically clears the public-publish flag so
+                    // the user can't end up with a half-and-half state.
+                    setEditPublished(false);
+                  }
+                }}
               />
             </div>
           </div>

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

@@ -1,44 +1,141 @@
 "use client";
 
-import { BotIcon, PlusIcon } from "lucide-react";
+import { BotIcon, LockIcon, PlusIcon, ShieldIcon } from "lucide-react";
 import { useRouter } from "next/navigation";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
+import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { TagSearchBar } from "@/components/workspace/tags/tag-search-bar";
-import { useAgents } from "@/core/agents";
+import { useAgents, usePrivateAgents } from "@/core/agents";
+import type { Agent } from "@/core/agents";
 import { getStoredAuth } from "@/core/auth";
 import { useI18n } from "@/core/i18n/hooks";
+import { usePrivateSquareStatus } from "@/core/system-settings/hooks";
+import { desensitize } from "@/lib/desensitize";
 
 import { AgentCard } from "./agent-card";
 
+// Within a single tab the verified password is kept in sessionStorage so a
+// refresh / route navigation does not re-prompt. Cleared on tab close, so the
+// password never persists beyond the browsing session.
+const PRIVATE_SQUARE_PASSWORD_KEY = "deer-flow.private-square-password";
+
 export function AgentGallery() {
   const { t } = useI18n();
   const router = useRouter();
-  const [activeTab, setActiveTab] = useState<"all" | "mine">("mine");
+  const [activeTab, setActiveTab] = useState<"all" | "mine" | "private">(
+    "mine",
+  );
   const [search, setSearch] = useState("");
   const [tagIds, setTagIds] = useState<string[]>([]);
-  // Name + tag filtering is resolved server-side via the /api/agents query.
-  const { agents, isLoading } = useAgents({ search, tagIds });
+  // Tag filtering stays server-side; name search must run on the *desensitized*
+  // form because that's what the user sees on the card. If we sent the search
+  // string to the backend it would compare against the raw stored name and
+  // miss every desensitized hit (e.g. typing "TS分析" wouldn't match the
+  // stored "态势分析").
+  const { agents, isLoading } = useAgents({ tagIds });
+
+  const needle = search.trim().toLowerCase();
+  const matchesSearch = (a: Agent) =>
+    !needle || desensitize(a.name).toLowerCase().includes(needle);
 
   const storedAuth = useMemo(() => getStoredAuth(), []);
   const currentUserId = storedAuth?.user_id ?? null;
 
+  const { data: privateStatus } = usePrivateSquareStatus();
+  const privateFeatureAvailable = !!privateStatus?.enabled;
+  const privateFeatureUsable =
+    privateFeatureAvailable && !!privateStatus?.password_set;
+
+  const [privatePassword, setPrivatePassword] = useState<string | null>(() => {
+    if (typeof window === "undefined") return null;
+    return window.sessionStorage.getItem(PRIVATE_SQUARE_PASSWORD_KEY);
+  });
+  const [passwordInput, setPasswordInput] = useState("");
+
+  const {
+    agents: privateAgents,
+    isLoading: isPrivateLoading,
+    error: privateError,
+  } = usePrivateAgents(privatePassword);
+
+  // If the server reports the stored password no longer works (likely the
+  // admin rotated it), drop it from session storage and re-prompt.
+  useEffect(() => {
+    if (privatePassword && privateError) {
+      window.sessionStorage.removeItem(PRIVATE_SQUARE_PASSWORD_KEY);
+      setPrivatePassword(null);
+      toast.error("私密广场密码已失效，请重新输入");
+    }
+  }, [privateError, privatePassword]);
+
+  // The "广场" tab must never surface private-square agents, even to their
+  // own owner — moving an agent into the private square is supposed to hide
+  // it from the public square entirely. (The backend listing endpoint
+  // already filters them out for non-owners; this extra clause covers the
+  // owner's own private agents, which still come back in the unified list
+  // because owners always see their own.)
   const allAgents = useMemo(
-    () => agents.filter((a) => a.builtin || a.published),
-    [agents],
+    () =>
+      agents.filter(
+        (a) => (a.builtin || a.published) && !a.is_private && matchesSearch(a),
+      ),
+    // matchesSearch closes over `needle`; depending on `search` is sufficient
+    // and avoids re-running on every render via the function reference.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [agents, search],
   );
 
+  // "我的" shows the user's own agents plus any agent they've favorited (收藏)
+  // from the square — favorited public agents have a different user_id but a
+  // truthy is_favorite flag.
   const myAgents = useMemo(
-    () => agents.filter((a) => a.user_id !== null && a.user_id === currentUserId),
-    [agents, currentUserId],
+    () =>
+      agents.filter(
+        (a) =>
+          ((a.user_id !== null && a.user_id === currentUserId) ||
+            a.is_favorite) &&
+          matchesSearch(a),
+      ),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [agents, currentUserId, search],
   );
 
+  const filteredPrivateAgents = useMemo(() => {
+    const wanted = new Set(tagIds);
+    return privateAgents.filter((a) => {
+      if (!matchesSearch(a)) return false;
+      if (wanted.size > 0) {
+        if (!(a.tags ?? []).some((tg) => wanted.has(tg.id))) return false;
+      }
+      return true;
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [privateAgents, search, tagIds]);
+
   const handleNewAgent = () => {
     router.push("/page/workspace/agents/new");
   };
 
+  const handleSubmitPassword = () => {
+    const trimmed = passwordInput.trim();
+    if (!trimmed) {
+      toast.error("请输入密码");
+      return;
+    }
+    window.sessionStorage.setItem(PRIVATE_SQUARE_PASSWORD_KEY, trimmed);
+    setPrivatePassword(trimmed);
+    setPasswordInput("");
+  };
+
+  const handleLockPrivate = () => {
+    window.sessionStorage.removeItem(PRIVATE_SQUARE_PASSWORD_KEY);
+    setPrivatePassword(null);
+  };
+
   const renderGrid = (list: typeof agents) => (
     <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
       {list.map((agent) => (
@@ -49,15 +146,21 @@ export function AgentGallery() {
 
   const renderEmpty = (description: string, showNewButton = false) => (
     <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">
-        <BotIcon className="text-muted-foreground h-7 w-7" />
+      <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">{description}</p>
+        <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 variant="outline" className="mt-2" onClick={handleNewAgent}>
+        <Button
+          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" />
           {t.agents.newAgent}
         </Button>
@@ -65,6 +168,78 @@ export function AgentGallery() {
     </div>
   );
 
+  const renderPrivateTab = () => {
+    if (!privateFeatureAvailable) {
+      return (
+        <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">
+            <ShieldIcon className="text-muted-foreground h-7 w-7" />
+          </div>
+          <p className="font-medium">私密广场尚未开启</p>
+          <p className="text-muted-foreground max-w-sm text-sm">
+            请管理员前往「综合管理 → 私密广场配置」开启该功能并设置密码。
+          </p>
+        </div>
+      );
+    }
+
+    if (!privateFeatureUsable) {
+      return (
+        <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">
+            <ShieldIcon className="text-muted-foreground h-7 w-7" />
+          </div>
+          <p className="font-medium">私密广场未配置密码</p>
+          <p className="text-muted-foreground max-w-sm text-sm">
+            请管理员在私密广场配置页设置一个访问密码。
+          </p>
+        </div>
+      );
+    }
+
+    if (!privatePassword) {
+      return (
+        <div className="mx-auto flex w-full max-w-sm flex-col gap-4 pt-12 text-center">
+          <div className="bg-muted mx-auto flex h-14 w-14 items-center justify-center rounded-full">
+            <LockIcon className="text-muted-foreground h-7 w-7" />
+          </div>
+          <div>
+            <p className="font-medium">私密广场</p>
+            <p className="text-muted-foreground mt-1 text-sm">
+              请输入访问密码，验证通过后才能查看其中的智能体。
+            </p>
+          </div>
+          <div className="flex flex-col gap-2">
+            <Input
+              type="password"
+              placeholder="访问密码"
+              value={passwordInput}
+              onChange={(e) => setPasswordInput(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") handleSubmitPassword();
+              }}
+            />
+            <Button onClick={handleSubmitPassword}>进入私密广场</Button>
+          </div>
+        </div>
+      );
+    }
+
+    if (isPrivateLoading) {
+      return (
+        <div className="text-muted-foreground flex h-40 items-center justify-center text-sm">
+          {t.common.loading}
+        </div>
+      );
+    }
+
+    if (filteredPrivateAgents.length === 0) {
+      return renderEmpty("私密广场暂时还没有智能体。");
+    }
+
+    return renderGrid(filteredPrivateAgents);
+  };
+
   return (
     <div className="flex size-full flex-col">
       {/* Page header */}
@@ -84,14 +259,35 @@ export function AgentGallery() {
       {/* Tabs */}
       <Tabs
         value={activeTab}
-        onValueChange={(v) => setActiveTab(v as "all" | "mine")}
+        onValueChange={(v) =>
+          setActiveTab(v as "all" | "mine" | "private")
+        }
         className="flex flex-1 flex-col overflow-hidden"
       >
         <div className="mx-6 mt-4 flex flex-col gap-3">
-          <TabsList className="w-auto self-start">
-            <TabsTrigger value="mine">我的</TabsTrigger>
-            <TabsTrigger value="all">广场</TabsTrigger>
-          </TabsList>
+          <div className="flex items-center justify-between gap-3">
+            <TabsList className="w-auto self-start">
+              <TabsTrigger value="mine">我的</TabsTrigger>
+              <TabsTrigger value="all">广场</TabsTrigger>
+              {privateFeatureAvailable && (
+                <TabsTrigger value="private">
+                  <LockIcon className="mr-1 h-3.5 w-3.5" />
+                  私密广场
+                </TabsTrigger>
+              )}
+            </TabsList>
+            {activeTab === "private" && privatePassword && (
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={handleLockPrivate}
+                title="锁定私密广场，下次需要重新输入密码"
+              >
+                <LockIcon className="mr-1.5 h-3.5 w-3.5" />
+                锁定
+              </Button>
+            )}
+          </div>
           <TagSearchBar
             targetType="agent"
             onSearchChange={setSearch}
@@ -123,6 +319,15 @@ export function AgentGallery() {
             renderGrid(myAgents)
           )}
         </TabsContent>
+
+        {privateFeatureAvailable && (
+          <TabsContent
+            value="private"
+            className="flex-1 overflow-y-auto p-6 mt-0"
+          >
+            {renderPrivateTab()}
+          </TabsContent>
+        )}
       </Tabs>
     </div>
   );

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

@@ -61,7 +61,12 @@ export function AgentManageDialog({
 
   const candidates = useMemo(() => {
     const existing = new Set(agents.map((a) => a.id));
-    return allAgents.filter((a) => a.published && !existing.has(a.id));
+    // Private-square agents are hidden from the homepage selector even if
+    // they're published — the backend ``list_featured`` filter would drop
+    // them again on the way out, so offering them here is just confusing.
+    return allAgents.filter(
+      (a) => a.published && !a.is_private && !existing.has(a.id),
+    );
   }, [agents, allAgents]);
 
   const busy = setFeaturedMutation.isPending || reorderMutation.isPending;

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

@@ -50,6 +50,7 @@ import { installSkill } from "@/core/skills/api";
 import { streamdownPlugins } from "@/core/streamdown";
 import { checkCodeFile, getFileName } from "@/core/utils/files";
 import { env } from "@/env";
+import { desensitize } from "@/lib/desensitize";
 import { cn } from "@/lib/utils";
 
 import { ArtifactLink } from "../citations/artifact-link";
@@ -399,6 +400,47 @@ export function ArtifactFileDetail({
     }
   }, [displayContent, filepath]);
 
+  const handleOpenWriteFileInNewTab = useCallback(() => {
+    const source = displayContent ?? "";
+    if (!source.trim()) {
+      toast.error("文件内容为空，暂时无法打开");
+      return;
+    }
+    const blobType =
+      language === "html"
+        ? "text/html;charset=utf-8"
+        : language === "markdown"
+          ? "text/markdown;charset=utf-8"
+          : "text/plain;charset=utf-8";
+    const blob = new Blob([source], { type: blobType });
+    const url = URL.createObjectURL(blob);
+    window.open(url, "_blank", "noopener,noreferrer");
+    window.setTimeout(() => URL.revokeObjectURL(url), 60_000);
+  }, [displayContent, language]);
+
+  const handleDownloadWriteFile = useCallback(() => {
+    const source = displayContent ?? "";
+    if (!source.trim()) {
+      toast.error("文件内容为空，暂时无法下载");
+      return;
+    }
+    const blobType =
+      language === "html"
+        ? "text/html;charset=utf-8"
+        : language === "markdown"
+          ? "text/markdown;charset=utf-8"
+          : "text/plain;charset=utf-8";
+    const blob = new Blob([source], { type: blobType });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = getFileName(filepath);
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+  }, [displayContent, filepath, language]);
+
   return (
     <Artifact className={cn(className)}>
       <ArtifactHeader className="grid grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 px-4 py-3">
@@ -499,30 +541,32 @@ export function ArtifactFileDetail({
                 />
               </Tooltip>
             )}
-            {!isWriteFile && (
-              <ArtifactAction
-                icon={SquareArrowOutUpRightIcon}
-                label={t.common.openInNewWindow}
-                tooltip={t.common.openInNewWindow}
-                onClick={async () => {
-                  try {
-                    await openArtifactInNewTab({
-                      filepath,
-                      threadId,
-                      isMock,
-                      publicShareCode,
-                    });
-                  } catch (error) {
-                    console.error(error);
-                    toast.error(
-                      error instanceof Error
-                        ? error.message
-                        : "Failed to open artifact",
-                    );
-                  }
-                }}
-              />
-            )}
+            <ArtifactAction
+              icon={SquareArrowOutUpRightIcon}
+              label={t.common.openInNewWindow}
+              tooltip={t.common.openInNewWindow}
+              onClick={async () => {
+                if (isWriteFile) {
+                  handleOpenWriteFileInNewTab();
+                  return;
+                }
+                try {
+                  await openArtifactInNewTab({
+                    filepath,
+                    threadId,
+                    isMock,
+                    publicShareCode,
+                  });
+                } catch (error) {
+                  console.error(error);
+                  toast.error(
+                    error instanceof Error
+                      ? error.message
+                      : "Failed to open artifact",
+                  );
+                }
+              }}
+            />
             {isCodeFile && (
               <ArtifactAction
                 icon={CopyIcon}
@@ -549,30 +593,32 @@ export function ArtifactFileDetail({
                 onClick={handleDownloadAsWord}
               />
             )}
-            {!isWriteFile && (
-              <ArtifactAction
-                icon={DownloadIcon}
-                label={t.common.download}
-                tooltip={t.common.download}
-                onClick={async () => {
-                  try {
-                    await downloadArtifactFile({
-                      filepath,
-                      threadId,
-                      isMock,
-                      publicShareCode,
-                    });
-                  } catch (error) {
-                    console.error(error);
-                    toast.error(
-                      error instanceof Error
-                        ? error.message
-                        : "Download failed",
-                    );
-                  }
-                }}
-              />
-            )}
+            <ArtifactAction
+              icon={DownloadIcon}
+              label={t.common.download}
+              tooltip={t.common.download}
+              onClick={async () => {
+                if (isWriteFile) {
+                  handleDownloadWriteFile();
+                  return;
+                }
+                try {
+                  await downloadArtifactFile({
+                    filepath,
+                    threadId,
+                    isMock,
+                    publicShareCode,
+                  });
+                } catch (error) {
+                  console.error(error);
+                  toast.error(
+                    error instanceof Error
+                      ? error.message
+                      : "Download failed",
+                  );
+                }
+              }}
+            />
             <ArtifactAction
               className="hover:bg-background"
               icon={XIcon}
@@ -608,7 +654,7 @@ export function ArtifactFileDetail({
           viewMode === "preview" &&
           (language === "markdown" || language === "html") && (
               <ArtifactFilePreview
-                content={displayContent}
+                content={desensitize(displayContent ?? "")}
                 language={language ?? "text"}
                 animated={showPreviewSwitchPulse}
                 activeCursor={isApplyingEdit}
@@ -618,7 +664,11 @@ export function ArtifactFileDetail({
           <div className="size-full">
             <CodeEditor
               className="size-full resize-none rounded-none border-none bg-transparent"
-              value={displayContent ?? ""}
+              value={
+                canEditArtifact
+                  ? (displayContent ?? "")
+                  : desensitize(displayContent ?? "")
+              }
               readonly={!canEditArtifact}
               onChange={
                 canEditArtifact
@@ -665,7 +715,10 @@ export function ArtifactFilePreview({
       return;
     }
 
-    const blob = new Blob([content ?? ""], { type: "text/html" });
+    // 必须带 charset=utf-8：blob: URL 的 Content-Type 不含 charset 时，iframe 会按
+    // 系统默认编码(中文 Windows 常为 GBK/Latin-1)解码,模型生成的 HTML 若没写
+    // <meta charset> 就会中文乱码。与下方下载/新窗口打开的 blobType 保持一致。
+    const blob = new Blob([content ?? ""], { type: "text/html;charset=utf-8" });
     const url = URL.createObjectURL(blob);
     setHtmlPreviewUrl(url);
 

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

@@ -32,7 +32,10 @@ interface ArtifactsProviderProps {
 }
 
 export function ArtifactsProvider({ children }: ArtifactsProviderProps) {
-  const [artifacts, setArtifacts] = useState<string[]>([]);
+  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(

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

@@ -1,183 +1,806 @@
-import { FilesIcon, XIcon } from "lucide-react";
-import { usePathname } from "next/navigation";
-import { useEffect, useMemo, useRef, useState } from "react";
-import type { GroupImperativeHandle } from "react-resizable-panels";
-
-import { ConversationEmptyState } from "@/components/ai-elements/conversation";
-import { Button } from "@/components/ui/button";
-import {
-  ResizableHandle,
-  ResizablePanel,
-  ResizablePanelGroup,
-} from "@/components/ui/resizable";
-import { env } from "@/env";
-import { cn } from "@/lib/utils";
-
-import {
-  ArtifactFileDetail,
-  ArtifactFileList,
-  useArtifacts,
-} from "../artifacts";
-import { useThread } from "../messages/context";
-
-const CLOSE_MODE = { chat: 100, artifacts: 0 };
-const OPEN_MODE = { chat: 60, artifacts: 40 };
-
-const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
-  children,
-  threadId,
-}) => {
-  const { thread } = useThread();
-  const pathname = usePathname();
-  const threadIdRef = useRef(threadId);
-  const layoutRef = useRef<GroupImperativeHandle>(null);
-
-  const {
-    artifacts,
-    open: artifactsOpen,
-    setOpen: setArtifactsOpen,
-    setArtifacts,
-    select: selectArtifact,
-    deselect,
-    selectedArtifact,
-  } = useArtifacts();
-
-  const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true);
-  useEffect(() => {
-    if (threadIdRef.current !== threadId) {
-      threadIdRef.current = threadId;
-      deselect();
-    }
-
-    // Update artifacts from the current thread
-    setArtifacts(thread.values.artifacts);
-
-    // DO NOT automatically deselect the artifact when switching threads, because the artifacts auto discovering is not work now.
-    // if (
-    //   selectedArtifact &&
-    //   !thread.values.artifacts?.includes(selectedArtifact)
-    // ) {
-    //   deselect();
-    // }
-
-    if (
-      env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" &&
-      autoSelectFirstArtifact
-    ) {
-      if (thread?.values?.artifacts?.length > 0) {
-        setAutoSelectFirstArtifact(false);
-        selectArtifact(thread.values.artifacts[0]!);
-      }
-    }
-  }, [
-    threadId,
-    autoSelectFirstArtifact,
-    deselect,
-    selectArtifact,
-    selectedArtifact,
-    setArtifacts,
-    thread.values.artifacts,
-  ]);
-
-  const artifactPanelOpen = useMemo(() => {
-    if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true") {
-      return artifactsOpen && artifacts?.length > 0;
-    }
-    return artifactsOpen;
-  }, [artifactsOpen, artifacts]);
-
-  const resizableIdBase = useMemo(() => {
-    const raw = pathname
-      .replace(/[^a-zA-Z0-9_-]+/g, "-")
-      .replace(/^-+|-+$/g, "");
-    return raw.length > 0 ? raw : `thread-${threadId}`;
-  }, [pathname, threadId]);
-
-  useEffect(() => {
-    if (layoutRef.current) {
-      if (artifactPanelOpen) {
-        layoutRef.current.setLayout(OPEN_MODE);
-      } else {
-        layoutRef.current.setLayout(CLOSE_MODE);
-      }
-    }
-  }, [artifactPanelOpen]);
-
-  return (
-    <ResizablePanelGroup
-      id={`${resizableIdBase}-panels`}
-      orientation="horizontal"
-      defaultLayout={{ chat: 100, artifacts: 0 }}
-      groupRef={layoutRef}
-    >
-      <ResizablePanel className="relative" defaultSize={100} id="chat">
-        {children}
-      </ResizablePanel>
-      <ResizableHandle
-        id={`${resizableIdBase}-separator`}
-        className={cn(
-          "opacity-33 hover:opacity-100",
-          !artifactPanelOpen && "pointer-events-none opacity-0",
-        )}
-      />
-      <ResizablePanel
-        className={cn(
-          "bg-[#fffdfa] transition-all duration-300 ease-in-out",
-          !artifactsOpen && "opacity-0",
-        )}
-        id="artifacts"
-      >
-        <div
-          className={cn(
-            "h-full bg-[#fffdfa] p-4 transition-transform duration-300 ease-in-out",
-            artifactPanelOpen ? "translate-x-0" : "translate-x-full",
-          )}
-        >
-          {selectedArtifact ? (
-            <ArtifactFileDetail
-              className="size-full"
-              filepath={selectedArtifact}
-              threadId={threadId}
-            />
-          ) : (
-            <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>
-          )}
-        </div>
-      </ResizablePanel>
-    </ResizablePanelGroup>
-  );
-};
-
-export { ChatBox };
+import type { Message } from "@langchain/langgraph-sdk";
+import { FilesIcon, XIcon } from "lucide-react";
+import { usePathname } from "next/navigation";
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { GroupImperativeHandle } from "react-resizable-panels";
+
+import { ConversationEmptyState } from "@/components/ai-elements/conversation";
+import { Button } from "@/components/ui/button";
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from "@/components/ui/resizable";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { apiFetch } from "@/core/api";
+import { getBackendBaseURL } from "@/core/config";
+import { isThreadRagModeLocked, useLocalSettings } from "@/core/settings";
+import { useSkills } from "@/core/skills/hooks";
+import type { SkillDisplayConfig } from "@/core/skills/type";
+import {
+  displayConfigFromResultSet,
+  normalizeDisplaySources,
+} from "@/core/skill-display/display-adapter";
+import {
+  buildSkillDisplayMap,
+  collectRuntimeDisplaySources,
+} from "@/core/skill-display/runtime";
+import { env } from "@/env";
+import { cn } from "@/lib/utils";
+
+import {
+  ArtifactFileDetail,
+  ArtifactFileList,
+  useArtifacts,
+} from "../artifacts";
+import { useThread } from "../messages/context";
+import { SkillDisplaySources } from "../skill-display-sources";
+
+const CLOSE_MODE = { chat: 100, artifacts: 0 };
+const OPEN_MODE = { chat: 60, artifacts: 40 };
+const SHOW_REFERENCE_EVENT = "workspace:show-reference";
+
+type BackendReferenceSource = Parameters<typeof SkillDisplaySources>[0]["sources"][number];
+
+type BackendReferenceBatch = {
+  id: string;
+  assistant_message_id?: string;
+  sources: BackendReferenceSource[];
+};
+
+function logReferenceDebug(
+  event: string,
+  threadId: string,
+  payload: Record<string, unknown>,
+) {
+  console.info(`[RAG引用调试] ${event}`, payload);
+  void apiFetch(`${getBackendBaseURL()}/api/threads/reference-debug-log`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      event,
+      thread_id: threadId,
+      payload,
+    }),
+  }).catch(() => {
+    // Debug logging must never affect the chat flow.
+  });
+}
+
+const ChatBox: React.FC<{
+  children: React.ReactNode;
+  threadId: string;
+  disableArtifacts?: boolean;
+}> = ({
+  children,
+  threadId,
+  disableArtifacts = false,
+}) => {
+  const { thread } = useThread();
+  const pathname = usePathname();
+  const threadIdRef = useRef(threadId);
+  const artifactsCountRef = useRef(0);
+  const layoutRef = useRef<GroupImperativeHandle>(null);
+  const latestReferenceBatchIdRef = useRef<string | null>(null);
+  const manualReferenceBatchRef = useRef(false);
+  const referenceDebugSignatureRef = useRef<string>("");
+  const [sideTab, setSideTab] = useState("document");
+  const [referencesOpen, setReferencesOpen] = useState(true);
+  const [activeReferenceBatchId, setActiveReferenceBatchId] = useState<string | null>(null);
+  const [pinnedReferenceId, setPinnedReferenceId] = useState<string | null>(null);
+  const [backendReferenceBatches, setBackendReferenceBatches] = useState<BackendReferenceBatch[]>([]);
+  const [settings] = useLocalSettings();
+  const ragModeEnabled =
+    settings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
+  const { skills } = useSkills();
+
+  const {
+    artifacts,
+    open: artifactsOpen,
+    setOpen: setArtifactsOpen,
+    setArtifacts,
+    select: selectArtifact,
+    deselect,
+    selectedArtifact,
+  } = useArtifacts();
+
+  const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true);
+  const skillDisplayMap = useMemo(
+    () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [ragModeEnabled, skills],
+  );
+  const fallbackReferenceBatches = useMemo(() => {
+    if (!ragModeEnabled) {
+      return [];
+    }
+    return buildTurnReferenceBatches(
+      thread.values.messages ?? [],
+      skillDisplayMap,
+      thread.isLoading,
+    );
+  }, [ragModeEnabled, skillDisplayMap, thread.isLoading, thread.values.messages]);
+  useEffect(() => {
+    if (!ragModeEnabled) {
+      setBackendReferenceBatches([]);
+      return;
+    }
+    if (thread.isLoading) {
+      return;
+    }
+    const controller = new AbortController();
+    logReferenceDebug("开始拉取后端参考文献", threadId, {
+      messageCount: thread.values.messages?.length ?? 0,
+    });
+    apiFetch(
+      `${getBackendBaseURL()}/api/threads/${encodeURIComponent(threadId)}/reference-batches`,
+      { signal: controller.signal },
+    )
+      .then(async (response) => {
+        if (!response.ok) {
+          throw new Error(`Failed to load reference batches: ${response.status}`);
+        }
+        return (await response.json()) as { batches?: BackendReferenceBatch[] };
+      })
+      .then((data) => {
+        const batches = data.batches ?? [];
+        logReferenceDebug("后端参考文献返回", threadId, {
+          batchCount: batches.length,
+          sourceCounts: batches.map((batch) => batch.sources?.length ?? 0),
+          batchIds: batches.map((batch) => batch.id),
+        });
+        setBackendReferenceBatches(batches);
+      })
+      .catch((error) => {
+        if (!controller.signal.aborted) {
+          console.warn("Failed to load backend reference batches", error);
+        }
+      });
+    return () => controller.abort();
+  }, [ragModeEnabled, thread.isLoading, threadId, thread.values.messages]);
+  const adaptedBackendReferenceBatches = useMemo(
+    () =>
+      adaptBackendReferenceBatches(
+        backendReferenceBatches,
+        skillDisplayMap,
+      ),
+    [backendReferenceBatches, skillDisplayMap],
+  );
+  const referenceBatches = useMemo(
+    () => {
+      if (adaptedBackendReferenceBatches.length > 0) {
+        return adaptedBackendReferenceBatches;
+      }
+      return fallbackReferenceBatches;
+    },
+    [adaptedBackendReferenceBatches, fallbackReferenceBatches],
+  );
+  useEffect(() => {
+    if (!ragModeEnabled) {
+      return;
+    }
+    const signature = JSON.stringify({
+      backend: backendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      adaptedBackend: adaptedBackendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      fallback: fallbackReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      final: referenceBatches.map((batch) => batch.sources?.length ?? 0),
+    });
+    if (referenceDebugSignatureRef.current === signature) {
+      return;
+    }
+    referenceDebugSignatureRef.current = signature;
+    logReferenceDebug("前端参考文献来源选择", threadId, {
+      using: backendReferenceBatches.length > 0 ? "后端接口" : "前端兜底",
+      backendBatchCount: backendReferenceBatches.length,
+      backendSourceCounts: backendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      adaptedBackendSourceCounts: adaptedBackendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      fallbackBatchCount: fallbackReferenceBatches.length,
+      fallbackSourceCounts: fallbackReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      finalBatchCount: referenceBatches.length,
+      finalSourceCounts: referenceBatches.map((batch) => batch.sources?.length ?? 0),
+      backendBatches: debugReferenceBatches(backendReferenceBatches),
+      adaptedBackendBatches: debugReferenceBatches(adaptedBackendReferenceBatches),
+      fallbackBatches: debugReferenceBatches(fallbackReferenceBatches),
+      finalBatches: debugReferenceBatches(referenceBatches),
+    });
+  }, [adaptedBackendReferenceBatches, backendReferenceBatches, fallbackReferenceBatches, ragModeEnabled, referenceBatches, threadId]);
+  const latestReferenceBatch =
+    referenceBatches.length > 0
+      ? referenceBatches[referenceBatches.length - 1]!
+      : null;
+  const activeReferenceBatch =
+    referenceBatches.find((batch) => batch.id === activeReferenceBatchId) ??
+    latestReferenceBatch;
+  const referenceSources = activeReferenceBatch?.sources ?? [];
+  const hasCitationReferences = referenceSources.length > 0;
+  useEffect(() => {
+    if (!ragModeEnabled || !activeReferenceBatch) {
+      return;
+    }
+    logReferenceDebug("frontend-active-reference-batch-payload", threadId, {
+      activeBatchId: activeReferenceBatch.id,
+      assistantMessageId: activeReferenceBatch.assistant_message_id,
+      sourceCount: activeReferenceBatch.sources.length,
+      sources: activeReferenceBatch.sources.map(debugReferenceSource),
+    });
+  }, [activeReferenceBatch, ragModeEnabled, threadId]);
+  useEffect(() => {
+    if (hasCitationReferences) {
+      setReferencesOpen(true);
+    }
+  }, [hasCitationReferences]);
+  useEffect(() => {
+    if (!latestReferenceBatch) {
+      setActiveReferenceBatchId(null);
+      latestReferenceBatchIdRef.current = null;
+      manualReferenceBatchRef.current = false;
+      return;
+    }
+    const previousLatestId = latestReferenceBatchIdRef.current;
+    latestReferenceBatchIdRef.current = latestReferenceBatch.id;
+    setActiveReferenceBatchId((current) =>
+      current &&
+      referenceBatches.some((batch) => batch.id === current) &&
+      manualReferenceBatchRef.current &&
+      current !== previousLatestId
+        ? current
+        : latestReferenceBatch.id,
+    );
+  }, [latestReferenceBatch?.id, referenceBatches]);
+  useEffect(() => {
+    const handleShowReference = (event: Event) => {
+      const detail = (event as CustomEvent<{ batchId?: string; referenceId?: string }>).detail;
+      if (detail?.batchId) {
+        manualReferenceBatchRef.current = true;
+        setActiveReferenceBatchId(detail.batchId);
+      }
+      setPinnedReferenceId(null);
+      window.setTimeout(() => {
+        setPinnedReferenceId(detail?.referenceId ?? null);
+      }, 0);
+      setReferencesOpen(true);
+      setSideTab("references");
+    };
+    window.addEventListener(SHOW_REFERENCE_EVENT, handleShowReference);
+    return () => {
+      window.removeEventListener(SHOW_REFERENCE_EVENT, handleShowReference);
+    };
+  }, []);
+  useEffect(() => {
+    if (threadIdRef.current !== threadId) {
+      threadIdRef.current = threadId;
+      artifactsCountRef.current = 0;
+      deselect();
+      setReferencesOpen(false);
+      setActiveReferenceBatchId(null);
+      setPinnedReferenceId(null);
+      setBackendReferenceBatches([]);
+      latestReferenceBatchIdRef.current = null;
+      manualReferenceBatchRef.current = false;
+      referenceDebugSignatureRef.current = "";
+    }
+
+    // Update artifacts from the current thread
+    const nextArtifacts = disableArtifacts ? [] : (thread.values.artifacts ?? []);
+    const hadArtifacts = artifactsCountRef.current > 0;
+    const hasNewArtifact = nextArtifacts.length > artifactsCountRef.current;
+    artifactsCountRef.current = nextArtifacts.length;
+    setArtifacts(nextArtifacts);
+    if (
+      !disableArtifacts &&
+      (hasNewArtifact || (!hadArtifacts && nextArtifacts.length > 0)) &&
+      !selectedArtifact
+    ) {
+      selectArtifact(nextArtifacts[nextArtifacts.length - 1]!);
+      setArtifactsOpen(true);
+      setSideTab("document");
+    }
+
+    // DO NOT automatically deselect the artifact when switching threads, because the artifacts auto discovering is not work now.
+    // if (
+    //   selectedArtifact &&
+    //   !thread.values.artifacts?.includes(selectedArtifact)
+    // ) {
+    //   deselect();
+    // }
+
+    if (
+      !disableArtifacts &&
+      env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" &&
+      autoSelectFirstArtifact
+    ) {
+      if (thread?.values?.artifacts?.length > 0) {
+        setAutoSelectFirstArtifact(false);
+        selectArtifact(thread.values.artifacts[0]!);
+      }
+    }
+  }, [
+    threadId,
+    autoSelectFirstArtifact,
+    deselect,
+    selectArtifact,
+    selectedArtifact,
+    setArtifacts,
+    thread.values.artifacts,
+    disableArtifacts,
+  ]);
+
+  const artifactPanelOpen = useMemo(() => {
+    if (disableArtifacts) {
+      return false;
+    }
+    if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true") {
+      return artifactsOpen && artifacts?.length > 0;
+    }
+    return artifactsOpen;
+  }, [artifactsOpen, artifacts, disableArtifacts]);
+  const sidePanelOpen = artifactPanelOpen || (hasCitationReferences && referencesOpen);
+  const showTabs = !!selectedArtifact && hasCitationReferences;
+
+  useEffect(() => {
+    if (selectedArtifact) {
+      setSideTab("document");
+    } else if (hasCitationReferences) {
+      setSideTab("references");
+    }
+  }, [hasCitationReferences, selectedArtifact]);
+
+  const resizableIdBase = useMemo(() => {
+    const raw = pathname
+      .replace(/[^a-zA-Z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "");
+    return raw.length > 0 ? raw : `thread-${threadId}`;
+  }, [pathname, threadId]);
+
+  useEffect(() => {
+    if (layoutRef.current) {
+      if (sidePanelOpen) {
+        layoutRef.current.setLayout(OPEN_MODE);
+      } else {
+        layoutRef.current.setLayout(CLOSE_MODE);
+      }
+    }
+  }, [sidePanelOpen]);
+
+  if (disableArtifacts) {
+    return <>{children}</>;
+  }
+
+  return (
+    <ResizablePanelGroup
+      id={`${resizableIdBase}-panels`}
+      orientation="horizontal"
+      defaultLayout={{ chat: 100, artifacts: 0 }}
+      groupRef={layoutRef}
+    >
+      <ResizablePanel className="relative" defaultSize={100} id="chat">
+        {children}
+      </ResizablePanel>
+      <ResizableHandle
+        id={`${resizableIdBase}-separator`}
+        className={cn(
+          "opacity-33 hover:opacity-100",
+          !sidePanelOpen && "pointer-events-none opacity-0",
+        )}
+      />
+      <ResizablePanel
+        className={cn(
+          "bg-background transition-all duration-300 ease-in-out",
+          !sidePanelOpen && "opacity-0",
+        )}
+        id="artifacts"
+      >
+        <div
+          className={cn(
+            "h-full bg-background p-4 transition-transform duration-300 ease-in-out",
+            sidePanelOpen ? "translate-x-0" : "translate-x-full",
+          )}
+        >
+          {showTabs ? (
+            <Tabs value={sideTab} onValueChange={setSideTab} className="flex size-full flex-col overflow-hidden">
+              <div className="mb-3 flex shrink-0 items-center justify-between gap-2">
+                <TabsList variant="line">
+                  <TabsTrigger value="document">文档</TabsTrigger>
+                  <TabsTrigger value="references">参考文献</TabsTrigger>
+                </TabsList>
+                <Button
+                  size="icon-sm"
+                  variant="ghost"
+                  onClick={() => {
+                    setReferencesOpen(false);
+                    setArtifactsOpen(false);
+                  }}
+                >
+                  <XIcon />
+                </Button>
+              </div>
+              <TabsContent value="document" className="min-h-0 flex-1 overflow-hidden p-0">
+                <ArtifactFileDetail
+                  className="size-full"
+                  filepath={selectedArtifact}
+                  threadId={threadId}
+                />
+              </TabsContent>
+              <TabsContent value="references" className="min-h-0 flex-1 overflow-y-auto p-0">
+                <ReferencePanel
+                  highlightedReferenceId={pinnedReferenceId}
+                  sources={referenceSources}
+                />
+              </TabsContent>
+            </Tabs>
+          ) : selectedArtifact ? (
+            <ArtifactFileDetail
+              className="size-full"
+              filepath={selectedArtifact}
+              threadId={threadId}
+            />
+          ) : hasCitationReferences ? (
+            <div className="relative size-full overflow-hidden">
+              <div className="absolute top-1 right-1 z-30">
+                <Button
+                  size="icon-sm"
+                  variant="ghost"
+                  onClick={() => {
+                    setReferencesOpen(false);
+                    setArtifactsOpen(false);
+                  }}
+                >
+                  <XIcon />
+                </Button>
+              </div>
+              <ReferencePanel
+                highlightedReferenceId={pinnedReferenceId}
+                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>
+          )}
+        </div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  );
+};
+
+function ReferencePanel({
+  highlightedReferenceId,
+  sources,
+}: {
+  highlightedReferenceId?: string | null;
+  sources: Parameters<typeof SkillDisplaySources>[0]["sources"];
+}) {
+  const orderedSources = useMemo(() => {
+    if (!highlightedReferenceId) {
+      return sources;
+    }
+    const index = Number(highlightedReferenceId);
+    if (!Number.isFinite(index)) {
+      return sources;
+    }
+    const selected = sources.find((source) => source.index === index);
+    if (!selected) {
+      return sources;
+    }
+    return [selected, ...sources.filter((source) => source.index !== index)];
+  }, [highlightedReferenceId, sources]);
+
+  return (
+    <div className="flex size-full flex-col overflow-hidden">
+      <header className="shrink-0 px-1 pb-3">
+        <div className="flex items-baseline gap-2">
+          <h2 className="text-foreground text-base font-semibold tracking-tight">
+            参考文献
+          </h2>
+          <span className="text-muted-foreground text-xs tabular-nums">
+            {sources.length} 条
+          </span>
+        </div>
+        <p className="text-muted-foreground mt-1 text-xs leading-relaxed">
+          点击编号或卡片可查看引用详情。
+        </p>
+      </header>
+      <main className="min-h-0 flex-1 overflow-y-auto px-1 pt-1 pb-6">
+        <SkillDisplaySources
+          highlightedReferenceId={highlightedReferenceId}
+          sources={orderedSources}
+        />
+      </main>
+    </div>
+  );
+}
+
+function debugReferenceBatches(batches: BackendReferenceBatch[]) {
+  return batches.map((batch) => ({
+    id: batch.id,
+    assistantMessageId: batch.assistant_message_id,
+    sourceCount: batch.sources?.length ?? 0,
+    sources: (batch.sources ?? []).map(debugReferenceSource),
+  }));
+}
+
+function debugReferenceSource(source: BackendReferenceSource) {
+  const raw =
+    source.raw && typeof source.raw === "object" && !Array.isArray(source.raw)
+      ? (source.raw as Record<string, unknown>)
+      : {};
+  return {
+    index: source.index,
+    id: source.id,
+    skillName: source.skillName,
+    mode: source.mode,
+    title: source.title,
+    source: source.source,
+    author: source.author,
+    time: source.time,
+    url: source.url,
+    snippet: source.snippet,
+    content: source.content,
+    rawIdCandidates: {
+      recUuid: raw.recUuid,
+      rec_uuid: raw.rec_uuid,
+      uuid: raw.uuid,
+      docId: raw.docId,
+      doc_id: raw.doc_id,
+      id: raw.id,
+      url: raw.url,
+    },
+    raw: source.raw,
+  };
+}
+
+function adaptBackendReferenceBatches(
+  backendBatches: BackendReferenceBatch[],
+  skillDisplayMap: ReturnType<typeof buildSkillDisplayMap>,
+): BackendReferenceBatch[] {
+  if (backendBatches.length === 0) {
+    return backendBatches;
+  }
+  return backendBatches.map((backendBatch) => {
+    return {
+      ...backendBatch,
+      sources: backendBatch.sources.map((backendSource) => {
+        const configuredSource = adaptBackendSourceWithSkillDisplay(
+          backendSource,
+          skillDisplayMap,
+        );
+        if (!configuredSource) {
+          return backendSource;
+        }
+        return {
+          ...backendSource,
+          ...configuredSource,
+          index: backendSource.index,
+          mode:
+            backendSource.mode !== "citation"
+              ? backendSource.mode
+              : configuredSource.mode || backendSource.mode,
+          raw: backendSource.raw ?? configuredSource.raw,
+        };
+      }),
+    };
+  });
+}
+
+function adaptBackendSourceWithSkillDisplay(
+  source: BackendReferenceSource,
+  skillDisplayMap: ReturnType<typeof buildSkillDisplayMap>,
+): BackendReferenceSource | null {
+  const raw = source.raw;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return null;
+  }
+  const rawItem = raw as Record<string, unknown>;
+  const match = findBackendSourceDisplay(source, skillDisplayMap);
+  if (!match) {
+    return null;
+  }
+  const display = findDisplayConfigForBackendSource(source, match.display);
+  const normalized = normalizeDisplaySources(
+    buildPayloadAtPath(display.resultPath || "results", [rawItem]),
+    display,
+  )[0];
+  if (!normalized) {
+    return null;
+  }
+  return {
+    ...source,
+    ...normalized,
+    skillName: match.skillName,
+    mode: display.mode,
+    tableColumns: display.tableColumns,
+    index: source.index,
+    raw: source.raw,
+  };
+}
+
+function findDisplayConfigForBackendSource(
+  source: BackendReferenceSource,
+  display: SkillDisplayConfig,
+) {
+  const resultSetKey = source.resultSetKey;
+  if (resultSetKey) {
+    const resultSet = display.resultSets?.find((item) => item.key === resultSetKey);
+    if (resultSet) {
+      return displayConfigFromResultSet(display, resultSet);
+    }
+  }
+  return { ...display, resultSets: [] };
+}
+
+function findBackendSourceDisplay(
+  source: BackendReferenceSource,
+  skillDisplayMap: ReturnType<typeof buildSkillDisplayMap>,
+) {
+  const direct = skillDisplayMap.get(source.skillName);
+  if (direct) {
+    return { skillName: source.skillName, display: direct };
+  }
+  const normalizedSource = normalizeSkillName(source.skillName);
+  for (const [skillName, display] of skillDisplayMap) {
+    const normalizedSkill = normalizeSkillName(skillName);
+    if (
+      normalizedSource === normalizedSkill ||
+      normalizedSource.endsWith(normalizedSkill) ||
+      normalizedSource.includes(normalizedSkill)
+    ) {
+      return { skillName, display };
+    }
+  }
+  return null;
+}
+
+function normalizeSkillName(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function buildPayloadAtPath(path: string, items: Record<string, unknown>[]) {
+  const parts = path.split(".").map((part) => part.trim()).filter(Boolean);
+  if (parts.length === 0) {
+    return items;
+  }
+  const root: Record<string, unknown> = {};
+  let cursor = root;
+  for (let index = 0; index < parts.length; index++) {
+    const part = parts[index]!;
+    if (index === parts.length - 1) {
+      cursor[part] = items;
+    } else {
+      const next: Record<string, unknown> = {};
+      cursor[part] = next;
+      cursor = next;
+    }
+  }
+  return root;
+}
+
+function findPreviousHumanMessageId(
+  messages: Message[],
+  beforeMessageId?: string,
+): string | undefined {
+  const beforeIndex =
+    beforeMessageId === undefined
+      ? messages.length
+      : messages.findIndex((message) => message.id === beforeMessageId);
+  const end = beforeIndex < 0 ? messages.length : beforeIndex;
+  for (let index = end - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message?.type === "human") {
+      return message.id;
+    }
+  }
+  return undefined;
+}
+
+function buildTurnReferenceBatches(
+  messages: Message[],
+  skillDisplayMap: ReturnType<typeof buildSkillDisplayMap>,
+  isLoading: boolean,
+): BackendReferenceBatch[] {
+  const batches: BackendReferenceBatch[] = [];
+  for (let index = 0; index < messages.length; index++) {
+    const human = messages[index];
+    if (human?.type !== "human" || !human.id) {
+      continue;
+    }
+    const nextHumanIndex = findNextHumanIndex(messages, index + 1);
+    if (nextHumanIndex === -1 && isLoading) {
+      continue;
+    }
+    const endIndex = nextHumanIndex === -1 ? messages.length : nextHumanIndex;
+    const assistant = findLastAssistantAnswer(messages, index + 1, endIndex);
+    if (!assistant?.id) {
+      continue;
+    }
+    const sources = collectRuntimeDisplaySources(messages, skillDisplayMap, {
+      afterMessageId: human.id,
+      beforeMessageId:
+        nextHumanIndex === -1 ? undefined : messages[nextHumanIndex]?.id,
+      includeBeforeMessage: false,
+    }).filter((source) => source.mode !== "none");
+    if (sources.length > 0) {
+      batches.push({
+        id: assistant.id,
+        assistant_message_id: assistant.id,
+        sources,
+      });
+    }
+  }
+  return batches;
+}
+
+function findNextHumanIndex(messages: Message[], start: number): number {
+  for (let index = start; index < messages.length; index++) {
+    if (messages[index]?.type === "human") {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function findLastAssistantAnswer(
+  messages: Message[],
+  start: number,
+  end: number,
+): Message | null {
+  for (let index = end - 1; index >= start; index--) {
+    const message = messages[index];
+    if (
+      message?.type === "ai" &&
+      message.id &&
+      hasAssistantAnswerContent(message)
+    ) {
+      return message;
+    }
+  }
+  return null;
+}
+
+function hasAssistantAnswerContent(message: Message): boolean {
+  const content = message.content;
+  if (typeof content === "string") {
+    return content.trim().length > 0;
+  }
+  if (!Array.isArray(content)) {
+    return false;
+  }
+  return content.some((part) => {
+    if (!part || typeof part !== "object") {
+      return false;
+    }
+    const block = part as Record<string, unknown>;
+    return block.type === "text" && typeof block.text === "string" && block.text.trim().length > 0;
+  });
+}
+
+export { ChatBox };

frontend-web/src/components/workspace/chats/use-thread-chat.ts

@@ -2,12 +2,19 @@
 
 import { useParams, usePathname, useSearchParams } from "next/navigation";
 import { useEffect, useState } from "react";
+import { useLocation } from "react-router-dom";
 
 import { uuid } from "@/core/utils/uuid";
 
 export function useThreadChat() {
   const { thread_id: threadIdFromPath } = useParams<{ thread_id: string }>();
   const pathname = usePathname();
+  // ``location.key`` is regenerated on every react-router navigation, even when
+  // the resolved pathname is identical. We depend on it so that clicking
+  // "新对话" while already at /chats/new still triggers a fresh thread reset
+  // (otherwise navigate-to-same-path is silently a no-op and the in-flight
+  // conversation would persist on screen).
+  const locationKey = useLocation().key;
 
   const searchParams = useSearchParams();
   const [threadId, setThreadId] = useState(() => {
@@ -37,7 +44,7 @@ export function useThreadChat() {
     }
     setIsNewThread(false);
     setThreadId(threadIdFromPath);
-  }, [pathname, threadIdFromPath]);
+  }, [pathname, threadIdFromPath, locationKey]);
   const isMock = searchParams.get("mock") === "true";
   return { threadId, setThreadId, isNewThread, setIsNewThread, isMock };
 }

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

@@ -1,82 +1,77 @@
-import { ExternalLinkIcon } from "lucide-react";
-import type { ComponentProps } from "react";
-
-import { Badge } from "@/components/ui/badge";
-import {
-  HoverCard,
-  HoverCardContent,
-  HoverCardTrigger,
-} from "@/components/ui/hover-card";
-import { cn } from "@/lib/utils";
-
-export function CitationLink({
-  href,
-  children,
-  ...props
-}: ComponentProps<"a">) {
-  const domain = extractDomain(href ?? "");
-
-  // Priority: children > domain
-  const childrenText =
-    typeof children === "string"
-      ? children.replace(/^citation:\s*/i, "")
-      : null;
-  const isGenericText = childrenText === "Source" || childrenText === "来源";
-  const displayText = (!isGenericText && childrenText) ?? domain;
-
-  return (
-    <HoverCard closeDelay={0} openDelay={0}>
-      <HoverCardTrigger asChild>
-        <a
-          href={href}
-          target="_blank"
-          rel="noopener noreferrer"
-          className="inline-flex items-center"
-          onClick={(e) => e.stopPropagation()}
-          {...props}
-        >
-          <Badge
-            variant="secondary"
-            className="hover:bg-secondary/80 mx-0.5 cursor-pointer gap-1 rounded-full px-2 py-0.5 text-xs font-normal"
-          >
-            {displayText}
-            <ExternalLinkIcon className="size-3" />
-          </Badge>
-        </a>
-      </HoverCardTrigger>
-      <HoverCardContent className={cn("relative w-80 p-0", props.className)}>
-        <div className="p-3">
-          <div className="space-y-1">
-            {displayText && (
-              <h4 className="truncate text-sm leading-tight font-medium">
-                {displayText}
-              </h4>
-            )}
-            {href && (
-              <p className="text-muted-foreground truncate text-xs break-all">
-                {href}
-              </p>
-            )}
-          </div>
-          <a
-            href={href}
-            target="_blank"
-            rel="noopener noreferrer"
-            className="text-primary mt-2 inline-flex items-center gap-1 text-xs hover:underline"
-          >
-            Visit source
-            <ExternalLinkIcon className="size-3" />
-          </a>
-        </div>
-      </HoverCardContent>
-    </HoverCard>
-  );
-}
-
-function extractDomain(url: string): string {
-  try {
-    return new URL(url).hostname.replace(/^www\./i, "");
-  } catch {
-    return url;
-  }
-}
+import type { ComponentProps } from "react";
+
+import { cn } from "@/lib/utils";
+
+const SHOW_REFERENCE_EVENT = "workspace:show-reference";
+
+export function CitationLink({
+  href,
+  children,
+  className,
+  ...props
+}: ComponentProps<"a">) {
+  const childrenText = normalizeCitationText(children);
+  const displayText = childrenText ?? "";
+  const referenceId = href?.startsWith("#reference-")
+    ? href.slice("#reference-".length)
+    : null;
+
+  if (referenceId) {
+    const badgeLabel = displayText.replace(/^\[|\]$/g, "") || referenceId;
+    return (
+      <a
+        href={href}
+        title={`查看参考文献 ${badgeLabel}`}
+        className={cn(
+          "border-primary/30 bg-primary/10 text-primary hover:border-primary/60 hover:bg-primary/20 focus-visible:ring-primary/30 mx-0.5 inline-flex h-[18px] min-w-[18px] -translate-y-[1px] items-center justify-center rounded-full border px-1 text-[10.5px] font-semibold tabular-nums no-underline transition-colors focus-visible:ring-2 focus-visible:outline-none",
+          className,
+        )}
+        onClick={(event) => {
+          event.preventDefault();
+          const batchId =
+            event.currentTarget.closest<HTMLElement>("[data-reference-batch-id]")
+              ?.dataset.referenceBatchId;
+          window.dispatchEvent(
+            new CustomEvent(SHOW_REFERENCE_EVENT, {
+              detail: { batchId, referenceId },
+            }),
+          );
+          const scroll = () => {
+            const target = document.getElementById(`reference-${referenceId}`);
+            target?.scrollIntoView({ behavior: "smooth", block: "center" });
+          };
+          window.setTimeout(scroll, 240);
+        }}
+        {...props}
+      >
+        {badgeLabel}
+      </a>
+    );
+  }
+
+  return (
+    <a
+      href={href}
+      target={href?.startsWith("http") ? "_blank" : undefined}
+      rel={href?.startsWith("http") ? "noopener noreferrer" : undefined}
+      className={cn(
+        "text-primary decoration-primary/30 hover:decoration-primary/60 underline underline-offset-2 transition-colors",
+        className,
+      )}
+      {...props}
+    >
+      {displayText || children}
+    </a>
+  );
+}
+
+function normalizeCitationText(children: ComponentProps<"a">["children"]) {
+  if (typeof children !== "string") {
+    return null;
+  }
+  let text = children.trim();
+  while (/^citation:\s*/i.test(text)) {
+    text = text.replace(/^citation:\s*/i, "");
+  }
+  return text;
+}

frontend-web/src/components/workspace/custom-prompt-menu.tsx

@@ -0,0 +1,294 @@
+"use client";
+
+import {
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  PencilIcon,
+  Settings2Icon,
+  Trash2Icon,
+} from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  useCreateCustomPrompt,
+  useCustomPrompts,
+  useDeleteCustomPrompt,
+  useUpdateCustomPrompt,
+} from "@/core/custom-prompts";
+import { cn } from "@/lib/utils";
+
+/**
+ * Bar above the chat input showing the user's saved prompts as centered,
+ * clickable chips. When there are too many to fit, they become a horizontal
+ * carousel (arrows appear). A gear pinned to the far right opens the manage
+ * dialog. Prompts are bound to the account (server-backed), and this coexists
+ * with the admin-configured global prompt prefix.
+ */
+export function CustomPromptBar({
+  onInsert,
+  className,
+}: {
+  onInsert: (content: string) => void;
+  className?: string;
+}) {
+  const prompts = useCustomPrompts();
+  const [manageOpen, setManageOpen] = useState(false);
+
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [canLeft, setCanLeft] = useState(false);
+  const [canRight, setCanRight] = useState(false);
+
+  const updateArrows = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    setCanLeft(el.scrollLeft > 4);
+    setCanRight(el.scrollLeft + el.clientWidth < el.scrollWidth - 4);
+  }, []);
+
+  useEffect(() => {
+    updateArrows();
+    window.addEventListener("resize", updateArrows);
+    return () => window.removeEventListener("resize", updateArrows);
+  }, [updateArrows, prompts]);
+
+  const scrollByDir = (dir: 1 | -1) => {
+    scrollRef.current?.scrollBy({ left: dir * 220, behavior: "smooth" });
+  };
+
+  const overflowing = canLeft || canRight;
+
+  return (
+    <>
+      <div className={cn("flex items-center gap-1", className)}>
+        {prompts.length > 0 && (
+          <>
+            {overflowing && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                className="text-muted-foreground hover:text-foreground h-7 w-7 shrink-0 rounded-full"
+                disabled={!canLeft}
+                onClick={() => scrollByDir(-1)}
+                aria-label="上一组"
+              >
+                <ChevronLeftIcon className="size-4" />
+              </Button>
+            )}
+            <div
+              ref={scrollRef}
+              onScroll={updateArrows}
+              className="flex-1 overflow-x-auto [-ms-overflow-style:none] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+            >
+              <div className="mx-auto flex w-max items-center gap-1.5 px-0.5 py-0.5">
+                {prompts.map((prompt) => (
+                  <button
+                    key={prompt.id}
+                    type="button"
+                    onClick={() => onInsert(prompt.content)}
+                    title={prompt.content}
+                    className={cn(
+                      "border-border/60 bg-muted/40 text-foreground/80 hover:bg-muted hover:text-foreground hover:border-border max-w-[200px] shrink-0 truncate rounded-full border px-3 py-1 text-xs font-medium shadow-sm transition-colors",
+                      "dark:border-slate-600/70 dark:bg-slate-700/40 dark:text-slate-200 dark:hover:bg-slate-700",
+                    )}
+                  >
+                    {prompt.title || prompt.content || "未命名提示词"}
+                  </button>
+                ))}
+              </div>
+            </div>
+            {overflowing && (
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                className="text-muted-foreground hover:text-foreground h-7 w-7 shrink-0 rounded-full"
+                disabled={!canRight}
+                onClick={() => scrollByDir(1)}
+                aria-label="下一组"
+              >
+                <ChevronRightIcon className="size-4" />
+              </Button>
+            )}
+          </>
+        )}
+        {prompts.length === 0 && <div className="flex-1" />}
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          className="text-muted-foreground hover:text-foreground hover:bg-muted/70 h-7 w-7 shrink-0 rounded-full"
+          title="管理常用提示词"
+          aria-label="管理常用提示词"
+          onClick={() => setManageOpen(true)}
+        >
+          <Settings2Icon className="size-4" />
+        </Button>
+      </div>
+
+      <ManagePromptsDialog open={manageOpen} onOpenChange={setManageOpen} />
+    </>
+  );
+}
+
+function ManagePromptsDialog({
+  open,
+  onOpenChange,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const prompts = useCustomPrompts();
+  const createPrompt = useCreateCustomPrompt();
+  const updatePrompt = useUpdateCustomPrompt();
+  const deletePrompt = useDeleteCustomPrompt();
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [title, setTitle] = useState("");
+  const [content, setContent] = useState("");
+
+  const saving = createPrompt.isPending || updatePrompt.isPending;
+
+  const resetForm = () => {
+    setEditingId(null);
+    setTitle("");
+    setContent("");
+  };
+
+  const handleSubmit = async () => {
+    const trimmedTitle = title.trim();
+    if (!content.trim()) {
+      toast.error("提示词内容不能为空");
+      return;
+    }
+    try {
+      if (editingId) {
+        await updatePrompt.mutateAsync({
+          id: editingId,
+          input: { title: trimmedTitle, content },
+        });
+        toast.success("提示词已更新");
+      } else {
+        await createPrompt.mutateAsync({ title: trimmedTitle, content });
+        toast.success("提示词已添加");
+      }
+      resetForm();
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  };
+
+  const handleEdit = (id: string) => {
+    const target = prompts.find((p) => p.id === id);
+    if (!target) return;
+    setEditingId(id);
+    setTitle(target.title);
+    setContent(target.content);
+  };
+
+  const handleDelete = async (id: string) => {
+    try {
+      await deletePrompt.mutateAsync(id);
+      if (editingId === id) resetForm();
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) resetForm();
+        onOpenChange(next);
+      }}
+    >
+      <DialogContent className="max-h-[85vh] overflow-y-auto sm:max-w-xl">
+        <DialogHeader>
+          <DialogTitle>管理常用提示词</DialogTitle>
+          <DialogDescription>
+            保存常用的提示词，保存后会以小标签形式显示在输入框上方，点击即可填入。提示词与你的账号绑定，可跨设备使用。
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-3 rounded-md border p-3">
+          <Input
+            value={title}
+            onChange={(e) => setTitle(e.target.value)}
+            placeholder="名称（可选，例如：周报总结）"
+          />
+          <Textarea
+            value={content}
+            onChange={(e) => setContent(e.target.value)}
+            placeholder="提示词内容"
+            className="min-h-28"
+          />
+          <div className="flex justify-end gap-2">
+            {editingId && (
+              <Button variant="outline" size="sm" onClick={resetForm} disabled={saving}>
+                取消编辑
+              </Button>
+            )}
+            <Button size="sm" onClick={handleSubmit} disabled={saving}>
+              {editingId ? "保存修改" : "添加提示词"}
+            </Button>
+          </div>
+        </div>
+
+        <div className="space-y-2">
+          {prompts.length === 0 ? (
+            <p className="text-muted-foreground py-4 text-center text-sm">
+              暂无常用提示词
+            </p>
+          ) : (
+            prompts.map((prompt) => (
+              <div
+                key={prompt.id}
+                className="flex items-start justify-between gap-2 rounded-md border p-3"
+              >
+                <div className="min-w-0 flex-1">
+                  <p className="truncate text-sm font-medium">
+                    {prompt.title || "未命名提示词"}
+                  </p>
+                  <p className="text-muted-foreground mt-0.5 line-clamp-2 text-xs whitespace-pre-wrap">
+                    {prompt.content}
+                  </p>
+                </div>
+                <div className="flex shrink-0 items-center gap-1">
+                  <Button
+                    size="icon"
+                    variant="ghost"
+                    className="h-8 w-8"
+                    onClick={() => handleEdit(prompt.id)}
+                    title="编辑"
+                  >
+                    <PencilIcon className="h-3.5 w-3.5" />
+                  </Button>
+                  <Button
+                    size="icon"
+                    variant="ghost"
+                    className="text-destructive hover:text-destructive h-8 w-8"
+                    onClick={() => void handleDelete(prompt.id)}
+                    title="删除"
+                  >
+                    <Trash2Icon className="h-3.5 w-3.5" />
+                  </Button>
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

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

@@ -3,6 +3,7 @@
 import type { ChatStatus } from "ai";
 import {
   BrainCircuitIcon,
+  BookMarkedIcon,
   CheckIcon,
   FileTextIcon,
   GraduationCapIcon,
@@ -63,6 +64,7 @@ import { useI18n } from "@/core/i18n/hooks";
 import { useModels } from "@/core/models/hooks";
 import type { AgentThreadContext } from "@/core/threads";
 import { textOfMessage } from "@/core/threads/utils";
+import { desensitize } from "@/lib/desensitize";
 import { cn } from "@/lib/utils";
 
 import { AgentSelector } from "@/components/workspace/agents/agent-selector";
@@ -85,8 +87,14 @@ import {
 } from "../ui/dropdown-menu";
 
 import { useRecommendedQuestions } from "@/core/recommended-questions/hooks";
+import {
+  isThreadRagModeLocked,
+  lockThreadRagMode,
+  useLocalSettings,
+} from "@/core/settings";
 
 
+import { CustomPromptBar } from "./custom-prompt-menu";
 import { useThread } from "./messages/context";
 import { ModeHoverGuide } from "./mode-hover-guide";
 import { Tooltip } from "./tooltip";
@@ -176,6 +184,7 @@ export function InputBox({
   };
 }) {
   const { t } = useI18n();
+  const [localSettings, setLocalSettings] = useLocalSettings();
   const searchParams = useSearchParams();
   const [modelDialogOpen, setModelDialogOpen] = useState(false);
   const { models } = useModels();
@@ -296,6 +305,15 @@ export function InputBox({
     });
   }, [context, memoryInjectionEnabled, onContextChange]);
 
+  const ragModeLocked = isThreadRagModeLocked(threadId);
+  const ragModeEnabled = localSettings.display.ragModeEnabled || ragModeLocked;
+  const handleRagModeToggle = useCallback(() => {
+    if (ragModeLocked) {
+      return;
+    }
+    setLocalSettings("display", { ragModeEnabled: !ragModeEnabled });
+  }, [ragModeEnabled, ragModeLocked, setLocalSettings]);
+
   const handleSubmit = useCallback(
     async (message: PromptInputMessage) => {
       if (status === "streaming") {
@@ -308,6 +326,9 @@ export function InputBox({
       setFollowups([]);
       setFollowupsHidden(false);
       setFollowupsLoading(false);
+      if (ragModeEnabled) {
+        lockThreadRagMode(threadId);
+      }
 
       // Guard against submitting before the initial model auto-selection
       // effect has flushed thread settings to storage/state.
@@ -332,8 +353,10 @@ export function InputBox({
       onSubmit,
       onStop,
       resolvedModelName,
+      ragModeEnabled,
       selectedModel?.supports_thinking,
       status,
+      threadId,
     ],
   );
 
@@ -500,7 +523,7 @@ export function InputBox({
                 setTimeout(() => requestFormSubmit(), 0);
               }}
             >
-              {q.title}
+              {desensitize(q.title)}
             </button>
           ))}
         </div>
@@ -537,6 +560,21 @@ export function InputBox({
           </div>
         </div>
       )}
+      <div className="flex flex-col gap-1.5">
+      {isNewThread && (
+        <CustomPromptBar
+          className="px-1"
+          onInsert={(content) => {
+            const current = textInput.value?.trim() ?? "";
+            textInput.setInput(current ? `${current}\n${content}` : content);
+            setTimeout(() => {
+              document
+                .querySelector<HTMLTextAreaElement>("textarea[name='message']")
+                ?.focus();
+            }, 0);
+          }}
+        />
+      )}
       <div className={cn(isNewThread && "gemini-gradient-border gemini-shadow")}>
       <PromptInput
         className={cn(
@@ -545,7 +583,7 @@ export function InputBox({
           // 对话态：常规白卡 + 中性边框 + 轻阴影
           isNewThread
             ? "rounded-3xl bg-transparent border-0 shadow-none ring-0"
-            : "rounded-3xl bg-background border border-border shadow-sm dark:bg-slate-800 dark:border-slate-700",
+            : "rounded-3xl bg-background border border-border shadow-sm transition-shadow hover:shadow-md focus-within:border-ring/40 focus-within:shadow-md focus-within:ring-1 focus-within:ring-ring/20 dark:bg-slate-800 dark:border-slate-700",
           className,
         )}
         disabled={disabled}
@@ -621,6 +659,33 @@ export function InputBox({
                 <span className="text-xs font-normal">记忆</span>
               </PromptInputButton>
             </Tooltip>
+            <Tooltip
+              content={
+                ragModeEnabled
+                  ? "参考文献模式已开启：检索类结果会按编号引用展示"
+                  : "参考文献模式已关闭：点击开启"
+              }
+            >
+              <PromptInputButton
+                type="button"
+                aria-pressed={ragModeEnabled}
+                disabled={ragModeLocked || disabled}
+                className={cn(
+                  "gap-1.5! rounded-full px-3! shadow-none",
+                  ragModeLocked && "cursor-not-allowed opacity-80",
+                  ragModeEnabled
+                    ? "border border-emerald-300 bg-emerald-50 text-emerald-700 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-950/40 dark:text-emerald-200"
+                    : "border-0 bg-transparent text-muted-foreground hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100",
+                )}
+                onClick={handleRagModeToggle}
+              >
+                {ragModeEnabled && (
+                  <CheckIcon className="size-3 text-emerald-700 dark:text-emerald-200" />
+                )}
+                <BookMarkedIcon className="size-3" />
+                <span className="text-xs font-normal">参考文献</span>
+              </PromptInputButton>
+            </Tooltip>
             <PromptInputActionMenu>
               <ModeHoverGuide
                 mode={
@@ -996,6 +1061,7 @@ export function InputBox({
         )}
       </PromptInput>
       </div>
+      </div>
 
       <Dialog open={confirmOpen} onOpenChange={setConfirmOpen}>
         <DialogContent>

frontend-web/src/components/workspace/messages/markdown-content.tsx

@@ -36,6 +36,9 @@ export function MarkdownContent({
   const components = useMemo(() => {
     return {
       a: (props: AnchorHTMLAttributes<HTMLAnchorElement>) => {
+        if (props.href?.startsWith("#reference-")) {
+          return <CitationLink {...props} />;
+        }
         if (typeof props.children === "string") {
           const match = /^citation:(.+)$/.exec(props.children);
           if (match) {

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

@@ -47,6 +47,17 @@ import {
   findToolCallResult,
 } from "@/core/messages/utils";
 import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
+import { useLocalSettings } from "@/core/settings";
+import { useSkills } from "@/core/skills/hooks";
+import {
+  buildSkillDisplayMap,
+  findDisplayConfigForTool,
+  isDisplaySamplePayload,
+  normalizeDefaultDisplaySources,
+  shouldUseDefaultCitationMode,
+  type RuntimeDisplaySource,
+} from "@/core/skill-display/runtime";
+import { normalizeDisplaySources } from "@/core/skill-display/display-adapter";
 import { extractTitleFromMarkdown } from "@/core/utils/markdown";
 import { env } from "@/env";
 import { cn } from "@/lib/utils";
@@ -54,6 +65,7 @@ import { cn } from "@/lib/utils";
 import { useArtifactsOptional } from "../artifacts";
 import { FlipDisplay } from "../flip-display";
 import { Tooltip } from "../tooltip";
+import { SourceCard } from "../skill-display-sources";
 
 import { MarkdownContent } from "./markdown-content";
 
@@ -74,6 +86,12 @@ export function MessageGroup({
     env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true",
   );
   const steps = useMemo(() => convertToSteps(messages), [messages]);
+  const [settings] = useLocalSettings();
+  const { skills } = useSkills();
+  const skillDisplayMap = useMemo(
+    () => (settings.display.ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [settings.display.ragModeEnabled, skills],
+  );
   const lastToolCallStep = useMemo(() => {
     const filteredSteps = steps.filter((step) => step.type === "toolCall");
     return filteredSteps[filteredSteps.length - 1];
@@ -142,7 +160,13 @@ export function MessageGroup({
                   }
                 ></ChainOfThoughtStep>
               ) : (
-                <ToolCall key={step.id} {...step} isLoading={isLoading} />
+                <ToolCall
+                  key={step.id}
+                  {...step}
+                  isLoading={isLoading}
+                  skillDisplayMap={skillDisplayMap}
+                  ragModeEnabled={settings.display.ragModeEnabled}
+                />
               ),
             )}
           {lastToolCallStep && (
@@ -152,6 +176,8 @@ export function MessageGroup({
                 {...lastToolCallStep}
                 isLast={true}
                 isLoading={isLoading}
+                skillDisplayMap={skillDisplayMap}
+                ragModeEnabled={settings.display.ragModeEnabled}
               />
             </FlipDisplay>
           )}
@@ -209,6 +235,8 @@ function ToolCall({
   result,
   isLast = false,
   isLoading = false,
+  skillDisplayMap = new Map(),
+  ragModeEnabled = false,
 }: {
   id?: string;
   messageId?: string;
@@ -217,11 +245,56 @@ function ToolCall({
   result?: string | Record<string, unknown>;
   isLast?: boolean;
   isLoading?: boolean;
+  skillDisplayMap?: ReturnType<typeof buildSkillDisplayMap>;
+  ragModeEnabled?: boolean;
 }) {
   const { t } = useI18n();
   const artifacts = useArtifactsOptional();
 
+  const displayMatch =
+    result !== undefined && isDisplaySamplePayload(result)
+      ? null
+      : (findDisplayConfigForTool(name, skillDisplayMap, args) ??
+        null);
+  const displayItems =
+    displayMatch && result !== undefined
+      ? normalizeDisplaySources(result, displayMatch.display).map((item, index) => ({
+          ...item,
+          index: index + 1,
+          skillName: displayMatch.skillName,
+          mode: item.displayMode ?? displayMatch.display.mode,
+        }))
+      : [];
+  if (displayItems.length > 0) {
+    return (
+      <ChainOfThoughtStep
+        key={id}
+        label={
+          displayMatch?.display.mode === "citation" || !displayMatch
+            ? "检索参考来源"
+            : `获取 ${displayItems.length} 条结果`
+        }
+        icon={SearchIcon}
+      >
+        <DisplayResultsList results={displayItems} />
+      </ChainOfThoughtStep>
+    );
+  }
+
   const searchItems = normalizeSearchResults(result);
+  if (ragModeEnabled && shouldUseDefaultCitationMode(name, result, args) && searchItems.length > 0) {
+    const defaultItems = normalizeDefaultDisplaySources(result).map((item, index) => ({
+      ...item,
+      index: index + 1,
+      skillName: name,
+      mode: "citation" as const,
+    }));
+    return (
+      <ChainOfThoughtStep key={id} label="检索参考来源" icon={SearchIcon}>
+        <DisplayResultsList results={defaultItems} />
+      </ChainOfThoughtStep>
+    );
+  }
   if (name === "web_search" || searchItems.length > 0) {
     const query = resolveSearchQuery(args, result);
     let label: React.ReactNode = t.toolCalls.searchForRelatedInfo;
@@ -463,7 +536,7 @@ interface CoTReasoningStep extends GenericCoTStep<"reasoning"> {
 interface CoTToolCallStep extends GenericCoTStep<"toolCall"> {
   name: string;
   args: Record<string, unknown>;
-  result?: string;
+  result?: string | Record<string, unknown>;
 }
 
 type CoTStep = CoTReasoningStep | CoTToolCallStep;
@@ -495,12 +568,22 @@ function convertToSteps(messages: Message[]): CoTStep[] {
         };
         const toolCallId = tool_call.id;
         if (toolCallId) {
-          const toolCallResult = findToolCallResult(toolCallId, messages);
-          if (toolCallResult) {
-            try {
-              const json = JSON.parse(toolCallResult);
-              step.result = json;
-            } catch {
+          const toolCallResult = findToolCallResult(
+            toolCallId,
+            messages,
+            tool_call.name,
+          );
+          if (toolCallResult !== undefined) {
+            if (typeof toolCallResult === "string") {
+              try {
+                step.result = JSON.parse(toolCallResult) as Record<
+                  string,
+                  unknown
+                >;
+              } catch {
+                step.result = toolCallResult;
+              }
+            } else {
               step.result = toolCallResult;
             }
           }
@@ -534,6 +617,28 @@ function WebSearchResultsList({ results }: { results: SearchResultItem[] }) {
   );
 }
 
+function DisplayResultsList({ results }: { results: RuntimeDisplaySource[] }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Collapsible open={open} onOpenChange={setOpen} className="w-full">
+      <CollapsibleTrigger className="text-muted-foreground hover:text-foreground flex items-center gap-1 text-xs">
+        <ChevronDownIcon
+          className={cn(
+            "size-3.5 transition-transform duration-200",
+            open && "rotate-180",
+          )}
+        />
+        <span>{results.length} 条真实返回结果</span>
+      </CollapsibleTrigger>
+      <CollapsibleContent className="mt-2 flex flex-col gap-2">
+        {results.map((item) => (
+          <SourceCard key={`${item.skillName}-${item.index}`} source={item} />
+        ))}
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
 function SearchResultCard({ item }: { item: SearchResultItem }) {
   const [open, setOpen] = useState(false);
   const content = item.snippet ?? item.content;

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

@@ -1,32 +1,41 @@
-import type { Message } from "@langchain/langgraph-sdk";
-import { FileIcon, Loader2Icon } from "lucide-react";
+import type { Message } from '@langchain/langgraph-sdk';
+import { ClockIcon, FileIcon, Loader2Icon, PencilIcon } from 'lucide-react';
 import {
   memo,
   useCallback,
   useContext,
+  useEffect,
   useMemo,
+  useState,
   type AnchorHTMLAttributes,
   type ImgHTMLAttributes,
-} from "react";
-import rehypeKatex from "rehype-katex";
+} from 'react';
+import rehypeKatex from 'rehype-katex';
 
-import { Loader } from "@/components/ai-elements/loader";
+import { Loader } from '@/components/ai-elements/loader';
 import {
   Message as AIElementMessage,
   MessageContent as AIElementMessageContent,
   MessageResponse as AIElementMessageResponse,
   MessageToolbar,
-} from "@/components/ai-elements/message";
+} from '@/components/ai-elements/message';
 import {
   Reasoning,
   ReasoningContent,
   ReasoningTrigger,
-} from "@/components/ai-elements/reasoning";
-import { Task, TaskTrigger } from "@/components/ai-elements/task";
-import { Badge } from "@/components/ui/badge";
-import { resolveArtifactURL } from "@/core/artifacts/utils";
-import { getBackendBaseURL } from "@/core/config";
-import { useI18n } from "@/core/i18n/hooks";
+} from '@/components/ai-elements/reasoning';
+import { Task, TaskTrigger } from '@/components/ai-elements/task';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Textarea } from '@/components/ui/textarea';
+import {
+  UploadedFilePreviewDialog,
+  useAuthedObjectUrl,
+} from '@/components/workspace/messages/uploaded-file-preview-dialog';
+import { resolveArtifactURL } from '@/core/artifacts/utils';
+import { useChatAskTimes } from '@/core/chat-timestamps';
+import { getBackendBaseURL } from '@/core/config';
+import { useI18n } from '@/core/i18n/hooks';
 import {
   extractContentFromMessage,
   extractReasoningContentFromMessage,
@@ -34,17 +43,64 @@ import {
   stripArtifactTag,
   stripUploadedFilesTag,
   type FileInMessage,
-} from "@/core/messages/utils";
-import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
-import { humanMessagePlugins } from "@/core/streamdown";
-import { cn } from "@/lib/utils";
+} from '@/core/messages/utils';
+import { useRehypeSplitWordsIntoSpans } from '@/core/rehype';
+import {
+  applyInlineCitations,
+  type RuntimeDisplaySource,
+} from '@/core/skill-display/runtime';
+import { humanMessagePlugins } from '@/core/streamdown';
+import { cn } from '@/lib/utils';
 
-import { CopyButton } from "../copy-button";
+import { CitationLink } from '../citations/citation-link';
+import { CopyButton } from '../copy-button';
+import { Tooltip } from '../tooltip';
+import { SkillDisplayBlock } from '../skill-display-block';
+import { ThreadContext } from './context';
+import { DownloadWordButton } from './download-word-button';
+import { MarkdownContent, type MarkdownContentProps } from './markdown-content';
+import { MessageTokenUsage } from './message-token-usage';
 
-import { ThreadContext } from "./context";
-import { DownloadWordButton } from "./download-word-button";
-import { MarkdownContent } from "./markdown-content";
-import { MessageTokenUsage } from "./message-token-usage";
+type EmbeddedPageContext = {
+  title?: string;
+  url?: string;
+  content?: string;
+};
+
+function extractTagContent(source: string, tagName: string) {
+  const match = new RegExp(
+    `<${tagName}>\\s*([\\s\\S]*?)\\s*</${tagName}>`,
+    'i',
+  ).exec(source);
+  return match?.[1]?.trim() ?? '';
+}
+
+function parseEmbeddedPageContext(source: string): {
+  content: string;
+  pageContext: EmbeddedPageContext | null;
+} {
+  const match = /<page_context>\s*([\s\S]*?)\s*<\/page_context>/i.exec(source);
+  if (!match) {
+    return { content: source, pageContext: null };
+  }
+
+  const body = match[1] ?? '';
+  const pageContext = {
+    title: extractTagContent(body, 'title') || undefined,
+    url: extractTagContent(body, 'url') || undefined,
+    content: extractTagContent(body, 'content') || undefined,
+  };
+  const cleanedContent = source
+    .replace(match[0], '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+
+  if (!pageContext.title && !pageContext.url && !pageContext.content) {
+    return { content: cleanedContent, pageContext: null };
+  }
+
+  return { content: cleanedContent, pageContext };
+}
 
 /**
  * Resolve an in-conversation file path to a fetchable URL.
@@ -58,7 +114,7 @@ function useArtifactResolver(threadId: string): (path: string) => string {
   return useCallback(
     (path: string) => {
       if (publicShareCode) {
-        const normalized = path.startsWith("/") ? path : `/${path}`;
+        const normalized = path.startsWith('/') ? path : `/${path}`;
         return `${getBackendBaseURL()}/api/public/shares/${encodeURIComponent(
           publicShareCode,
         )}/files${normalized}`;
@@ -71,44 +127,65 @@ function useArtifactResolver(threadId: string): (path: string) => string {
 
 export function MessageListItem({
   className,
+  fitRowToContent = false,
   message,
   isLoading,
   threadId,
   tokenUsageEnabled = false,
+  displaySources = [],
+  extraRehypePlugins,
+  onEditResubmit,
 }: {
   className?: string;
+  fitRowToContent?: boolean;
   message: Message;
   isLoading?: boolean;
   threadId: string;
   tokenUsageEnabled?: boolean;
+  displaySources?: RuntimeDisplaySource[];
+  extraRehypePlugins?: ReturnType<typeof useRehypeSplitWordsIntoSpans>;
+  onEditResubmit?: (text: string) => void;
 }) {
-  const isHuman = message.type === "human";
+  const isHuman = message.type === 'human';
   const messageMarkdown =
     extractContentFromMessage(message) ??
     extractReasoningContentFromMessage(message) ??
-    "";
+    '';
   return (
     <AIElementMessage
-      className={cn("group/conversation-message relative w-full", className)}
-      from={isHuman ? "user" : "assistant"}
+      className={cn(
+        'group/conversation-message relative',
+        fitRowToContent ? 'max-w-full w-fit' : 'w-full',
+        isHuman && fitRowToContent && 'ml-auto',
+        className,
+      )}
+      from={isHuman ? 'user' : 'assistant'}
     >
       <MessageContent
-        className={isHuman ? "w-fit" : "w-full"}
+        className={isHuman ? 'w-fit' : 'w-full'}
         message={message}
         isLoading={isLoading}
         threadId={threadId}
         tokenUsageEnabled={tokenUsageEnabled}
+        displaySources={displaySources}
+        extraRehypePlugins={extraRehypePlugins}
+        onEditResubmit={onEditResubmit}
       />
-      {!isLoading && (
+      {/*
+        Human messages carry their own inline copy/edit toolbar inside
+        MessageContent (above the timestamp). Only assistant answers use the
+        floating bottom toolbar here.
+      */}
+      {!isLoading && !isHuman && (
         <MessageToolbar
           className={cn(
-            isHuman ? "-bottom-9 justify-end" : "-bottom-8",
-            "absolute right-0 left-0 z-20 opacity-0 transition-opacity delay-200 duration-300 group-hover/conversation-message:opacity-100",
+            '-bottom-8',
+            'absolute right-0 left-0 z-20 opacity-0 transition-opacity delay-200 duration-300 group-hover/conversation-message:opacity-100',
           )}
         >
           <div className="flex gap-1">
             <CopyButton clipboardData={messageMarkdown} />
-            {!isHuman && messageMarkdown && (
+            {messageMarkdown && (
               <DownloadWordButton
                 markdown={messageMarkdown}
                 fileName="message"
@@ -121,6 +198,128 @@ export function MessageListItem({
   );
 }
 
+/**
+ * Inline copy/edit affordances + editor for the user's own question bubble.
+ *
+ * Layout: bubble → hover toolbar (copy + edit) → timestamp. The toolbar sits
+ * in normal flow above the timestamp (not floating) so it never covers the
+ * following message. Clicking edit turns the bubble into a textarea seeded with
+ * the question; confirming sends the edited text as a brand-new turn (the
+ * original question stays in the thread).
+ */
+function HumanMessageBlock({
+  text,
+  pageContext,
+  filesList,
+  messageTime,
+  components,
+  onEditResubmit,
+}: {
+  text: string;
+  pageContext?: EmbeddedPageContext | null;
+  filesList: React.ReactNode;
+  messageTime: { label: string; full: string } | null;
+  components: MarkdownContentProps["components"];
+  onEditResubmit?: (text: string) => void;
+}) {
+  const { t } = useI18n();
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState(text);
+
+  useEffect(() => {
+    if (!editing) {
+      setDraft(text);
+    }
+  }, [text, editing]);
+
+  const confirmEdit = useCallback(() => {
+    const value = draft.trim();
+    if (!value) {
+      return;
+    }
+    onEditResubmit?.(value);
+    setEditing(false);
+  }, [draft, onEditResubmit]);
+
+  if (editing) {
+    return (
+      <div className="ml-auto flex w-full max-w-[min(85%,42rem)] flex-col gap-2">
+        {filesList}
+        <Textarea
+          value={draft}
+          autoFocus
+          onChange={(event) => setDraft(event.currentTarget.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+              event.preventDefault();
+              confirmEdit();
+            }
+            if (event.key === "Escape") {
+              event.preventDefault();
+              setEditing(false);
+            }
+          }}
+          className="min-h-20 resize-none text-[15px] leading-7"
+        />
+        <div className="flex items-center justify-end gap-2">
+          <Button
+            size="sm"
+            variant="ghost"
+            onClick={() => setEditing(false)}
+          >
+            {t.common.cancel}
+          </Button>
+          <Button size="sm" onClick={confirmEdit} disabled={!draft.trim()}>
+            {t.common.confirm}
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  const messageResponse = text ? (
+    <AIElementMessageResponse
+      remarkPlugins={humanMessagePlugins.remarkPlugins}
+      rehypePlugins={humanMessagePlugins.rehypePlugins}
+      components={components}
+      parseIncompleteMarkdown={false}
+    >
+      {text}
+    </AIElementMessageResponse>
+  ) : null;
+
+  return (
+    <div className="ml-auto flex flex-col items-end gap-1">
+      {filesList}
+      {messageResponse && (
+        <AIElementMessageContent className="w-fit">
+          {messageResponse}
+        </AIElementMessageContent>
+      )}
+      <MessageTimeStamp time={messageTime} align="right" />
+      {pageContext && <EmbeddedPageContextCard pageContext={pageContext} />}
+      {text && (
+        <div className="flex items-center gap-0.5 opacity-0 transition-opacity duration-200 group-hover/conversation-message:opacity-100">
+          <CopyButton clipboardData={text} className="size-6" />
+          {onEditResubmit && (
+            <Tooltip content={t.inputBox.editQuestion}>
+              <Button
+                size="icon-sm"
+                type="button"
+                variant="ghost"
+                className="size-6"
+                onClick={() => setEditing(true)}
+              >
+                <PencilIcon size={11} />
+              </Button>
+            </Tooltip>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
 /**
  * Custom image component that handles artifact URLs
  */
@@ -128,7 +327,7 @@ function MessageImage({
   src,
   alt,
   threadId,
-  maxWidth = "90%",
+  maxWidth = '90%',
   ...props
 }: React.ImgHTMLAttributes<HTMLImageElement> & {
   threadId: string;
@@ -137,13 +336,13 @@ function MessageImage({
   const resolveArtifact = useArtifactResolver(threadId);
   if (!src) return null;
 
-  const imgClassName = cn("overflow-hidden rounded-lg", `max-w-[${maxWidth}]`);
+  const imgClassName = cn('overflow-hidden rounded-lg', `max-w-[${maxWidth}]`);
 
-  if (typeof src !== "string") {
+  if (typeof src !== 'string') {
     return <img className={imgClassName} src={src} alt={alt} {...props} />;
   }
 
-  const url = src.startsWith("/mnt/") ? resolveArtifact(src) : src;
+  const url = src.startsWith('/mnt/') ? resolveArtifact(src) : src;
 
   return (
     <a href={url} target="_blank" rel="noopener noreferrer">
@@ -158,15 +357,41 @@ function MessageContent_({
   isLoading = false,
   threadId,
   tokenUsageEnabled = false,
+  displaySources = [],
+  extraRehypePlugins,
+  onEditResubmit,
 }: {
   className?: string;
   message: Message;
   isLoading?: boolean;
   threadId: string;
   tokenUsageEnabled?: boolean;
+  displaySources?: RuntimeDisplaySource[];
+  extraRehypePlugins?: ReturnType<typeof useRehypeSplitWordsIntoSpans>;
+  onEditResubmit?: (text: string) => void;
 }) {
-  const rehypePlugins = useRehypeSplitWordsIntoSpans(isLoading);
-  const isHuman = message.type === "human";
+  const baseRehypePlugins = useRehypeSplitWordsIntoSpans(isLoading);
+
+  // Streamdown splits content into per-block processors; calling the factory
+  // once here ensures all blocks share the same transformer instance (and thus
+  // the same citation counter) for this message.
+  const stableExtraPlugins = useMemo(() => {
+    if (!extraRehypePlugins?.length) return [];
+    return extraRehypePlugins.map((factory) => {
+      const transformer = factory();
+      return () => transformer;
+    });
+  }, [extraRehypePlugins]);
+
+  const rehypePlugins = useMemo(
+    () =>
+      extraRehypePlugins?.length
+        ? [...baseRehypePlugins, ...extraRehypePlugins]
+        : baseRehypePlugins,
+    [baseRehypePlugins, extraRehypePlugins],
+  );
+  const askTimes = useChatAskTimes();
+  const isHuman = message.type === 'human';
   const resolveArtifact = useArtifactResolver(threadId);
   const components = useMemo(
     () => ({
@@ -174,7 +399,16 @@ function MessageContent_({
         <MessageImage {...props} threadId={threadId} maxWidth="90%" />
       ),
       a: ({ href, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) => {
-        if (href?.startsWith("/mnt/")) {
+        if (href?.startsWith('#reference-')) {
+          return <CitationLink href={href} {...props} />;
+        }
+        if (
+          typeof props.children === 'string' &&
+          /^citation:/i.test(props.children)
+        ) {
+          return <CitationLink href={href} {...props} />;
+        }
+        if (href?.startsWith('/mnt/')) {
           const url = resolveArtifact(href);
           return (
             <a
@@ -191,13 +425,18 @@ function MessageContent_({
     [threadId, resolveArtifact],
   );
 
+  const messageTime = formatAskedTime(
+    message.additional_kwargs?.client_ts ??
+      (message.id ? askTimes[message.id] : undefined),
+  );
+
   const rawContent = extractContentFromMessage(message);
   const reasoningContent = extractReasoningContentFromMessage(message);
 
   const files = useMemo(() => {
     const files = message.additional_kwargs?.files;
     if (!Array.isArray(files) || files.length === 0) {
-      if (rawContent.includes("<uploaded_files>")) {
+      if (rawContent.includes('<uploaded_files>')) {
         // If the content contains the <uploaded_files> tag, we return the parsed files from the content for backward compatibility.
         return parseUploadedFiles(rawContent);
       }
@@ -208,10 +447,19 @@ function MessageContent_({
 
   const contentToDisplay = useMemo(() => {
     if (isHuman) {
-      return rawContent ? stripArtifactTag(stripUploadedFilesTag(rawContent)) : "";
+      return rawContent
+        ? stripArtifactTag(stripUploadedFilesTag(rawContent))
+        : '';
     }
-    return rawContent ?? "";
-  }, [rawContent, isHuman]);
+    return applyInlineCitations(rawContent ?? '', displaySources);
+  }, [rawContent, isHuman, displaySources]);
+  const parsedHumanContent = useMemo(
+    () =>
+      isHuman
+        ? parseEmbeddedPageContext(contentToDisplay)
+        : { content: contentToDisplay, pageContext: null },
+    [contentToDisplay, isHuman],
+  );
 
   const filesList =
     files && files.length > 0 ? (
@@ -219,7 +467,7 @@ function MessageContent_({
     ) : null;
 
   // Uploading state: mock AI message shown while files upload
-  if (message.additional_kwargs?.element === "task") {
+  if (message.additional_kwargs?.element === 'task') {
     return (
       <AIElementMessageContent className={className}>
         <Task defaultOpen={false}>
@@ -252,84 +500,145 @@ function MessageContent_({
   }
 
   if (isHuman) {
-    const messageResponse = contentToDisplay ? (
-      <AIElementMessageResponse
-        remarkPlugins={humanMessagePlugins.remarkPlugins}
-        rehypePlugins={humanMessagePlugins.rehypePlugins}
-        components={components}
-        parseIncompleteMarkdown={false}
-      >
-        {contentToDisplay}
-      </AIElementMessageResponse>
-    ) : null;
     return (
-      <div className={cn("ml-auto flex flex-col gap-2", className)}>
-        {filesList}
-        {messageResponse && (
-          <AIElementMessageContent className="w-fit">
-            {messageResponse}
-          </AIElementMessageContent>
-        )}
-      </div>
+      <HumanMessageBlock
+        text={parsedHumanContent.content}
+        pageContext={parsedHumanContent.pageContext}
+        filesList={filesList}
+        messageTime={messageTime}
+        components={components}
+        onEditResubmit={onEditResubmit}
+      />
     );
   }
 
   return (
     <AIElementMessageContent className={className}>
       {filesList}
-      <MarkdownContent
-        content={contentToDisplay}
-        isLoading={isLoading}
-        rehypePlugins={[...rehypePlugins, [rehypeKatex, { output: "html" }]]}
-        className="my-3"
-        components={components}
-      />
+      <div data-reference-batch-id={message.id} className="contents">
+        <AssistantDisplayContent
+          content={contentToDisplay}
+          displaySources={displaySources}
+          isLoading={isLoading}
+          renderSkillDisplayBlocks={false}
+          rehypePlugins={[...rehypePlugins, [rehypeKatex, { output: 'html' }]]}
+          components={components}
+        />
+      </div>
       <MessageTokenUsage
         enabled={tokenUsageEnabled}
         isLoading={isLoading}
         message={message}
       />
+      {!isLoading && contentToDisplay ? (
+        <MessageTimeStamp time={messageTime} align="left" />
+      ) : null}
     </AIElementMessageContent>
   );
 }
 
+function EmbeddedPageContextCard({
+  pageContext,
+}: {
+  pageContext: EmbeddedPageContext;
+}) {
+  const previewText = [pageContext.title, pageContext.url, pageContext.content]
+    .filter(Boolean)
+    .join(' | ');
+
+  return (
+    <div className="bg-muted/70 ml-auto flex w-fit min-w-0 max-w-[min(24rem,calc(100vw-2rem),100%)] flex-col gap-2 rounded-2xl border px-3 py-2 text-sm shadow-sm">
+      <div
+        className="text-muted-foreground line-clamp-2 min-w-0 [overflow-wrap:anywhere] break-words text-xs"
+        title={previewText}
+      >
+        {previewText}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Format a wall-clock message time as ``YYYY-MM-DD HH:mm`` for display, plus a
+ * full localized string for the hover title. Returns ``null`` when no/invalid
+ * timestamp is present.
+ */
+function formatAskedTime(
+  clientTs: unknown,
+): { label: string; full: string } | null {
+  if (typeof clientTs !== 'string' || !clientTs) return null;
+  const date = new Date(clientTs);
+  if (Number.isNaN(date.getTime())) return null;
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const label =
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    ` ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+  return { label, full: date.toLocaleString() };
+}
+
+/**
+ * Small date+time label shown under a message. ``align`` controls the corner:
+ * ``right`` for the user's own question, ``left`` for the model's answer.
+ */
+function MessageTimeStamp({
+  time,
+  align = 'right',
+}: {
+  time: { label: string; full: string } | null;
+  align?: 'left' | 'right';
+}) {
+  if (!time) return null;
+  return (
+    <div
+      className={cn(
+        'text-muted-foreground/60 flex items-center gap-1 text-[11px] leading-none tabular-nums',
+        align === 'right' ? 'justify-end pr-0.5' : 'justify-start pl-0.5',
+      )}
+      title={time.full}
+    >
+      <ClockIcon className="size-3 shrink-0" />
+      <span>{time.label}</span>
+    </div>
+  );
+}
+
 /**
  * Get file extension and check helpers
  */
 const getFileExt = (filename: string) =>
-  filename.split(".").pop()?.toLowerCase() ?? "";
+  filename.split('.').pop()?.toLowerCase() ?? '';
 
 const FILE_TYPE_MAP: Record<string, string> = {
-  json: "JSON",
-  csv: "CSV",
-  txt: "TXT",
-  md: "Markdown",
-  py: "Python",
-  js: "JavaScript",
-  ts: "TypeScript",
-  tsx: "TSX",
-  jsx: "JSX",
-  html: "HTML",
-  css: "CSS",
-  xml: "XML",
-  yaml: "YAML",
-  yml: "YAML",
-  pdf: "PDF",
-  png: "PNG",
-  jpg: "JPG",
-  jpeg: "JPEG",
-  gif: "GIF",
-  svg: "SVG",
-  zip: "ZIP",
-  tar: "TAR",
-  gz: "GZ",
+  json: 'JSON',
+  csv: 'CSV',
+  txt: 'TXT',
+  md: 'Markdown',
+  py: 'Python',
+  js: 'JavaScript',
+  ts: 'TypeScript',
+  tsx: 'TSX',
+  jsx: 'JSX',
+  html: 'HTML',
+  css: 'CSS',
+  xml: 'XML',
+  yaml: 'YAML',
+  yml: 'YAML',
+  pdf: 'PDF',
+  png: 'PNG',
+  jpg: 'JPG',
+  jpeg: 'JPEG',
+  gif: 'GIF',
+  svg: 'SVG',
+  zip: 'ZIP',
+  tar: 'TAR',
+  gz: 'GZ',
 };
 
-const IMAGE_EXTENSIONS = ["png", "jpg", "jpeg", "gif", "webp", "svg", "bmp"];
+const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp'];
 
 function getFileTypeLabel(filename: string): string {
   const ext = getFileExt(filename);
-  return FILE_TYPE_MAP[ext] ?? (ext.toUpperCase() || "FILE");
+  return FILE_TYPE_MAP[ext] ?? (ext.toUpperCase() || 'FILE');
 }
 
 function isImageFile(filename: string): boolean {
@@ -340,7 +649,7 @@ function isImageFile(filename: string): boolean {
  * Format bytes to human-readable size string
  */
 function formatBytes(bytes: number): string {
-  if (bytes === 0) return "—";
+  if (bytes === 0) return '0 B';
   const kb = bytes / 1024;
   if (kb < 1024) return `${kb.toFixed(1)} KB`;
   return `${(kb / 1024).toFixed(1)} MB`;
@@ -382,8 +691,17 @@ function RichFileCard({
 }) {
   const { t } = useI18n();
   const resolveArtifact = useArtifactResolver(threadId);
-  const isUploading = file.status === "uploading";
+  const [previewOpen, setPreviewOpen] = useState(false);
+  const isUploading = file.status === 'uploading';
   const isImage = isImageFile(file.filename);
+  const fileUrl = file.path ? resolveArtifact(file.path) : null;
+  // Thumbnails must be fetched with auth: the artifact route is gated and a
+  // plain <img src> sends no Authorization header → 401 (broken image). Fetch
+  // the bytes via apiFetch and display the resulting object URL instead.
+  const { objectUrl: thumbUrl, loading: thumbLoading } = useAuthedObjectUrl(
+    fileUrl,
+    isImage && !isUploading && !!fileUrl,
+  );
 
   if (isUploading) {
     return (
@@ -412,51 +730,252 @@ function RichFileCard({
     );
   }
 
-  if (!file.path) return null;
+  if (!fileUrl) return null;
 
-  const fileUrl = resolveArtifact(file.path);
+  const preview = (
+    <UploadedFilePreviewDialog
+      filename={file.filename}
+      fileUrl={fileUrl}
+      open={previewOpen}
+      onOpenChange={setPreviewOpen}
+    />
+  );
 
   if (isImage) {
     return (
-      <a
-        href={fileUrl}
-        target="_blank"
-        rel="noopener noreferrer"
-        className="group border-border/40 relative block overflow-hidden rounded-lg border"
-      >
-        <img
-          src={fileUrl}
-          alt={file.filename}
-          className="h-32 w-auto max-w-60 object-cover transition-transform group-hover:scale-105"
-        />
-      </a>
+      <>
+        <button
+          type="button"
+          onClick={() => setPreviewOpen(true)}
+          title={file.filename}
+          className="group border-border/40 relative block cursor-pointer overflow-hidden rounded-lg border"
+        >
+          {thumbUrl ? (
+            <img
+              src={thumbUrl}
+              alt={file.filename}
+              className="h-32 w-auto max-w-60 object-cover transition-transform group-hover:scale-105"
+            />
+          ) : (
+            <div className="bg-muted/40 text-muted-foreground flex h-32 w-44 items-center justify-center gap-2 text-xs">
+              {thumbLoading ? (
+                <Loader2Icon className="size-4 animate-spin" />
+              ) : (
+                <>
+                  <FileIcon className="size-4" />
+                  <span className="truncate">{file.filename}</span>
+                </>
+              )}
+            </div>
+          )}
+        </button>
+        {preview}
+      </>
     );
   }
 
   return (
-    <div className="bg-background border-border/40 flex max-w-50 min-w-30 flex-col gap-1 rounded-lg border p-3 shadow-sm">
-      <div className="flex items-start gap-2">
-        <FileIcon className="text-muted-foreground mt-0.5 size-4 shrink-0" />
-        <span
-          className="text-foreground truncate text-sm font-medium"
-          title={file.filename}
-        >
-          {file.filename}
-        </span>
-      </div>
-      <div className="flex items-center justify-between gap-2">
-        <Badge
-          variant="secondary"
-          className="rounded px-1.5 py-0.5 text-[10px] font-normal"
-        >
-          {getFileTypeLabel(file.filename)}
-        </Badge>
-        <span className="text-muted-foreground text-[10px]">
-          {formatBytes(file.size)}
-        </span>
-      </div>
-    </div>
+    <>
+      <button
+        type="button"
+        onClick={() => setPreviewOpen(true)}
+        title={file.filename}
+        className="bg-background border-border/40 hover:bg-accent/50 flex max-w-50 min-w-30 cursor-pointer flex-col gap-1 rounded-lg border p-3 text-left shadow-sm transition-colors"
+      >
+        <div className="flex items-start gap-2">
+          <FileIcon className="text-muted-foreground mt-0.5 size-4 shrink-0" />
+          <span
+            className="text-foreground truncate text-sm font-medium"
+            title={file.filename}
+          >
+            {file.filename}
+          </span>
+        </div>
+        <div className="flex items-center justify-between gap-2">
+          <Badge
+            variant="secondary"
+            className="rounded px-1.5 py-0.5 text-[10px] font-normal"
+          >
+            {getFileTypeLabel(file.filename)}
+          </Badge>
+          <span className="text-muted-foreground text-[10px]">
+            {formatBytes(file.size)}
+          </span>
+        </div>
+      </button>
+      {preview}
+    </>
   );
 }
 
 const MessageContent = memo(MessageContent_);
+
+function AssistantDisplayContent({
+  content,
+  displaySources,
+  isLoading,
+  renderSkillDisplayBlocks,
+  rehypePlugins,
+  components,
+}: {
+  content: string;
+  displaySources: RuntimeDisplaySource[];
+  isLoading: boolean;
+  renderSkillDisplayBlocks: boolean;
+  rehypePlugins: MarkdownContentProps['rehypePlugins'];
+  components: MarkdownContentProps['components'];
+}) {
+  const { parts, placedKeys } = useMemo(
+    () =>
+      splitSkillDisplayPlaceholders(
+        content,
+        displaySources,
+        renderSkillDisplayBlocks,
+      ),
+    [content, displaySources, renderSkillDisplayBlocks],
+  );
+  const fallbackBlocks = useMemo(() => {
+    if (!renderSkillDisplayBlocks) {
+      return [];
+    }
+    return groupDisplaySources(displaySources).filter(
+      (group) => group.mode !== 'citation' && !placedKeys.has(group.key),
+    );
+  }, [displaySources, placedKeys, renderSkillDisplayBlocks]);
+
+  return (
+    <>
+      {parts.map((part, index) =>
+        part.type === 'markdown' ? (
+          <MarkdownContent
+            key={`markdown-${index}`}
+            content={part.content}
+            isLoading={isLoading}
+            rehypePlugins={rehypePlugins}
+            className="my-3"
+            components={components}
+          />
+        ) : (
+          <SkillDisplayBlock
+            key={`display-${index}`}
+            mode={part.mode}
+            sources={part.sources}
+          />
+        ),
+      )}
+      {fallbackBlocks.map((group) => (
+        <SkillDisplayBlock
+          key={`fallback-${group.key}`}
+          mode={group.mode}
+          sources={group.sources}
+        />
+      ))}
+    </>
+  );
+}
+
+type DisplayPart =
+  | { type: 'markdown'; content: string }
+  | {
+      type: 'display';
+      key: string;
+      mode: RuntimeDisplaySource['mode'];
+      sources: RuntimeDisplaySource[];
+    };
+
+function splitSkillDisplayPlaceholders(
+  content: string,
+  displaySources: RuntimeDisplaySource[],
+  renderSkillDisplayBlocks: boolean,
+): { parts: DisplayPart[]; placedKeys: Set<string> } {
+  const pattern = /<skill-display\s+([^>]*?)\/>/g;
+  const parts: DisplayPart[] = [];
+  const placedKeys = new Set<string>();
+  let cursor = 0;
+  for (const match of content.matchAll(pattern)) {
+    const start = match.index ?? 0;
+    const before = content.slice(cursor, start);
+    if (before.trim()) {
+      parts.push({ type: 'markdown', content: before });
+    }
+    const attrs = parseDisplayAttrs(match[1] ?? '');
+    const group = findDisplayGroup(displaySources, attrs.tool, attrs.mode);
+    if (group) {
+      placedKeys.add(group.key);
+    }
+    if (group && renderSkillDisplayBlocks) {
+      parts.push({
+        type: 'display',
+        key: group.key,
+        mode: group.mode,
+        sources: group.sources,
+      });
+    }
+    cursor = start + match[0].length;
+  }
+  const rest = content.slice(cursor);
+  if (rest.trim() || parts.length === 0) {
+    parts.push({ type: 'markdown', content: rest });
+  }
+  return { parts, placedKeys };
+}
+
+function parseDisplayAttrs(raw: string): {
+  tool?: string;
+  mode?: RuntimeDisplaySource['mode'];
+} {
+  const attrs: Record<string, string> = {};
+  for (const match of raw.matchAll(/([a-zA-Z][\w-]*)="([^"]*)"/g)) {
+    attrs[match[1]!] = match[2]!;
+  }
+  return {
+    tool: attrs.tool || attrs.skill || attrs.name,
+    mode: attrs.mode as RuntimeDisplaySource['mode'] | undefined,
+  };
+}
+
+function findDisplayGroup(
+  sources: RuntimeDisplaySource[],
+  tool?: string,
+  mode?: RuntimeDisplaySource['mode'],
+) {
+  return groupDisplaySources(sources).find((group) => {
+    if (mode && group.mode !== mode) {
+      return false;
+    }
+    if (!tool) {
+      return true;
+    }
+    const left = normalizeName(group.skillName);
+    const right = normalizeName(tool);
+    return left === right || left.includes(right) || right.includes(left);
+  });
+}
+
+function groupDisplaySources(sources: RuntimeDisplaySource[]) {
+  const groups = new Map<
+    string,
+    {
+      key: string;
+      skillName: string;
+      mode: RuntimeDisplaySource['mode'];
+      sources: RuntimeDisplaySource[];
+    }
+  >();
+  for (const source of sources) {
+    const key = `${source.skillName}:${source.mode}`;
+    const group = groups.get(key) ?? {
+      key,
+      skillName: source.skillName,
+      mode: source.mode,
+      sources: [],
+    };
+    group.sources.push(source);
+    groups.set(key, group);
+  }
+  return [...groups.values()];
+}
+
+function normalizeName(name: string) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}