Merge branch 'xuhd' of http://192.168.0.200/knowledge-base-bj/deerflow-server into liuq

- StudioNotebooksPage: 卡片改为灰底无边框圆角网格，hover 显示三点菜单，支持重命名（PATCH）和删除（DELETE）
- StudioNotebookDetailPage: 详情页背景改为主题色渐变，内容垂直居中，输入框内联布局，模型选择器移至右侧，历史对话限显 5 条可展开/滚动
- api.ts: 新增 deleteSearchSpace、renameSearchSpace、uploadSourceText 接口
- 来源 Dialog：新增「复制的文字」面板，支持粘贴文本上传

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.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: $_\" })"
+    ]
+  }
+}

.git-remote-test.txt

@@ -0,0 +1 @@
+remote connectivity test - 2026-05-13

.gitignore

@@ -2,9 +2,20 @@
 .vscode/
 frontend-web/.vscode/
 
+# Claude Code local-only settings (per-user permissions, not shared)
+.claude/settings.local.json
+
+# 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
 frontend-web/vite-dev.log
 frontend-web/vite-dev.err.log
@@ -17,8 +28,9 @@ frontend-web/src.zip
 frontend-web/src9.zip
 frontend-web/src-v1.zip
 frontend-web/src-*.rar
-
+frontend-web/dist
 # Frontend build artifacts
+frontend-web/dist/
 frontend-web/dist-scheduled-check/
 
 # Offline backend bundles and local deployment artifacts
@@ -40,17 +52,37 @@ offline-backend-20260505/bundle/start_backend.sh
 offline-backend-20260505/bundle/stop_backend.sh
 
 # offline-backend-20260512 runtime artifacts (large files, local config, data)
-offline-backend-20260512/.env
 offline-backend-20260512/.env.example
 offline-backend-20260512/DEPLOY_BACKEND_OFFLINE_ZH.md
 offline-backend-20260512/SHA256SUMS
-offline-backend-20260512/config.yaml
 offline-backend-20260512/config.yaml.example
 offline-backend-20260512/data/
 offline-backend-20260512/deerflow-backend-offline-image-20260505.tar
 offline-backend-20260512/extensions_config.json
 offline-backend-20260512/skills/
 offline-backend-20260512/wheelhouse/
+offline-backend-20260512/backend/.deer-flow/data/*.db
+offline-backend-20260512/backend/.deer-flow/data/*.db-*
+offline-backend-20260512/backend/.deer-flow/*
 offline-backend-20260512/start_backend.sh
 offline-backend-20260512/stop_backend.sh
 offline-backend-20260512/check_backend.sh
+
+hermes-agent-main/
+
+
+skills/*
+
+offline-backend-20260512/backend/.deer-flow/*
+
+# Per-user skill_evolution overrides — runtime data written by the API
+offline-backend-20260512/backend/skill_evolution.json
+skills/
+hermes-agent-main/
+.gitignore
+offline-backend-20260512/backend/tests/*
+deploy
+.history
+
+# Frontend skills components must be tracked (excluded from the broad skills/ ignore above)
+!frontend-web/src/components/workspace/skills/

.idea/.gitignore

@@ -1,10 +0,0 @@
-# 默认忽略的文件
-/shelf/
-/workspace.xml
-# 基于编辑器的 HTTP 客户端请求
-/httpRequests/
-# 已忽略包含查询文件的默认文件夹
-/queries/
-# Datasource local storage ignored files
-/dataSources/
-/dataSources.local.xml

.idea/deerflow-server-master.iml

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<module type="WEB_MODULE" version="4">
-  <component name="NewModuleRootManager">
-    <content url="file://$MODULE_DIR$" />
-    <orderEntry type="inheritedJdk" />
-    <orderEntry type="sourceFolder" forTests="false" />
-  </component>
-</module>

.idea/modules.xml

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ProjectModuleManager">
-    <modules>
-      <module fileurl="file://$PROJECT_DIR$/.idea/deerflow-server-master.iml" filepath="$PROJECT_DIR$/.idea/deerflow-server-master.iml" />
-    </modules>
-  </component>
-</project>

.idea/prettier.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="PrettierConfiguration">
-    <option name="myConfigurationMode" value="AUTOMATIC" />
-  </component>
-</project>

.idea/vcs.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="VcsDirectoryMappings">
-    <mapping directory="" vcs="Git" />
-  </component>
-</project>

CLAUDE.md

@@ -4,669 +4,92 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-DeerFlow is a full-stack AI agent system combining:
-- **Frontend**: React/Vite web interface for interactive agent conversations
-- **Backend**: LangGraph-based agent runtime with sandbox execution, persistent memory, and subagent delegation
+This is a customized offline deployment of **DeerFlow** — a LangGraph-based AI super agent platform. The repo contains two sub-projects:
 
-This is a monorepo with frontend and backend components running in parallel.
+- `offline-backend-20260512/backend/` — Python backend (FastAPI Gateway + LangGraph agent runtime)
+- `frontend-web/` — Vite + React 19 frontend (TypeScript, pnpm)
 
----
+Managed together via shell scripts in `scripts/`.
 
-## Architecture
+## Commands
 
-```
-┌────────────────────────────────────────────────────────┐
-│                  DeerFlow Application                  │
-├────────────────────────────────────────────────────────┤
-│                    Nginx (Port 2026)                   │
-│              (Unified reverse proxy)                   │
-└─────────────────┬──────────────────┬──────────────────┘
-                  │                  │
-    /api/langgraph/* (Gateway)      / (Frontend + /api/*)
-           │                              │
-    ┌──────▼──────────┐        ┌─────────▼────────────┐
-    │  Gateway API    │        │  Frontend Web UI     │
-    │   (Port 8001)   │        │   (Port 3000)        │
-    │                 │        │                      │
-    │  - LangGraph    │        │ - React 19 + Vite   │
-    │  - FastAPI      │        │ - TypeScript         │
-    │  - Tools        │        │ - Tailwind CSS       │
-    │  - Memory       │        │                      │
-    └─────────────────┘        └──────────────────────┘
-            │
-    ┌───────▼──────────────────┐
-    │  Agent Runtime (LangGraph)│
-    │  ┌──────────────────────┐ │
-    │  │    Lead Agent        │ │
-    │  │  ┌────────────────┐  │ │
-    │  │  │  Middlewares   │  │ │
-    │  │  │  (10 total)    │  │ │
-    │  │  └────────────────┘  │ │
-    │  │  ┌────────────────┐  │ │
-    │  │  │  Tools         │  │ │
-    │  │  │  - Sandbox     │  │ │
-    │  │  │  - MCP         │  │ │
-    │  │  │  - Built-in    │  │ │
-    │  │  │  - Subagents   │  │ │
-    │  │  └────────────────┘  │ │
-    │  └──────────────────────┘ │
-    └───────────────────────────┘
-```
-
-**Request Routing**:
-- `/api/langgraph/*` → Gateway (LangGraph runtime)
-- `/api/*` (other) → Gateway (FastAPI REST endpoints)
-- `/` → Frontend (React web interface)
-
----
-
-## Project Structure
-
-```
-deerflow-server-master/
-├── CLAUDE.md                          # This file (root guidance)
-├── .gitignore                         # Git ignore rules
-│
-├── frontend-web/                      # React/Vite web interface
-│   ├── package.json                   # Frontend dependencies
-│   ├── package-lock.json
-│   ├── vite.config.ts                 # Vite bundler config
-│   ├── tsconfig.json                  # TypeScript config
-│   ├── tailwind.config.ts             # Tailwind CSS config
-│   ├── postcss.config.js              # PostCSS config
-│   ├── index.html                     # HTML entry point
-│   └── src/
-│       ├── App.tsx                    # Root component
-│       ├── main.tsx                   # React DOM mount
-│       ├── components/
-│       │   ├── ai-elements/           # Agent UI components (message, artifact, plan, etc.)
-│       │   ├── landing/               # Landing page components
-│       │   ├── ui/                    # Base UI components (shadcn/ui styled)
-│       │   ├── workspace/             # Main workspace interface
-│       │   ├── query-client-provider.tsx
-│       │   └── theme-provider.tsx
-│       ├── hooks/                     # Custom React hooks
-│       ├── lib/                       # Utilities (HTTP client, formatting)
-│       ├── pages/                     # Route pages
-│       └── styles/                    # Global CSS
-│
-└── offline-backend-20260512/backend/  # Python FastAPI + LangGraph backend
-    ├── CLAUDE.md                      # Detailed backend guidance
-    ├── README.md                      # Backend documentation
-    ├── Makefile                       # Backend commands
-    ├── pyproject.toml                 # Python dependencies + workspace
-    ├── langgraph.json                 # LangGraph Studio configuration
-    │
-    ├── packages/harness/              # deerflow-harness: Publishable agent framework
-    │   ├── pyproject.toml
-    │   └── deerflow/
-    │       ├── agents/                # LangGraph agent system
-    │       ├── sandbox/               # Code execution isolation
-    │       ├── subagents/             # Task delegation system
-    │       ├── tools/                 # Tool ecosystem
-    │       ├── models/                # LLM model factory
-    │       ├── mcp/                   # Model Context Protocol integration
-    │       ├── skills/                # Skills discovery & loading
-    │       ├── config/                # Configuration system
-    │       ├── community/             # Community tools (Tavily, Jina, Firecrawl)
-    │       ├── reflection/            # Dynamic module loading
-    │       └── client.py              # Embedded DeerFlowClient
-    │
-    ├── app/                           # Unpublished application code
-    │   ├── gateway/                   # FastAPI Gateway API
-    │   │   ├── app.py                 # FastAPI application
-    │   │   └── routers/               # REST endpoints
-    │   └── channels/                  # IM integrations (Feishu, Slack, Telegram, DingTalk)
-    │
-    ├── tests/                         # Comprehensive test suite
-    ├── docs/                          # Detailed documentation
-    └── .deer-flow/                    # Runtime directory (created at startup)
-        ├── agents/                    # Custom agent definitions
-        ├── users/                     # Per-user data
-        │   └── {user_id}/
-        │       ├── memory.json        # Memory system
-        │       ├── threads/           # Per-thread data
-        │       └── agents/            # Per-agent memory
-        └── threads/                   # Thread-specific workspace (legacy)
-```
-
----
-
-## Setup & Installation
-
-### Prerequisites
-
-- Node.js 18+ and pnpm
-- Python 3.12+
-- uv package manager
-- API keys for LLM providers (OpenAI, Anthropic, etc.)
-
-### Quick Start (Full Application)
+### Full Application (from repo root)
 
 ```bash
-cd offline-backend-20260512/backend
-
-# Install all dependencies
-make install
-
-# Create config from template
-cp config.example.yaml config.yaml
-
-# Set your API keys
-export OPENAI_API_KEY="your-key-here"
-# ... other API keys as needed
-
-# Start all services
-make dev
+./scripts/start-all.sh    # Start backend + frontend as background daemons
+./scripts/stop-all.sh     # Stop both
+./scripts/restart-all.sh  # Restart both
+./scripts/status.sh       # Check running status
 ```
 
-Access at: **http://localhost:2026**
+Logs and PID files are written to `.runtime/logs/` and `.runtime/pids/`.
 
----
-
-## Development Commands
-
-### Full Application (from backend directory)
+### Backend Only (from `offline-backend-20260512/backend/`)
 
 ```bash
-make install      # Install frontend + backend dependencies
-make dev          # Start Gateway + Frontend + Nginx (port 2026)
-make gateway      # Run Gateway API only (port 8001)
-make test         # Run all tests
-make lint         # Lint code
-make format       # Format code with ruff
+make install    # Install Python dependencies (uv)
+make dev        # Run Gateway API with hot-reload on port 8001
+make gateway    # Run Gateway API without reload
+make test       # Run all tests: PYTHONPATH=. uv run pytest tests/ -v
+make lint       # Lint with ruff
+make format     # Format with ruff
 ```
 
-### Frontend Only (from frontend-web directory)
-
+Run a single test file:
 ```bash
-pnpm install      # Install frontend dependencies
-pnpm dev          # Start Vite dev server (port 3000)
-pnpm build        # Build for production
-pnpm preview      # Preview production build
-pnpm typecheck    # TypeScript type checking
-```
-
-### Backend Only (from backend directory)
-
-```bash
-make install      # Install dependencies
-make dev          # Run Gateway API with auto-reload (port 8001)
-make gateway      # Run Gateway API (no reload)
-make test         # Run tests
-make lint         # Check code style
-make format       # Auto-format code
-```
-
----
-
-## Architecture Highlights
-
-### Frontend (`frontend-web/`)
-
-- **Framework**: React 19 with TypeScript
-- **Bundler**: Vite for fast dev/build
-- **Styling**: Tailwind CSS + shadcn/ui components
-- **State Management**: React Query (TanStack Query) + local state
-- **Routing**: React Router v7
-- **Key Libraries**:
-  - `@xyflow/react` - Node/edge visualization for agent workflows
-  - `codemirror` - Code editing with language support
-  - `sonner` - Toast notifications
-  - `motion` - Animation library
-  - `katex` - Math rendering
-  - `remark-gfm` + `rehype` - Markdown processing
-
-**Main Components**:
-- `components/ai-elements/` - Agent-specific UI (message, artifact, plan, canvas, etc.)
-- `components/ui/` - Reusable shadcn/ui-style components
-- `components/workspace/` - Main workspace interface
-- `components/landing/` - Public landing page
-
-### Backend (`offline-backend-20260512/backend/`)
-
-The backend is split into two layers:
-
-1. **Harness** (`packages/harness/deerflow/`)
-   - Publishable agent framework package
-   - Contains: agents, sandbox, tools, models, MCP, skills, config
-   - Import prefix: `from deerflow.*`
-   - Can be published as `deerflow-harness` PyPI package
-
-2. **App** (`app/`)
-   - Unpublished application code
-   - Contains: FastAPI Gateway API, IM channel integrations
-   - Import prefix: `from app.*`
-   - **Boundary rule**: App imports Harness, but Harness never imports App
-
-**Key Systems**:
-- **Lead Agent** - Single LangGraph agent with 10 middleware components
-- **Sandbox** - Per-thread isolated execution (local filesystem or Docker)
-- **Subagents** - Background task delegation with 3-concurrent limit
-- **Memory** - LLM-powered persistent context across conversations
-- **Tools** - Sandbox (bash, read/write), MCP, community (web search), built-in (clarification, image view)
-- **Skills** - Domain-specific workflows injected via system prompt
-- **MCP** - Model Context Protocol server integration
-
-**For detailed backend architecture, see `offline-backend-20260512/backend/CLAUDE.md`**
-
----
-
-## Configuration
-
-### Main Configuration (`config.yaml`)
-
-Place in project root (same level as this file). See `offline-backend-20260512/backend/config.example.yaml` for full template.
-
-Key sections:
-- `models` - LLM configurations (OpenAI, Anthropic, etc.) with thinking/vision flags
-- `tools` - Tool definitions with module paths
-- `sandbox` - Execution environment provider
-- `skills` - Skills directory paths
-- `memory` - Memory system (enabled, storage, debounce)
-- `title` - Auto-title generation
-- `summarization` - Context summarization
-- `subagents` - Task delegation (enabled/disabled)
-
-Config values starting with `$` are resolved as environment variables (e.g., `$OPENAI_API_KEY`).
-
-### Extensions Configuration (`extensions_config.json`)
-
-Place in project root. Configures MCP servers and skill states:
-
-```json
-{
-  "mcpServers": {
-    "github": {
-      "enabled": true,
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
-    }
-  },
-  "skills": {
-    "pdf-processing": {"enabled": true}
-  }
-}
-```
-
-### Environment Variables
-
-```bash
-# LLM API Keys
-export OPENAI_API_KEY="sk-..."
-export ANTHROPIC_API_KEY="sk-ant-..."
-
-# Tool API Keys
-export TAVILY_API_KEY="tvly-..."
-export GITHUB_TOKEN="ghp_..."
-
-# Configuration paths
-export DEER_FLOW_CONFIG_PATH="./config.yaml"
-export DEER_FLOW_EXTENSIONS_CONFIG_PATH="./extensions_config.json"
-
-# Tracing (optional)
-export LANGSMITH_TRACING=true
-export LANGSMITH_API_KEY="lsv2_pt_..."
-export LANGSMITH_PROJECT="myproject"
-```
-
----
-
-## Important Development Guidelines
-
-### Documentation Updates
-
-**CRITICAL**: Always update relevant documentation after code changes:
-- Update `offline-backend-20260512/backend/README.md` for user-facing changes
-- Update `offline-backend-20260512/backend/CLAUDE.md` for internal changes
-- Keep documentation synchronized with code
-
-### Testing
-
-**Test-Driven Development (TDD) is mandatory** for backend:
-```bash
-cd offline-backend-20260512/backend
-
-# Run all tests
-make test
-
-# Run specific test
 PYTHONPATH=. uv run pytest tests/test_<feature>.py -v
 ```
 
-Frontend testing is lighter-weight but should be done for critical components.
-
-### Code Style
-
-- **Backend**: `ruff` (line length: 240, Python 3.12+, double quotes)
-- **Frontend**: TypeScript with eslint/prettier defaults
-
-### Architecture Boundaries
-
-The **Harness ↔ App boundary** (enforced by CI tests):
-```python
-# ✅ Allowed (App → Harness)
-from deerflow.agents import make_lead_agent
-
-# ❌ Forbidden (Harness → App)
-from app.gateway.routers import ...  # This will fail CI tests
-```
-
----
-
-## Key Features
-
-### 1. Sandbox Execution
-
-Per-thread isolated code execution with virtual path mapping:
-- **Local**: Filesystem-based execution (default)
-- **Docker**: Aio sandbox provider for complete isolation
-- **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace`
-- **Paths**: `/mnt/user-data/{workspace,uploads,outputs}` → thread-specific physical directories
-
-### 2. Persistent Memory
-
-LLM-powered context retention across conversations:
-- Automatic extraction of facts and preferences
-- Structured storage with confidence scoring
-- Debounced updates to minimize LLM calls
-- Injected into agent system prompt for context awareness
-
-See `offline-backend-20260512/backend/docs/memory-improvements.md` for details.
-
-### 3. Subagent Delegation
-
-Background task execution with concurrent limits:
-- Built-in agents: `general-purpose` (full toolset) and `bash` (commands)
-- Max 3 concurrent subagents per turn
-- 15-minute timeout per task
-- Real-time status updates via SSE
-
-### 4. Tool Ecosystem
-
-Modular tool system supporting multiple providers:
-- **Sandbox tools**: Code execution in isolated environments
-- **Built-in tools**: `ask_clarification`, `view_image`, `present_files`
-- **MCP tools**: Any Model Context Protocol server (stdio, SSE, HTTP)
-- **Community tools**: Tavily (web search), Jina (web fetch), Firecrawl (scraping)
-- **Skills**: Domain-specific workflows loaded from SKILL.md files
-
-### 5. Model Context Protocol (MCP)
-
-Integrate external tools and services:
-- **Transports**: stdio, SSE, HTTP (with OAuth support)
-- **Configuration**: `extensions_config.json` for server setup
-- **Runtime updates**: Changes detected and reloaded automatically
-
-### 6. Plan Mode
-
-TodoList middleware for complex multi-step tasks:
-- Controlled via runtime config: `is_plan_mode = True`
-- Provides `write_todos` tool for task tracking
-- Real-time task status updates
-
-See `offline-backend-20260512/backend/docs/plan_mode_usage.md`.
-
-### 7. Vision Support
-
-For models with `supports_vision: true`:
-- `ViewImageMiddleware` processes images automatically
-- `view_image_tool` added to agent toolset
-- Images converted to base64 and injected into state
-
-### 8. File Upload
-
-Multi-file upload with automatic document conversion:
-- Supports: PDF, PPT, Excel, Word documents
-- Auto-conversion via `markitdown`
-- Endpoint: `POST /api/threads/{thread_id}/uploads`
-- Files stored in thread-isolated directories
-
-See `offline-backend-20260512/backend/docs/FILE_UPLOAD.md`.
-
-### 9. IM Channel Integration
-
-External messaging platform bridges:
-- **Supported**: Feishu, Slack, Telegram, DingTalk
-- **Architecture**: Channels use `langgraph-sdk` HTTP client
-- **Streaming**: Feishu updates single card in place; Slack/Telegram use `wait()` response
-- See `offline-backend-20260512/backend/app/channels/` for implementation
-
-### 10. Context Summarization
-
-Automatic conversation compression when approaching token limits:
-- Configurable trigger types: tokens, messages, or token fraction
-- Keeps recent messages while summarizing older ones
-- See `offline-backend-20260512/backend/docs/summarization.md`.
-
----
-
-## Middleware Chain (Backend)
-
-The agent runtime executes 18 middleware components in strict order:
-
-1. **ThreadDataMiddleware** - Per-thread isolated directories
-2. **UploadsMiddleware** - Inject uploaded files
-3. **SandboxMiddleware** - Acquire sandbox environment
-4. **DanglingToolCallMiddleware** - Handle incomplete tool responses
-5. **LLMErrorHandlingMiddleware** - Normalize provider errors
-6. **GuardrailMiddleware** - Tool call authorization (optional)
-7. **SandboxAuditMiddleware** - Security audit logging
-8. **ToolErrorHandlingMiddleware** - Convert exceptions to error messages
-9. **SummarizationMiddleware** - Context reduction (optional)
-10. **TodoListMiddleware** - Task tracking (optional, plan mode)
-11. **TokenUsageMiddleware** - Token tracking (optional)
-12. **TitleMiddleware** - Auto-generate conversation titles
-13. **MemoryMiddleware** - Queue for async memory updates
-14. **ViewImageMiddleware** - Inject vision image data (conditional)
-15. **DeferredToolFilterMiddleware** - Hide deferred tools (optional)
-16. **SubagentLimitMiddleware** - Enforce concurrent subagent limit (optional)
-17. **LoopDetectionMiddleware** - Detect and break tool-call loops
-18. **ClarificationMiddleware** - Interrupt on clarification requests (must be last)
-
-See `offline-backend-20260512/backend/CLAUDE.md` for detailed middleware descriptions.
-
----
-
-## Common Workflows
-
-### Adding a New Tool
-
-1. Define tool in `packages/harness/deerflow/tools/` or `packages/harness/deerflow/community/`
-2. Add to `config.yaml` `tools` section with module path
-3. Write unit tests in `backend/tests/`
-4. Update `CLAUDE.md` with tool description
-5. Test via `make test`
-
-### Creating a Custom Agent
-
-1. Add agent metadata to database (`agents` table)
-2. Create agent directory: `.deer-flow/agents/{agent_id}/SOUL.md`
-3. Define agent behavior via SOUL.md frontmatter
-4. Access via Gateway API: `GET /api/agents/{id}`
-
-### Configuring MCP Servers
-
-1. Add server to `extensions_config.json`:
-```json
-{
-  "mcpServers": {
-    "my-server": {
-      "enabled": true,
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "my-mcp-package"]
-    }
-  }
-}
-```
-
-2. Restart Gateway API - MCP tools auto-loaded via lazy initialization
-3. Tools available immediately in agent toolset
-
-### Testing in Development
+### Frontend Only (from `frontend-web/`)
 
 ```bash
-# Backend unit tests
-cd offline-backend-20260512/backend
-make test
-
-# Run specific test
-PYTHONPATH=. uv run pytest tests/test_memory_updater.py -v
-
-# Frontend development
-cd frontend-web
-pnpm dev  # Access at http://localhost:3000
+pnpm install    # Install dependencies
+pnpm dev        # Start Vite dev server on port 5174
+pnpm build      # Production build
+pnpm typecheck  # TypeScript type checking (tsc --noEmit)
 ```
 
----
+## Service Ports
 
-## Port Mapping
+| Service | Port | Notes |
+|---------|------|-------|
+| Backend (Gateway API) | 8001 | FastAPI + LangGraph runtime |
+| Frontend (Vite) | 5174 | React SPA |
 
-| Service | Port | Purpose |
-|---------|------|---------|
-| **Frontend** | 3000 | React development server |
-| **Gateway API** | 8001 | FastAPI REST endpoints + LangGraph runtime |
-| **LangGraph Server** | 2024 | Raw LangGraph protocol (used internally) |
-| **Nginx** | 2026 | Unified reverse proxy (public entry point) |
-| **Provisioner** | 8002 | Kubernetes sandbox provisioner (optional, Docker dev only) |
+Frontend connects to backend via env vars `VITE_BACKEND_BASE_URL` and `VITE_LANGGRAPH_BASE_URL` (injected by `scripts/start-frontend.sh`).
 
----
-
-## Important Files & References
-
-### Backend Architecture
-- `offline-backend-20260512/backend/CLAUDE.md` - Detailed backend guidance
-- `offline-backend-20260512/backend/README.md` - User-facing backend documentation
-- `offline-backend-20260512/backend/docs/ARCHITECTURE.md` - Deep-dive architecture
-- `offline-backend-20260512/backend/docs/API.md` - Gateway API reference
-- `offline-backend-20260512/backend/docs/CONFIGURATION.md` - Config schema
-
-### Frontend Components
-- `frontend-web/src/components/ai-elements/` - Agent UI components
-- `frontend-web/src/components/ui/` - Reusable UI components
-- `frontend-web/src/components/workspace/` - Main workspace
-
-### Configuration
-- `config.example.yaml` - Backend configuration template
-- `extensions_config.json` - MCP servers and skills
-- `offline-backend-20260512/backend/langgraph.json` - LangGraph Studio config
-
-### Testing
-- `offline-backend-20260512/backend/tests/` - Test suite
-- Regression tests: `test_docker_sandbox_mode_detection.py`, `test_provisioner_kubeconfig.py`, `test_harness_boundary.py`
-
----
-
-## Troubleshooting
-
-### Port Already in Use
-
-If a port is already in use, kill the process:
-```bash
-# Find process on port (e.g., 8001)
-lsof -i :8001
-
-# Kill process
-kill -9 <PID>
-```
-
-### Configuration Issues
-
-1. Verify `config.yaml` exists in project root
-2. Run: `make config-upgrade` to auto-merge missing fields
-3. Check `config_version` in `config.yaml` matches `config.example.yaml`
-
-### Memory System Issues
-
-Check memory state:
-```bash
-# List memory files
-ls -la offline-backend-20260512/backend/.deer-flow/users/
-
-# Reload memory
-curl -X POST http://localhost:8001/api/memory/reload
-```
-
-### Test Failures
-
-Ensure the test dependency boundary is not violated:
-```bash
-# Run boundary test specifically
-cd offline-backend-20260512/backend
-PYTHONPATH=. uv run pytest tests/test_harness_boundary.py -v
-```
-
----
-
-## Technology Stack
-
-### Frontend
-- **React** 19 - UI framework
-- **TypeScript** - Type safety
-- **Vite** - Fast bundler
-- **Tailwind CSS** - Utility-first styling
-- **React Router** - Client routing
-- **TanStack Query** - Data fetching
-- **XYFlow** - Graph visualization
-- **CodeMirror** - Code editor
-- **Shiki** - Syntax highlighting
-- **Remark/Rehype** - Markdown processing
+## Architecture
 
 ### Backend
-- **LangGraph** 1.0.6+ - Agent orchestration framework
-- **LangChain** 1.2.3+ - LLM abstractions and tools
-- **FastAPI** 0.115.0+ - REST API framework
-- **Uvicorn** - ASGI server
-- **Python 3.12+** - Programming language
-- **uv** - Fast Python package manager
-- **Ruff** - Linting and formatting
-- **Pytest** - Testing framework
-- **langchain-mcp-adapters** - Model Context Protocol support
-- **markitdown** - Document conversion
-- **Tavily/Jina/Firecrawl** - Web tools
 
----
+The backend (`offline-backend-20260512/backend/`) is split into two layers:
 
-## Contributing
+- **`packages/harness/deerflow/`** — publishable agent framework (`deerflow.*` imports): LangGraph lead agent, middleware chain, sandbox, tools, MCP, memory, models, skills. **Never imports from `app.*`.**
+- **`app/`** — application layer (`app.*` imports): FastAPI Gateway routers, IM channel integrations (Feishu, Slack, Telegram, DingTalk).
 
-1. Create a feature branch from `master`
-2. Make changes and write tests
-3. Run linting and tests:
-   ```bash
-   make lint
-   make test
-   ```
-4. Update relevant CLAUDE.md and README.md files
-5. Create a pull request
+The **Lead Agent** (`deerflow/agents/lead_agent/`) is the single LangGraph graph entry point. It wraps a middleware chain (~18 middlewares assembled in strict order) around LLM calls, handling: thread isolation, sandbox lifecycle, uploads, memory, plan mode, vision, subagent delegation, and loop detection.
 
-### CI/CD
+**Middleware order matters** — middlewares are appended in a fixed sequence; `ClarificationMiddleware` must always be last. See `offline-backend-20260512/backend/CLAUDE.md` for the full ordered list.
 
-GitHub Actions runs:
-- Backend unit tests (including harness boundary test)
-- Linting checks
-- Type checking
+**Harness → App import firewall** is enforced by `tests/test_harness_boundary.py` (runs in CI).
 
-All must pass before merging to `master`.
+### Frontend
 
----
+The frontend (`frontend-web/`) is a React 19 + Vite SPA:
 
-## Support
+- **Routing**: React Router v7; top-level routes in `src/pages/PageRoutes.tsx`, workspace sub-routes in `src/pages/WorkspaceRoutes.tsx`
+- **Pages**: `ChatPage` (thread chat), `AgentChatPage` (custom agent chat), `AgentsPage`/`NewAgentPage` (agent management), `ScheduledTasksPage`/`ScheduledTaskRunDetailPage` (scheduled tasks)
+- **State**: TanStack Query for server state, context providers (`SubtasksProvider`, `ArtifactsProvider`, `PromptInputProvider`) scoped to `WorkspaceRoutes`
+- **LLM streaming**: `@langchain/langgraph-sdk` streams messages from the backend via SSE
+- **UI**: Radix UI primitives + TailwindCSS v4 + shadcn-style components in `src/components/ui/`
+- **Shims**: `src/shims/` provides `next/link` and `next/navigation` polyfills (original code was Next.js)
 
-For issues and feature requests:
-- Check the detailed docs in `offline-backend-20260512/backend/docs/`
-- Review existing tests for usage examples
-- Ask Claude Code for help with `/help` command
+### Configuration
 
----
+Backend config lives in `offline-backend-20260512/backend/config.yaml`. Values starting with `$` resolve as environment variables (e.g., `$OPENAI_API_KEY`). MCP servers and skills are configured in `extensions_config.json` in the same directory.
 
-## License & Attribution
+## Detailed Backend Reference
 
-See LICENSE file in project root.
-
-For more details on specific systems, see:
-- Backend: `offline-backend-20260512/backend/CLAUDE.md`
-- Backend architecture: `offline-backend-20260512/backend/docs/ARCHITECTURE.md`
-- Frontend: Components in `frontend-web/src/components/`
+The backend has its own comprehensive documentation at:
+- `offline-backend-20260512/backend/CLAUDE.md` — architecture, middleware chain, all API routes, config schema, sandbox/memory/subagent systems
+- `offline-backend-20260512/backend/README.md` — setup guide, technology stack

frontend-web/.env.development

@@ -1,4 +1,34 @@
-# 本地开发：直连 Gateway（与 offline-backend-20260512/backend 默认端口一致）
-# 修改端口时请同步改这里，并重启 `npm run dev`
-VITE_BACKEND_BASE_URL=http://127.0.0.1:8001/
+# 本地开发（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= xxx
+VITE_AIPI_CONSUMER_URL=https://ch1.b.uat.4.cn/consumer
+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=

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

@@ -0,0 +1,23 @@
+# 复制为 .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_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,7 +1,35 @@
-# 复制为 .env 或 .env.development 后按需修改（Vite 仅暴露以 VITE_ 开头的变量）
+# 环境变量说明（Vite 仅暴露以 VITE_ 开头的变量）
 #
-# Gateway 根地址（REST：`/api/models`、`/api/threads/...` 等）
-VITE_BACKEND_BASE_URL=http://127.0.0.1:8001
+# ┌─────────────────┬──────────────────────────────────────────────────┐
+# │ 命令            │ 生效文件                                          │
+# ├─────────────────┼──────────────────────────────────────────────────┤
+# │ pnpm dev        │ .env.development + .env.development.local        │
+# │ pnpm build      │ .env.production + .env.production.local          │
+# │ scripts/start-* │ 脚本注入的环境变量会覆盖上述文件（见下方说明）      │
+# └─────────────────┴──────────────────────────────────────────────────┘
 #
-# LangGraph SDK 的 apiUrl：须指向带 `/api` 的前缀，以便请求落在 `/api/threads`、`/api/assistants` 等路由上
-VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api
+# 推荐：
+# - 日常本地开发：改 .env.development（已提交，团队默认 UAT 地址）
+# - 本机连 127.0.0.1:8001：复制 .env.development.local.example → .env.development.local
+# - 内网打包部署：改 .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
+
+# --- 开发环境（见 .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
+
+# --- 生产打包（见 .env.production）---
+# 部署前修改 .env.production 中的地址，再执行 pnpm build
+
+# 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.production

@@ -0,0 +1,28 @@
+# 生产打包（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
+VITE_AIPI_PGLINKTO_URL=https://pg.b.uat.4.cn
+VITE_AIPI_XKLINKTO_URL=https://kz.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/docs/kaifawendnag.md

@@ -0,0 +1,975 @@
+# DeerFlow 前端开发文档
+
+## 目录
+
+1. [整体目录结构](#1-整体目录结构)
+2. [路由结构](#2-路由结构)
+3. [核心数据流与状态管理](#3-核心数据流与状态管理)
+4. [主要页面组件](#4-主要页面组件)
+5. [核心业务组件](#5-核心业务组件)
+6. [核心 Hooks 与工具函数](#6-核心-hooks-与工具函数)
+7. [API 调用层](#7-api-调用层)
+8. [国际化机制](#8-国际化机制)
+9. [主题与样式体系](#9-主题与样式体系)
+10. [关键业务流程](#10-关键业务流程)
+11. [项目配置与依赖](#11-项目配置与依赖)
+12. [常见开发模式](#12-常见开发模式)
+
+---
+
+## 1. 整体目录结构
+
+```
+frontend-web/src/
+├── App.tsx                        # 应用入口，顶层路由 + Provider
+├── env.ts                         # 环境变量类型定义
+├── pages/                         # 路由级页面组件
+│   ├── PageRoutes.tsx             # /page/* 根路由容器（含外部系统预留位）
+│   ├── WorkspaceRoutes.tsx        # /page/workspace/* 工作区路由
+│   ├── LoginPage.tsx              # 登录页
+│   ├── LandingPage.tsx            # 营销落地页（强制 dark 主题）
+│   ├── ChatsPage.tsx              # 对话列表
+│   ├── ChatPage.tsx               # 单条对话（核心页面）
+│   ├── AgentsPage.tsx             # 智能体库
+│   ├── AgentChatPage.tsx          # 与智能体对话
+│   ├── NewAgentPage.tsx           # 创建智能体（两步流程）
+│   ├── ScheduledTasksPage.tsx     # 定时任务管理
+│   ├── ScheduledTaskRunDetailPage.tsx  # 定时任务执行详情
+│   ├── ScheduledChatPage.tsx      # 定时任务对话跳转页
+│   └── NotFoundPage.tsx           # 404 页面
+├── components/                    # 业务组件库
+│   ├── ui/                        # shadcn/ui 基础组件（Button、Card、Dialog 等 40+）
+│   ├── ai-elements/               # AI 交互可视化组件
+│   │   ├── prompt-input/          # 输入框 Context + 子组件系统
+│   │   ├── artifact.tsx           # 制品展示
+│   │   ├── canvas.tsx
+│   │   ├── conversation.tsx       # 虚拟滚动对话容器
+│   │   ├── message.tsx
+│   │   ├── model-selector.tsx
+│   │   ├── code-block.tsx
+│   │   └── shimmer.tsx
+│   ├── workspace/                 # 工作区业务组件（详见第 5 节）
+│   └── landing/                   # 落地页组件
+├── core/                          # 核心业务逻辑层（非 UI）
+│   ├── api/                       # API 客户端（LangGraph SDK + Fetch）
+│   ├── auth/                      # 认证管理
+│   ├── config/                    # 环境配置 & Base URL
+│   ├── i18n/                      # 国际化（上下文、翻译文件、语言检测）
+│   ├── threads/                   # 对话线程管理（最核心）
+│   ├── agents/                    # 智能体 CRUD
+│   ├── models/                    # 模型列表
+│   ├── settings/                  # 本地设置（LocalStorage 发布订阅）
+│   ├── uploads/                   # 文件上传
+│   ├── artifacts/                 # 制品管理
+│   ├── memory/                    # 用户记忆
+│   ├── skills/                    # 技能管理
+│   ├── scheduled-tasks/           # 定时任务
+│   ├── messages/                  # 消息处理工具函数
+│   ├── tasks/                     # 子任务 Context
+│   ├── notification/              # 系统通知
+│   └── utils/                     # 通用工具（文件下载、日期格式化等）
+└── hooks/                         # 全局自定义 hooks
+```
+
+---
+
+## 2. 路由结构
+
+> 项目使用 **HashRouter**，所有路由访问形如 `http://host/#/xxx`
+
+### 2.1 App.tsx 顶层路由
+
+| 路径 | 组件 | 说明 |
+|------|------|------|
+| `/` | Navigate | 重定向到 `/login` |
+| `/login` | LoginPage | 登录（自动登录，无表单） |
+| `/login/:username` | LoginPage | 带用户名登录 |
+| `/landing` | LandingPage | 营销落地页（固定 dark 主题） |
+| `/page/*` | PageRoutes | 应用内容根容器 |
+| `*` | NotFoundPage | 404 |
+
+### 2.2 PageRoutes.tsx（`/page/*`）
+
+```
+/page/
+├── index              → Navigate to "workspace"
+├── workspace/*        → WorkspaceRoutes
+└── [TODO 预留]        → 外部系统路由挂载位置
+```
+
+### 2.3 WorkspaceRoutes.tsx（`/page/workspace/*`）
+
+| 路径 | 页面组件 | 布局包裹 |
+|------|---------|--------|
+| `index` | Navigate → `chats/new` | - |
+| `chats` | ChatsPage | WorkspaceLayout |
+| `chats/:thread_id` | ChatPage | WorkspaceLayout + ChatRuntime |
+| `agents` | AgentsPage | WorkspaceLayout |
+| `agents/new` | NewAgentPage | WorkspaceLayout |
+| `agents/:agent_id/chats` | Navigate → `/page/workspace/agents` | - |
+| `agents/:agent_id/chats/:thread_id` | AgentChatPage | WorkspaceLayout + ChatRuntime |
+| `scheduled` | Navigate → `.../scheduled/tasks` | - |
+| `scheduled/tasks` | ScheduledTasksPage | WorkspaceLayout |
+| `scheduled/runs/:run_id` | ScheduledTaskRunDetailPage | WorkspaceLayout |
+
+### 2.4 布局 Provider 层级结构
+
+```
+WorkspaceLayout
+├── SidebarProvider（侧边栏展开/收起状态）
+│   ├── WorkspaceSidebar
+│   │   ├── WorkspaceHeader（Logo、新建按钮）
+│   │   ├── WorkspaceNavChatList（Chats / Agents / Scheduled 导航）
+│   │   ├── RecentChatList（最近会话列表）
+│   │   └── WorkspaceNavMenu（Settings / About / GitHub）
+│   ├── SidebarInset（主内容区）
+│   │   └── [Page Content]
+│   ├── CommandPalette（快捷命令面板）
+│   └── Toaster（全局通知）
+
+ChatRuntime（仅 ChatPage / AgentChatPage 使用）
+├── SubtasksProvider（子任务执行状态）
+├── ArtifactsProvider（制品选中/打开状态）
+└── PromptInputProvider（输入框内容/附件状态）
+```
+
+---
+
+## 3. 核心数据流与状态管理
+
+### 3.1 全局 Provider 架构
+
+```
+App
+└── HashRouter
+    └── AppProviders（useLocation 驱动主题判断）
+        ├── NextThemesProvider
+        │   └── attribute="class"，/landing 强制 forcedTheme="dark"
+        ├── I18nProvider
+        │   └── initialLocale = detectLocale()（从 cookie 或浏览器语言）
+        └── QueryClientProvider（TanStack React Query 全局缓存）
+```
+
+### 3.2 全局 Context 列表
+
+| Context | 文件 | 职责 | 消费 Hook |
+|---------|------|------|-----------|
+| `I18nContext` | `core/i18n/context.tsx` | 当前语言 + 翻译对象 | `useI18n()` |
+| `SubtaskContext` | `core/tasks/context.tsx` | 实时子任务执行状态 | `useSubtaskContext()` |
+| `ArtifactsContext` | `components/workspace/artifacts/context.tsx` | 制品选中/面板开关 | `useArtifacts()` |
+| `PromptInputContext` | `components/ai-elements/prompt-input/` | 输入框内容、附件列表 | `usePromptInputController()` |
+| `ThreadContext` | `components/workspace/messages/context.tsx` | 当前 thread 对象下传 | 直接读 context.thread |
+
+### 3.3 LocalStorage 数据
+
+**操作层：** `core/settings/store.ts`（发布-订阅，`useSyncExternalStore` 驱动响应式）
+
+| Key | 内容 |
+|-----|------|
+| `deerflow.auth` | `{ access_token, token_type, user_id, email }` |
+| `deerflow.local-settings` | `{ notification, context: { model_name, mode, reasoning_effort } }` |
+| `deerflow.thread-model.{threadId}` | 每条线程的模型覆盖 |
+
+### 3.4 SessionStorage 数据
+
+| Key | 内容 |
+|-----|------|
+| `deerflow.run-id.{threadId}` | WebSocket run_id，用于断线重连 |
+
+### 3.5 React Query 缓存 Key
+
+| Query Key | 数据 |
+|-----------|------|
+| `["threads"]` | 线程列表 |
+| `["thread", threadId]` | 单条线程 |
+| `["agents"]` | 智能体列表 |
+| `["models"]` | 模型列表 |
+| `["skills"]` | 技能列表 |
+| `["memory"]` | 用户记忆 |
+| `["scheduled-tasks"]` | 定时任务列表 |
+| `["scheduled-runs", taskId]` | 任务执行记录 |
+
+---
+
+## 4. 主要页面组件
+
+### 4.1 ChatPage.tsx — 单条对话页面
+
+**职责：** 管理单条聊天线程的完整交互，包括消息流、输入、工具调用展示、制品等。
+
+**关键状态：**
+
+```typescript
+const [threadId, setThreadId] = useState(routeThreadId || uuid());
+const [isNewThread, setIsNewThread] = useState(!routeThreadId || routeThreadId === "new");
+const [hasStartedConversation, setHasStartedConversation] = useState(false);
+const [showFollowups, setShowFollowups] = useState(false);
+const [settings, setSettings] = useThreadSettings(threadId);
+```
+
+**核心 Hook：**
+
+```typescript
+const [thread, sendMessage, isUploading] = useThreadStream({
+  threadId: isNewThread ? undefined : threadId,
+  context: settings.context,
+  onStart: (createdThreadId) => {
+    setThreadId(createdThreadId);
+    setIsNewThread(false);
+    // 不刷新页面，直接更新 URL hash
+    history.replaceState(null, "", `...#/page/workspace/chats/${createdThreadId}`);
+  },
+  onFinish: (state) => {
+    // 后台通知
+    showNotification(state.title, { body: lastMessageText });
+  }
+});
+```
+
+**主要子组件：**
+
+| 组件 | 职责 |
+|------|------|
+| `<MessageList>` | 消息渲染（含工具调用、子任务、制品） |
+| `<Welcome>` | 新对话欢迎屏 |
+| `<InputBox>` | 输入框（模式选择、附件、发送） |
+| `<ThreadTitle>` | 线程标题（自动生成后同步更新） |
+| `<ExportTrigger>` | 导出对话按钮 |
+| `<ArtifactTrigger>` | 制品面板开关 |
+| `<TokenUsageIndicator>` | Token 用量展示（可选） |
+| `<TodoList>` | 任务清单 |
+| `<Suggestions>` | 追问建议 |
+
+**数据流：**
+
+```
+用户输入 (InputBox)
+  ↓ handleSubmit(message: PromptInputMessage)
+  ↓ sendMessage(threadId, message)
+  ↓ [内部] 上传文件 → 提交到 LangGraph API
+  ↓ WebSocket 流返回消息
+  ↓ thread.messages 更新 → MessageList 重渲染
+```
+
+---
+
+### 4.2 AgentChatPage.tsx — 与智能体对话
+
+与 ChatPage 结构基本一致，差异点：
+
+- 从路由获取 `agent_id`，传入 `useThreadStream({ assistantId: agent_id })`
+- Header 展示智能体名称 Badge
+- "新建对话"跳转到 `/page/workspace/agents/${agent_id}/chats/new`
+- URL 更新为 `#/page/workspace/agents/${agent_id}/chats/${threadId}`
+
+---
+
+### 4.3 NewAgentPage.tsx — 创建智能体（两步流程）
+
+**Step 1：name（命名 + 选技能）**
+
+```typescript
+// 自动预选前 3 个启用的技能
+useEffect(() => {
+  if (!isSkillSelectionTouched) {
+    setSelectedSkills(enabledSkills.slice(0, 3).map(s => s.name));
+  }
+}, [enabledSkills]);
+
+// 提交：验证名称 → 创建智能体
+await checkAgentName(name);   // 检查重名
+await createAgent(request);   // 创建，返回 agent.id
+setStep("chat");              // 进入 Step 2
+```
+
+**Step 2：chat（初始化对话）**
+
+```typescript
+// 发送 bootstrap 消息触发智能体初始化
+sendMessage(threadId, bootstrapMessage, { agent_id: agentId });
+
+// 监听 setup_agent 工具完成事件
+onToolEnd: (event) => {
+  if (event.name === "setup_agent") {
+    // 带重试轮询加载 agent 最新信息
+    retryLoadAgent(agentId);
+  }
+}
+```
+
+---
+
+### 4.4 ChatsPage.tsx — 对话列表
+
+```typescript
+const { data: threads } = useThreads({ limit: 50, sortBy: "updated_at" });
+
+// 客户端过滤：排除定时任务线程 + 搜索关键词
+const filteredThreads = useMemo(() =>
+  threads?.filter(t =>
+    t.metadata?.thread_type !== "scheduler" &&
+    titleOfThread(t).toLowerCase().includes(search)
+  ), [threads, search]
+);
+```
+
+---
+
+### 4.5 LoginPage.tsx — 登录
+
+```typescript
+// 自动登录，无需用户操作
+useEffect(() => {
+  loginByUsername(username || "guest")
+    .then(auth => {
+      setStoredAuth(auth);
+      router.replace("/page/workspace/chats/new");
+    })
+    .catch(err => setStatus("error"));
+}, [username]);
+```
+
+---
+
+### 4.6 ScheduledTasksPage.tsx — 定时任务
+
+**功能：** 创建/编辑/发布/暂停/恢复定时任务，查看执行历史。
+
+**Cron 表达式构建：**
+
+```typescript
+type ScheduleFreq = "hourly" | "daily" | "weekly" | "monthly";
+
+function buildCron(config): string {
+  // hourly  → "15 * * * *"
+  // daily   → "0 9 * * *"
+  // weekly  → "0 9 * * 1"
+  // monthly → "0 9 1 * *"
+}
+```
+
+**核心操作：**
+
+```typescript
+const actions = useScheduledTaskActions();
+actions.create.mutateAsync(payload);
+actions.publish.mutateAsync(taskId);
+actions.pause.mutateAsync(taskId);
+actions.trigger.mutateAsync(taskId);   // 立即执行一次
+actions.subscribe.mutateAsync(params); // 订阅推送
+```
+
+---
+
+## 5. 核心业务组件
+
+### 5.1 消息系统（`components/workspace/messages/`）
+
+| 文件 | 职责 |
+|------|------|
+| `message-list.tsx` | 消息列表容器，调用 `groupMessages` 分组后渲染 |
+| `message-list-item.tsx` | 单条消息渲染（含 role 判断） |
+| `message-group.tsx` | 消息组（human / assistant / processing 等） |
+| `markdown-content.tsx` | Markdown 渲染（rehype 系列插件） |
+| `subtask-card.tsx` | 子任务状态卡片 |
+| `message-token-usage.tsx` | 单条消息 Token 用量 |
+| `skeleton.tsx` | 流式加载骨架屏 |
+| `context.tsx` | ThreadContext，向下传递 thread 对象 |
+
+**消息分组类型（`groupMessages`）：**
+
+```typescript
+type MessageGroup =
+  | "human"                    // 用户输入
+  | "assistant:processing"     // 推理/工具调用中
+  | "assistant"                // 最终响应
+  | "assistant:clarification"  // 澄清请求
+  | "assistant:present-files"  // 文件呈现
+  | "assistant:subagent";      // 子智能体消息
+```
+
+---
+
+### 5.2 输入框（`components/workspace/input-box.tsx`）
+
+**子组件层级：**
+
+```
+InputBox
+└── PromptInput（Context Provider）
+    ├── PromptInputBody
+    │   ├── PromptInputTextarea（文本输入）
+    │   ├── PromptInputAttachments（附件列表）
+    │   └── PromptInputTools（工具栏：附件上传、模式选择）
+    ├── PromptInputFooter
+    │   ├── PromptInputSubmit（发送/停止按钮）
+    │   └── Suggestions（追问建议列表）
+    └── ModelSelector（模型下拉选择）
+```
+
+**四种会话模式：**
+
+| Mode | 说明 |
+|------|------|
+| `flash` | 快速模式，无推理步骤 |
+| `thinking` | 推理模式，开启深度思考 |
+| `pro` | 专业模式，多模态 + 规划 |
+| `ultra` | 超级模式，启用子智能体 |
+
+**推理努力等级（mode ≠ flash 时可选）：** `minimal` / `low` / `medium` / `high`
+
+---
+
+### 5.3 侧边栏（`components/workspace/workspace-sidebar.tsx`）
+
+```
+WorkspaceSidebar
+├── SidebarHeader → WorkspaceHeader
+│   ├── Logo（可点击，跳转 /page/workspace/chats/new）
+│   └── 新建对话按钮
+├── SidebarContent
+│   ├── WorkspaceNavChatList
+│   │   ├── 新建对话（/page/workspace/chats/new）
+│   │   ├── 所有对话（/page/workspace/chats）
+│   │   ├── 智能体（/page/workspace/agents）
+│   │   └── 任务管理（/page/workspace/scheduled/tasks）
+│   └── RecentChatList（最近会话，含搜索）
+└── SidebarFooter → WorkspaceNavMenu
+    ├── Settings（打开设置 Dialog）
+    ├── About
+    └── GitHub
+```
+
+---
+
+### 5.4 制品管理（`components/workspace/artifacts/`）
+
+```typescript
+interface ArtifactsContextType {
+  artifacts: string[];             // artifact ID 列表
+  selectedArtifact: string | null;
+  autoSelect: boolean;             // 是否自动选中最新制品
+  open: boolean;                   // 面板是否展开
+  autoOpen: boolean;
+  select(artifact: string, autoSelect?: boolean): void;
+  deselect(): void;
+  setOpen(open: boolean): void;
+}
+```
+
+**文件：**
+
+| 文件 | 职责 |
+|------|------|
+| `context.tsx` | ArtifactsContext + Provider |
+| `artifact-trigger.tsx` | 面板展开/收起按钮 |
+| `artifact-file-list.tsx` | 制品文件列表 |
+| `artifact-file-detail.tsx` | 单个制品详情（含代码编辑器） |
+
+---
+
+### 5.5 设置面板（`components/workspace/settings/`）
+
+| 页面文件 | 内容 |
+|---------|------|
+| `appearance-settings-page.tsx` | 主题切换（light/dark/system）、语言切换 |
+| `memory-settings-page.tsx` | 用户记忆（事实列表、总结管理） |
+| `notification-settings-page.tsx` | 桌面通知开关 |
+| `skill-settings-page.tsx` | 技能启用/禁用 |
+| `tool-settings-page.tsx` | 工具配置 |
+| `about-settings-page.tsx` | 版本号、仓库链接 |
+
+---
+
+### 5.6 命令面板（`components/workspace/command-palette.tsx`）
+
+通过 `Cmd/Ctrl + K` 触发，提供快速导航和操作入口。
+
+```typescript
+const handleNewChat = useCallback(() => {
+  router.push("/page/workspace/chats/new");
+  setOpen(false);
+}, [router]);
+```
+
+---
+
+## 6. 核心 Hooks 与工具函数
+
+### 6.1 useThreadStream（最核心 Hook）
+
+**位置：** `core/threads/hooks.ts`
+
+管理 LangGraph WebSocket 连接、消息流、乐观更新。
+
+**签名：**
+
+```typescript
+const [thread, sendMessage, isUploading] = useThreadStream({
+  threadId?: string,               // 有值则连接现有线程，无值表示新建
+  context: LocalSettings["context"], // 模型、模式等
+  isMock?: boolean,
+  assistantId?: string,            // 默认 "lead_agent"
+  onStart?: (threadId: string) => void,
+  onFinish?: (state: AgentThreadState) => void,
+  onToolEnd?: (event: ToolEndEvent) => void,
+});
+```
+
+**thread 对象关键属性：**
+
+```typescript
+thread: {
+  messages: Message[],      // 含乐观消息的完整列表
+  isLoading: boolean,       // 流是否进行中
+  isThreadLoading: boolean, // 初始线程数据是否加载中
+  values: AgentThreadState, // 线程最终状态
+  error?: Error,
+  stop: async () => void,   // 终止当前流
+}
+```
+
+**sendMessage 签名：**
+
+```typescript
+sendMessage(
+  threadId: string | undefined,
+  message: PromptInputMessage,
+  extraContext?: Partial<AgentThreadContext>,
+  options?: { isMock?: boolean }
+): Promise<void>
+```
+
+**内部机制：**
+- **乐观更新：** 用户发送后立即本地展示消息，不等服务端响应
+- **文件上传：** 自动调用 `uploadFiles()` 后再提交
+- **run_id 持久化：** sessionStorage 保存，支持页面刷新后断线重连
+- **消息同步：** 流结束后通过 `queryClient.invalidateQueries(["threads"])` 刷新列表
+
+---
+
+### 6.2 useThreadSettings
+
+**位置：** `core/settings/hooks.ts`
+
+```typescript
+const [settings, setSettings] = useThreadSettings(threadId);
+
+// settings 结构
+{
+  notification: { enabled: boolean },
+  context: {
+    model_name?: string,
+    mode: "flash" | "thinking" | "pro" | "ultra",
+    reasoning_effort?: "minimal" | "low" | "medium" | "high"
+  }
+}
+
+// 修改（合并更新）
+setSettings("context", { mode: "pro" });
+setSettings("notification", { enabled: true });
+```
+
+**工作原理：** `useSyncExternalStore` 监听 localStorage 变化，跨标签页同步。
+
+---
+
+### 6.3 useI18n
+
+**位置：** `core/i18n/hooks.ts`
+
+```typescript
+const { t, locale, changeLocale } = useI18n();
+
+t.sidebar.newChat          // "New Chat"
+t.agents.createPageTitle   // "Create Agent"
+t.toolCalls.moreSteps(3)   // "Show 3 more steps"
+
+changeLocale("zh-CN");     // 切换语言，自动存 cookie
+```
+
+---
+
+### 6.4 useScheduledTaskActions
+
+**位置：** `core/scheduled-tasks/hooks.ts`
+
+```typescript
+const actions = useScheduledTaskActions();
+
+// 所有返回值均为 TanStack Query Mutation
+actions.create           // 创建定时任务
+actions.update           // 更新任务配置
+actions.remove           // 删除任务
+actions.removeRun        // 删除执行记录
+actions.pause            // 暂停
+actions.resume           // 恢复
+actions.trigger          // 立即触发一次
+actions.publish          // 发布（激活）
+actions.unpublish        // 取消发布
+actions.subscribe        // 订阅推送
+actions.updateSubscription
+actions.unsubscribe
+```
+
+---
+
+### 6.5 工具函数
+
+**消息处理（`core/messages/utils.ts`）：**
+
+```typescript
+groupMessages(messages, mapper)            // 按类型分组消息列表
+extractTextFromMessage(message)            // 提取纯文本
+extractContentFromMessage(message)         // 提取 Markdown/图像内容
+extractReasoningContentFromMessage(msg)    // 提取推理过程
+hasToolCalls(message)                      // 是否含工具调用
+hasPresentFiles(message)                   // 是否包含文件呈现
+extractPresentFilesFromMessage(message)    // 获取文件列表
+isClarificationToolMessage(message)        // 是否为澄清请求
+```
+
+**线程路由（`core/threads/utils.ts`）：**
+
+```typescript
+pathOfThread(thread, context?)
+// → "/page/workspace/agents/{agentRef}/chats/{threadId}"
+// 或 "/page/workspace/chats/{threadId}"
+
+titleOfThread(thread)
+// → thread.values?.title ?? "Untitled"
+
+textOfMessage(message)
+// → 消息文本内容（string 或 content 数组中第一个 text）
+```
+
+**其他工具：**
+
+```typescript
+// core/utils/files.tsx
+downloadFile(blob: Blob, filename: string)
+
+// core/utils/datetime.ts
+formatTimeAgo(dateString: string)  // → "2 小时前" / "3 days ago"
+```
+
+---
+
+## 7. API 调用层
+
+### 7.1 API 客户端架构
+
+**两层设计：**
+
+**第一层：LangGraph SDK Client**（`core/api/api-client.ts`）
+
+```typescript
+const client = new LangGraphClient({
+  apiUrl: getLangGraphBaseURL(isMock),
+  onRequest(url, init) {
+    const headers = new Headers(init.headers ?? {});
+    headers.set("Authorization", getAuthorizationHeaderValue());
+    return { ...init, headers };
+  }
+});
+
+export function getAPIClient(isMock?: boolean): LangGraphClient
+```
+
+**第二层：Fetch Client**（`core/api/fetch-client.ts`）
+
+```typescript
+function apiFetch(input: RequestInfo, init?: RequestInit): Promise<Response> {
+  return fetch(input, {
+    ...init,
+    headers: withAuthHeaders(init?.headers)
+  });
+}
+```
+
+### 7.2 主要 API 模块
+
+| 模块 | 文件 | 关键函数 |
+|------|------|---------|
+| **Auth** | `core/auth/api.ts` | `loginByUsername(username)` → `LoginByUsernameResponse` |
+| **Agents** | `core/agents/api.ts` | `createAgent()`, `updateAgent()`, `listAgents()`, `deleteAgent()`, `checkAgentName()` |
+| **Models** | `core/models/api.ts` | `loadModels()` → `Model[]` |
+| **Threads** | (via LangGraph SDK) | `useThreadStream()`, `useThreads()`, `useDeleteThread()`, `useRenameThread()` |
+| **Skills** | `core/skills/api.ts` | `loadSkills()`, `enableSkill(name, enabled)` |
+| **Uploads** | `core/uploads/api.ts` | `uploadFiles(threadId, files[])`, `listUploadedFiles()`, `deleteUploadedFile()` |
+| **Memory** | `core/memory/api.ts` | `loadMemory()`, `createMemoryFact()`, `updateMemoryFact()`, `deleteMemoryFact()` |
+| **Scheduled Tasks** | `core/scheduled-tasks/api.ts` | CRUD、publish、pause、resume、trigger、subscribe |
+
+### 7.3 Base URL 配置
+
+**文件：** `core/config/index.ts`
+
+```typescript
+export function getBackendBaseURL(): string {
+  // env.NEXT_PUBLIC_BACKEND_BASE_URL
+  // 默认：""（当前域名根路径）
+}
+
+export function getLangGraphBaseURL(isMock?: boolean): string {
+  // mock 模式：${origin}/mock/api
+  // 正常：${origin}/api/langgraph
+  // 或读取 env.NEXT_PUBLIC_LANGGRAPH_BASE_URL
+}
+```
+
+### 7.4 认证流程
+
+```
+LoginPage 调用 loginByUsername(username)
+  ↓ POST /api/auth/login
+  ↓ 返回 { access_token, token_type, user_id, email }
+  ↓ setStoredAuth() 存入 localStorage["deerflow.auth"]
+  ↓
+后续所有 API 请求
+  ↓ getAuthorizationHeaderValue()
+  ↓ → "Bearer {access_token}"
+  ↓ 自动添加到 Authorization header
+```
+
+---
+
+## 8. 国际化机制
+
+### 8.1 文件结构
+
+```
+core/i18n/
+├── context.tsx          # I18nProvider（包裹 App）
+├── hooks.ts             # useI18n()
+├── locale.ts            # detectLocale()，Locale = "en-US" | "zh-CN"
+├── cookies.ts           # cookie 读写（持久化语言选择）
+├── translations.ts      # 翻译映射表入口
+└── locales/
+    ├── types.ts         # Translations 接口定义（所有翻译 key 的类型）
+    ├── en-US.ts         # 英文翻译
+    └── zh-CN.ts         # 简体中文翻译
+```
+
+### 8.2 Translations 接口分类
+
+```typescript
+interface Translations {
+  locale: { localName: string }         // 语言自身名称
+  common: { ... }                       // 通用词汇（确认、取消等）
+  welcome: { ... }                      // 欢迎屏
+  inputBox: { ... }                     // 输入框（模式、占位符）
+  sidebar: { ... }                      // 侧边栏导航
+  agents: { ... }                       // 智能体相关
+  chats: { ... }                        // 对话相关
+  workspace: { ... }                    // 工作区通用
+  settings: { ... }                     // 设置面板
+  toolCalls: { ... }                    // 工具调用展示
+  uploads: { ... }                      // 文件上传
+  subtasks: { ... }                     // 子任务
+  tokenUsage: { ... }                   // Token 用量
+  shortcuts: { ... }                    // 快捷键说明
+}
+```
+
+### 8.3 语言检测优先级
+
+1. 读取 cookie `deerflow.locale`
+2. 读取浏览器 `navigator.language`
+3. 回退到 `en-US`
+
+---
+
+## 9. 主题与样式体系
+
+### 9.1 主题系统
+
+**库：** `next-themes`
+
+```typescript
+// App.tsx
+<NextThemesProvider
+  attribute="class"           // 通过 <html class="dark"> 应用主题
+  enableSystem               // 跟随系统偏好
+  disableTransitionOnChange  // 切换时禁用过渡动画
+  forcedTheme={pathname === "/landing" ? "dark" : undefined}
+>
+```
+
+**可选主题值：** `light` / `dark` / `system`
+
+### 9.2 样式方案
+
+**基础：** Tailwind CSS
+
+**组件库：** shadcn/ui（`components/ui/` 目录，40+ 基础组件）
+
+**主要 CSS 自定义属性：**
+
+```css
+--container-width-sm    /* 小容器宽度 */
+--container-width-md    /* 中等容器宽度（对话主区域） */
+--primary               /* 主色 */
+--background            /* 页面背景 */
+--foreground            /* 主文本色 */
+--muted-foreground      /* 次要文本色 */
+--border                /* 边框色 */
+--sidebar-foreground    /* 侧边栏文本 */
+```
+
+### 9.3 样式使用规范
+
+- 工具类优先（Tailwind）
+- 动态样式用 `cn()` 工具函数合并（基于 `clsx` + `tailwind-merge`）
+- 主题感知样式使用 CSS 变量（如 `text-muted-foreground`）
+
+---
+
+## 10. 关键业务流程
+
+### 10.1 新建对话流程
+
+```
+1. 点击"新建对话" → navigate("/page/workspace/chats/new")
+2. ChatPage 挂载，threadId = uuid()，isNewThread = true
+3. 用户输入消息，点击发送
+4. sendMessage(undefined, message) 调用
+5. useThreadStream 内部：
+   a. 上传文件（若有）
+   b. 创建 LangGraph 线程，后端返回 threadId
+   c. onStart(threadId) 回调：
+      - setIsNewThread(false)
+      - history.replaceState 更新 URL hash
+6. WebSocket 流开始接收 AI 消息
+7. MessageList 实时渲染消息
+8. 流结束，onFinish 回调，可能触发桌面通知
+```
+
+### 10.2 创建智能体流程
+
+```
+Step 1（name 步骤）
+  ↓ 用户输入名称
+  ↓ checkAgentName(name) → 验证是否重名
+  ↓ createAgent({ name, skills: selectedSkills })
+  ↓ 后端返回 agent.id，setStep("chat")
+
+Step 2（chat 步骤）
+  ↓ 生成临时 threadId
+  ↓ useThreadStream({ assistantId: agent.id })
+  ↓ 发送 bootstrap 消息（触发智能体自我设置）
+  ↓ onToolEnd 监听：event.name === "setup_agent"
+  ↓ 指数退避重试加载 agent 信息，确认已保存
+  ↓ 显示"Agent Created"完成界面
+  ↓ 用户可点击"开始对话"或"返回列表"
+```
+
+### 10.3 文件上传流程
+
+```
+1. 用户在 InputBox 选择/粘贴文件
+2. PromptInputAttachments 展示预览列表
+3. 用户点击发送
+4. sendMessage 内部调用 uploadFiles(threadId, files)
+5. POST /api/threads/{threadId}/upload
+6. 后端返回 { files: [{ filename, size, virtual_path }] }
+7. 构建 Message additional_kwargs.files
+8. 完整 Message 提交到 LangGraph
+```
+
+---
+
+## 11. 项目配置与依赖
+
+### 11.1 主要依赖
+
+| 包 | 版本 | 用途 |
+|----|------|------|
+| `react` | ^18 | 核心框架 |
+| `react-router-dom` | ^6 | 客户端路由（HashRouter） |
+| `@tanstack/react-query` | - | 服务端状态缓存 |
+| `@langchain/langgraph-sdk` | - | LangGraph WebSocket 连接 |
+| `next-themes` | - | 主题管理 |
+| `sonner` | - | Toast 通知 |
+| `lucide-react` | - | 图标库 |
+| `tailwindcss` | - | CSS 框架 |
+| `rehype` 系列 | - | Markdown 渲染 |
+| `uuid` | - | 生成临时 thread ID |
+
+### 11.2 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `NEXT_PUBLIC_BACKEND_BASE_URL` | 后端接口基础 URL | `""` (当前域名) |
+| `NEXT_PUBLIC_LANGGRAPH_BASE_URL` | LangGraph API URL | `/api/langgraph` |
+| `NEXT_PUBLIC_STATIC_WEBSITE_ONLY` | 纯静态演示模式 | `"false"` |
+
+---
+
+## 12. 常见开发模式
+
+### 12.1 添加新工作区页面
+
+```
+1. 创建 src/pages/MyPage.tsx
+2. 在 WorkspaceRoutes.tsx 中添加路由：
+   <Route path="my-page" element={<WorkspaceLayout><MyPage /></WorkspaceLayout>} />
+3. 在 workspace-nav-chat-list.tsx 中添加导航入口（如需要）
+4. 更新相关的跳转路径
+```
+
+### 12.2 添加新 API 接口
+
+```
+1. 在 core/xxx/api.ts 中定义 API 函数（使用 apiFetch 或 getAPIClient()）
+2. 在 core/xxx/hooks.ts 中封装 useQuery / useMutation
+3. 在页面或组件中调用 hook
+```
+
+### 12.3 添加新 Context
+
+```
+1. 创建 core/xxx/context.tsx：定义 Context + Provider + 默认值
+2. 创建消费 hook（如 useXxx()）
+3. 在合适的组件树根部插入 Provider（WorkspaceRoutes 或 ChatRuntime）
+```
+
+### 12.4 添加国际化文本
+
+```
+1. 在 core/i18n/locales/types.ts 的 Translations 接口中添加字段
+2. 在 core/i18n/locales/en-US.ts 添加英文内容
+3. 在 core/i18n/locales/zh-CN.ts 添加中文内容
+4. 组件中通过 useI18n() 访问：const { t } = useI18n(); t.xxx.yyy
+```
+
+### 12.5 引入外部系统路由
+
+在 `src/pages/PageRoutes.tsx` 中找到 TODO 注释位置，填入：
+
+```typescript
+import AnotherSystemRoutes from "外部系统路径";
+
+// 在 Routes 中添加：
+<Route path="other/*" element={<AnotherSystemRoutes />} />
+```
+
+如外部系统有独立 Provider 依赖，在此文件或 App.tsx 中包裹。
+
+---
+
+## 附：关键文件速查
+
+| 需求 | 关键文件 |
+|------|---------|
+| 修改路由结构 | `App.tsx`, `PageRoutes.tsx`, `WorkspaceRoutes.tsx` |
+| 修改侧边栏导航 | `components/workspace/workspace-nav-chat-list.tsx` |
+| 修改对话逻辑 | `pages/ChatPage.tsx`, `core/threads/hooks.ts` |
+| 修改输入框 | `components/workspace/input-box.tsx`, `components/ai-elements/prompt-input/` |
+| 修改消息渲染 | `components/workspace/messages/` |
+| 添加 API 接口 | `core/xxx/api.ts` + `core/xxx/hooks.ts` |
+| 修改全局设置 | `core/settings/store.ts`, `core/settings/hooks.ts` |
+| 修改翻译文本 | `core/i18n/locales/en-US.ts`, `core/i18n/locales/zh-CN.ts` |
+| 修改主题 | `App.tsx` (NextThemesProvider) |
+| 修改认证逻辑 | `core/auth/api.ts`, `pages/LoginPage.tsx` |
+| 定时任务 | `pages/ScheduledTasksPage.tsx`, `core/scheduled-tasks/` |
+| 智能体管理 | `pages/NewAgentPage.tsx`, `core/agents/` |

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-frontend-dev.md

@@ -0,0 +1,778 @@
+# 多智能体圆桌研讨 · 前端开发文档
+
+本文档面向维护 `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}`；以 JSON 整存进后端 `step1`/`step2`（`PortableLongText`/LONGTEXT，避免大对话超 64KB）。
+  - **`selectedAgents`（2026-06 修复）**：本次研讨实际选中的席位。**不存的话加载草稿后 Step 2/3 左侧「参与角色」会回退到 `DEFAULT_SELECTED_AGENTS`（默认 6 个）而非当时真正选的那几个** —— `roleTemplates`/`agentNameToRole` 都由 `selectedAgents` 派生。`useStep2Orchestration.hydrateFromDraft` 在该字段非空时 `setSelectedAgents`，老草稿（无此字段）保持当前值不强行覆盖。
+- `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`
+
+- **新增 `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/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

@@ -0,0 +1,109 @@
+# AI 智能写作 — 手工测试清单
+
+> 测试环境：后端 `http://localhost:8001`，前端 `http://localhost:5174`
+> 每项测试前确认后端已启动（`make dev`）、前端已启动（`pnpm dev`）
+
+---
+
+## T1 — 启动写作任务
+
+| # | 步骤 | 预期结果 |
+|---|------|----------|
+| 1.1 | 打开 Canvas 页面，点击右上角「AI 写作」按钮 | AIWritingPanel 在右侧展开，显示写作配置表单 |
+| 1.2 | 填写：意图「新能源汽车市场趋势分析」，类型「分析报告」，目标读者「行业研究人员」，字数「1200」 | 表单验证通过，提交按钮可点击 |
+| 1.3 | 点击「开始写作」 | 按钮变为 loading 状态；时间轴出现第一条「素材收集专家 · 开始检索素材」进度条目 |
+| 1.4 | 意图字段留空后点击提交 | 表单校验阻止提交，提示「请填写写作意图」 |
+
+---
+
+## T2 — SSE 进度流（时间轴）
+
+| # | 步骤 | 预期结果 |
+|---|------|----------|
+| 2.1 | 任务启动后观察时间轴 | 每隔几秒新增进度条目，agent_name 标签分别出现「素材收集专家」「作家」「编辑」 |
+| 2.2 | 打开浏览器 DevTools → Network，过滤 `stream` | 看到一个 `text/event-stream` 请求长连接，持续收到 `data:` 帧 |
+| 2.3 | 断网 5 秒后恢复 | 面板显示「连接中断」提示（或 error 事件），不崩溃 |
+
+---
+
+## T3 — PAUSE-1 素材确认
+
+| # | 步骤 | 预期结果 |
+|---|------|----------|
+| 3.1 | 等待素材收集专家完成检索，出现 PAUSE-1 干预卡 | 卡片标题「素材确认」，列出 ≥1 条素材，每条有复选框、标题、来源、相关度分数色条 |
+| 3.2 | 全选所有素材，点击「确认素材，继续写作」 | 干预卡禁用，时间轴新增「作家 · 开始规划大纲」 |
+| 3.3 | 重新发起任务，PAUSE-1 出现后取消勾选全部素材，点击「重新检索」 | 向后端发送 `action: re_search`；时间轴回到素材收集专家节点重新检索 |
+| 3.4 | PAUSE-1 出现后填写「追加关键词」输入框（如「锂电池」）并按 Enter，再点「追加搜索」 | 标签出现「锂电池」；后端收到 `action: append_search, extraKeywords: ["锂电池"]` |
+| 3.5 | 验证相关度色条颜色：分数 ≥0.8 绿色 / 0.5–0.8 橙色 / <0.5 红色 | 三种颜色均可在不同素材中观察到 |
+
+---
+
+## T4 — PAUSE-2 大纲确认
+
+| # | 步骤 | 预期结果 |
+|---|------|----------|
+| 4.1 | PAUSE-2 出现后检查大纲卡 | 显示文章标题 + ≥2 个章节，每节有节标题与要点列表 |
+| 4.2 | 点击文章标题，内联编辑改为「2025 新能源趋势报告」，按 Enter | 标题实时变更，不刷新页面 |
+| 4.3 | 展开某章节，点击一条要点，修改文字，按 Blur 失焦 | 要点文字更新 |
+| 4.4 | 点击「+ 新增章节」，填写章节标题 | 大纲末尾追加新章节 |
+| 4.5 | 点击「确认大纲，开始写作」 | 编辑后的大纲随 `action: confirm_outline` 提交；时间轴出现「作家 · 开始撰写草稿」 |
+| 4.6 | PAUSE-2 出现后点击「重新规划大纲」 | 显示意见输入框；填写「请增加政策分析章节」后提交；后端收到 `action: re_outline, outlineFeedback: ...` |
+
+---
+
+## T5 — PAUSE-3 草稿确认
+
+| # | 步骤 | 预期结果 |
+|---|------|----------|
+| 5.1 | 作家完成草稿，PAUSE-3 出现 | 干预卡显示修改次数（如「第 1 稿」）；右侧 Artifact 面板同步显示 Markdown 草稿内容 |
+| 5.2 | 点击「定稿，提交编辑审核」 | 进入编辑节点；时间轴出现「编辑 · 开始审核」 |
+| 5.3 | 点击「提出修改意见」，填写意见后提交 | 作家节点重新生成草稿；修改次数 +1 |
+| 5.4 | 连续打回 3 次，观察第 4 次 PAUSE-3 | revisionCount 正确递增显示 |
+
+---
+
+## T6 — PAUSE-4 审核结果确认
+
+| # | 步骤 | 预期结果 |
+|---|------|----------|
+| 6.1 | 编辑审核完成，PAUSE-4 出现 | ReviewCard 显示：综合得分、事实/逻辑/语言三项分数、及格线（默认 75）、verdict 徽章（通过=绿 / 打回=红）|
+| 6.2 | verdict=pass 时，点击「接受审核，定稿」 | 流程结束；时间轴出现「完成」；右侧面板保留最终草稿 |
+| 6.3 | verdict=reject 时，查看问题列表 | major 问题排在 minor 前；每条显示类别徽章、位置、问题描述、建议 |
+| 6.4 | verdict=reject 时，点击「强制定稿」 | 向后端发送 `action: force_finalize`；流程结束 |
+| 6.5 | 添加「额外说明」文字后点击「接受审核，定稿」 | extra_notes 包含在提交的 intervention payload 中（DevTools → Network 验证） |
+
+---
+
+## T7 — 错误与边界场景
+
+| # | 步骤 | 预期结果 |
+|---|------|----------|
+| 7.1 | 后端未启动时点击「开始写作」 | 面板显示错误提示「无法连接到服务器」，不白屏 |
+| 7.2 | 写作进行中点击「停止/重置」 | 时间轴清空，表单恢复可编辑，后端流被中断（Network 连接关闭）|
+| 7.3 | 素材列表为空（后端返回 0 条）时 PAUSE-1 | 干预卡显示「暂无素材」提示，「确认」按钮仍可点击 |
+| 7.4 | 大纲只有 1 个章节时，点击删除该章节 | 删除按钮禁用或弹出「至少保留一个章节」提示 |
+| 7.5 | 弱模型返回格式错误的 JSON（手动 mock 后端） | 前端收到 fallback 结构，不崩溃；时间轴正常继续 |
+
+---
+
+## T8 — 跨阶段状态一致性
+
+| # | 步骤 | 预期结果 |
+|---|------|----------|
+| 8.1 | PAUSE-2 时展开大纲卡，刷新页面（F5） | 页面恢复；如写作任务 ID 持久化，状态可恢复（否则回到初始状态，均可接受）|
+| 8.2 | 同时打开两个浏览器标签，各自启动独立写作任务 | 两个任务互不干扰，各自有独立 task_id |
+| 8.3 | 完整跑通一次全流程（T1→T2→T3→T4→T5→T6 pass） | 右侧 Artifact 面板显示完整定稿文章，时间轴所有节点状态为「完成」 |
+
+---
+
+## 后端单元测试（补充确认）
+
+```bash
+# 在 offline-backend-20260512/backend/ 下运行
+PYTHONPATH=. uv run pytest tests/test_ai_writing_json_parse.py -v   # 16 tests
+PYTHONPATH=. uv run pytest tests/test_ai_writing_graph.py -v        # 19 tests
+```
+
+两个测试文件均应全部通过（0 failed）。
+
+npm install @tiptap/core @tiptap/starter-kit @tiptap/extension-underline @tiptap/extension-placeholder

frontend-web/index.html

@@ -1,9 +1,20 @@
 <!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>DeerFlow Vite</title>
+    <title>CM 助手</title>
   </head>
   <body>
     <div id="root"></div>

frontend-web/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
+    "build": "node --max-old-space-size=8192 ./node_modules/vite/bin/vite.js build",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit"
   },
@@ -37,6 +37,13 @@
     "@radix-ui/react-tooltip": "^1.2.8",
     "@radix-ui/react-use-controllable-state": "^1.2.2",
     "@tanstack/react-query": "^5.90.17",
+    "@tiptap/core": "^3.23.4",
+    "@tiptap/extension-bubble-menu": "^3.23.4",
+    "@tiptap/extension-placeholder": "^3.23.4",
+    "@tiptap/extension-underline": "^3.23.4",
+    "@tiptap/pm": "^3.23.4",
+    "@tiptap/react": "^3.23.4",
+    "@tiptap/starter-kit": "^3.23.4",
     "@types/hast": "^3.0.4",
     "@uiw/codemirror-theme-basic": "^4.25.4",
     "@uiw/codemirror-theme-monokai": "^4.25.4",
@@ -50,8 +57,11 @@
     "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",
+    "file-saver": "^2.0.5",
     "gsap": "^3.13.0",
     "hast": "^1.0.0",
     "katex": "^0.16.28",
@@ -62,8 +72,10 @@
     "ogl": "^1.0.11",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "react-markdown": "^10.1.0",
     "react-resizable-panels": "^4.4.1",
     "react-router-dom": "^7.9.4",
+    "react-syntax-highlighter": "^16.1.1",
     "rehype-katex": "^7.0.1",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.1",
@@ -72,6 +84,8 @@
     "sonner": "^2.0.7",
     "streamdown": "1.4.0",
     "tailwind-merge": "^3.4.0",
+    "tdesign-react": "^1.12.3",
+    "tiptap-markdown": "^0.9.0",
     "tokenlens": "^1.3.1",
     "unist-util-visit": "^5.0.0",
     "use-stick-to-bottom": "^1.1.1",
@@ -80,6 +94,7 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.0.15",
+    "@types/file-saver": "^2.0.7",
     "@types/gsap": "^3.0.0",
     "@types/node": "^20.14.10",
     "@types/react": "^19.0.0",
@@ -89,7 +104,8 @@
     "tailwindcss": "^4.0.15",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.8.2",
-    "vite": "^6.0.0"
+    "vite": "^6.0.0",
+    "vite-plugin-source-identifier": "^1.1.2"
   },
   "packageManager": "pnpm@10.26.2"
 }

frontend-web/src/App.tsx

@@ -3,69 +3,51 @@ import { Navigate, Route, Routes } from "react-router-dom";
 import { ThemeProvider as NextThemesProvider } from "next-themes";
 
 import { QueryClientProvider } from "@/components/query-client-provider";
-import { SidebarInset, SidebarProvider } from "@/components/ui/sidebar";
-import { PromptInputProvider } from "@/components/ai-elements/prompt-input";
-import { WorkspaceSidebar } from "@/components/workspace/workspace-sidebar";
-import { CommandPalette } from "@/components/workspace/command-palette";
-import { Toaster } from "sonner";
+import { AuthSyncWatcher } from "@/core/auth/sync";
 import { I18nProvider } from "@/core/i18n/context";
 import { detectLocale } from "@/core/i18n/locale";
-import { SubtasksProvider } from "@/core/tasks/context";
-import { ArtifactsProvider } from "@/components/workspace/artifacts";
+import { ChatProvider } from "@/contexts/ChatContext";
+import { ThemeProvider } from "@/contexts/ThemeContext";
 
 import { HashRouter, useLocation } from "react-router-dom";
 
 import LandingPage from "./pages/LandingPage";
-import ChatsPage from "./pages/ChatsPage";
-import ChatPage from "./pages/ChatPage";
-import AgentsPage from "./pages/AgentsPage";
-import AgentChatPage from "./pages/AgentChatPage";
-import NewAgentPage from "./pages/NewAgentPage";
 import LoginPage from "./pages/LoginPage";
-import ScheduledTaskRunDetailPage from "./pages/ScheduledTaskRunDetailPage";
-import ScheduledTasksPage from "./pages/ScheduledTasksPage";
+import PageRoutes from "./pages/PageRoutes";
+import PublicScheduledTaskPage from "./pages/PublicScheduledTaskPage";
+import PublicSharePage from "./pages/PublicSharePage";
 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}
     >
+      {/* QueryClientProvider must wrap ThemeProvider because the custom
+          ThemeProvider reads the admin-configured default via useQuery. */}
+      <QueryClientProvider>
         <I18nProvider initialLocale={locale}>
-        <QueryClientProvider>{children}</QueryClientProvider>
+          <ThemeProvider>
+            <ChatProvider>
+              <AuthSyncWatcher />
+              {children}
+            </ChatProvider>
+          </ThemeProvider>
         </I18nProvider>
+      </QueryClientProvider>
     </NextThemesProvider>
   );
 }
 
-function WorkspaceLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <SidebarProvider className="h-screen" defaultOpen>
-      <WorkspaceSidebar />
-      <SidebarInset className="min-w-0">{children}</SidebarInset>
-      <CommandPalette />
-      <Toaster position="top-center" />
-    </SidebarProvider>
-  );
-}
-
-function ChatRuntime({ children }: { children: React.ReactNode }) {
-  return (
-    <SubtasksProvider>
-      <ArtifactsProvider>
-        <PromptInputProvider>{children}</PromptInputProvider>
-      </ArtifactsProvider>
-    </SubtasksProvider>
-  );
-}
-
 export function App() {
   return (
     <HashRouter>
@@ -75,78 +57,14 @@ export function App() {
           <Route path="/login" element={<LoginPage />} />
           <Route path="/login/:username" element={<LoginPage />} />
           <Route path="/landing" element={<LandingPage />} />
+          {/* Public read-only conversation viewer — no authentication. */}
+          <Route path="/share/:shareCode" element={<PublicSharePage />} />
+          {/* Public read-only scheduled-task runs viewer — no authentication. */}
           <Route
-            path="/workspace"
-            element={<Navigate to="/workspace/chats/new" replace />}
-          />
-          <Route
-            path="/workspace/chats"
-            element={
-              <WorkspaceLayout>
-                <ChatsPage />
-              </WorkspaceLayout>
-            }
-          />
-          <Route
-            path="/workspace/chats/:thread_id"
-            element={
-              <WorkspaceLayout>
-                <ChatRuntime>
-                  <ChatPage />
-                </ChatRuntime>
-              </WorkspaceLayout>
-            }
-          />
-          <Route
-            path="/workspace/agents"
-            element={
-              <WorkspaceLayout>
-                <AgentsPage />
-              </WorkspaceLayout>
-            }
-          />
-          <Route
-            path="/workspace/scheduled"
-            element={<Navigate to="/workspace/scheduled/tasks" replace />}
-          />
-          <Route
-            path="/workspace/scheduled/tasks"
-            element={
-              <WorkspaceLayout>
-                <ScheduledTasksPage />
-              </WorkspaceLayout>
-            }
-          />
-          <Route
-            path="/workspace/scheduled/runs/:run_id"
-            element={
-              <WorkspaceLayout>
-                <ScheduledTaskRunDetailPage />
-              </WorkspaceLayout>
-            }
-          />
-          <Route
-            path="/workspace/agents/new"
-            element={
-              <WorkspaceLayout>
-                <NewAgentPage />
-              </WorkspaceLayout>
-            }
-          />
-          <Route
-            path="/workspace/agents/:agent_id/chats"
-            element={<Navigate to="/workspace/agents" replace />}
-          />
-          <Route
-            path="/workspace/agents/:agent_id/chats/:thread_id"
-            element={
-              <WorkspaceLayout>
-                <ChatRuntime>
-                  <AgentChatPage />
-                </ChatRuntime>
-              </WorkspaceLayout>
-            }
+            path="/public/scheduled-tasks/:taskId"
+            element={<PublicScheduledTaskPage />}
           />
+          <Route path="/page/*" element={<PageRoutes />} />
           <Route path="*" element={<NotFoundPage />} />
         </Routes>
       </AppProviders>

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/ai-elements/prompt-input.tsx

@@ -674,12 +674,22 @@ export const PromptInput = ({
   useEffect(() => {
     if (!globalDrop) return;
 
+    // Suppress the global chat-upload handler when the drop happens inside an open
+    // modal dialog or popover — those owners (e.g. the skill-install dialog) handle
+    // their own file uploads and should not leak into the active chat thread.
+    const isInsideModal = (target: EventTarget | null): boolean => {
+      if (!(target instanceof Element)) return false;
+      return target.closest('[role="dialog"], [role="alertdialog"]') !== null;
+    };
+
     const onDragOver = (e: DragEvent) => {
+      if (isInsideModal(e.target)) return;
       if (e.dataTransfer?.types?.includes("Files")) {
         e.preventDefault();
       }
     };
     const onDrop = (e: DragEvent) => {
+      if (isInsideModal(e.target)) return;
       if (e.dataTransfer?.types?.includes("Files")) {
         e.preventDefault();
       }

frontend-web/src/components/landing/footer.tsx

@@ -12,7 +12,7 @@ export function Footer() {
       </div>
       <div className="text-muted-foreground container mb-8 flex flex-col items-center justify-center text-xs">
         <p>Licensed under MIT License</p>
-        <p>&copy; {year} CM业务中心-问答管理</p>
+        <p>&copy; {year} CM 助手</p>
       </div>
     </footer>
   );

frontend-web/src/components/landing/header.tsx

@@ -1,14 +1,9 @@
 "use client";
 
-import { StarFilledIcon, GitHubLogoIcon } from "@radix-ui/react-icons";
 import Link from "next/link";
-import { useEffect, useState } from "react";
 
-import { Button } from "@/components/ui/button";
-import { NumberTicker } from "@/components/ui/number-ticker";
 import type { Locale } from "@/core/i18n/locale";
 import { useI18n } from "@/core/i18n/hooks";
-import { env } from "@/env";
 import { cn } from "@/lib/utils";
 
 export type HeaderProps = {
@@ -30,11 +25,11 @@ export function Header({ className, homeURL }: HeaderProps) {
     >
       <div className="flex items-center gap-6">
         <a
-          href={homeURL ?? "https://github.com/bytedance/deer-flow"}
+          href={homeURL ?? "/"}
           target={isExternalHome ? "_blank" : "_self"}
           rel={isExternalHome ? "noopener noreferrer" : undefined}
         >
-          <h1 className="font-serif text-xl">CM业务中心-问答管理</h1>
+          <h1 className="font-serif text-xl">CM 助手</h1>
         </a>
       </div>
       <nav className="mr-8 ml-auto flex items-center gap-8 text-sm font-medium">
@@ -51,77 +46,7 @@ export function Header({ className, homeURL }: HeaderProps) {
           {t.home.blog}
         </Link>
       </nav>
-      <div className="relative">
-        <div
-          className="pointer-events-none absolute inset-0 z-0 h-full w-full rounded-full opacity-30 blur-2xl"
-          style={{
-            background: "linear-gradient(90deg, #ff80b5 0%, #9089fc 100%)",
-            filter: "blur(16px)",
-          }}
-        />
-        <Button
-          variant="outline"
-          size="sm"
-          asChild
-          className="group relative z-10"
-        >
-          <a
-            href="https://github.com/bytedance/deer-flow"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            <GitHubLogoIcon className="size-4" />
-            Star on GitHub
-            {env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" &&
-              env.GITHUB_OAUTH_TOKEN && <StarCounter />}
-          </a>
-        </Button>
-      </div>
       <hr className="from-border/0 via-border/70 to-border/0 absolute top-16 right-0 left-0 z-10 m-0 h-px w-full border-none bg-linear-to-r" />
     </header>
   );
 }
-
-function StarCounter() {
-  const [stars, setStars] = useState(10000);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    async function loadStars() {
-      try {
-        const response = await fetch(
-          "https://api.github.com/repos/bytedance/deer-flow",
-          {
-            headers: env.GITHUB_OAUTH_TOKEN
-              ? {
-                  Authorization: `Bearer ${env.GITHUB_OAUTH_TOKEN}`,
-                  "Content-Type": "application/json",
-                }
-              : {},
-          },
-        );
-
-        if (!response.ok) return;
-        const data = await response.json();
-        if (!cancelled && typeof data?.stargazers_count === "number") {
-          setStars(data.stargazers_count);
-        }
-      } catch (error) {
-        console.error("Error fetching GitHub stars:", error);
-      }
-    }
-
-    void loadStars();
-    return () => {
-      cancelled = true;
-    };
-  }, []);
-
-  return (
-    <>
-      <StarFilledIcon className="size-4 transition-colors duration-300 group-hover:text-yellow-500" />
-      <NumberTicker className="font-mono tabular-nums" value={stars} />
-    </>
-  );
-}

frontend-web/src/components/landing/hero.tsx

@@ -55,7 +55,7 @@ export function Hero({ className }: { className?: string }) {
               "Learn Anything",
             ]}
           />{" "}
-          <div>CM业务中心-问答管理</div>
+          <div>CM 助手</div>
         </h1>
         {env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY && (
           <a

frontend-web/src/components/landing/progressive-skills-animation.tsx

@@ -461,7 +461,7 @@ export default function ProgressiveSkillsAnimation() {
           <div className="border-b border-zinc-800 p-4">
             <div className="flex items-center gap-2">
               <div className="h-3 w-3 rounded-full bg-green-500" />
-              <span className="text-sm text-zinc-400">CM业务中心-问答管理 Agent</span>
+              <span className="text-sm text-zinc-400">CM 助手 Agent</span>
             </div>
           </div>
 
@@ -691,7 +691,7 @@ export default function ProgressiveSkillsAnimation() {
           {/* Chat Input (decorative) */}
           <div className="border-t border-zinc-800 p-4">
             <div className="rounded-xl bg-zinc-800 px-4 py-3 text-sm text-zinc-500">
-              Ask CM业务中心-问答管理 anything...
+              Ask CM 助手 anything...
             </div>
           </div>
         </div>

frontend-web/src/components/landing/sections/case-study-section.tsx

@@ -49,7 +49,7 @@ export function CaseStudySection({ className }: { className?: string }) {
     <Section
       className={className}
       title="Case Studies"
-      subtitle="CM业务中心-问答管理"
+      subtitle="CM 助手"
     >
       <div className="container-md mt-8 grid grid-cols-1 gap-4 px-4 md:grid-cols-2 md:px-20 lg:grid-cols-3">
         {caseStudies.map((caseStudy) => (

frontend-web/src/components/landing/sections/community-section.tsx

@@ -1,10 +1,6 @@
 "use client";
 
-import { GitHubLogoIcon } from "@radix-ui/react-icons";
-import Link from "next/link";
-
 import { AuroraText } from "@/components/ui/aurora-text";
-import { Button } from "@/components/ui/button";
 
 import { Section } from "../section";
 
@@ -16,20 +12,9 @@ export function CommunitySection() {
           Join the Community
         </AuroraText>
       }
-      subtitle="Contribute brilliant ideas to shape the future of DeerFlow. Collaborate, innovate, and make impacts."
+      subtitle="Contribute brilliant ideas to shape the future of CM Assistant. Collaborate, innovate, and make impacts."
     >
-      <div className="flex justify-center">
-        <Button className="text-xl" size="lg" asChild>
-          <Link
-            href="https://github.com/bytedance/deer-flow"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            <GitHubLogoIcon />
-            Contribute Now
-          </Link>
-        </Button>
-      </div>
+      <div />
     </Section>
   );
 }

frontend-web/src/components/landing/sections/sandbox-section.tsx

@@ -15,7 +15,7 @@ export function SandboxSection({ className }: { className?: string }) {
       title="Agent Runtime Environment"
       subtitle={
         <p>
-          We give DeerFlow a &quot;computer&quot;, which can execute commands,
+          We give CM Assistant a &quot;computer&quot;, which can execute commands,
           manage files, and run long tasks — all in a secure Docker-based
           sandbox
         </p>

frontend-web/src/components/landing/sections/skills-section.tsx

@@ -15,7 +15,7 @@ export function SkillsSection({ className }: { className?: string }) {
           Agent Skills are loaded progressively — only what's needed, when
           it's needed.
           <br />
-          Extend DeerFlow with your own skill files, or use our built-in
+          Extend CM Assistant with your own skill files, or use our built-in
           library.
         </div>
       }

frontend-web/src/components/landing/sections/whats-new-section.tsx

@@ -52,8 +52,8 @@ export function WhatsNewSection({ className }: { className?: string }) {
   return (
     <Section
       className={cn("", className)}
-      title="CM业务中心-问答管理"
-      subtitle="CM业务中心-问答管理"
+      title="CM 助手"
+      subtitle="CM 助手"
     >
       <div className="flex w-full items-center justify-center">
         <MagicBento data={features} />

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

@@ -0,0 +1,297 @@
+import { useEffect, useState } from "react";
+import { useNavigate, useLocation } from "react-router-dom";
+import {
+  Bell,
+  ChevronLeft,
+  ChevronRight,
+  ChevronsUpDown,
+  Folder,
+  FolderOpen,
+  Settings,
+  User,
+  Wrench,
+} from "lucide-react";
+
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { NotificationDialog } from "@/components/workspace/notification-dialog";
+import { SettingsDialog } from "@/components/workspace/settings";
+import { useTheme } from "@/contexts/ThemeContext";
+import { getStoredAuth } from "@/core/auth";
+import { useI18n } from "@/core/i18n/hooks";
+import { useUnreadCount } from "@/core/notifications";
+import {
+  defaultExpandedIds,
+  filterMenuItemsByRole,
+  sidebarMenuItems,
+  type MenuItem,
+} from "@/core/page-layout/sidebar-menu";
+
+type PageSidebarProps = {
+  collapsed: boolean;
+  onToggleCollapsed: () => void;
+};
+
+type SettingsSection = "account" | "appearance" | "memory" | "tools" | "about";
+
+export function PageSidebar({
+  collapsed,
+  onToggleCollapsed,
+}: PageSidebarProps) {
+  const { theme } = useTheme();
+  const isDark = theme === "dark";
+  const isAdmin = getStoredAuth()?.system_role === "admin";
+  const visibleMenuItems = filterMenuItemsByRole(sidebarMenuItems, !!isAdmin);
+  const { t } = useI18n();
+  const { data: unreadCount = 0 } = useUnreadCount();
+  // defaultExpandedIds 是共享的 ReadonlySet，复制一份给 useState（避免外部突变）
+  const [expandedIds, setExpandedIds] = useState<Set<string>>(() => new Set(defaultExpandedIds));
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  const [settingsDefaultSection, setSettingsDefaultSection] =
+    useState<SettingsSection>("appearance");
+  const [notificationOpen, setNotificationOpen] = useState(false);
+  const [mounted, setMounted] = useState(false);
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  const openSettings = (section: SettingsSection) => {
+    setSettingsDefaultSection(section);
+    setSettingsOpen(true);
+  };
+
+  const iconButtonClass = isDark
+    ? "rounded-lg p-2 text-slate-400 transition-all duration-300 ease-out hover:scale-105 hover:bg-slate-800/50 hover:text-white"
+    : "rounded-lg p-2 text-gray-500 transition-all duration-300 ease-out hover:scale-105 hover:bg-red-50 hover:text-red-600";
+  const panelClass = isDark
+    ? "ml-4 space-y-1 border-l border-blue-800/30 pl-4"
+    : "ml-4 space-y-1 border-l border-red-100 pl-4";
+  const labelClass = (compact: boolean, small = false) =>
+    `overflow-hidden whitespace-nowrap transition-all duration-300 ease-out ${
+      compact ? "max-w-0 opacity-0" : "max-w-[220px] opacity-100"
+    } ${small ? "text-xs" : "text-sm"} flex-1 font-medium`;
+  const menuButtonClass = (isActive: boolean, depth = 0) =>
+    `flex w-full items-center rounded-lg py-2 text-left transition-all duration-300 ease-out hover:-translate-y-0.5 theme-transition ${
+      collapsed && depth === 0 ? "justify-center px-2" : "gap-2 px-3"
+    } ${
+      isActive
+        ? isDark
+          ? "bg-blue-500/15 text-cyan-300 font-semibold"
+          : "bg-red-50 text-red-600 font-semibold"
+        : isDark
+          ? "text-slate-400 hover:bg-slate-800/50 hover:text-white"
+          : "text-gray-600 hover:bg-red-50 hover:text-red-600"
+    }`;
+  const footerButtonClass = menuButtonClass(false, 0);
+
+  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 renderLeaf = (item: MenuItem, depth = 0) => {
+    const Icon = item.icon;
+    const isActive = !!item.path && pathname === item.path;
+
+    return (
+      <button
+        key={item.id}
+        type="button"
+        title={collapsed && depth === 0 ? item.label : undefined}
+        onClick={() => item.path && navigate(item.path)}
+        className={menuButtonClass(isActive, depth)}
+      >
+        <Icon className={`${depth === 0 ? "h-5 w-5" : "h-4 w-4"} flex-shrink-0 transition-transform duration-300 ease-out`} />
+        {(!collapsed || depth > 0) && (
+          <span className={labelClass(false, depth > 0)}>
+            {item.label}
+          </span>
+        )}
+      </button>
+    );
+  };
+
+  const renderBranch = (item: MenuItem, depth = 0) => {
+    const expanded = expandedIds.has(item.id);
+    const isTopLevel = depth === 0;
+    const Icon = depth > 0 && item.icon === Folder && expanded ? FolderOpen : item.icon;
+
+    return (
+      <div key={item.id} className="space-y-1">
+        <button
+          type="button"
+          onClick={() => {
+            if (collapsed && isTopLevel) {
+              onToggleCollapsed();
+              return;
+            }
+            toggleExpanded(item.id);
+          }}
+          title={collapsed && isTopLevel ? item.label : undefined}
+          className={menuButtonClass(false, depth)}
+        >
+          <Icon
+            className={`${isTopLevel ? "h-5 w-5" : "h-4 w-4"} flex-shrink-0 transition-transform duration-300 ease-out ${
+              expanded && depth > 0 ? "scale-105" : ""
+            }`}
+          />
+          {(!collapsed || !isTopLevel) && (
+            <span className={labelClass(false, depth > 0)}>
+              {item.label}
+            </span>
+          )}
+          {(!collapsed || !isTopLevel) && (
+            <ChevronRight
+              className={`h-4 w-4 transition-transform duration-300 ease-out ${expanded ? "rotate-90" : ""}`}
+            />
+          )}
+        </button>
+
+        {(!collapsed || !isTopLevel) && item.children && (
+          <div
+            className={`${panelClass} overflow-hidden transition-all duration-300 ease-out ${
+              expanded ? "max-h-[1200px] opacity-100" : "max-h-0 opacity-0"
+            }`}
+          >
+            {item.children.map((child) =>
+              child.children ? renderBranch(child, depth + 1) : renderLeaf(child, depth + 1),
+            )}
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  return (
+    <>
+      <SettingsDialog
+        open={settingsOpen}
+        onOpenChange={setSettingsOpen}
+        defaultSection={settingsDefaultSection}
+      />
+      <NotificationDialog
+        open={notificationOpen}
+        onOpenChange={setNotificationOpen}
+      />
+      <aside
+        className={`fixed left-0 top-16 z-40 flex h-[calc(100vh-4rem)] flex-col overflow-hidden shadow-sm theme-transition transition-all duration-300 ${
+          isDark
+            ? "border-r border-blue-800/30 bg-slate-900"
+            : "border-r border-red-100 bg-white"
+        } ${collapsed ? "w-16" : "w-64"}`}
+      >
+      <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"
+        }`}
+      >
+        {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`}>
+        {visibleMenuItems.map((item) =>
+          item.children ? renderBranch(item) : renderLeaf(item),
+        )}
+      </nav>
+
+      <div
+        className={`mt-auto shrink-0 theme-transition ${
+          isDark ? "border-t border-blue-800/30" : "border-t border-red-100"
+        } ${collapsed ? "p-2" : "p-4"}`}
+      >
+        {mounted ? (
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <button
+                type="button"
+                title={collapsed ? t.workspace.settingsAndMore : undefined}
+                className={footerButtonClass}
+              >
+                <Settings className="h-5 w-5 flex-shrink-0" />
+                {!collapsed && (
+                  <>
+                    <span className={labelClass(false)}>
+                      {t.workspace.settingsAndMore}
+                    </span>
+                    <ChevronsUpDown className="h-4 w-4 flex-shrink-0" />
+                  </>
+                )}
+              </button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent
+              align={collapsed ? "start" : "end"}
+              side={collapsed ? "right" : "top"}
+              sideOffset={4}
+              className="min-w-56 rounded-lg"
+            >
+              <DropdownMenuItem onClick={() => setNotificationOpen(true)}>
+                <Bell className="size-4" />
+                {t.notifications.title}
+                {unreadCount > 0 && (
+                  <span
+                    className={`ml-auto flex h-4 min-w-4 items-center justify-center rounded-full px-1 text-[10px] font-medium leading-none text-white ${
+                      isDark ? "bg-cyan-500" : "bg-red-500"
+                    }`}
+                  >
+                    {unreadCount > 99 ? "99+" : unreadCount}
+                  </span>
+                )}
+              </DropdownMenuItem>
+              <DropdownMenuItem onClick={() => openSettings("tools")}>
+                <Wrench className="size-4" />
+                {t.settings.sections.tools}
+              </DropdownMenuItem>
+              <DropdownMenuItem onClick={() => openSettings("account")}>
+                <User className="size-4" />
+                个人信息
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        ) : (
+          <button
+            type="button"
+            className={`${footerButtonClass} pointer-events-none`}
+          >
+            <Settings className="h-5 w-5 flex-shrink-0" />
+            {!collapsed && (
+              <span className={labelClass(false)}>
+                {t.workspace.settingsAndMore}
+              </span>
+            )}
+          </button>
+        )}
+      </div>
+
+      <div
+        className={`pointer-events-none absolute right-0 top-0 h-32 w-32 rounded-full blur-3xl theme-transition ${
+          isDark ? "bg-blue-500/10" : "bg-red-500/5"
+        }`}
+      />
+      <div
+        className={`pointer-events-none absolute bottom-20 right-0 h-24 w-24 rounded-full blur-3xl theme-transition ${
+          isDark ? "bg-cyan-400/5" : "bg-red-400/5"
+        }`}
+      />
+    </aside>
+    </>
+  );
+}

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

@@ -31,23 +31,25 @@ function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
   );
 }
 
-function BreadcrumbLink({
-  asChild,
-  className,
-  ...props
-}: React.ComponentProps<"a"> & {
+const BreadcrumbLink = React.forwardRef<
+  HTMLAnchorElement,
+  React.ComponentProps<"a"> & {
     asChild?: boolean;
-}) {
+  }
+>(({ asChild, className, ...props }, ref) => {
   const Comp = asChild ? Slot : "a";
 
   return (
     <Comp
+      ref={ref}
       data-slot="breadcrumb-link"
       className={cn("hover:text-foreground transition-colors", className)}
       {...props}
     />
   );
-}
+});
+
+BreadcrumbLink.displayName = "BreadcrumbLink";
 
 function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
   return (

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

@@ -37,20 +37,18 @@ const buttonVariants = cva(
   },
 );
 
-function Button({
-  className,
-  variant = "default",
-  size = "default",
-  asChild = false,
-  ...props
-}: React.ComponentProps<"button"> &
+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 })}
@@ -58,6 +56,8 @@ function Button({
       {...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/collapsible.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import * as React from "react";
 import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
 
 import { cn } from "@/lib/utils";
@@ -10,28 +11,37 @@ function Collapsible({
   return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />;
 }
 
-function CollapsibleTrigger({
-  className,
-  ...props
-}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>) {
+const CollapsibleTrigger = React.forwardRef<
+  React.ElementRef<typeof CollapsiblePrimitive.CollapsibleTrigger>,
+  React.ComponentPropsWithoutRef<typeof CollapsiblePrimitive.CollapsibleTrigger>
+>(({ className, ...props }, ref) => {
   return (
     <CollapsiblePrimitive.CollapsibleTrigger
+      ref={ref}
       data-slot="collapsible-trigger"
       className={cn("cursor-pointer", className)}
       {...props}
     />
   );
-}
+});
 
-function CollapsibleContent({
-  ...props
-}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>) {
+CollapsibleTrigger.displayName =
+  CollapsiblePrimitive.CollapsibleTrigger.displayName;
+
+const CollapsibleContent = React.forwardRef<
+  React.ElementRef<typeof CollapsiblePrimitive.CollapsibleContent>,
+  React.ComponentPropsWithoutRef<typeof CollapsiblePrimitive.CollapsibleContent>
+>(({ ...props }, ref) => {
   return (
     <CollapsiblePrimitive.CollapsibleContent
+      ref={ref}
       data-slot="collapsible-content"
       {...props}
     />
   );
-}
+});
+
+CollapsibleContent.displayName =
+  CollapsiblePrimitive.CollapsibleContent.displayName;
 
 export { Collapsible, CollapsibleTrigger, CollapsibleContent };

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

@@ -12,11 +12,20 @@ function Dialog({
   return <DialogPrimitive.Root data-slot="dialog" {...props} />;
 }
 
-function DialogTrigger({
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
-  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
-}
+const DialogTrigger = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Trigger>
+>(({ ...props }, ref) => {
+  return (
+    <DialogPrimitive.Trigger
+      ref={ref}
+      data-slot="dialog-trigger"
+      {...props}
+    />
+  );
+});
+
+DialogTrigger.displayName = DialogPrimitive.Trigger.displayName;
 
 function DialogPortal({
   ...props
@@ -24,18 +33,22 @@ function DialogPortal({
   return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />;
 }
 
-function DialogClose({
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Close>) {
-  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />;
-}
+const DialogClose = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Close>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Close>
+>(({ ...props }, ref) => {
+  return <DialogPrimitive.Close ref={ref} data-slot="dialog-close" {...props} />;
+});
 
-function DialogOverlay({
-  className,
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+DialogClose.displayName = DialogPrimitive.Close.displayName;
+
+const DialogOverlay = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => {
   return (
     <DialogPrimitive.Overlay
+      ref={ref}
       data-slot="dialog-overlay"
       className={cn(
         "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50",
@@ -44,20 +57,21 @@ function DialogOverlay({
       {...props}
     />
   );
-}
+});
 
-function DialogContent({
-  className,
-  children,
-  showCloseButton = true,
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Content> & {
+DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
+
+const DialogContent = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & {
     showCloseButton?: boolean;
-}) {
+  }
+>(({ className, children, showCloseButton = true, ...props }, ref) => {
   return (
     <DialogPortal data-slot="dialog-portal">
       <DialogOverlay />
       <DialogPrimitive.Content
+        ref={ref}
         data-slot="dialog-content"
         className={cn(
           "bg-background 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 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 outline-none sm:max-w-lg",
@@ -78,7 +92,9 @@ function DialogContent({
       </DialogPrimitive.Content>
     </DialogPortal>
   );
-}
+});
+
+DialogContent.displayName = DialogPrimitive.Content.displayName;
 
 function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (

frontend-web/src/components/ui/dropdown-menu.tsx

@@ -20,25 +20,29 @@ function DropdownMenuPortal({
   );
 }
 
-function DropdownMenuTrigger({
-  ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+const DropdownMenuTrigger = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Trigger>
+>(({ ...props }, ref) => {
   return (
     <DropdownMenuPrimitive.Trigger
+      ref={ref}
       data-slot="dropdown-menu-trigger"
       {...props}
     />
   );
-}
+});
 
-function DropdownMenuContent({
-  className,
-  sideOffset = 4,
-  ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+DropdownMenuTrigger.displayName = DropdownMenuPrimitive.Trigger.displayName;
+
+const DropdownMenuContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
+>(({ className, sideOffset = 4, ...props }, ref) => {
   return (
     <DropdownMenuPrimitive.Portal>
       <DropdownMenuPrimitive.Content
+        ref={ref}
         data-slot="dropdown-menu-content"
         sideOffset={sideOffset}
         className={cn(
@@ -49,7 +53,9 @@ function DropdownMenuContent({
       />
     </DropdownMenuPrimitive.Portal>
   );
-}
+});
+
+DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName;
 
 function DropdownMenuGroup({
   ...props
@@ -59,17 +65,16 @@ function DropdownMenuGroup({
   );
 }
 
-function DropdownMenuItem({
-  className,
-  inset,
-  variant = "default",
-  ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+const DropdownMenuItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item> & {
     inset?: boolean;
     variant?: "default" | "destructive";
-}) {
+  }
+>(({ className, inset, variant = "default", ...props }, ref) => {
   return (
     <DropdownMenuPrimitive.Item
+      ref={ref}
       data-slot="dropdown-menu-item"
       data-inset={inset}
       data-variant={variant}
@@ -80,7 +85,9 @@ function DropdownMenuItem({
       {...props}
     />
   );
-}
+});
+
+DropdownMenuItem.displayName = DropdownMenuPrimitive.Item.displayName;
 
 function DropdownMenuCheckboxItem({
   className,
@@ -198,16 +205,15 @@ function DropdownMenuSub({
   return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />;
 }
 
-function DropdownMenuSubTrigger({
-  className,
-  inset,
-  children,
-  ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+const DropdownMenuSubTrigger = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.SubTrigger>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubTrigger> & {
     inset?: boolean;
-}) {
+  }
+>(({ className, inset, children, ...props }, ref) => {
   return (
     <DropdownMenuPrimitive.SubTrigger
+      ref={ref}
       data-slot="dropdown-menu-sub-trigger"
       data-inset={inset}
       className={cn(
@@ -220,14 +226,18 @@ function DropdownMenuSubTrigger({
       <ChevronRightIcon className="ml-auto size-4" />
     </DropdownMenuPrimitive.SubTrigger>
   );
-}
+});
 
-function DropdownMenuSubContent({
-  className,
-  ...props
-}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+DropdownMenuSubTrigger.displayName =
+  DropdownMenuPrimitive.SubTrigger.displayName;
+
+const DropdownMenuSubContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.SubContent>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubContent>
+>(({ className, ...props }, ref) => {
   return (
     <DropdownMenuPrimitive.SubContent
+      ref={ref}
       data-slot="dropdown-menu-sub-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 z-50 min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg",
@@ -236,7 +246,10 @@ function DropdownMenuSubContent({
       {...props}
     />
   );
-}
+});
+
+DropdownMenuSubContent.displayName =
+  DropdownMenuPrimitive.SubContent.displayName;
 
 export {
   DropdownMenu,

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

@@ -11,23 +11,29 @@ function HoverCard({
   return <HoverCardPrimitive.Root data-slot="hover-card" {...props} />;
 }
 
-function HoverCardTrigger({
-  ...props
-}: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {
+const HoverCardTrigger = React.forwardRef<
+  React.ElementRef<typeof HoverCardPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Trigger>
+>(({ ...props }, ref) => {
   return (
-    <HoverCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
+    <HoverCardPrimitive.Trigger
+      ref={ref}
+      data-slot="hover-card-trigger"
+      {...props}
+    />
   );
-}
+});
 
-function HoverCardContent({
-  className,
-  align = "center",
-  sideOffset = 4,
-  ...props
-}: React.ComponentProps<typeof HoverCardPrimitive.Content>) {
+HoverCardTrigger.displayName = HoverCardPrimitive.Trigger.displayName;
+
+const HoverCardContent = React.forwardRef<
+  React.ElementRef<typeof HoverCardPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Content>
+>(({ className, align = "center", sideOffset = 4, ...props }, ref) => {
   return (
     <HoverCardPrimitive.Portal data-slot="hover-card-portal">
       <HoverCardPrimitive.Content
+        ref={ref}
         data-slot="hover-card-content"
         align={align}
         sideOffset={sideOffset}
@@ -39,6 +45,8 @@ function HoverCardContent({
       />
     </HoverCardPrimitive.Portal>
   );
-}
+});
+
+HoverCardContent.displayName = HoverCardPrimitive.Content.displayName;
 
 export { HoverCard, HoverCardTrigger, HoverCardContent };

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

@@ -8,9 +8,12 @@ function Input({ className, type, ...props }: React.ComponentProps<"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-[#022248] dark:text-[#AACEFF] dark:placeholder:text-[#566B7F] rounded-[4px] text-[16px]",
+        "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,16 +24,15 @@ function SelectValue({
   return <SelectPrimitive.Value data-slot="select-value" {...props} />;
 }
 
-function SelectTrigger({
-  className,
-  size = "default",
-  children,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+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(
@@ -48,18 +47,18 @@ function SelectTrigger({
       </SelectPrimitive.Icon>
     </SelectPrimitive.Trigger>
   );
-}
+});
 
-function SelectContent({
-  className,
-  children,
-  position = "item-aligned",
-  align = "center",
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+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",
@@ -85,7 +84,9 @@ function SelectContent({
       </SelectPrimitive.Content>
     </SelectPrimitive.Portal>
   );
-}
+});
+
+SelectContent.displayName = SelectPrimitive.Content.displayName;
 
 function SelectLabel({
   className,
@@ -100,13 +101,13 @@ function SelectLabel({
   );
 }
 
-function SelectItem({
-  className,
-  children,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+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",
@@ -125,7 +126,9 @@ function SelectItem({
       <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
     </SelectPrimitive.Item>
   );
-}
+});
+
+SelectItem.displayName = SelectPrimitive.Item.displayName;
 
 function SelectSeparator({
   className,

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

@@ -10,17 +10,23 @@ function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
   return <SheetPrimitive.Root data-slot="sheet" {...props} />;
 }
 
-function SheetTrigger({
-  ...props
-}: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
-  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />;
-}
+const SheetTrigger = React.forwardRef<
+  React.ElementRef<typeof SheetPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof SheetPrimitive.Trigger>
+>(({ ...props }, ref) => {
+  return <SheetPrimitive.Trigger ref={ref} data-slot="sheet-trigger" {...props} />;
+});
 
-function SheetClose({
-  ...props
-}: React.ComponentProps<typeof SheetPrimitive.Close>) {
-  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />;
-}
+SheetTrigger.displayName = SheetPrimitive.Trigger.displayName;
+
+const SheetClose = React.forwardRef<
+  React.ElementRef<typeof SheetPrimitive.Close>,
+  React.ComponentPropsWithoutRef<typeof SheetPrimitive.Close>
+>(({ ...props }, ref) => {
+  return <SheetPrimitive.Close ref={ref} data-slot="sheet-close" {...props} />;
+});
+
+SheetClose.displayName = SheetPrimitive.Close.displayName;
 
 function SheetPortal({
   ...props
@@ -28,12 +34,13 @@ function SheetPortal({
   return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />;
 }
 
-function SheetOverlay({
-  className,
-  ...props
-}: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
+const SheetOverlay = React.forwardRef<
+  React.ElementRef<typeof SheetPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof SheetPrimitive.Overlay>
+>(({ className, ...props }, ref) => {
   return (
     <SheetPrimitive.Overlay
+      ref={ref}
       data-slot="sheet-overlay"
       className={cn(
         "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50",
@@ -42,20 +49,21 @@ function SheetOverlay({
       {...props}
     />
   );
-}
+});
 
-function SheetContent({
-  className,
-  children,
-  side = "right",
-  ...props
-}: React.ComponentProps<typeof SheetPrimitive.Content> & {
+SheetOverlay.displayName = SheetPrimitive.Overlay.displayName;
+
+const SheetContent = React.forwardRef<
+  React.ElementRef<typeof SheetPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content> & {
     side?: "top" | "right" | "bottom" | "left";
-}) {
+  }
+>(({ className, children, side = "right", ...props }, ref) => {
   return (
     <SheetPortal>
       <SheetOverlay />
       <SheetPrimitive.Content
+        ref={ref}
         data-slot="sheet-content"
         className={cn(
           "bg-background data-[state=open]:animate-in data-[state=closed]:animate-out fixed z-50 flex flex-col gap-4 shadow-lg transition ease-in-out data-[state=closed]:duration-300 data-[state=open]:duration-500",
@@ -79,7 +87,9 @@ function SheetContent({
       </SheetPrimitive.Content>
     </SheetPortal>
   );
-}
+});
+
+SheetContent.displayName = SheetPrimitive.Content.displayName;
 
 function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
   return (

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

@@ -53,6 +53,10 @@ function useSidebar() {
   return context;
 }
 
+function useSidebarSafe() {
+  return React.useContext(SidebarContext);
+}
+
 function SidebarProvider({
   defaultOpen = true,
   open: openProp,
@@ -139,7 +143,7 @@ function SidebarProvider({
             } as React.CSSProperties
           }
           className={cn(
-            "group/sidebar-wrapper has-data-[variant=inset]:bg-sidebar flex min-h-svh w-full",
+            "group/sidebar-wrapper has-data-[variant=inset]:bg-sidebar flex h-full w-full",
             className,
           )}
           {...props}
@@ -229,7 +233,7 @@ function Sidebar({
       <div
         data-slot="sidebar-container"
         className={cn(
-          "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex",
+          "fixed bottom-0 z-10 hidden w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex [top:var(--header-height,4rem)]",
           side === "left"
             ? "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]"
             : "right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",
@@ -309,7 +313,7 @@ function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
     <main
       data-slot="sidebar-inset"
       className={cn(
-        "bg-[#fffdfa] relative flex w-full flex-1 flex-col",
+        "bg-background relative flex w-full flex-1 flex-col",
         "md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2",
         className,
       )}
@@ -393,15 +397,15 @@ function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
-function SidebarGroupLabel({
-  className,
-  asChild = false,
-  ...props
-}: React.ComponentProps<"div"> & { asChild?: boolean }) {
+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(
@@ -412,17 +416,19 @@ function SidebarGroupLabel({
       {...props}
     />
   );
-}
+});
 
-function SidebarGroupAction({
-  className,
-  asChild = false,
-  ...props
-}: React.ComponentProps<"button"> & { asChild?: boolean }) {
+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(
@@ -435,7 +441,9 @@ function SidebarGroupAction({
       {...props}
     />
   );
-}
+});
+
+SidebarGroupAction.displayName = "SidebarGroupAction";
 
 function SidebarGroupContent({
   className,
@@ -495,7 +503,16 @@ const sidebarMenuButtonVariants = cva(
   },
 );
 
-function 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",
@@ -503,16 +520,15 @@ function SidebarMenuButton({
       tooltip,
       className,
       ...props
-}: React.ComponentProps<"button"> & {
-  asChild?: boolean;
-  isActive?: boolean;
-  tooltip?: string | React.ComponentProps<typeof TooltipContent>;
-} & VariantProps<typeof sidebarMenuButtonVariants>) {
+    },
+    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}
@@ -543,21 +559,23 @@ function SidebarMenuButton({
         />
       </Tooltip>
     );
-}
+  },
+);
 
-function SidebarMenuAction({
-  className,
-  asChild = false,
-  showOnHover = false,
-  ...props
-}: React.ComponentProps<"button"> & {
+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(
@@ -575,7 +593,9 @@ function SidebarMenuAction({
       {...props}
     />
   );
-}
+});
+
+SidebarMenuAction.displayName = "SidebarMenuAction";
 
 function SidebarMenuBadge({
   className,
@@ -666,21 +686,19 @@ function SidebarMenuSubItem({
   );
 }
 
-function SidebarMenuSubButton({
-  asChild = false,
-  size = "md",
-  isActive = false,
-  className,
-  ...props
-}: React.ComponentProps<"a"> & {
+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}
@@ -696,7 +714,9 @@ function SidebarMenuSubButton({
       {...props}
     />
   );
-}
+});
+
+SidebarMenuSubButton.displayName = "SidebarMenuSubButton";
 
 export {
   Sidebar,
@@ -723,4 +743,5 @@ export {
   SidebarSeparator,
   SidebarTrigger,
   useSidebar,
+  useSidebarSafe,
 };

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

@@ -30,7 +30,8 @@ const tabsListVariants = cva(
   {
     variants: {
       variant: {
-        default: "bg-muted",
+        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",
       },
     },
@@ -40,52 +41,65 @@ const tabsListVariants = cva(
   },
 );
 
-function TabsList({
-  className,
-  variant = "default",
-  ...props
-}: React.ComponentProps<typeof TabsPrimitive.List> &
-  VariantProps<typeof tabsListVariants>) {
+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}
     />
   );
-}
+});
 
-function TabsTrigger({
-  className,
-  ...props
-}: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+TabsList.displayName = TabsPrimitive.List.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 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",
+        "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 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",
+        "data-[state=active]:bg-background data-[state=active]:text-foreground",
+        "dark:group-data-[variant=line]/tabs-list:data-[state=active]:border-input dark:group-data-[variant=line]/tabs-list:data-[state=active]:bg-input/30 dark:group-data-[variant=line]/tabs-list:data-[state=active]:text-foreground",
+        "dark:group-data-[variant=default]/tabs-list:relative dark:group-data-[variant=default]/tabs-list:!h-full dark:group-data-[variant=default]/tabs-list:self-stretch dark:group-data-[variant=default]/tabs-list:flex-none 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:shadow-none 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]:[&_svg]:text-[#FFFFFF] dark:group-data-[variant=default]/tabs-list:hover:text-[#CCD2DA]",
         "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}
     />
   );
-}
+});
 
-function TabsContent({
-  className,
-  ...props
-}: React.ComponentProps<typeof TabsPrimitive.Content>) {
+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/ui/tooltip.tsx

@@ -28,21 +28,29 @@ function Tooltip({
   );
 }
 
-function TooltipTrigger({
-  ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
-  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
-}
+const TooltipTrigger = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Trigger>
+>(({ ...props }, ref) => {
+  return (
+    <TooltipPrimitive.Trigger
+      ref={ref}
+      data-slot="tooltip-trigger"
+      {...props}
+    />
+  );
+});
 
-function TooltipContent({
-  className,
-  sideOffset,
-  children,
-  ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+TooltipTrigger.displayName = TooltipPrimitive.Trigger.displayName;
+
+const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
+>(({ className, sideOffset, children, ...props }, ref) => {
   return (
     <TooltipPrimitive.Portal>
       <TooltipPrimitive.Content
+        ref={ref}
         data-slot="tooltip-content"
         sideOffset={sideOffset ?? 4}
         className={cn(
@@ -55,6 +63,8 @@ function TooltipContent({
       </TooltipPrimitive.Content>
     </TooltipPrimitive.Portal>
   );
-}
+});
+
+TooltipContent.displayName = TooltipPrimitive.Content.displayName;
 
 export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };

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

@@ -0,0 +1,716 @@
+"use client";
+
+import { useState } from "react";
+import { Check, Loader2, Pencil, Plus, Trash2, X } from "lucide-react";
+import { toast } from "sonner";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+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 { Textarea } from "@/components/ui/textarea";
+import {
+  useAdminAddMemoryEntry,
+  useAdminAddV1Fact,
+  useAdminDeleteMemoryEntry,
+  useAdminDeleteV1Fact,
+  useAdminReplaceMemoryEntry,
+  useAdminUpdateV1Fact,
+  useAdminUpdateV1Section,
+  useUserMemory,
+} from "@/core/admin/hooks";
+import { useAllUsers } from "@/core/auth/hooks";
+
+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);
+}
+
+// ── V1 只读视图 ────────────────────────────────────────────────────────────
+
+const CTX_LABELS: Record<string, string> = {
+  workContext: "工作背景",
+  personalContext: "个人信息",
+  topOfMind: "当前重点",
+};
+const HISTORY_LABELS: Record<string, string> = {
+  recentMonths: "近期",
+  earlierContext: "早期背景",
+  longTermBackground: "长期背景",
+};
+const CATEGORY_COLORS: Record<string, string> = {
+  preference: "bg-blue-100 text-blue-700",
+  knowledge: "bg-green-100 text-green-700",
+  context: "bg-yellow-100 text-yellow-700",
+  behavior: "bg-purple-100 text-purple-700",
+  goal: "bg-orange-100 text-orange-700",
+  correction: "bg-red-100 text-red-700",
+};
+
+const V1_CATEGORIES = ["preference", "knowledge", "context", "behavior", "goal", "correction"];
+
+function extractSummary(val: unknown): string {
+  if (typeof val === "string") return val;
+  if (val && typeof val === "object" && "summary" in val)
+    return String((val as Record<string, unknown>).summary ?? "");
+  return "";
+}
+
+// 单个摘要字段的行内编辑
+function V1SectionField({
+  label,
+  value,
+  onSave,
+}: {
+  label: string;
+  value: string;
+  onSave: (v: string) => Promise<void>;
+}) {
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState(value);
+  const [saving, setSaving] = useState(false);
+
+  async function handleSave() {
+    if (draft.trim() === value.trim()) { setEditing(false); return; }
+    setSaving(true);
+    try { await onSave(draft.trim()); setEditing(false); }
+    catch (err) { toast.error(err instanceof Error ? err.message : "保存失败"); }
+    finally { setSaving(false); }
+  }
+
+  return (
+    <div className="space-y-1">
+      <div className="flex items-center justify-between">
+        <span className="text-xs font-medium text-muted-foreground">{label}</span>
+        {!editing && (
+          <Button size="icon" variant="ghost" className="size-6" onClick={() => { setDraft(value); setEditing(true); }}>
+            <Pencil className="size-3" />
+          </Button>
+        )}
+      </div>
+      {editing ? (
+        <div className="space-y-1.5">
+          <Textarea value={draft} onChange={(e) => setDraft(e.target.value)} className="min-h-[72px] text-sm" autoFocus />
+          <div className="flex gap-1.5">
+            <Button size="sm" onClick={handleSave} disabled={saving}>
+              {saving ? <Loader2 className="size-3 animate-spin" /> : <Check className="size-3" />}保存
+            </Button>
+            <Button size="sm" variant="ghost" onClick={() => setEditing(false)}><X className="size-3" />取消</Button>
+          </div>
+        </div>
+      ) : (
+        <p className="text-sm whitespace-pre-wrap text-foreground/80 min-h-[1.5rem]">{value || <span className="text-muted-foreground italic">（空）</span>}</p>
+      )}
+    </div>
+  );
+}
+
+// 单条事实的行内编辑
+function V1FactItem({
+  fact,
+  agent,
+  userId,
+}: {
+  fact: Record<string, unknown>;
+  agent: string | null;
+  userId: string;
+}) {
+  const [editing, setEditing] = useState(false);
+  const [draftContent, setDraftContent] = useState(String(fact.content ?? ""));
+  const [draftCategory, setDraftCategory] = useState(String(fact.category ?? "context"));
+  const [draftConfidence, setDraftConfidence] = useState(
+    typeof fact.confidence === "number" ? Math.round(fact.confidence * 100) : 80,
+  );
+  const updateFact = useAdminUpdateV1Fact(userId);
+  const deleteFact = useAdminDeleteV1Fact(userId);
+
+  const factId = String(fact.id ?? "");
+  const confidence = typeof fact.confidence === "number" ? fact.confidence : 0;
+  const category = String(fact.category ?? "context");
+
+  async function handleSave() {
+    try {
+      await updateFact.mutateAsync({
+        factId,
+        updates: { content: draftContent.trim(), category: draftCategory, confidence: draftConfidence / 100 },
+        agent,
+      });
+      setEditing(false);
+    } catch (err) { toast.error(err instanceof Error ? err.message : "更新失败"); }
+  }
+
+  async function handleDelete() {
+    try { await deleteFact.mutateAsync({ factId, agent }); }
+    catch (err) { toast.error(err instanceof Error ? err.message : "删除失败"); }
+  }
+
+  return (
+    <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 />
+          <div className="flex items-center gap-2 flex-wrap">
+            <Select value={draftCategory} onValueChange={setDraftCategory}>
+              <SelectTrigger className="h-7 w-36 text-xs"><SelectValue /></SelectTrigger>
+              <SelectContent>{V1_CATEGORIES.map((c) => <SelectItem key={c} value={c} className="text-xs">{c}</SelectItem>)}</SelectContent>
+            </Select>
+            <div className="flex items-center gap-1">
+              <span className="text-xs text-muted-foreground">置信度</span>
+              <input
+                type="number" min={0} max={100} value={draftConfidence}
+                onChange={(e) => setDraftConfidence(Number(e.target.value))}
+                className="w-16 h-7 rounded border px-2 text-xs"
+              />
+              <span className="text-xs text-muted-foreground">%</span>
+            </div>
+          </div>
+          <div className="flex gap-1.5">
+            <Button size="sm" onClick={handleSave} disabled={updateFact.isPending}>
+              {updateFact.isPending ? <Loader2 className="size-3 animate-spin" /> : <Check className="size-3" />}保存
+            </Button>
+            <Button size="sm" variant="ghost" onClick={() => setEditing(false)}><X className="size-3" />取消</Button>
+          </div>
+        </div>
+      ) : (
+        <>
+          <div className="flex items-center justify-between gap-2">
+            <div className="flex items-center gap-2">
+              <span className={`rounded px-1.5 py-0.5 text-[10px] font-medium ${CATEGORY_COLORS[category] ?? "bg-gray-100 text-gray-700"}`}>{category}</span>
+              <span className="text-xs text-muted-foreground">{Math.round(confidence * 100)}%</span>
+            </div>
+            <div className="flex gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
+              <Button size="icon" variant="ghost" className="size-6" onClick={() => { setDraftContent(String(fact.content ?? "")); setDraftCategory(category); setDraftConfidence(Math.round(confidence * 100)); setEditing(true); }}>
+                <Pencil className="size-3" />
+              </Button>
+              <Button size="icon" variant="ghost" className="size-6 hover:text-destructive" onClick={handleDelete} disabled={deleteFact.isPending}>
+                {deleteFact.isPending ? <Loader2 className="size-3 animate-spin" /> : <Trash2 className="size-3" />}
+              </Button>
+            </div>
+          </div>
+          <p className="text-sm whitespace-pre-wrap">{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}
+        </>
+      )}
+    </div>
+  );
+}
+
+// 新增事实表单
+function V1AddFactForm({ agent, userId }: { agent: string | null; userId: string }) {
+  const [open, setOpen] = useState(false);
+  const [content, setContent] = useState("");
+  const [category, setCategory] = useState("context");
+  const [confidence, setConfidence] = useState(80);
+  const addFact = useAdminAddV1Fact(userId);
+
+  async function handleAdd() {
+    if (!content.trim()) return;
+    try {
+      await addFact.mutateAsync({ content: content.trim(), category, confidence: confidence / 100, agent });
+      setContent(""); setCategory("context"); setConfidence(80); setOpen(false);
+    } catch (err) { toast.error(err instanceof Error ? err.message : "新增失败"); }
+  }
+
+  if (!open) {
+    return (
+      <Button variant="outline" size="sm" className="mt-1 w-full" onClick={() => setOpen(true)}>
+        <Plus className="size-3" />新增事实
+      </Button>
+    );
+  }
+  return (
+    <div className="rounded-md border p-3 space-y-2">
+      <Textarea placeholder="事实内容…" value={content} onChange={(e) => setContent(e.target.value)} className="min-h-[64px] text-sm" autoFocus />
+      <div className="flex items-center gap-2 flex-wrap">
+        <Select value={category} onValueChange={setCategory}>
+          <SelectTrigger className="h-7 w-36 text-xs"><SelectValue /></SelectTrigger>
+          <SelectContent>{V1_CATEGORIES.map((c) => <SelectItem key={c} value={c} className="text-xs">{c}</SelectItem>)}</SelectContent>
+        </Select>
+        <div className="flex items-center gap-1">
+          <span className="text-xs text-muted-foreground">置信度</span>
+          <input type="number" min={0} max={100} value={confidence} onChange={(e) => setConfidence(Number(e.target.value))} className="w-16 h-7 rounded border px-2 text-xs" />
+          <span className="text-xs text-muted-foreground">%</span>
+        </div>
+      </div>
+      <div className="flex gap-1.5">
+        <Button size="sm" onClick={handleAdd} disabled={addFact.isPending || !content.trim()}>
+          {addFact.isPending ? <Loader2 className="size-3 animate-spin" /> : <Check className="size-3" />}确认
+        </Button>
+        <Button size="sm" variant="ghost" onClick={() => setOpen(false)}><X className="size-3" />取消</Button>
+      </div>
+    </div>
+  );
+}
+
+export function V1BucketView({
+  data,
+  agent,
+  userId,
+}: {
+  data: Record<string, unknown>;
+  agent: string | null;
+  userId: string;
+}) {
+  const updateSection = useAdminUpdateV1Section(userId);
+
+  const ctxRaw = (data.user ?? data.userContext ?? {}) as Record<string, unknown>;
+  const historyRaw = (data.history ?? {}) as Record<string, unknown>;
+  const factsRaw = Array.isArray(data.facts) ? (data.facts as Record<string, unknown>[]) : [];
+
+  const allCtxFields = ["workContext", "personalContext", "topOfMind"];
+  const allHistoryFields = ["recentMonths", "earlierContext", "longTermBackground"];
+
+  if (!Object.keys(ctxRaw).length && !Object.keys(historyRaw).length && !factsRaw.length) {
+    return <p className="text-muted-foreground py-6 text-center text-sm">暂无 V1 记忆</p>;
+  }
+
+  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>
+        {allCtxFields.map((field) => (
+          <V1SectionField
+            key={field}
+            label={CTX_LABELS[field] ?? field}
+            value={extractSummary(ctxRaw[field])}
+            onSave={(summary) =>
+              updateSection.mutateAsync({ sectionType: "user", field, summary, agent }).then(() => undefined)
+            }
+          />
+        ))}
+      </div>
+
+      {/* 历史摘要字段 */}
+      <div className="rounded-md border p-3 space-y-3">
+        <h4 className="text-xs font-semibold text-muted-foreground">历史摘要</h4>
+        {allHistoryFields.map((field) => (
+          <V1SectionField
+            key={field}
+            label={HISTORY_LABELS[field] ?? field}
+            value={extractSummary(historyRaw[field])}
+            onSave={(summary) =>
+              updateSection.mutateAsync({ sectionType: "history", field, summary, agent }).then(() => undefined)
+            }
+          />
+        ))}
+      </div>
+
+      {/* 事实记录 */}
+      <div className="rounded-md border p-3 space-y-2">
+        <h4 className="text-xs font-semibold text-muted-foreground">事实记录（{factsRaw.length} 条）</h4>
+        {factsRaw.map((fact, i) => (
+          <V1FactItem key={String(fact.id ?? i)} fact={fact} agent={agent} userId={userId} />
+        ))}
+        <V1AddFactForm agent={agent} userId={userId} />
+      </div>
+    </div>
+  );
+}
+
+// ── Memory entry list with inline editing ──────────────────────────────────
+
+export function MemoryEntryList({
+  entries,
+  userId,
+  agent,
+}: {
+  entries: string[];
+  userId: string;
+  agent: string | null;
+}) {
+  const [editIndex, setEditIndex] = useState<number | null>(null);
+  const [editDraft, setEditDraft] = useState("");
+  const [addDraft, setAddDraft] = useState("");
+  const [isAdding, setIsAdding] = useState(false);
+
+  const addMutation = useAdminAddMemoryEntry(userId);
+  const replaceMutation = useAdminReplaceMemoryEntry(userId);
+  const deleteMutation = useAdminDeleteMemoryEntry(userId);
+
+  const isPending =
+    addMutation.isPending || replaceMutation.isPending || deleteMutation.isPending;
+
+  function startEdit(index: number) {
+    setEditIndex(index);
+    setEditDraft(entries[index] ?? "");
+  }
+
+  function cancelEdit() {
+    setEditIndex(null);
+    setEditDraft("");
+  }
+
+  async function confirmEdit(index: number) {
+    const oldText = entries[index];
+    if (!oldText || editDraft.trim() === oldText.trim()) {
+      cancelEdit();
+      return;
+    }
+    try {
+      await replaceMutation.mutateAsync({ oldText, content: editDraft.trim(), agent });
+      cancelEdit();
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "修改失败");
+    }
+  }
+
+  async function handleDelete(entry: string) {
+    try {
+      await deleteMutation.mutateAsync({ oldText: entry, agent });
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "删除失败");
+    }
+  }
+
+  async function handleAdd() {
+    const content = addDraft.trim();
+    if (!content) return;
+    try {
+      await addMutation.mutateAsync({ content, agent });
+      setAddDraft("");
+      setIsAdding(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "新增失败");
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      {entries.length === 0 && !isAdding && (
+        <p className="text-muted-foreground py-6 text-center text-sm">暂无记忆条目</p>
+      )}
+
+      {entries.map((entry, i) => (
+        <div key={i} className="group rounded-md border p-3">
+          {editIndex === i ? (
+            <div className="flex flex-col gap-2">
+              <Textarea
+                value={editDraft}
+                onChange={(e) => setEditDraft(e.target.value)}
+                className="min-h-[80px] text-sm"
+                autoFocus
+              />
+              <div className="flex gap-2">
+                <Button
+                  size="sm"
+                  onClick={() => confirmEdit(i)}
+                  disabled={replaceMutation.isPending}
+                >
+                  {replaceMutation.isPending ? (
+                    <Loader2 className="size-3 animate-spin" />
+                  ) : (
+                    <Check className="size-3" />
+                  )}
+                  保存
+                </Button>
+                <Button size="sm" variant="ghost" onClick={cancelEdit}>
+                  <X className="size-3" />
+                  取消
+                </Button>
+              </div>
+            </div>
+          ) : (
+            <div className="flex items-start gap-2">
+              <span className="text-muted-foreground mt-0.5 shrink-0 text-sm">·</span>
+              <span className="flex-1 whitespace-pre-wrap text-sm">{entry}</span>
+              <div className="flex shrink-0 gap-1 opacity-0 transition-opacity group-hover:opacity-100">
+                <Button
+                  size="icon"
+                  variant="ghost"
+                  className="size-7"
+                  onClick={() => startEdit(i)}
+                  disabled={isPending}
+                >
+                  <Pencil className="size-3" />
+                </Button>
+                <Button
+                  size="icon"
+                  variant="ghost"
+                  className="size-7 hover:text-destructive"
+                  onClick={() => handleDelete(entry)}
+                  disabled={isPending}
+                >
+                  {deleteMutation.isPending ? (
+                    <Loader2 className="size-3 animate-spin" />
+                  ) : (
+                    <Trash2 className="size-3" />
+                  )}
+                </Button>
+              </div>
+            </div>
+          )}
+        </div>
+      ))}
+
+      {isAdding ? (
+        <div className="flex flex-col gap-2 rounded-md border p-3">
+          <Textarea
+            placeholder="输入新记忆条目内容…"
+            value={addDraft}
+            onChange={(e) => setAddDraft(e.target.value)}
+            className="min-h-[80px] text-sm"
+            autoFocus
+          />
+          <div className="flex gap-2">
+            <Button size="sm" onClick={handleAdd} disabled={addMutation.isPending || !addDraft.trim()}>
+              {addMutation.isPending ? <Loader2 className="size-3 animate-spin" /> : <Check className="size-3" />}
+              确认
+            </Button>
+            <Button size="sm" variant="ghost" onClick={() => { setIsAdding(false); setAddDraft(""); }}>
+              <X className="size-3" />
+              取消
+            </Button>
+          </div>
+        </div>
+      ) : (
+        <Button
+          variant="outline"
+          size="sm"
+          className="mt-1 w-full"
+          onClick={() => setIsAdding(true)}
+          disabled={isPending}
+        >
+          <Plus className="size-3" />
+          新增条目
+        </Button>
+      )}
+    </div>
+  );
+}
+
+// ── Right panel: memory tabs for a selected user ───────────────────────────
+
+export function UserMemoryPanel({ userId }: { userId: string }) {
+  const { data: memory, isLoading } = useUserMemory(userId);
+  const [selectedAgent, setSelectedAgent] = useState<string | null>(null);
+
+  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";
+  const globalBucket = memory?.buckets.find((b) => b.name === "global");
+  const agentBuckets = (memory?.buckets ?? []).filter((b) => b.name !== "global");
+
+  // ── V1 只读视图 ──────────────────────────────────────────────────────────
+  if (isV1) {
+    const currentAgent = selectedAgent ?? agentBuckets[0]?.name ?? null;
+    const currentBucket = currentAgent
+      ? agentBuckets.find((b) => b.name === currentAgent)
+      : globalBucket;
+
+    return (
+      <Tabs defaultValue="global" className="flex flex-1 flex-col overflow-hidden">
+        <div className="border-b px-4 pt-4">
+          <div className="mb-2 rounded-md bg-amber-50 border border-amber-200 px-3 py-1.5 text-xs text-amber-700">
+            V1 模式：记忆由系统自动提取，不支持手动管理
+          </div>
+          <TabsList variant="line">
+            <TabsTrigger value="global">用户记忆</TabsTrigger>
+            {agentBuckets.length > 0 && (
+              <TabsTrigger value="agent">
+                Agent 记忆
+                <Badge variant="secondary" className="ml-1.5 text-xs">
+                  {agentBuckets.length}
+                </Badge>
+              </TabsTrigger>
+            )}
+          </TabsList>
+        </div>
+
+        <TabsContent value="global" className="flex-1 overflow-hidden p-0">
+          <ScrollArea className="h-full">
+            <div className="p-4">
+              {globalBucket ? <V1BucketView data={globalBucket.data} agent={null} userId={userId} /> : (
+                <p className="text-muted-foreground py-6 text-center text-sm">暂无数据</p>
+              )}
+            </div>
+          </ScrollArea>
+        </TabsContent>
+
+        {agentBuckets.length > 0 && (
+          <TabsContent value="agent" className="flex-1 overflow-hidden p-0">
+            <ScrollArea className="h-full">
+              <div className="p-4">
+                <div className="mb-3 flex items-center gap-2">
+                  <span className="text-muted-foreground text-xs">选择 Agent：</span>
+                  <Select value={currentAgent ?? ""} onValueChange={(v) => setSelectedAgent(v)}>
+                    <SelectTrigger className="h-7 w-48 text-xs">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {agentBuckets.map((b) => (
+                        <SelectItem key={b.name} value={b.name} className="text-xs">
+                          {b.display_name || b.name}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </div>
+                {currentBucket && <V1BucketView data={currentBucket.data} agent={currentAgent} userId={userId} />}
+              </div>
+            </ScrollArea>
+          </TabsContent>
+        )}
+      </Tabs>
+    );
+  }
+
+  // ── V2 可编辑视图 ────────────────────────────────────────────────────────
+  const userEntries = globalBucket ? getEntries(globalBucket.data) : [];
+  const currentAgent = selectedAgent ?? agentBuckets[0]?.name ?? null;
+  const agentBucket = agentBuckets.find((b) => b.name === currentAgent);
+  const agentEntries = agentBucket ? getEntries(agentBucket.data) : [];
+
+  return (
+    <Tabs defaultValue="user" className="flex flex-1 flex-col overflow-hidden">
+      <div className="border-b px-4 pt-4">
+        <TabsList variant="line">
+          <TabsTrigger value="user">
+            用户画像
+            {userEntries.length > 0 && (
+              <Badge variant="secondary" className="ml-1.5 text-xs">
+                {userEntries.length}
+              </Badge>
+            )}
+          </TabsTrigger>
+          <TabsTrigger value="agent">
+            Agent 记忆
+            {agentBuckets.length > 0 && (
+              <Badge variant="secondary" className="ml-1.5 text-xs">
+                {agentBuckets.length}
+              </Badge>
+            )}
+          </TabsTrigger>
+        </TabsList>
+      </div>
+
+      <TabsContent value="user" className="flex-1 overflow-hidden p-0">
+        <ScrollArea className="h-full">
+          <div className="p-4">
+            <p className="text-muted-foreground mb-3 text-xs">
+              USER.md — 跨 Agent 共享的用户画像
+            </p>
+            <MemoryEntryList entries={userEntries} userId={userId} agent={null} />
+          </div>
+        </ScrollArea>
+      </TabsContent>
+
+      <TabsContent value="agent" className="flex-1 overflow-hidden p-0">
+        <ScrollArea className="h-full">
+          <div className="p-4">
+            {agentBuckets.length === 0 ? (
+              <p className="text-muted-foreground py-6 text-center text-sm">该用户暂无 Agent 记忆</p>
+            ) : (
+              <>
+                <div className="mb-3 flex items-center gap-2">
+                  <span className="text-muted-foreground text-xs">选择 Agent：</span>
+                  <Select
+                    value={currentAgent ?? ""}
+                    onValueChange={(v) => setSelectedAgent(v)}
+                  >
+                    <SelectTrigger className="h-7 w-48 text-xs">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {agentBuckets.map((b) => (
+                        <SelectItem key={b.name} value={b.name} className="text-xs">
+                          {b.display_name || b.name}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                  <span className="text-muted-foreground text-xs">— MEMORY.md</span>
+                </div>
+                {currentAgent && (
+                  <MemoryEntryList entries={agentEntries} userId={userId} agent={currentAgent} />
+                )}
+              </>
+            )}
+          </div>
+        </ScrollArea>
+      </TabsContent>
+    </Tabs>
+  );
+}
+
+// ── Main page ──────────────────────────────────────────────────────────────
+
+export default function AdminMemoryPage() {
+  const { data: users, isLoading: usersLoading } = useAllUsers(true);
+  const [selectedUserId, setSelectedUserId] = useState<string | null>(null);
+  const [userQuery, setUserQuery] = useState("");
+
+  const filteredUsers = (users ?? []).filter((u) =>
+    u.email.toLowerCase().includes(userQuery.toLowerCase()),
+  );
+
+  return (
+    <div className="flex h-full">
+      {/* Left: user list */}
+      <div className="flex w-64 shrink-0 flex-col border-r">
+        <div className="border-b p-3">
+          <Input
+            placeholder="搜索用户…"
+            value={userQuery}
+            onChange={(e) => setUserQuery(e.target.value)}
+            className="h-8 text-sm"
+          />
+        </div>
+        <ScrollArea className="flex-1">
+          {usersLoading && (
+            <div className="text-muted-foreground flex items-center justify-center gap-2 py-10 text-sm">
+              <Loader2 className="size-4 animate-spin" />
+              加载中…
+            </div>
+          )}
+          {!usersLoading && filteredUsers.length === 0 && (
+            <p className="text-muted-foreground py-8 text-center text-sm">暂无用户</p>
+          )}
+          {filteredUsers.map((user) => (
+            <button
+              key={user.id}
+              className={`flex w-full flex-col items-start gap-0.5 px-3 py-2.5 text-left text-sm transition-colors hover:bg-accent ${
+                selectedUserId === user.id ? "bg-accent font-medium" : ""
+              }`}
+              onClick={() => setSelectedUserId(user.id)}
+            >
+              <span className="max-w-full truncate">{user.email}</span>
+              {user.system_role === "admin" && (
+                <Badge variant="default" className="h-4 px-1 text-[10px]">
+                  Admin
+                </Badge>
+              )}
+            </button>
+          ))}
+        </ScrollArea>
+      </div>
+
+      {/* Right: memory tabs */}
+      <div className="flex flex-1 flex-col overflow-hidden">
+        {selectedUserId ? (
+          <UserMemoryPanel key={selectedUserId} userId={selectedUserId} />
+        ) : (
+          <div className="text-muted-foreground flex flex-1 items-center justify-center text-sm">
+            请在左侧选择用户
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

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">
+              <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>
+                {/* 默认助手始终显示，对应全局记忆文件 */}
+                <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

@@ -0,0 +1,293 @@
+"use client";
+
+import { Loader2, PencilIcon, PlusIcon, Trash2Icon } from "lucide-react";
+import { useState } from "react";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { Textarea } from "@/components/ui/textarea";
+import { SettingsSection } from "@/components/workspace/settings/settings-section";
+import { TagChip } from "@/components/workspace/tags/tag-chip";
+import { TAG_COLORS } from "@/components/workspace/tags/tag-colors";
+import { useI18n } from "@/core/i18n/hooks";
+import {
+  useCreateTag,
+  useDeleteTag,
+  useTags,
+  useUpdateTag,
+  type Tag,
+  type TagType,
+} from "@/core/tags";
+import { cn } from "@/lib/utils";
+
+function TagFormDialog({
+  open,
+  onOpenChange,
+  tagType,
+  editing,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  tagType: TagType;
+  editing: Tag | null;
+}) {
+  const { t } = useI18n();
+  const createTag = useCreateTag();
+  const updateTag = useUpdateTag();
+  const [name, setName] = useState("");
+  const [color, setColor] = useState("gray");
+  const [description, setDescription] = useState("");
+
+  // Sync form state whenever the dialog (re)opens.
+  const [syncedFor, setSyncedFor] = useState<string | null>(null);
+  const syncKey = `${open}:${editing?.id ?? "new"}`;
+  if (open && syncedFor !== syncKey) {
+    setName(editing?.name ?? "");
+    setColor(editing?.color ?? "gray");
+    setDescription(editing?.description ?? "");
+    setSyncedFor(syncKey);
+  }
+  if (!open && syncedFor !== null) setSyncedFor(null);
+
+  const pending = createTag.isPending || updateTag.isPending;
+
+  const handleSave = async () => {
+    const trimmed = name.trim();
+    if (!trimmed) return;
+    try {
+      if (editing) {
+        await updateTag.mutateAsync({
+          id: editing.id,
+          input: { name: trimmed, color, description },
+        });
+      } else {
+        await createTag.mutateAsync({
+          name: trimmed,
+          tag_type: tagType,
+          color,
+          description,
+        });
+      }
+      onOpenChange(false);
+    } catch (e) {
+      toast.error(String(e instanceof Error ? e.message : e));
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>
+            {editing ? t.adminTags.editTitle : t.adminTags.createTitle}
+          </DialogTitle>
+        </DialogHeader>
+        <div className="flex flex-col gap-4">
+          <div className="flex flex-col gap-1.5">
+            <label className="text-sm font-medium">{t.adminTags.name}</label>
+            <Input
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              placeholder={t.adminTags.namePlaceholder}
+              maxLength={256}
+            />
+          </div>
+          <div className="flex flex-col gap-1.5">
+            <label className="text-sm font-medium">{t.adminTags.color}</label>
+            <div className="flex flex-wrap gap-2">
+              {TAG_COLORS.map((c) => (
+                <button
+                  key={c.name}
+                  type="button"
+                  onClick={() => setColor(c.name)}
+                  aria-label={c.name}
+                  className={cn(
+                    "size-6 rounded-full border-2",
+                    c.swatch,
+                    color === c.name
+                      ? "border-foreground"
+                      : "border-transparent",
+                  )}
+                />
+              ))}
+            </div>
+          </div>
+          <div className="flex flex-col gap-1.5">
+            <label className="text-sm font-medium">
+              {t.adminTags.tagDescription}
+            </label>
+            <Textarea
+              value={description}
+              onChange={(e) => setDescription(e.target.value)}
+              placeholder={t.adminTags.descriptionPlaceholder}
+              maxLength={1024}
+              rows={2}
+            />
+          </div>
+          {name.trim() && (
+            <div className="flex items-center gap-2">
+              <span className="text-muted-foreground text-xs">Preview:</span>
+              <TagChip tag={{ name: name.trim(), color }} />
+            </div>
+          )}
+        </div>
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>
+            {t.adminTags.cancel}
+          </Button>
+          <Button onClick={handleSave} disabled={pending || !name.trim()}>
+            {pending && <Loader2 className="size-4 animate-spin" />}
+            {t.adminTags.save}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export function TagManagementPage() {
+  const { t } = useI18n();
+  const [activeType, setActiveType] = useState<TagType>("agent");
+  const { data: tags, isLoading, error } = useTags(activeType);
+  const deleteTag = useDeleteTag();
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [editing, setEditing] = useState<Tag | null>(null);
+
+  const openCreate = () => {
+    setEditing(null);
+    setDialogOpen(true);
+  };
+  const openEdit = (tag: Tag) => {
+    setEditing(tag);
+    setDialogOpen(true);
+  };
+  const handleDelete = async (tag: Tag) => {
+    if (!window.confirm(t.adminTags.deleteConfirm)) return;
+    try {
+      await deleteTag.mutateAsync(tag.id);
+    } catch (e) {
+      toast.error(String(e instanceof Error ? e.message : e));
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-6 p-6">
+      <SettingsSection
+        title={t.adminTags.title}
+        description={t.adminTags.description}
+      >
+        <div className="flex items-center justify-between gap-4">
+          <Tabs
+            value={activeType}
+            onValueChange={(v) => setActiveType(v as TagType)}
+          >
+            <TabsList variant="line">
+              <TabsTrigger value="agent">{t.adminTags.typeAgent}</TabsTrigger>
+              <TabsTrigger value="skill">{t.adminTags.typeSkill}</TabsTrigger>
+              <TabsTrigger value="scheduled_task">
+                {t.adminTags.typeScheduledTask}
+              </TabsTrigger>
+            </TabsList>
+          </Tabs>
+          <Button size="sm" onClick={openCreate}>
+            <PlusIcon className="size-4" />
+            {t.adminTags.createButton}
+          </Button>
+        </div>
+
+        <div className="mt-4">
+          {isLoading && (
+            <div className="text-muted-foreground flex items-center justify-center gap-2 py-8">
+              <Loader2 className="size-4 animate-spin" />
+              <span>{t.common.loading}</span>
+            </div>
+          )}
+          {error && (
+            <div className="text-destructive py-4 text-sm">{String(error)}</div>
+          )}
+          {!isLoading && !error && tags && tags.length === 0 && (
+            <div className="text-muted-foreground py-8 text-center text-sm">
+              {t.adminTags.empty}
+            </div>
+          )}
+          {!isLoading && !error && tags && tags.length > 0 && (
+            <div className="overflow-hidden rounded-md border">
+              <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">
+                      {t.adminTags.name}
+                    </th>
+                    <th className="text-muted-foreground px-4 py-3 text-left font-medium">
+                      {t.adminTags.tagDescription}
+                    </th>
+                    <th className="text-muted-foreground px-4 py-3 text-right font-medium">
+                      {t.adminTags.usageCount}
+                    </th>
+                    <th className="text-muted-foreground px-4 py-3 text-right font-medium">
+                      {t.adminTags.actions}
+                    </th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {tags.map((tag, i) => (
+                    <tr
+                      key={tag.id}
+                      className={i % 2 === 0 ? "bg-background" : "bg-muted/20"}
+                    >
+                      <td className="px-4 py-3">
+                        <TagChip tag={tag} />
+                      </td>
+                      <td className="text-muted-foreground px-4 py-3">
+                        {tag.description || "—"}
+                      </td>
+                      <td className="px-4 py-3 text-right tabular-nums">
+                        {tag.usage_count}
+                      </td>
+                      <td className="px-4 py-3 text-right">
+                        <div className="flex justify-end gap-1">
+                          <Button
+                            variant="ghost"
+                            size="icon"
+                            onClick={() => openEdit(tag)}
+                            aria-label={t.adminTags.edit}
+                          >
+                            <PencilIcon className="size-4" />
+                          </Button>
+                          <Button
+                            variant="ghost"
+                            size="icon"
+                            onClick={() => handleDelete(tag)}
+                            aria-label={t.adminTags.delete}
+                          >
+                            <Trash2Icon className="text-destructive size-4" />
+                          </Button>
+                        </div>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </div>
+      </SettingsSection>
+
+      <TagFormDialog
+        open={dialogOpen}
+        onOpenChange={setDialogOpen}
+        tagType={activeType}
+        editing={editing}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,604 @@
+"use client";
+
+import { Download, Loader2 } from "lucide-react";
+import { useMemo, useState } from "react";
+import { toast } from "sonner";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  downloadToolMetricsExcel,
+  TOOL_ERROR_CATEGORIES,
+  TOOL_ERROR_CATEGORY_LABELS,
+  type ToolMetric,
+  type ToolMetricsFilters,
+} from "@/core/tool-metrics/api";
+import { useToolMetrics, useToolMetricsSummary } from "@/core/tool-metrics/hooks";
+import { cn } from "@/lib/utils";
+
+const PAGE_SIZE = 50;
+
+type StatusFilter = "all" | "success" | "error";
+type KindFilter = "skill" | "all";
+
+function displayUser(row: { user_name?: string | null; user_id?: string | null }): string {
+  if (row.user_name && row.user_name.trim()) return row.user_name.trim();
+  const id = (row.user_id ?? "").trim();
+  return id || "—";
+}
+
+function formatDate(value?: string | null): string {
+  if (!value) return "—";
+  try {
+    return new Date(value).toLocaleString();
+  } catch {
+    return value;
+  }
+}
+
+function formatDuration(value?: number | null): string {
+  if (value === null || value === undefined || Number.isNaN(value)) return "—";
+  if (value === 0) return "0 ms";
+  if (value < 1000) return `${value} ms`;
+  if (value < 60_000) return `${(value / 1000).toFixed(1)} s`;
+  const minutes = Math.floor(value / 60_000);
+  const seconds = Math.round((value % 60_000) / 1000);
+  return `${minutes}m ${seconds}s`;
+}
+
+function categoryLabel(category?: string | null): string {
+  if (!category) return "—";
+  return TOOL_ERROR_CATEGORY_LABELS[category] ?? category;
+}
+
+export function ToolMetricsPanel() {
+  const [page, setPage] = useState(0);
+  const [tool, setTool] = useState("");
+  const [user, setUser] = useState("");
+  const [skill, setSkill] = useState("");
+  // Default to skill-only — the table is otherwise flooded with low-level
+  // bash / file-op calls. "全部" reveals every tool invocation.
+  const [kind, setKind] = useState<KindFilter>("skill");
+  const [status, setStatus] = useState<StatusFilter>("all");
+  const [category, setCategory] = useState<string>("all");
+  const [since, setSince] = useState("");
+  const [until, setUntil] = useState("");
+  const [exporting, setExporting] = useState(false);
+  const [detailRow, setDetailRow] = useState<ToolMetric | null>(null);
+
+  const filters = useMemo<ToolMetricsFilters>(() => {
+    const out: ToolMetricsFilters = {};
+    if (tool.trim()) out.tool_name = tool.trim();
+    if (user.trim()) out.user_name = user.trim();
+    if (skill.trim()) out.skill_name = skill.trim();
+    if (kind !== "all") out.kind = kind;
+    if (status !== "all") out.status = status;
+    if (category !== "all") out.error_category = category;
+    if (since) out.since = new Date(since).toISOString();
+    if (until) out.until = new Date(until).toISOString();
+    return out;
+  }, [tool, user, skill, kind, status, category, since, until]);
+
+  const query = useMemo(
+    () => ({ ...filters, limit: PAGE_SIZE, offset: page * PAGE_SIZE }),
+    [filters, page],
+  );
+
+  const { data, isLoading, error, isFetching } = useToolMetrics(query);
+  // The summary ignores the status/category filter so the breakdown always
+  // reflects the full failure picture for the chosen tool/user/time window.
+  const summaryFilters = useMemo<ToolMetricsFilters>(() => {
+    const out: ToolMetricsFilters = {};
+    if (tool.trim()) out.tool_name = tool.trim();
+    if (user.trim()) out.user_name = user.trim();
+    if (skill.trim()) out.skill_name = skill.trim();
+    if (kind !== "all") out.kind = kind;
+    if (since) out.since = new Date(since).toISOString();
+    if (until) out.until = new Date(until).toISOString();
+    return out;
+  }, [tool, user, skill, kind, since, until]);
+  const { data: summary } = useToolMetricsSummary(summaryFilters);
+
+  const handleExport = async () => {
+    setExporting(true);
+    try {
+      await downloadToolMetricsExcel(filters);
+      toast.success("已导出为 Excel");
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "导出失败");
+    } finally {
+      setExporting(false);
+    }
+  };
+
+  const resetFilters = () => {
+    setTool("");
+    setUser("");
+    setSkill("");
+    setKind("skill");
+    setStatus("all");
+    setCategory("all");
+    setSince("");
+    setUntil("");
+    setPage(0);
+  };
+
+  const items = data?.items ?? [];
+  const total = data?.total ?? 0;
+  const totalPages = Math.max(1, Math.ceil(total / PAGE_SIZE));
+
+  const errorRate =
+    summary && summary.total > 0
+      ? ((summary.error_total / summary.total) * 100).toFixed(1)
+      : "0.0";
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-wrap items-end justify-between gap-3">
+        <div>
+          <h2 className="text-lg font-semibold">工具调用统计</h2>
+          <p className="text-muted-foreground mt-1 text-sm">
+            记录每一次工具 / 技能 / MCP 调用，并对失败进行归类：检索为空、IP
+            被封、限流、超时、鉴权失败等。后台无条件记录。
+          </p>
+        </div>
+        <Button onClick={handleExport} disabled={exporting}>
+          {exporting ? (
+            <Loader2 className="mr-1 size-4 animate-spin" />
+          ) : (
+            <Download className="mr-1 size-4" />
+          )}
+          导出 Excel
+        </Button>
+      </div>
+
+      {/* Summary strip */}
+      <div className="flex flex-wrap items-center gap-2 rounded-xl border bg-white p-4">
+        <div className="mr-4 flex flex-col">
+          <span className="text-muted-foreground text-xs">总调用</span>
+          <span className="text-lg font-semibold tabular-nums">
+            {summary?.total ?? "—"}
+          </span>
+        </div>
+        <div className="mr-4 flex flex-col">
+          <span className="text-muted-foreground text-xs">失败数</span>
+          <span className="text-destructive text-lg font-semibold tabular-nums">
+            {summary?.error_total ?? "—"}
+          </span>
+        </div>
+        <div className="mr-4 flex flex-col">
+          <span className="text-muted-foreground text-xs">失败率</span>
+          <span className="text-lg font-semibold tabular-nums">{errorRate}%</span>
+        </div>
+        <div className="flex flex-1 flex-wrap items-center gap-1.5">
+          {summary && Object.keys(summary.by_category).length === 0 && (
+            <span className="text-muted-foreground text-sm">暂无失败记录 🎉</span>
+          )}
+          {summary &&
+            Object.entries(summary.by_category)
+              .sort((a, b) => b[1] - a[1])
+              .map(([cat, count]) => (
+                <button
+                  key={cat}
+                  type="button"
+                  onClick={() => {
+                    setCategory(cat);
+                    setStatus("error");
+                    setPage(0);
+                  }}
+                  className="hover:bg-muted inline-flex items-center gap-1 rounded-full border px-2.5 py-1 text-xs"
+                >
+                  <span>{categoryLabel(cat)}</span>
+                  <span className="text-destructive font-semibold tabular-nums">
+                    {count}
+                  </span>
+                </button>
+              ))}
+        </div>
+      </div>
+
+      {/* 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">
+          <h3 className="mb-2 text-sm font-medium">各技能调用情况</h3>
+          <div className="overflow-x-auto">
+            <table className="w-full text-sm">
+              <thead className="text-muted-foreground">
+                <tr>
+                  <th className="px-2 py-1 text-left text-xs font-medium">技能名称</th>
+                  <th className="px-2 py-1 text-right text-xs font-medium">调用次数</th>
+                  <th className="px-2 py-1 text-right text-xs font-medium">成功</th>
+                  <th className="px-2 py-1 text-right text-xs font-medium">失败</th>
+                  <th className="px-2 py-1 text-right text-xs font-medium">成功率</th>
+                </tr>
+              </thead>
+              <tbody>
+                {summary.by_skill.map((s) => {
+                  const rate =
+                    s.total > 0 ? ((s.success / s.total) * 100).toFixed(0) : "0";
+                  return (
+                    <tr
+                      key={s.skill_name}
+                      className="hover:bg-muted cursor-pointer border-t"
+                      title="点击只看该技能"
+                      onClick={() => {
+                        setSkill(s.skill_name);
+                        setPage(0);
+                      }}
+                    >
+                      <td className="px-2 py-1.5 font-medium">{s.skill_name}</td>
+                      <td className="px-2 py-1.5 text-right tabular-nums">{s.total}</td>
+                      <td className="px-2 py-1.5 text-right tabular-nums text-green-600">
+                        {s.success}
+                      </td>
+                      <td className="text-destructive px-2 py-1.5 text-right tabular-nums">
+                        {s.error}
+                      </td>
+                      <td className="px-2 py-1.5 text-right tabular-nums">{rate}%</td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          </div>
+        </div>
+      )}
+      {summary && kind === "skill" && summary.by_skill.length === 0 && (
+        <div className="text-muted-foreground rounded-xl border bg-white p-4 text-sm">
+          当前筛选范围内没有检测到任何技能调用记录。技能只有在被 Agent 通过
+          <code className="bg-muted mx-1 rounded px-1">skill_view</code>
+          读取(即真正"调用")时才会被记录;仅在系统提示里被列出、但未被读取的技能不会计入。
+        </div>
+      )}
+
+      {/* Filters */}
+      <div className="grid gap-3 rounded-xl border bg-white p-4 md:grid-cols-3 lg:grid-cols-6">
+        <div className="flex flex-col gap-1">
+          <label className="text-muted-foreground text-xs">调用类型</label>
+          <Select
+            value={kind}
+            onValueChange={(value) => {
+              setKind(value as KindFilter);
+              setPage(0);
+            }}
+          >
+            <SelectTrigger>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <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>
+          <Input
+            value={skill}
+            placeholder="按技能名筛选"
+            onChange={(e) => {
+              setSkill(e.target.value);
+              setPage(0);
+            }}
+          />
+        </div>
+        <div className="flex flex-col gap-1">
+          <label className="text-muted-foreground text-xs">工具名</label>
+          <Input
+            value={tool}
+            placeholder="按工具名筛选"
+            onChange={(e) => {
+              setTool(e.target.value);
+              setPage(0);
+            }}
+          />
+        </div>
+        <div className="flex flex-col gap-1">
+          <label className="text-muted-foreground text-xs">用户名</label>
+          <Input
+            value={user}
+            placeholder="@ 前部分"
+            onChange={(e) => {
+              setUser(e.target.value);
+              setPage(0);
+            }}
+          />
+        </div>
+        <div className="flex flex-col gap-1">
+          <label className="text-muted-foreground text-xs">状态</label>
+          <Select
+            value={status}
+            onValueChange={(value) => {
+              setStatus(value as StatusFilter);
+              setPage(0);
+            }}
+          >
+            <SelectTrigger>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="all">全部</SelectItem>
+              <SelectItem value="success">成功</SelectItem>
+              <SelectItem value="error">失败</SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+        <div className="flex flex-col gap-1">
+          <label className="text-muted-foreground text-xs">错误类型</label>
+          <Select
+            value={category}
+            onValueChange={(value) => {
+              setCategory(value);
+              setPage(0);
+            }}
+          >
+            <SelectTrigger>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="all">全部</SelectItem>
+              {TOOL_ERROR_CATEGORIES.map((cat) => (
+                <SelectItem key={cat} value={cat}>
+                  {categoryLabel(cat)}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+        <div className="flex flex-col gap-1">
+          <label className="text-muted-foreground text-xs">开始时间</label>
+          <Input
+            type="datetime-local"
+            value={since}
+            onChange={(e) => {
+              setSince(e.target.value);
+              setPage(0);
+            }}
+          />
+        </div>
+        <div className="flex flex-col gap-1">
+          <label className="text-muted-foreground text-xs">结束时间</label>
+          <Input
+            type="datetime-local"
+            value={until}
+            onChange={(e) => {
+              setUntil(e.target.value);
+              setPage(0);
+            }}
+          />
+        </div>
+        <div className="flex justify-end lg:col-span-6">
+          <Button variant="outline" size="sm" onClick={resetFilters}>
+            清空筛选
+          </Button>
+        </div>
+      </div>
+
+      {/* Table */}
+      <div className="rounded-xl border bg-white">
+        <div className="overflow-x-auto">
+          <table className="w-full min-w-[960px] text-sm">
+            <thead className="bg-muted/60 text-muted-foreground">
+              <tr>
+                <Th>时间</Th>
+                <Th>用户</Th>
+                <Th>Agent</Th>
+                <Th>技能</Th>
+                <Th>工具</Th>
+                <Th className="text-right">耗时</Th>
+                <Th>状态</Th>
+                <Th>错误类型</Th>
+                <Th>错误详情</Th>
+              </tr>
+            </thead>
+            <tbody>
+              {isLoading && (
+                <tr>
+                  <td colSpan={9} className="py-10 text-center">
+                    <Loader2 className="text-muted-foreground inline size-5 animate-spin" />
+                  </td>
+                </tr>
+              )}
+              {!isLoading && error && (
+                <tr>
+                  <td colSpan={9} className="text-destructive py-10 text-center text-sm">
+                    加载失败：{error.message}
+                  </td>
+                </tr>
+              )}
+              {!isLoading && !error && items.length === 0 && (
+                <tr>
+                  <td colSpan={9} className="text-muted-foreground py-10 text-center text-sm">
+                    暂无符合条件的调用记录。
+                  </td>
+                </tr>
+              )}
+              {items.map((row) => (
+                <tr key={row.id} className="border-t">
+                  <Td>{formatDate(row.created_at)}</Td>
+                  <Td title={row.user_id ?? undefined}>{displayUser(row)}</Td>
+                  <Td>{row.agent_name ?? "—"}</Td>
+                  <Td className="font-medium">
+                    {row.skill_name ? (
+                      <button
+                        type="button"
+                        onClick={() => {
+                          setSkill(row.skill_name as string);
+                          setPage(0);
+                        }}
+                        className="hover:text-foreground underline-offset-2 hover:underline"
+                        title="点击只看该技能"
+                      >
+                        {row.skill_name}
+                      </button>
+                    ) : (
+                      <span className="text-muted-foreground">—</span>
+                    )}
+                  </Td>
+                  <Td className="font-mono text-xs">{row.tool_name ?? "—"}</Td>
+                  <Td className="text-right tabular-nums" title={`${row.duration_ms} ms`}>
+                    {formatDuration(row.duration_ms)}
+                  </Td>
+                  <Td>
+                    <Badge variant={row.status === "success" ? "default" : "destructive"}>
+                      {row.status === "success" ? "成功" : "失败"}
+                    </Badge>
+                  </Td>
+                  <Td>
+                    {row.error_category ? (
+                      <Badge variant="outline">{categoryLabel(row.error_category)}</Badge>
+                    ) : (
+                      "—"
+                    )}
+                  </Td>
+                  <Td className="max-w-[300px]">
+                    {row.error_message ? (
+                      <button
+                        type="button"
+                        onClick={() => setDetailRow(row)}
+                        className="text-muted-foreground hover:text-foreground block max-w-full truncate text-left underline-offset-2 hover:underline"
+                        title="点击查看完整报错"
+                      >
+                        {row.error_message}
+                      </button>
+                    ) : (
+                      <span className="text-muted-foreground">—</span>
+                    )}
+                  </Td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+        <div className="flex items-center justify-between border-t px-4 py-2 text-xs">
+          <span className="text-muted-foreground">
+            {isFetching && !isLoading ? "更新中..." : `共 ${total} 条`}
+          </span>
+          <div className="flex items-center gap-2">
+            <Button
+              size="sm"
+              variant="outline"
+              disabled={page <= 0 || isLoading}
+              onClick={() => setPage((p) => Math.max(0, p - 1))}
+            >
+              上一页
+            </Button>
+            <span className="text-muted-foreground">
+              第 {page + 1} / {totalPages} 页
+            </span>
+            <Button
+              size="sm"
+              variant="outline"
+              disabled={page + 1 >= totalPages || isLoading}
+              onClick={() => setPage((p) => p + 1)}
+            >
+              下一页
+            </Button>
+          </div>
+        </div>
+      </div>
+
+      {/* Full error detail popup */}
+      <Dialog
+        open={detailRow !== null}
+        onOpenChange={(open) => {
+          if (!open) setDetailRow(null);
+        }}
+      >
+        <DialogContent className="max-w-2xl">
+          <DialogHeader>
+            <DialogTitle>工具调用报错详情</DialogTitle>
+          </DialogHeader>
+          {detailRow && (
+            <div className="flex flex-col gap-3 text-sm">
+              <div className="grid grid-cols-2 gap-x-4 gap-y-2">
+                <DetailField label="时间" value={formatDate(detailRow.created_at)} />
+                <DetailField label="用户" value={displayUser(detailRow)} />
+                <DetailField label="工具" value={detailRow.tool_name ?? "—"} mono />
+                <DetailField label="技能" value={detailRow.skill_name ?? "—"} />
+                <DetailField label="Agent" value={detailRow.agent_name ?? "—"} />
+                <DetailField
+                  label="状态"
+                  value={detailRow.status === "success" ? "成功" : "失败"}
+                />
+                <DetailField
+                  label="错误类型"
+                  value={categoryLabel(detailRow.error_category)}
+                />
+                <DetailField label="耗时" value={formatDuration(detailRow.duration_ms)} />
+                <DetailField label="Thread" value={detailRow.thread_id ?? "—"} mono />
+              </div>
+              <div>
+                <span className="text-muted-foreground text-xs">完整报错信息</span>
+                <pre className="bg-muted mt-1 max-h-72 overflow-auto whitespace-pre-wrap break-all rounded-md p-3 text-xs">
+                  {detailRow.error_message ?? "（无）"}
+                </pre>
+              </div>
+            </div>
+          )}
+        </DialogContent>
+      </Dialog>
+    </div>
+  );
+}
+
+function DetailField({
+  label,
+  value,
+  mono,
+}: {
+  label: string;
+  value: string;
+  mono?: boolean;
+}) {
+  return (
+    <div className="flex flex-col">
+      <span className="text-muted-foreground text-xs">{label}</span>
+      <span className={cn("break-all", mono && "font-mono text-xs")}>{value}</span>
+    </div>
+  );
+}
+
+function Th({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) {
+  return (
+    <th className={`px-3 py-2 text-left text-xs font-medium ${className ?? ""}`}>
+      {children}
+    </th>
+  );
+}
+
+function Td({
+  children,
+  className,
+  title,
+}: {
+  children: React.ReactNode;
+  className?: string;
+  title?: string;
+}) {
+  return (
+    <td className={cn("px-3 py-2 align-top text-sm", className)} title={title}>
+      {children}
+    </td>
+  );
+}

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

@@ -0,0 +1,79 @@
+"use client";
+
+import { Loader2 } from "lucide-react";
+
+import { Badge } from "@/components/ui/badge";
+import { SettingsSection } from "@/components/workspace/settings/settings-section";
+import { useAllUsers } from "@/core/auth/hooks";
+import { useI18n } from "@/core/i18n/hooks";
+
+export function UserManagementPage() {
+  const { t } = useI18n();
+  const { data: users, isLoading, error } = useAllUsers(true);
+
+  return (
+    <div className="flex flex-col gap-6 p-6">
+      <SettingsSection
+        title={t.adminUsers.title}
+        description={t.adminUsers.description}
+      >
+        {isLoading && (
+          <div className="flex items-center gap-2 text-muted-foreground py-8 justify-center">
+            <Loader2 className="h-4 w-4 animate-spin" />
+            <span>{t.common.loading}</span>
+          </div>
+        )}
+
+        {error && (
+          <div className="text-destructive text-sm py-4">
+            {String(error)}
+          </div>
+        )}
+
+        {!isLoading && !error && users && users.length === 0 && (
+          <div className="text-muted-foreground text-sm py-8 text-center">
+            {t.adminUsers.empty}
+          </div>
+        )}
+
+        {!isLoading && !error && users && users.length > 0 && (
+          <div className="rounded-md border overflow-hidden">
+            <table className="w-full text-sm">
+              <thead className="bg-muted/50">
+                <tr>
+                  <th className="text-left px-4 py-3 font-medium text-muted-foreground">{t.adminUsers.email}</th>
+                  <th className="text-left px-4 py-3 font-medium text-muted-foreground">{t.adminUsers.role}</th>
+                  <th className="text-right px-4 py-3 font-medium text-muted-foreground">{t.adminUsers.skillCount}</th>
+                  <th className="text-right px-4 py-3 font-medium text-muted-foreground">{t.adminUsers.agentCount}</th>
+                  <th className="text-left px-4 py-3 font-medium text-muted-foreground">{t.adminUsers.userId}</th>
+                </tr>
+              </thead>
+              <tbody>
+                {users.map((user, i) => (
+                  <tr
+                    key={user.id}
+                    className={i % 2 === 0 ? "bg-background" : "bg-muted/20"}
+                  >
+                    <td className="px-4 py-3">{user.email}</td>
+                    <td className="px-4 py-3">
+                      {user.system_role === "admin" ? (
+                        <Badge variant="default">{t.adminUsers.roleAdmin}</Badge>
+                      ) : (
+                        <Badge variant="secondary">{t.adminUsers.roleUser}</Badge>
+                      )}
+                    </td>
+                    <td className="px-4 py-3 text-right tabular-nums">{user.skill_count}</td>
+                    <td className="px-4 py-3 text-right tabular-nums">{user.agent_count}</td>
+                    <td className="px-4 py-3 font-mono text-xs text-muted-foreground truncate max-w-[160px]">
+                      {user.id}
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </SettingsSection>
+    </div>
+  );
+}

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,10 +2,15 @@
 
 import {
   BotIcon,
-  EyeIcon,
-  EyeOffIcon,
+  GlobeIcon,
+  InfoIcon,
+  LockIcon,
   MessageSquareIcon,
+  ShieldIcon,
+  SparklesIcon,
   SquarePenIcon,
+  StarIcon,
+  TagsIcon,
   Trash2Icon,
 } from "lucide-react";
 import { useRouter } from "next/navigation";
@@ -33,11 +38,23 @@ import {
 import { Input } from "@/components/ui/input";
 import { Switch } from "@/components/ui/switch";
 import { Textarea } from "@/components/ui/textarea";
-import { useDeleteAgent, useUpdateAgent } from "@/core/agents";
+import { SkillDetailDialog } from "@/components/workspace/skills/skill-detail-dialog";
+import { TagChipList } from "@/components/workspace/tags/tag-chip";
+import { TagPickerDialog } from "@/components/workspace/tags/tag-picker-dialog";
+import {
+  useAgent,
+  useDeleteAgent,
+  useSetAgentFeatured,
+  useSetAgentPrivate,
+  useToggleAgentFavorite,
+  useUpdateAgent,
+} from "@/core/agents";
 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 {
   agent: Agent;
@@ -48,22 +65,47 @@ export function AgentCard({ agent }: AgentCardProps) {
   const router = useRouter();
   const deleteAgent = useDeleteAgent();
   const updateAgent = useUpdateAgent();
+  const setFeatured = useSetAgentFeatured();
+  const setPrivate = useSetAgentPrivate();
+  const toggleFavorite = useToggleAgentFavorite();
   const { skills, isLoading: isSkillsLoading } = useSkills();
   const [deleteOpen, setDeleteOpen] = useState(false);
   const [editOpen, setEditOpen] = useState(false);
+  const [tagPickerOpen, setTagPickerOpen] = useState(false);
   const [editName, setEditName] = useState(agent.name);
   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);
 
-  const currentUserId = useMemo(() => getStoredAuth()?.user_id ?? 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";
   const isBuiltin = agent.builtin;
   const isOwned =
     !isBuiltin && agent.user_id !== null && agent.user_id === currentUserId;
   const isFromOthers = !isBuiltin && !isOwned;
+  // 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 || 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) {
@@ -71,20 +113,34 @@ 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(`/workspace/agents/${agent.id}/chats/new`);
+    router.push(`/page/workspace/agents/${agent.id}/chats/new`);
   }
 
   async function handleDelete() {
@@ -103,6 +159,10 @@ export function AgentCard({ agent }: AgentCardProps) {
       toast.error(t.agents.nameStepInvalidError ?? "名称不能为空");
       return;
     }
+    if (editIsPrivate && editPublished) {
+      toast.warning("私密广场与公开发布互斥，请只勾选其一");
+      return;
+    }
     try {
       await updateAgent.mutateAsync({
         id: agent.id,
@@ -110,7 +170,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,
         },
       });
@@ -122,6 +185,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,
@@ -133,6 +203,57 @@ 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
+    // safe seed; the manage dialog can rewrite to 0..N-1 later).
+    const turningOn = agent.featured_order == null;
+    if (turningOn && !agent.published) {
+      toast.error("只有已发布的智能体可以加入首页选择器");
+      return;
+    }
+    try {
+      await setFeatured.mutateAsync({
+        id: agent.id,
+        order: turningOn ? Date.now() : null,
+      });
+      toast.success(turningOn ? "已加入首页选择器" : "已从首页选择器移除");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
   function toggleSkill(skillName: string) {
     setSelectedSkills((prev) => {
       if (prev.includes(skillName)) {
@@ -146,20 +267,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>
@@ -187,24 +311,51 @@ 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"
                   title="该智能体已对所有用户可见"
                 >
+                  <GlobeIcon className="size-3" />
                   已发布
                 </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"
+                  className="border-amber-500/40 text-amber-700 dark:text-amber-300 text-xs"
+                  title="已加入首页选择器"
+                >
+                  <SparklesIcon className="size-3" />
+                  首页推荐
+                </Badge>
+              )}
             </div>
           </div>
           {agent.description && (
             <CardDescription className="mt-2 line-clamp-2 text-sm">
-              {agent.description}
+              {desensitize(agent.description)}
             </CardDescription>
           )}
         </CardHeader>
 
+        {(agent.tags?.length ?? 0) > 0 && (
+          <CardContent className="pt-0 pb-2">
+            <TagChipList tags={agent.tags!} />
+          </CardContent>
+        )}
+
         {(agent.tool_groups?.length ?? agent.skills?.length ?? 0) > 0 && (
           <CardContent className="pt-0 pb-3">
             <div className="flex flex-wrap gap-1">
@@ -214,29 +365,79 @@ export function AgentCard({ agent }: AgentCardProps) {
                   variant="outline"
                   className="text-xs"
                 >
-                  {group}
+                  {desensitize(group)}
                 </Badge>
               ))}
               {agent.skills?.map((skill) => (
                 <Badge
                   key={`sk:${skill}`}
                   variant="secondary"
-                  className="text-xs"
+                  className="hover:bg-secondary/70 cursor-pointer text-xs"
+                  title={t.settings.skills.viewDetailAction}
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    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}
+        <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"
+                  variant="ghost"
+                  className={cn(
+                    "h-8 w-8 shrink-0",
+                    agent.featured_order != null &&
+                      "text-amber-600 hover:text-amber-700",
+                  )}
+                  onClick={() => void handleToggleFeatured()}
+                  disabled={setFeatured.isPending}
+                  title={
+                    agent.featured_order != null
+                      ? "从首页选择器移除"
+                      : "加入首页选择器"
+                  }
+                >
+                  <SparklesIcon className="h-3.5 w-3.5" />
+                </Button>
+              )}
+              {isAdmin && (
+                <Button
+                  size="icon"
+                  variant="ghost"
+                  className="h-8 w-8 shrink-0"
+                  onClick={() => setTagPickerOpen(true)}
+                  title={t.adminTags.manageTags}
+                >
+                  <TagsIcon className="h-3.5 w-3.5" />
+                </Button>
+              )}
               {isOwned && (
-            <div className="flex gap-1">
                 <Button
                   size="icon"
                   variant="ghost"
@@ -246,11 +447,31 @@ export function AgentCard({ agent }: AgentCardProps) {
                   title={agent.published ? "取消发布" : "发布"}
                 >
                   {agent.published ? (
-                  <EyeOffIcon className="h-3.5 w-3.5" />
+                    <LockIcon className="h-3.5 w-3.5" />
                   ) : (
-                  <EyeIcon className="h-3.5 w-3.5" />
+                    <GlobeIcon className="h-3.5 w-3.5" />
                   )}
                 </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>
+              )}
+              {canEdit && (
                 <Button
                   size="icon"
                   variant="ghost"
@@ -260,6 +481,8 @@ export function AgentCard({ agent }: AgentCardProps) {
                 >
                   <SquarePenIcon className="h-3.5 w-3.5" />
                 </Button>
+              )}
+              {canDelete && (
                 <Button
                   size="icon"
                   variant="ghost"
@@ -269,15 +492,20 @@ export function AgentCard({ agent }: AgentCardProps) {
                 >
                   <Trash2Icon className="h-3.5 w-3.5" />
                 </Button>
+              )}
             </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>
@@ -319,17 +547,31 @@ export function AgentCard({ agent }: AgentCardProps) {
                     {enabledSkills.map((skill) => {
                       const checked = selectedSkills.includes(skill.name);
                       return (
-                        <Button
+                        <div
                           key={skill.name}
+                          className="inline-flex max-w-full items-center"
+                        >
+                          <Button
                             type="button"
                             size="sm"
                             variant={checked ? "default" : "outline"}
                             onClick={() => toggleSkill(skill.name)}
-                          title={skill.description}
-                          className="h-8"
+                            title={desensitize(skill.description ?? "")}
+                            className="h-8 max-w-[200px] rounded-r-none"
                           >
-                          {skill.name}
+                            <span className="truncate">{desensitize(skill.name)}</span>
                           </Button>
+                          <Button
+                            type="button"
+                            size="icon"
+                            variant={checked ? "default" : "outline"}
+                            onClick={() => setDetailSkillName(skill.name)}
+                            title={t.settings.skills.viewDetailAction}
+                            className="h-8 w-7 rounded-l-none border-l-0"
+                          >
+                            <InfoIcon className="size-3.5" />
+                          </Button>
+                        </div>
                       );
                     })}
                   </div>
@@ -344,7 +586,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>
@@ -352,12 +598,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>
@@ -401,6 +676,25 @@ export function AgentCard({ agent }: AgentCardProps) {
           </DialogFooter>
         </DialogContent>
       </Dialog>
+
+      {isAdmin && (
+        <TagPickerDialog
+          open={tagPickerOpen}
+          onOpenChange={setTagPickerOpen}
+          targetType="agent"
+          targetId={agent.id}
+          currentTags={agent.tags ?? []}
+        />
+      )}
+
+
+      <SkillDetailDialog
+        skillName={detailSkillName}
+        open={detailSkillName !== null}
+        onOpenChange={(o) => {
+          if (!o) setDetailSkillName(null);
+        }}
+      />
     </>
   );
 }

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

@@ -1,21 +1,243 @@
 "use client";
 
-import { BotIcon, PlusIcon } from "lucide-react";
+import { BotIcon, LockIcon, PlusIcon, ShieldIcon } from "lucide-react";
 import { useRouter } from "next/navigation";
+import { useEffect, useMemo, useState } from "react";
+import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
-import { useAgents } from "@/core/agents";
+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, 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 { agents, isLoading } = useAgents();
   const router = useRouter();
+  const [activeTab, setActiveTab] = useState<"all" | "mine" | "private">(
+    "mine",
+  );
+  const [search, setSearch] = useState("");
+  const [tagIds, setTagIds] = useState<string[]>([]);
+  // 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) && !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) ||
+            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("/workspace/agents/new");
+    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) => (
+        <AgentCard key={agent.id} agent={agent} />
+      ))}
+    </div>
+  );
+
+  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 dark:bg-[#022248]">
+        <BotIcon className="text-muted-foreground h-7 w-7 dark:text-[#AACEFF]" />
+      </div>
+      <div>
+        <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 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>
+      )}
+    </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 (
@@ -34,36 +256,79 @@ export function AgentGallery() {
         </Button>
       </div>
 
-      {/* Content */}
-      <div className="flex-1 overflow-y-auto p-6">
+      {/* Tabs */}
+      <Tabs
+        value={activeTab}
+        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">
+          <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}
+            tagIds={tagIds}
+            onTagIdsChange={setTagIds}
+          />
+        </div>
+
+        <TabsContent value="all" className="flex-1 overflow-y-auto p-6 mt-0">
           {isLoading ? (
             <div className="text-muted-foreground flex h-40 items-center justify-center text-sm">
               {t.common.loading}
             </div>
-        ) : agents.length === 0 ? (
-          <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>
-            <div>
-              <p className="font-medium">{t.agents.emptyTitle}</p>
-              <p className="text-muted-foreground mt-1 text-sm">
-                {t.agents.emptyDescription}
-              </p>
-            </div>
-            <Button variant="outline" className="mt-2" onClick={handleNewAgent}>
-              <PlusIcon className="mr-1.5 h-4 w-4" />
-              {t.agents.newAgent}
-            </Button>
-          </div>
+          ) : allAgents.length === 0 ? (
+            renderEmpty(t.agents.emptyDescription)
           ) : (
-          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
-            {agents.map((agent) => (
-              <AgentCard key={agent.id} agent={agent} />
-            ))}
-          </div>
+            renderGrid(allAgents)
           )}
+        </TabsContent>
+
+        <TabsContent value="mine" className="flex-1 overflow-y-auto p-6 mt-0">
+          {isLoading ? (
+            <div className="text-muted-foreground flex h-40 items-center justify-center text-sm">
+              {t.common.loading}
             </div>
+          ) : myAgents.length === 0 ? (
+            renderEmpty(t.agents.emptyDescription, true)
+          ) : (
+            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

@@ -0,0 +1,245 @@
+"use client";
+
+import {
+  ArrowDownIcon,
+  ArrowUpIcon,
+  BotIcon,
+  PlusIcon,
+  Trash2Icon,
+} from "lucide-react";
+import { useMemo, useState } from "react";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Tooltip } from "@/components/workspace/tooltip";
+import {
+  useAgentSelector,
+  useAgents,
+  useReorderFeaturedAgents,
+  useSetAgentFeatured,
+} from "@/core/agents";
+import type { Agent } from "@/core/agents";
+import { cn } from "@/lib/utils";
+
+interface AgentManageDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Admin-only homepage agent picker management.
+ *
+ * Single list (no tabs, no per-user buckets): admin curates exactly what every
+ * user sees in the new-chat selector. Up/down to reorder, ✕ to remove, ＋ to
+ * add a published agent. All actions hit the server immediately and react to
+ * TanStack Query invalidation, so the selector dropdown stays in lockstep.
+ */
+export function AgentManageDialog({
+  open,
+  onOpenChange,
+}: AgentManageDialogProps) {
+  const { agents, isLoading } = useAgentSelector();
+  const { agents: allAgents } = useAgents();
+  const setFeaturedMutation = useSetAgentFeatured();
+  const reorderMutation = useReorderFeaturedAgents();
+  const [pickerOpen, setPickerOpen] = useState(false);
+
+  const candidates = useMemo(() => {
+    const existing = new Set(agents.map((a) => 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;
+
+  const move = async (index: number, direction: -1 | 1) => {
+    const target = index + direction;
+    if (target < 0 || target >= agents.length) return;
+    const next = agents.map((a) => a.id);
+    [next[index], next[target]] = [next[target]!, next[index]!];
+    try {
+      await reorderMutation.mutateAsync(next);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  };
+
+  const remove = async (agentId: string) => {
+    try {
+      await setFeaturedMutation.mutateAsync({ id: agentId, order: null });
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  };
+
+  const add = async (agent: Agent) => {
+    if (!agent.published) {
+      toast.error("只有已发布的智能体可以加入选择器");
+      return;
+    }
+    const maxOrder = agents.reduce(
+      (acc, a) => Math.max(acc, a.featured_order ?? 0),
+      -1,
+    );
+    try {
+      await setFeaturedMutation.mutateAsync({
+        id: agent.id,
+        order: maxOrder + 1,
+      });
+      setPickerOpen(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  };
+
+  return (
+    <>
+      <Dialog open={open} onOpenChange={onOpenChange}>
+        <DialogContent className="sm:max-w-xl">
+          <DialogHeader>
+            <DialogTitle>管理 Agent 列表</DialogTitle>
+            <DialogDescription>
+              配置首页对话框里展示的 agent。所有人会看到同一份列表，按下方顺序展示。
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-3">
+            {isLoading ? (
+              <div className="rounded-md border p-6 text-center text-sm text-muted-foreground">
+                加载中…
+              </div>
+            ) : agents.length === 0 ? (
+              <div className="rounded-md border border-dashed p-6 text-center text-sm text-muted-foreground">
+                还没有配置任何 agent。点击下方“添加 Agent”开始。
+              </div>
+            ) : (
+              <div className="max-h-[50vh] divide-y overflow-y-auto rounded-md border">
+                {agents.map((agent, index) => (
+                  <div
+                    key={agent.id}
+                    className="flex items-center gap-2 px-3 py-2 hover:bg-accent/30"
+                  >
+                    <span className="text-muted-foreground w-6 shrink-0 text-center text-xs tabular-nums">
+                      {index + 1}
+                    </span>
+                    <BotIcon className="text-muted-foreground size-4 shrink-0" />
+                    <div className="flex min-w-0 flex-1 flex-col">
+                      <span className="truncate text-sm">{agent.name}</span>
+                      {agent.description && (
+                        <span className="truncate text-[11px] text-muted-foreground">
+                          {agent.description}
+                        </span>
+                      )}
+                    </div>
+                    <div className="flex items-center gap-0.5">
+                      <Tooltip content="上移">
+                        <Button
+                          size="icon"
+                          variant="ghost"
+                          disabled={busy || index === 0}
+                          onClick={() => void move(index, -1)}
+                          className="size-7"
+                        >
+                          <ArrowUpIcon className="size-3.5" />
+                        </Button>
+                      </Tooltip>
+                      <Tooltip content="下移">
+                        <Button
+                          size="icon"
+                          variant="ghost"
+                          disabled={busy || index === agents.length - 1}
+                          onClick={() => void move(index, 1)}
+                          className="size-7"
+                        >
+                          <ArrowDownIcon className="size-3.5" />
+                        </Button>
+                      </Tooltip>
+                      <Tooltip content="从选择器移除">
+                        <Button
+                          size="icon"
+                          variant="ghost"
+                          disabled={busy}
+                          onClick={() => void remove(agent.id)}
+                          className="text-destructive hover:text-destructive size-7"
+                        >
+                          <Trash2Icon className="size-3.5" />
+                        </Button>
+                      </Tooltip>
+                    </div>
+                  </div>
+                ))}
+              </div>
+            )}
+
+            <Button
+              type="button"
+              variant="outline"
+              disabled={busy}
+              onClick={() => setPickerOpen(true)}
+              className="w-full"
+            >
+              <PlusIcon className="mr-1 size-3.5" />
+              添加 Agent
+            </Button>
+          </div>
+        </DialogContent>
+      </Dialog>
+
+      <Dialog open={pickerOpen} onOpenChange={setPickerOpen}>
+        <DialogContent className="overflow-hidden p-0 sm:max-w-md">
+          <DialogTitle className="sr-only">添加 Agent</DialogTitle>
+          <Command className={cn("**:data-[slot=command-input-wrapper]:h-auto")}>
+            <CommandInput placeholder="搜索可添加的 agent…" className="h-auto py-3.5" />
+            <CommandList>
+              <CommandEmpty>
+                {candidates.length === 0
+                  ? "没有更多已发布的 agent 可添加。"
+                  : "没有找到匹配的 agent。"}
+              </CommandEmpty>
+              {candidates.length > 0 && (
+                <CommandGroup>
+                  {candidates.map((agent) => (
+                    <CommandItem
+                      key={agent.id}
+                      value={`${agent.name} ${agent.description ?? ""}`}
+                      onSelect={() => void add(agent)}
+                    >
+                      <BotIcon className="text-muted-foreground mr-2 size-4 shrink-0" />
+                      <div className="flex min-w-0 flex-1 flex-col">
+                        <span className="truncate text-sm">{agent.name}</span>
+                        {agent.description && (
+                          <span className="truncate text-[10px] text-muted-foreground">
+                            {agent.description}
+                          </span>
+                        )}
+                      </div>
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              )}
+            </CommandList>
+          </Command>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

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

@@ -0,0 +1,173 @@
+"use client";
+
+import { BotIcon, SettingsIcon, XIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
+import {
+  Dialog,
+  DialogContent,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { PromptInputButton } from "@/components/ai-elements/prompt-input";
+import { AgentManageDialog } from "@/components/workspace/agents/agent-manage-dialog";
+import { useAgentSelector } from "@/core/agents";
+import type { Agent } from "@/core/agents";
+import { getStoredAuth } from "@/core/auth";
+import { cn } from "@/lib/utils";
+
+interface AgentSelectorProps {
+  selectedAgentId: string | null;
+  onAgentChange: (agentId: string | null) => void;
+  disabled?: boolean;
+}
+
+/**
+ * Homepage agent picker — shows the admin-curated selector list.
+ *
+ * - Non-admins see a read-only dropdown.
+ * - Admins also see a "管理 Agent 列表" entry that opens the management dialog.
+ *
+ * Selecting an agent flips this chip to a coloured pill with a ✕ to clear.
+ * The actual handoff to ``AgentChatPage`` happens in ``ChatPage`` on submit.
+ */
+export function AgentSelector({
+  selectedAgentId,
+  onAgentChange,
+  disabled,
+}: AgentSelectorProps) {
+  const [open, setOpen] = useState(false);
+  const [manageOpen, setManageOpen] = useState(false);
+  const { agents, isLoading } = useAgentSelector();
+  const isAdmin = useMemo(() => getStoredAuth()?.system_role === "admin", []);
+
+  const selectedAgent = useMemo<Agent | null>(() => {
+    if (!selectedAgentId) return null;
+    return agents.find((a) => a.id === selectedAgentId) ?? null;
+  }, [agents, selectedAgentId]);
+
+  const handleSelect = (agent: Agent) => {
+    onAgentChange(agent.id);
+    setOpen(false);
+  };
+
+  const handleClear = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    onAgentChange(null);
+  };
+
+  const triggerLabel = selectedAgent?.name ?? "选择 Agent";
+
+  return (
+    <>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogTrigger asChild>
+          <PromptInputButton
+            type="button"
+            disabled={disabled}
+            className={cn(
+              "gap-1.5! rounded-full border px-3! shadow-none transition-colors",
+              selectedAgent
+                ? "border-[#d6a868] bg-[#fff3df] text-[#7a5417] hover:bg-[#ffe8c4]"
+                : "border-[#eee3d5] bg-[#fffaf5] text-[#7e6a57] hover:bg-white dark:border-slate-600 dark:bg-slate-700/50 dark:text-slate-300 dark:hover:bg-slate-700",
+            )}
+          >
+            <BotIcon className="size-3" />
+            <span className="max-w-[140px] truncate text-xs font-normal">
+              {triggerLabel}
+            </span>
+            {selectedAgent && (
+              <span
+                role="button"
+                tabIndex={0}
+                aria-label="清除已选 agent"
+                className="ml-0.5 inline-flex items-center justify-center rounded-full p-0.5 hover:bg-[#ffd9a7]"
+                onClick={handleClear}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter" || e.key === " ") {
+                    e.preventDefault();
+                    onAgentChange(null);
+                  }
+                }}
+              >
+                <XIcon className="size-3" />
+              </span>
+            )}
+          </PromptInputButton>
+        </DialogTrigger>
+        <DialogContent className="overflow-hidden p-0 sm:max-w-md">
+          <DialogTitle className="sr-only">选择 Agent</DialogTitle>
+          <Command className="**:data-[slot=command-input-wrapper]:h-auto">
+            <CommandInput placeholder="搜索 agent…" className="h-auto py-3.5" />
+            <CommandList>
+              <CommandEmpty>
+                {isLoading ? "加载中…" : "没有找到匹配的 agent"}
+              </CommandEmpty>
+              {agents.length > 0 && (
+                <CommandGroup>
+                  {agents.map((agent) => (
+                    <CommandItem
+                      key={agent.id}
+                      value={`${agent.name} ${agent.description ?? ""}`}
+                      onSelect={() => handleSelect(agent)}
+                      className={cn(
+                        "flex items-center gap-2",
+                        agent.id === selectedAgentId && "bg-accent",
+                      )}
+                    >
+                      <BotIcon className="text-muted-foreground size-4 shrink-0" />
+                      <div className="flex min-w-0 flex-1 flex-col">
+                        <span className="truncate text-sm">{agent.name}</span>
+                        {agent.description && (
+                          <span className="truncate text-[10px] text-muted-foreground">
+                            {agent.description}
+                          </span>
+                        )}
+                      </div>
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              )}
+              {!isLoading && agents.length === 0 && (
+                <div className="px-4 py-6 text-center text-xs text-muted-foreground">
+                  {isAdmin
+                    ? "还没有配置任何 agent。点击下方 “管理” 添加几个。"
+                    : "管理员还没有配置可选的 agent。"}
+                </div>
+              )}
+            </CommandList>
+            {isAdmin && (
+              <div className="border-t px-2 py-1.5">
+                <Button
+                  type="button"
+                  size="sm"
+                  variant="ghost"
+                  className="w-full justify-start text-xs"
+                  onClick={() => {
+                    setOpen(false);
+                    setManageOpen(true);
+                  }}
+                >
+                  <SettingsIcon className="mr-2 size-3.5" />
+                  管理 Agent 列表 …
+                </Button>
+              </div>
+            )}
+          </Command>
+        </DialogContent>
+      </Dialog>
+      {isAdmin && (
+        <AgentManageDialog open={manageOpen} onOpenChange={setManageOpen} />
+      )}
+    </>
+  );
+}

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

@@ -6,8 +6,10 @@ import {
   CopyIcon,
   DownloadIcon,
   EyeIcon,
+  FileType2Icon,
   LoaderIcon,
   PackageIcon,
+  SaveIcon,
   SquareArrowOutUpRightIcon,
   XIcon,
 } from "lucide-react";
@@ -37,13 +39,18 @@ import {
   downloadArtifactFile,
   openArtifactInNewTab,
 } from "@/core/artifacts/download";
-import { useArtifactContent } from "@/core/artifacts/hooks";
+import {
+  useArtifactContent,
+  useUpdateArtifactContent,
+} from "@/core/artifacts/hooks";
 import { urlOfArtifact } from "@/core/artifacts/utils";
 import { useI18n } from "@/core/i18n/hooks";
+import { downloadMarkdownAsDocx } from "@/core/scheduled-tasks/markdown-docx";
 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";
@@ -85,7 +92,7 @@ export function ArtifactFileDetail({
 }) {
   const { t } = useI18n();
   const { artifacts, setOpen, select } = useArtifacts();
-  const { isMock, thread } = useThread();
+  const { isMock, thread, publicShareCode } = useThread();
   const isWriteFile = useMemo(() => {
     return filepathFromProps.startsWith("write-file:");
   }, [filepathFromProps]);
@@ -113,13 +120,18 @@ export function ArtifactFileDetail({
   const isSupportPreview = useMemo(() => {
     return language === "html" || language === "markdown";
   }, [language]);
-  const { content } = useArtifactContent({
+  const { content, isApplyingEdit } = useArtifactContent({
     threadId,
     filepath: filepathFromProps,
     enabled: isCodeFile && !isWriteFile,
   });
 
-  const displayContent = content ?? "";
+  const canEditArtifact =
+    language === "markdown" && !isWriteFile && !isSkillFile && !isMock;
+  const [draftContent, setDraftContent] = useState("");
+  const [hasLocalEdits, setHasLocalEdits] = useState(false);
+  const updateArtifact = useUpdateArtifactContent();
+  const displayContent = canEditArtifact ? draftContent : (content ?? "");
   const isHtmlStreaming = language === "html" && thread.isLoading;
   const hasMultipleArtifacts = (artifacts?.length ?? 0) > 1;
   const fileTypeLabel = useMemo(() => {
@@ -142,6 +154,18 @@ export function ArtifactFileDetail({
   const artifactContentRef = useRef<HTMLDivElement | null>(null);
   const resumeButtonTimeoutRef = useRef<number | null>(null);
 
+  useEffect(() => {
+    setDraftContent(content ?? "");
+    setHasLocalEdits(false);
+  }, [filepathFromProps]);
+
+  useEffect(() => {
+    if (!canEditArtifact || hasLocalEdits) {
+      return;
+    }
+    setDraftContent(content ?? "");
+  }, [canEditArtifact, content, hasLocalEdits]);
+
   useEffect(() => {
     setAllowAutoViewSwitch(true);
     setAutoScrollEnabled(true);
@@ -258,7 +282,7 @@ export function ArtifactFileDetail({
     (async () => {
       try {
         const res = await apiFetch(
-          urlOfArtifact({ filepath, threadId, isMock }),
+          urlOfArtifact({ filepath, threadId, isMock, publicShareCode }),
         );
         if (cancelled || !res.ok) return;
         const blob = await res.blob();
@@ -283,7 +307,7 @@ export function ArtifactFileDetail({
         return null;
       });
     };
-  }, [filepath, threadId, isMock, isCodeFile]);
+  }, [filepath, threadId, isMock, isCodeFile, publicShareCode]);
 
   const handlePauseAutoScroll = useCallback(() => {
     if (!thread.isLoading || !autoScrollEnabled) {
@@ -330,6 +354,52 @@ export function ArtifactFileDetail({
     }
   }, [threadId, filepath, isInstalling]);
 
+  const handleSaveArtifact = useCallback(async () => {
+    if (!canEditArtifact || updateArtifact.isPending) {
+      return;
+    }
+    try {
+      await updateArtifact.mutateAsync({
+        filepath,
+        threadId,
+        isMock,
+        content: draftContent,
+      });
+      setHasLocalEdits(false);
+      toast.success("Markdown 已保存");
+    } catch (error) {
+      console.error("Failed to save artifact:", error);
+      toast.error(error instanceof Error ? error.message : "Markdown 保存失败");
+    }
+  }, [
+    canEditArtifact,
+    draftContent,
+    filepath,
+    isMock,
+    threadId,
+    updateArtifact,
+  ]);
+
+  const [isExportingWord, setIsExportingWord] = useState(false);
+  const handleDownloadAsWord = useCallback(async () => {
+    const source = (displayContent ?? "").trim();
+    if (!source) {
+      toast.error("Markdown 内容为空，无法另存为 Word");
+      return;
+    }
+    setIsExportingWord(true);
+    try {
+      const baseName = getFileName(filepath).replace(/\.(md|markdown)$/i, "");
+      await downloadMarkdownAsDocx(source, baseName || "document", baseName);
+      toast.success("已另存为 Word");
+    } catch (error) {
+      console.error("Failed to export markdown as docx:", error);
+      toast.error(error instanceof Error ? error.message : "另存为 Word 失败");
+    } finally {
+      setIsExportingWord(false);
+    }
+  }, [displayContent, filepath]);
+
   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">
@@ -407,6 +477,15 @@ export function ArtifactFileDetail({
         </div>
         <div className="flex items-center justify-end gap-2">
           <ArtifactActions className="bg-muted/45 rounded-full border border-black/6 p-1 dark:border-white/8">
+            {canEditArtifact && (
+              <ArtifactAction
+                icon={updateArtifact.isPending ? LoaderIcon : SaveIcon}
+                label="保存 Markdown"
+                tooltip={hasLocalEdits ? "保存 Markdown 修改" : "Markdown 已保存"}
+                disabled={!hasLocalEdits || updateArtifact.isPending}
+                onClick={handleSaveArtifact}
+              />
+            )}
             {!isWriteFile && filepath.endsWith(".skill") && (
               <Tooltip content={t.toolCalls.skillInstallTooltip}>
                 <ArtifactAction
@@ -432,6 +511,7 @@ export function ArtifactFileDetail({
                       filepath,
                       threadId,
                       isMock,
+                      publicShareCode,
                     });
                   } catch (error) {
                     console.error(error);
@@ -461,6 +541,15 @@ export function ArtifactFileDetail({
                 tooltip={t.clipboard.copyToClipboard}
               />
             )}
+            {!isWriteFile && language === "markdown" && (
+              <ArtifactAction
+                icon={isExportingWord ? LoaderIcon : FileType2Icon}
+                label="另存为 Word"
+                tooltip="另存为 Word (.docx)"
+                disabled={isExportingWord || !displayContent}
+                onClick={handleDownloadAsWord}
+              />
+            )}
             {!isWriteFile && (
               <ArtifactAction
                 icon={DownloadIcon}
@@ -472,6 +561,7 @@ export function ArtifactFileDetail({
                       filepath,
                       threadId,
                       isMock,
+                      publicShareCode,
                     });
                   } catch (error) {
                     console.error(error);
@@ -499,6 +589,12 @@ export function ArtifactFileDetail({
         className="relative p-0"
         onWheelCapture={handlePauseAutoScroll}
       >
+        {isApplyingEdit && (
+          <div className="absolute right-4 bottom-4 z-20 inline-flex items-center gap-2 rounded-full border border-[#d8b878] bg-[#fff3cf]/95 px-3 py-1.5 text-xs text-[#6d5625] shadow-sm">
+            <span className="h-3.5 w-0.5 animate-pulse rounded-full bg-[#9b7a2f]" />
+            正在改写 Markdown
+          </div>
+        )}
         {showResumeAutoScroll && (
           <button
             type="button"
@@ -513,17 +609,31 @@ export function ArtifactFileDetail({
           viewMode === "preview" &&
           (language === "markdown" || language === "html") && (
               <ArtifactFilePreview
-              content={displayContent}
+                content={desensitize(displayContent ?? "")}
                 language={language ?? "text"}
                 animated={showPreviewSwitchPulse}
+                activeCursor={isApplyingEdit}
               />
             )}
         {isCodeFile && viewMode === "code" && (
           <div className="size-full">
             <CodeEditor
               className="size-full resize-none rounded-none border-none bg-transparent"
-              value={displayContent ?? ""}
-              readonly
+              value={
+                canEditArtifact
+                  ? (displayContent ?? "")
+                  : desensitize(displayContent ?? "")
+              }
+              readonly={!canEditArtifact}
+              onChange={
+                canEditArtifact
+                  ? (value) => {
+                      setDraftContent(value);
+                      setHasLocalEdits(true);
+                    }
+                  : undefined
+              }
+              streamingReadonlyFallback={!canEditArtifact}
             />
           </div>
         )}
@@ -545,10 +655,12 @@ export function ArtifactFilePreview({
   content,
   language,
   animated = false,
+  activeCursor = false,
 }: {
   content: string;
   language: string;
   animated?: boolean;
+  activeCursor?: boolean;
 }) {
   const [htmlPreviewUrl, setHtmlPreviewUrl] = useState<string>();
 
@@ -583,6 +695,9 @@ export function ArtifactFilePreview({
         >
           {content ?? ""}
         </Streamdown>
+        {activeCursor && (
+          <span className="mt-2 inline-block h-5 w-0.5 animate-pulse rounded-full bg-[#9b7a2f]" />
+        )}
       </div>
     );
   }

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

@@ -33,7 +33,7 @@ export function ArtifactFileList({
   threadId: string;
 }) {
   const { t } = useI18n();
-  const { isMock } = useThread();
+  const { isMock, publicShareCode } = useThread();
   const { select: selectArtifact, setOpen } = useArtifacts();
   const [installingFile, setInstallingFile] = useState<string | null>(null);
   const [downloadingFile, setDownloadingFile] = useState<string | null>(null);
@@ -81,7 +81,7 @@ export function ArtifactFileList({
       if (downloadingFile) return;
       setDownloadingFile(filepath);
       try {
-        await downloadArtifactFile({ filepath, threadId, isMock });
+        await downloadArtifactFile({ filepath, threadId, isMock, publicShareCode });
       } catch (error) {
         console.error(error);
         toast.error(
@@ -91,7 +91,7 @@ export function ArtifactFileList({
         setDownloadingFile(null);
       }
     },
-    [threadId, isMock, downloadingFile],
+    [threadId, isMock, publicShareCode, downloadingFile],
   );
 
   return (

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

@@ -6,7 +6,7 @@ import {
   type ReactNode,
 } from "react";
 
-import { useSidebar } from "@/components/ui/sidebar";
+import { useSidebarSafe } from "@/components/ui/sidebar";
 import { env } from "@/env";
 
 export interface ArtifactsContextType {
@@ -32,26 +32,29 @@ 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(
     env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true",
   );
   const [autoOpen, setAutoOpen] = useState(true);
-  const { setOpen: setSidebarOpen } = useSidebar();
+  const sidebar = useSidebarSafe();
 
   const select = useCallback(
     (artifact: string, autoSelect = false) => {
       setSelectedArtifact(artifact);
       if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY !== "true") {
-        setSidebarOpen(false);
+        sidebar?.setOpen(false);
       }
       if (!autoSelect) {
         setAutoSelect(false);
       }
     },
-    [setSidebarOpen, setSelectedArtifact, setAutoSelect],
+    [sidebar, setSelectedArtifact, setAutoSelect],
   );
 
   const deselect = useCallback(() => {
@@ -94,3 +97,7 @@ export function useArtifacts() {
   }
   return context;
 }
+
+export function useArtifactsOptional(): ArtifactsContextType | null {
+  return useContext(ArtifactsContext) ?? null;
+}

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

@@ -1,3 +1,4 @@
+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";
@@ -10,6 +11,16 @@ import {
   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 { normalizeDisplaySources } from "@/core/skill-display/display-adapter";
+import {
+  buildSkillDisplayMap,
+  collectRuntimeDisplaySources,
+} from "@/core/skill-display/runtime";
 import { env } from "@/env";
 import { cn } from "@/lib/utils";
 
@@ -19,9 +30,38 @@ import {
   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 }> = ({
   children,
@@ -30,7 +70,20 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
   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,
@@ -43,14 +96,191 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
   } = 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
-    setArtifacts(thread.values.artifacts);
+    const nextArtifacts = thread.values.artifacts ?? [];
+    const hadArtifacts = artifactsCountRef.current > 0;
+    const hasNewArtifact = nextArtifacts.length > artifactsCountRef.current;
+    artifactsCountRef.current = nextArtifacts.length;
+    setArtifacts(nextArtifacts);
+    if ((hasNewArtifact || (!hadArtifacts && nextArtifacts.length > 0)) && !selectedArtifact) {
+      selectArtifact(nextArtifacts[nextArtifacts.length - 1]!);
+      setArtifactsOpen(true);
+      setSideTab("document");
+    }
 
     // DO NOT automatically deselect the artifact when switching threads, because the artifacts auto discovering is not work now.
     // if (
@@ -85,6 +315,16 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
     }
     return artifactsOpen;
   }, [artifactsOpen, artifacts]);
+  const sidePanelOpen = artifactPanelOpen || (hasCitationReferences && referencesOpen);
+  const showTabs = !!selectedArtifact && hasCitationReferences;
+
+  useEffect(() => {
+    if (selectedArtifact) {
+      setSideTab("document");
+    } else if (hasCitationReferences) {
+      setSideTab("references");
+    }
+  }, [hasCitationReferences, selectedArtifact]);
 
   const resizableIdBase = useMemo(() => {
     const raw = pathname
@@ -95,13 +335,13 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
 
   useEffect(() => {
     if (layoutRef.current) {
-      if (artifactPanelOpen) {
+      if (sidePanelOpen) {
         layoutRef.current.setLayout(OPEN_MODE);
       } else {
         layoutRef.current.setLayout(CLOSE_MODE);
       }
     }
-  }, [artifactPanelOpen]);
+  }, [sidePanelOpen]);
 
   return (
     <ResizablePanelGroup
@@ -117,28 +357,79 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
         id={`${resizableIdBase}-separator`}
         className={cn(
           "opacity-33 hover:opacity-100",
-          !artifactPanelOpen && "pointer-events-none opacity-0",
+          !sidePanelOpen && "pointer-events-none opacity-0",
         )}
       />
       <ResizablePanel
         className={cn(
-          "bg-[#fffdfa] transition-all duration-300 ease-in-out",
-          !artifactsOpen && "opacity-0",
+          "bg-background transition-all duration-300 ease-in-out",
+          !sidePanelOpen && "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",
+            "h-full bg-background p-4 transition-transform duration-300 ease-in-out",
+            sidePanelOpen ? "translate-x-0" : "translate-x-full",
           )}
         >
-          {selectedArtifact ? (
+          {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">
@@ -180,4 +471,299 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
   );
 };
 
+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 normalized = normalizeDisplaySources(
+    buildPayloadAtPath(match.display.resultPath || "results", [rawItem]),
+    match.display,
+  )[0];
+  if (!normalized) {
+    return null;
+  }
+  return {
+    ...source,
+    ...normalized,
+    skillName: match.skillName,
+    mode: match.display.mode,
+    tableColumns: match.display.tableColumns,
+    index: source.index,
+    raw: source.raw,
+  };
+}
+
+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";
 
+const SHOW_REFERENCE_EVENT = "workspace:show-reference";
+
 export function CitationLink({
   href,
   children,
+  className,
   ...props
 }: ComponentProps<"a">) {
-  const domain = extractDomain(href ?? "");
-
-  // Priority: children > domain
-  const childrenText =
-    typeof children === "string"
-      ? children.replace(/^citation:\s*/i, "")
+  const childrenText = normalizeCitationText(children);
+  const displayText = childrenText ?? "";
+  const referenceId = href?.startsWith("#reference-")
+    ? href.slice("#reference-".length)
     : null;
-  const isGenericText = childrenText === "Source" || childrenText === "来源";
-  const displayText = (!isGenericText && childrenText) ?? domain;
 
+  if (referenceId) {
+    const badgeLabel = displayText.replace(/^\[|\]$/g, "") || referenceId;
     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()}
+        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}
       >
-          <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>
+        {badgeLabel}
       </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>
+    );
+  }
+
+  return (
     <a
       href={href}
-            target="_blank"
-            rel="noopener noreferrer"
-            className="text-primary mt-2 inline-flex items-center gap-1 text-xs hover:underline"
+      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}
     >
-            Visit source
-            <ExternalLinkIcon className="size-3" />
+      {displayText || children}
     </a>
-        </div>
-      </HoverCardContent>
-    </HoverCard>
   );
 }
 
-function extractDomain(url: string): string {
-  try {
-    return new URL(url).hostname.replace(/^www\./i, "");
-  } catch {
-    return url;
+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/code-editor.tsx

@@ -38,18 +38,22 @@ export function CodeEditor({
   className,
   placeholder,
   value,
+  onChange,
   readonly,
   disabled,
   autoFocus,
   settings,
+  streamingReadonlyFallback = true,
 }: {
   className?: string;
   placeholder?: string;
   value: string;
+  onChange?: (value: string) => void;
   readonly?: boolean;
   disabled?: boolean;
   autoFocus?: boolean;
   settings?: unknown;
+  streamingReadonlyFallback?: boolean;
 }) {
   const {
     thread: { isLoading },
@@ -77,7 +81,7 @@ export function CodeEditor({
         className,
       )}
     >
-      {isLoading ? (
+      {isLoading && streamingReadonlyFallback ? (
         <Textarea
           className={cn(
             "h-full overflow-auto font-mono [&_.cm-editor]:h-full [&_.cm-focused]:outline-none!",
@@ -107,6 +111,7 @@ export function CodeEditor({
           }}
           autoFocus={autoFocus}
           value={value}
+          onChange={onChange}
         />
       )}
     </div>

frontend-web/src/components/workspace/command-palette.tsx

@@ -38,7 +38,7 @@ export function CommandPalette() {
   const [isMac, setIsMac] = useState(false);
 
   const handleNewChat = useCallback(() => {
-    router.push("/workspace/chats/new");
+    router.push("/page/workspace/chats/new");
     setOpen(false);
   }, [router]);
 

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/export-trigger.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Download, FileJson, FileText } from "lucide-react";
+import { Download, FileJson, FileText, FileType2 } from "lucide-react";
 import { useCallback } from "react";
 import { toast } from "sonner";
 
@@ -15,6 +15,7 @@ import { useI18n } from "@/core/i18n/hooks";
 import {
   exportThreadAsJSON,
   exportThreadAsMarkdown,
+  exportThreadAsWord,
 } from "@/core/threads/export";
 import type { AgentThread } from "@/core/threads/types";
 
@@ -28,7 +29,7 @@ export function ExportTrigger({ threadId }: { threadId: string }) {
   const messages = thread.messages;
 
   const handleExport = useCallback(
-    (format: "markdown" | "json") => {
+    async (format: "markdown" | "json" | "word") => {
       if (messages.length === 0) {
         toast.error(t.conversation.noMessages);
         return;
@@ -39,12 +40,18 @@ export function ExportTrigger({ threadId }: { threadId: string }) {
         values: thread.values,
       } as AgentThread;
 
+      try {
         if (format === "markdown") {
           exportThreadAsMarkdown(agentThread, messages);
-      } else {
+        } else if (format === "json") {
           exportThreadAsJSON(agentThread, messages);
+        } else {
+          await exportThreadAsWord(agentThread, messages);
         }
         toast.success(t.common.exportSuccess);
+      } catch (error) {
+        toast.error(error instanceof Error ? error.message : "导出失败");
+      }
     },
     [messages, thread.values, threadId, t],
   );
@@ -67,11 +74,15 @@ export function ExportTrigger({ threadId }: { threadId: string }) {
         </DropdownMenuTrigger>
       </Tooltip>
       <DropdownMenuContent align="end">
-        <DropdownMenuItem onSelect={() => handleExport("markdown")}>
+        <DropdownMenuItem onSelect={() => void handleExport("markdown")}>
           <FileText className="text-muted-foreground" />
           <span>{t.common.exportAsMarkdown}</span>
         </DropdownMenuItem>
-        <DropdownMenuItem onSelect={() => handleExport("json")}>
+        <DropdownMenuItem onSelect={() => void handleExport("word")}>
+          <FileType2 className="text-muted-foreground" />
+          <span>{t.common.exportAsWord}</span>
+        </DropdownMenuItem>
+        <DropdownMenuItem onSelect={() => void handleExport("json")}>
           <FileJson className="text-muted-foreground" />
           <span>{t.common.exportAsJSON}</span>
         </DropdownMenuItem>

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

@@ -2,7 +2,10 @@
 
 import type { ChatStatus } from "ai";
 import {
+  BrainCircuitIcon,
+  BookMarkedIcon,
   CheckIcon,
+  FileTextIcon,
   GraduationCapIcon,
   LightbulbIcon,
   PaperclipIcon,
@@ -61,8 +64,11 @@ 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";
+
 import {
   ModelSelector,
   ModelSelectorContent,
@@ -80,12 +86,22 @@ import {
   DropdownMenuTrigger,
 } 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";
 
 type InputMode = "flash" | "thinking" | "pro" | "ultra";
 
+
 function getResolvedMode(
   mode: InputMode | undefined,
   supportsThinking: boolean,
@@ -113,6 +129,8 @@ export function InputBox({
   onFollowupsVisibilityChange,
   onSubmit,
   onStop,
+  promptPrefix,
+  agentSelector,
   ...props
 }: Omit<ComponentProps<typeof PromptInput>, "onSubmit"> & {
   assistantId?: string | null;
@@ -124,6 +142,8 @@ export function InputBox({
   > & {
     mode: "flash" | "thinking" | "pro" | "ultra" | undefined;
     reasoning_effort?: "minimal" | "low" | "medium" | "high";
+    writing_mode?: boolean;
+    memory_injection_enabled?: boolean;
   };
   extraHeader?: React.ReactNode;
   isNewThread?: boolean;
@@ -136,13 +156,35 @@ export function InputBox({
     > & {
       mode: "flash" | "thinking" | "pro" | "ultra" | undefined;
       reasoning_effort?: "minimal" | "low" | "medium" | "high";
+      writing_mode?: boolean;
+      memory_injection_enabled?: boolean;
     },
   ) => void;
   onFollowupsVisibilityChange?: (visible: boolean) => void;
   onSubmit?: (message: PromptInputMessage) => void;
   onStop?: () => void;
+  /**
+   * Optional toggle rendered next to the model selector. Used for the
+   * admin-configurable prompt-prefix switch on the chat input. Omitting the
+   * prop hides the button entirely.
+   */
+  promptPrefix?: {
+    label: string;
+    on: boolean;
+    onToggle: () => void;
+  };
+  /**
+   * Optional agent picker shown alongside the model selector. Only the new-chat
+   * homepage (``ChatPage``) passes this; ``AgentChatPage`` omits it because the
+   * thread is already bound to one agent.
+   */
+  agentSelector?: {
+    selectedAgentId: string | null;
+    onAgentChange: (agentId: string | null) => void;
+  };
 }) {
   const { t } = useI18n();
+  const [localSettings, setLocalSettings] = useLocalSettings();
   const searchParams = useSearchParams();
   const [modelDialogOpen, setModelDialogOpen] = useState(false);
   const { models } = useModels();
@@ -161,6 +203,8 @@ export function InputBox({
     null,
   );
 
+  const { questions: recommendedQuestions } = useRecommendedQuestions();
+
   useEffect(() => {
     if (models.length === 0) {
       return;
@@ -246,6 +290,30 @@ export function InputBox({
     [onContextChange, context],
   );
 
+  const handleWritingModeToggle = useCallback(() => {
+    onContextChange?.({
+      ...context,
+      writing_mode: !context.writing_mode,
+    });
+  }, [context, onContextChange]);
+
+  const memoryInjectionEnabled = context.memory_injection_enabled ?? true;
+  const handleMemoryInjectionToggle = useCallback(() => {
+    onContextChange?.({
+      ...context,
+      memory_injection_enabled: !memoryInjectionEnabled,
+    });
+  }, [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") {
@@ -258,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.
@@ -282,8 +353,10 @@ export function InputBox({
       onSubmit,
       onStop,
       resolvedModelName,
+      ragModeEnabled,
       selectedModel?.supports_thinking,
       status,
+      threadId,
     ],
   );
 
@@ -430,7 +503,32 @@ export function InputBox({
   }, [context.model_name, disabled, isMock, status, thread.messages, threadId]);
 
   return (
-    <div ref={promptRootRef} className="relative flex flex-col gap-4">
+    <div ref={promptRootRef} className="relative flex flex-col gap-6">
+      {extraHeader && (
+        <div className="flex items-center justify-center">
+          {extraHeader}
+        </div>
+      )}
+
+      {isNewThread && searchParams.get("mode") !== "skill" && recommendedQuestions.length > 0 && (
+        <div className="flex flex-wrap justify-center gap-2.5 px-4 mb-[10px]">
+          {recommendedQuestions.map((q) => (
+            <button
+              key={q.id}
+              type="button"
+              className="rounded-full border border-[#e4e4e7] bg-white px-4 py-2 text-sm text-[#18181b] shadow-none transition-colors hover:bg-[#f4f4f5] cursor-pointer dark:border-slate-600 dark:bg-slate-700/50 dark:text-slate-300 dark:hover:bg-slate-700"
+              onClick={() => {
+                textInput.setInput(q.content);
+                setFollowupsHidden(true);
+                setTimeout(() => requestFormSubmit(), 0);
+              }}
+            >
+              {desensitize(q.title)}
+            </button>
+          ))}
+        </div>
+      )}
+
       {showFollowups && (
         <div className="flex items-center justify-center pb-2">
           <div className="flex items-center gap-2">
@@ -462,9 +560,30 @@ 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(
-          "rounded-[1.85rem] border border-[#eadfce] bg-white shadow-[0_24px_70px_-34px_rgba(120,83,42,0.32)] ring-1 ring-[#f6efe5] transition-all duration-300 ease-out *:data-[slot='input-group']:rounded-[1.85rem]",
+          "transition-all duration-300 ease-out *:data-[slot='input-group']:rounded-3xl",
+          // landing 态：透明，让外层 gemini-gradient-border 提供白卡 + 旋转描边
+          // 对话态：常规白卡 + 中性边框 + 轻阴影
+          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",
           className,
         )}
         disabled={disabled}
@@ -473,20 +592,14 @@ export function InputBox({
         onSubmit={handleSubmit}
         {...props}
       >
-        {extraHeader && (
-          <div className="absolute top-0 right-0 left-0 z-10">
-            <div className="absolute right-0 bottom-0 left-0 flex items-center justify-center">
-              {extraHeader}
-            </div>
-          </div>
-        )}
         <PromptInputAttachments>
           {(attachment) => <PromptInputAttachment data={attachment} />}
         </PromptInputAttachments>
         <PromptInputBody className="absolute top-0 right-0 left-0 z-3">
           <PromptInputTextarea
             className={cn(
-              "size-full px-2 py-1 text-[15px] leading-7 placeholder:text-[#b7ab9a]",
+              "size-full px-2 py-1 text-[15px] leading-7 placeholder:text-muted-foreground/60",
+              isNewThread && "min-h-[110px]!",
             )}
             disabled={disabled}
             placeholder={t.inputBox.placeholder}
@@ -494,7 +607,7 @@ export function InputBox({
             defaultValue={initialValue}
           />
         </PromptInputBody>
-        <PromptInputFooter className="flex items-center border-t border-[#f4ede4] px-2 pt-2.5 pb-1.5">
+        <PromptInputFooter className="flex items-center border-t-0 px-2 pt-1 pb-1.5">
           <PromptInputTools className="gap-1.5">
             {/* TODO: Add more connectors here
           <PromptInputActionMenu>
@@ -505,7 +618,74 @@ export function InputBox({
               />
             </PromptInputActionMenuContent>
           </PromptInputActionMenu> */}
-            <AddAttachmentsButton className="rounded-full border border-[#eee3d5] bg-[#fffaf5] px-2.5! shadow-none hover:bg-white" />
+            <AddAttachmentsButton className="rounded-full border-0 bg-transparent px-2.5! shadow-none text-muted-foreground hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100" />
+            <Tooltip
+              content={
+                context.writing_mode
+                  ? "写作模式已开启：最终输出会强制保存为 Markdown 文件"
+                  : "开启写作模式：最终输出保存为 Markdown 文件并进入画布"
+              }
+            >
+              <PromptInputButton
+                className={cn(
+                  "gap-1.5! rounded-full px-3! shadow-none",
+                  context.writing_mode
+                    ? "border border-amber-300 bg-amber-50 text-amber-700 hover:bg-amber-100 dark:border-amber-700 dark:bg-amber-950/40 dark:text-amber-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={handleWritingModeToggle}
+              >
+                <FileTextIcon className="size-3" />
+                <span className="text-xs font-normal">写作</span>
+              </PromptInputButton>
+            </Tooltip>
+            <Tooltip
+              content={
+                memoryInjectionEnabled
+                  ? "记忆注入已开启：对话前会注入历史记忆"
+                  : "记忆注入已关闭：本次对话不注入记忆"
+              }
+            >
+              <PromptInputButton
+                className={cn(
+                  "gap-1.5! rounded-full px-3! shadow-none",
+                  memoryInjectionEnabled
+                    ? "border border-blue-300 bg-blue-50 text-blue-700 hover:bg-blue-100 dark:border-blue-700 dark:bg-blue-950/40 dark:text-blue-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={handleMemoryInjectionToggle}
+              >
+                <BrainCircuitIcon className="size-3" />
+                <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={
@@ -517,7 +697,7 @@ export function InputBox({
                     : "flash"
                 }
               >
-                <PromptInputActionMenuTrigger className="gap-1.5! rounded-full border border-[#eee3d5] bg-[#fffaf5] px-3! text-[#7e6a57] shadow-none hover:bg-white">
+                <PromptInputActionMenuTrigger className="gap-1.5! rounded-full border-0 bg-transparent px-3! text-muted-foreground shadow-none hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100">
                   <div>
                     {context.mode === "flash" && <ZapIcon className="size-3" />}
                     {context.mode === "thinking" && (
@@ -679,7 +859,7 @@ export function InputBox({
             </PromptInputActionMenu>
             {supportReasoningEffort && context.mode !== "flash" && (
               <PromptInputActionMenu>
-                <PromptInputActionMenuTrigger className="gap-1.5! rounded-full border border-[#eee3d5] bg-[#fffaf5] px-3! text-[#7e6a57] shadow-none hover:bg-white">
+                <PromptInputActionMenuTrigger className="gap-1.5! rounded-full border-0 bg-transparent px-3! text-muted-foreground shadow-none hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100">
                   <div className="text-xs font-normal">
                     {t.inputBox.reasoningEffort}:
                     {context.reasoning_effort === "minimal" &&
@@ -795,12 +975,47 @@ export function InputBox({
             )}
           </PromptInputTools>
           <PromptInputTools className="gap-1.5">
+            {agentSelector && (
+              <AgentSelector
+                selectedAgentId={agentSelector.selectedAgentId}
+                onAgentChange={agentSelector.onAgentChange}
+                disabled={disabled}
+              />
+            )}
+            {promptPrefix && (
+              <Tooltip
+                content={
+                  promptPrefix.on
+                    ? `已开启：${promptPrefix.label}`
+                    : `点击开启：${promptPrefix.label}`
+                }
+              >
+                <PromptInputButton
+                  type="button"
+                  onClick={promptPrefix.onToggle}
+                  aria-pressed={promptPrefix.on}
+                  className={cn(
+                    "rounded-full px-3 shadow-none transition-colors",
+                    promptPrefix.on
+                      ? "border border-amber-300 bg-amber-50 text-amber-700 hover:bg-amber-100 dark:border-amber-700 dark:bg-amber-950/40 dark:text-amber-200"
+                      : "border-0 bg-transparent text-muted-foreground hover:bg-muted/70 hover:text-foreground",
+                  )}
+                >
+                  <span className="max-w-[160px] truncate text-xs font-normal">
+                    {promptPrefix.label}
+                  </span>
+                  {promptPrefix.on && (
+                    <CheckIcon className="ml-1 size-3.5 text-amber-700 dark:text-amber-200" />
+                  )}
+                </PromptInputButton>
+              </Tooltip>
+            )}
             <ModelSelector
               open={modelDialogOpen}
               onOpenChange={setModelDialogOpen}
             >
               <ModelSelectorTrigger asChild>
-                <PromptInputButton className="rounded-full border border-[#eee3d5] bg-[#fffaf5] px-3 shadow-none hover:bg-white">
+                <PromptInputButton className="rounded-full border-0 bg-transparent px-3 shadow-none text-muted-foreground hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100">
                   <div className="flex min-w-0 flex-col items-start text-left">
                     <ModelSelectorName className="text-xs font-normal">
                       {selectedModel?.display_name}
@@ -834,7 +1049,7 @@ export function InputBox({
               </ModelSelectorContent>
             </ModelSelector>
             <PromptInputSubmit
-              className="rounded-full border-[#e7d9c7] bg-white shadow-[0_10px_24px_-18px_rgba(120,83,42,0.34)]"
+              className="rounded-full border-border bg-background shadow-sm hover:bg-muted dark:bg-blue-500 dark:border-blue-500 dark:text-white dark:hover:bg-blue-400 dark:shadow-none"
               disabled={disabled}
               variant="outline"
               status={status}
@@ -842,15 +1057,11 @@ export function InputBox({
           </PromptInputTools>
         </PromptInputFooter>
         {!isNewThread && (
-          <div className="absolute right-0 -bottom-[17px] left-0 z-0 h-4 bg-[#fffdfa]"></div>
+          <div className="absolute right-0 -bottom-[17px] left-0 z-0 h-4 bg-background"></div>
         )}
       </PromptInput>
-
-      {isNewThread && searchParams.get("mode") !== "skill" && (
-        <div className="flex items-center justify-center pt-2">
-          <SuggestionList />
       </div>
-      )}
+      </div>
 
       <Dialog open={confirmOpen} onOpenChange={setConfirmOpen}>
         <DialogContent>

frontend-web/src/components/workspace/messages/context.ts

@@ -6,6 +6,13 @@ import type { AgentThreadState } from "@/core/threads";
 export interface ThreadContextType {
   thread: BaseStream<AgentThreadState>;
   isMock?: boolean;
+  /**
+   * When set, the conversation is rendered from a public read-only share.
+   * Artifact/image URLs then resolve to the unauthenticated
+   * `/api/public/shares/{code}/files/...` endpoint instead of the
+   * auth-gated thread artifact route.
+   */
+  publicShareCode?: string;
 }
 
 export const ThreadContext = createContext<ThreadContextType | undefined>(

frontend-web/src/components/workspace/messages/download-word-button.tsx

@@ -0,0 +1,55 @@
+import { FileText, Loader2 } from "lucide-react";
+import { useState, type ComponentProps } from "react";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import { downloadMarkdownAsDocx } from "@/core/scheduled-tasks/markdown-docx";
+
+import { Tooltip } from "../tooltip";
+
+export function DownloadWordButton({
+  markdown,
+  fileName,
+  title,
+  ...props
+}: ComponentProps<typeof Button> & {
+  markdown: string;
+  fileName?: string;
+  title?: string;
+}) {
+  const [busy, setBusy] = useState(false);
+  const handleDownload = async () => {
+    const source = markdown?.trim();
+    if (!source) {
+      toast.error("无可下载的 Markdown 内容");
+      return;
+    }
+    setBusy(true);
+    try {
+      await downloadMarkdownAsDocx(source, fileName || "message", title);
+      toast.success("Word 文件已生成");
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : "生成 Word 失败");
+    } finally {
+      setBusy(false);
+    }
+  };
+  return (
+    <Tooltip content="下载为 Word">
+      <Button
+        size="icon-sm"
+        type="button"
+        variant="ghost"
+        disabled={busy}
+        onClick={handleDownload}
+        {...props}
+      >
+        {busy ? (
+          <Loader2 size={12} className="animate-spin" />
+        ) : (
+          <FileText size={12} />
+        )}
+      </Button>
+    </Tooltip>
+  );
+}

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

@@ -8,6 +8,7 @@ import {
   type MessageResponseProps,
 } from "@/components/ai-elements/message";
 import { streamdownPlugins } from "@/core/streamdown";
+import { desensitize } from "@/lib/desensitize";
 import { cn } from "@/lib/utils";
 
 import { CitationLink } from "../citations/citation-link";
@@ -36,6 +37,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) {
@@ -63,6 +67,8 @@ export function MarkdownContent({
 
   if (!content) return null;
 
+  const displayContent = desensitize(content);
+
   return (
     <MessageResponse
       className={className}
@@ -70,7 +76,7 @@ export function MarkdownContent({
       rehypePlugins={rehypePlugins}
       components={components}
     >
-      {content}
+      {displayContent}
     </MessageResponse>
   );
 }

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

@@ -1,6 +1,7 @@
 import type { Message } from "@langchain/langgraph-sdk";
 import {
   BookOpenTextIcon,
+  ChevronDownIcon,
   ChevronUp,
   FolderOpenIcon,
   GlobeIcon,
@@ -23,19 +24,48 @@ import {
 } from "@/components/ai-elements/chain-of-thought";
 import { CodeBlock } from "@/components/ai-elements/code-block";
 import { Button } from "@/components/ui/button";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
 import { useI18n } from "@/core/i18n/hooks";
+import {
+  normalizeSearchResults,
+  resolveSearchQuery,
+  type SearchResultItem,
+} from "@/core/messages/search-results";
 import {
   extractReasoningContentFromMessage,
   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";
 
-import { useArtifacts } from "../artifacts";
+import { useArtifactsOptional } from "../artifacts";
 import { FlipDisplay } from "../flip-display";
 import { Tooltip } from "../tooltip";
+import { SourceCard } from "../skill-display-sources";
 
 import { MarkdownContent } from "./markdown-content";
 
@@ -56,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];
@@ -124,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 && (
@@ -134,6 +176,8 @@ export function MessageGroup({
                 {...lastToolCallStep}
                 isLast={true}
                 isLoading={isLoading}
+                skillDisplayMap={skillDisplayMap}
+                ragModeEnabled={settings.display.ragModeEnabled}
               />
             </FlipDisplay>
           )}
@@ -191,6 +235,8 @@ function ToolCall({
   result,
   isLast = false,
   isLoading = false,
+  skillDisplayMap = new Map(),
+  ragModeEnabled = false,
 }: {
   id?: string;
   messageId?: string;
@@ -199,28 +245,69 @@ function ToolCall({
   result?: string | Record<string, unknown>;
   isLast?: boolean;
   isLoading?: boolean;
+  skillDisplayMap?: ReturnType<typeof buildSkillDisplayMap>;
+  ragModeEnabled?: boolean;
 }) {
   const { t } = useI18n();
-  const { setOpen, autoOpen, autoSelect, selectedArtifact, select } =
-    useArtifacts();
+  const artifacts = useArtifactsOptional();
 
-  if (name === "web_search") {
+  const displayMatch =
+    result !== undefined && isDisplaySamplePayload(result)
+      ? null
+      : (findDisplayConfigForTool(name, skillDisplayMap, args) ??
+        null);
+  const displayItems =
+    displayMatch && result !== undefined
+      ? normalizeDisplaySources(result, displayMatch.display).map((item, index) => ({
+          ...item,
+          index: index + 1,
+          skillName: displayMatch.skillName,
+          mode: displayMatch.display.mode,
+        }))
+      : [];
+  if (displayItems.length > 0) {
+    return (
+      <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;
-    if (typeof args.query === "string") {
-      label = t.toolCalls.searchOnWebFor(args.query);
+    if (query) {
+      label =
+        name === "web_search"
+          ? t.toolCalls.searchOnWebFor(query)
+          : t.toolCalls.searchFor(query);
     }
     return (
       <ChainOfThoughtStep key={id} label={label} icon={SearchIcon}>
-        {Array.isArray(result) && (
-          <ChainOfThoughtSearchResults>
-            {result.map((item) => (
-              <ChainOfThoughtSearchResult key={item.url}>
-                <a href={item.url} target="_blank" rel="noopener noreferrer">
-                  {item.title}
-                </a>
-              </ChainOfThoughtSearchResult>
-            ))}
-          </ChainOfThoughtSearchResults>
+        {searchItems.length > 0 && (
+          <WebSearchResultsList results={searchItems} />
         )}
       </ChainOfThoughtStep>
     );
@@ -336,16 +423,19 @@ function ToolCall({
       description = t.toolCalls.writeFile;
     }
     const path: string | undefined = (args as { path: string })?.path;
-    if (isLoading && isLast && autoOpen && autoSelect && path && !result) {
-      setTimeout(() => {
-        const url = new URL(
+    const artifactPath =
+      name === "write_file" && path
+        ? new URL(
             `write-file:${path}?message_id=${messageId}&tool_call_id=${id}`,
-        ).toString();
-        if (selectedArtifact === url) {
+          ).toString()
+        : path;
+    if (artifacts && isLoading && isLast && artifacts.autoOpen && artifacts.autoSelect && path && !result) {
+      setTimeout(() => {
+        if (!artifactPath || artifacts.selectedArtifact === artifactPath) {
           return;
         }
-        select(url, true);
-        setOpen(true);
+        artifacts.select(artifactPath, true);
+        artifacts.setOpen(true);
       }, 100);
     }
 
@@ -356,12 +446,11 @@ function ToolCall({
         label={description}
         icon={NotebookPenIcon}
         onClick={() => {
-          select(
-            new URL(
-              `write-file:${path}?message_id=${messageId}&tool_call_id=${id}`,
-            ).toString(),
-          );
-          setOpen(true);
+          if (!artifactPath || !artifacts) {
+            return;
+          }
+          artifacts.select(artifactPath);
+          artifacts.setOpen(true);
         }}
       >
         {path && (
@@ -410,6 +499,17 @@ function ToolCall({
         icon={ListTodoIcon}
       ></ChainOfThoughtStep>
     );
+  } else if (name === "update_artifact") {
+    const title = typeof args.title === "string" ? args.title : undefined;
+    const type = args.type as string | undefined;
+    const label = title ?? (type === "code" ? "生成代码" : "生成文档");
+    return (
+      <ChainOfThoughtStep key={id} label={label} icon={NotebookPenIcon}>
+        <ChainOfThoughtSearchResult>
+          {type === "code" ? "代码文件" : "Markdown 文档"}
+        </ChainOfThoughtSearchResult>
+      </ChainOfThoughtStep>
+    );
   } else {
     const description: string | undefined = (args as { description: string })
       ?.description;
@@ -436,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;
@@ -468,14 +568,24 @@ function convertToSteps(messages: Message[]): CoTStep[] {
         };
         const toolCallId = tool_call.id;
         if (toolCallId) {
-          const toolCallResult = findToolCallResult(toolCallId, messages);
-          if (toolCallResult) {
+          const toolCallResult = findToolCallResult(
+            toolCallId,
+            messages,
+            tool_call.name,
+          );
+          if (toolCallResult !== undefined) {
+            if (typeof toolCallResult === "string") {
               try {
-              const json = JSON.parse(toolCallResult);
-              step.result = json;
+                step.result = JSON.parse(toolCallResult) as Record<
+                  string,
+                  unknown
+                >;
               } catch {
                 step.result = toolCallResult;
               }
+            } else {
+              step.result = toolCallResult;
+            }
           }
         }
         steps.push(step);
@@ -484,3 +594,114 @@ function convertToSteps(messages: Message[]): CoTStep[] {
   }
   return steps;
 }
+
+function WebSearchResultsList({ results }: { results: SearchResultItem[] }) {
+  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, idx) => (
+          <SearchResultCard key={item.url ?? idx} item={item} />
+        ))}
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
+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;
+  const date = item.published_date ?? item.publishedDate ?? item.date;
+  let sourceLabel: string | undefined = item.source;
+  if (item.url) {
+    try {
+      sourceLabel = new URL(item.url).hostname.replace(/^www\./, "");
+    } catch {
+      sourceLabel = sourceLabel ?? item.url;
+    }
+  }
+  return (
+    <>
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        className="bg-card hover:bg-accent block w-full cursor-pointer rounded-lg border p-3 text-left transition-colors"
+      >
+        {item.title && (
+          <div className="text-foreground line-clamp-1 text-sm font-medium">
+            {item.title}
+          </div>
+        )}
+        {(sourceLabel || date) && (
+          <div className="text-muted-foreground mt-1 flex items-center gap-2 text-xs">
+            {sourceLabel && <span className="truncate">{sourceLabel}</span>}
+            {sourceLabel && date && <span>·</span>}
+            {date && <span>{date}</span>}
+          </div>
+        )}
+        {content && (
+          <div className="text-muted-foreground mt-1.5 line-clamp-2 text-xs leading-relaxed">
+            {content}
+          </div>
+        )}
+      </button>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent className="max-w-2xl">
+          <DialogHeader>
+            <DialogTitle className="pr-6 text-base leading-relaxed">
+              {item.title ?? "检索结果"}
+            </DialogTitle>
+            {(sourceLabel || date) && (
+              <DialogDescription className="flex items-center gap-2 text-xs">
+                {sourceLabel && <span>{sourceLabel}</span>}
+                {sourceLabel && date && <span>·</span>}
+                {date && <span>{date}</span>}
+              </DialogDescription>
+            )}
+          </DialogHeader>
+          {content && (
+            <div className="text-foreground max-h-[60vh] overflow-y-auto whitespace-pre-wrap text-sm leading-relaxed">
+              {content}
+            </div>
+          )}
+          {item.url && (
+            <div className="text-muted-foreground border-t pt-3 text-xs break-all">
+              {item.url}
+            </div>
+          )}
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

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

@@ -1,7 +1,9 @@
 import type { Message } from "@langchain/langgraph-sdk";
-import { FileIcon, Loader2Icon } from "lucide-react";
+import { ClockIcon, FileIcon, Loader2Icon } from "lucide-react";
 import {
   memo,
+  useCallback,
+  useContext,
   useMemo,
   type AnchorHTMLAttributes,
   type ImgHTMLAttributes,
@@ -23,37 +25,79 @@ import {
 import { Task, TaskTrigger } from "@/components/ai-elements/task";
 import { Badge } from "@/components/ui/badge";
 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,
   parseUploadedFiles,
+  stripArtifactTag,
   stripUploadedFilesTag,
   type FileInMessage,
 } from "@/core/messages/utils";
 import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
+import {
+  applyInlineCitations,
+  type RuntimeDisplaySource,
+} from "@/core/skill-display/runtime";
 import { humanMessagePlugins } from "@/core/streamdown";
+import { desensitize } from "@/lib/desensitize";
 import { cn } from "@/lib/utils";
 
+import { CitationLink } from "../citations/citation-link";
 import { CopyButton } from "../copy-button";
-
-import { MarkdownContent } from "./markdown-content";
+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";
 
+/**
+ * Resolve an in-conversation file path to a fetchable URL.
+ *
+ * On a public read-only share (`ThreadContext.publicShareCode` set) artifact
+ * URLs point at the unauthenticated `/api/public/shares/{code}/files/...`
+ * endpoint; otherwise they use the normal auth-gated thread artifact route.
+ */
+function useArtifactResolver(threadId: string): (path: string) => string {
+  const publicShareCode = useContext(ThreadContext)?.publicShareCode;
+  return useCallback(
+    (path: string) => {
+      if (publicShareCode) {
+        const normalized = path.startsWith("/") ? path : `/${path}`;
+        return `${getBackendBaseURL()}/api/public/shares/${encodeURIComponent(
+          publicShareCode,
+        )}/files${normalized}`;
+      }
+      return resolveArtifactURL(path, threadId);
+    },
+    [publicShareCode, threadId],
+  );
+}
+
 export function MessageListItem({
   className,
   message,
   isLoading,
   threadId,
   tokenUsageEnabled = false,
+  displaySources = [],
+  extraRehypePlugins,
 }: {
   className?: string;
   message: Message;
   isLoading?: boolean;
   threadId: string;
   tokenUsageEnabled?: boolean;
+  displaySources?: RuntimeDisplaySource[];
+  extraRehypePlugins?: ReturnType<typeof useRehypeSplitWordsIntoSpans>;
 }) {
   const isHuman = message.type === "human";
+  const messageMarkdown =
+    extractContentFromMessage(message) ??
+    extractReasoningContentFromMessage(message) ??
+    "";
   return (
     <AIElementMessage
       className={cn("group/conversation-message relative w-full", className)}
@@ -65,6 +109,8 @@ export function MessageListItem({
         isLoading={isLoading}
         threadId={threadId}
         tokenUsageEnabled={tokenUsageEnabled}
+        displaySources={displaySources}
+        extraRehypePlugins={extraRehypePlugins}
       />
       {!isLoading && (
         <MessageToolbar
@@ -74,13 +120,13 @@ export function MessageListItem({
           )}
         >
           <div className="flex gap-1">
-            <CopyButton
-              clipboardData={
-                extractContentFromMessage(message) ??
-                extractReasoningContentFromMessage(message) ??
-                ""
-              }
+            <CopyButton clipboardData={messageMarkdown} />
+            {!isHuman && messageMarkdown && (
+              <DownloadWordButton
+                markdown={messageMarkdown}
+                fileName="message"
               />
+            )}
           </div>
         </MessageToolbar>
       )}
@@ -101,6 +147,7 @@ function MessageImage({
   threadId: string;
   maxWidth?: string;
 }) {
+  const resolveArtifact = useArtifactResolver(threadId);
   if (!src) return null;
 
   const imgClassName = cn("overflow-hidden rounded-lg", `max-w-[${maxWidth}]`);
@@ -109,7 +156,7 @@ function MessageImage({
     return <img className={imgClassName} src={src} alt={alt} {...props} />;
   }
 
-  const url = src.startsWith("/mnt/") ? resolveArtifactURL(src, threadId) : src;
+  const url = src.startsWith("/mnt/") ? resolveArtifact(src) : src;
 
   return (
     <a href={url} target="_blank" rel="noopener noreferrer">
@@ -124,23 +171,51 @@ function MessageContent_({
   isLoading = false,
   threadId,
   tokenUsageEnabled = false,
+  displaySources = [],
+  extraRehypePlugins,
 }: {
   className?: string;
   message: Message;
   isLoading?: boolean;
   threadId: string;
   tokenUsageEnabled?: boolean;
+  displaySources?: RuntimeDisplaySource[];
+  extraRehypePlugins?: ReturnType<typeof useRehypeSplitWordsIntoSpans>;
 }) {
-  const rehypePlugins = useRehypeSplitWordsIntoSpans(isLoading);
+  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(
+    () => (stableExtraPlugins.length ? [...stableExtraPlugins, ...baseRehypePlugins] : baseRehypePlugins),
+    [stableExtraPlugins, baseRehypePlugins],
+  );
+  const askTimes = useChatAskTimes();
   const isHuman = message.type === "human";
+  const resolveArtifact = useArtifactResolver(threadId);
   const components = useMemo(
     () => ({
       img: (props: ImgHTMLAttributes<HTMLImageElement>) => (
         <MessageImage {...props} threadId={threadId} maxWidth="90%" />
       ),
       a: ({ href, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) => {
+        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 = resolveArtifactURL(href, threadId);
+          const url = resolveArtifact(href);
           return (
             <a
               {...props}
@@ -153,7 +228,12 @@ function MessageContent_({
         return <a {...props} href={href} />;
       },
     }),
-    [threadId],
+    [threadId, resolveArtifact],
+  );
+
+  const messageTime = formatAskedTime(
+    message.additional_kwargs?.client_ts ??
+      (message.id ? askTimes[message.id] : undefined),
   );
 
   const rawContent = extractContentFromMessage(message);
@@ -173,10 +253,10 @@ function MessageContent_({
 
   const contentToDisplay = useMemo(() => {
     if (isHuman) {
-      return rawContent ? stripUploadedFilesTag(rawContent) : "";
+      return rawContent ? stripArtifactTag(stripUploadedFilesTag(rawContent)) : "";
     }
-    return rawContent ?? "";
-  }, [rawContent, isHuman]);
+    return applyInlineCitations(rawContent ?? "", displaySources);
+  }, [rawContent, isHuman, displaySources]);
 
   const filesList =
     files && files.length > 0 ? (
@@ -191,7 +271,7 @@ function MessageContent_({
           <TaskTrigger title="">
             <div className="text-muted-foreground flex w-full cursor-default items-center gap-2 text-sm select-none">
               <Loader className="size-4" />
-              <span>{contentToDisplay}</span>
+              <span>{desensitize(contentToDisplay)}</span>
             </div>
           </TaskTrigger>
         </Task>
@@ -205,7 +285,7 @@ function MessageContent_({
       <AIElementMessageContent className={className}>
         <Reasoning isStreaming={isLoading}>
           <ReasoningTrigger />
-          <ReasoningContent>{reasoningContent}</ReasoningContent>
+          <ReasoningContent>{desensitize(reasoningContent)}</ReasoningContent>
         </Reasoning>
         <MessageTokenUsage
           enabled={tokenUsageEnabled}
@@ -224,7 +304,7 @@ function MessageContent_({
         components={components}
         parseIncompleteMarkdown={false}
       >
-        {contentToDisplay}
+        {desensitize(contentToDisplay)}
       </AIElementMessageResponse>
     ) : null;
     return (
@@ -235,6 +315,7 @@ function MessageContent_({
             {messageResponse}
           </AIElementMessageContent>
         )}
+        <MessageTimeStamp time={messageTime} align="right" />
       </div>
     );
   }
@@ -242,22 +323,72 @@ function MessageContent_({
   return (
     <AIElementMessageContent className={className}>
       {filesList}
-      <MarkdownContent
+      <div data-reference-batch-id={message.id} className="contents">
+        <AssistantDisplayContent
           content={contentToDisplay}
+          displaySources={displaySources}
           isLoading={isLoading}
+          renderSkillDisplayBlocks={false}
           rehypePlugins={[...rehypePlugins, [rehypeKatex, { output: "html" }]]}
-        className="my-3"
           components={components}
         />
+      </div>
       <MessageTokenUsage
         enabled={tokenUsageEnabled}
         isLoading={isLoading}
         message={message}
       />
+      {!isLoading && contentToDisplay ? (
+        <MessageTimeStamp time={messageTime} align="left" />
+      ) : null}
     </AIElementMessageContent>
   );
 }
 
+/**
+ * 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
  */
@@ -346,6 +477,7 @@ function RichFileCard({
   threadId: string;
 }) {
   const { t } = useI18n();
+  const resolveArtifact = useArtifactResolver(threadId);
   const isUploading = file.status === "uploading";
   const isImage = isImageFile(file.filename);
 
@@ -378,7 +510,7 @@ function RichFileCard({
 
   if (!file.path) return null;
 
-  const fileUrl = resolveArtifactURL(file.path, threadId);
+  const fileUrl = resolveArtifact(file.path);
 
   if (isImage) {
     return (
@@ -424,3 +556,172 @@ function RichFileCard({
 }
 
 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, "");
+}