fix(flushing): 收紧空阀门区域高度

Runtime model checks previously mapped every authenticated endpoint failure to models_unavailable. Treat request failures as service outages and retry failed checks after five seconds; empty model configurations remain distinct.

.dockerignore

@@ -3,8 +3,10 @@ node_modules
 out
 build
 .git
+.env
+.env.*
 .env*.local
 README.md
 docker-compose.yml
 Dockerfile
-.dockerignore
+.dockerignore

.env

@@ -1,16 +0,0 @@
-KEYCLOAK_CLIENT_ID="tjwater"
-KEYCLOAK_CLIENT_SECRET="83h0n413hau9bldzWdEaq6xRfASv24s5"
-KEYCLOAK_ISSUER="https://keycloak.waternetwork.cn/realms/tjwater"
-NEXTAUTH_SECRET="eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiS"
-NEXTAUTH_URL="https://demo.waternetwork.cn/"
-
-# 为前端暴露的变量添加 NEXT_PUBLIC_ 前缀
-NEXT_PUBLIC_BACKEND_URL="https://server.waternetwork.cn"
-NEXT_PUBLIC_AGENT_URL="https://agent.waternetwork.cn"
-NEXT_PUBLIC_AUDIO_SERVICE_URL="https://tts.waternetwork.cn"
-NEXT_PUBLIC_MAP_URL="https://geoserver.waternetwork.cn/geoserver"
-NEXT_PUBLIC_MAP_WORKSPACE="tjwater"
-NEXT_PUBLIC_MAP_EXTENT="13490131, 3630016, 13525879, 3666968.25"
-NEXT_PUBLIC_NETWORK_NAME="tjwater"
-NEXT_PUBLIC_MAPBOX_TOKEN="pk.eyJ1IjoiemhpZnUiLCJhIjoiY205azNyNGY1MGkyZDJxcTJleDUwaHV1ZCJ9.wOmSdOnDDdre-mB1Lpy6Fg"
-NEXT_PUBLIC_TIANDITU_TOKEN="e3e8ad95ee911741fa71ed7bff2717ec"

.env.example

@@ -0,0 +1,14 @@
+KEYCLOAK_CLIENT_ID="tjwater"
+KEYCLOAK_CLIENT_SECRET="replace-with-keycloak-client-secret"
+KEYCLOAK_ISSUER="https://keycloak.example.com/realms/tjwater"
+NEXTAUTH_SECRET="replace-with-nextauth-secret"
+NEXTAUTH_URL="https://frontend.example.com/"
+
+BACKEND_URL="https://server.example.com"
+AGENT_URL="https://agent.example.com"
+MAP_URL="https://geoserver.example.com/geoserver"
+MAP_WORKSPACE="tjwater"
+MAP_EXTENT="13490131,3630016,13525879,3666968.25"
+NETWORK_NAME="tjwater"
+MAPBOX_TOKEN="replace-with-public-mapbox-token"
+TIANDITU_TOKEN="replace-with-public-tianditu-token"

.gitea/workflows/package.yml

@@ -1,166 +1,21 @@
-name: Build Push and Deploy
+name: Frontend CI/CD v2
 
 on:
   push:
     tags:
       - "v*"
-      - "latest"
+  workflow_dispatch: {}
 
 jobs:
-  docker-image:
-    runs-on: ubuntu-22.04
-    permissions:
-      contents: read
-    defaults:
-      run:
-        shell: sh
-
-    steps:
-      - name: Checkout code
-        env:
-          SERVER_URL: ${{ github.server_url }}
-          REPOSITORY: ${{ github.repository }}
-          COMMIT_SHA: ${{ github.sha }}
-          GIT_USERNAME: ${{ github.actor }}
-          GIT_TOKEN: ${{ github.token }}
-        run: |
-          case "$SERVER_URL" in
-            http://*)
-              AUTH_SERVER_URL="http://${GIT_USERNAME}:${GIT_TOKEN}@${SERVER_URL#http://}"
-              ;;
-            https://*)
-              AUTH_SERVER_URL="https://${GIT_USERNAME}:${GIT_TOKEN}@${SERVER_URL#https://}"
-              ;;
-            *)
-              AUTH_SERVER_URL="$SERVER_URL"
-              ;;
-          esac
-
-          if [ ! -d .git ]; then
-            git init .
-          fi
-
-          if git remote get-url origin >/dev/null 2>&1; then
-            git remote set-url origin "${AUTH_SERVER_URL}/${REPOSITORY}.git"
-          else
-            git remote add origin "${AUTH_SERVER_URL}/${REPOSITORY}.git"
-          fi
-
-          git fetch --depth=1 origin "$COMMIT_SHA"
-          git checkout --force --detach FETCH_HEAD
-          git clean -ffdx
-
-      - name: Normalize image metadata
-        env:
-          RAW_REGISTRY_HOST: ${{ vars.REGISTRY_HOST }}
-          RAW_REPOSITORY: ${{ github.repository }}
-          IMAGE_TAG: ${{ github.ref_name }}
-        run: |
-          REGISTRY_HOST="${RAW_REGISTRY_HOST#http://}"
-          REGISTRY_HOST="${REGISTRY_HOST#https://}"
-          REGISTRY_HOST="${REGISTRY_HOST%/}"
-          REPOSITORY_PATH="${RAW_REPOSITORY#/}"
-          IMAGE_REPOSITORY_PATH="$(printf '%s' "$REPOSITORY_PATH" | tr '[:upper:]' '[:lower:]')"
-          IMAGE_NAME="${REGISTRY_HOST}/${IMAGE_REPOSITORY_PATH}"
-          {
-            echo "REGISTRY_HOST=${REGISTRY_HOST}"
-            echo "REPOSITORY_PATH=${REPOSITORY_PATH}"
-            echo "IMAGE_REPOSITORY_PATH=${IMAGE_REPOSITORY_PATH}"
-            echo "IMAGE_NAME=${IMAGE_NAME}"
-            echo "IMAGE_TAG=${IMAGE_TAG}"
-            echo "IMAGE_REF=${IMAGE_NAME}:${IMAGE_TAG}"
-          } >> "$GITHUB_ENV"
-
-      - name: Login to Gitea Container Registry
-        run: |
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login "$REGISTRY_HOST" \
-            --username "${{ secrets.REGISTRY_USERNAME }}" \
-            --password-stdin
-
-      - name: Build and Push Image
-        run: |
-          push_with_retry() {
-            image_ref="$1"
-            attempt=1
-            max_attempts=3
-
-            while [ "$attempt" -le "$max_attempts" ]; do
-              if docker push "$image_ref"; then
-                return 0
-              fi
-
-              if [ "$attempt" -eq "$max_attempts" ]; then
-                return 1
-              fi
-
-              echo "Push failed for $image_ref (attempt $attempt/$max_attempts); retrying in 10s..."
-              attempt=$((attempt + 1))
-              sleep 10
-            done
-          }
-
-          docker build \
-            -f ./Dockerfile \
-            -t "${IMAGE_NAME}:${IMAGE_TAG}" \
-            -t "${IMAGE_NAME}:latest" \
-            --build-arg NEXT_PUBLIC_BACKEND_URL="${{ vars.NEXT_PUBLIC_BACKEND_URL }}" \
-            --build-arg NEXT_PUBLIC_AGENT_URL="${{ vars.NEXT_PUBLIC_AGENT_URL }}" \
-            --build-arg NEXT_PUBLIC_AUDIO_SERVICE_URL="${{ vars.NEXT_PUBLIC_AUDIO_SERVICE_URL }}" \
-            --build-arg NEXT_PUBLIC_MAP_URL="${{ vars.NEXT_PUBLIC_MAP_URL }}" \
-            --build-arg NEXT_PUBLIC_MAP_WORKSPACE="${{ vars.NEXT_PUBLIC_MAP_WORKSPACE }}" \
-            --build-arg NEXT_PUBLIC_MAP_EXTENT="${{ vars.NEXT_PUBLIC_MAP_EXTENT }}" \
-            --build-arg NEXT_PUBLIC_NETWORK_NAME="${{ vars.NEXT_PUBLIC_NETWORK_NAME }}" \
-            --build-arg NEXT_PUBLIC_MAPBOX_TOKEN="${{ secrets.NEXT_PUBLIC_MAPBOX_TOKEN }}" \
-            --build-arg NEXT_PUBLIC_TIANDITU_TOKEN="${{ secrets.NEXT_PUBLIC_TIANDITU_TOKEN }}" \
-            .
-          push_with_retry "${IMAGE_NAME}:${IMAGE_TAG}"
-          push_with_retry "${IMAGE_NAME}:latest"
-
-      - name: Notify Deploy Server
-        run: |
-          post_deploy_webhook() {
-            label="$1"
-            payload="$2"
-
-            http_code=$(curl -sS -D /tmp/deploy_headers.txt -o /tmp/deploy_response.txt -w "%{http_code}" -X POST "${{ vars.DEPLOY_WEBHOOK_URL }}" \
-              -H "Content-Type: application/json" \
-              -H "Authorization: Bearer ${{ secrets.DEPLOY_WEBHOOK_TOKEN }}" \
-              -d "$payload")
-
-            echo "[$label] webhook HTTP status: ${http_code}"
-            if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
-              return 0
-            fi
-
-            echo "[$label] response headers:"
-            cat /tmp/deploy_headers.txt
-            echo "[$label] response body:"
-            cat /tmp/deploy_response.txt
-            return 1
-          }
-
-          PRIMARY_PAYLOAD="{\"image\":\"${IMAGE_REF}\",\"tag\":\"${IMAGE_TAG}\",\"repo\":\"${REPOSITORY_PATH}\"}"
-          FALLBACK_PAYLOAD="{\"image\":\"${IMAGE_REF}\",\"tag\":\"${IMAGE_TAG}\",\"repo\":\"${IMAGE_REPOSITORY_PATH}\"}"
-
-          echo "Deploy webhook target: ${{ vars.DEPLOY_WEBHOOK_URL }}"
-          echo "Deploy payload(primary): image=${IMAGE_REF}, tag=${IMAGE_TAG}, repo=${REPOSITORY_PATH}"
-          if post_deploy_webhook "primary" "$PRIMARY_PAYLOAD"; then
-            exit 0
-          fi
-
-          echo "Primary webhook request failed, retrying with lowercase repo path..."
-          echo "Deploy payload(fallback): image=${IMAGE_REF}, tag=${IMAGE_TAG}, repo=${IMAGE_REPOSITORY_PATH}"
-          if post_deploy_webhook "fallback" "$FALLBACK_PAYLOAD"; then
-            exit 0
-          fi
-
-          echo "Deploy webhook failed after primary and fallback attempts."
-          exit 1
-
-  deploy-fallback-log:
-    runs-on: ubuntu-22.04
-    needs: docker-image
-    if: failure()
-    steps:
-      - name: Deployment not triggered
-        run: echo "Image build/push failed, deployment webhook was not called."
+  build-test-publish-and-deploy:
+    uses: OrgTJWater/ci-templates/.gitea/workflows/container-cd.yml@main
+    with:
+      image_name: gitea.waternetwork.cn/orgtjwater/tjwaterfrontend_refine
+      dockerfile: Dockerfile
+      build_context: .
+      deploy_service: frontend
+      deploy_host: 192.168.1.114
+    secrets:
+      REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
+      REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+      DEV_DEPLOY_SSH_KEY: ${{ secrets.DEV_DEPLOY_SSH_KEY }}

.github/copilot-instructions.md

@@ -1,60 +0,0 @@
-# Copilot Instructions for TJWaterFrontend_Refine
-
-## Environment Setup
-
-1. **Node.js**: Ensure you have Node.js v18 or later installed.
-2. **Dependencies**: Run `npm install` to install all project dependencies.
-3. **Environment Variables**: Create a `.env.local` file in the root directory with
-
-Using bash setup dependencies:
-
-```bash
-npm install
-```
-
-## Build, Test, and Lint
-
-- **Dev Server**: `npm run dev` (Runs with increased memory limit: `--max_old_space_size=4096`)
-- **Build**: `npm run build`
-- **Lint**: `npm run lint` (ESLint)
-- **Test**: `npm run test` (Jest)
-  - Run a specific test file: `npm run test -- <path/to/file>`
-  - Run a specific test case: `npm run test -- -t 'test name'`
-
-## High-Level Architecture
-
-- **Framework**: **Next.js 16 (App Router)** integrated with **Refine** (`@refinedev/core`).
-- **Routing**:
-  - Routes are defined in `src/app`.
-  - Refine resources (e.g., `/network-simulation`, `/hydraulic-simulation/*`) map directly to these routes.
-  - Configuration is central in `src/app/_refine_context.tsx`.
-- **State Management**:
-  - **Global App State**: **Zustand** (`src/store`).
-  - **Server State**: Managed by Refine hooks (`useList`, `useOne`, etc.) via **React Query**.
-- **Authentication**:
-  - **NextAuth.js** handling Keycloak integration.
-  - Session token is synced to Zustand (`useAuthStore`) in `RefineContext`.
-- **Data Layer**:
-  - Custom Data Provider: `src/providers/data-provider`.
-  - API Utilities: `src/lib/api.ts`, `src/lib/apiFetch.ts`.
-- **UI & Styling**:
-  - **Material UI (MUI)**: Primary component library (`@mui/material`, `@refinedev/mui`).
-  - **Tailwind CSS v4**: Utility classes for layout and custom styling (`@tailwindcss/postcss`).
-  - **Mapping**: OpenLayers (`ol`), deck.gl, Turf.js.
-  - **Charts**: ECharts, MUI X Charts.
-
-## Key Conventions
-
-- **Refine Integration**:
-  - Use Refine hooks (`useTable`, `useForm`, `useNavigation`) for data-heavy components.
-  - Resources are defined in the `<Refine>` component in `src/app/_refine_context.tsx`.
-- **Project Structure**:
-  - `src/components/`: Grouped by feature (e.g., `olmap`, `project`) or common UI elements.
-  - `src/lib/`: Utility functions and API helpers.
-  - `src/providers/`: Refine providers (data, etc.).
-- **Imports**:
-  - Use absolute imports with `@/` alias (e.g., `@/components`, `@/store`, `@/lib`).
-  - _Note_: `@libs` alias in tsconfig points to non-existent `src/libs` folder; prefer `@/lib`.
-- **Styling**:
-  - Prefer MUI components for standard UI elements.
-  - Use Tailwind utility classes for layout and custom overrides.

.gitignore

@@ -19,6 +19,7 @@
 # misc
 .DS_Store
 *.pem
+/public/runtime-config.js
 
 # debug
 npm-debug.log*
@@ -26,8 +27,9 @@ yarn-debug.log*
 yarn-error.log*
 
 # local env files
-.env*.local
-
+.env
+.env.*
+!.env.example
 # vercel
 .vercel
 
@@ -35,3 +37,5 @@ yarn-error.log*
 *.tsbuildinfo
 next-env.d.ts
 memery.md
+
+docs/

AGENTS.md

@@ -0,0 +1,41 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository is the TJWater web frontend built with Refine, Next.js, React, and MUI. Application source lives under the existing Next.js project folders. Reuse established page, component, provider, map, and chat patterns instead of adding parallel structures. Static assets and public files should remain in the existing asset/public locations. Build output (`.next/`), dependency folders, and local caches are generated and must not be edited by hand.
+
+Deployment files are `Dockerfile`, `docker-compose.yml`, and `.gitea/workflows/package.yml`.
+
+## Build, Test, and Development Commands
+
+Use npm and Node 20 or newer:
+
+```bash
+npm install
+npm run dev
+npm run lint
+npm test
+npm run test:coverage
+npm run build
+npm run start
+```
+
+`npm run dev` starts the Refine/Next development server. `npm run lint` runs ESLint. `npm test` runs Jest. `npm run build` creates the production build.
+
+## Coding Style & Naming Conventions
+
+Use TypeScript and React function components. Follow ESLint and Next.js conventions. Use `PascalCase` for React component files and component names. Use `camelCase` for ordinary TypeScript modules, hooks, stores, providers, utilities, variables, and functions. Next.js route directories under `src/app` use `kebab-case`; route groups and dynamic segments keep the Next.js syntax such as `(main)` and `[...nextauth]`. Keep backend/Agent boundary fields and query parameters in the shape required by the API, typically `snake_case`, and do not translate third-party SDK fields. Prefer MUI components and existing design tokens/patterns for UI. Keep operational screens dense, clear, and task-focused.
+
+## Testing Guidelines
+
+Tests use Jest with React Testing Library. Name tests `*.test.ts` or `*.test.tsx` near the related code when possible. Add tests for user-visible behavior, state transitions, route guards, data transforms, and map/chat interactions. Run `npm test` or `npm run test:coverage` before larger PRs.
+
+## Commit & Pull Request Guidelines
+
+History uses Conventional Commit messages such as `feat(map): add coordinate zoom action` and `fix(chat): hide raw permission metadata`, with occasional Chinese summaries. Prefer `feat(scope):`, `fix(scope):`, or `refactor(scope):`.
+
+PRs should include a UI/behavior summary, verification commands, screenshots for visual changes, and notes for changed environment variables or backend API expectations.
+
+## Security & Configuration Tips
+
+Do not commit `.env`, `.next/`, `node_modules/`, local caches, or private map/API tokens. Public build-time variables should be documented; sensitive values belong in Gitea secrets.

Dockerfile

@@ -1,32 +1,23 @@
-FROM refinedev/node:22 AS base
+FROM node:22.23.1-bookworm-slim AS base
+
+WORKDIR /app/refine
+
+ARG NPM_CONFIG_REGISTRY
+ENV NPM_CONFIG_REGISTRY=${NPM_CONFIG_REGISTRY}
 
 FROM base AS deps
 
-RUN apk add --no-cache libc6-compat
-
 COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./
 
 RUN \
   if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
-  elif [ -f package-lock.json ]; then npm ci; \
+  elif [ -f package-lock.json ]; then npm ci || (echo "===== npm debug logs =====" && find /root/.npm/_logs -maxdepth 1 -type f -name "*-debug-0.log" -print -exec cat {} \; && exit 1); \
   elif [ -f pnpm-lock.yaml ]; then yarn global add pnpm && pnpm i --frozen-lockfile; \
   else echo "Lockfile not found." && exit 1; \
   fi
 
 FROM base AS builder
 
-# 只定义 ARG 接收来自构建命令或 docker-compose.yaml 的参数
-# Next.js 在 build 时会自动读取同名的 ARG 作为环境变量
-ARG NEXT_PUBLIC_BACKEND_URL
-ARG NEXT_PUBLIC_AGENT_URL
-ARG NEXT_PUBLIC_AUDIO_SERVICE_URL
-ARG NEXT_PUBLIC_MAP_URL
-ARG NEXT_PUBLIC_MAP_WORKSPACE
-ARG NEXT_PUBLIC_MAP_EXTENT
-ARG NEXT_PUBLIC_NETWORK_NAME
-ARG NEXT_PUBLIC_MAPBOX_TOKEN
-ARG NEXT_PUBLIC_TIANDITU_TOKEN
-
 COPY --from=deps /app/refine/node_modules ./node_modules
 
 COPY . .
@@ -37,19 +28,22 @@ FROM base AS runner
 
 ENV NODE_ENV=production
 
-COPY --from=builder /app/refine/public ./public
+COPY --from=builder --chown=node:node /app/refine/public ./public
+COPY --chown=node:node docker/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
 
 RUN mkdir .next
-RUN chown refine:nodejs .next
+RUN chown node:node .next
 
-COPY --from=builder --chown=refine:nodejs /app/refine/.next/standalone ./
-COPY --from=builder --chown=refine:nodejs /app/refine/.next/static ./.next/static
+COPY --from=builder --chown=node:node /app/refine/.next/standalone ./
+COPY --from=builder --chown=node:node /app/refine/.next/static ./.next/static
 
-USER refine
+USER node
 
 EXPOSE 3000
 
 ENV PORT=3000
 ENV HOSTNAME="0.0.0.0"
 
+ENTRYPOINT ["/entrypoint.sh"]
 CMD ["node", "server.js"]

FRONTEND_NAMING_AUDIT.md

@@ -0,0 +1,56 @@
+# Frontend Naming Audit
+
+DOC-004 audit for the internal `TJWaterFrontend_Refine` application.
+
+## Local frontend naming
+
+- Next.js route directories under `src/app` are already `kebab-case`: `audit-logs`, `health-risk-analysis`, `hydraulic-simulation`, `monitoring-place-optimization`, `network-simulation`, `scada-data-cleaning`, and `system-admin`.
+- Route groups and dynamic segments keep Next.js syntax: `(main)` and `[...nextauth]`.
+- Local ordinary module filenames now use `camelCase`, including `src/utils/breaksClassification.ts`, `src/components/chat/globalChatboxUtils.ts`, and `src/components/chat/globalChatboxVoice.ts`.
+- React component files remain `PascalCase.tsx`, including `src/app/RefineContext.tsx`, `src/components/chat/GlobalChatboxParts.tsx`, and domain directories under `src/components/olmap`.
+
+## API boundary naming
+
+Frontend request and response boundary fields intentionally keep backend/Agent wire names. Examples include `project_id`, `user_id`, `scheme_name`, `scheme_type`, `start_time`, `end_time`, `session_id`, `request_id`, and `keep_message_count`.
+
+Current direct API calls mostly use new `kebab-case` URL paths, including:
+
+- `/api/v1/admin/projects`
+- `/api/v1/audit/logs`
+- `/api/v1/projects/open`
+- `/api/v1/project-info`
+- `/api/v1/schemes`
+- `/api/v1/sensor-placement-schemes`
+- `/api/v1/burst-analysis`
+- `/api/v1/valve-isolation-analysis`
+- `/api/v1/flushing-analysis`
+- `/api/v1/contaminant-simulation`
+- `/api/v1/simulations/run-by-date`
+- `/api/v1/burst-detection/detect`
+- `/api/v1/burst-location/locate`
+- `/api/v1/scada/by-ids-field-time-range`
+- `/api/v1/composite/clean-scada`
+- `/api/v1/agent/chat/render-ref/{render_ref}`
+
+## Legacy URL inventory
+
+The frontend no longer calls these active legacy URLs directly. The backend still exposes them as deprecated compatibility aliases:
+
+| Current frontend URL | Files | Suggested target |
+| --- | --- | --- |
+| `/api/v1/openproject/` | `src/contexts/ProjectContext.tsx` | `/api/v1/projects/open` or `/api/v1/project/open` |
+| `/api/v1/project_info/` | `src/contexts/ProjectContext.tsx` | `/api/v1/project-info` |
+| `/api/v1/getallschemes/` | burst, burst simulation, contaminant, flushing scheme query components | `/api/v1/schemes` |
+| `/api/v1/getallsensorplacements/` | `src/components/olmap/MonitoringPlaceOptimization/SchemeQuery.tsx` | `/api/v1/sensor-placement-schemes` |
+| `/api/v1/sensorplacementscheme/create` | `src/components/olmap/MonitoringPlaceOptimization/OptimizationParameters.tsx` | `/api/v1/sensor-placement-schemes` |
+| `/api/v1/burst_analysis/` | `src/components/olmap/BurstSimulation/AnalysisParameters.tsx` | `/api/v1/burst-analysis` |
+| `/api/v1/valve_isolation_analysis/` | `src/components/olmap/BurstSimulation/ValveIsolation.tsx` | `/api/v1/valve-isolation-analysis` |
+| `/api/v1/flushing_analysis/` | `src/components/olmap/FlushingAnalysis/AnalysisParameters.tsx` | `/api/v1/flushing-analysis` |
+| `/api/v1/contaminant_simulation/` | `src/components/olmap/ContaminantSimulation/AnalysisParameters.tsx` | `/api/v1/contaminant-simulation` |
+| `/api/v1/runsimulationmanuallybydate/` | `src/components/olmap/core/Controls/Timeline.tsx` | `/api/v1/simulations/run-by-date` |
+
+Already migrated frontend code leaves comments showing older pre-`/api/v1` URLs in `src/components/olmap/core/Controls/Toolbar.tsx`; those comments are historical only and are not active calls.
+
+## Follow-up
+
+Continue tracking broad passive legacy backend routes under the shared legacy API compatibility strategy.

README.MD

@@ -1,48 +1,91 @@
-# my-refine-app
+# TJWaterFrontend_Refine 内部前端
 
-<div align="center" style="margin: 30px;">
-    <a href="https://refine.dev">
-    <img alt="refine logo" src="https://refine.ams3.cdn.digitaloceanspaces.com/readme/refine-readme-banner.png">
-    </a>
-</div>
-<br/>
+`TJWaterFrontend_Refine` 是 TJWater 内部 Web 前端，基于 Refine、Next.js、React 和 MUI 构建。它承载管网地图、业务管理、用户认证、智能体聊天、SCADA/历史数据查看和结果可视化等内部功能。
 
-This [Refine](https://github.com/refinedev/refine) project was generated with [create refine-app](https://github.com/refinedev/refine/tree/master/packages/create-refine-app).
+## 技术栈
 
-## Getting Started
+- Next.js 16
+- React 19
+- Refine 5
+- MUI 6 / MUI X
+- OpenLayers、deck.gl、Turf
+- Zustand、NextAuth、Jest
 
-A React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility ✨
+## 目录结构
 
-Refine's hooks and components simplifies the development process and eliminates the repetitive tasks by providing industry-standard solutions for crucial aspects of a project, including authentication, access control, routing, networking, state management, and i18n.
-
-## Available Scripts
-
-### Running the development server.
-
-```bash
-    npm run dev
+```text
+src/app/              Next.js App Router 页面
+src/components/       复用 UI 组件
+src/providers/        Refine、认证、数据和主题 provider
+src/hooks/            业务 hooks
+src/utils/            通用工具
+public/               静态资源
+scripts/              运行时配置和辅助脚本
+Dockerfile            镜像构建文件
+docker-compose.yml    本地编排参考
 ```
 
-### Building for production.
+新增功能应复用现有页面、组件、provider、地图和聊天结构，避免创建平行体系。
+
+## 本地开发
+
+要求 Node.js 20 或更高版本：
 
 ```bash
-    npm run build
+npm install
+npm run dev
 ```
 
-### Running the production server.
+`npm run dev` 会先执行运行时配置生成，再启动 Next.js 开发服务。
+
+## 常用命令
 
 ```bash
-    npm run start
+npm run lint
+npm test
+npm run test:coverage
+npm run build
+npm run start
+docker build -t tjwater-frontend:local .
 ```
 
-## Learn More
+- `npm run lint`：运行 ESLint。
+- `npm test`：运行 Jest。
+- `npm run test:coverage`：生成测试覆盖率。
+- `npm run build`：生成生产构建。
+- `npm run start`：启动生产模式服务。
 
-To learn more about **Refine**, please check out the [Documentation](https://refine.dev/docs)
+## 配置说明
 
-- **REST Data Provider** [Docs](https://refine.dev/docs/core/providers/data-provider/#overview)
-- **Material UI** [Docs](https://refine.dev/docs/ui-frameworks/mui/tutorial/)
-- **Custom Auth Provider** [Docs](https://refine.dev/docs/core/providers/auth-provider/)
+运行时配置由 `scripts/generate-runtime-config.mjs` 生成。API 地址、Agent 地址、Keycloak/认证参数、地图服务地址和其他环境差异配置应通过环境变量或部署配置注入。
 
-## License
+只有允许暴露给浏览器的配置才应进入 public/runtime 配置；密钥和私有 token 不能进入前端构建产物。
 
-MIT
+## 开发规范
+
+- React 组件文件使用 `PascalCase.tsx`。
+- 普通 TypeScript 模块、hooks、store、provider 和工具使用 `camelCase.ts`。
+- `src/app` 路由目录使用 `kebab-case`，保留 Next.js 路由组和动态段语法。
+- UI 优先沿用 MUI、Refine 和既有地图/聊天界面模式。
+- 与后端或 Agent 通信的字段保持接口原始格式，通常为 `snake_case`。
+
+## 测试与发布
+
+提交前建议运行：
+
+```bash
+npm run lint
+npm test
+```
+
+发布镜像前运行：
+
+```bash
+npm run build
+```
+
+Gitea 包工作流位于 `.gitea/workflows/package.yml`，通常由 tag 触发构建和推送镜像。
+
+## 安全规则
+
+不要提交 `.env`、`.next/`、`node_modules/`、本地缓存、私有地图/API token、客户数据或部署密钥。CI/CD 凭据应放在 Gitea secrets 中。

contracts/manifest.json

@@ -0,0 +1,9 @@
+{
+  "contract_version": "1.0.0",
+  "contracts": {
+    "agent": {
+      "file": "agent-v1.openapi.json",
+      "sha256": "94bd8914597c56b6429160e8c556993ac0617ad079de2980a4b6cb9fdf89c039"
+    }
+  }
+}

docker-compose.yml

@@ -6,19 +6,15 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
-      args:
-        NEXT_PUBLIC_BACKEND_URL: ${NEXT_PUBLIC_BACKEND_URL}
-        NEXT_PUBLIC_AGENT_URL: ${NEXT_PUBLIC_AGENT_URL}
-        NEXT_PUBLIC_AUDIO_SERVICE_URL: ${NEXT_PUBLIC_AUDIO_SERVICE_URL}
-        NEXT_PUBLIC_MAP_URL: ${NEXT_PUBLIC_MAP_URL}
-        NEXT_PUBLIC_MAP_WORKSPACE: ${NEXT_PUBLIC_MAP_WORKSPACE}
-        NEXT_PUBLIC_MAP_EXTENT: ${NEXT_PUBLIC_MAP_EXTENT}
-        NEXT_PUBLIC_NETWORK_NAME: ${NEXT_PUBLIC_NETWORK_NAME}
-        NEXT_PUBLIC_MAPBOX_TOKEN: ${NEXT_PUBLIC_MAPBOX_TOKEN}
-        NEXT_PUBLIC_TIANDITU_TOKEN: ${NEXT_PUBLIC_TIANDITU_TOKEN}
-    env_file:
-      - .env
     environment:
+      BACKEND_URL: ${BACKEND_URL}
+      AGENT_URL: ${AGENT_URL}
+      MAP_URL: ${MAP_URL}
+      MAP_WORKSPACE: ${MAP_WORKSPACE}
+      MAP_EXTENT: ${MAP_EXTENT}
+      NETWORK_NAME: ${NETWORK_NAME}
+      MAPBOX_TOKEN: ${MAPBOX_TOKEN}
+      TIANDITU_TOKEN: ${TIANDITU_TOKEN}
       KEYCLOAK_CLIENT_ID: ${KEYCLOAK_CLIENT_ID}
       KEYCLOAK_CLIENT_SECRET: ${KEYCLOAK_CLIENT_SECRET}
       KEYCLOAK_ISSUER: ${KEYCLOAK_ISSUER}

docker/entrypoint.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+set -eu
+
+node <<'NODE'
+const fs = require("fs");
+
+const parseExtent = (value) => {
+  if (!value) {
+    return [13508849, 3608036, 13555781, 3633813];
+  }
+
+  const extent = value.split(",").map(Number);
+  return extent.length === 4 && extent.every(Number.isFinite)
+    ? extent
+    : [13508849, 3608036, 13555781, 3633813];
+};
+
+const config = {
+  BACKEND_URL: process.env.BACKEND_URL || "http://127.0.0.1:8000",
+  AGENT_URL: process.env.AGENT_URL || "http://127.0.0.1:8788",
+  MAP_URL: process.env.MAP_URL || "http://127.0.0.1:8080/geoserver",
+  MAP_WORKSPACE: process.env.MAP_WORKSPACE || "tjwater",
+  MAP_EXTENT: parseExtent(process.env.MAP_EXTENT),
+  NETWORK_NAME: process.env.NETWORK_NAME || "tjwater",
+  MAPBOX_TOKEN: process.env.MAPBOX_TOKEN || "",
+  TIANDITU_TOKEN: process.env.TIANDITU_TOKEN || "",
+};
+
+fs.writeFileSync(
+  "/app/refine/public/runtime-config.js",
+  `window.__TJWATER_RUNTIME_CONFIG__ = ${JSON.stringify(config)};\n`,
+);
+NODE
+
+exec "$@"

docs/chat-streaming-animation-notes.md

@@ -0,0 +1,167 @@
+# Chat 流式生成动画改造经验
+
+本文记录 `src/components/chat` 里本次文字生成、图表生成、滚动稳定性的改造经验。重点不是复盘代码行数，而是总结后续继续调整时应遵守的工程边界和交互原则。
+
+## 目标
+
+- 文本生成要有连续感，避免 token 直接到达导致忽快忽慢。
+- 已生成内容必须稳定，不能反复淡入、重排或闪烁。
+- 图表和工具调用插入时不能让“分析结果”边框剧烈抖动。
+- 底部自动滚动要跟随，但不能每个 token 都强制贴底。
+- 动画应辅助理解，不能比内容本身更抢眼。
+
+## 文本流式生成
+
+### 经验结论
+
+不要把后端 token 到达节奏直接暴露给 UI。后端 token 通常不均匀，前端如果每个 token 都立即渲染，会出现文字跳动、滚动频繁、动画看不出来等问题。
+
+更稳的做法是类似 Vercel AI SDK `smoothStream` 的思路：
+
+- token 先进入缓冲区。
+- 前端按固定节奏释放 chunk。
+- chunk 尽量按词、短语、标点边界切分。
+- 当缓冲积压较大时，自适应加快 drain，避免显示落后真实输出太多。
+
+当前实现采用：
+
+- `TOKEN_PLAYBACK_INTERVAL_MS = 16`
+- 小缓冲按较短 chunk 输出。
+- 大缓冲最多每帧释放 `160` 字符。
+- 中文优先使用 `Intl.Segmenter("zh", { granularity: "word" })`。
+- 非 token 事件前强制 flush，保证工具调用、done、error 的顺序正确。
+
+### 踩坑
+
+- 只做 `setTimeout(120ms)` 批量 flush 不够。它只是减少更新次数，并不能形成稳定播放节奏。
+- interval 太小，例如 `8ms`，浏览器调度不一定更稳定，反而可能增加 React 更新压力。
+- 中文按 `Intl.Segmenter` 的单个词输出会显得慢，必须结合缓冲长度动态放大 chunk。
+- `done`、`error`、`tool_call` 前如果不 flush，会造成文本和结构事件顺序错乱。
+
+## Markdown 动画
+
+### 经验结论
+
+Markdown 是流式文本动画里最容易出问题的部分。原因是 `ReactMarkdown` 每次都会重新解析完整内容，原始 Markdown 字符索引和最终 DOM 文本节点索引不一致。
+
+典型例子：
+
+- `**加粗**` 的原始长度包含 `**`，但可见文本不包含。
+- 列表符号、链接语法、代码块围栏都可能影响原始索引。
+- 新增文本可能落在 `p`、`li`、`strong`、`code` 等不同节点里。
+
+因此不要简单用原始 `text.length` 或 `fadeFrom` 去对应 Markdown 渲染后的 DOM 文本。
+
+当前策略：
+
+- Markdown 仍完整解析，保证格式正确。
+- 在 rehype 阶段处理 AST。
+- 从 AST 尾部反向找最后的可见 text node。
+- 只给最后一段尾部文本加动画。
+- 每次最多动画最后 `48` 个字符，避免大 chunk 整段闪烁。
+
+### 踩坑
+
+- 用 `text.length` 作为 React key 会导致整段 Markdown remount，所有文本都会重新淡入。
+- CSS animation 和 Web Animations 同时作用在同一个 span 上，会出现闪烁或动画重启。
+- 在 render 阶段读写 ref 会触发 React hooks lint 规则，也容易产生不可控渲染。
+- 反向遍历 AST 时拆分 text node 要注意顺序。使用 `unshift` 时应先插入动画尾巴，再插入稳定文本，最终 DOM 才是“稳定文本在前，动画尾巴在后”。
+
+## 当前文字动画建议
+
+推荐保留轻量动画：
+
+- 使用 Web Animations，在 `useLayoutEffect` 中启动，避免先完整显示一帧再裁切。
+- 使用 `clip-path` 做左到右 reveal。
+- 叠加轻微 opacity：当前约 `0.46 -> 1`。
+- 时长控制在 `120ms - 260ms`。
+
+不要做：
+
+- 外层整段 `motion.div` 淡入。
+- 每次流式更新都改变 key。
+- 对整个 Markdown AST 的新增范围大面积包 span。
+- 在生成中对已有文本重复动画。
+
+## 滚动和边框稳定
+
+### 经验结论
+
+滚动条在最底部时，内容增长会不断改变 `scrollTop`。如果每个 token 都执行 `scrollTop = scrollHeight` 或 `scrollIntoView`，最后一个 assistant turn 的边框会产生明显抖动。
+
+当前策略：
+
+- 生成中不再每个 token 精确贴底。
+- 底部保留生成缓冲区，当前约 `180px`。
+- 只有缓冲被消耗到阈值后才恢复滚动。
+- 用户离开底部附近后，不再强制自动跟随。
+- 使用 `scrollbar-gutter: stable` 减少滚动条出现/消失造成的宽度变化。
+
+### 踩坑
+
+- “锁最大高度”不是正确方向。问题不是高度无限增长，而是底部锚定过于频繁。
+- 每 token 自动滚动会把视口不断向下推，视觉上就是边框抖动。
+- 滚动判断阈值要和底部缓冲一致，否则缓冲刚出现就被判断为“离开底部”。
+
+## 图表生成
+
+### 经验结论
+
+图表不能等数据到达后突然插入。图表生成应先占位，再 crossfade，再让图表内部动画接管。
+
+当前策略：
+
+- 工具调用 pending 时使用固定尺寸 `ChartGenerationSkeleton`。
+- 图表真实数据到达后，继续短暂保留 skeleton overlay。
+- ECharts 在 skeleton 下方淡入。
+- 容器尺寸保持一致，避免边框高度突变。
+- ECharts 内部使用 enter/update 动画，而不是外层布局动画。
+
+图表类型动画建议：
+
+- 折线图：平滑 enter，面积渐显。
+- 柱状图：柱子从基线增长，并对数据点轻微 stagger。
+- 饼图：使用 expansion/sweep 类进入动画。
+- update 动画要短于 enter 动画。
+
+### 踩坑
+
+- 只给外层图表卡片 fade in 不够，插入瞬间仍可能造成内容跳变。
+- skeleton 和最终图表尺寸不一致，会导致边框先长再缩。
+- 图表更新时不要重建组件，尽量让 ECharts diff 数据并执行内部 transition。
+
+## 状态提示
+
+“正在生成”状态是有价值的，应该保留。它承担了部分动感和系统状态反馈，不需要让文本动画本身过于夸张。
+
+推荐：
+
+- 状态放在“分析结果”标题行右侧。
+- 使用小尺寸、低干扰的 pulsing dots。
+- 不使用末尾光标，避免和业务文本混在一起。
+
+## 验证建议
+
+每次调整流式动画后至少跑：
+
+```bash
+npx eslint src/components/chat/AgentMarkdownBlock.tsx src/components/chat/AgentTurn.tsx src/components/chat/ChatInlineChart.tsx src/components/chat/AgentWorkspace.tsx src/components/chat/GlobalChatbox.tsx src/components/chat/hooks/useAgentChatSession.ts
+npx tsc --noEmit
+npm test -- src/components/chat/hooks/useAgentChatSession.lifecycle.test.tsx src/components/chat/hooks/useAgentChatSession.actions.test.tsx src/components/chat/AgentWorkspace.test.tsx src/components/chat/ChatInlineChart.test.ts --runInBand
+```
+
+人工验证重点：
+
+- 长中文回答是否明显落后后端真实速度。
+- Markdown 加粗、列表、代码块是否乱序。
+- 底部自动滚动时“分析结果”边框是否抖动。
+- 工具调用 pending 到图表出现时是否有高度跳变。
+- 用户手动上滚后是否停止强制跟随。
+
+## 后续调整原则
+
+1. 先调节 token playback，再调动画。
+2. 动画只作用于新增内容，已有内容不能重播。
+3. Markdown 动画优先保守，宁可弱一点，也不能破坏文本顺序。
+4. 图表和工具调用先稳定布局，再考虑视觉效果。
+5. 滚动跟随要有缓冲，不能逐 token 贴底。

package.json

@@ -6,14 +6,16 @@
     "node": ">=20"
   },
   "scripts": {
-    "dev": "cross-env NODE_OPTIONS=--max_old_space_size=4096 refine dev",
-    "build": "refine build",
-    "start": "refine start",
+    "dev": "npm run runtime:config && cross-env NODE_OPTIONS=--max_old_space_size=4096 next dev",
+    "runtime:config": "node scripts/generate-runtime-config.mjs",
+    "build": "next build",
+    "start": "next start",
     "lint": "eslint .",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
-    "refine": "refine",
+    "api:generate": "openapi-typescript contracts/server-v1.openapi.json -o src/generated/serverApi.ts && openapi-typescript contracts/agent-v1.openapi.json -o src/generated/agentApi.ts",
+    "api:check": "node scripts/check-api-contracts.mjs",
     "pipeline:trigger": "bash scripts/trigger-gitea-pipeline.sh"
   },
   "dependencies": {
@@ -38,12 +40,14 @@
     "deck.gl": "^9.1.14",
     "echarts": "^6.0.0",
     "echarts-for-react": "^3.0.5",
+    "edge-tts-ts": "^1.0.0",
     "framer-motion": "^12.38.0",
     "js-cookie": "^3.0.5",
     "next": "^16.1.6",
     "next-auth": "^4.24.5",
     "ol": "^10.7.0",
-    "postcss": "^8.5.6",
+    "openapi-fetch": "^0.17.0",
+    "postcss": "8.5.25",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-draggable": "^4.5.0",
@@ -55,15 +59,11 @@
     "zustand": "^5.0.11"
   },
   "overrides": {
-    "fast-xml-parser": "5.5.9"
+    "fast-xml-parser": "5.5.9",
+    "postcss": "8.5.25",
+    "sharp": "0.35.3"
   },
   "devDependencies": {
-    "@refinedev/cli": "^2.16.52",
-    "@refinedev/devtools": "^2.0.5",
-    "@refinedev/devtools-internal": "^2.0.2",
-    "@refinedev/devtools-server": "^2.0.2",
-    "@refinedev/devtools-shared": "^2.0.2",
-    "@refinedev/devtools-ui": "^2.0.3",
     "@svgr/webpack": "^8.1.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
@@ -80,10 +80,8 @@
     "eslint-config-next": "^16.1.6",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
+    "openapi-typescript": "^7.13.0",
     "ts-jest": "^29.4.6",
     "typescript": "^5.8.3"
-  },
-  "refine": {
-    "projectId": "4LwOCL-BBaV29-qUYMAJ"
   }
 }

public/login-logo-mark.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72" role="img" aria-labelledby="title">
+  <title id="title">TJWater</title>
+  <rect width="72" height="72" rx="18" fill="#1478d4"/>
+  <path d="M36 13c-7.8 11.1-16.1 19.4-16.1 29.3A16.1 16.1 0 0 0 36 58.4a16.1 16.1 0 0 0 16.1-16.1C52.1 32.4 43.8 24.1 36 13Z" fill="#f5fbfc"/>
+  <path d="M26.5 43.5h19M31 36.5l5 7 5-7" fill="none" stroke="#0b8f82" stroke-linecap="round" stroke-linejoin="round" stroke-width="3"/>
+  <circle cx="26.5" cy="43.5" r="2.7" fill="#0b8f82"/>
+  <circle cx="45.5" cy="43.5" r="2.7" fill="#0b8f82"/>
+</svg>

public/login-network-blueprint.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 900" preserveAspectRatio="xMidYMid slice">
+  <rect width="1440" height="900" fill="#edf5f5"/>
+  <path d="M0 0h790L650 900H0Z" fill="#dceced"/>
+  <path d="M0 182c187-78 303-73 451-16 153 59 288 47 409-25M0 552c193-45 327-19 461 74 128 90 266 100 410 47" fill="none" stroke="#c8dddd" stroke-width="2"/>
+  <g fill="none" stroke="#a9ccce" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M-32 725 178 608l142 51 155-190 184 67 176-205" stroke-width="5"/>
+    <path d="m178 608 25-222 151-92 121 175" stroke-width="3"/>
+    <path d="m203 386-92-95 55-161M354 294l92-141 152 58 98-106" stroke-width="3"/>
+    <path d="m320 659-4 132 171 81M659 536l88 116 124-42" stroke-width="3"/>
+  </g>
+  <g fill="#edf5f5" stroke="#1478d4" stroke-width="4">
+    <circle cx="178" cy="608" r="10"/><circle cx="203" cy="386" r="9"/>
+    <circle cx="354" cy="294" r="9"/><circle cx="475" cy="469" r="11"/>
+    <circle cx="659" cy="536" r="10"/><circle cx="747" cy="652" r="9"/>
+    <circle cx="320" cy="659" r="8"/>
+  </g>
+  <g fill="#0b8f82">
+    <circle cx="111" cy="291" r="6"/><circle cx="166" cy="130" r="6"/>
+    <circle cx="446" cy="153" r="7"/><circle cx="598" cy="211" r="6"/>
+    <circle cx="696" cy="105" r="6"/><circle cx="316" cy="791" r="6"/>
+    <circle cx="487" cy="872" r="6"/><circle cx="835" cy="331" r="7"/>
+  </g>
+  <g fill="none" stroke="#86b8bb" stroke-width="2" opacity=".72">
+    <circle cx="615" cy="448" r="222"/><circle cx="615" cy="448" r="276"/>
+    <circle cx="615" cy="448" r="334"/>
+  </g>
+  <g fill="#1478d4" opacity=".08">
+    <rect x="40" y="40" width="118" height="10" rx="5"/>
+    <rect x="40" y="62" width="72" height="6" rx="3"/>
+  </g>
+</svg>

scripts/check-api-contracts.mjs

@@ -0,0 +1,57 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const manifest = JSON.parse(
+  await readFile(new URL("../contracts/manifest.json", import.meta.url), "utf8"),
+);
+const run = promisify(execFile);
+const projectRoot = fileURLToPath(new URL("../", import.meta.url));
+const generator = join(
+  projectRoot,
+  "node_modules",
+  "openapi-typescript",
+  "bin",
+  "cli.js",
+);
+const temporaryDirectory = await mkdtemp(
+  join(tmpdir(), "tjwater-api-contracts-"),
+);
+
+try {
+  for (const [name, contract] of Object.entries(manifest.contracts)) {
+    const contractPath = fileURLToPath(
+      new URL(`../contracts/${contract.file}`, import.meta.url),
+    );
+    const payload = await readFile(contractPath);
+    const actual = createHash("sha256").update(payload).digest("hex");
+    if (actual !== contract.sha256) {
+      throw new Error(
+        `${name} contract hash mismatch: expected ${contract.sha256}, got ${actual}`,
+      );
+    }
+
+    const generatedName = `${name}Api.ts`;
+    const temporaryOutput = join(temporaryDirectory, generatedName);
+    await run(process.execPath, [generator, contractPath, "-o", temporaryOutput]);
+    const expectedOutput = await readFile(
+      new URL(`../src/generated/${generatedName}`, import.meta.url),
+    );
+    const generatedOutput = await readFile(temporaryOutput);
+    if (!expectedOutput.equals(generatedOutput)) {
+      throw new Error(
+        `${basename(contract.file)} generated type is stale: run \`npm run api:generate\``,
+      );
+    }
+  }
+} finally {
+  await rm(temporaryDirectory, { recursive: true, force: true });
+}
+
+console.log(
+  `validated API contract mirrors and generated types for ${manifest.contract_version}`,
+);

scripts/generate-runtime-config.mjs

@@ -0,0 +1,39 @@
+import nextEnv from "@next/env";
+import fs from "node:fs";
+import path from "node:path";
+
+const projectDir = process.cwd();
+const { loadEnvConfig } = nextEnv;
+
+loadEnvConfig(projectDir, process.env.NODE_ENV !== "production");
+
+const parseExtent = (value) => {
+  if (!value) {
+    return [13508849, 3608036, 13555781, 3633813];
+  }
+
+  const extent = value.split(",").map(Number);
+  return extent.length === 4 && extent.every(Number.isFinite)
+    ? extent
+    : [13508849, 3608036, 13555781, 3633813];
+};
+
+const config = {
+  BACKEND_URL: process.env.BACKEND_URL || "http://127.0.0.1:8000",
+  AGENT_URL: process.env.AGENT_URL || "http://127.0.0.1:8788",
+  MAP_URL: process.env.MAP_URL || "http://127.0.0.1:8080/geoserver",
+  MAP_WORKSPACE: process.env.MAP_WORKSPACE || "tjwater",
+  MAP_EXTENT: parseExtent(process.env.MAP_EXTENT),
+  NETWORK_NAME: process.env.NETWORK_NAME || "tjwater",
+  MAPBOX_TOKEN: process.env.MAPBOX_TOKEN || "",
+  TIANDITU_TOKEN: process.env.TIANDITU_TOKEN || "",
+};
+
+const outputPath = path.join(projectDir, "public", "runtime-config.js");
+
+fs.writeFileSync(
+  outputPath,
+  `window.__TJWATER_RUNTIME_CONFIG__ = ${JSON.stringify(config)};\n`,
+);
+
+console.log(`Generated ${path.relative(projectDir, outputPath)}`);

src/app/(main)/(map)/health-risk-analysis/page.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+import { MapPanelSkeleton, MapTimelineSkeleton } from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+import { HealthRiskProvider } from "@components/olmap/HealthRiskAnalysis/HealthRiskContext";
+import StyleLegend from "@components/olmap/core/Controls/StyleLegend";
+import {
+  RAINBOW_COLORS,
+  RISK_BREAKS,
+} from "@components/olmap/HealthRiskAnalysis/types";
+import { Box } from "@mui/material";
+
+const Timeline = dynamic(
+  () => import("@components/olmap/HealthRiskAnalysis/Timeline"),
+  {
+    loading: () => <MapTimelineSkeleton />,
+  },
+);
+const HealthRiskStatistics = dynamic(
+  () =>
+    import("@components/olmap/HealthRiskAnalysis/HealthRiskStatistics"),
+  {
+    loading: () => <MapPanelSkeleton variant="health-risk-analysis" />,
+  },
+);
+const PredictDataPanel = dynamic(
+  () => import("@components/olmap/HealthRiskAnalysis/PredictDataPanel"),
+  {
+    loading: () => null,
+  },
+);
+
+export default function Home() {
+  return (
+    <HealthRiskProvider>
+      <MapToolbar
+        queryType="realtime"
+        hiddenButtons={["style"]}
+        HistoryPanel={PredictDataPanel}
+      />
+      <Timeline />
+      <HealthRiskStatistics />
+      <Box className="absolute bottom-40 right-4 drop-shadow-xl flex flex-row items-end max-w-screen-lg overflow-x-auto z-10">
+        <StyleLegend
+          layerName="管道"
+          layerId="health-risk"
+          property="健康风险"
+          colors={RAINBOW_COLORS}
+          type="line"
+          dimensions={Array(RAINBOW_COLORS.length).fill(2)}
+          breaks={[0, ...RISK_BREAKS]}
+        />
+      </Box>
+    </HealthRiskProvider>
+  );
+}

src/app/(main)/(map)/hydraulic-simulation/burst-detection/page.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+import { MapPanelSkeleton } from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+
+const BurstDetectionPanel = dynamic(
+  () => import("@/components/olmap/BurstDetection/BurstDetectionPanel"),
+  {
+    loading: () => <MapPanelSkeleton variant="burst-detection" />,
+  },
+);
+
+export default function Home() {
+  return (
+    <>
+      <MapToolbar
+        queryType="scheme"
+        schemeType="burst_detection"
+        hiddenButtons={["style"]}
+      />
+      <BurstDetectionPanel />
+    </>
+  );
+}

src/app/(main)/(map)/hydraulic-simulation/burst-location/page.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+import { MapPanelSkeleton } from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+
+const BurstLocationPanel = dynamic(
+  () => import("@/components/olmap/BurstLocation/BurstLocationPanel"),
+  {
+    loading: () => <MapPanelSkeleton variant="burst-location" />,
+  },
+);
+
+export default function Home() {
+  return (
+    <>
+      <MapToolbar
+        queryType="scheme"
+        schemeType="burst_location"
+        hiddenButtons={["style"]}
+      />
+      <BurstLocationPanel />
+    </>
+  );
+}

src/app/(main)/(map)/hydraulic-simulation/burst-simulation/page.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+import { MapPanelSkeleton } from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+
+const BurstPipeAnalysisPanel = dynamic(
+  () => import("@/components/olmap/BurstSimulation/BurstPipeAnalysisPanel"),
+  {
+    loading: () => <MapPanelSkeleton variant="burst-simulation" />,
+  },
+);
+
+export default function Home() {
+  return (
+    <>
+      <MapToolbar
+        queryType="scheme"
+        schemeType="burst_analysis"
+        enableCompare
+      />
+      <BurstPipeAnalysisPanel />
+    </>
+  );
+}

src/app/(main)/(map)/hydraulic-simulation/contaminant-simulation/page.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+import { MapPanelSkeleton } from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+
+const WaterQualityPanel = dynamic(
+  () => import("@/components/olmap/ContaminantSimulation/WaterQualityPanel"),
+  {
+    loading: () => <MapPanelSkeleton variant="contaminant-simulation" />,
+  },
+);
+
+export default function Home() {
+  return (
+    <>
+      <MapToolbar
+        queryType="scheme"
+        schemeType="contaminant_analysis"
+        enableCompare
+      />
+      <WaterQualityPanel />
+    </>
+  );
+}

src/app/(main)/(map)/hydraulic-simulation/dma-leak-detection/page.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+import { MapPanelSkeleton } from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+
+const DMALeakDetectionPanel = dynamic(
+  () => import("@/components/olmap/DMALeakDetection/DMALeakDetectionPanel"),
+  {
+    loading: () => <MapPanelSkeleton variant="dma-leak-detection" />,
+  },
+);
+
+export default function Home() {
+  return (
+    <>
+      <MapToolbar
+        queryType="scheme"
+        schemeType="dma_leak_identification"
+        hiddenButtons={["style"]}
+      />
+      <DMALeakDetectionPanel />
+    </>
+  );
+}

src/app/(main)/(map)/hydraulic-simulation/flushing-analysis/page.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+import { MapPanelSkeleton } from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+
+const FlushingAnalysisPanel = dynamic(
+  () => import("@/components/olmap/FlushingAnalysis/FlushingAnalysisPanel"),
+  {
+    loading: () => <MapPanelSkeleton variant="flushing-analysis" />,
+  },
+);
+
+export default function Home() {
+  return (
+    <>
+      <MapToolbar queryType="scheme" schemeType="flushing_analysis" />
+      <FlushingAnalysisPanel />
+    </>
+  );
+}

src/app/(main)/(map)/layout.tsx

@@ -0,0 +1,9 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import MapComponent from "@components/olmap/core/MapComponent";
+
+export default function MapLayout({ children }: { children: ReactNode }) {
+  return <MapComponent>{children}</MapComponent>;
+}

src/app/(main)/(map)/monitoring-place-optimization/page.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+import { MapPanelSkeleton } from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+
+const MonitoringPlaceOptimizationPanel = dynamic(
+  () =>
+    import(
+      "@components/olmap/MonitoringPlaceOptimization/MonitoringPlaceOptimizationPanel"
+    ),
+  {
+    loading: () => (
+      <MapPanelSkeleton variant="monitoring-place-optimization" />
+    ),
+  },
+);
+
+export default function Home() {
+  return (
+    <>
+      <MapToolbar hiddenButtons={["style"]} />
+      <MonitoringPlaceOptimizationPanel />
+    </>
+  );
+}

src/app/(main)/(map)/network-simulation/page.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import { useCallback, useState } from "react";
+
+import {
+  MapPanelSkeleton,
+  MapTimelineSkeleton,
+} from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+
+const Timeline = dynamic(
+  () => import("@components/olmap/core/Controls/Timeline"),
+  {
+    loading: () => <MapTimelineSkeleton />,
+  },
+);
+const SCADADeviceList = dynamic(
+  () => import("@components/olmap/SCADA/SCADADeviceList"),
+  {
+    loading: () => <MapPanelSkeleton variant="network-simulation" />,
+  },
+);
+const SCADADataPanel = dynamic(
+  () => import("@components/olmap/SCADA/SCADADataPanel"),
+  {
+    loading: () => null,
+  },
+);
+
+export default function Home() {
+  const [selectedDeviceIds, setSelectedDeviceIds] = useState<string[]>([]);
+  const [panelVisible, setPanelVisible] = useState<boolean>(false);
+
+  const handleSelectionChange = useCallback((ids: string[]) => {
+    setSelectedDeviceIds(ids);
+    setPanelVisible(ids.length > 0);
+  }, []);
+
+  const handleDeviceClick = useCallback(() => {
+    setPanelVisible(true);
+  }, []);
+
+  return (
+    <>
+      <MapToolbar queryType="realtime" />
+      <Timeline />
+      <SCADADeviceList
+        onDeviceClick={handleDeviceClick}
+        onSelectionChange={handleSelectionChange}
+        selectedDeviceIds={selectedDeviceIds}
+      />
+      <SCADADataPanel deviceIds={selectedDeviceIds} visible={panelVisible} />
+    </>
+  );
+}

src/app/(main)/(map)/scada-data-cleaning/page.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import { useCallback, useState } from "react";
+
+import { MapPanelSkeleton } from "@components/loading/MapComponentSkeletons";
+import MapToolbar from "@components/olmap/core/Controls/Toolbar";
+
+const SCADADeviceList = dynamic(
+  () => import("@components/olmap/SCADA/SCADADeviceList"),
+  {
+    loading: () => <MapPanelSkeleton variant="scada-data-cleaning" />,
+  },
+);
+const SCADADataPanel = dynamic(
+  () => import("@components/olmap/SCADA/SCADADataPanel"),
+  {
+    loading: () => null,
+  },
+);
+
+export default function Home() {
+  const [selectedDeviceIds, setSelectedDeviceIds] = useState<string[]>([]);
+  const [panelVisible, setPanelVisible] = useState<boolean>(false);
+
+  const handleSelectionChange = useCallback((ids: string[]) => {
+    setSelectedDeviceIds(ids);
+    setPanelVisible(ids.length > 0);
+  }, []);
+
+  const handleDeviceClick = useCallback(() => {
+    setPanelVisible(true);
+  }, []);
+
+  return (
+    <>
+      <MapToolbar hiddenButtons={["style"]} />
+      <SCADADeviceList
+        onDeviceClick={handleDeviceClick}
+        onSelectionChange={handleSelectionChange}
+        selectedDeviceIds={selectedDeviceIds}
+        showCleaning={true}
+      />
+      <SCADADataPanel
+        deviceIds={selectedDeviceIds}
+        visible={panelVisible}
+        showCleaning={true}
+      />
+    </>
+  );
+}

src/app/(main)/audit-logs/page.tsx

@@ -0,0 +1,5 @@
+import { AuditLogPanel } from "@/components/audit/AuditLogPanel";
+
+export default function AuditLogsPage() {
+  return <AuditLogPanel />;
+}

src/app/(main)/health-risk-analysis/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/health-risk-analysis/page.tsx

@@ -1,43 +0,0 @@
-"use client";
-
-import MapComponent from "@components/olmap/core/MapComponent";
-import Timeline from "@components/olmap/HealthRiskAnalysis/Timeline";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-import { HealthRiskProvider } from "@components/olmap/HealthRiskAnalysis/HealthRiskContext";
-import HealthRiskStatistics from "@components/olmap/HealthRiskAnalysis/HealthRiskStatistics";
-import PredictDataPanel from "@components/olmap/HealthRiskAnalysis/PredictDataPanel";
-import StyleLegend from "@components/olmap/core/Controls/StyleLegend";
-import {
-  RAINBOW_COLORS,
-  RISK_BREAKS,
-} from "@components/olmap/HealthRiskAnalysis/types";
-import { Box } from "@mui/material";
-
-export default function Home() {
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      <HealthRiskProvider>
-        <MapComponent>
-          <MapToolbar
-            queryType="realtime"
-            hiddenButtons={["style"]}
-            HistoryPanel={PredictDataPanel}
-          />
-          <Timeline />
-          <HealthRiskStatistics />
-          <Box className="absolute bottom-40 right-4 drop-shadow-xl flex flex-row items-end max-w-screen-lg overflow-x-auto z-10">
-            <StyleLegend
-              layerName="管道"
-              layerId="health-risk"
-              property="健康风险"
-              colors={RAINBOW_COLORS}
-              type="line"
-              dimensions={Array(RAINBOW_COLORS.length).fill(2)}
-              breaks={[0, ...RISK_BREAKS]}
-            />
-          </Box>
-        </MapComponent>
-      </HealthRiskProvider>
-    </div>
-  );
-}

src/app/(main)/hydraulic-simulation/burst-detection/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/hydraulic-simulation/burst-detection/page.tsx

@@ -1,16 +0,0 @@
-"use client";
-
-import MapComponent from "@components/olmap/core/MapComponent";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-import BurstDetectionPanel from "@/components/olmap/BurstDetection/BurstDetectionPanel";
-
-export default function Home() {
-  return (
-    <div className="relative h-full w-full overflow-hidden">
-      <MapComponent>
-        <MapToolbar queryType="scheme" schemeType="burst_detection" hiddenButtons={["style"]} />
-        <BurstDetectionPanel />
-      </MapComponent>
-    </div>
-  );
-}

src/app/(main)/hydraulic-simulation/burst-location/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/hydraulic-simulation/burst-location/page.tsx

@@ -1,20 +0,0 @@
-"use client";
-
-import MapComponent from "@components/olmap/core/MapComponent";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-import BurstLocationPanel from "@/components/olmap/BurstLocation/BurstLocationPanel";
-
-export default function Home() {
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      <MapComponent>
-        <MapToolbar
-          queryType="scheme"
-          schemeType="burst_location"
-          hiddenButtons={["style"]}
-        />
-        <BurstLocationPanel />
-      </MapComponent>
-    </div>
-  );
-}

src/app/(main)/hydraulic-simulation/burst-simulation/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/hydraulic-simulation/burst-simulation/page.tsx

@@ -1,20 +0,0 @@
-"use client";
-
-import MapComponent from "@components/olmap/core/MapComponent";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-import BurstPipeAnalysisPanel from "@/components/olmap/BurstSimulation/BurstPipeAnalysisPanel";
-
-export default function Home() {
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      <MapComponent>
-        <MapToolbar
-          queryType="scheme"
-          schemeType="burst_analysis"
-          enableCompare
-        />
-        <BurstPipeAnalysisPanel />
-      </MapComponent>
-    </div>
-  );
-}

src/app/(main)/hydraulic-simulation/contaminant-simulation/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/hydraulic-simulation/contaminant-simulation/page.tsx

@@ -1,20 +0,0 @@
-"use client";
-
-import MapComponent from "@components/olmap/core/MapComponent";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-import WaterQualityPanel from "@/components/olmap/ContaminantSimulation/WaterQualityPanel";
-
-export default function Home() {
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      <MapComponent>
-        <MapToolbar
-          queryType="scheme"
-          schemeType="contaminant_analysis"
-          enableCompare
-        />
-        <WaterQualityPanel />
-      </MapComponent>
-    </div>
-  );
-}

src/app/(main)/hydraulic-simulation/dma-leak-detection/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/hydraulic-simulation/dma-leak-detection/page.tsx

@@ -1,20 +0,0 @@
-"use client";
-
-import MapComponent from "@components/olmap/core/MapComponent";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-import DMALeakDetectionPanel from "@/components/olmap/DMALeakDetection/DMALeakDetectionPanel";
-
-export default function Home() {
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      <MapComponent>
-        <MapToolbar
-          queryType="scheme"
-          schemeType="dma_leak_identification"
-          hiddenButtons={["style"]}
-        />
-        <DMALeakDetectionPanel />
-      </MapComponent>
-    </div>
-  );
-}

src/app/(main)/hydraulic-simulation/flushing-analysis/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/hydraulic-simulation/flushing-analysis/page.tsx

@@ -1,16 +0,0 @@
-"use client";
-
-import MapComponent from "@components/olmap/core/MapComponent";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-import FlushingAnalysisPanel from "@/components/olmap/FlushingAnalysis/FlushingAnalysisPanel";
-
-export default function Home() {
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      <MapComponent>
-        <MapToolbar queryType="scheme" schemeType="flushing_analysis" />
-        <FlushingAnalysisPanel />
-      </MapComponent>
-    </div>
-  );
-}

src/app/(main)/layout.tsx

@@ -1,11 +1,11 @@
 import type { Metadata } from "next";
 import { cookies } from "next/headers";
-import React, { Suspense } from "react";
+import type { ReactNode } from "react";
 
 import authOptions from "@app/api/auth/[...nextauth]/options";
 import { Header } from "@components/header";
 import { Title } from "@components/title";
-import { MapSkeleton } from "@components/loading/MapSkeleton";
+import { AppSider } from "@components/sider/AppSider";
 import { ThemedLayout } from "@refinedev/mui";
 import { getServerSession } from "next-auth/next";
 import { redirect } from "next/navigation";
@@ -19,7 +19,7 @@ export const metadata: Metadata = META_DATA;
 export default async function MainLayout({
   children,
 }: Readonly<{
-  children: React.ReactNode;
+  children: ReactNode;
 }>) {
   const cookieStore = await cookies();
   const theme = cookieStore.get("theme");
@@ -35,16 +35,20 @@ export default async function MainLayout({
     <ThemedLayout
       Header={Header}
       Title={Title}
+      Sider={AppSider}
       childrenBoxProps={{
-        sx: { height: "100vh", p: 0 },
+        sx: {
+          flex: 1,
+          minHeight: 0,
+          overflow: "auto",
+          p: 0,
+        },
       }}
       containerBoxProps={{
-        sx: { height: "100%" },
+        sx: { height: "100vh", overflow: "hidden" },
       }}
     >
-      <Suspense fallback={<MapSkeleton />}>
-        {children}
-      </Suspense>
+      {children}
     </ThemedLayout>
   );
 }

src/app/(main)/monitoring-place-optimization/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/monitoring-place-optimization/page.tsx

@@ -1,15 +0,0 @@
-"use client";
-
-import MapComponent from "@components/olmap/core/MapComponent";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-import MonitoringPlaceOptimizationPanel from "@components/olmap/MonitoringPlaceOptimization/MonitoringPlaceOptimizationPanel";
-export default function Home() {
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      <MapComponent>
-        <MapToolbar hiddenButtons={["style"]} />
-        <MonitoringPlaceOptimizationPanel />
-      </MapComponent>
-    </div>
-  );
-}

src/app/(main)/network-simulation/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/network-simulation/page.tsx

@@ -1,38 +0,0 @@
-"use client";
-
-import { useCallback, useState } from "react";
-import MapComponent from "@components/olmap/core/MapComponent";
-import Timeline from "@components/olmap/core/Controls/Timeline";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-
-import SCADADeviceList from "@components/olmap/SCADA/SCADADeviceList";
-import SCADADataPanel from "@components/olmap/SCADA/SCADADataPanel";
-
-export default function Home() {
-  const [selectedDeviceIds, setSelectedDeviceIds] = useState<string[]>([]);
-  const [panelVisible, setPanelVisible] = useState<boolean>(false);
-
-  const handleSelectionChange = useCallback((ids: string[]) => {
-    setSelectedDeviceIds(ids);
-    setPanelVisible(ids.length > 0);
-  }, []);
-
-  const handleDeviceClick = useCallback(() => {
-    setPanelVisible(true);
-  }, []);
-
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      <MapComponent>
-        <MapToolbar queryType="realtime" />
-        <Timeline />
-        <SCADADeviceList
-          onDeviceClick={handleDeviceClick}
-          onSelectionChange={handleSelectionChange}
-          selectedDeviceIds={selectedDeviceIds}
-        />
-        <SCADADataPanel deviceIds={selectedDeviceIds} visible={panelVisible} />
-      </MapComponent>
-    </div>
-  );
-}

src/app/(main)/scada-data-cleaning/loading.tsx

@@ -1,5 +0,0 @@
-import { MapSkeleton } from "@components/loading/MapSkeleton";
-
-export default function Loading() {
-  return <MapSkeleton />;
-}

src/app/(main)/scada-data-cleaning/page.tsx

@@ -1,41 +0,0 @@
-"use client";
-
-import { useCallback, useState } from "react";
-import MapComponent from "@components/olmap/core/MapComponent";
-import MapToolbar from "@components/olmap/core/Controls/Toolbar";
-
-import SCADADeviceList from "@components/olmap/SCADA/SCADADeviceList";
-import SCADADataPanel from "@components/olmap/SCADA/SCADADataPanel";
-
-export default function Home() {
-  const [selectedDeviceIds, setSelectedDeviceIds] = useState<string[]>([]);
-  const [panelVisible, setPanelVisible] = useState<boolean>(false);
-
-  const handleSelectionChange = useCallback((ids: string[]) => {
-    setSelectedDeviceIds(ids);
-    setPanelVisible(ids.length > 0);
-  }, []);
-
-  const handleDeviceClick = useCallback(() => {
-    setPanelVisible(true);
-  }, []);
-
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      <MapComponent>
-        <MapToolbar hiddenButtons={["style"]} />
-        <SCADADeviceList
-          onDeviceClick={handleDeviceClick}
-          onSelectionChange={handleSelectionChange}
-          selectedDeviceIds={selectedDeviceIds}
-          showCleaning={true}
-        />
-        <SCADADataPanel
-          deviceIds={selectedDeviceIds}
-          visible={panelVisible}
-          showCleaning={true}
-        />
-      </MapComponent>
-    </div>
-  );
-}

src/app/(main)/system-admin/page.tsx

@@ -0,0 +1,5 @@
+import { SystemAdminPanel } from "@/components/admin/SystemAdminPanel";
+
+export default function SystemAdminPage() {
+  return <SystemAdminPanel />;
+}

src/app/RefineContext.tsx

@@ -0,0 +1,379 @@
+"use client";
+
+import {
+  Refine,
+  type AccessControlProvider,
+  type AuthProvider,
+} from "@refinedev/core";
+import { RefineKbar, RefineKbarProvider } from "@refinedev/kbar";
+import { RefineSnackbarProvider } from "@refinedev/mui";
+import { SessionProvider, signIn, useSession } from "next-auth/react";
+import { usePathname } from "next/navigation";
+import React, { useEffect } from "react";
+
+import routerProvider from "@refinedev/nextjs-router";
+
+import { ColorModeContextProvider } from "@contexts/color-mode";
+import { dataProvider } from "@providers/data-provider";
+import { ProjectProvider } from "@/contexts/ProjectContext";
+import { RoutePermissionGuard } from "@/components/auth/RoutePermissionGuard";
+import { SessionExpiryDialog } from "@/components/auth/SessionExpiryDialog";
+import { useAuthStore } from "@/store/authStore";
+import { useAccessStore } from "@/store/accessStore";
+import { useProjectStore } from "@/store/projectStore";
+import { apiFetch } from "@/lib/apiFetch";
+import { completeLogout, reportLogoutAudit } from "@/lib/logoutFlow";
+import { clearSessionRecoveryDrafts } from "@/lib/sessionRecoveryDraft";
+import { permissionCodes, resourcePermissions } from "@/lib/permissions";
+import { config } from "@config/config";
+import { useAppNotificationProvider } from "@/providers/notification-provider/useAppNotificationProvider";
+
+import { LiaNetworkWiredSolid } from "react-icons/lia";
+import { TbActivity, TbDatabaseEdit, TbLocationPin } from "react-icons/tb";
+import { LuReplace } from "react-icons/lu";
+import { AiOutlineSecurityScan } from "react-icons/ai";
+import { MdCleaningServices, MdOutlineWaterDrop } from "react-icons/md";
+import {
+  FactCheck as FactCheckIcon,
+  ManageAccounts as ManageAccountsIcon,
+  MyLocation as MyLocationIcon,
+  Search as SearchIcon,
+} from "@mui/icons-material";
+
+type RefineContextProps = {
+  defaultMode?: string;
+};
+
+export const RefineContext = (
+  props: React.PropsWithChildren<RefineContextProps>,
+) => (
+  <SessionProvider>
+    <App {...props} />
+  </SessionProvider>
+);
+
+type AppProps = {
+  defaultMode?: string;
+};
+
+const App = (props: React.PropsWithChildren<AppProps>) => {
+  const { data, status } = useSession();
+  const to = usePathname();
+  const setAccessToken = useAuthStore((state) => state.setAccessToken);
+  const markSessionExpired = useAuthStore((state) => state.markSessionExpired);
+  const clearSessionExpired = useAuthStore((state) => state.clearSessionExpired);
+  const currentProjectId = useProjectStore((state) => state.currentProjectId);
+  const permissions = useAccessStore((state) => state.permissions);
+  const setAccessContext = useAccessStore((state) => state.setContext);
+  const setAccessLoading = useAccessStore((state) => state.setLoading);
+  const resetAccess = useAccessStore((state) => state.reset);
+  const can = (permission: string) => permissions.includes(permission);
+
+  useEffect(() => {
+    setAccessToken(
+      typeof data?.accessToken === "string" ? data.accessToken : null,
+    );
+  }, [data?.accessToken, setAccessToken]);
+
+  useEffect(() => {
+    if (data?.error === "SessionExpired") {
+      markSessionExpired("session_max_age");
+      return;
+    }
+    if (data?.error === "RefreshAccessTokenError") {
+      markSessionExpired("refresh_failed");
+      return;
+    }
+    if (status === "authenticated") {
+      clearSessionExpired();
+    }
+  }, [clearSessionExpired, data?.error, markSessionExpired, status]);
+
+  useEffect(() => {
+    if (status !== "authenticated") {
+      resetAccess();
+      return;
+    }
+
+    let cancelled = false;
+    setAccessLoading(true);
+    apiFetch(`${config.BACKEND_URL}/api/v1/access-context`, {
+      projectHeaderMode: currentProjectId ? "include" : "omit",
+      skipAuthRedirect: true,
+    })
+      .then(async (response) => {
+        if (cancelled) return;
+        if (!response.ok) {
+          resetAccess();
+          return;
+        }
+        setAccessContext(await response.json());
+      })
+      .catch(() => {
+        if (!cancelled) resetAccess();
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    currentProjectId,
+    resetAccess,
+    setAccessContext,
+    setAccessLoading,
+    status,
+  ]);
+
+  useEffect(() => {
+    if (status !== "authenticated" || !data?.user?.id) return;
+    const auditKey = `tjwater-login-audit:${data.user.id}`;
+    if (sessionStorage.getItem(auditKey)) return;
+
+    apiFetch(`${config.BACKEND_URL}/api/v1/audit-events`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ event: "login" }),
+      projectHeaderMode: "omit",
+      skipAuthRedirect: true,
+    })
+      .then((response) => {
+        if (response.ok) sessionStorage.setItem(auditKey, "1");
+      })
+      .catch(() => undefined);
+  }, [data?.user?.id, status]);
+
+  if (status === "loading") {
+    return <span>loading...</span>;
+  }
+
+  const authProvider: AuthProvider = {
+    login: async () => {
+      signIn("keycloak", {
+        callbackUrl: to ? to.toString() : "/",
+        redirect: true,
+      });
+      return { success: true };
+    },
+    logout: () =>
+      completeLogout({
+        reportAudit: () =>
+          reportLogoutAudit({
+            endpoint: `${config.BACKEND_URL}/api/v1/audit-events`,
+            accessToken:
+              typeof data?.accessToken === "string"
+                ? data.accessToken
+                : useAuthStore.getState().accessToken,
+          }),
+        clearLocalState: () => {
+          if (data?.user?.id) {
+            sessionStorage.removeItem(`tjwater-login-audit:${data.user.id}`);
+          }
+          clearSessionRecoveryDrafts();
+        },
+        navigate: (path) => window.location.assign(path),
+      }),
+    onError: async (error) => {
+      return { error };
+    },
+    check: async () =>
+      status === "unauthenticated"
+        ? { authenticated: false, redirectTo: "/login" }
+        : { authenticated: true },
+    getPermissions: async () => permissions,
+    getIdentity: async () => {
+      if (!data?.user) return null;
+      return {
+        id: data.user.id,
+        username: data.user.username,
+        name: data.user.name,
+        avatar: data.user.image,
+      };
+    },
+  };
+
+  const accessControlProvider: AccessControlProvider = {
+    can: async ({ resource }) => {
+      const requiredPermission = resource
+        ? resourcePermissions[resource]
+        : undefined;
+      return {
+        can: !requiredPermission || permissions.includes(requiredPermission),
+        reason: requiredPermission
+          ? `需要权限：${requiredPermission}`
+          : undefined,
+      };
+    },
+  };
+
+  const resources = [
+    ...(can(permissionCodes.simulationView)
+      ? [
+          {
+            name: "管网在线模拟",
+            list: "/network-simulation",
+            meta: {
+              icon: <LiaNetworkWiredSolid className="w-6 h-6" />,
+              label: "管网在线模拟",
+            },
+          },
+        ]
+      : []),
+    ...(can(permissionCodes.scadaClean)
+      ? [
+          {
+            name: "SCADA 数据清洗",
+            list: "/scada-data-cleaning",
+            meta: {
+              icon: <TbDatabaseEdit className="w-6 h-6" />,
+              label: "SCADA 数据清洗",
+            },
+          },
+        ]
+      : []),
+    ...(can(permissionCodes.optimizationRun)
+      ? [
+          {
+            name: "监测点优化布置",
+            list: "/monitoring-place-optimization",
+            meta: {
+              icon: <LuReplace className="w-6 h-6" />,
+              label: "监测点优化布置",
+            },
+          },
+        ]
+      : []),
+    ...(can(permissionCodes.riskRun)
+      ? [
+          {
+            name: "健康风险分析",
+            list: "/health-risk-analysis",
+            meta: {
+              icon: <AiOutlineSecurityScan className="w-6 h-6" />,
+              label: "健康风险分析",
+            },
+          },
+        ]
+      : []),
+    ...(can(permissionCodes.simulationRun) || can(permissionCodes.burstRun)
+      ? [
+          {
+            name: "Hydraulic Simulation",
+            meta: { label: "事件模拟" },
+          },
+        ]
+      : []),
+    ...(can(permissionCodes.burstRun)
+      ? [
+          {
+            name: "爆管模拟",
+            list: "/hydraulic-simulation/burst-simulation",
+            meta: {
+              parent: "Hydraulic Simulation",
+              icon: <TbLocationPin className="w-6 h-6" />,
+              label: "爆管模拟",
+            },
+          },
+          {
+            name: "爆管侦测",
+            list: "/hydraulic-simulation/burst-detection",
+            meta: {
+              parent: "Hydraulic Simulation",
+              icon: <TbActivity className="w-6 h-6" />,
+              label: "爆管侦测",
+            },
+          },
+          {
+            name: "爆管定位",
+            list: "/hydraulic-simulation/burst-location",
+            meta: {
+              parent: "Hydraulic Simulation",
+              icon: <MyLocationIcon className="w-6 h-6" />,
+              label: "爆管定位",
+            },
+          },
+          {
+            name: "DMA 漏损识别",
+            list: "/hydraulic-simulation/dma-leak-detection",
+            meta: {
+              parent: "Hydraulic Simulation",
+              icon: <SearchIcon className="w-6 h-6" />,
+              label: "DMA 漏损识别",
+            },
+          },
+        ]
+      : []),
+    ...(can(permissionCodes.simulationRun)
+      ? [
+          {
+            name: "水质模拟",
+            list: "/hydraulic-simulation/contaminant-simulation",
+            meta: {
+              parent: "Hydraulic Simulation",
+              icon: <MdOutlineWaterDrop className="w-6 h-6" />,
+              label: "水质模拟",
+            },
+          },
+          {
+            name: "管道冲洗",
+            list: "/hydraulic-simulation/flushing-analysis",
+            meta: {
+              parent: "Hydraulic Simulation",
+              icon: <MdCleaningServices className="w-6 h-6" />,
+              label: "管道冲洗",
+            },
+          },
+        ]
+      : []),
+    ...(can(permissionCodes.environmentManage)
+      ? [
+          {
+            name: "系统管理",
+            list: "/system-admin",
+            meta: {
+              icon: <ManageAccountsIcon className="w-6 h-6" />,
+              label: "系统管理",
+            },
+          },
+        ]
+      : []),
+    ...(can(permissionCodes.auditView)
+      ? [
+          {
+            name: "审计日志",
+            list: "/audit-logs",
+            meta: {
+              icon: <FactCheckIcon className="w-6 h-6" />,
+              label: "审计日志",
+            },
+          },
+        ]
+      : []),
+  ];
+
+  return (
+    <ProjectProvider>
+      <RefineKbarProvider>
+        <ColorModeContextProvider defaultMode={props.defaultMode}>
+          <RefineSnackbarProvider>
+            <Refine
+              routerProvider={routerProvider}
+              dataProvider={dataProvider}
+              notificationProvider={useAppNotificationProvider}
+              authProvider={authProvider}
+              accessControlProvider={accessControlProvider}
+              resources={resources}
+              options={{
+                syncWithLocation: true,
+                warnWhenUnsavedChanges: true,
+              }}
+            >
+              <SessionExpiryDialog expiresAt={data?.sessionExpiresAt} />
+              <RoutePermissionGuard>{props.children}</RoutePermissionGuard>
+              <RefineKbar />
+            </Refine>
+          </RefineSnackbarProvider>
+        </ColorModeContextProvider>
+      </RefineKbarProvider>
+    </ProjectProvider>
+  );
+};

src/app/_refine_context.tsx

@@ -1,244 +0,0 @@
-"use client";
-
-import { Refine, type AuthProvider } from "@refinedev/core";
-import { RefineKbar, RefineKbarProvider } from "@refinedev/kbar";
-import {
-  RefineSnackbarProvider,
-  useNotificationProvider,
-} from "@refinedev/mui";
-import { SessionProvider, signIn, signOut, useSession } from "next-auth/react";
-import { usePathname } from "next/navigation";
-import React, { useEffect } from "react";
-
-import routerProvider from "@refinedev/nextjs-router";
-
-import { ColorModeContextProvider } from "@contexts/color-mode";
-import { dataProvider } from "@providers/data-provider";
-import { ProjectProvider } from "@/contexts/ProjectContext";
-import { useAuthStore } from "@/store/authStore";
-
-import { LiaNetworkWiredSolid } from "react-icons/lia";
-import { TbDatabaseEdit, TbLocationPin, TbActivity } from "react-icons/tb";
-import { LuReplace } from "react-icons/lu";
-import { AiOutlineSecurityScan } from "react-icons/ai";
-import { MdWater, MdOutlineWaterDrop, MdCleaningServices } from "react-icons/md";
-import {
-  MyLocation as MyLocationIcon,
-  Search as SearchIcon,
-} from "@mui/icons-material";
-
-type RefineContextProps = {
-  defaultMode?: string;
-};
-
-export const RefineContext = (
-  props: React.PropsWithChildren<RefineContextProps>
-) => {
-  return (
-    <SessionProvider>
-      <ProjectProvider>
-        <App {...props} />
-      </ProjectProvider>
-    </SessionProvider>
-  );
-};
-
-type AppProps = {
-  defaultMode?: string;
-};
-
-const App = (props: React.PropsWithChildren<AppProps>) => {
-  const { data, status } = useSession();
-  const to = usePathname();
-  const setAccessToken = useAuthStore((state) => state.setAccessToken);
-
-  useEffect(() => {
-    setAccessToken(typeof data?.accessToken === "string" ? data.accessToken : null);
-  }, [data?.accessToken, setAccessToken]);
-
-  if (status === "loading") {
-    return <span>loading...</span>;
-  }
-
-  const authProvider: AuthProvider = {
-    login: async () => {
-      signIn("keycloak", {
-        callbackUrl: to ? to.toString() : "/",
-        redirect: true,
-      });
-
-      return {
-        success: true,
-      };
-    },
-    logout: async () => {
-      signOut({
-        redirect: true,
-        callbackUrl: "/login",
-      });
-
-      return {
-        success: true,
-      };
-    },
-    onError: async (error) => {
-      if (error.response?.status === 401) {
-        return {
-          logout: true,
-        };
-      }
-
-      return {
-        error,
-      };
-    },
-    check: async () => {
-      if (status === "unauthenticated") {
-        return {
-          authenticated: false,
-          redirectTo: "/login",
-        };
-      }
-
-      return {
-        authenticated: true,
-      };
-    },
-    getPermissions: async () => {
-      return null;
-    },
-    getIdentity: async () => {
-      if (data?.user) {
-        const { user } = data;
-        return {
-          id: user.id,
-          name: user.name,
-          avatar: user.image,
-        };
-      }
-
-      return null;
-    },
-  };
-
-  const defaultMode = props?.defaultMode;
-
-  return (
-    <>
-      <RefineKbarProvider>
-        <ColorModeContextProvider defaultMode={defaultMode}>
-          <RefineSnackbarProvider>
-            <Refine
-              routerProvider={routerProvider}
-              dataProvider={dataProvider}
-              notificationProvider={useNotificationProvider}
-              authProvider={authProvider}
-              resources={[
-                {
-                  name: "管网在线模拟",
-                  list: "/network-simulation",
-                  meta: {
-                    icon: <LiaNetworkWiredSolid className="w-6 h-6" />,
-                    label: "管网在线模拟",
-                  },
-                },
-                {
-                  name: "SCADA 数据清洗",
-                  list: "/scada-data-cleaning",
-                  meta: {
-                    icon: <TbDatabaseEdit className="w-6 h-6" />,
-                    label: "SCADA 数据清洗",
-                  },
-                },
-                {
-                  name: "监测点优化布置",
-                  list: "/monitoring-place-optimization",
-                  meta: {
-                    icon: <LuReplace className="w-6 h-6" />,
-                    label: "监测点优化布置",
-                  },
-                },
-                {
-                  name: "健康风险分析",
-                  list: "/health-risk-analysis",
-                  meta: {
-                    icon: <AiOutlineSecurityScan className="w-6 h-6" />,
-                    label: "健康风险分析",
-                  },
-                },
-                {
-                  name: "Hydraulic Simulation",
-                  meta: {
-                    // icon: <MdWater className="w-6 h-6" />,
-                    label: "事件模拟",
-                  },
-                },
-                {
-                  name: "爆管模拟",
-                  list: "/hydraulic-simulation/burst-simulation",
-                  meta: {
-                    parent: "Hydraulic Simulation",
-                    icon: <TbLocationPin className="w-6 h-6" />,
-                    label: "爆管模拟",
-                  },
-                },
-                {
-                  name: "爆管侦测",
-                  list: "/hydraulic-simulation/burst-detection",
-                  meta: {
-                    parent: "Hydraulic Simulation",
-                    icon: <TbActivity className="w-6 h-6" />,
-                    label: "爆管侦测",
-                  },
-                },
-                {
-                  name: "爆管定位",
-                  list: "/hydraulic-simulation/burst-location",
-                  meta: {
-                    parent: "Hydraulic Simulation",
-                    icon: <MyLocationIcon className="w-6 h-6" />,
-                    label: "爆管定位",
-                  },
-                },
-                {
-                  name: "DMA 漏损识别",
-                  list: "/hydraulic-simulation/dma-leak-detection",
-                  meta: {
-                    parent: "Hydraulic Simulation",
-                    icon: <SearchIcon className="w-6 h-6" />,
-                    label: "DMA 漏损识别",
-                  },
-                },
-                {
-                  name: "水质模拟",
-                  list: "/hydraulic-simulation/contaminant-simulation",
-                  meta: {
-                    parent: "Hydraulic Simulation",
-                    icon: <MdOutlineWaterDrop className="w-6 h-6" />,
-                    label: "水质模拟",
-                  },
-                },
-                {
-                  name: "管道冲洗",
-                  list: "/hydraulic-simulation/flushing-analysis",
-                  meta: {
-                    parent: "Hydraulic Simulation",
-                    icon: <MdCleaningServices className="w-6 h-6" />,
-                    label: "管道冲洗",
-                  },
-                },
-              ]}
-              options={{
-                syncWithLocation: true,
-                warnWhenUnsavedChanges: true,
-              }}
-            >
-              {props.children}
-              <RefineKbar />
-            </Refine>
-          </RefineSnackbarProvider>
-        </ColorModeContextProvider>
-      </RefineKbarProvider>
-    </>
-  );
-};

src/app/api/auth/[...nextauth]/options.test.ts

@@ -0,0 +1,111 @@
+import authOptions from "./options";
+
+describe("NextAuth access token refresh", () => {
+  it("forces a Keycloak refresh for an agent credential request", async () => {
+    const previousEnv = {
+      issuer: process.env.KEYCLOAK_ISSUER,
+      clientId: process.env.KEYCLOAK_CLIENT_ID,
+      clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
+    };
+    process.env.KEYCLOAK_ISSUER = "https://keycloak.example/realms/tjwater";
+    process.env.KEYCLOAK_CLIENT_ID = "frontend";
+    process.env.KEYCLOAK_CLIENT_SECRET = "secret";
+    const originalFetch = globalThis.fetch;
+    const fetchMock = jest.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+          access_token: "fresh-access-token",
+          expires_in: 900,
+          refresh_token: "rotated-refresh-token",
+      }),
+    });
+    globalThis.fetch = fetchMock as typeof fetch;
+
+    try {
+      const jwt = authOptions.callbacks?.jwt as (input: unknown) => Promise<{
+        accessToken?: string;
+        refreshToken?: string;
+      }>;
+      const result = await jwt({
+        token: {
+          accessToken: "still-fresh-access-token",
+          accessTokenExpires: Date.now() + 600_000,
+          accessTokenIssuedAt: Date.now(),
+          refreshToken: "refresh-token",
+        },
+        trigger: "update",
+        session: { forceRefresh: true },
+      });
+
+      expect(result.accessToken).toBe("fresh-access-token");
+      expect(result.refreshToken).toBe("rotated-refresh-token");
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://keycloak.example/realms/tjwater/protocol/openid-connect/token",
+        expect.objectContaining({ method: "POST" }),
+      );
+    } finally {
+      if (originalFetch) globalThis.fetch = originalFetch;
+      else delete (globalThis as { fetch?: typeof fetch }).fetch;
+      restoreEnv("KEYCLOAK_ISSUER", previousEnv.issuer);
+      restoreEnv("KEYCLOAK_CLIENT_ID", previousEnv.clientId);
+      restoreEnv("KEYCLOAK_CLIENT_SECRET", previousEnv.clientSecret);
+    }
+  });
+
+  it.each([
+    ["network failure", () => Promise.reject(new Error("connection refused"))],
+    [
+      "non-JSON response",
+      () =>
+        Promise.resolve({
+          ok: false,
+          json: async () => {
+            throw new SyntaxError("Unexpected token");
+          },
+        }),
+    ],
+    [
+      "invalid token payload",
+      () =>
+        Promise.resolve({
+          ok: true,
+          json: async () => ({ access_token: "   ", expires_in: 0 }),
+        }),
+    ],
+  ])("returns a session error for %s", async (_label, fetchResult) => {
+    const previousEnv = {
+      issuer: process.env.KEYCLOAK_ISSUER,
+      clientId: process.env.KEYCLOAK_CLIENT_ID,
+      clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
+    };
+    process.env.KEYCLOAK_ISSUER = "https://keycloak.example/realms/tjwater";
+    process.env.KEYCLOAK_CLIENT_ID = "frontend";
+    process.env.KEYCLOAK_CLIENT_SECRET = "secret";
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = jest.fn(fetchResult) as unknown as typeof fetch;
+
+    try {
+      const jwt = authOptions.callbacks?.jwt as (input: unknown) => Promise<{
+        error?: string;
+      }>;
+      await expect(
+        jwt({
+          token: { refreshToken: "refresh-token" },
+          trigger: "update",
+          session: { forceRefresh: true },
+        }),
+      ).resolves.toMatchObject({ error: "RefreshAccessTokenError" });
+    } finally {
+      if (originalFetch) globalThis.fetch = originalFetch;
+      else delete (globalThis as { fetch?: typeof fetch }).fetch;
+      restoreEnv("KEYCLOAK_ISSUER", previousEnv.issuer);
+      restoreEnv("KEYCLOAK_CLIENT_ID", previousEnv.clientId);
+      restoreEnv("KEYCLOAK_CLIENT_SECRET", previousEnv.clientSecret);
+    }
+  });
+});
+
+const restoreEnv = (key: string, value: string | undefined) => {
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+};

src/app/api/auth/[...nextauth]/options.ts

@@ -3,22 +3,35 @@ import { JWT } from "next-auth/jwt";
 import KeycloakProvider from "next-auth/providers/keycloak";
 import Avatar from "@assets/avatar/avatar-small.jpeg";
 
+const SESSION_MAX_AGE_SECONDS = 12 * 60 * 60;
+const ACCESS_TOKEN_REFRESH_SKEW_MS = 30_000;
+
 type KeycloakTokenResponse = {
   access_token: string;
   expires_in: number;
   refresh_token?: string;
 };
 
-const keycloakIssuer = process.env.KEYCLOAK_ISSUER!;
-const keycloakClientId = process.env.KEYCLOAK_CLIENT_ID!;
-const keycloakClientSecret = process.env.KEYCLOAK_CLIENT_SECRET!;
-const keycloakTokenEndpoint = `${keycloakIssuer.replace(/\/$/, "")}/protocol/openid-connect/token`;
+const getKeycloakTokenEndpoint = () => {
+  const issuer = process.env.KEYCLOAK_ISSUER;
+  return issuer
+    ? `${issuer.replace(/\/$/, "")}/protocol/openid-connect/token`
+    : undefined;
+};
 
 const refreshAccessToken = async (token: JWT): Promise<JWT> => {
   if (!token.refreshToken) {
     return { ...token, error: "RefreshAccessTokenError" };
   }
 
+  const keycloakClientId = process.env.KEYCLOAK_CLIENT_ID;
+  const keycloakClientSecret = process.env.KEYCLOAK_CLIENT_SECRET;
+  const keycloakTokenEndpoint = getKeycloakTokenEndpoint();
+
+  if (!keycloakClientId || !keycloakClientSecret || !keycloakTokenEndpoint) {
+    return { ...token, error: "RefreshAccessTokenError" };
+  }
+
   const body = new URLSearchParams({
     grant_type: "refresh_token",
     client_id: keycloakClientId,
@@ -26,36 +39,56 @@ const refreshAccessToken = async (token: JWT): Promise<JWT> => {
     refresh_token: token.refreshToken,
   });
 
-  const response = await fetch(keycloakTokenEndpoint, {
-    method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body,
-  });
-  const refreshed = (await response.json()) as KeycloakTokenResponse;
+  try {
+    const response = await fetch(keycloakTokenEndpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body,
+    });
+    const refreshed = (await response.json()) as Partial<KeycloakTokenResponse> | null;
 
-  if (!response.ok || !refreshed.access_token || typeof refreshed.expires_in !== "number") {
+    if (
+      !response.ok ||
+      !refreshed ||
+      typeof refreshed.access_token !== "string" ||
+      !refreshed.access_token.trim() ||
+      typeof refreshed.expires_in !== "number" ||
+      !Number.isFinite(refreshed.expires_in) ||
+      refreshed.expires_in <= 0
+    ) {
+      return { ...token, error: "RefreshAccessTokenError" };
+    }
+
+    const rotatedRefreshToken =
+      typeof refreshed.refresh_token === "string" &&
+      refreshed.refresh_token.trim()
+        ? refreshed.refresh_token.trim()
+        : token.refreshToken;
+
+    return {
+      ...token,
+      accessToken: refreshed.access_token.trim(),
+      accessTokenIssuedAt: Date.now(),
+      accessTokenExpires: Date.now() + refreshed.expires_in * 1000,
+      refreshToken: rotatedRefreshToken,
+      error: undefined,
+    };
+  } catch {
     return { ...token, error: "RefreshAccessTokenError" };
   }
-
-  return {
-    ...token,
-    accessToken: refreshed.access_token,
-    accessTokenExpires: Date.now() + refreshed.expires_in * 1000,
-    refreshToken: refreshed.refresh_token ?? token.refreshToken,
-    error: undefined,
-  };
 };
 
 const authOptions: NextAuthOptions = {
   // Configure one or more authentication providers
   providers: [
     KeycloakProvider({
-      clientId: keycloakClientId,
-      clientSecret: keycloakClientSecret,
-      issuer: keycloakIssuer,
+      clientId: process.env.KEYCLOAK_CLIENT_ID ?? "",
+      clientSecret: process.env.KEYCLOAK_CLIENT_SECRET ?? "",
+      issuer: process.env.KEYCLOAK_ISSUER ?? "",
       profile(profile) {
         return {
           id: profile.sub,
+          username: profile.preferred_username,
           name: profile.name ?? profile.preferred_username,
           email: profile.email,
           image: Avatar.src,
@@ -65,18 +98,29 @@ const authOptions: NextAuthOptions = {
   ],
   secret: process.env.NEXTAUTH_SECRET,
   callbacks: {
-    jwt: async ({ token, profile, account }) => {
+    jwt: async ({ token, profile, account, trigger, session }) => {
       if (profile?.sub) {
         token.sub = profile.sub;
       }
+      const preferredUsername = (
+        profile as { preferred_username?: unknown } | undefined
+      )?.preferred_username;
+      if (typeof preferredUsername === "string") {
+        token.username = preferredUsername;
+      }
 
       if (account) {
+        token.sessionExpiresAt = Date.now() + SESSION_MAX_AGE_SECONDS * 1000;
         if (account.access_token) {
           token.accessToken = account.access_token;
+          token.accessTokenIssuedAt = Date.now();
         }
         if (account.refresh_token) {
           token.refreshToken = account.refresh_token;
         }
+        if (account.id_token) {
+          token.idToken = account.id_token;
+        }
         if (typeof account.expires_at === "number") {
           token.accessTokenExpires = account.expires_at * 1000;
         }
@@ -84,7 +128,26 @@ const authOptions: NextAuthOptions = {
         return token;
       }
 
-      if (typeof token.accessTokenExpires === "number" && Date.now() < token.accessTokenExpires - 30_000) {
+      if (
+        typeof token.sessionExpiresAt === "number" &&
+        Date.now() >= token.sessionExpiresAt
+      ) {
+        return { ...token, error: "SessionExpired" };
+      }
+
+      if (
+        trigger === "update" &&
+        (session as { forceRefresh?: unknown } | undefined)?.forceRefresh === true
+      ) {
+        return refreshAccessToken(token);
+      }
+
+      const accessTokenIsFresh =
+        typeof token.accessTokenExpires === "number" &&
+        typeof token.accessTokenIssuedAt === "number" &&
+        Date.now() < token.accessTokenExpires - ACCESS_TOKEN_REFRESH_SKEW_MS;
+
+      if (accessTokenIsFresh) {
         return token;
       }
 
@@ -94,15 +157,28 @@ const authOptions: NextAuthOptions = {
       if (session.user && token.sub) {
         session.user.id = token.sub;
       }
+      if (session.user && token.username) {
+        session.user.username = token.username;
+      }
       if (token.accessToken) {
         session.accessToken = token.accessToken;
       }
       if (token.error) {
         session.error = token.error;
       }
+      if (typeof token.sessionExpiresAt === "number") {
+        session.sessionExpiresAt = token.sessionExpiresAt;
+      }
       return session;
     },
   },
+  session: {
+    strategy: "jwt",
+    maxAge: SESSION_MAX_AGE_SECONDS,
+  },
+  jwt: {
+    maxAge: SESSION_MAX_AGE_SECONDS,
+  },
 };
 
 export default authOptions;

src/app/api/auth/keycloak-logout/route.test.ts

@@ -0,0 +1,97 @@
+/**
+ * @jest-environment node
+ */
+
+import { NextRequest } from "next/server";
+import { getToken } from "next-auth/jwt";
+
+import { GET } from "./route";
+
+jest.mock("next-auth/jwt", () => ({
+  getToken: jest.fn(),
+}));
+
+const getTokenMock = getToken as jest.MockedFunction<typeof getToken>;
+
+describe("GET /api/auth/keycloak-logout", () => {
+  const originalIssuer = process.env.KEYCLOAK_ISSUER;
+  const originalClientId = process.env.KEYCLOAK_CLIENT_ID;
+  const originalNextAuthUrl = process.env.NEXTAUTH_URL;
+  const originalPostLogoutRedirectUri =
+    process.env.KEYCLOAK_POST_LOGOUT_REDIRECT_URI;
+
+  beforeEach(() => {
+    process.env.KEYCLOAK_ISSUER = "https://keycloak.example.com/realms/tjwater";
+    process.env.KEYCLOAK_CLIENT_ID = "tjwater";
+    process.env.NEXTAUTH_URL = "https://frontend.example.com";
+    delete process.env.KEYCLOAK_POST_LOGOUT_REDIRECT_URI;
+    getTokenMock.mockReset();
+  });
+
+  afterAll(() => {
+    process.env.KEYCLOAK_ISSUER = originalIssuer;
+    process.env.KEYCLOAK_CLIENT_ID = originalClientId;
+    process.env.NEXTAUTH_URL = originalNextAuthUrl;
+    if (originalPostLogoutRedirectUri) {
+      process.env.KEYCLOAK_POST_LOGOUT_REDIRECT_URI = originalPostLogoutRedirectUri;
+    } else {
+      delete process.env.KEYCLOAK_POST_LOGOUT_REDIRECT_URI;
+    }
+  });
+
+  it("clears the local session and redirects the browser to Keycloak logout", async () => {
+    getTokenMock.mockResolvedValue({
+      idToken: "header.payload.signature",
+    });
+    const request = new NextRequest(
+      "https://frontend.example.com/api/auth/keycloak-logout",
+      {
+        headers: {
+          cookie:
+            "__Secure-next-auth.session-token.0=first; __Secure-next-auth.session-token.1=second; next-auth.session-token=local",
+        },
+      },
+    );
+
+    const response = await GET(request);
+    const logoutUrl = new URL(response.headers.get("location") ?? "");
+
+    expect(logoutUrl.origin).toBe("https://keycloak.example.com");
+    expect(logoutUrl.pathname).toBe(
+      "/realms/tjwater/protocol/openid-connect/logout",
+    );
+    expect(logoutUrl.searchParams.get("id_token_hint")).toBe(
+      "header.payload.signature",
+    );
+    expect(logoutUrl.searchParams.get("client_id")).toBe("tjwater");
+    expect(logoutUrl.searchParams.get("post_logout_redirect_uri")).toBeNull();
+    expect(
+      response.cookies.get("__Secure-next-auth.session-token.0"),
+    ).toMatchObject({ value: "", path: "/", secure: true });
+    expect(
+      response.cookies.get("__Secure-next-auth.session-token.1"),
+    ).toMatchObject({ value: "", path: "/", secure: true });
+    expect(response.cookies.get("next-auth.session-token")).toMatchObject({
+      value: "",
+      path: "/",
+    });
+    expect(
+      response.cookies.get("next-auth.session-token")?.secure,
+    ).toBeFalsy();
+  });
+
+  it("ignores a legacy automatic post-logout redirect setting", async () => {
+    process.env.KEYCLOAK_POST_LOGOUT_REDIRECT_URI =
+      "https://frontend.example.com/login";
+    getTokenMock.mockResolvedValue({ idToken: "header.payload.signature" });
+
+    const response = await GET(
+      new NextRequest(
+        "https://frontend.example.com/api/auth/keycloak-logout",
+      ),
+    );
+    const logoutUrl = new URL(response.headers.get("location") ?? "");
+
+    expect(logoutUrl.searchParams.get("post_logout_redirect_uri")).toBeNull();
+  });
+});

src/app/api/auth/keycloak-logout/route.ts

@@ -0,0 +1,48 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getToken } from "next-auth/jwt";
+
+type KeycloakToken = {
+  idToken?: string;
+};
+
+const sessionCookiePrefixes = [
+  "next-auth.session-token",
+  "__Secure-next-auth.session-token",
+];
+
+const isSessionCookie = (name: string) =>
+  sessionCookiePrefixes.some((prefix) => name.startsWith(prefix));
+
+export const GET = async (request: NextRequest) => {
+  const localLoginUrl = new URL(
+    "/login",
+    process.env.NEXTAUTH_URL ?? request.nextUrl.origin,
+  );
+  const issuer = process.env.KEYCLOAK_ISSUER?.replace(/\/$/, "");
+  const clientId = process.env.KEYCLOAK_CLIENT_ID;
+  const token = (await getToken({
+    req: request,
+    secret: process.env.NEXTAUTH_SECRET,
+  })) as KeycloakToken | null;
+  const logoutUrl = issuer
+    ? new URL(`${issuer}/protocol/openid-connect/logout`)
+    : localLoginUrl;
+
+  if (issuer) {
+    if (clientId) logoutUrl.searchParams.set("client_id", clientId);
+    if (token?.idToken) logoutUrl.searchParams.set("id_token_hint", token.idToken);
+  }
+
+  const response = NextResponse.redirect(logoutUrl);
+  for (const { name } of request.cookies.getAll()) {
+    if (isSessionCookie(name)) {
+      response.cookies.delete({
+        name,
+        path: "/",
+        secure: name.startsWith("__Secure-"),
+      });
+    }
+  }
+
+  return response;
+};

src/app/api/tts/edge/route.test.ts

@@ -0,0 +1,50 @@
+/**
+ * @jest-environment node
+ */
+
+import { POST } from "./route";
+
+const streamMock = jest.fn();
+
+jest.mock("edge-tts-ts", () => ({
+  Communicate: jest.fn().mockImplementation(() => ({
+    stream: streamMock,
+  })),
+}));
+
+describe("POST /api/tts/edge", () => {
+  beforeEach(() => {
+    streamMock.mockReset();
+  });
+
+  it("returns synthesized mp3 audio", async () => {
+    streamMock.mockImplementation(async function* () {
+      yield { type: "audio", data: new Uint8Array([1, 2]) };
+      yield { type: "SentenceBoundary", offset: 0, duration: 1, text: "测试" };
+      yield { type: "audio", data: new Uint8Array([3]) };
+    });
+
+    const response = await POST(
+      new Request("http://localhost/api/tts/edge", {
+        method: "POST",
+        body: JSON.stringify({ text: "测试文本" }),
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("Content-Type")).toBe("audio/mpeg");
+    expect(Array.from(new Uint8Array(await response.arrayBuffer()))).toEqual([1, 2, 3]);
+  });
+
+  it("rejects empty text", async () => {
+    const response = await POST(
+      new Request("http://localhost/api/tts/edge", {
+        method: "POST",
+        body: JSON.stringify({ text: " " }),
+      }),
+    );
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({ error: "text is required" });
+  });
+});

src/app/api/tts/edge/route.ts

@@ -0,0 +1,76 @@
+import { NextResponse } from "next/server";
+import { Communicate } from "edge-tts-ts";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const DEFAULT_VOICE = process.env.EDGE_TTS_VOICE || "zh-CN-XiaoxiaoNeural";
+const MAX_TEXT_LENGTH = 12000;
+
+type EdgeTtsRequest = {
+  text?: unknown;
+  voice?: unknown;
+};
+
+const jsonError = (message: string, status: number) =>
+  NextResponse.json({ error: message }, { status });
+
+export async function POST(request: Request) {
+  let payload: EdgeTtsRequest;
+  try {
+    payload = (await request.json()) as EdgeTtsRequest;
+  } catch {
+    return jsonError("Invalid JSON body", 400);
+  }
+
+  const text = typeof payload.text === "string" ? payload.text.trim() : "";
+  if (!text) {
+    return jsonError("text is required", 400);
+  }
+  if (text.length > MAX_TEXT_LENGTH) {
+    return jsonError(`text must be ${MAX_TEXT_LENGTH} characters or fewer`, 413);
+  }
+
+  const voice =
+    typeof payload.voice === "string" && payload.voice.trim()
+      ? payload.voice.trim()
+      : DEFAULT_VOICE;
+
+  try {
+    const communicate = new Communicate(text, { voice });
+    const chunks: Uint8Array[] = [];
+    let byteLength = 0;
+
+    for await (const chunk of communicate.stream()) {
+      if (chunk.type !== "audio") continue;
+      chunks.push(chunk.data);
+      byteLength += chunk.data.byteLength;
+    }
+
+    if (byteLength === 0) {
+      return jsonError("Edge TTS returned empty audio", 502);
+    }
+
+    const audio = new Uint8Array(byteLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      audio.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+
+    const audioBuffer = audio.buffer.slice(
+      audio.byteOffset,
+      audio.byteOffset + audio.byteLength,
+    );
+
+    return new Response(audioBuffer, {
+      headers: {
+        "Content-Type": "audio/mpeg",
+        "Cache-Control": "no-store",
+      },
+    });
+  } catch (error) {
+    console.error("[EdgeTTS] Failed to synthesize speech:", error);
+    return jsonError("Failed to synthesize speech", 502);
+  }
+}

src/app/layout.tsx

@@ -1,7 +1,8 @@
 import type { Metadata } from "next";
 import { cookies } from "next/headers";
+import Script from "next/script";
 import React, { Suspense } from "react";
-import { RefineContext } from "./_refine_context";
+import { RefineContext } from "./RefineContext";
 import { META_DATA } from "@config/config";
 
 export const metadata: Metadata = META_DATA;
@@ -16,8 +17,9 @@ export default async function RootLayout({
   const defaultMode = theme?.value === "dark" ? "dark" : "light";
 
   return (
-    <html lang="en">
+    <html lang="zh-CN">
       <body>
+        <Script src="/runtime-config.js" strategy="beforeInteractive" />
         <Suspense>
           <RefineContext defaultMode={defaultMode}>{children}</RefineContext>
         </Suspense>

src/app/login/page.test.tsx

@@ -0,0 +1,45 @@
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import Login from "./page";
+
+const mockLogin = jest.fn();
+
+jest.mock("@refinedev/core", () => ({
+  useLogin: () => ({ mutate: mockLogin }),
+}));
+
+describe("Login", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    mockLogin.mockClear();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("starts Keycloak login once when the page opens", () => {
+    const { rerender } = render(<Login />);
+
+    expect(mockLogin).toHaveBeenCalledTimes(1);
+    expect(mockLogin).toHaveBeenCalledWith({});
+    expect(screen.getByText("正在进入账号登录")).toBeInTheDocument();
+
+    rerender(<Login />);
+    expect(mockLogin).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows a manual fallback when automatic redirect does not complete", () => {
+    render(<Login />);
+
+    expect(
+      screen.queryByRole("button", { name: "继续登录" }),
+    ).not.toBeInTheDocument();
+
+    act(() => {
+      jest.advanceTimersByTime(4000);
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "继续登录" }));
+    expect(mockLogin).toHaveBeenCalledTimes(2);
+  });
+});

src/app/login/page.tsx

@@ -1,54 +1,259 @@
 "use client";
 
-import Image from "next/image";
 import Box from "@mui/material/Box";
 import Button from "@mui/material/Button";
-import Container from "@mui/material/Container";
+import CircularProgress from "@mui/material/CircularProgress";
+import Stack from "@mui/material/Stack";
 import Typography from "@mui/material/Typography";
 import { useLogin } from "@refinedev/core";
-import { Title } from "@components/title";
+import { PROJECT_TITLE } from "@config/config";
+import { useEffect, useRef, useState } from "react";
+
+const FALLBACK_DELAY_MS = 4000;
 
 export default function Login() {
   const { mutate: login } = useLogin();
+  const loginStartedRef = useRef(false);
+  const [showFallback, setShowFallback] = useState(false);
+
+  useEffect(() => {
+    if (!loginStartedRef.current) {
+      loginStartedRef.current = true;
+      login({});
+    }
+
+    const fallbackTimer = window.setTimeout(
+      () => setShowFallback(true),
+      FALLBACK_DELAY_MS,
+    );
+
+    return () => window.clearTimeout(fallbackTimer);
+  }, [login]);
 
   return (
-    <Container
-      style={{
-        height: "100vh",
-        display: "flex",
-        justifyContent: "center",
-        alignItems: "center",
+    <Box
+      component="main"
+      sx={{
+        minHeight: "100vh",
+        "@supports (height: 100svh)": {
+          minHeight: "100svh",
+        },
+        color: "oklch(0.3 0.055 215)",
+        bgcolor: "oklch(0.965 0.014 205)",
+        backgroundImage: `
+          linear-gradient(
+            90deg,
+            transparent 0%,
+            transparent 50%,
+            oklch(0.975 0.01 205 / 62%) 68%,
+            oklch(0.975 0.01 205 / 82%) 100%
+          ),
+          url("/login-network-blueprint.svg")
+        `,
+        backgroundPosition: "center",
+        backgroundRepeat: "no-repeat",
+        backgroundSize: "cover",
+        "@keyframes tjwaterEnter": {
+          from: { opacity: 0, transform: "translateY(12px)" },
+          to: { opacity: 1, transform: "translateY(0)" },
+        },
       }}
     >
       <Box
-        display="flex"
-        gap="36px"
-        justifyContent="center"
-        flexDirection="column"
+        sx={{
+          width: "100%",
+          maxWidth: 1720,
+          minHeight: "100vh",
+          "@supports (height: 100svh)": {
+            minHeight: "100svh",
+          },
+          mx: "auto",
+          px: {
+            xs: 1.75,
+            sm: 3,
+            md: "clamp(40px, 5vw, 88px)",
+          },
+          py: {
+            xs: "max(28px, env(safe-area-inset-top))",
+            md: "clamp(32px, 4.5vw, 76px)",
+          },
+          display: "grid",
+          gridTemplateColumns: {
+            xs: "minmax(0, 1fr)",
+            md: "minmax(360px, 1fr) minmax(400px, 460px)",
+          },
+          gridTemplateAreas: {
+            xs: '"brand" "status"',
+            md: '"brand status"',
+          },
+          alignContent: { xs: "center", md: "stretch" },
+          alignItems: "center",
+          gap: { xs: 2.25, md: "clamp(64px, 8vw, 152px)" },
+        }}
       >
-        <Box display="flex" justifyContent="center">
-          <Title collapsed={false} />
-        </Box>
-        <Button
-          style={{ width: "240px" }}
-          size="large"
-          variant="contained"
-          onClick={() => login({})}
+        <Stack
+          spacing={{ xs: 0, md: 3 }}
+          direction={{ xs: "row", md: "column" }}
+          alignItems={{ xs: "center", md: "flex-start" }}
+          sx={{
+            position: "relative",
+            isolation: "isolate",
+            gridArea: "brand",
+            width: "fit-content",
+            maxWidth: "100%",
+            animation:
+              "tjwaterEnter 480ms cubic-bezier(0.16, 1, 0.3, 1) both",
+            "&::before": {
+              position: "absolute",
+              zIndex: -1,
+              inset: { xs: "-24px -20px", md: "-54px -72px" },
+              background: {
+                xs: `radial-gradient(
+                  ellipse at center,
+                  oklch(0.965 0.014 205 / 98%) 0%,
+                  oklch(0.965 0.014 205 / 88%) 58%,
+                  transparent 84%
+                )`,
+                md: `radial-gradient(
+                  ellipse at center,
+                  oklch(0.925 0.018 205 / 98%) 0%,
+                  oklch(0.925 0.018 205 / 94%) 48%,
+                  oklch(0.925 0.018 205 / 62%) 65%,
+                  transparent 82%
+                )`,
+              },
+              pointerEvents: "none",
+              content: '""',
+            },
+          }}
         >
-          Sign in
-        </Button>
-        <Typography align="center" color={"text.secondary"} fontSize="12px">
-          Powered by
-          <Image
-            style={{ padding: "0 5px" }}
-            alt="Keycloak"
-            src="https://refine.ams3.cdn.digitaloceanspaces.com/superplate-auth-icons%2Fkeycloak.svg"
-            width={18}
-            height={18}
+          <Box
+            component="img"
+            src="/login-logo-mark.svg"
+            alt=""
+            width={56}
+            height={56}
+            sx={{
+              width: { xs: 42, md: 56 },
+              height: { xs: 42, md: 56 },
+              flex: { xs: "0 0 42px", md: "0 0 auto" },
+              mr: { xs: 1.5, md: 0 },
+            }}
           />
-          Keycloak
-        </Typography>
+          <Typography
+            component="h1"
+            sx={{
+              maxWidth: 680,
+              m: 0,
+              fontSize: { xs: 21, sm: 28, md: "clamp(34px, 3vw, 46px)" },
+              fontWeight: 720,
+              lineHeight: { xs: 1.4, md: 1.28 },
+              textWrap: "balance",
+            }}
+          >
+            {PROJECT_TITLE}
+          </Typography>
+          <Box
+            aria-hidden="true"
+            sx={{
+              display: { xs: "none", md: "block" },
+              width: 64,
+              height: 3,
+              borderRadius: 999,
+              bgcolor: "oklch(0.58 0.12 180)",
+            }}
+          />
+        </Stack>
+
+        <Box
+          aria-live="polite"
+          sx={{
+            gridArea: "status",
+            width: "100%",
+            maxWidth: 460,
+            justifySelf: "stretch",
+            p: { xs: 2.75, sm: 4.5 },
+            overflow: "hidden",
+            borderRadius: { xs: 4, sm: 4.5 },
+            bgcolor: "oklch(0.995 0.004 205 / 97%)",
+            boxShadow:
+              "0 32px 80px rgb(22 65 75 / 16%), 0 5px 18px rgb(22 65 75 / 9%)",
+            animation:
+              "tjwaterEnter 520ms 70ms cubic-bezier(0.16, 1, 0.3, 1) both",
+          }}
+        >
+          <Stack spacing={3}>
+            <Stack direction="row" spacing={2} alignItems="center">
+              <CircularProgress
+                size={30}
+                thickness={4.5}
+                aria-label="正在连接统一身份认证"
+                sx={{
+                  flex: "0 0 auto",
+                  color: "oklch(0.57 0.16 242)",
+                  "@media (prefers-reduced-motion: reduce)": {
+                    animation: "none",
+                    "& .MuiCircularProgress-circle": {
+                      animation: "none",
+                    },
+                  },
+                }}
+              />
+              <Stack spacing={0.5}>
+                <Typography
+                  component="h2"
+                  sx={{ fontSize: { xs: 22, sm: 26 }, fontWeight: 720 }}
+                >
+                  正在进入账号登录
+                </Typography>
+                <Typography
+                  sx={{
+                    color: "oklch(0.52 0.035 215)",
+                    fontSize: { xs: 14, sm: 15 },
+                    lineHeight: 1.7,
+                  }}
+                >
+                  正在连接统一身份认证服务，请稍候。
+                </Typography>
+              </Stack>
+            </Stack>
+
+            {showFallback ? (
+              <Button
+                fullWidth
+                size="large"
+                variant="contained"
+                onClick={() => login({})}
+                sx={{
+                  minHeight: 48,
+                  borderRadius: 3,
+                  fontSize: 16,
+                  fontWeight: 700,
+                  textTransform: "none",
+                  boxShadow:
+                    "0 8px 18px oklch(0.48 0.15 242 / 20%)",
+                  transitionProperty:
+                    "transform, background-color, box-shadow",
+                  "&:active": { transform: "scale(0.96)" },
+                }}
+              >
+                继续登录
+              </Button>
+            ) : null}
+
+            <Typography
+              sx={{
+                color: "oklch(0.52 0.035 215)",
+                fontSize: { xs: 12, sm: 13 },
+                lineHeight: 1.7,
+                textAlign: "center",
+              }}
+            >
+              账号与访问权限由统一身份认证服务管理
+            </Typography>
+          </Stack>
+        </Box>
       </Box>
-    </Container>
+    </Box>
   );
 }

src/components/auth/RoutePermissionGuard.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import LockOutlinedIcon from "@mui/icons-material/LockOutlined";
+import { Alert, Box, CircularProgress, Stack, Typography } from "@mui/material";
+import { usePathname } from "next/navigation";
+import type { ReactNode } from "react";
+
+import { permissionForPath } from "@/lib/permissions";
+import { useAccessStore } from "@/store/accessStore";
+
+export const RoutePermissionGuard = ({
+  children,
+}: {
+  children: ReactNode;
+}) => {
+  const pathname = usePathname();
+  const permissions = useAccessStore((state) => state.permissions);
+  const loading = useAccessStore((state) => state.loading);
+  const requiredPermission = permissionForPath(pathname);
+
+  if (requiredPermission && loading) {
+    return (
+      <Box sx={{ minHeight: 320, display: "grid", placeItems: "center" }}>
+        <CircularProgress size={28} />
+      </Box>
+    );
+  }
+
+  if (requiredPermission && !permissions.includes(requiredPermission)) {
+    return (
+      <Box sx={{ p: { xs: 2, md: 4 } }}>
+        <Alert severity="error" icon={<LockOutlinedIcon />}>
+          <Stack spacing={0.5}>
+            <Typography fontWeight={700}>无权访问此功能</Typography>
+            <Typography variant="body2">
+              当前项目角色缺少权限：{requiredPermission}
+            </Typography>
+          </Stack>
+        </Alert>
+      </Box>
+    );
+  }
+
+  return children;
+};

src/components/auth/SessionExpiryDialog.test.tsx

@@ -0,0 +1,39 @@
+import { createTheme, ThemeProvider } from "@mui/material/styles";
+import { act, render, screen } from "@testing-library/react";
+
+import { useAuthStore } from "@/store/authStore";
+import { SessionExpiryDialog } from "./SessionExpiryDialog";
+
+jest.mock("next-auth/react", () => ({
+  signIn: jest.fn(),
+}));
+
+describe("SessionExpiryDialog", () => {
+  beforeEach(() => {
+    useAuthStore.setState({
+      accessToken: null,
+      sessionExpired: true,
+      sessionExpiryReason: "unauthorized",
+    });
+  });
+
+  afterEach(() => {
+    act(() => useAuthStore.getState().clearSessionExpired());
+  });
+
+  it("renders above every regular application overlay", () => {
+    const theme = createTheme();
+
+    render(
+      <ThemeProvider theme={theme}>
+        <SessionExpiryDialog />
+      </ThemeProvider>,
+    );
+
+    const dialogRoot = screen.getByRole("dialog").closest(".MuiModal-root");
+    expect(dialogRoot).not.toBeNull();
+    expect(dialogRoot).toHaveStyle({
+      zIndex: theme.zIndex.tooltip + 1,
+    });
+  });
+});

src/components/auth/SessionExpiryDialog.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { signIn } from "next-auth/react";
+import AccessTimeOutlinedIcon from "@mui/icons-material/AccessTimeOutlined";
+import {
+  Alert,
+  Button,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogTitle,
+  Stack,
+  Typography,
+} from "@mui/material";
+import { useTheme } from "@mui/material/styles";
+
+import { useAuthStore } from "@/store/authStore";
+
+const WARNING_WINDOW_MS = 15 * 60 * 1000;
+
+type SessionExpiryDialogProps = {
+  expiresAt?: number;
+};
+
+export const SessionExpiryDialog = ({
+  expiresAt,
+}: SessionExpiryDialogProps) => {
+  const theme = useTheme();
+  const sessionExpired = useAuthStore((state) => state.sessionExpired);
+  const reason = useAuthStore((state) => state.sessionExpiryReason);
+  const [now, setNow] = useState(() => Date.now());
+  const [warningDismissed, setWarningDismissed] = useState(false);
+
+  useEffect(() => {
+    const timer = window.setInterval(() => setNow(Date.now()), 30_000);
+    return () => window.clearInterval(timer);
+  }, []);
+
+  const isExpiringSoon = useMemo(
+    () =>
+      !sessionExpired &&
+      !warningDismissed &&
+      typeof expiresAt === "number" &&
+      expiresAt > now &&
+      expiresAt - now <= WARNING_WINDOW_MS,
+    [expiresAt, now, sessionExpired, warningDismissed],
+  );
+
+  const handleReauthenticate = () => {
+    const callbackUrl = `${window.location.pathname}${window.location.search}`;
+    void signIn("keycloak", { callbackUrl, redirect: true });
+  };
+
+  const isOpen = sessionExpired || isExpiringSoon;
+  const title = sessionExpired ? "登录已过期" : "登录即将到期";
+  const detail = sessionExpired
+    ? reason === "session_max_age"
+      ? "已达到 12 小时的最长连续登录时间。请重新认证后继续。"
+      : "无法续期当前登录。请重新认证后继续。"
+    : "当前登录将在 15 分钟内到期。请先保存正在编辑的内容。";
+
+  return (
+    <Dialog
+      open={isOpen}
+      style={{ zIndex: theme.zIndex.tooltip + 1 }}
+      disableEscapeKeyDown={sessionExpired}
+      onClose={sessionExpired ? undefined : () => setWarningDismissed(true)}
+      aria-labelledby="session-expiry-dialog-title"
+    >
+      <DialogTitle id="session-expiry-dialog-title">{title}</DialogTitle>
+      <DialogContent>
+        <Stack spacing={2} sx={{ pt: 0.5 }}>
+          <Alert icon={<AccessTimeOutlinedIcon />} severity={sessionExpired ? "warning" : "info"}>
+            {detail}
+          </Alert>
+          <Typography variant="body2" color="text.secondary">
+            重新认证不会自动重放已失败的写入请求；请在返回后确认内容并再次提交。
+          </Typography>
+        </Stack>
+      </DialogContent>
+      <DialogActions>
+        {!sessionExpired && (
+          <Button onClick={() => setWarningDismissed(true)}>稍后处理</Button>
+        )}
+        <Button variant="contained" onClick={handleReauthenticate}>
+          重新认证
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+};

src/components/chat/AgentArtifactPanel.tsx

@@ -17,7 +17,6 @@ import SensorsRounded from "@mui/icons-material/SensorsRounded";
 import BuildCircleRounded from "@mui/icons-material/BuildCircleRounded";
 
 import { ChatInlineChart } from "./ChatInlineChart";
-import type { ChatChartSeries } from "./ChatInlineChart";
 import type { AgentArtifact } from "./GlobalChatbox.types";
 
 const artifactIcon = (kind: AgentArtifact["kind"]) => {
@@ -61,8 +60,13 @@ export const AgentArtifactPanel = ({ artifacts }: { artifacts: AgentArtifact[] }
               chart_type={
                 (artifact.params.chart_type as "line" | "bar" | "pie") ?? "line"
               }
-              x_data={(artifact.params.x_data as string[]) ?? []}
-              series={(artifact.params.series as ChatChartSeries[]) ?? []}
+              x_data={
+                artifact.params.x_data ??
+                artifact.params.xData ??
+                artifact.params.labels ??
+                artifact.params.categories
+              }
+              series={artifact.params.series}
               x_axis_name={(artifact.params.x_axis_name as string) ?? undefined}
               y_axis_name={(artifact.params.y_axis_name as string) ?? undefined}
             />

src/components/chat/AgentComposer.test.tsx

@@ -0,0 +1,111 @@
+/* eslint-disable @next/next/no-img-element */
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { ThemeProvider, createTheme } from "@mui/material/styles";
+
+import { AgentComposer } from "./AgentComposer";
+
+jest.mock("next/image", () => ({
+  __esModule: true,
+  default: (props: React.ImgHTMLAttributes<HTMLImageElement>) => (
+    <img {...props} alt={props.alt ?? ""} />
+  ),
+}));
+
+jest.mock("framer-motion", () => ({
+  AnimatePresence: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  motion: {
+    div: ({
+      children,
+      animate: _animate,
+      exit: _exit,
+      initial: _initial,
+      transition: _transition,
+      ...props
+    }: React.HTMLAttributes<HTMLDivElement> & Record<string, unknown>) => (
+      <div {...props}>{children}</div>
+    ),
+  },
+}));
+
+describe("AgentComposer", () => {
+  it("places voice input immediately before send without an attachment action", () => {
+    render(
+      <ThemeProvider theme={createTheme()}>
+        <AgentComposer
+          isStreaming={false}
+          isListening={false}
+          isSttSupported
+          presets={[]}
+          onSend={jest.fn()}
+          onAbort={jest.fn()}
+          onStartListening={jest.fn()}
+          onStopListening={jest.fn()}
+          modelOptions={[{ id: "test-model", label: "测试模型" }]}
+          selectedModel="test-model"
+          onModelChange={jest.fn()}
+          approvalMode="auto"
+          onApprovalModeChange={jest.fn()}
+        />
+      </ThemeProvider>,
+    );
+
+    const voiceButton = screen.getByRole("button", { name: "语音输入" });
+    const sendButton = screen.getByRole("button", { name: "发送" });
+
+    expect(screen.queryByRole("button", { name: "上传附件" })).not.toBeInTheDocument();
+    expect(screen.getByTitle("快捷指令图标")).toBeInTheDocument();
+    expect(screen.queryByAltText("TJWater Agent")).not.toBeInTheDocument();
+    expect(screen.getByText("自动批准")).toBeInTheDocument();
+    expect(voiceButton.nextElementSibling?.contains(sendButton)).toBe(true);
+  });
+
+  it("disables input while the Agent runtime is unavailable", () => {
+    render(
+      <ThemeProvider theme={createTheme()}>
+        <AgentComposer
+          isStreaming={false}
+          runtimeState="unavailable"
+          isListening={false}
+          isSttSupported={false}
+          presets={[]}
+          onSend={jest.fn()}
+          onAbort={jest.fn()}
+          onStartListening={jest.fn()}
+          onStopListening={jest.fn()}
+          modelOptions={[]}
+          onModelChange={jest.fn()}
+          approvalMode="auto"
+          onApprovalModeChange={jest.fn()}
+        />
+      </ThemeProvider>,
+    );
+
+    expect(screen.getByPlaceholderText("Agent 服务未就绪，暂时无法发送消息")).toBeDisabled();
+    expect(screen.getByRole("button", { name: "发送" })).toBeDisabled();
+  });
+
+  it("renders the always-allow mode as an explicit warning state", () => {
+    render(
+      <ThemeProvider theme={createTheme()}>
+        <AgentComposer
+          isStreaming={false}
+          isListening={false}
+          isSttSupported={false}
+          presets={[]}
+          onSend={jest.fn()}
+          onAbort={jest.fn()}
+          onStartListening={jest.fn()}
+          onStopListening={jest.fn()}
+          modelOptions={[]}
+          onModelChange={jest.fn()}
+          approvalMode="always"
+          onApprovalModeChange={jest.fn()}
+        />
+      </ThemeProvider>,
+    );
+
+    expect(screen.getByText("始终允许")).toBeInTheDocument();
+    expect(screen.getByTestId("WarningAmberRoundedIcon")).toBeInTheDocument();
+  });
+});

src/components/chat/AgentComposer.tsx

@@ -23,49 +23,133 @@ import StopRounded from "@mui/icons-material/StopRounded";
 import MicRounded from "@mui/icons-material/MicRounded";
 import KeyboardArrowDownRounded from "@mui/icons-material/KeyboardArrowDownRounded";
 import KeyboardArrowUpRounded from "@mui/icons-material/KeyboardArrowUpRounded";
-import AttachFileRounded from "@mui/icons-material/AttachFileRounded";
 import BoltRounded from "@mui/icons-material/BoltRounded";
 import AutoAwesomeRounded from "@mui/icons-material/AutoAwesomeRounded";
-import type { AgentModel } from "@/lib/chatStream";
+import VerifiedUserRounded from "@mui/icons-material/VerifiedUserRounded";
+import AdminPanelSettingsRounded from "@mui/icons-material/AdminPanelSettingsRounded";
+import WarningAmberRounded from "@mui/icons-material/WarningAmberRounded";
+import type { AgentRuntimeState } from "@/lib/agentRuntime";
+import type { AgentModelOption } from "@/lib/chatModels";
+import type { AgentApprovalMode, AgentModel } from "@/lib/chatStream";
+
+export type AgentComposerHandle = {
+  focus: () => void;
+  clear: () => void;
+  append: (text: string) => void;
+  setValue: (value: string) => void;
+  getValue: () => string;
+};
 
 type AgentComposerProps = {
-  input: string;
-  inputRef: React.RefObject<HTMLInputElement | null>;
   isHydrating?: boolean;
+  runtimeState?: AgentRuntimeState;
   isStreaming: boolean;
   isListening: boolean;
   isSttSupported: boolean;
   presets: string[];
-  onInputChange: (value: string) => void;
-  onSend: () => void;
+  onSend: (prompt: string) => void;
   onAbort: () => void;
   onStartListening: () => void;
   onStopListening: () => void;
-  onPresetSelect: (prompt: string) => void;
-  selectedModel: AgentModel;
+  modelOptions: AgentModelOption[];
+  selectedModel?: AgentModel;
   onModelChange: (model: AgentModel) => void;
+  approvalMode: AgentApprovalMode;
+  onApprovalModeChange: (mode: AgentApprovalMode) => void;
 };
 
-export const AgentComposer = ({
-  input,
-  inputRef,
+const approvalModeOptions: ReadonlyArray<{
+  value: AgentApprovalMode;
+  label: string;
+  description: string;
+  icon: React.ElementType;
+}> = [
+  {
+    value: "request",
+    label: "请求批准",
+    description: "白名单外的工具权限逐次确认",
+    icon: VerifiedUserRounded,
+  },
+  {
+    value: "auto",
+    label: "自动批准",
+    description: "低风险自动批准，其余仍需确认",
+    icon: AdminPanelSettingsRounded,
+  },
+  {
+    value: "always",
+    label: "始终允许",
+    description: "除明确禁止项外自动放行",
+    icon: WarningAmberRounded,
+  },
+];
+
+const getApprovalModeOption = (value: AgentApprovalMode) =>
+  approvalModeOptions.find((option) => option.value === value) ?? approvalModeOptions[0];
+
+const renderModelIcon = (
+  icon: AgentModelOption["icon"] | undefined,
+  props?: React.ComponentProps<typeof BoltRounded>,
+) =>
+  icon === "bolt" ? (
+    <BoltRounded {...props} />
+  ) : (
+    <AutoAwesomeRounded {...props} />
+  );
+
+export const AgentComposer = React.forwardRef<AgentComposerHandle, AgentComposerProps>(function AgentComposer({
   isHydrating = false,
+  runtimeState = "ready",
   isStreaming,
   isListening,
   isSttSupported,
   presets,
-  onInputChange,
   onSend,
   onAbort,
   onStartListening,
   onStopListening,
-  onPresetSelect,
+  modelOptions,
   selectedModel,
   onModelChange,
-}: AgentComposerProps) => {
+  approvalMode,
+  onApprovalModeChange,
+}, ref) {
   const theme = useTheme();
-  const canSend = input.trim().length > 0 && !isStreaming && !isHydrating;
+  const inputRef = React.useRef<HTMLInputElement | HTMLTextAreaElement | null>(null);
+  const [input, setInput] = React.useState("");
   const [isPresetOpen, setIsPresetOpen] = React.useState(false);
+  const isRuntimeReady = runtimeState === "ready";
+  const canSend = input.trim().length > 0 && !isStreaming && !isHydrating && isRuntimeReady;
+  const placeholder = isHydrating
+    ? "正在加载对话记录..."
+    : runtimeState === "checking"
+      ? "正在连接 Agent 服务..."
+      : runtimeState === "models_unavailable"
+        ? "模型尚未加载，暂时无法发送消息"
+        : runtimeState === "unavailable"
+          ? "Agent 服务未就绪，暂时无法发送消息"
+          : "描述你的分析目标，或点击上方指令库...";
+  const selectedModelOption = modelOptions.find((model) => model.id === selectedModel);
+  const selectedApprovalModeOption = getApprovalModeOption(approvalMode);
+
+  React.useImperativeHandle(
+    ref,
+    () => ({
+      focus: () => inputRef.current?.focus(),
+      clear: () => setInput(""),
+      append: (text: string) => setInput((prev) => prev + text),
+      setValue: (value: string) => setInput(value),
+      getValue: () => input,
+    }),
+    [input],
+  );
+
+  const handleSend = React.useCallback(() => {
+    const prompt = input.trim();
+    if (!prompt || isStreaming || isHydrating || !isRuntimeReady) return;
+    setInput("");
+    onSend(prompt);
+  }, [input, isHydrating, isRuntimeReady, isStreaming, onSend]);
 
   return (
     <Box sx={{ px: 2, pb: 2, pt: 1, zIndex: 10 }}>
@@ -84,16 +168,10 @@ export const AgentComposer = ({
         }}
         >
           <Stack direction="row" spacing={1} alignItems="center">
-          <Image
-            src="/ai-agent.svg"
-            alt="TJWater Agent"
-            width={18}
-            height={18}
-            style={{
-              objectFit: "contain",
-              flexShrink: 0,
-            }}
-          />
+            <AutoAwesomeRounded
+              titleAccess="快捷指令图标"
+              sx={{ fontSize: 18, color: "#00acc1", flexShrink: 0 }}
+            />
             <Typography variant="caption" color="text.secondary" fontWeight={800} sx={{ letterSpacing: 0.5 }}>
               管网分析快捷指令
             </Typography>
@@ -120,9 +198,13 @@ export const AgentComposer = ({
                   label={prompt.replace(/[。.]$/, "")}
                   size="medium"
                   clickable
+                  disabled={!isRuntimeReady || isHydrating || isStreaming}
                   onClick={() => {
-                    onPresetSelect(prompt);
+                    setInput(prompt);
                     setIsPresetOpen(false);
+                    window.setTimeout(() => {
+                      inputRef.current?.focus();
+                    }, 0);
                   }}
                   sx={{
                     height: 32,
@@ -165,19 +247,19 @@ export const AgentComposer = ({
           <TextField
             inputRef={inputRef}
             value={input}
-            onChange={(event) => onInputChange(event.target.value)}
+            onChange={(event) => setInput(event.target.value)}
             onKeyDown={(event) => {
               if (event.key === "Enter" && !event.shiftKey) {
                 event.preventDefault();
-                onSend();
+                handleSend();
               }
             }}
-            placeholder={isHydrating ? "正在加载对话记录..." : "描述你的分析目标，或点击上方指令库..."}
+            placeholder={placeholder}
             fullWidth
             multiline
             maxRows={5}
             variant="standard"
-            disabled={isHydrating}
+            disabled={isHydrating || !isRuntimeReady}
             InputProps={{
               disableUnderline: true,
               sx: { px: 1, py: 0.5, fontSize: "1rem", lineHeight: 1.6, fontWeight: 500, color: "text.primary" },
@@ -186,59 +268,152 @@ export const AgentComposer = ({
 
           <Stack direction="row" alignItems="center" justifyContent="space-between" sx={{ mt: 2 }}>
             <Stack direction="row" spacing={0.5} alignItems="center">
-              <IconButton size="small" aria-label="上传附件" sx={{ color: "text.secondary", width: 36, height: 36, bgcolor: alpha("#fff", 0.6) }}>
-                <AttachFileRounded fontSize="small" />
-              </IconButton>
-              {isSttSupported ? (
-                isListening ? (
-                  <motion.div
-                    animate={{ scale: [1, 1.14, 1] }}
-                    transition={{ duration: 1.5, repeat: Infinity, ease: "easeInOut" }}
-                  >
-                    <IconButton
-                      onClick={onStopListening}
-                      aria-label="停止语音输入"
-                      size="small"
-                      sx={{
-                        color: "error.main",
-                        bgcolor: alpha(theme.palette.error.main, 0.15),
-                        width: 36,
-                        height: 36,
-                      }}
-                    >
-                      <MicRounded fontSize="small" />
-                    </IconButton>
-                  </motion.div>
-                ) : (
-                  <IconButton
-                    onClick={onStartListening}
-                    disabled={isStreaming || isHydrating}
-                    aria-label="语音输入"
-                    size="small"
-                    sx={{ color: "text.secondary", width: 36, height: 36, bgcolor: alpha("#fff", 0.6) }}
-                  >
-                    <MicRounded fontSize="small" />
-                  </IconButton>
-                )
-              ) : null}
+              <FormControl size="small" sx={{ minWidth: 128 }}>
+                <Select
+                  value={approvalMode}
+                  onChange={(event) =>
+                    onApprovalModeChange(event.target.value as AgentApprovalMode)
+                  }
+                  disabled={isHydrating || isStreaming || !isRuntimeReady}
+                  aria-label="权限批准模式"
+                  renderValue={() => {
+                    const SelectedApprovalIcon = selectedApprovalModeOption.icon;
+                    return (
+                      <Box sx={{ display: "flex", alignItems: "center", gap: 0.45 }}>
+                        <SelectedApprovalIcon
+                          sx={{
+                            fontSize: 18,
+                            color:
+                              selectedApprovalModeOption.value === "always"
+                                ? "warning.main"
+                                : "inherit",
+                          }}
+                        />
+                        <Typography sx={{ fontSize: "0.75rem", fontWeight: 600, color: "inherit" }}>
+                          {selectedApprovalModeOption.label}
+                        </Typography>
+                      </Box>
+                    );
+                  }}
+                  MenuProps={{
+                    anchorOrigin: { vertical: "top", horizontal: "left" },
+                    transformOrigin: { vertical: "bottom", horizontal: "left" },
+                    sx: { zIndex: (theme) => theme.zIndex.modal + 110 },
+                    PaperProps: {
+                      sx: {
+                        mb: 1.5,
+                        width: 248,
+                        borderRadius: 4,
+                        bgcolor: alpha("#fff", 0.9),
+                        backdropFilter: "blur(24px)",
+                        border: `1px solid ${alpha("#fff", 0.9)}`,
+                        boxShadow: `0 -12px 40px ${alpha("#000", 0.08)}`,
+                        "& .MuiList-root": { p: 1 },
+                        "& .MuiMenuItem-root": {
+                          px: 1.5,
+                          py: 1.2,
+                          mb: 0.5,
+                          borderRadius: 3,
+                          alignItems: "flex-start",
+                          "&:last-child": { mb: 0 },
+                          "&.Mui-selected": {
+                            bgcolor: alpha("#00acc1", 0.08),
+                            "&:hover": { bgcolor: alpha("#00acc1", 0.12) },
+                            "& .title": { color: "#00838f" },
+                            "& .icon": { color: "#00acc1" },
+                            "& .always-icon": { color: "warning.main" },
+                          },
+                        },
+                      },
+                    },
+                  }}
+                  sx={{
+                    height: 36,
+                    borderRadius: "18px",
+                    bgcolor: alpha("#fff", 0.6),
+                    color: "text.secondary",
+                    ".MuiOutlinedInput-notchedOutline": { border: "none" },
+                    ".MuiSelect-select": {
+                      py: 0,
+                      pl: 1,
+                      pr: "28px !important",
+                      minHeight: 36,
+                      display: "flex",
+                      alignItems: "center",
+                    },
+                    "&:hover, &:has(.MuiSelect-select[aria-expanded=\"true\"])": {
+                      bgcolor: alpha("#000", 0.06),
+                      color: "text.primary",
+                    },
+                    ".MuiSelect-icon": {
+                      color: "text.secondary",
+                      right: 4,
+                    },
+                  }}
+                >
+                  {approvalModeOptions.map((option) => {
+                    const ApprovalIcon = option.icon;
+                    const isAlways = option.value === "always";
+                    return (
+                      <MenuItem key={option.value} value={option.value}>
+                        <ApprovalIcon
+                          className={isAlways ? "icon always-icon" : "icon"}
+                          sx={{
+                            mr: 1.5,
+                            mt: 0.15,
+                            fontSize: 18,
+                            color: isAlways ? "warning.main" : "text.secondary",
+                          }}
+                        />
+                        <Box>
+                          <Typography
+                            className="title"
+                            sx={{
+                              mb: 0.2,
+                              color: "text.primary",
+                              fontSize: "0.85rem",
+                              fontWeight: 700,
+                            }}
+                          >
+                            {option.label}
+                          </Typography>
+                          <Typography
+                            sx={{
+                              color: "text.secondary",
+                              fontSize: "0.7rem",
+                              fontWeight: 500,
+                              lineHeight: 1.3,
+                              whiteSpace: "nowrap",
+                            }}
+                          >
+                            {option.description}
+                          </Typography>
+                        </Box>
+                      </MenuItem>
+                    );
+                  })}
+                </Select>
+              </FormControl>
             </Stack>
 
             <Stack direction="row" spacing={1} alignItems="center">
               <FormControl size="small" sx={{ minWidth: 80 }}>
                 <Select
-                  value={selectedModel}
+                  value={selectedModel ?? ""}
                   onChange={(event) => onModelChange(event.target.value as AgentModel)}
-                  disabled={isHydrating || isStreaming}
+                  disabled={isHydrating || isStreaming || modelOptions.length === 0}
                   aria-label="模型选择"
-                  renderValue={(val) => (
-                    <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
-                      {val === "deepseek/deepseek-v4-flash" ? (
-                        <BoltRounded sx={{ fontSize: 18, color: "inherit", transition: "color 0.2s" }} />
-                      ) : (
-                        <AutoAwesomeRounded sx={{ fontSize: 16, color: "inherit", transition: "color 0.2s" }} />
-                      )}
+                  renderValue={() => (
+                    <Box sx={{ display: "flex", alignItems: "center", gap: 0.5 }}>
+                      {renderModelIcon(selectedModelOption?.icon, {
+                        sx: {
+                          fontSize: selectedModelOption?.icon === "bolt" ? 18 : 16,
+                          color: "inherit",
+                          transition: "color 0.2s",
+                        },
+                      })}
                       <Typography sx={{ fontSize: "0.8rem", fontWeight: 600, color: "inherit", transition: "color 0.2s" }}>
-                        {val === "deepseek/deepseek-v4-flash" ? "快速" : "专家"}
+                        {selectedModelOption?.label ?? "模型"}
                       </Typography>
                     </Box>
                   )}
@@ -312,33 +487,61 @@ export const AgentComposer = ({
                   }}
                 >
                   <Box sx={{ px: 2, py: 1.5, pb: 1, display: "flex", alignItems: "center", gap: 1, pointerEvents: "none" }}>
-                    <Box
-                      component="img"
-                      src="/deepseek-logo.svg"
-                      alt="DeepSeek"
-                      sx={{ width: 16, height: 16, display: "block", flexShrink: 0 }}
-                    />
+                    <AutoAwesomeRounded sx={{ width: 16, height: 16, color: "text.secondary", flexShrink: 0 }} />
                     <Typography sx={{ fontSize: "0.75rem", fontWeight: 700, color: "text.secondary", letterSpacing: 0.5 }}>
-                      DEEPSEEK V4
+                      模型选择
                     </Typography>
                   </Box>
-                  <MenuItem value="deepseek/deepseek-v4-flash">
-                    <BoltRounded className="icon" sx={{ mr: 1.5, mt: 0.2, fontSize: 20, color: "text.secondary", transition: "color 0.2s" }} />
-                    <Box>
-                      <Typography className="title" sx={{ fontSize: "0.85rem", fontWeight: 700, color: "text.primary", mb: 0.2, transition: "color 0.2s" }}>快速</Typography>
-                      <Typography sx={{ fontSize: "0.7rem", fontWeight: 500, color: "text.secondary", lineHeight: 1.3 }}>快速回答和任务执行</Typography>
-                    </Box>
-                  </MenuItem>
-                  <MenuItem value="deepseek/deepseek-v4-pro">
-                    <AutoAwesomeRounded className="icon" sx={{ mr: 1.5, mt: 0.2, fontSize: 18, color: "text.secondary", transition: "color 0.2s" }} />
-                    <Box>
-                      <Typography className="title" sx={{ fontSize: "0.85rem", fontWeight: 700, color: "text.primary", mb: 0.2, transition: "color 0.2s" }}>专家</Typography>
-                      <Typography sx={{ fontSize: "0.7rem", fontWeight: 500, color: "text.secondary", lineHeight: 1.3 }}>探索、解决复杂任务</Typography>
-                    </Box>
-                  </MenuItem>
+                  {modelOptions.map((model) => (
+                    <MenuItem key={model.id} value={model.id}>
+                      {renderModelIcon(model.icon, {
+                        className: "icon",
+                        sx: { mr: 1.5, mt: 0.2, fontSize: model.icon === "bolt" ? 20 : 18, color: "text.secondary", transition: "color 0.2s" },
+                      })}
+                      <Box>
+                        <Typography className="title" sx={{ fontSize: "0.85rem", fontWeight: 700, color: "text.primary", mb: 0.2, transition: "color 0.2s" }}>{model.label}</Typography>
+                        {model.description ? (
+                          <Typography sx={{ fontSize: "0.7rem", fontWeight: 500, color: "text.secondary", lineHeight: 1.3 }}>{model.description}</Typography>
+                        ) : null}
+                      </Box>
+                    </MenuItem>
+                  ))}
                 </Select>
               </FormControl>
 
+              {isSttSupported ? (
+                isListening ? (
+                  <motion.div
+                    animate={{ scale: [1, 1.14, 1] }}
+                    transition={{ duration: 1.5, repeat: Infinity, ease: "easeInOut" }}
+                  >
+                    <IconButton
+                      onClick={onStopListening}
+                      aria-label="停止语音输入"
+                      size="small"
+                      sx={{
+                        color: "error.main",
+                        bgcolor: alpha(theme.palette.error.main, 0.15),
+                        width: 36,
+                        height: 36,
+                      }}
+                    >
+                      <MicRounded fontSize="small" />
+                    </IconButton>
+                  </motion.div>
+                ) : (
+                  <IconButton
+                    onClick={onStartListening}
+                    disabled={isStreaming || isHydrating || !isRuntimeReady}
+                    aria-label="语音输入"
+                    size="small"
+                    sx={{ color: "text.secondary", width: 36, height: 36, bgcolor: alpha("#fff", 0.6) }}
+                  >
+                    <MicRounded fontSize="small" />
+                  </IconButton>
+                )
+              ) : null}
+
               <AnimatePresence mode="wait">
                 {isStreaming ? (
                   <motion.div key="stop" initial={{ scale: 0 }} animate={{ scale: 1 }} exit={{ scale: 0 }}>
@@ -362,7 +565,7 @@ export const AgentComposer = ({
                   <motion.div key="send" initial={{ scale: 0 }} animate={{ scale: 1 }} exit={{ scale: 0 }}>
                     <IconButton
                       disabled={!canSend}
-                      onClick={onSend}
+                      onClick={handleSend}
                       aria-label="发送"
                       size="small"
                       sx={{
@@ -397,4 +600,4 @@ export const AgentComposer = ({
       </Box>
     </Box>
   );
-};
+});

src/components/chat/AgentHeader.tsx

@@ -19,12 +19,14 @@ import CloseRounded from "@mui/icons-material/CloseRounded";
 import EditRounded from "@mui/icons-material/EditRounded";
 import EditNoteRounded from "@mui/icons-material/EditNoteRounded";
 import HistoryRounded from "@mui/icons-material/HistoryRounded";
+import type { AgentRuntimeState } from "@/lib/agentRuntime";
 
 type AgentHeaderProps = {
   sessionTitle?: string;
   canRenameSessionTitle?: boolean;
   isHydrating?: boolean;
   isStreaming: boolean;
+  runtimeState?: AgentRuntimeState;
   isHistoryOpen: boolean;
   onHistoryToggle: () => void;
   onRenameSessionTitle?: (title: string) => void;
@@ -37,6 +39,7 @@ export const AgentHeader = ({
   canRenameSessionTitle = false,
   isHydrating = false,
   isStreaming,
+  runtimeState = "ready",
   isHistoryOpen,
   onHistoryToggle,
   onRenameSessionTitle,
@@ -47,6 +50,14 @@ export const AgentHeader = ({
   const displayTitle = sessionTitle?.trim() || "新对话";
   const [isEditingTitle, setIsEditingTitle] = React.useState(false);
   const [draftTitle, setDraftTitle] = React.useState(sessionTitle?.trim() || "");
+  const runtimeStatus =
+    runtimeState === "unavailable" || runtimeState === "models_unavailable"
+      ? { color: "#e53935", label: "Agent 服务未就绪" }
+      : runtimeState === "checking"
+        ? { color: "#ffb300", label: "正在连接 Agent 服务" }
+        : isStreaming
+          ? { color: "#ff9800", label: "Agent 正在生成" }
+          : { color: "#00e676", label: "Agent 已就绪" };
 
   React.useEffect(() => {
     if (!isEditingTitle) {
@@ -109,17 +120,19 @@ export const AgentHeader = ({
               />
             </Avatar>
             <Box
+              role="status"
+              aria-label={runtimeStatus.label}
               sx={{
                 position: "absolute",
                 bottom: -2,
                 right: -2,
                 width: 14,
                 height: 14,
-                bgcolor: isStreaming ? "#ff9800" : "#00e676",
+                bgcolor: runtimeStatus.color,
                 borderRadius: "50%",
                 border: "2.5px solid #fff",
-                boxShadow: `0 0 10px ${isStreaming ? "#ff9800" : "#00e676"}`,
-                animation: isStreaming ? "pulse 1.5s infinite" : "none",
+                boxShadow: `0 0 10px ${runtimeStatus.color}`,
+                animation: isStreaming && runtimeState === "ready" ? "pulse 1.5s infinite" : "none",
                 "@keyframes pulse": {
                   "0%": { boxShadow: `0 0 0 0 ${alpha("#ff9800", 0.7)}` },
                   "70%": { boxShadow: `0 0 0 6px ${alpha("#ff9800", 0)}` },

src/components/chat/AgentHistoryPanel.test.tsx

@@ -8,6 +8,56 @@ const renderWithTheme = (ui: React.ReactElement) =>
   render(<ThemeProvider theme={createTheme()}>{ui}</ThemeProvider>);
 
 describe("AgentHistoryPanel", () => {
+  it("shows skeleton rows while history sessions are loading", () => {
+    renderWithTheme(
+      <AgentHistoryPanel
+        sessions={[]}
+        isLoadingSessions
+        onNewSession={jest.fn()}
+        onRenameSession={jest.fn()}
+        onSelectSession={jest.fn()}
+        onDeleteSession={jest.fn()}
+      />,
+    );
+
+    expect(screen.getByLabelText("正在加载历史会话")).toBeInTheDocument();
+    expect(screen.queryByText("暂无历史会话")).not.toBeInTheDocument();
+  });
+
+  it("disables the loading history session item", () => {
+    const onSelectSession = jest.fn();
+    const onRenameSession = jest.fn();
+    const onDeleteSession = jest.fn();
+
+    renderWithTheme(
+      <AgentHistoryPanel
+        sessions={[
+          {
+            id: "session-loading",
+            title: "正在加载的会话",
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+          },
+        ]}
+        loadingSessionId="session-loading"
+        onNewSession={jest.fn()}
+        onRenameSession={onRenameSession}
+        onSelectSession={onSelectSession}
+        onDeleteSession={onDeleteSession}
+      />,
+    );
+
+    expect(screen.queryByText("正在加载的会话")).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "修改会话标题" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "删除会话" })).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByLabelText("正在加载会话 正在加载的会话"));
+
+    expect(onSelectSession).not.toHaveBeenCalled();
+    expect(onRenameSession).not.toHaveBeenCalled();
+    expect(onDeleteSession).not.toHaveBeenCalled();
+  });
+
   it("renames a history session from the list", () => {
     const onRenameSession = jest.fn();
 

src/components/chat/AgentHistoryPanel.tsx

@@ -13,6 +13,7 @@ import {
   Divider,
   IconButton,
   Paper,
+  Skeleton,
   Stack,
   TextField,
   Tooltip,
@@ -34,9 +35,11 @@ type AgentHistoryPanelProps = {
   sessions: ChatSessionSummary[];
   activeSessionId?: string;
   isHydrating?: boolean;
+  isLoadingSessions?: boolean;
+  loadingSessionId?: string;
   onNewSession: () => void;
   onRenameSession: (sessionId: string, title: string) => void;
-  onSelectSession: (sessionId: string) => void;
+  onSelectSession: (sessionId: string, title: string) => void;
   onDeleteSession: (sessionId: string) => void;
 };
 
@@ -76,6 +79,8 @@ export const AgentHistoryPanel = ({
   sessions,
   activeSessionId,
   isHydrating = false,
+  isLoadingSessions = false,
+  loadingSessionId,
   onNewSession,
   onRenameSession,
   onSelectSession,
@@ -127,6 +132,30 @@ export const AgentHistoryPanel = ({
     (session) => session.id === pendingDeleteSessionId,
   );
 
+  const renderSessionListSkeleton = () => (
+    <Stack spacing={1} aria-label="正在加载历史会话">
+      {Array.from({ length: 6 }, (_, index) => (
+        <Paper
+          key={index}
+          elevation={0}
+          sx={{
+            px: 1.25,
+            py: 1,
+            borderRadius: 3,
+            bgcolor: alpha("#fff", 0.48),
+            border: `1px solid ${alpha("#fff", 0.68)}`,
+            boxShadow: `0 4px 12px ${alpha("#000", 0.025)}`,
+          }}
+        >
+          <Stack spacing={0.75} sx={{ minHeight: 46, justifyContent: "center" }}>
+            <Skeleton variant="text" width={`${72 - (index % 3) * 12}%`} height={18} />
+            <Skeleton variant="text" width="32%" height={14} />
+          </Stack>
+        </Paper>
+      ))}
+    </Stack>
+  );
+
   const handleStartRename = (sessionId: string, title: string) => {
     setEditingSessionId(sessionId);
     setDraftTitle(title);
@@ -165,9 +194,6 @@ export const AgentHistoryPanel = ({
             <Typography variant="subtitle2" fontWeight={800} color="text.primary">
               历史会话
             </Typography>
-            <Typography variant="caption" color="text.secondary">
-              本地保存于浏览器
-            </Typography>
           </Box>
           <Tooltip title="新建对话">
             <motion.div whileHover={{ scale: 1.08 }} whileTap={{ scale: 0.92 }} style={{ display: "flex" }}>
@@ -218,7 +244,9 @@ export const AgentHistoryPanel = ({
         <Divider sx={{ borderColor: alpha("#fff", 0.6) }} />
 
         <Box sx={{ flex: 1, overflowY: "auto", px: 1.25, py: 1.25 }}>
-          {sessions.length === 0 ? (
+          {isLoadingSessions ? (
+            renderSessionListSkeleton()
+          ) : sessions.length === 0 ? (
             <Stack
               alignItems="center"
               justifyContent="center"
@@ -274,27 +302,42 @@ export const AgentHistoryPanel = ({
                   <Stack spacing={1}>
                     {groupSessions.map((session) => {
                       const isActive = session.id === activeSessionId;
+                      const isLoading = session.id === loadingSessionId;
 
                       return (
                         <Paper
                           key={session.id}
                           elevation={0}
+                          aria-label={isLoading ? `正在加载会话 ${session.title}` : undefined}
                           onClick={() => {
-                            if (editingSessionId === session.id) return;
-                            onSelectSession(session.id);
+                            if (editingSessionId === session.id || isLoading) return;
+                            onSelectSession(session.id, session.title);
                           }}
                           sx={{
                             px: 1.25,
                             py: 1,
                             borderRadius: 3,
-                            cursor: isHydrating ? "default" : "pointer",
-                            bgcolor: isActive ? alpha("#00acc1", 0.12) : alpha("#fff", 0.56),
-                            border: `1px solid ${isActive ? alpha("#00acc1", 0.25) : alpha("#fff", 0.72)}`,
-                            boxShadow: isActive ? `0 8px 20px ${alpha("#00acc1", 0.12)}` : `0 4px 12px ${alpha("#000", 0.03)}`,
+                            cursor: isHydrating || isLoading ? "default" : "pointer",
+                            bgcolor:
+                              isActive || isLoading
+                                ? alpha("#00acc1", 0.12)
+                                : alpha("#fff", 0.56),
+                            border: `1px solid ${
+                              isActive || isLoading
+                                ? alpha("#00acc1", 0.25)
+                                : alpha("#fff", 0.72)
+                            }`,
+                            boxShadow:
+                              isActive || isLoading
+                                ? `0 8px 20px ${alpha("#00acc1", 0.12)}`
+                                : `0 4px 12px ${alpha("#000", 0.03)}`,
                             transition: "all 0.2s ease",
-                            pointerEvents: isHydrating ? "none" : "auto",
+                            pointerEvents: isHydrating || isLoading ? "none" : "auto",
                             "&:hover": {
-                              bgcolor: isActive ? alpha("#00acc1", 0.14) : alpha("#fff", 0.86),
+                              bgcolor:
+                                isActive || isLoading
+                                  ? alpha("#00acc1", 0.14)
+                                  : alpha("#fff", 0.86),
                               borderColor: alpha("#00acc1", 0.2),
                             },
                           }}
@@ -385,6 +428,11 @@ export const AgentHistoryPanel = ({
                                     <CloseRounded sx={{ fontSize: 16 }} />
                                   </IconButton>
                                 </Stack>
+                              ) : isLoading ? (
+                                <Box sx={{ minHeight: 46, display: "flex", flexDirection: "column", justifyContent: "center" }}>
+                                  <Skeleton variant="text" width="74%" height={18} />
+                                  <Skeleton variant="text" width="34%" height={14} sx={{ mt: 0.5 }} />
+                                </Box>
                               ) : pendingDeleteSessionId === session.id ? (
                                 <Stack direction="row" spacing={0.75} alignItems="center" sx={{ minHeight: 46 }}>
                                   <Box
@@ -440,7 +488,7 @@ export const AgentHistoryPanel = ({
                               )}
                             </Box>
 
-                            {!(editingSessionId === session.id || pendingDeleteSessionId === session.id) && (
+                            {!(editingSessionId === session.id || pendingDeleteSessionId === session.id || isLoading) && (
                               <Stack direction="row" spacing={0.25}>
                                 <Tooltip title="修改会话标题">
                                 <span>

src/components/chat/AgentMarkdownBlock.tsx

@@ -0,0 +1,168 @@
+"use client";
+
+import React from "react";
+import type { Element, Root, RootContent, Text } from "hast";
+import ReactMarkdown, { type Components } from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+import markdownStyles from "./GlobalChatboxMarkdown.module.css";
+
+export const normalizeClipboardText = (value: string) => value.replace(/\s+$/u, "");
+
+const isTextNode = (node: RootContent): node is Text => node.type === "text";
+
+const isElementNode = (node: RootContent): node is Element => node.type === "element";
+
+const createFadeSpan = (value: string, fadeKey: string): Element => ({
+  type: "element",
+  tagName: "span",
+  properties: {
+    className: [markdownStyles.streamFade],
+    dataStreamFadeKey: fadeKey,
+    dataStreamRevealLength: value.length,
+  },
+  children: [{ type: "text", value }],
+});
+
+const splitTextTail = (value: string, tailLength: number) => {
+  const codePoints = Array.from(value);
+  const stableText = codePoints.slice(0, -tailLength).join("");
+  const animatedText = codePoints.slice(-tailLength).join("");
+  return { stableText, animatedText };
+};
+
+const createStreamFadePlugin = (fadeLength: number, fadeKey: string) => {
+  return () => (tree: Root) => {
+    let remainingFadeLength = fadeLength;
+
+    const visitChildren = (parent: Element | Root) => {
+      const nextChildren: RootContent[] = [];
+
+      for (let index = parent.children.length - 1; index >= 0; index -= 1) {
+        const child = (parent.children as RootContent[])[index];
+        if (isTextNode(child)) {
+          if (!child.value.trim()) {
+            nextChildren.unshift(child);
+            continue;
+          }
+
+          if (remainingFadeLength <= 0) {
+            nextChildren.unshift(child);
+            continue;
+          }
+
+          const textLength = Array.from(child.value).length;
+          const tailLength = Math.min(textLength, remainingFadeLength);
+          const { stableText, animatedText } = splitTextTail(child.value, tailLength);
+          remainingFadeLength -= tailLength;
+
+          if (animatedText) {
+            nextChildren.unshift(createFadeSpan(animatedText, fadeKey));
+          }
+          if (stableText) {
+            nextChildren.unshift({ ...child, value: stableText });
+          }
+          continue;
+        }
+
+        if (isElementNode(child)) {
+          visitChildren(child);
+        }
+
+        nextChildren.unshift(child);
+      }
+
+      parent.children = nextChildren as typeof parent.children;
+    };
+
+    visitChildren(tree);
+  };
+};
+
+const StreamFadeSpan: Components["span"] = ({ node, children, ...props }) => {
+  const ref = React.useRef<HTMLSpanElement>(null);
+  const fadeKeyValue = node?.properties?.dataStreamFadeKey;
+  const fadeKey = typeof fadeKeyValue === "string" ? fadeKeyValue : undefined;
+  const revealLengthValue = node?.properties?.dataStreamRevealLength;
+  const revealLength =
+    typeof revealLengthValue === "number"
+      ? revealLengthValue
+      : typeof revealLengthValue === "string"
+        ? Number.parseInt(revealLengthValue, 10)
+        : 0;
+
+  React.useLayoutEffect(() => {
+    if (!fadeKey) return;
+
+    const element = ref.current;
+    if (!element) return;
+    if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return;
+
+    const duration = Math.min(260, Math.max(120, revealLength * 14));
+    const animation = element.animate(
+      [
+        { clipPath: "inset(0 100% 0 0)", opacity: 0.46 },
+        { clipPath: "inset(0 0% 0 0)", opacity: 1 },
+      ],
+      {
+        duration,
+        easing: "cubic-bezier(0.16, 1, 0.3, 1)",
+        fill: "both",
+      },
+    );
+
+    return () => {
+      animation.cancel();
+    };
+  }, [fadeKey, revealLength]);
+
+  return (
+    <span {...props} ref={ref}>
+      {children}
+    </span>
+  );
+};
+
+const markdownComponents: Components = {
+  span: StreamFadeSpan,
+};
+
+export const MarkdownBlock = ({
+  children,
+  streamFadeKey,
+  streamFadeLength,
+}: {
+  children: string;
+  streamFadeKey?: string;
+  streamFadeLength?: number | null;
+}) => {
+  const handleCopy = React.useCallback((event: React.ClipboardEvent<HTMLDivElement>) => {
+    const selectedText = window.getSelection()?.toString();
+    if (!selectedText) return;
+
+    event.preventDefault();
+    event.clipboardData.setData("text/plain", normalizeClipboardText(selectedText));
+  }, []);
+  const rehypePlugins = React.useMemo(
+    () =>
+      typeof streamFadeLength === "number" && streamFadeLength > 0
+        ? [createStreamFadePlugin(
+            streamFadeLength,
+            streamFadeKey ?? `stream-tail-${children.length}`,
+          )]
+        : [],
+    [children.length, streamFadeKey, streamFadeLength],
+  );
+
+  return (
+    <div className={markdownStyles.markdown} onCopy={handleCopy}>
+      <ReactMarkdown
+        components={markdownComponents}
+        remarkPlugins={[remarkGfm]}
+        rehypePlugins={rehypePlugins}
+      >
+        {children}
+      </ReactMarkdown>
+    </div>
+  );
+};

src/components/chat/AgentPermissionRequests.tsx

@@ -0,0 +1,631 @@
+"use client";
+
+import React from "react";
+import { AnimatePresence, motion } from "framer-motion";
+import {
+  Box,
+  Button,
+  Chip,
+  CircularProgress,
+  Collapse,
+  IconButton,
+  Stack,
+  Typography,
+  alpha,
+  useTheme,
+} from "@mui/material";
+import type { Theme } from "@mui/material/styles";
+import TerminalRounded from "@mui/icons-material/TerminalRounded";
+import FolderOpenRounded from "@mui/icons-material/FolderOpenRounded";
+import CheckCircleRounded from "@mui/icons-material/CheckCircleRounded";
+import BlockRounded from "@mui/icons-material/BlockRounded";
+import KeyboardArrowDownRounded from "@mui/icons-material/KeyboardArrowDownRounded";
+import KeyboardArrowUpRounded from "@mui/icons-material/KeyboardArrowUpRounded";
+import VerifiedUserRounded from "@mui/icons-material/VerifiedUserRounded";
+import GppGoodRounded from "@mui/icons-material/GppGoodRounded";
+
+import type { PermissionDecision } from "@/lib/chatStream";
+import type { Message } from "./GlobalChatbox.types";
+
+const getPermissionTitle = (permission: NonNullable<Message["permissions"]>[number]) => {
+  if (permission.permission === "external_directory") return "访问工作区外目录";
+  if (permission.permission === "bash") return "执行终端命令";
+  if (permission.permission === "edit") return "修改文件内容";
+  return permission.permission || "工具权限请求";
+};
+
+const getPermissionPrimaryValue = (
+  permission: NonNullable<Message["permissions"]>[number],
+) => {
+  if (typeof permission.target === "string" && permission.target.trim()) {
+    return permission.target.trim();
+  }
+  return permission.patterns[0] ?? permission.permission;
+};
+
+const PermissionIcon = ({
+  permission,
+}: {
+  permission: NonNullable<Message["permissions"]>[number];
+}) => {
+  if (permission.permission === "bash") {
+    return <TerminalRounded sx={{ fontSize: 22 }} />;
+  }
+  if (permission.permission === "external_directory") {
+    return <FolderOpenRounded sx={{ fontSize: 22 }} />;
+  }
+  return <VerifiedUserRounded sx={{ fontSize: 22 }} />;
+};
+
+const getPermissionStatusLabel = (status: NonNullable<Message["permissions"]>[number]["status"]) => {
+  if (status === "approved_always") return "已保存授权";
+  if (status === "approved_once") return "已允许一次";
+  if (status === "rejected") return "已拒绝";
+  if (status === "aborted") return "已中断";
+  if (status === "error") return "提交失败";
+  if (status === "submitting") return "提交中";
+  return "等待确认";
+};
+
+const pendingPermissionColor = "#f9a825";
+const approvedOncePermissionColor = "#00838f";
+
+const getPermissionStatusColor = (
+  status: NonNullable<Message["permissions"]>[number]["status"],
+  theme: Theme,
+) => {
+  if (status === "approved_once") return approvedOncePermissionColor;
+  if (status === "approved_always") return theme.palette.success.main;
+  if (status === "rejected" || status === "error") return theme.palette.error.main;
+  if (status === "aborted") return theme.palette.text.secondary;
+  return pendingPermissionColor;
+};
+
+const getPermissionStatusTextColor = (
+  status: NonNullable<Message["permissions"]>[number]["status"],
+  theme: Theme,
+) => {
+  if (status === "approved_once") return "#006c78";
+  if (status === "approved_always") return theme.palette.success.dark;
+  if (status === "rejected" || status === "error") return theme.palette.error.main;
+  if (status === "aborted") return theme.palette.text.secondary;
+  return "#8a5a00";
+};
+
+const PermissionRequestCard = ({
+  permission,
+  isRunning,
+  onReply,
+}: {
+  permission: NonNullable<Message["permissions"]>[number];
+  isRunning: boolean;
+  onReply: (requestId: string, reply: PermissionDecision) => void;
+}) => {
+  const theme = useTheme();
+  const isPending =
+    isRunning && (permission.status === "pending" || permission.status === "error");
+  const isSubmitting = isRunning && permission.status === "submitting";
+  const primaryValue = getPermissionPrimaryValue(permission);
+  const accentColor = getPermissionStatusColor(permission.status, theme);
+  const statusTextColor = getPermissionStatusTextColor(permission.status, theme);
+  const statusLabel = getPermissionStatusLabel(permission.status);
+  const persistentScope = permission.always.length > 0
+    ? permission.always
+    : permission.patterns;
+
+  return (
+    <Box
+      sx={{
+        borderRadius: 3,
+        overflow: "hidden",
+        border: `1px solid ${alpha("#fff", 0.72)}`,
+        bgcolor: alpha("#fff", 0.5),
+        boxShadow: `0 8px 24px ${alpha("#000", 0.05)}`,
+        backdropFilter: "blur(20px)",
+        position: "relative",
+        "&::before": {
+          content: '""',
+          position: "absolute",
+          inset: "10px auto 10px 0",
+          width: 3,
+          borderRadius: "0 999px 999px 0",
+          bgcolor: accentColor,
+        },
+      }}
+    >
+      <Stack
+        direction="row"
+        spacing={1}
+        alignItems="center"
+        sx={{
+          px: 1.5,
+          py: 1.25,
+          pl: 1.75,
+          borderBottom: `1px solid ${alpha("#000", 0.05)}`,
+        }}
+      >
+        <Box
+          sx={{
+            width: 32,
+            height: 32,
+            borderRadius: "50%",
+            display: "grid",
+            placeItems: "center",
+            flex: "0 0 auto",
+            color: accentColor,
+            bgcolor: alpha(accentColor, 0.1),
+            border: `1px solid ${alpha(accentColor, 0.16)}`,
+          }}
+        >
+          <PermissionIcon permission={permission} />
+        </Box>
+        <Box sx={{ minWidth: 0, flex: 1 }}>
+          <Typography variant="subtitle2" fontWeight={800} noWrap sx={{ lineHeight: 1.25 }}>
+            {getPermissionTitle(permission)}
+          </Typography>
+        </Box>
+        <Chip
+          size="small"
+          label={statusLabel}
+          sx={{
+            height: 24,
+            fontSize: "0.7rem",
+            fontWeight: 800,
+            borderRadius: "12px",
+            bgcolor: alpha(accentColor, 0.12),
+            color: statusTextColor,
+            "& .MuiChip-label": { px: 1 },
+          }}
+        />
+      </Stack>
+
+      <Stack spacing={1.15} sx={{ px: 1.5, pt: 1.25, pb: 1.35, pl: 1.75 }}>
+        <Box
+          sx={{
+            px: 1.25,
+            py: 1,
+            borderRadius: 2.5,
+            bgcolor: alpha("#000", 0.025),
+            border: `1px solid ${alpha("#000", 0.045)}`,
+          }}
+        >
+          <Typography variant="caption" color="text.secondary" fontWeight={800}>
+            请求目标
+          </Typography>
+          <Typography
+            variant="body2"
+            color="text.primary"
+            fontFamily={permission.permission === "bash" ? "monospace" : undefined}
+            sx={{
+              mt: 0.25,
+              lineHeight: 1.55,
+              wordBreak: "break-word",
+              whiteSpace: "pre-wrap",
+            }}
+          >
+            {primaryValue}
+          </Typography>
+        </Box>
+        {isPending || isSubmitting ? (
+          <Box
+            sx={{
+              px: 1.25,
+              py: 0.85,
+              borderRadius: 2.5,
+              bgcolor: alpha(theme.palette.success.main, 0.055),
+              border: `1px solid ${alpha(theme.palette.success.main, 0.11)}`,
+            }}
+          >
+            <Typography variant="caption" color="success.dark" fontWeight={800}>
+              保存授权范围
+            </Typography>
+            <Typography
+              variant="caption"
+              color="text.secondary"
+              fontFamily={permission.permission === "bash" ? "monospace" : undefined}
+              sx={{ display: "block", mt: 0.2, lineHeight: 1.45, wordBreak: "break-word", whiteSpace: "pre-wrap" }}
+            >
+              {persistentScope.join("\n")}
+            </Typography>
+          </Box>
+        ) : null}
+      </Stack>
+
+      {permission.error ? (
+        <Box sx={{ px: 1.5, pb: isPending || isSubmitting ? 1 : 1.35, pl: 1.75 }}>
+          <Typography
+            variant="caption"
+            color="error.main"
+            sx={{
+              display: "block",
+              px: 1.25,
+              py: 0.75,
+              borderRadius: 2,
+              bgcolor: alpha(theme.palette.error.main, 0.06),
+              wordBreak: "break-word",
+            }}
+          >
+            {permission.error}
+          </Typography>
+        </Box>
+      ) : null}
+
+      {isPending || isSubmitting ? (
+        <Stack
+          direction="row"
+          spacing={1}
+          flexWrap="wrap"
+          useFlexGap
+          sx={{ px: 1.5, pb: 1.35, pl: 1.75, pt: 0 }}
+        >
+          <Button
+            size="small"
+            variant="contained"
+            disableElevation
+            disabled={isSubmitting}
+            onClick={() => onReply(permission.requestId, "once")}
+            startIcon={
+              isSubmitting ? (
+                <CircularProgress size={14} color="inherit" />
+              ) : (
+                <CheckCircleRounded fontSize="small" />
+              )
+            }
+            sx={{
+              minWidth: 94,
+              height: 34,
+              borderRadius: "17px",
+              bgcolor: "#00838f",
+              fontWeight: 800,
+              fontSize: "0.78rem",
+              textTransform: "none",
+              boxShadow: `0 4px 12px ${alpha("#00838f", 0.24)}`,
+              "&:hover": {
+                bgcolor: "#006c78",
+                boxShadow: `0 6px 16px ${alpha("#00838f", 0.28)}`,
+              },
+            }}
+          >
+            允许一次
+          </Button>
+          <Button
+            size="small"
+            color="success"
+            variant="outlined"
+            disabled={isSubmitting}
+            onClick={() => onReply(permission.requestId, "always")}
+            startIcon={<GppGoodRounded fontSize="small" />}
+            sx={{
+              height: 34,
+              borderRadius: "17px",
+              px: 1.5,
+              fontWeight: 800,
+              fontSize: "0.78rem",
+              textTransform: "none",
+              borderColor: alpha(theme.palette.success.main, 0.28),
+              bgcolor: alpha("#fff", 0.45),
+              "&:hover": {
+                borderColor: alpha(theme.palette.success.main, 0.42),
+                bgcolor: alpha(theme.palette.success.main, 0.08),
+              },
+            }}
+          >
+            保存授权
+          </Button>
+          <Button
+            size="small"
+            color="error"
+            variant="outlined"
+            disabled={isSubmitting}
+            onClick={() => onReply(permission.requestId, "reject")}
+            startIcon={<BlockRounded fontSize="small" />}
+            sx={{
+              height: 34,
+              borderRadius: "17px",
+              px: 1.5,
+              fontWeight: 800,
+              fontSize: "0.78rem",
+              textTransform: "none",
+              borderColor: alpha(theme.palette.error.main, 0.22),
+              bgcolor: alpha("#fff", 0.45),
+              "&:hover": {
+                borderColor: alpha(theme.palette.error.main, 0.34),
+                bgcolor: alpha(theme.palette.error.main, 0.07),
+              },
+            }}
+          >
+            拒绝
+          </Button>
+        </Stack>
+      ) : null}
+    </Box>
+  );
+};
+
+export const PermissionRequestGroup = ({
+  permissions,
+  isRunning,
+  onReply,
+}: {
+  permissions: NonNullable<Message["permissions"]>;
+  isRunning: boolean;
+  onReply: (requestId: string, reply: PermissionDecision) => void;
+}) => {
+  const theme = useTheme();
+  const onceCount = permissions.filter((permission) => permission.status === "approved_once").length;
+  const alwaysCount = permissions.filter((permission) => permission.status === "approved_always").length;
+  const rejectedCount = permissions.filter((permission) => permission.status === "rejected").length;
+  const abortedCount = permissions.filter((permission) => permission.status === "aborted").length;
+  const pendingCount = permissions.filter(
+    (permission) =>
+      permission.status === "pending" ||
+      permission.status === "submitting" ||
+      permission.status === "error",
+  ).length;
+  const hasPendingPermissions = pendingCount > 0;
+  const [expanded, setExpanded] = React.useState(false);
+  const latestPermissions = permissions.slice(-3);
+  const pendingPermissions = permissions.filter(
+    (permission) =>
+      permission.status === "pending" ||
+      permission.status === "submitting" ||
+      permission.status === "error",
+  );
+  const summaryItems = [
+    { label: "共", value: permissions.length, color: theme.palette.text.secondary },
+    { label: "允许一次", value: onceCount, color: getPermissionStatusColor("approved_once", theme), textColor: getPermissionStatusTextColor("approved_once", theme) },
+    { label: "保存授权", value: alwaysCount, color: getPermissionStatusColor("approved_always", theme), textColor: getPermissionStatusTextColor("approved_always", theme) },
+    { label: "拒绝", value: rejectedCount, color: getPermissionStatusColor("rejected", theme), textColor: getPermissionStatusTextColor("rejected", theme) },
+    { label: "中断", value: abortedCount, color: getPermissionStatusColor("aborted", theme), textColor: getPermissionStatusTextColor("aborted", theme) },
+  ];
+  const chipColor =
+    pendingCount > 0
+      ? getPermissionStatusColor("pending", theme)
+      : abortedCount > 0
+        ? getPermissionStatusColor("aborted", theme)
+        : rejectedCount > 0
+          ? getPermissionStatusColor("rejected", theme)
+          : getPermissionStatusColor("approved_always", theme);
+  const chipTextColor =
+    pendingCount > 0
+      ? getPermissionStatusTextColor("pending", theme)
+      : abortedCount > 0
+        ? getPermissionStatusTextColor("aborted", theme)
+        : rejectedCount > 0
+          ? getPermissionStatusTextColor("rejected", theme)
+          : getPermissionStatusTextColor("approved_always", theme);
+
+  return (
+    <Box
+      sx={{
+        borderRadius: 3,
+        overflow: "hidden",
+        border: `1px solid ${alpha("#fff", 0.72)}`,
+        bgcolor: alpha("#fff", 0.46),
+        boxShadow: `0 8px 24px ${alpha("#000", 0.045)}`,
+        backdropFilter: "blur(20px)",
+      }}
+    >
+      <Stack
+        direction="row"
+        alignItems="center"
+        spacing={1}
+        role="button"
+        tabIndex={0}
+        onClick={() => setExpanded((value) => !value)}
+        onKeyDown={(event) => {
+          if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            setExpanded((value) => !value);
+          }
+        }}
+        sx={{
+          px: 1.5,
+          py: 1.15,
+          cursor: "pointer",
+          transition: "background-color 0.2s ease",
+          "&:hover": { bgcolor: alpha("#000", 0.025) },
+        }}
+      >
+        <Box
+          sx={{
+            width: 30,
+            height: 30,
+            borderRadius: "50%",
+            display: "grid",
+            placeItems: "center",
+            flex: "0 0 auto",
+            color: chipColor,
+            bgcolor: alpha(chipColor, 0.1),
+            border: `1px solid ${alpha(chipColor, 0.15)}`,
+          }}
+        >
+          <VerifiedUserRounded sx={{ fontSize: 18 }} />
+        </Box>
+        <Box sx={{ minWidth: 0, flex: 1 }}>
+          <Typography variant="subtitle2" fontWeight={800} noWrap sx={{ lineHeight: 1.25 }}>
+            权限请求
+          </Typography>
+          <Stack
+            direction="row"
+            flexWrap="wrap"
+            gap={0.6}
+            sx={{ mt: 0.55, maxHeight: 48, overflow: "hidden" }}
+          >
+            {summaryItems.map((item) => (
+              <Box
+                key={item.label}
+                component="span"
+                sx={{
+                  display: "inline-flex",
+                  alignItems: "center",
+                  gap: 0.45,
+                  height: 22,
+                  px: 0.8,
+                  borderRadius: "11px",
+                  bgcolor: alpha(item.color, 0.08),
+                  border: `1px solid ${alpha(item.color, 0.12)}`,
+                  color: "textColor" in item ? item.textColor : item.color,
+                  fontSize: "0.7rem",
+                  fontWeight: 800,
+                  lineHeight: 1,
+                  whiteSpace: "nowrap",
+                }}
+              >
+                <Box
+                  component="span"
+                  sx={{
+                    color: "textColor" in item ? item.textColor : item.color,
+                    fontWeight: 700,
+                  }}
+                >
+                  {item.label}
+                </Box>
+                <Box component="span">{item.value} 项</Box>
+              </Box>
+            ))}
+          </Stack>
+        </Box>
+        {isRunning && pendingCount > 0 ? (
+          <Chip
+            size="small"
+            label={`待确认 ${pendingCount} 项`}
+            sx={{
+              height: 24,
+              borderRadius: "12px",
+              fontSize: "0.7rem",
+              fontWeight: 800,
+              color: chipTextColor,
+              bgcolor: alpha(chipColor, 0.1),
+              "& .MuiChip-label": { px: 1 },
+            }}
+          />
+        ) : null}
+        <IconButton
+          size="small"
+          aria-label={expanded ? "收起权限请求" : "展开权限请求"}
+          sx={{
+            width: 28,
+            height: 28,
+            color: "text.secondary",
+            bgcolor: alpha("#000", 0.035),
+            "&:hover": { bgcolor: alpha("#000", 0.07) },
+          }}
+        >
+          {expanded ? (
+            <KeyboardArrowUpRounded sx={{ fontSize: 18 }} />
+          ) : (
+            <KeyboardArrowDownRounded sx={{ fontSize: 18 }} />
+          )}
+        </IconButton>
+      </Stack>
+
+      {!expanded && isRunning && !hasPendingPermissions && latestPermissions.length > 0 ? (
+        <Stack spacing={0} sx={{ px: 1.5, pb: 1.25 }}>
+          {latestPermissions.map((permission, index) => {
+            const primaryValue = getPermissionPrimaryValue(permission);
+            const isLast = index === latestPermissions.length - 1;
+            const itemColor = getPermissionStatusColor(permission.status, theme);
+            const itemTextColor = getPermissionStatusTextColor(permission.status, theme);
+
+            return (
+              <Stack
+                key={permission.requestId}
+                direction="row"
+                spacing={1}
+                alignItems="center"
+                sx={{
+                  py: 0.8,
+                  borderTop: index === 0 ? `1px solid ${alpha(chipColor, 0.1)}` : "none",
+                  borderBottom: isLast ? "none" : `1px solid ${alpha("#000", 0.045)}`,
+                }}
+              >
+                <Box
+                  sx={{
+                    width: 24,
+                    height: 24,
+                    borderRadius: "50%",
+                    display: "grid",
+                    placeItems: "center",
+                    flex: "0 0 auto",
+                    color: itemColor,
+                    bgcolor: alpha(itemColor, 0.08),
+                  }}
+                >
+                  <PermissionIcon permission={permission} />
+                </Box>
+                <Box sx={{ minWidth: 0, flex: 1 }}>
+                  <Typography variant="caption" color="text.primary" fontWeight={750} noWrap sx={{ display: "block" }}>
+                    {getPermissionTitle(permission)}
+                  </Typography>
+                  <Typography
+                    variant="caption"
+                    color="text.secondary"
+                    noWrap
+                    title={primaryValue}
+                    sx={{
+                      display: "block",
+                      fontFamily: permission.permission === "bash" ? "monospace" : undefined,
+                    }}
+                  >
+                    {primaryValue}
+                  </Typography>
+                </Box>
+                <Chip
+                  size="small"
+                  label={getPermissionStatusLabel(permission.status)}
+                  sx={{
+                    height: 22,
+                    borderRadius: "11px",
+                    fontSize: "0.68rem",
+                    fontWeight: 800,
+                    color: itemTextColor,
+                    bgcolor: alpha(itemColor, 0.08),
+                    "& .MuiChip-label": { px: 0.85 },
+                  }}
+                />
+              </Stack>
+            );
+          })}
+        </Stack>
+      ) : null}
+
+      <AnimatePresence initial={false}>
+        {!expanded && isRunning && hasPendingPermissions ? (
+          <motion.div
+            key="pending-permissions"
+            initial={{ opacity: 0, y: -10, height: 0 }}
+            animate={{ opacity: 1, y: 0, height: "auto" }}
+            exit={{ opacity: 0, y: -8, height: 0 }}
+            transition={{ duration: 0.2, ease: "easeOut" }}
+            style={{ overflow: "hidden" }}
+          >
+            <Stack spacing={1} sx={{ px: 1.25, pb: 1.25 }}>
+              {pendingPermissions.map((permission) => (
+                <PermissionRequestCard
+                  key={permission.requestId}
+                  permission={permission}
+                  isRunning={isRunning}
+                  onReply={onReply}
+                />
+              ))}
+            </Stack>
+          </motion.div>
+        ) : null}
+      </AnimatePresence>
+
+      <Collapse in={expanded} timeout="auto" unmountOnExit>
+        <Stack spacing={1} sx={{ px: 1.25, pb: 1.25 }}>
+          {permissions.map((permission) => (
+            <PermissionRequestCard
+              key={permission.requestId}
+              permission={permission}
+              isRunning={isRunning}
+              onReply={onReply}
+            />
+          ))}
+        </Stack>
+      </Collapse>
+    </Box>
+  );
+};

src/components/chat/AgentProgressTimeline.test.tsx

@@ -30,8 +30,8 @@ describe("AgentProgressTimeline", () => {
         id: "tool",
         phase: "tool",
         status: "running",
-        title: "正在调用 dynamic_http_call",
-        detail: "GET /api/v1/network/bottlenecks",
+        title: "正在调用 tjwater_cli",
+        detail: "analysis bottlenecks",
         startedAt: now - 1200,
         elapsedMs: 1200,
         elapsedSnapshotAt: now,
@@ -43,7 +43,7 @@ describe("AgentProgressTimeline", () => {
     expect(screen.getByText(/Agent 过程:/)).toBeInTheDocument();
     expect(screen.getByText(/耗时 5.0s/)).toBeInTheDocument();
     expect(screen.getByText("查询后端数据")).toBeInTheDocument();
-    expect(screen.getByText("GET /api/v1/network/bottlenecks")).toBeInTheDocument();
+    expect(screen.getByText("analysis bottlenecks")).toBeInTheDocument();
     expect(screen.getByText("1.2s")).toBeInTheDocument();
   });
 
@@ -86,7 +86,7 @@ describe("AgentProgressTimeline", () => {
         id: "tool",
         phase: "tool",
         status: "completed",
-        title: "正在调用 dynamic_http_call",
+        title: "正在调用 tjwater_cli",
         startedAt: Date.now() - 4000,
         endedAt: Date.now(),
       },

src/components/chat/AgentProgressTimeline.tsx

@@ -76,7 +76,7 @@ const phaseIcon = (phase: string, status: ChatProgress["status"]) => {
 
 const formatToolTitle = (item: ChatProgress) => {
   const text = `${item.title} ${item.detail ?? ""}`;
-  if (text.includes("dynamic_http_call")) return "查询后端数据";
+  if (text.includes("tjwater_cli")) return "查询后端数据";
   if (text.includes("show_chart")) return "生成图表";
   if (text.includes("locate_features")) return "地图定位";
   if (text.includes("view_history")) return "打开历史曲线";
@@ -85,7 +85,12 @@ const formatToolTitle = (item: ChatProgress) => {
   return item.title;
 };
 
-export const AgentProgressTimeline = ({ progress, isAborted }: { progress: ChatProgress[], isAborted?: boolean }) => {
+type AgentProgressTimelineProps = {
+  progress: ChatProgress[];
+  isAborted?: boolean;
+};
+
+const AgentProgressTimelineInner = ({ progress, isAborted }: AgentProgressTimelineProps) => {
   const theme = useTheme();
   const [nowMs, setNowMs] = useState(() => Date.now());
   
@@ -356,3 +361,12 @@ export const AgentProgressTimeline = ({ progress, isAborted }: { progress: ChatP
     </Box>
   );
 };
+
+export const AgentProgressTimeline = React.memo(
+  AgentProgressTimelineInner,
+  (prevProps, nextProps) =>
+    prevProps.progress === nextProps.progress &&
+    prevProps.isAborted === nextProps.isAborted,
+);
+
+AgentProgressTimeline.displayName = "AgentProgressTimeline";

src/components/chat/AgentQuestionRequests.tsx

@@ -0,0 +1,564 @@
+"use client";
+
+import React from "react";
+import {
+  Box,
+  Button,
+  Checkbox,
+  Chip,
+  CircularProgress,
+  Collapse,
+  FormControlLabel,
+  Stack,
+  TextField,
+  Typography,
+  alpha,
+  useTheme,
+} from "@mui/material";
+import type { Theme } from "@mui/material/styles";
+import CheckCircleRounded from "@mui/icons-material/CheckCircleRounded";
+import EditNoteRounded from "@mui/icons-material/EditNoteRounded";
+import HelpOutlineRounded from "@mui/icons-material/HelpOutlineRounded";
+import RadioButtonUncheckedRounded from "@mui/icons-material/RadioButtonUncheckedRounded";
+
+import type { Message } from "./GlobalChatbox.types";
+
+const getQuestionStatusLabel = (
+  status: NonNullable<Message["questions"]>[number]["status"],
+) => {
+  if (status === "answered") return "已回答";
+  if (status === "rejected") return "已跳过";
+  if (status === "error") return "提交失败";
+  if (status === "submitting") return "提交中";
+  return "等待回答";
+};
+
+const getQuestionStatusColor = (
+  status: NonNullable<Message["questions"]>[number]["status"],
+  theme: Theme,
+) => {
+  if (status === "answered") return theme.palette.success.main;
+  if (status === "rejected") return theme.palette.text.secondary;
+  if (status === "error") return theme.palette.error.main;
+  return "#0288d1";
+};
+
+const QuestionRequestCard = ({
+  questionRequest,
+  onReply,
+  onReject,
+}: {
+  questionRequest: NonNullable<Message["questions"]>[number];
+  onReply: (requestId: string, answers: string[][]) => void;
+  onReject: (requestId: string) => void;
+}) => {
+  const theme = useTheme();
+  const isEditable =
+    questionRequest.status === "pending" || questionRequest.status === "error";
+  const isSubmitting = questionRequest.status === "submitting";
+  const statusColor = getQuestionStatusColor(questionRequest.status, theme);
+  const [selected, setSelected] = React.useState<Record<number, string[]>>({});
+  const [customSelected, setCustomSelected] = React.useState<Record<number, boolean>>({});
+  const [custom, setCustom] = React.useState<Record<number, string>>({});
+
+  const answers = React.useMemo(
+    () =>
+      questionRequest.questions.map((question, index) => {
+        const selectedAnswers = selected[index] ?? [];
+        const isCustomSelected =
+          customSelected[index] === true ||
+          (question.custom !== false && question.options.length === 0);
+        const customAnswer = custom[index]?.trim();
+        return isCustomSelected && customAnswer
+          ? [...selectedAnswers, customAnswer]
+          : selectedAnswers;
+      }),
+    [custom, customSelected, questionRequest.questions, selected],
+  );
+
+  const canSubmit =
+    isEditable &&
+    questionRequest.questions.length > 0 &&
+    questionRequest.questions.every((_, index) => {
+      const answer = answers[index] ?? [];
+      return answer.some((item) => item.trim().length > 0);
+    });
+
+  const answerSummary = (questionRequest.answers ?? [])
+    .map((answer) => answer.join("、"))
+    .filter(Boolean)
+    .join("；");
+
+  return (
+    <Box
+      sx={{
+        borderRadius: 3,
+        overflow: "hidden",
+        border: `1px solid ${alpha("#fff", 0.72)}`,
+        bgcolor: alpha("#fff", 0.52),
+        boxShadow: `0 8px 24px ${alpha("#000", 0.05)}`,
+        backdropFilter: "blur(20px)",
+        position: "relative",
+        "&::before": {
+          content: '""',
+          position: "absolute",
+          inset: "10px auto 10px 0",
+          width: 3,
+          borderRadius: "0 999px 999px 0",
+          bgcolor: statusColor,
+        },
+      }}
+    >
+      <Stack
+        direction="row"
+        spacing={1}
+        alignItems="center"
+        sx={{
+          px: 1.5,
+          py: 1.25,
+          pl: 1.75,
+          borderBottom: `1px solid ${alpha("#000", 0.05)}`,
+        }}
+      >
+        <Box
+          sx={{
+            width: 32,
+            height: 32,
+            borderRadius: "50%",
+            display: "grid",
+            placeItems: "center",
+            flex: "0 0 auto",
+            color: statusColor,
+            bgcolor: alpha(statusColor, 0.1),
+            border: `1px solid ${alpha(statusColor, 0.16)}`,
+          }}
+        >
+          <HelpOutlineRounded sx={{ fontSize: 21 }} />
+        </Box>
+        <Box sx={{ minWidth: 0, flex: 1 }}>
+          <Typography variant="subtitle2" fontWeight={800} noWrap sx={{ lineHeight: 1.25 }}>
+            需要补充信息
+          </Typography>
+        </Box>
+        <Chip
+          size="small"
+          label={getQuestionStatusLabel(questionRequest.status)}
+          sx={{
+            height: 24,
+            fontSize: "0.7rem",
+            fontWeight: 800,
+            borderRadius: "12px",
+            bgcolor: alpha(statusColor, 0.12),
+            color: statusColor,
+            "& .MuiChip-label": { px: 1 },
+          }}
+        />
+      </Stack>
+
+      <Stack spacing={1.3} sx={{ px: 1.5, py: 1.35, pl: 1.75 }}>
+        {questionRequest.questions.map((question, index) => {
+          const selectedAnswers = selected[index] ?? [];
+          const isCustomEnabled = question.custom !== false;
+          const isCustomSelected =
+            customSelected[index] === true ||
+            (isCustomEnabled && question.options.length === 0);
+          const setQuestionAnswers = (nextAnswers: string[]) => {
+            setSelected((current) => ({
+              ...current,
+              [index]: nextAnswers,
+            }));
+          };
+          const setQuestionCustomSelected = (checked: boolean) => {
+            setCustomSelected((current) => ({
+              ...current,
+              [index]: checked,
+            }));
+          };
+
+          return (
+            <Box
+              key={`${question.header}-${index}`}
+              sx={{
+                px: 1.25,
+                py: 1,
+                borderRadius: 2.5,
+                bgcolor: alpha("#000", 0.025),
+                border: `1px solid ${alpha("#000", 0.045)}`,
+              }}
+            >
+              <Typography variant="caption" color="text.secondary" fontWeight={800}>
+                {question.header || `问题 ${index + 1}`}
+              </Typography>
+              <Typography
+                variant="body2"
+                color="text.primary"
+                sx={{ mt: 0.35, lineHeight: 1.55, wordBreak: "break-word" }}
+              >
+                {question.question}
+              </Typography>
+
+              {question.options.length ? (
+                <Stack spacing={0.75} sx={{ mt: 1 }}>
+                  {question.options.map((option) => {
+                    const checked = selectedAnswers.includes(option.label);
+                    if (question.multiple) {
+                      return (
+                        <FormControlLabel
+                          key={option.label}
+                          disabled={!isEditable || isSubmitting}
+                          control={
+                            <Checkbox
+                              size="small"
+                              checked={checked}
+                              onChange={(event) => {
+                                if (event.target.checked) {
+                                  setQuestionAnswers([...selectedAnswers, option.label]);
+                                } else {
+                                  setQuestionAnswers(
+                                    selectedAnswers.filter((item) => item !== option.label),
+                                  );
+                                }
+                              }}
+                            />
+                          }
+                          label={
+                            <Box>
+                              <Typography variant="body2" fontWeight={750}>
+                                {option.label}
+                              </Typography>
+                              {option.description ? (
+                                <Typography variant="caption" color="text.secondary">
+                                  {option.description}
+                                </Typography>
+                              ) : null}
+                            </Box>
+                          }
+                          sx={{ alignItems: "flex-start", m: 0 }}
+                        />
+                      );
+                    }
+                    return (
+                      <Button
+                        key={option.label}
+                        size="small"
+                        variant={checked ? "contained" : "outlined"}
+                        disabled={!isEditable || isSubmitting}
+                        onClick={() => {
+                          setQuestionAnswers([option.label]);
+                          setQuestionCustomSelected(false);
+                        }}
+                        startIcon={
+                          checked ? (
+                            <CheckCircleRounded fontSize="small" />
+                          ) : (
+                            <RadioButtonUncheckedRounded fontSize="small" />
+                          )
+                        }
+                        sx={{
+                          justifyContent: "flex-start",
+                          minHeight: 38,
+                          borderRadius: 2,
+                          textTransform: "none",
+                          fontWeight: 800,
+                          bgcolor: checked ? "#0288d1" : alpha("#fff", 0.45),
+                          borderColor: checked ? "#0288d1" : alpha("#0288d1", 0.22),
+                          "&:hover": {
+                            bgcolor: checked ? "#0277bd" : alpha("#0288d1", 0.08),
+                          },
+                        }}
+                      >
+                        <Box sx={{ textAlign: "left", minWidth: 0 }}>
+                          <Typography variant="body2" fontWeight={800}>
+                            {option.label}
+                          </Typography>
+                          {option.description ? (
+                            <Typography
+                              variant="caption"
+                              sx={{ display: "block", opacity: checked ? 0.86 : 0.72 }}
+                            >
+                              {option.description}
+                            </Typography>
+                          ) : null}
+                        </Box>
+                      </Button>
+                    );
+                  })}
+                  {isCustomEnabled ? (
+                    question.multiple ? (
+                      <FormControlLabel
+                        disabled={!isEditable || isSubmitting}
+                        control={
+                          <Checkbox
+                            size="small"
+                            checked={isCustomSelected}
+                            onChange={(event) =>
+                              setQuestionCustomSelected(event.target.checked)
+                            }
+                            sx={{
+                              p: 0.5,
+                              color: alpha("#0288d1", 0.55),
+                              "&.Mui-checked": { color: "#0288d1" },
+                            }}
+                          />
+                        }
+                        label={
+                          <Stack direction="row" spacing={0.75} alignItems="center">
+                            <EditNoteRounded sx={{ fontSize: 18, color: "#0288d1" }} />
+                            <Typography variant="body2" fontWeight={800}>
+                              自定义回答
+                            </Typography>
+                          </Stack>
+                        }
+                        sx={{
+                          alignItems: "center",
+                          minHeight: 38,
+                          m: 0,
+                          px: 0.75,
+                          py: 0.25,
+                          borderRadius: 2,
+                          border: `1px solid ${
+                            isCustomSelected ? "#0288d1" : alpha("#0288d1", 0.18)
+                          }`,
+                          bgcolor: isCustomSelected
+                            ? alpha("#0288d1", 0.1)
+                            : alpha("#fff", 0.45),
+                          transition: "background-color 0.18s ease, border-color 0.18s ease",
+                          "&:hover": {
+                            bgcolor: isCustomSelected
+                              ? alpha("#0288d1", 0.13)
+                              : alpha("#0288d1", 0.07),
+                          },
+                          "& .MuiFormControlLabel-label": {
+                            color: isCustomSelected ? "#0277bd" : "text.primary",
+                          },
+                        }}
+                      />
+                    ) : (
+                      <Button
+                        size="small"
+                        variant={isCustomSelected ? "contained" : "outlined"}
+                        disabled={!isEditable || isSubmitting}
+                        onClick={() => {
+                          setQuestionAnswers([]);
+                          setQuestionCustomSelected(true);
+                        }}
+                        startIcon={
+                          isCustomSelected ? (
+                            <CheckCircleRounded fontSize="small" />
+                          ) : (
+                            <EditNoteRounded fontSize="small" />
+                          )
+                        }
+                        sx={{
+                          justifyContent: "flex-start",
+                          minHeight: 38,
+                          borderRadius: 2,
+                          textTransform: "none",
+                          fontWeight: 800,
+                          bgcolor: isCustomSelected ? "#0288d1" : alpha("#fff", 0.45),
+                          borderColor: isCustomSelected
+                            ? "#0288d1"
+                            : alpha("#0288d1", 0.22),
+                          "&:hover": {
+                            bgcolor: isCustomSelected
+                              ? "#0277bd"
+                              : alpha("#0288d1", 0.08),
+                          },
+                        }}
+                      >
+                        <Box sx={{ textAlign: "left", minWidth: 0 }}>
+                          <Typography variant="body2" fontWeight={800}>
+                            自定义回答
+                          </Typography>
+                        </Box>
+                      </Button>
+                    )
+                  ) : null}
+                </Stack>
+              ) : null}
+
+              <Collapse in={isCustomEnabled && isCustomSelected} timeout="auto" unmountOnExit>
+                <Box
+                  sx={{
+                    mt: 0.85,
+                    px: 1.15,
+                    py: 0.85,
+                    borderRadius: 2.5,
+                    bgcolor: alpha("#fff", 0.62),
+                    border: `1px solid ${alpha("#fff", 0.82)}`,
+                    boxShadow: `0 8px 22px ${alpha("#000", 0.045)}, 0 0 0 1px ${alpha("#0288d1", 0.05)} inset`,
+                    backdropFilter: "blur(18px)",
+                  }}
+                >
+                  <TextField
+                    multiline
+                    minRows={2}
+                    maxRows={5}
+                    fullWidth
+                    variant="standard"
+                    disabled={!isEditable || isSubmitting}
+                    value={custom[index] ?? ""}
+                    onChange={(event) =>
+                      setCustom((current) => ({
+                        ...current,
+                        [index]: event.target.value,
+                      }))
+                    }
+                    placeholder="输入自定义回答"
+                    InputProps={{
+                      disableUnderline: true,
+                      sx: {
+                        alignItems: "flex-start",
+                        fontSize: "0.88rem",
+                        lineHeight: 1.55,
+                        fontWeight: 500,
+                        color: "text.primary",
+                        "& textarea::placeholder": {
+                          color: alpha(theme.palette.text.primary, 0.38),
+                          opacity: 1,
+                        },
+                      },
+                    }}
+                  />
+                </Box>
+              </Collapse>
+            </Box>
+          );
+        })}
+
+        {questionRequest.status === "answered" ? (
+          <Typography
+            variant="caption"
+            color="success.main"
+            sx={{
+              display: "block",
+              px: 1.25,
+              py: 0.75,
+              borderRadius: 2,
+              bgcolor: alpha(theme.palette.success.main, 0.07),
+              wordBreak: "break-word",
+            }}
+          >
+            已回答{answerSummary ? `：${answerSummary}` : ""}
+          </Typography>
+        ) : null}
+
+        {questionRequest.status === "rejected" ? (
+          <Typography
+            variant="caption"
+            color="text.secondary"
+            sx={{
+              display: "block",
+              px: 1.25,
+              py: 0.75,
+              borderRadius: 2,
+              bgcolor: alpha("#000", 0.035),
+            }}
+          >
+            已跳过
+          </Typography>
+        ) : null}
+
+        {questionRequest.error ? (
+          <Typography
+            variant="caption"
+            color="error.main"
+            sx={{
+              display: "block",
+              px: 1.25,
+              py: 0.75,
+              borderRadius: 2,
+              bgcolor: alpha(theme.palette.error.main, 0.06),
+              wordBreak: "break-word",
+            }}
+          >
+            {questionRequest.error}
+          </Typography>
+        ) : null}
+      </Stack>
+
+      {isEditable || isSubmitting ? (
+        <Stack
+          direction="row"
+          spacing={1}
+          flexWrap="wrap"
+          useFlexGap
+          sx={{ px: 1.5, pb: 1.35, pl: 1.75 }}
+        >
+          <Button
+            size="small"
+            variant="outlined"
+            disabled={isSubmitting}
+            onClick={() => onReject(questionRequest.requestId)}
+            sx={{
+              height: 34,
+              borderRadius: "17px",
+              px: 1.5,
+              fontWeight: 800,
+              fontSize: "0.78rem",
+              textTransform: "none",
+              color: "text.secondary",
+              borderColor: alpha(theme.palette.text.secondary, 0.22),
+              bgcolor: alpha("#fff", 0.45),
+            }}
+          >
+            跳过
+          </Button>
+          <Button
+            size="small"
+            variant="contained"
+            disableElevation
+            disabled={!canSubmit || isSubmitting}
+            onClick={() => onReply(questionRequest.requestId, answers)}
+            startIcon={
+              isSubmitting ? (
+                <CircularProgress size={14} color="inherit" />
+              ) : (
+                <CheckCircleRounded fontSize="small" />
+              )
+            }
+            sx={{
+              minWidth: 104,
+              height: 34,
+              borderRadius: "17px",
+              bgcolor: "#0288d1",
+              fontWeight: 800,
+              fontSize: "0.78rem",
+              textTransform: "none",
+              boxShadow: `0 4px 12px ${alpha("#0288d1", 0.24)}`,
+              "&:hover": {
+                bgcolor: "#0277bd",
+                boxShadow: `0 6px 16px ${alpha("#0288d1", 0.28)}`,
+              },
+            }}
+          >
+            提交回答
+          </Button>
+        </Stack>
+      ) : null}
+    </Box>
+  );
+};
+
+export const QuestionRequestGroup = ({
+  questions,
+  onReply,
+  onReject,
+}: {
+  questions: NonNullable<Message["questions"]>;
+  onReply: (requestId: string, answers: string[][]) => void;
+  onReject: (requestId: string) => void;
+}) => (
+  <Stack spacing={1}>
+    {questions.map((question) => (
+      <QuestionRequestCard
+        key={question.requestId}
+        questionRequest={question}
+        onReply={onReply}
+        onReject={onReject}
+      />
+    ))}
+  </Stack>
+);
+
+

src/components/chat/AgentTodoPlanCard.tsx

@@ -0,0 +1,308 @@
+"use client";
+
+import React from "react";
+import {
+  Box,
+  Chip,
+  CircularProgress,
+  Collapse,
+  IconButton,
+  Stack,
+  Typography,
+  alpha,
+  useTheme,
+} from "@mui/material";
+import AssignmentTurnedInRounded from "@mui/icons-material/AssignmentTurnedInRounded";
+import CheckCircleRounded from "@mui/icons-material/CheckCircleRounded";
+import BlockRounded from "@mui/icons-material/BlockRounded";
+import KeyboardArrowDownRounded from "@mui/icons-material/KeyboardArrowDownRounded";
+import KeyboardArrowUpRounded from "@mui/icons-material/KeyboardArrowUpRounded";
+import RadioButtonUncheckedRounded from "@mui/icons-material/RadioButtonUncheckedRounded";
+
+import type { Message } from "./GlobalChatbox.types";
+
+export const TodoPlanCard = ({
+  todoUpdate,
+}: {
+  todoUpdate: NonNullable<Message["todos"]>;
+}) => {
+  const theme = useTheme();
+  const total = todoUpdate.todos.length;
+  const completed = todoUpdate.todos.filter((todo) => todo.status === "completed").length;
+  const running = todoUpdate.todos.find((todo) => todo.status === "in_progress");
+  const cancelled = todoUpdate.todos.filter((todo) => todo.status === "cancelled").length;
+  const pending = todoUpdate.todos.filter((todo) => todo.status === "pending").length;
+  const progress = total > 0 ? Math.round((completed / total) * 100) : 0;
+  const isAborted = cancelled > 0 && completed + cancelled === total;
+  const canCollapse = total > 4;
+  const [expanded, setExpanded] = React.useState(!canCollapse && !isAborted);
+  const pinnedTodos = canCollapse ? todoUpdate.todos.slice(0, 4) : todoUpdate.todos;
+  const collapsibleTodos = canCollapse ? todoUpdate.todos.slice(4) : [];
+  const hiddenCount = expanded ? 0 : collapsibleTodos.length;
+  const latestUpdatedAt = Math.max(
+    todoUpdate.createdAt,
+    ...todoUpdate.todos
+      .map((todo) => todo.updatedAt ?? todo.createdAt ?? 0)
+      .filter((value) => value > 0),
+  );
+  const updatedAtLabel =
+    latestUpdatedAt > 0
+      ? new Intl.DateTimeFormat("zh-CN", {
+          hour: "2-digit",
+          minute: "2-digit",
+        }).format(new Date(latestUpdatedAt))
+      : undefined;
+
+  const getTodoVisual = (status: NonNullable<Message["todos"]>["todos"][number]["status"]) => {
+    if (status === "completed") {
+      return { icon: <CheckCircleRounded sx={{ fontSize: 17 }} />, color: theme.palette.success.main, label: "完成" };
+    }
+    if (status === "in_progress") {
+      return { icon: <CircularProgress size={15} thickness={5} />, color: "#0288d1", label: "进行中" };
+    }
+    if (status === "cancelled") {
+      return { icon: <BlockRounded sx={{ fontSize: 17 }} />, color: theme.palette.text.disabled, label: "中止" };
+    }
+    return { icon: <RadioButtonUncheckedRounded sx={{ fontSize: 17 }} />, color: theme.palette.text.secondary, label: "待办" };
+  };
+
+  const getPriorityLabel = (priority: NonNullable<Message["todos"]>["todos"][number]["priority"]) => {
+    if (priority === "high") return { label: "高优先级", color: "#8a5a00" };
+    if (priority === "medium") return { label: "中优先级", color: "#9a6a16" };
+    if (priority === "low") return { label: "低优先级", color: "#8d7960" };
+    return undefined;
+  };
+
+  const statusSummary = isAborted
+    ? `${completed} 完成 / ${cancelled} 中止`
+    : [
+        completed ? `${completed} 完成` : null,
+        running ? "1 进行中" : null,
+        pending ? `${pending} 待办` : null,
+        cancelled ? `${cancelled} 中止` : null,
+      ].filter(Boolean).join(" / ") || "等待任务";
+  const renderTodoRow = (
+    todo: NonNullable<Message["todos"]>["todos"][number],
+    index: number,
+  ) => {
+    const visual = getTodoVisual(todo.status);
+    const priority = getPriorityLabel(todo.priority);
+    return (
+      <Stack
+        key={`${todo.id}-${index}`}
+        direction="row"
+        alignItems="flex-start"
+        spacing={1}
+        sx={{
+          py: 0.8,
+          borderTop: `1px solid ${alpha("#00838f", 0.08)}`,
+          color: todo.status === "cancelled" ? "text.disabled" : "text.primary",
+        }}
+      >
+        <Box
+          sx={{
+            width: 24,
+            height: 24,
+            borderRadius: 1.25,
+            display: "grid",
+            placeItems: "center",
+            flex: "0 0 auto",
+            color: visual.color,
+            bgcolor: alpha(visual.color, 0.08),
+            mt: 0.1,
+          }}
+        >
+          {visual.icon}
+        </Box>
+        <Box sx={{ minWidth: 0, flex: 1 }}>
+          <Typography
+            variant="body2"
+            sx={{
+              minWidth: 0,
+              wordBreak: "break-word",
+              lineHeight: 1.45,
+              textDecoration: todo.status === "cancelled" ? "line-through" : undefined,
+            }}
+          >
+            {todo.content}
+          </Typography>
+        </Box>
+        <Stack direction="row" spacing={0.5} sx={{ flex: "0 0 auto" }}>
+          {priority ? (
+            <Chip
+              size="small"
+              label={priority.label}
+              sx={{
+                height: 22,
+                borderRadius: "11px",
+                fontSize: "0.66rem",
+                fontWeight: 800,
+                color: priority.color,
+                bgcolor: alpha(priority.color, 0.045),
+                border: `1px solid ${alpha(priority.color, 0.16)}`,
+                "& .MuiChip-label": { px: 0.75 },
+              }}
+            />
+          ) : null}
+          <Chip
+            size="small"
+            label={visual.label}
+            sx={{
+              height: 22,
+              borderRadius: "11px",
+              fontSize: "0.66rem",
+              fontWeight: 800,
+              color: visual.color,
+              bgcolor: alpha(visual.color, 0.08),
+              "& .MuiChip-label": { px: 0.75 },
+            }}
+          />
+        </Stack>
+      </Stack>
+    );
+  };
+
+  if (total === 0) {
+    return null;
+  }
+
+  return (
+    <Box
+      sx={{
+        borderRadius: 2,
+        overflow: "hidden",
+        border: `1px solid ${alpha("#00838f", 0.16)}`,
+        bgcolor: alpha("#f8fbfc", 0.82),
+      }}
+    >
+      <Stack
+        spacing={1}
+        role="button"
+        tabIndex={0}
+        onClick={() => {
+          if (canCollapse) {
+            setExpanded((value) => !value);
+          }
+        }}
+        onKeyDown={(event) => {
+          if (canCollapse && (event.key === "Enter" || event.key === " ")) {
+            event.preventDefault();
+            setExpanded((value) => !value);
+          }
+        }}
+        sx={{
+          px: 1.4,
+          py: 1.15,
+          cursor: canCollapse ? "pointer" : "default",
+          transition: "background-color 0.2s ease",
+          "&:hover": canCollapse ? { bgcolor: alpha("#00838f", 0.035) } : undefined,
+        }}
+      >
+        <Stack direction="row" alignItems="center" spacing={1}>
+          <Box
+            sx={{
+              width: 28,
+              height: 28,
+              borderRadius: 1.5,
+              display: "grid",
+              placeItems: "center",
+              flex: "0 0 auto",
+              color: "#00838f",
+              bgcolor: alpha("#00838f", 0.1),
+              border: `1px solid ${alpha("#00838f", 0.14)}`,
+            }}
+          >
+            <AssignmentTurnedInRounded sx={{ fontSize: 18 }} />
+          </Box>
+          <Box sx={{ minWidth: 0, flex: 1 }}>
+            <Stack direction="row" alignItems="center" spacing={0.75}>
+              <Typography variant="subtitle2" fontWeight={800} noWrap sx={{ lineHeight: 1.25 }}>
+                会话任务
+              </Typography>
+              <Chip
+                size="small"
+                label={running ? "执行中" : isAborted ? "已中止" : completed === total ? "已完成" : "已同步"}
+                sx={{
+                  height: 20,
+                  borderRadius: "10px",
+                  fontSize: "0.66rem",
+                  fontWeight: 800,
+                  color: running ? "#0277bd" : isAborted ? "text.secondary" : "#00838f",
+                  bgcolor: alpha(running ? "#0288d1" : isAborted ? "#64748b" : "#00838f", 0.08),
+                  "& .MuiChip-label": { px: 0.75 },
+                }}
+              />
+            </Stack>
+            <Typography variant="caption" color="text.secondary">
+              {statusSummary}{updatedAtLabel ? ` · ${updatedAtLabel} 更新` : ""}
+            </Typography>
+          </Box>
+          {canCollapse ? (
+            <IconButton
+              size="small"
+              aria-label={expanded ? "收起会话任务" : "展开会话任务"}
+              sx={{
+                width: 28,
+                height: 28,
+                color: "text.secondary",
+                bgcolor: alpha("#000", 0.035),
+                "&:hover": { bgcolor: alpha("#000", 0.07) },
+              }}
+            >
+              {expanded ? (
+                <KeyboardArrowUpRounded sx={{ fontSize: 18 }} />
+              ) : (
+                <KeyboardArrowDownRounded sx={{ fontSize: 18 }} />
+              )}
+            </IconButton>
+          ) : null}
+        </Stack>
+        <Box
+          sx={{
+            height: 6,
+            borderRadius: 999,
+            overflow: "hidden",
+            bgcolor: alpha("#00838f", 0.1),
+          }}
+        >
+          <Box
+            sx={{
+              width: `${progress}%`,
+              height: "100%",
+              borderRadius: 999,
+              bgcolor: isAborted ? theme.palette.text.disabled : "#00838f",
+              transition: "width 0.25s ease",
+            }}
+          />
+        </Box>
+      </Stack>
+
+      <Stack spacing={0} sx={{ px: 1.4, pb: 1.1 }}>
+        {pinnedTodos.map((todo, index) => renderTodoRow(todo, index))}
+        {canCollapse ? (
+          <Collapse in={expanded} timeout={220} unmountOnExit={false}>
+            <Stack spacing={0}>
+              {collapsibleTodos.map((todo, index) =>
+                renderTodoRow(todo, index + pinnedTodos.length),
+              )}
+            </Stack>
+          </Collapse>
+        ) : null}
+        {hiddenCount > 0 ? (
+          <Typography
+            variant="caption"
+            color="text.secondary"
+            sx={{
+              pt: 0.8,
+              borderTop: `1px solid ${alpha("#00838f", 0.08)}`,
+            }}
+          >
+            还有 {hiddenCount} 项，展开查看全部
+          </Typography>
+        ) : null}
+      </Stack>
+    </Box>
+  );
+};
+
+

src/components/chat/AgentTurn.test.tsx

@@ -0,0 +1,167 @@
+/* eslint-disable @next/next/no-img-element */
+import "@testing-library/jest-dom";
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+
+import { AgentTurn } from "./AgentTurn";
+
+jest.mock("next/image", () => ({
+  __esModule: true,
+  default: (props: React.ImgHTMLAttributes<HTMLImageElement>) => (
+    <img {...props} alt={props.alt ?? ""} />
+  ),
+}));
+
+jest.mock("framer-motion", () => ({
+  AnimatePresence: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  motion: {
+    div: ({
+      children,
+      animate: _animate,
+      exit: _exit,
+      initial: _initial,
+      transition: _transition,
+      ...props
+    }: React.HTMLAttributes<HTMLDivElement> & Record<string, unknown>) => (
+      <div {...props}>{children}</div>
+    ),
+    span: ({
+      children,
+      animate: _animate,
+      transition: _transition,
+      ...props
+    }: React.HTMLAttributes<HTMLSpanElement> & Record<string, unknown>) => (
+      <span {...props}>{children}</span>
+    ),
+  },
+}));
+
+jest.mock("./AgentMarkdownBlock", () => ({
+  MarkdownBlock: ({ children }: { children: string }) => (
+    <div>{children.split(/\n+/u).map((line) => <p key={line}>{line}</p>)}</div>
+  ),
+  normalizeClipboardText: (value: string) => value.replace(/\s+$/u, ""),
+}));
+
+describe("AgentTurn speech selection", () => {
+  it("shows a floating action and reads from the selected text", async () => {
+    const content = "第一段内容。\n\n第二段内容。";
+    const speechText = "第一段内容。\n第二段内容。";
+    const onSpeak = jest.fn();
+    const removeAllRanges = jest.fn();
+
+    render(
+      <AgentTurn
+        message={{ id: "assistant-1", role: "assistant", content }}
+        isStreaming={false}
+        messageSpeechState="idle"
+        onSpeak={onSpeak}
+        onPause={jest.fn()}
+        onResume={jest.fn()}
+        onStopSpeech={jest.fn()}
+        isTtsSupported
+        onCreateBranch={jest.fn()}
+        onReplyPermission={jest.fn()}
+        onReplyQuestion={jest.fn()}
+        onRejectQuestion={jest.fn()}
+      />,
+    );
+
+    const selectedParagraph = screen.getByText("第二段内容。");
+    const selectedTextNode = selectedParagraph.firstChild as Text;
+    const range = {
+      commonAncestorContainer: selectedTextNode,
+      getBoundingClientRect: () => ({
+        width: 72,
+        height: 20,
+        top: 120,
+        right: 172,
+        bottom: 140,
+        left: 100,
+        x: 100,
+        y: 120,
+        toJSON: () => ({}),
+      }),
+    } as unknown as Range;
+    const selection = {
+      rangeCount: 1,
+      isCollapsed: false,
+      getRangeAt: () => range,
+      toString: () => "第二段",
+      removeAllRanges,
+    } as unknown as Selection;
+
+    jest.spyOn(window, "getSelection").mockReturnValue(selection);
+    jest.spyOn(window, "requestAnimationFrame").mockImplementation((callback) => {
+      callback(0);
+      return 1;
+    });
+
+    fireEvent.pointerUp(selectedParagraph);
+
+    const speechAction = await screen.findByRole("button", { name: "从这里开始朗读" });
+    fireEvent.click(speechAction);
+
+    await waitFor(() => {
+      expect(onSpeak).toHaveBeenCalledWith("assistant-1", speechText, {
+        startOffset: speechText.indexOf("第二段"),
+      });
+    });
+    expect(removeAllRanges).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(screen.queryByRole("button", { name: "从这里开始朗读" })).not.toBeInTheDocument();
+    });
+  });
+
+  it("offers one-time and saved permission approval with distinct actions", () => {
+    const onReplyPermission = jest.fn();
+    render(
+      <AgentTurn
+        message={{
+          id: "assistant-permission",
+          role: "assistant",
+          content: "",
+          progress: [
+            {
+              id: "permission-progress",
+              phase: "permission",
+              status: "running",
+              title: "等待权限确认",
+            },
+          ],
+          permissions: [
+            {
+              requestId: "permission-1",
+              sessionId: "session-1",
+              permission: "bash",
+              patterns: ["npm test"],
+              target: "npm test",
+              always: ["npm test"],
+              createdAt: 1,
+              status: "pending",
+            },
+          ],
+        }}
+        isStreaming
+        messageSpeechState="idle"
+        onSpeak={jest.fn()}
+        onPause={jest.fn()}
+        onResume={jest.fn()}
+        onStopSpeech={jest.fn()}
+        isTtsSupported
+        onCreateBranch={jest.fn()}
+        onReplyPermission={onReplyPermission}
+        onReplyQuestion={jest.fn()}
+        onRejectQuestion={jest.fn()}
+      />,
+    );
+
+    expect(screen.getByRole("button", { name: "允许一次" })).toBeInTheDocument();
+    expect(screen.getByText("保存授权范围")).toBeInTheDocument();
+    expect(screen.getAllByText("npm test")).toHaveLength(2);
+    expect(screen.getByTestId("GppGoodRoundedIcon")).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "保存授权" }));
+    expect(onReplyPermission).toHaveBeenCalledWith("permission-1", "always");
+    expect(screen.getByRole("button", { name: "拒绝" })).toBeInTheDocument();
+  });
+});

src/components/chat/AgentTurn.tsx

@@ -1,16 +1,17 @@
 "use client";
 
 import Image from "next/image";
-import React from "react";
-import ReactMarkdown from "react-markdown";
-import remarkGfm from "remark-gfm";
-import { AnimatePresence, motion } from "framer-motion";
+import React, { useMemo } from "react";
+import { motion } from "framer-motion";
 import {
   Avatar,
   Box,
+  CircularProgress,
   Button,
+  Grow,
   IconButton,
   Paper,
+  Popper,
   Stack,
   Tooltip,
   Typography,
@@ -18,82 +19,340 @@ import {
   useTheme,
 } from "@mui/material";
 import ContentCopyRounded from "@mui/icons-material/ContentCopyRounded";
-import RefreshRounded from "@mui/icons-material/RefreshRounded";
-import EditRounded from "@mui/icons-material/EditRounded";
-import CloseRounded from "@mui/icons-material/CloseRounded";
-import ChevronLeftRounded from "@mui/icons-material/ChevronLeftRounded";
-import ChevronRightRounded from "@mui/icons-material/ChevronRightRounded";
+import { TbArrowsSplit2 } from "react-icons/tb";
+import type { PermissionDecision } from "@/lib/chatStream";
 import {
   parseAssistantMessageSections,
   parseContentWithToolCalls,
   type ContentSegment,
 } from "./chatMessageSections";
-import markdownStyles from "./GlobalChatboxMarkdown.module.css";
-import type { BranchState, Message, SpeechState } from "./GlobalChatbox.types";
-import { stripMarkdown } from "./GlobalChatbox.utils";
+import type {
+  Message,
+  SpeechState,
+} from "./GlobalChatbox.types";
+import { stripMarkdown } from "./globalChatboxUtils";
+import { findSpeechSelectionStartOffset } from "./speechStartOptions";
 import { AgentProgressTimeline } from "./AgentProgressTimeline";
-import { ChatInlineChart } from "./ChatInlineChart";
-import type { ChatChartSeries } from "./ChatInlineChart";
+import { ChartGenerationSkeleton, ChatInlineChart } from "./ChatInlineChart";
 import { ChatToolCallBlock } from "./ChatToolCallBlock";
-import { AgentArtifactPanel } from "./AgentArtifactPanel";
-import ErrorOutlineRounded from "@mui/icons-material/ErrorOutlineRounded";
+import { MarkdownBlock, normalizeClipboardText } from "./AgentMarkdownBlock";
+import { PermissionRequestGroup } from "./AgentPermissionRequests";
+import { QuestionRequestGroup } from "./AgentQuestionRequests";
+import { TodoPlanCard } from "./AgentTodoPlanCard";
 import VolumeUpRounded from "@mui/icons-material/VolumeUpRounded";
 import PauseRounded from "@mui/icons-material/PauseRounded";
 import PlayArrowRounded from "@mui/icons-material/PlayArrowRounded";
 import StopRounded from "@mui/icons-material/StopRounded";
-import SendRounded from "@mui/icons-material/SendRounded";
+
+const floatingActionSurfaceSx = {
+  display: "flex",
+  gap: 0.5,
+  p: 0.5,
+  borderRadius: "16px",
+  bgcolor: alpha("#fff", 0.8),
+  backdropFilter: "blur(16px)",
+  border: `1px solid ${alpha("#fff", 0.9)}`,
+  boxShadow: `0 4px 12px ${alpha("#000", 0.08)}`,
+  overflow: "hidden",
+} as const;
+
+const floatingActionTransitionTimeout = { enter: 150, exit: 120 } as const;
+const floatingIconButtonSx = {
+  width: 28,
+  height: 28,
+  color: "text.secondary",
+  "&:hover": {
+    color: "#00acc1",
+    bgcolor: alpha("#00acc1", 0.1),
+  },
+} as const;
+const floatingSpeechButtonSx = {
+  minHeight: 34,
+  px: 1.25,
+  color: "text.primary",
+  fontSize: 13,
+  fontWeight: 700,
+  letterSpacing: 0,
+  whiteSpace: "nowrap",
+  borderRadius: "12px",
+  "&:hover": {
+    bgcolor: alpha("#00acc1", 0.1),
+    color: "#00acc1",
+  },
+} as const;
+
+type SpeechSelection = {
+  startOffset: number;
+  anchorRect: DOMRect;
+};
 
 type AgentTurnProps = {
   message: Message;
-  branchState?: BranchState;
+  isStreaming: boolean;
   messageSpeechState: SpeechState;
-  onSpeak: (messageId: string, text: string) => void;
+  onSpeak: (
+    messageId: string,
+    text: string,
+    options?: { startOffset?: number },
+  ) => void;
   onPause: () => void;
   onResume: () => void;
   onStopSpeech: () => void;
   isTtsSupported: boolean;
-  onRegenerate: () => void;
-  onEditResubmit: (messageId: string, newContent: string) => void;
-  onCycleBranch: (rootMessageId: string, direction: -1 | 1) => void;
+  onCreateBranch: (messageId: string) => void;
+  onReplyPermission: (requestId: string, reply: PermissionDecision) => void;
+  onReplyQuestion: (requestId: string, answers: string[][]) => void;
+  onRejectQuestion: (requestId: string) => void;
 };
 
-const MarkdownBlock = ({ children }: { children: string }) => (
-  <div className={markdownStyles.markdown}>
-    <ReactMarkdown remarkPlugins={[remarkGfm]}>{children}</ReactMarkdown>
-  </div>
-);
+const StreamingStatus = () => {
+  const theme = useTheme();
+
+  return (
+    <Stack
+      direction="row"
+      spacing={0.75}
+      alignItems="center"
+      sx={{
+        px: 1,
+        py: 0.35,
+        borderRadius: 999,
+        bgcolor: alpha(theme.palette.primary.main, 0.07),
+        color: "text.secondary",
+      }}
+    >
+      <Stack direction="row" spacing={0.35} alignItems="center">
+        {[0, 1, 2].map((index) => (
+          <motion.span
+            key={index}
+            animate={{ opacity: [0.28, 0.86, 0.28] }}
+            transition={{
+              duration: 0.95,
+              repeat: Infinity,
+              delay: index * 0.14,
+              ease: "easeInOut",
+            }}
+            style={{
+              width: 4,
+              height: 4,
+              borderRadius: "50%",
+              background: theme.palette.primary.main,
+              display: "block",
+            }}
+          />
+        ))}
+      </Stack>
+      <Typography variant="caption" color="text.secondary" fontWeight={700}>
+        正在生成
+      </Typography>
+    </Stack>
+  );
+};
+
+const StreamingMarkdownBlock = ({
+  text,
+  isStreaming,
+  segmentKey,
+}: {
+  text: string;
+  isStreaming: boolean;
+  segmentKey: string;
+}) => {
+  const [streamTextState, setStreamTextState] = React.useState<{
+    displayText: string;
+    animatedTailLength: number;
+  }>({
+    displayText: text,
+    animatedTailLength: 0,
+  });
+
+  React.useLayoutEffect(() => {
+    setStreamTextState((current) => {
+      if (current.displayText === text) {
+        return current;
+      }
+
+      if (!isStreaming) {
+        return {
+          displayText: text,
+          animatedTailLength: 0,
+        };
+      }
+
+      if (current.displayText === text) {
+        return current;
+      }
+
+      return {
+        displayText: text,
+        animatedTailLength:
+          text.length > current.displayText.length &&
+          text.startsWith(current.displayText)
+            ? Math.min(48, text.length - current.displayText.length)
+            : 0,
+      };
+    });
+  }, [isStreaming, text]);
+
+  return (
+    <MarkdownBlock
+      streamFadeKey={`${segmentKey}-${streamTextState.displayText.length}`}
+      streamFadeLength={streamTextState.animatedTailLength}
+    >
+      {streamTextState.displayText}
+    </MarkdownBlock>
+  );
+};
 
 export const AgentTurn = React.memo(
   ({
     message,
-    branchState,
+    isStreaming,
     messageSpeechState,
     onSpeak,
     onPause,
     onResume,
     onStopSpeech,
     isTtsSupported,
-    onRegenerate,
-    onEditResubmit,
-    onCycleBranch,
+    onCreateBranch,
+    onReplyPermission,
+    onReplyQuestion,
+    onRejectQuestion,
   }: AgentTurnProps) => {
     const theme = useTheme();
     const isUser = message.role === "user";
     const isErrorMessage = Boolean(message.isError);
+    const isStreamingAssistant = !isUser && !isErrorMessage && isStreaming;
     const [isHovered, setIsHovered] = React.useState(false);
-    const [isEditing, setIsEditing] = React.useState(false);
-    const [editDraft, setEditDraft] = React.useState(message.content);
-    const rootMessageId = message.branchRootId ?? message.id;
+    const answerContentRef = React.useRef<HTMLDivElement | null>(null);
+    const [speechSelection, setSpeechSelection] = React.useState<SpeechSelection | null>(null);
+    const isProgressComplete = message.progress?.some(
+      (item) => item.phase === "complete" && item.status === "completed",
+    ) ?? false;
+    const isProgressRunning = !isErrorMessage && !isProgressComplete && (
+      message.progress?.some((item) => item.status === "running") ?? false
+    );
 
-    const parsedAssistantSections =
-      !isUser && !isErrorMessage
-        ? parseAssistantMessageSections(message.content)
-        : null;
+    const parsedAssistantSections = useMemo(
+      () =>
+        !isUser && !isErrorMessage
+          ? parseAssistantMessageSections(message.content)
+          : null,
+      [isErrorMessage, isUser, message.content],
+    );
     const answerContent = parsedAssistantSections?.answer ?? message.content;
-    const contentSegments: ContentSegment[] =
-      !isUser && !isErrorMessage
-        ? parseContentWithToolCalls(answerContent).segments
-        : [{ type: "text", content: answerContent }];
+    const speechText = useMemo(
+      () => stripMarkdown(answerContent),
+      [answerContent],
+    );
+    const captureSpeechSelection = React.useCallback(() => {
+      if (!isTtsSupported || isStreamingAssistant) {
+        setSpeechSelection(null);
+        return;
+      }
+
+      const selection = window.getSelection();
+      const container = answerContentRef.current;
+      if (!selection || selection.rangeCount === 0 || selection.isCollapsed || !container) {
+        setSpeechSelection(null);
+        return;
+      }
+
+      const range = selection.getRangeAt(0);
+      if (!container.contains(range.commonAncestorContainer)) {
+        setSpeechSelection(null);
+        return;
+      }
+
+      const selectedText = selection.toString();
+      const startOffset = findSpeechSelectionStartOffset(speechText, selectedText);
+      if (startOffset === null) {
+        setSpeechSelection(null);
+        return;
+      }
+
+      const anchorRect = range.getBoundingClientRect();
+      if (anchorRect.width === 0 && anchorRect.height === 0) {
+        setSpeechSelection(null);
+        return;
+      }
+
+      setSpeechSelection({ startOffset, anchorRect });
+    }, [isStreamingAssistant, isTtsSupported, speechText]);
+    const handleCaptureSpeechSelection = React.useCallback(() => {
+      window.requestAnimationFrame(captureSpeechSelection);
+    }, [captureSpeechSelection]);
+    React.useEffect(() => {
+      setSpeechSelection(null);
+    }, [message.id, speechText]);
+    React.useEffect(() => {
+      if (!speechSelection) return;
+
+      const closeSpeechSelection = () => setSpeechSelection(null);
+      const handleSelectionChange = () => {
+        if (window.getSelection()?.isCollapsed) {
+          closeSpeechSelection();
+        }
+      };
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (event.key === "Escape") {
+          closeSpeechSelection();
+        }
+      };
+
+      document.addEventListener("selectionchange", handleSelectionChange);
+      document.addEventListener("keydown", handleKeyDown);
+      window.addEventListener("resize", closeSpeechSelection);
+      window.addEventListener("scroll", closeSpeechSelection, true);
+
+      return () => {
+        document.removeEventListener("selectionchange", handleSelectionChange);
+        document.removeEventListener("keydown", handleKeyDown);
+        window.removeEventListener("resize", closeSpeechSelection);
+        window.removeEventListener("scroll", closeSpeechSelection, true);
+      };
+    }, [speechSelection]);
+    const handleSpeakMessage = () => {
+      onSpeak(message.id, speechText);
+    };
+    const handleSpeakFromSelection = () => {
+      if (!speechSelection) return;
+
+      onSpeak(message.id, speechText, {
+        startOffset: speechSelection.startOffset,
+      });
+      window.getSelection()?.removeAllRanges();
+      setSpeechSelection(null);
+    };
+    const speechSelectionAnchor = React.useMemo(
+      () => speechSelection
+        ? {
+            getBoundingClientRect: () => speechSelection.anchorRect,
+          }
+        : null,
+      [speechSelection],
+    );
+    const isSpeechSelectionOpen = Boolean(speechSelection);
+    const contentSegments: ContentSegment[] = useMemo(
+      () =>
+        !isUser && !isErrorMessage
+          ? parseContentWithToolCalls(answerContent).segments
+          : [{ type: "text", content: answerContent }],
+      [answerContent, isErrorMessage, isUser],
+    );
+    const hasInlineChart = contentSegments.some(
+      (segment) =>
+        segment.type === "tool_call" &&
+        (segment.toolCall.tool === "chart" ||
+          segment.toolCall.tool === "show_chart"),
+    );
+    const visibleChartArtifacts = useMemo(
+      () =>
+        hasInlineChart
+          ? []
+          : (message.artifacts?.filter((artifact) => artifact.kind === "chart") ?? []),
+      [hasInlineChart, message.artifacts],
+    );
     
     if (isUser) {
       return (
@@ -106,185 +365,33 @@ export const AgentTurn = React.memo(
           onMouseEnter={() => setIsHovered(true)}
           onMouseLeave={() => setIsHovered(false)}
         >
-          {isEditing ? (
-            <Paper
-              elevation={12}
-              sx={{
-                p: 1.5,
-                borderRadius: 5,
-                bgcolor: alpha("#ffffff", 0.75),
-                backdropFilter: "blur(40px)",
-                border: `1px solid ${alpha("#ffffff", 0.9)}`,
-                boxShadow: `0 16px 40px ${alpha("#000", 0.1)}, 0 0 0 1px ${alpha("#00acc1", 0.05)} inset`,
-                minWidth: { xs: 260, sm: 320, md: 400 },
-                maxWidth: "100%",
-              }}
-            >
-              <Box component="textarea"
-                autoFocus
-                value={editDraft}
-                onChange={(e) => setEditDraft(e.target.value)}
-                onKeyDown={(e) => {
-                  if (e.key === "Enter" && !e.shiftKey) {
-                    e.preventDefault();
-                    if (editDraft.trim() !== message.content) {
-                      onEditResubmit(message.id, editDraft);
-                    }
-                    setIsEditing(false);
-                  } else if (e.key === "Escape") {
-                    setEditDraft(message.content);
-                    setIsEditing(false);
-                  }
-                }}
-                sx={{
-                  width: "100%",
-                  minHeight: 60,
-                  bgcolor: "transparent",
-                  border: "none",
-                  outline: "none",
-                  resize: "none",
-                  fontFamily: "inherit",
-                  fontSize: "1rem",
-                  color: "text.primary",
-                  lineHeight: 1.6,
-                }}
-              />
-              <Stack direction="row" justifyContent="flex-end" spacing={1} sx={{ mt: 1 }}>
-                <IconButton 
-                  size="small" 
-                  aria-label="取消"
-                  onClick={() => { setEditDraft(message.content); setIsEditing(false); }}
-                  sx={{ 
-                    bgcolor: alpha("#000", 0.05), 
-                    color: "text.secondary",
-                    width: 34, height: 34,
-                    "&:hover": { bgcolor: alpha("#000", 0.1) }
-                  }}
-                >
-                  <CloseRounded fontSize="small" />
-                </IconButton>
-                <IconButton 
-                  size="small" 
-                  aria-label="发送修改"
-                  disabled={editDraft.trim() === "" || editDraft.trim() === message.content}
-                  onClick={() => {
-                    onEditResubmit(message.id, editDraft);
-                    setIsEditing(false);
-                  }}
-                  sx={{ 
-                    bgcolor: editDraft.trim() !== "" && editDraft.trim() !== message.content ? "#00acc1" : alpha("#000", 0.1), 
-                    color: editDraft.trim() !== "" && editDraft.trim() !== message.content ? "#fff" : "action.disabled",
-                    width: 34, height: 34,
-                    boxShadow: editDraft.trim() !== "" && editDraft.trim() !== message.content ? `0 4px 12px ${alpha("#00acc1", 0.4)}` : "none",
-                    "&:hover": { bgcolor: editDraft.trim() !== "" && editDraft.trim() !== message.content ? "#00838f" : alpha("#000", 0.1) }
-                  }}
-                >
-                  <SendRounded fontSize="small" sx={{ ml: 0.2 }} />
-                </IconButton>
-              </Stack>
-            </Paper>
-          ) : (
-            <>
-              <Paper
-                elevation={4}
-                sx={{
-                  p: 2,
-                  borderRadius: 5,
-                  borderBottomRightRadius: 2,
-                  color: "#fff",
-                  background: `linear-gradient(135deg, #0288d1, #00acc1)`,
-                  boxShadow: `0 8px 24px -8px ${alpha("#00acc1", 0.5)}, inset 0 2px 4px ${alpha("#fff", 0.2)}`,
-                  backdropFilter: "blur(10px)",
-                  "--chat-md-text": alpha("#fff", 0.96),
-                  "--chat-md-heading": "#fff",
-                  "--chat-md-link": "#e0f7fa",
-                  "--chat-md-link-hover": "#fff",
-                  "--chat-md-inline-code-bg": "rgba(255,255,255,0.15)",
-                  "--chat-md-inline-code-border": alpha("#fff", 0.1),
-                  "--chat-md-inline-code-text": "#fff",
-                  "--chat-md-pre-bg": "rgba(0, 0, 0, 0.25)",
-                  "--chat-md-pre-border": alpha("#fff", 0.1),
-                  "--chat-md-pre-text": "#F8FAFC",
-                  "--chat-md-quote-border": alpha("#fff", 0.4),
-                  "--chat-md-quote-bg": alpha("#fff", 0.05),
-                  "--chat-md-quote-text": alpha("#fff", 0.8),
-                }}
-              >
-                <MarkdownBlock>{message.content}</MarkdownBlock>
-                
-                <AnimatePresence>
-                  {isHovered && !isEditing && (
-                    <motion.div
-                      initial={{ opacity: 0, scale: 0.9 }}
-                      animate={{ opacity: 1, scale: 1 }}
-                      exit={{ opacity: 0, scale: 0.9 }}
-                      transition={{ duration: 0.15 }}
-                      style={{ position: "absolute", top: -12, right: -8, zIndex: 10 }}
-                    >
-                      <IconButton
-                        size="small"
-                        onClick={() => { setIsEditing(true); setEditDraft(message.content); }}
-                        aria-label="编辑提问"
-                        sx={{
-                          width: 26,
-                          height: 26,
-                          bgcolor: alpha("#fff", 0.9),
-                          color: "#00acc1",
-                          boxShadow: `0 2px 8px ${alpha("#000", 0.15)}`,
-                          "&:hover": { bgcolor: "#fff", color: "#00838f" }
-                        }}
-                      >
-                        <EditRounded sx={{ fontSize: 14 }} />
-                      </IconButton>
-                    </motion.div>
-                  )}
-                </AnimatePresence>
-              </Paper>
-
-              {branchState && branchState.total > 1 ? (
-                <Stack
-                  direction="row"
-                  justifyContent="flex-end"
-                  sx={{ mt: 0.5, mr: 0.5 }}
-                >
-                  <Paper
-                    elevation={0}
-                    sx={{
-                      display: "flex",
-                      alignItems: "center",
-                      gap: 0.5,
-                      px: 0.5,
-                      py: 0.25,
-                      borderRadius: 4,
-                      bgcolor: alpha("#000", 0.04),
-                      backdropFilter: "blur(4px)",
-                      border: `1px solid ${alpha("#000", 0.08)}`,
-                    }}
-                  >
-                    <IconButton
-                      size="small"
-                      aria-label="上一分支"
-                      onClick={() => onCycleBranch(rootMessageId, -1)}
-                      sx={{ width: 22, height: 22, color: "text.secondary", "&:hover": { bgcolor: alpha("#000", 0.08) } }}
-                    >
-                      <ChevronLeftRounded sx={{ fontSize: 16 }} />
-                    </IconButton>
-                    <Typography variant="caption" sx={{ color: "text.secondary", fontWeight: 600, fontSize: "0.7rem", px: 0.5, userSelect: "none" }}>
-                      {branchState.activeIndex + 1} / {branchState.total}
-                    </Typography>
-                    <IconButton
-                      size="small"
-                      aria-label="下一分支"
-                      onClick={() => onCycleBranch(rootMessageId, 1)}
-                      sx={{ width: 22, height: 22, color: "text.secondary", "&:hover": { bgcolor: alpha("#000", 0.08) } }}
-                    >
-                      <ChevronRightRounded sx={{ fontSize: 16 }} />
-                    </IconButton>
-                  </Paper>
-                </Stack>
-              ) : null}
-            </>
-          )}
+          <Paper
+            elevation={4}
+            sx={{
+              p: 2,
+              borderRadius: 5,
+              borderBottomRightRadius: 2,
+              color: "#fff",
+              background: `linear-gradient(135deg, #0288d1, #00acc1)`,
+              boxShadow: `0 8px 24px -8px ${alpha("#00acc1", 0.5)}, inset 0 2px 4px ${alpha("#fff", 0.2)}`,
+              backdropFilter: "blur(10px)",
+              "--chat-md-text": alpha("#fff", 0.96),
+              "--chat-md-heading": "#fff",
+              "--chat-md-link": "#e0f7fa",
+              "--chat-md-link-hover": "#fff",
+              "--chat-md-inline-code-bg": "rgba(255,255,255,0.15)",
+              "--chat-md-inline-code-border": alpha("#fff", 0.1),
+              "--chat-md-inline-code-text": "#fff",
+              "--chat-md-pre-bg": "rgba(0, 0, 0, 0.25)",
+              "--chat-md-pre-border": alpha("#fff", 0.1),
+              "--chat-md-pre-text": "#F8FAFC",
+              "--chat-md-quote-border": alpha("#fff", 0.4),
+              "--chat-md-quote-bg": alpha("#fff", 0.05),
+              "--chat-md-quote-text": alpha("#fff", 0.8),
+            }}
+          >
+            <MarkdownBlock>{message.content}</MarkdownBlock>
+          </Paper>
         </motion.div>
       );
     }
@@ -353,23 +460,57 @@ export const AgentTurn = React.memo(
                 <AgentProgressTimeline progress={message.progress} isAborted={isErrorMessage} />
               ) : null}
 
+              {message.permissions?.length ? (
+                <PermissionRequestGroup
+                  permissions={message.permissions}
+                  isRunning={isProgressRunning}
+                  onReply={onReplyPermission}
+                />
+              ) : null}
+
+              {message.questions?.length ? (
+                <QuestionRequestGroup
+                  questions={message.questions}
+                  onReply={onReplyQuestion}
+                  onReject={onRejectQuestion}
+                />
+              ) : null}
+
+              {message.todos ? (
+                <TodoPlanCard todoUpdate={message.todos} />
+              ) : null}
+
               <Box
+                ref={answerContentRef}
+                onPointerUp={handleCaptureSpeechSelection}
+                onKeyUp={handleCaptureSpeechSelection}
                 sx={{
                   p: 1.5,
                   borderRadius: 4,
                   bgcolor: alpha("#fff", 0.4),
                   border: `1px solid ${alpha("#fff", 0.6)}`,
+                  position: "relative",
                 }}
               >
                 <Stack spacing={1.2}>
-                  <Typography variant="caption" color="text.secondary" fontWeight={800} sx={{ letterSpacing: 0.5 }}>
-                    分析结果
-                  </Typography>
+                  <Stack direction="row" alignItems="center" justifyContent="space-between" spacing={1}>
+                    <Typography variant="caption" color="text.secondary" fontWeight={800} sx={{ letterSpacing: 0.5 }}>
+                      分析结果
+                    </Typography>
+                    {isStreamingAssistant ? <StreamingStatus /> : null}
+                  </Stack>
                   {contentSegments.map((segment, segIdx) => {
                     if (segment.type === "text") {
                       const text = segment.content.trim();
                       if (!text && contentSegments.length > 1) return null;
-                      return <MarkdownBlock key={segIdx}>{text || "..."}</MarkdownBlock>;
+                      return (
+                        <StreamingMarkdownBlock
+                          key={segIdx}
+                          text={text || "..."}
+                          isStreaming={isStreamingAssistant}
+                          segmentKey={`${message.id}-${segIdx}`}
+                        />
+                      );
                     }
                     if (segment.type === "tool_call") {
                       if (
@@ -384,10 +525,11 @@ export const AgentTurn = React.memo(
                             chart_type={
                               (p.chart_type as "line" | "bar" | "pie") ?? "line"
                             }
-                            x_data={(p.x_data as string[]) ?? []}
-                            series={(p.series as ChatChartSeries[]) ?? []}
+                            x_data={p.x_data ?? p.xData ?? p.labels ?? p.categories}
+                            series={p.series}
                             x_axis_name={(p.x_axis_name as string) ?? undefined}
                             y_axis_name={(p.y_axis_name as string) ?? undefined}
+                            isStreaming={isStreamingAssistant}
                           />
                         );
                       }
@@ -400,153 +542,172 @@ export const AgentTurn = React.memo(
                     }
                     if (segment.type === "tool_call_pending") {
                       return (
-                        <Typography key="tool-pending" variant="caption" color="text.secondary">
-                          正在准备工具调用...
-                        </Typography>
+                        <ChartGenerationSkeleton
+                          key="tool-pending"
+                          status={<StreamingStatus />}
+                        />
                       );
                     }
                     return null;
                   })}
                 </Stack>
               </Box>
-            </Stack>
 
-            <AnimatePresence>
-              {isHovered && (
-                <motion.div
-                  initial={{ opacity: 0, scale: 0.9, y: 5 }}
-                  animate={{ opacity: 1, scale: 1, y: 0 }}
-                  exit={{ opacity: 0, scale: 0.9, y: 5 }}
-                  transition={{ duration: 0.15 }}
-                  style={{ position: "absolute", top: -14, right: 12, zIndex: 10 }}
-                >
-                  <Paper
-                    elevation={4}
-                    sx={{
-                      display: "flex",
-                      gap: 0.5,
-                      p: 0.5,
-                      borderRadius: "16px",
-                      bgcolor: alpha("#fff", 0.8),
-                      backdropFilter: "blur(16px)",
-                      border: `1px solid ${alpha("#fff", 0.9)}`,
-                      boxShadow: `0 4px 12px ${alpha("#000", 0.08)}`,
+              <Popper
+                open={isSpeechSelectionOpen}
+                anchorEl={speechSelectionAnchor}
+                placement="top"
+                transition
+                modifiers={[
+                  { name: "offset", options: { offset: [0, 8] } },
+                  { name: "flip", enabled: true },
+                  { name: "preventOverflow", options: { padding: 8 } },
+                ]}
+                sx={{ zIndex: theme.zIndex.tooltip }}
+              >
+                {({ TransitionProps, placement }) => (
+                  <Grow
+                    {...TransitionProps}
+                    timeout={floatingActionTransitionTimeout}
+                    style={{
+                      transformOrigin: placement.startsWith("bottom")
+                        ? "center top"
+                        : "center bottom",
                     }}
                   >
-                    <Tooltip title="复制">
-                      <IconButton 
-                        size="small" 
-                        aria-label="复制" 
-                        onClick={() => {
-                          navigator.clipboard.writeText(message.content);
-                          // Could add a toast here
-                        }}
-                        sx={{ width: 28, height: 28, color: "text.secondary", "&:hover": { color: "#00acc1", bgcolor: alpha("#00acc1", 0.1) } }}
+                    <Paper elevation={4} sx={floatingActionSurfaceSx}>
+                      <Button
+                        size="small"
+                        startIcon={<VolumeUpRounded sx={{ fontSize: 16 }} />}
+                        onMouseDown={(event) => event.preventDefault()}
+                        onClick={handleSpeakFromSelection}
+                        sx={floatingSpeechButtonSx}
                       >
-                        <ContentCopyRounded sx={{ fontSize: 16 }} />
-                      </IconButton>
-                    </Tooltip>
-                    <Tooltip title="重新生成">
-                      <IconButton 
-                        size="small" 
-                        aria-label="重新生成" 
-                        onClick={() => {
-                          onRegenerate();
-                        }}
-                        sx={{ width: 28, height: 28, color: "text.secondary", "&:hover": { color: "#00acc1", bgcolor: alpha("#00acc1", 0.1) } }}
-                      >
-                        <RefreshRounded sx={{ fontSize: 16 }} />
-                      </IconButton>
-                    </Tooltip>
-                  </Paper>
-                </motion.div>
-              )}
-            </AnimatePresence>
+                        从这里开始朗读
+                      </Button>
+                    </Paper>
+                  </Grow>
+                )}
+              </Popper>
+
+              {visibleChartArtifacts.map((artifact) => (
+                <ChatInlineChart
+                  key={artifact.id}
+                  title={(artifact.params.title as string) ?? artifact.title}
+                  chart_type={
+                    (artifact.params.chart_type as "line" | "bar" | "pie") ??
+                    "line"
+                  }
+                  x_data={
+                    artifact.params.x_data ??
+                    artifact.params.xData ??
+                    artifact.params.labels ??
+                    artifact.params.categories
+                  }
+                  series={artifact.params.series}
+                  x_axis_name={(artifact.params.x_axis_name as string) ?? undefined}
+                  y_axis_name={(artifact.params.y_axis_name as string) ?? undefined}
+                  isStreaming={isStreamingAssistant}
+                />
+              ))}
+            </Stack>
+
+            <Grow
+              in={isHovered && !isStreaming}
+              timeout={floatingActionTransitionTimeout}
+              mountOnEnter
+              unmountOnExit
+              style={{ transformOrigin: "right bottom" }}
+            >
+              <Paper
+                elevation={4}
+                sx={{
+                  ...floatingActionSurfaceSx,
+                  position: "absolute",
+                  top: -14,
+                  right: 12,
+                  zIndex: 10,
+                }}
+              >
+                <Tooltip title="复制">
+                  <IconButton
+                    size="small"
+                    aria-label="复制"
+                    onClick={() => {
+                      navigator.clipboard.writeText(
+                        normalizeClipboardText(message.content),
+                      );
+                    }}
+                    sx={floatingIconButtonSx}
+                  >
+                    <ContentCopyRounded sx={{ fontSize: 16 }} />
+                  </IconButton>
+                </Tooltip>
+                <Tooltip title="拆分为新会话">
+                  <IconButton
+                    size="small"
+                    aria-label="拆分为新会话"
+                    onClick={() => onCreateBranch(message.id)}
+                    sx={floatingIconButtonSx}
+                  >
+                    <TbArrowsSplit2 size={16} />
+                  </IconButton>
+                </Tooltip>
+              </Paper>
+            </Grow>
 
           </Paper>
         </Stack>
 
-        {(!isErrorMessage && isTtsSupported) || (branchState && branchState.total > 1) ? (
+        {!isErrorMessage && isTtsSupported ? (
           <Stack direction="row" alignItems="center" justifyContent="space-between" sx={{ mt: 0.5, ml: 6, mb: 1 }}>
             <Stack direction="row" spacing={0.5} sx={{ opacity: isHovered ? 1 : 0.4, transition: "opacity 0.2s" }}>
-              {!isErrorMessage && isTtsSupported ? (
+              {messageSpeechState === "idle" ? (
+                <IconButton
+                  size="small"
+                  onClick={handleSpeakMessage}
+                  aria-label="朗读消息"
+                  sx={{ color: "text.secondary", opacity: 0.68, p: 0.5 }}
+                >
+                  <VolumeUpRounded sx={{ fontSize: 16 }} />
+                </IconButton>
+              ) : null}
+              {messageSpeechState === "loading" ? (
                 <>
-                  {messageSpeechState === "idle" ? (
-                    <IconButton
-                      size="small"
-                      onClick={() => onSpeak(message.id, stripMarkdown(answerContent))}
-                      aria-label="朗读消息"
-                      sx={{ color: "text.secondary", opacity: 0.68, p: 0.5 }}
-                    >
-                      <VolumeUpRounded sx={{ fontSize: 16 }} />
-                    </IconButton>
-                  ) : null}
-                  {messageSpeechState === "playing" ? (
-                    <>
-                      <IconButton size="small" onClick={onPause} aria-label="暂停朗读" sx={{ color: "primary.main", p: 0.5 }}>
-                        <PauseRounded sx={{ fontSize: 16 }} />
-                      </IconButton>
-                      <IconButton size="small" onClick={onStopSpeech} aria-label="停止朗读" sx={{ color: "error.main", p: 0.5 }}>
-                        <StopRounded sx={{ fontSize: 16 }} />
-                      </IconButton>
-                    </>
-                  ) : null}
-                  {messageSpeechState === "paused" ? (
-                    <>
-                      <IconButton size="small" onClick={onResume} aria-label="继续朗读" sx={{ color: "primary.main", p: 0.5 }}>
-                        <PlayArrowRounded sx={{ fontSize: 16 }} />
-                      </IconButton>
-                      <IconButton size="small" onClick={onStopSpeech} aria-label="停止朗读" sx={{ color: "error.main", p: 0.5 }}>
-                        <StopRounded sx={{ fontSize: 16 }} />
-                      </IconButton>
-                    </>
-                  ) : null}
+                  <IconButton
+                    size="small"
+                    disabled
+                    aria-label="正在生成语音"
+                    sx={{ color: "primary.main", p: 0.5 }}
+                  >
+                    <CircularProgress size={16} thickness={5} />
+                  </IconButton>
+                  <IconButton size="small" onClick={onStopSpeech} aria-label="停止朗读" sx={{ color: "error.main", p: 0.5 }}>
+                    <StopRounded sx={{ fontSize: 16 }} />
+                  </IconButton>
+                </>
+              ) : null}
+              {messageSpeechState === "playing" ? (
+                <>
+                  <IconButton size="small" onClick={onPause} aria-label="暂停朗读" sx={{ color: "primary.main", p: 0.5 }}>
+                    <PauseRounded sx={{ fontSize: 16 }} />
+                  </IconButton>
+                  <IconButton size="small" onClick={onStopSpeech} aria-label="停止朗读" sx={{ color: "error.main", p: 0.5 }}>
+                    <StopRounded sx={{ fontSize: 16 }} />
+                  </IconButton>
+                </>
+              ) : null}
+              {messageSpeechState === "paused" ? (
+                <>
+                  <IconButton size="small" onClick={onResume} aria-label="继续朗读" sx={{ color: "primary.main", p: 0.5 }}>
+                    <PlayArrowRounded sx={{ fontSize: 16 }} />
+                  </IconButton>
+                  <IconButton size="small" onClick={onStopSpeech} aria-label="停止朗读" sx={{ color: "error.main", p: 0.5 }}>
+                    <StopRounded sx={{ fontSize: 16 }} />
+                  </IconButton>
                 </>
               ) : null}
             </Stack>
-
-            {branchState && branchState.total > 1 ? (
-              <Stack
-                direction="row"
-                justifyContent="flex-start"
-                sx={{ mr: 0.5 }}
-              >
-                <Paper
-                  elevation={0}
-                  sx={{
-                    display: "flex",
-                    alignItems: "center",
-                    gap: 0.5,
-                    px: 0.5,
-                    py: 0.25,
-                    borderRadius: 4,
-                    bgcolor: alpha("#000", 0.04),
-                    backdropFilter: "blur(4px)",
-                    border: `1px solid ${alpha("#000", 0.08)}`,
-                  }}
-                >
-                  <IconButton
-                    size="small"
-                    aria-label="上一分支"
-                    onClick={() => onCycleBranch(rootMessageId, -1)}
-                    sx={{ width: 22, height: 22, color: "text.secondary", "&:hover": { bgcolor: alpha("#000", 0.08) } }}
-                  >
-                    <ChevronLeftRounded sx={{ fontSize: 16 }} />
-                  </IconButton>
-                  <Typography variant="caption" sx={{ color: "text.secondary", fontWeight: 600, fontSize: "0.7rem", px: 0.5, userSelect: "none" }}>
-                    {branchState.activeIndex + 1} / {branchState.total}
-                  </Typography>
-                  <IconButton
-                    size="small"
-                    aria-label="下一分支"
-                    onClick={() => onCycleBranch(rootMessageId, 1)}
-                    sx={{ width: 22, height: 22, color: "text.secondary", "&:hover": { bgcolor: alpha("#000", 0.08) } }}
-                  >
-                    <ChevronRightRounded sx={{ fontSize: 16 }} />
-                  </IconButton>
-                </Paper>
-              </Stack>
-            ) : null}
           </Stack>
         ) : null}
       </motion.div>

src/components/chat/AgentWorkspace.test.tsx

@@ -0,0 +1,265 @@
+/* eslint-disable @next/next/no-img-element */
+import "@testing-library/jest-dom";
+import React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import { AgentWorkspace } from "./AgentWorkspace";
+import type { Message } from "./GlobalChatbox.types";
+
+const renderCounts = new Map<string, number>();
+const mountCounts = new Map<string, number>();
+const unmountCounts = new Map<string, number>();
+const streamingFlags = new Map<string, boolean>();
+
+jest.mock("next/image", () => ({
+  __esModule: true,
+  default: (props: React.ImgHTMLAttributes<HTMLImageElement>) => <img {...props} alt={props.alt ?? ""} />,
+}));
+
+jest.mock("framer-motion", () => ({
+  AnimatePresence: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  motion: {
+    div: ({
+      children,
+      animate: _animate,
+      exit: _exit,
+      initial: _initial,
+      layout: _layout,
+      transition: _transition,
+      whileHover: _whileHover,
+      ...props
+    }: React.HTMLAttributes<HTMLDivElement> & Record<string, unknown>) => (
+      <div {...props}>{children}</div>
+    ),
+  },
+}));
+
+jest.mock("./AgentTurn", () => ({
+  AgentTurn: ({ message, isStreaming }: { message: Message; isStreaming: boolean }) => {
+    React.useEffect(() => {
+      mountCounts.set(message.id, (mountCounts.get(message.id) ?? 0) + 1);
+      return () => {
+        unmountCounts.set(message.id, (unmountCounts.get(message.id) ?? 0) + 1);
+      };
+    }, [message.id]);
+    renderCounts.set(message.id, (renderCounts.get(message.id) ?? 0) + 1);
+    streamingFlags.set(message.id, isStreaming);
+    return <div data-testid={`turn-${message.id}`}>{message.content}</div>;
+  },
+}));
+
+describe("AgentWorkspace", () => {
+  const defaultProps = {
+    bottomRef: { current: null },
+    speakingMessageId: null,
+    speechState: "idle" as const,
+    onSpeak: jest.fn(),
+    onPauseSpeech: jest.fn(),
+    onResumeSpeech: jest.fn(),
+    onStopSpeech: jest.fn(),
+    isTtsSupported: false,
+    onCreateBranch: jest.fn(),
+    onReplyPermission: jest.fn(),
+    onReplyQuestion: jest.fn(),
+    onRejectQuestion: jest.fn(),
+  };
+
+  beforeEach(() => {
+    renderCounts.clear();
+    mountCounts.clear();
+    unmountCounts.clear();
+    streamingFlags.clear();
+  });
+
+  it("shows a loading skeleton instead of the empty state while switching history sessions", () => {
+    render(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming={false}
+        isLoadingSession
+        messages={[]}
+      />,
+    );
+
+    expect(screen.getByLabelText("正在加载历史记录")).toBeInTheDocument();
+    expect(screen.queryByText("我已就绪，请描述任务")).not.toBeInTheDocument();
+  });
+
+  it("shows runtime startup failures in the existing empty state and retries there", () => {
+    const onRetryRuntime = jest.fn();
+    render(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming={false}
+        runtimeState="unavailable"
+        onRetryRuntime={onRetryRuntime}
+        messages={[]}
+      />,
+    );
+
+    expect(screen.getByText("Agent 服务未就绪")).toBeInTheDocument();
+    expect(screen.queryByText("我已就绪，请描述任务")).not.toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "重新检测" }));
+    expect(onRetryRuntime).toHaveBeenCalledTimes(1);
+  });
+
+  it("distinguishes model loading failures from backend startup failures", () => {
+    render(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming={false}
+        runtimeState="models_unavailable"
+        messages={[]}
+      />,
+    );
+
+    expect(screen.getByText("模型未加载")).toBeInTheDocument();
+    expect(screen.getByText(/模型配置加载失败/)).toBeInTheDocument();
+  });
+
+  it("keeps stable history turns from re-rendering while the last assistant message streams", () => {
+    const userMessage: Message = {
+      id: "user-1",
+      role: "user",
+      content: "question",
+    };
+    const assistantHistoryMessage: Message = {
+      id: "assistant-1",
+      role: "assistant",
+      content: "stable answer",
+    };
+    const streamingMessage: Message = {
+      id: "assistant-2",
+      role: "assistant",
+      content: "partial",
+    };
+
+    const { rerender } = render(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming
+        messages={[userMessage, assistantHistoryMessage, streamingMessage]}
+      />,
+    );
+
+    const updatedStreamingMessage: Message = {
+      ...streamingMessage,
+      content: "partial with more tokens",
+    };
+
+    rerender(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming
+        messages={[userMessage, assistantHistoryMessage, updatedStreamingMessage]}
+      />,
+    );
+
+    expect(renderCounts.get("user-1")).toBe(1);
+    expect(renderCounts.get("assistant-1")).toBe(1);
+    expect(renderCounts.get("assistant-2")).toBe(2);
+    expect(streamingFlags.get("assistant-1")).toBe(false);
+    expect(streamingFlags.get("assistant-2")).toBe(true);
+  });
+
+  it("does not remount the streaming assistant turn when streaming finishes", () => {
+    const userMessage: Message = {
+      id: "user-1",
+      role: "user",
+      content: "question",
+    };
+    const assistantMessage: Message = {
+      id: "assistant-1",
+      role: "assistant",
+      content: "final answer",
+    };
+
+    const { rerender } = render(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming
+        messages={[userMessage, assistantMessage]}
+      />,
+    );
+
+    expect(streamingFlags.get("assistant-1")).toBe(true);
+
+    rerender(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming={false}
+        messages={[userMessage, assistantMessage]}
+      />,
+    );
+
+    expect(mountCounts.get("assistant-1")).toBe(1);
+    expect(unmountCounts.get("assistant-1") ?? 0).toBe(0);
+    expect(streamingFlags.get("assistant-1")).toBe(false);
+  });
+
+  it("windows long conversations instead of mounting every turn", () => {
+    const messages = Array.from({ length: 200 }, (_, index): Message => ({
+      id: `message-${index}`,
+      role: index % 2 === 0 ? "user" : "assistant",
+      content: `message ${index}`,
+    }));
+
+    render(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming={false}
+        messages={messages}
+      />,
+    );
+
+    expect(renderCounts.size).toBeGreaterThan(0);
+    expect(renderCounts.size).toBeLessThan(40);
+  });
+
+  it("preserves the flex alignment context around windowed turns", () => {
+    const messages = Array.from({ length: 41 }, (_, index): Message => ({
+      id: `message-${index}`,
+      role: index % 2 === 0 ? "user" : "assistant",
+      content: `message ${index}`,
+    }));
+
+    render(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming={false}
+        messages={messages}
+      />,
+    );
+
+    expect(screen.getByTestId("turn-message-0").parentElement).toHaveStyle({
+      display: "flex",
+      flexDirection: "column",
+    });
+  });
+
+  it("keeps visible turns mounted when crossing the windowing threshold", () => {
+    const messages = Array.from({ length: 41 }, (_, index): Message => ({
+      id: `message-${index}`,
+      role: index % 2 === 0 ? "user" : "assistant",
+      content: `message ${index}`,
+    }));
+    const { rerender } = render(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming={false}
+        messages={messages.slice(0, 40)}
+      />,
+    );
+
+    rerender(
+      <AgentWorkspace
+        {...defaultProps}
+        isStreaming={false}
+        messages={messages}
+      />,
+    );
+
+    expect(mountCounts.get("message-0")).toBe(1);
+    expect(unmountCounts.get("message-0") ?? 0).toBe(0);
+  });
+});

src/components/chat/AgentWorkspace.tsx

@@ -3,41 +3,320 @@
 import Image from "next/image";
 import React from "react";
 import { AnimatePresence, motion } from "framer-motion";
-import { Box, Paper, Stack, Typography, alpha, useTheme, Grid } from "@mui/material";
+import { Box, Button, CircularProgress, Paper, Skeleton, Stack, Typography, alpha, Grid } from "@mui/material";
 import WaterDropRounded from "@mui/icons-material/WaterDropRounded";
 import SensorsRounded from "@mui/icons-material/SensorsRounded";
 import TroubleshootRounded from "@mui/icons-material/TroubleshootRounded";
 import MapRounded from "@mui/icons-material/MapRounded";
+import ReplayRounded from "@mui/icons-material/ReplayRounded";
 
 import { AgentTurn } from "./AgentTurn";
-import { TypingIndicator } from "./GlobalChatbox.parts";
+import type { AgentRuntimeState } from "@/lib/agentRuntime";
+import type { PermissionDecision } from "@/lib/chatStream";
 import type {
-  BranchGroup,
-  BranchTransition,
   Message,
   SpeechState,
 } from "./GlobalChatbox.types";
 
 type AgentWorkspaceProps = {
   messages: Message[];
-  branchGroups: BranchGroup[];
-  branchTransition: BranchTransition | null;
   isStreaming: boolean;
+  runtimeState?: AgentRuntimeState;
+  onRetryRuntime?: () => void;
+  isLoadingSession?: boolean;
+  scrollContainerRef?: React.RefObject<HTMLDivElement | null>;
   bottomRef: React.RefObject<HTMLDivElement | null>;
+  onScrollStateChange?: (isNearBottom: boolean) => void;
   speakingMessageId: string | null;
   speechState: SpeechState;
-  onSpeak: (messageId: string, text: string) => void;
+  onSpeak: (
+    messageId: string,
+    text: string,
+    options?: { startOffset?: number },
+  ) => void;
   onPauseSpeech: () => void;
   onResumeSpeech: () => void;
   onStopSpeech: () => void;
   isTtsSupported: boolean;
-  onRegenerate: () => void;
-  onEditResubmit: (messageId: string, newContent: string) => void;
-  onCycleBranch: (rootMessageId: string, direction: -1 | 1) => void;
+  onCreateBranch: (messageId: string) => void;
+  onReplyPermission: (requestId: string, reply: PermissionDecision) => void;
+  onReplyQuestion: (requestId: string, answers: string[][]) => void;
+  onRejectQuestion: (requestId: string) => void;
 };
 
-const EmptyState = () => {
-  const theme = useTheme();
+type TurnListProps = {
+  messages: Message[];
+  scrollTop: number;
+  viewportHeight: number;
+  isAssistantStreaming: boolean;
+  streamingMessageId: string | null;
+  speakingMessageId: string | null;
+  speechState: SpeechState;
+  onSpeak: (
+    messageId: string,
+    text: string,
+    options?: { startOffset?: number },
+  ) => void;
+  onPauseSpeech: () => void;
+  onResumeSpeech: () => void;
+  onStopSpeech: () => void;
+  isTtsSupported: boolean;
+  onCreateBranch: (messageId: string) => void;
+  onReplyPermission: (requestId: string, reply: PermissionDecision) => void;
+  onReplyQuestion: (requestId: string, answers: string[][]) => void;
+  onRejectQuestion: (requestId: string) => void;
+};
+
+const STREAMING_BOTTOM_RESERVE_PX = 180;
+const STREAMING_NEAR_BOTTOM_THRESHOLD_PX = STREAMING_BOTTOM_RESERVE_PX + 120;
+const TURN_WINDOW_THRESHOLD = 40;
+const TURN_ESTIMATED_HEIGHT_PX = 220;
+const TURN_GAP_PX = 16;
+const TURN_OVERSCAN_PX = 600;
+const DEFAULT_VIEWPORT_HEIGHT_PX = 720;
+
+const sameMessages = (left: Message[], right: Message[]) =>
+  left.length === right.length &&
+  left.every((message, index) => message === right[index]);
+
+const TurnItem = React.memo(AgentTurn);
+
+const TurnListInner = ({
+  messages,
+  scrollTop,
+  viewportHeight,
+  isAssistantStreaming,
+  streamingMessageId,
+  speakingMessageId,
+  speechState,
+  onSpeak,
+  onPauseSpeech,
+  onResumeSpeech,
+  onStopSpeech,
+  isTtsSupported,
+  onCreateBranch,
+  onReplyPermission,
+  onReplyQuestion,
+  onRejectQuestion,
+}: TurnListProps) => {
+  const [measuredHeights, setMeasuredHeights] = React.useState(
+    () => new Map<string, number>(),
+  );
+  const isWindowed = messages.length > TURN_WINDOW_THRESHOLD;
+
+  React.useEffect(() => {
+    const activeIds = new Set(messages.map((message) => message.id));
+    setMeasuredHeights((current) => {
+      if ([...current.keys()].every((messageId) => activeIds.has(messageId))) {
+        return current;
+      }
+      return new Map(
+        [...current].filter(([messageId]) => activeIds.has(messageId)),
+      );
+    });
+  }, [messages]);
+
+  const updateMeasuredHeight = React.useCallback(
+    (messageId: string, height: number) => {
+      if (!Number.isFinite(height) || height <= 0) return;
+      const roundedHeight = Math.ceil(height);
+      setMeasuredHeights((current) => {
+        if (current.get(messageId) === roundedHeight) return current;
+        const next = new Map(current);
+        next.set(messageId, roundedHeight);
+        return next;
+      });
+    },
+    [],
+  );
+
+  const turnOffsets = React.useMemo(() => {
+    const offsets = new Array<number>(messages.length + 1).fill(0);
+    if (!isWindowed) return offsets;
+    for (let index = 0; index < messages.length; index += 1) {
+      const message = messages[index];
+      const size =
+        (measuredHeights.get(message.id) ?? TURN_ESTIMATED_HEIGHT_PX) +
+        TURN_GAP_PX;
+      offsets[index + 1] = offsets[index] + size;
+    }
+    return offsets;
+  }, [isWindowed, measuredHeights, messages]);
+
+  const windowState = React.useMemo(() => {
+    if (!isWindowed) {
+      return {
+        endIndex: messages.length,
+        startIndex: 0,
+        topSpacerHeight: 0,
+        bottomSpacerHeight: 0,
+      };
+    }
+
+    const visibleStart = Math.max(0, scrollTop - TURN_OVERSCAN_PX);
+    const visibleEnd = scrollTop + viewportHeight + TURN_OVERSCAN_PX;
+    const startIndex = Math.max(
+      0,
+      lowerBound(turnOffsets, visibleStart, 1) - 1,
+    );
+    const endIndex = lowerBound(turnOffsets, visibleEnd, startIndex);
+
+    const boundedEndIndex = Math.min(
+      messages.length,
+      Math.max(startIndex + 1, endIndex),
+    );
+    return {
+      startIndex,
+      endIndex: boundedEndIndex,
+      topSpacerHeight: turnOffsets[startIndex],
+      bottomSpacerHeight:
+        turnOffsets[messages.length] - turnOffsets[boundedEndIndex],
+    };
+  }, [isWindowed, messages.length, scrollTop, turnOffsets, viewportHeight]);
+
+  const visibleMessages = isWindowed
+    ? messages.slice(windowState.startIndex, windowState.endIndex)
+    : messages;
+
+  return (
+    <>
+      {windowState.topSpacerHeight > 0 ? (
+        <Box aria-hidden sx={{ height: windowState.topSpacerHeight, flexShrink: 0 }} />
+      ) : null}
+      {visibleMessages.map((message) => (
+        <MeasuredTurn
+          key={message.id}
+          message={message}
+          measure={isWindowed}
+          onHeightChange={updateMeasuredHeight}
+        >
+          <TurnItem
+            message={message}
+            isStreaming={isAssistantStreaming && message.id === streamingMessageId}
+            messageSpeechState={speakingMessageId === message.id ? speechState : "idle"}
+            onSpeak={onSpeak}
+            onPause={onPauseSpeech}
+            onResume={onResumeSpeech}
+            onStopSpeech={onStopSpeech}
+            isTtsSupported={isTtsSupported}
+            onCreateBranch={onCreateBranch}
+            onReplyPermission={onReplyPermission}
+            onReplyQuestion={onReplyQuestion}
+            onRejectQuestion={onRejectQuestion}
+          />
+        </MeasuredTurn>
+      ))}
+      {windowState.bottomSpacerHeight > 0 ? (
+        <Box aria-hidden sx={{ height: windowState.bottomSpacerHeight, flexShrink: 0 }} />
+      ) : null}
+    </>
+  );
+};
+
+const lowerBound = (values: number[], target: number, fromIndex: number) => {
+  let low = Math.max(0, fromIndex);
+  let high = values.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    if (values[middle] < target) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+};
+
+type MeasuredTurnProps = {
+  children: React.ReactNode;
+  measure: boolean;
+  message: Message;
+  onHeightChange: (messageId: string, height: number) => void;
+};
+
+const MeasuredTurn = ({
+  children,
+  measure,
+  message,
+  onHeightChange,
+}: MeasuredTurnProps) => {
+  const rowRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    const row = rowRef.current;
+    if (!measure || !row) return;
+    const measureRow = () =>
+      onHeightChange(message.id, row.getBoundingClientRect().height);
+    measureRow();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(measureRow);
+    observer.observe(row);
+    return () => observer.disconnect();
+  }, [measure, message.id, onHeightChange]);
+
+  return (
+    <Box
+      ref={rowRef}
+      sx={{
+        display: "flex",
+        flexDirection: "column",
+        flexShrink: 0,
+        mb: measure ? `${TURN_GAP_PX}px` : 0,
+      }}
+    >
+      {children}
+    </Box>
+  );
+};
+
+const TurnList = React.memo(
+  TurnListInner,
+  (prevProps, nextProps) =>
+    sameMessages(prevProps.messages, nextProps.messages) &&
+    prevProps.scrollTop === nextProps.scrollTop &&
+    prevProps.viewportHeight === nextProps.viewportHeight &&
+    prevProps.isAssistantStreaming === nextProps.isAssistantStreaming &&
+    prevProps.streamingMessageId === nextProps.streamingMessageId &&
+    prevProps.speakingMessageId === nextProps.speakingMessageId &&
+    prevProps.speechState === nextProps.speechState &&
+    prevProps.onSpeak === nextProps.onSpeak &&
+    prevProps.onPauseSpeech === nextProps.onPauseSpeech &&
+    prevProps.onResumeSpeech === nextProps.onResumeSpeech &&
+    prevProps.onStopSpeech === nextProps.onStopSpeech &&
+    prevProps.isTtsSupported === nextProps.isTtsSupported &&
+    prevProps.onCreateBranch === nextProps.onCreateBranch &&
+    prevProps.onReplyPermission === nextProps.onReplyPermission &&
+    prevProps.onReplyQuestion === nextProps.onReplyQuestion &&
+    prevProps.onRejectQuestion === nextProps.onRejectQuestion,
+);
+
+TurnList.displayName = "TurnList";
+
+const EmptyState = ({
+  runtimeState,
+  onRetryRuntime,
+}: {
+  runtimeState: AgentRuntimeState;
+  onRetryRuntime?: () => void;
+}) => {
+  const isReady = runtimeState === "ready";
+  const isChecking = runtimeState === "checking";
+  const statusCopy = isChecking
+    ? {
+        title: "正在连接 Agent 服务",
+        detail: "正在确认后端运行时和模型加载状态，请稍候。",
+      }
+    : runtimeState === "models_unavailable"
+      ? {
+          title: "模型未加载",
+          detail: "Agent 服务已启动，但模型配置加载失败。请检查模型配置后重新检测。",
+        }
+      : runtimeState === "unavailable"
+        ? {
+            title: "Agent 服务未就绪",
+            detail: "无法连接 Agent 后端，或运行时启动失败。请检查服务后重新检测。",
+          }
+        : {
+            title: "我已就绪，请描述任务",
+            detail: "你可以使用自然语言下达指令，我会自主规划决策执行、并在地图上呈现分析结果。",
+          };
   const capabilities = [
     { icon: <WaterDropRounded sx={{ fontSize: 20, color: "#00acc1" }} />, label: "水力瓶颈识别" },
     { icon: <SensorsRounded sx={{ fontSize: 20, color: "#0288d1" }} />, label: "异常状态预警" },
@@ -53,6 +332,8 @@ const EmptyState = () => {
       style={{ margin: "auto", width: "100%", maxWidth: 440, padding: 16 }}
     >
       <Paper
+        role={isReady || isChecking ? "status" : "alert"}
+        aria-live="polite"
         elevation={0}
         sx={{
           p: 4,
@@ -76,9 +357,9 @@ const EmptyState = () => {
         }} />
         <motion.div
           animate={{
-            y: [-6, 4, -6],
-            scale: [1, 1.04, 1],
-            rotate: [-3, 3, -3],
+            y: isReady ? [-6, 4, -6] : 0,
+            scale: isReady ? [1, 1.04, 1] : 1,
+            rotate: isReady ? [-3, 3, -3] : 0,
           }}
           transition={{ duration: 4.8, repeat: Infinity, ease: "easeInOut" }}
           style={{
@@ -100,22 +381,37 @@ const EmptyState = () => {
             height={54}
             style={{
               objectFit: "contain",
-              filter: "drop-shadow(0 4px 12px rgba(0, 131, 143, 0.2))",
+              filter: isReady
+                ? "drop-shadow(0 4px 12px rgba(0, 131, 143, 0.2))"
+                : "grayscale(0.65) opacity(0.72)",
             }}
           />
         </motion.div>
         <Typography variant="h6" color="text.primary" fontWeight={800} gutterBottom>
-          我已就绪，请描述任务
+          {statusCopy.title}
         </Typography>
-        <Typography variant="body2" color="text.secondary" sx={{ lineHeight: 1.6, mb: 3 }}>
-          你可以使用自然语言下达指令，我会自主规划决策执行、并在地图上呈现分析结果。
+        <Typography variant="body2" color="text.secondary" sx={{ lineHeight: 1.6, mb: isReady ? 3 : 2 }}>
+          {statusCopy.detail}
         </Typography>
 
-        <Grid container spacing={1.5}>
-          {capabilities.map((item) => (
-            <Grid item xs={6} key={item.label}>
-              <motion.div whileHover={{ y: -2, scale: 1.02 }} transition={{ duration: 0.2 }}>
-                <Stack
+        {isChecking ? (
+          <CircularProgress size={28} thickness={4} aria-label="正在检测 Agent 服务" />
+        ) : !isReady ? (
+          <Button
+            variant="contained"
+            size="small"
+            startIcon={<ReplayRounded />}
+            onClick={onRetryRuntime}
+            sx={{ borderRadius: 999, px: 2, boxShadow: "none" }}
+          >
+            重新检测
+          </Button>
+        ) : (
+          <Grid container spacing={1.5}>
+            {capabilities.map((item) => (
+              <Grid item xs={6} key={item.label}>
+                <motion.div whileHover={{ y: -2, scale: 1.02 }} transition={{ duration: 0.2 }}>
+                  <Stack
                   direction="row"
                   spacing={1}
                   alignItems="center"
@@ -140,22 +436,88 @@ const EmptyState = () => {
                   <Typography variant="caption" fontWeight={700}>
                     {item.label}
                   </Typography>
-                </Stack>
-              </motion.div>
-            </Grid>
-          ))}
-        </Grid>
+                  </Stack>
+                </motion.div>
+              </Grid>
+            ))}
+          </Grid>
+        )}
       </Paper>
     </motion.div>
   );
 };
 
+const SessionLoadingSkeleton = () => (
+  <Stack
+    spacing={2.25}
+    aria-label="正在加载历史记录"
+    sx={{ width: "100%", maxWidth: 760, alignSelf: "stretch" }}
+  >
+    {Array.from({ length: 2 }, (_, turnIndex) => (
+      <Stack key={turnIndex} spacing={1.25}>
+        <Stack direction="row" justifyContent="flex-end">
+          <Paper
+            elevation={0}
+            sx={{
+              width: turnIndex === 0 ? "72%" : "64%",
+              maxWidth: "86%",
+              p: 1.75,
+              borderRadius: 5,
+              borderBottomRightRadius: 2,
+              bgcolor: alpha("#00acc1", 0.16),
+              border: `1px solid ${alpha("#00acc1", 0.12)}`,
+              boxShadow: `0 8px 24px -12px ${alpha("#00acc1", 0.35)}`,
+            }}
+          >
+            <Stack spacing={0.85}>
+              <Skeleton variant="text" width="76%" height={18} />
+              <Skeleton variant="text" width="48%" height={15} />
+            </Stack>
+          </Paper>
+        </Stack>
+
+        <Stack direction="row" spacing={1.5} alignItems="flex-start">
+          <Skeleton
+            variant="circular"
+            width={34}
+            height={34}
+            sx={{ bgcolor: alpha("#00acc1", 0.12), flexShrink: 0, mt: 0.25 }}
+          />
+          <Paper
+            elevation={0}
+            sx={{
+              flex: 1,
+              minWidth: 0,
+              p: 2,
+              borderRadius: 5,
+              bgcolor: alpha("#ffffff", 0.52),
+              border: `1px solid ${alpha("#fff", 0.72)}`,
+              boxShadow: `0 10px 30px -10px ${alpha("#000", 0.06)}`,
+            }}
+          >
+            <Stack spacing={1}>
+              <Skeleton variant="text" width="38%" height={16} />
+              <Skeleton variant="text" width="94%" height={16} />
+              <Skeleton variant="text" width={turnIndex === 0 ? "88%" : "82%"} height={16} />
+              <Skeleton variant="text" width={turnIndex === 0 ? "78%" : "70%"} height={16} />
+              <Skeleton variant="rounded" width="100%" height={turnIndex === 0 ? 104 : 76} sx={{ borderRadius: 2 }} />
+            </Stack>
+          </Paper>
+        </Stack>
+      </Stack>
+    ))}
+  </Stack>
+);
+
 export const AgentWorkspace = ({
   messages,
-  branchGroups,
-  branchTransition,
   isStreaming,
+  runtimeState = "ready",
+  onRetryRuntime,
+  isLoadingSession = false,
+  scrollContainerRef,
   bottomRef,
+  onScrollStateChange,
   speakingMessageId,
   speechState,
   onSpeak,
@@ -163,59 +525,70 @@ export const AgentWorkspace = ({
   onResumeSpeech,
   onStopSpeech,
   isTtsSupported,
-  onRegenerate,
-  onEditResubmit,
-  onCycleBranch,
+  onCreateBranch,
+  onReplyPermission,
+  onReplyQuestion,
+  onRejectQuestion,
 }: AgentWorkspaceProps) => {
-  const theme = useTheme();
-  const latestAssistant = [...messages]
-    .reverse()
-    .find((message) => message.role === "assistant");
-  const showTypingIndicator =
-    isStreaming &&
-    (!latestAssistant ||
-      (latestAssistant.content.trim().length === 0 &&
-        !(latestAssistant.artifacts?.length)));
-  const stableMessages = branchTransition
-    ? messages.slice(0, branchTransition.parentCount)
-    : messages;
-  const transitionMessages = branchTransition
-    ? messages.slice(branchTransition.parentCount)
-    : [];
+  const localScrollContainerRef = React.useRef<HTMLDivElement>(null);
+  const [scrollMetrics, setScrollMetrics] = React.useState({
+    scrollTop: 0,
+    viewportHeight: DEFAULT_VIEWPORT_HEIGHT_PX,
+  });
+  const streamingMessageId =
+    isStreaming && messages.at(-1)?.role === "assistant"
+      ? messages.at(-1)?.id ?? null
+      : null;
+  const handleScroll = React.useCallback(
+    (event: React.UIEvent<HTMLDivElement>) => {
+      const target = event.currentTarget;
+      setScrollMetrics({
+        scrollTop: target.scrollTop,
+        viewportHeight: target.clientHeight || DEFAULT_VIEWPORT_HEIGHT_PX,
+      });
+      if (!onScrollStateChange) return;
+      const distanceToBottom =
+        target.scrollHeight - target.scrollTop - target.clientHeight;
+      onScrollStateChange(
+        distanceToBottom <
+          (isStreaming ? STREAMING_NEAR_BOTTOM_THRESHOLD_PX : 96),
+      );
+    },
+    [isStreaming, onScrollStateChange],
+  );
 
-  const renderTurn = (message: Message) => {
-    const rootMessageId = message.branchRootId ?? message.id;
-    const branchGroup = branchGroups.find(
-      (group) => group.rootMessageId === rootMessageId,
-    );
+  const setScrollContainer = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      localScrollContainerRef.current = node;
+      if (scrollContainerRef) {
+        scrollContainerRef.current = node;
+      }
+    },
+    [scrollContainerRef],
+  );
 
-    return (
-      <AgentTurn
-        key={rootMessageId}
-        message={message}
-        branchState={
-          branchGroup && branchGroup.branches.length > 1
-            ? {
-                activeIndex: branchGroup.activeIndex,
-                total: branchGroup.branches.length,
-              }
-            : undefined
-        }
-        messageSpeechState={speakingMessageId === message.id ? speechState : "idle"}
-        onSpeak={onSpeak}
-        onPause={onPauseSpeech}
-        onResume={onResumeSpeech}
-        onStopSpeech={onStopSpeech}
-        isTtsSupported={isTtsSupported}
-        onRegenerate={onRegenerate}
-        onEditResubmit={onEditResubmit}
-        onCycleBranch={onCycleBranch}
-      />
-    );
-  };
+  React.useEffect(() => {
+    const container = localScrollContainerRef.current;
+    if (!container || typeof ResizeObserver === "undefined") return;
+    const updateViewportHeight = () => {
+      const viewportHeight =
+        container.clientHeight || DEFAULT_VIEWPORT_HEIGHT_PX;
+      setScrollMetrics((current) =>
+        current.viewportHeight === viewportHeight
+          ? current
+          : { ...current, viewportHeight },
+      );
+    };
+    updateViewportHeight();
+    const observer = new ResizeObserver(updateViewportHeight);
+    observer.observe(container);
+    return () => observer.disconnect();
+  }, []);
 
   return (
     <Box
+      ref={setScrollContainer}
+      onScroll={handleScroll}
       sx={{
         flex: 1,
         overflowY: "auto",
@@ -223,56 +596,65 @@ export const AgentWorkspace = ({
         py: 2,
         display: "flex",
         flexDirection: "column",
+        scrollbarGutter: "stable",
         zIndex: 5,
       }}
     >
-      <AnimatePresence initial={false}>
-        {messages.length === 0 ? <EmptyState /> : null}
-      </AnimatePresence>
+      {isLoadingSession ? (
+        <SessionLoadingSkeleton />
+      ) : (
+        <>
+          <AnimatePresence initial={false}>
+            {messages.length === 0 ? (
+              <EmptyState
+                runtimeState={runtimeState}
+                onRetryRuntime={onRetryRuntime}
+              />
+            ) : null}
+          </AnimatePresence>
 
-      {messages.length > 0 ? (
-        <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
-          {stableMessages.map(renderTurn)}
-
-          {branchTransition ? (
-            <AnimatePresence initial={false} mode="wait">
-              <motion.div
-                key={`${branchTransition.rootMessageId}:${branchTransition.activeBranchId}:${branchTransition.nonce}`}
-                initial={{ opacity: 0, y: 8 }}
-                animate={{ opacity: 1, y: 0 }}
-                exit={{ opacity: 0, y: -8 }}
-                transition={{ duration: 0.18, ease: "easeOut" }}
-                style={{ display: "flex", flexDirection: "column", gap: 16 }}
-              >
-                {transitionMessages.map(renderTurn)}
-              </motion.div>
-            </AnimatePresence>
+          {messages.length > 0 ? (
+            <Box
+              sx={{
+                display: "flex",
+                flexDirection: "column",
+                gap: messages.length > TURN_WINDOW_THRESHOLD ? 0 : 2,
+              }}
+            >
+              <TurnList
+                messages={messages}
+                scrollTop={
+                  messages.length > TURN_WINDOW_THRESHOLD
+                    ? scrollMetrics.scrollTop
+                    : 0
+                }
+                viewportHeight={scrollMetrics.viewportHeight}
+                isAssistantStreaming={isStreaming}
+                streamingMessageId={streamingMessageId}
+                speakingMessageId={speakingMessageId}
+                speechState={speechState}
+                onSpeak={onSpeak}
+                onPauseSpeech={onPauseSpeech}
+                onResumeSpeech={onResumeSpeech}
+                onStopSpeech={onStopSpeech}
+                isTtsSupported={isTtsSupported}
+                onCreateBranch={onCreateBranch}
+                onReplyPermission={onReplyPermission}
+                onReplyQuestion={onReplyQuestion}
+                onRejectQuestion={onRejectQuestion}
+              />
+            </Box>
           ) : null}
-        </Box>
-      ) : null}
+        </>
+      )}
 
-      {showTypingIndicator ? (
-        <motion.div
-          initial={{ opacity: 0, y: 10, scale: 0.94 }}
-          animate={{ opacity: 1, y: 0, scale: 1 }}
-          transition={{ type: "spring", stiffness: 300 }}
-          style={{ alignSelf: "flex-start", display: "flex", gap: 12, marginTop: 4, marginLeft: 44 }}
-        >
-          <Paper
-            elevation={0}
-            sx={{
-              p: 1.3,
-              borderRadius: 4,
-              bgcolor: alpha("#fff", 0.82),
-              boxShadow: `0 4px 12px ${alpha(theme.palette.common.black, 0.05)}`,
-            }}
-          >
-            <TypingIndicator />
-          </Paper>
-        </motion.div>
-      ) : null}
-
-      <div ref={bottomRef} style={{ height: 1 }} />
+      <div
+        ref={bottomRef}
+        style={{
+          flexShrink: 0,
+          height: isStreaming ? STREAMING_BOTTOM_RESERVE_PX : 1,
+        }}
+      />
     </Box>
   );
 };

src/components/chat/ChatInlineChart.test.ts

@@ -0,0 +1,49 @@
+import { normalizeChartData } from "./ChatInlineChart";
+
+describe("normalizeChartData", () => {
+  it("keeps standard bar chart series data", () => {
+    const result = normalizeChartData(["A", "B"], [
+      { name: "数量", data: [3, 5], type: "bar" },
+    ]);
+
+    expect(result).toEqual({
+      xData: ["A", "B"],
+      series: [{ name: "数量", data: [3, 5], type: "bar" }],
+    });
+  });
+
+  it("normalizes line chart point arrays into x labels and y values", () => {
+    const result = normalizeChartData(undefined, [
+      { name: "压力", data: [["10:00", 12.5], ["11:00", 13.1]] },
+    ]);
+
+    expect(result).toEqual({
+      xData: ["10:00", "11:00"],
+      series: [{ name: "压力", data: [12.5, 13.1], type: undefined }],
+    });
+  });
+
+  it("normalizes pie chart point objects into a single series", () => {
+    const result = normalizeChartData(undefined, [
+      { name: "低风险", value: 8 },
+      { name: "高风险", value: 2 },
+    ]);
+
+    expect(result).toEqual({
+      xData: ["低风险", "高风险"],
+      series: [{ name: "数据", data: [8, 2], type: undefined }],
+    });
+  });
+
+  it("accepts a single series object", () => {
+    const result = normalizeChartData(["A", "B"], {
+      name: "流量",
+      values: ["1.2", "2.4"],
+    });
+
+    expect(result).toEqual({
+      xData: ["A", "B"],
+      series: [{ name: "流量", data: [1.2, 2.4], type: undefined }],
+    });
+  });
+});

src/components/chat/ChatInlineChart.tsx

@@ -3,7 +3,8 @@
 import React, { useMemo } from "react";
 import ReactECharts from "echarts-for-react";
 import * as echarts from "echarts";
-import { Box, Paper, Typography, alpha, useTheme } from "@mui/material";
+import { AnimatePresence, motion } from "framer-motion";
+import { Box, Paper, Skeleton, Stack, Typography, alpha, useTheme } from "@mui/material";
 
 /* ------------------------------------------------------------------ */
 /*  Inline chart rendered inside a chat message bubble.               */
@@ -16,15 +17,43 @@ export interface ChatChartSeries {
   type?: "line" | "bar";
 }
 
+type RawChartPoint =
+  | number
+  | string
+  | [unknown, unknown]
+  | RawChartPointObject;
+
+type RawChartPointObject = {
+  x?: unknown;
+  y?: unknown;
+  time?: unknown;
+  timestamp?: unknown;
+  label?: unknown;
+  name?: unknown;
+  value?: unknown;
+};
+
+type RawChartSeries = {
+  name?: unknown;
+  data?: unknown;
+  points?: unknown;
+  values?: unknown;
+  type?: unknown;
+};
+
 export interface ChatInlineChartProps {
   title?: string;
   chart_type?: "line" | "bar" | "pie";
-  x_data?: string[];
-  series?: ChatChartSeries[];
+  x_data?: unknown;
+  series?: unknown;
   y_axis_name?: string;
   x_axis_name?: string;
+  isStreaming?: boolean;
 }
 
+export const CHART_HEIGHT = 240;
+export const CHART_MIN_HEIGHT = 286;
+
 const COLORS = [
   "#5470c6",
   "#91cc75",
@@ -37,28 +66,211 @@ const COLORS = [
   "#ea7ccc",
 ];
 
+const ChartSkeletonContent = ({ status }: { status?: React.ReactNode }) => (
+  <Stack spacing={1.25} sx={{ p: 1.5 }}>
+    <Stack direction="row" alignItems="center" justifyContent="space-between">
+      <Skeleton variant="text" width="34%" height={20} />
+      {status}
+    </Stack>
+    <Skeleton variant="rounded" height={208} sx={{ borderRadius: 2 }} />
+    <Stack direction="row" spacing={1}>
+      <Skeleton variant="text" width="24%" height={16} />
+      <Skeleton variant="text" width="18%" height={16} />
+      <Skeleton variant="text" width="20%" height={16} />
+    </Stack>
+  </Stack>
+);
+
+export const ChartGenerationSkeleton = ({ status }: { status?: React.ReactNode }) => {
+  const theme = useTheme();
+
+  return (
+    <motion.div
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      transition={{ duration: 0.18 }}
+      style={{ width: "100%" }}
+    >
+      <Paper
+        elevation={0}
+        sx={{
+          mt: 1.5,
+          mb: 1,
+          minHeight: CHART_MIN_HEIGHT,
+          borderRadius: 3,
+          border: `1px solid ${alpha(theme.palette.divider, 0.12)}`,
+          bgcolor: alpha("#fff", 0.78),
+          overflow: "hidden",
+        }}
+      >
+        <ChartSkeletonContent status={status} />
+      </Paper>
+    </motion.div>
+  );
+};
+
+const toFiniteNumber = (value: unknown): number | null => {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+};
+
+export const pointToLabelValue = (
+  point: RawChartPoint,
+  fallbackLabel: string,
+): { label: string; value: number } | null => {
+  const directValue = toFiniteNumber(point);
+  if (directValue !== null) {
+    return { label: fallbackLabel, value: directValue };
+  }
+
+  if (Array.isArray(point)) {
+    const value = toFiniteNumber(point[1]);
+    if (value === null) return null;
+    return { label: String(point[0] ?? fallbackLabel), value };
+  }
+
+  if (point && typeof point === "object") {
+    const value = toFiniteNumber(point.value ?? point.y);
+    if (value === null) return null;
+    const label =
+      point.x ?? point.time ?? point.timestamp ?? point.label ?? point.name ?? fallbackLabel;
+    return { label: String(label), value };
+  }
+
+  return null;
+};
+
+const normalizeXData = (rawXData: unknown): string[] =>
+  Array.isArray(rawXData)
+    ? rawXData.map((item) => String(item ?? "")).filter((item) => item.length > 0)
+    : [];
+
+const normalizeSeriesType = (type: unknown): "line" | "bar" | undefined =>
+  type === "line" || type === "bar" ? type : undefined;
+
+const isRawChartPoint = (item: unknown): boolean => {
+  if (toFiniteNumber(item) !== null) return true;
+  if (Array.isArray(item)) return item.length >= 2 && toFiniteNumber(item[1]) !== null;
+  if (item && typeof item === "object") {
+    const rawItem = item as RawChartSeries & RawChartPointObject;
+    return (
+      rawItem.data === undefined &&
+      rawItem.points === undefined &&
+      rawItem.values === undefined &&
+      toFiniteNumber(rawItem.value ?? rawItem.y) !== null
+    );
+  }
+  return false;
+};
+
+const normalizeRawSeriesItems = (rawSeries: unknown): unknown[] => {
+  if (!Array.isArray(rawSeries)) {
+    return rawSeries && typeof rawSeries === "object" ? [rawSeries] : [];
+  }
+
+  return rawSeries.length > 0 && rawSeries.every(isRawChartPoint)
+    ? [{ name: "数据", data: rawSeries }]
+    : rawSeries;
+};
+
+export const normalizeChartData = (
+  rawXData: unknown,
+  rawSeries: unknown,
+): { xData: string[]; series: ChatChartSeries[] } => {
+  const xData = normalizeXData(rawXData);
+  const rawSeriesItems = normalizeRawSeriesItems(rawSeries);
+  if (!rawSeriesItems.length) {
+    return { xData, series: [] };
+  }
+
+  const normalizedSeries = rawSeriesItems
+    .map((rawItem, seriesIndex): ChatChartSeries | null => {
+      const item =
+        rawItem && typeof rawItem === "object" && !Array.isArray(rawItem)
+          ? (rawItem as RawChartSeries)
+          : ({ data: rawItem } satisfies RawChartSeries);
+      const rawData = item.data ?? item.points ?? item.values;
+      if (!Array.isArray(rawData)) return null;
+
+      const labelsFromPoints: string[] = [];
+      const data = rawData
+        .map((point, index) => {
+          const parsed = pointToLabelValue(
+            point as RawChartPoint,
+            xData[index] ?? `${index + 1}`,
+          );
+          if (!parsed) return null;
+          labelsFromPoints[index] = parsed.label;
+          return parsed.value;
+        })
+        .filter((value): value is number => value !== null);
+
+      if (!data.length) return null;
+      if (!xData.length && labelsFromPoints.length) {
+        xData.push(...labelsFromPoints);
+      }
+
+      return {
+        name:
+          typeof item.name === "string" && item.name.trim()
+            ? item.name
+            : `系列 ${seriesIndex + 1}`,
+        data,
+        type: normalizeSeriesType(item.type),
+      };
+    })
+    .filter((item): item is ChatChartSeries => Boolean(item));
+
+  return { xData, series: normalizedSeries };
+};
+
 export const ChatInlineChart: React.FC<ChatInlineChartProps> = ({
   title,
   chart_type: chartType = "line",
-  x_data: xData,
-  series = [],
+  x_data,
+  series,
   y_axis_name: yAxisName,
   x_axis_name: xAxisName,
+  isStreaming = false,
 }) => {
   const theme = useTheme();
+  const [showIntroSkeleton, setShowIntroSkeleton] = React.useState(true);
+  const { xData, series: chartSeries } = useMemo(
+    () => normalizeChartData(x_data, series),
+    [x_data, series],
+  );
+
+  React.useEffect(() => {
+    const timer = window.setTimeout(() => {
+      setShowIntroSkeleton(false);
+    }, isStreaming ? 360 : 260);
+
+    return () => window.clearTimeout(timer);
+  }, [isStreaming]);
 
   const option = useMemo(() => {
-    if (!series.length) return null;
+    if (!chartSeries.length) return null;
 
     /* ---------- Pie chart ---------- */
     if (chartType === "pie") {
       const pieData =
-        series[0]?.data.map((value, i) => ({
+        chartSeries[0]?.data.map((value, i) => ({
           name: xData?.[i] ?? `${i}`,
           value,
         })) ?? [];
 
       return {
+        animation: true,
+        animationDuration: isStreaming ? 560 : 420,
+        animationDurationUpdate: 240,
+        animationEasing: "cubicOut",
+        animationEasingUpdate: "cubicOut",
         tooltip: { trigger: "item" },
         legend: { top: "bottom", textStyle: { fontSize: 11 } },
         series: [
@@ -74,6 +286,10 @@ export const ChatInlineChart: React.FC<ChatInlineChartProps> = ({
               },
             },
             label: { fontSize: 11 },
+            animationType: "expansion",
+            animationDuration: isStreaming ? 560 : 420,
+            animationDelay: (idx: number) => idx * 40,
+            animationDurationUpdate: 240,
           },
         ],
         color: COLORS,
@@ -82,6 +298,11 @@ export const ChatInlineChart: React.FC<ChatInlineChartProps> = ({
 
     /* ---------- Line / Bar chart ---------- */
     return {
+      animation: true,
+      animationDuration: isStreaming ? 560 : 420,
+      animationDurationUpdate: 240,
+      animationEasing: "cubicOut",
+      animationEasingUpdate: "cubicOut",
       tooltip: { trigger: "axis", confine: true },
       legend: { top: "top", textStyle: { fontSize: 11 } },
       grid: {
@@ -111,16 +332,24 @@ export const ChatInlineChart: React.FC<ChatInlineChartProps> = ({
         xData && xData.length > 20
           ? [{ type: "inside", start: 0, end: 100 }]
           : undefined,
-      series: series.map((s, i) => {
+      series: chartSeries.map((s, i) => {
         const color = COLORS[i % COLORS.length];
+        const isLineSeries = chartType === "line";
         return {
           name: s.name,
           type: (s.type ?? chartType) as string,
           data: s.data,
-          symbol: chartType === "line" ? "none" : undefined,
-          smooth: chartType === "line",
+          symbol: isLineSeries ? "none" : undefined,
+          smooth: isLineSeries,
           itemStyle: { color },
-          ...(chartType === "line"
+          animationDuration: isStreaming ? 560 : 420,
+          animationDurationUpdate: 240,
+          animationDelay:
+            chartType === "bar"
+              ? (idx: number) => i * 80 + idx * 18
+              : i * 80,
+          animationDelayUpdate: 0,
+          ...(isLineSeries
             ? {
                 areaStyle: {
                   color: new echarts.graphic.LinearGradient(0, 0, 0, 1, [
@@ -135,44 +364,96 @@ export const ChatInlineChart: React.FC<ChatInlineChartProps> = ({
       }),
       color: COLORS,
     };
-  }, [chartType, xData, series, title, yAxisName, xAxisName]);
+  }, [chartType, xData, chartSeries, title, yAxisName, xAxisName, isStreaming]);
 
   if (!option) {
     return (
-      <Typography variant="caption" color="text.secondary" sx={{ mt: 1 }}>
-        图表数据为空
-      </Typography>
+      <Paper
+        elevation={0}
+        sx={{
+          mt: 1.5,
+          mb: 1,
+          minHeight: 72,
+          display: "flex",
+          alignItems: "center",
+          px: 2,
+          borderRadius: 3,
+          border: `1px solid ${alpha(theme.palette.divider, 0.12)}`,
+          bgcolor: alpha("#fff", 0.72),
+        }}
+      >
+        <Typography variant="caption" color="text.secondary">
+          图表数据为空
+        </Typography>
+      </Paper>
     );
   }
 
   return (
-    <Paper
-      elevation={0}
-      sx={{
-        mt: 1.5,
-        mb: 1,
-        borderRadius: 3,
-        border: `1px solid ${alpha(theme.palette.divider, 0.15)}`,
-        bgcolor: alpha("#fff", 0.92),
-        overflow: "hidden",
-      }}
+    <motion.div
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      transition={{ duration: 0.22, ease: "easeOut" }}
+      style={{ width: "100%" }}
     >
-      {title && (
-        <Typography
-          variant="subtitle2"
-          sx={{ px: 2, pt: 1.5, fontWeight: 600, color: "text.primary" }}
+      <Paper
+        elevation={0}
+        sx={{
+          mt: 1.5,
+          mb: 1,
+          minHeight: CHART_MIN_HEIGHT,
+          borderRadius: 3,
+          border: `1px solid ${alpha(theme.palette.divider, 0.15)}`,
+          bgcolor: alpha("#fff", 0.92),
+          overflow: "hidden",
+          position: "relative",
+        }}
+      >
+        <AnimatePresence initial={false}>
+          {showIntroSkeleton ? (
+            <Box
+              key="chart-intro-skeleton"
+              component={motion.div}
+              aria-hidden
+              initial={{ opacity: 1 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+              transition={{ duration: 0.22, ease: "easeOut" }}
+              sx={{
+                position: "absolute",
+                inset: 0,
+                zIndex: 2,
+                bgcolor: alpha("#fff", 0.92),
+                pointerEvents: "none",
+              }}
+            >
+              <ChartSkeletonContent />
+            </Box>
+          ) : null}
+        </AnimatePresence>
+        {title && (
+          <Typography
+            variant="subtitle2"
+            sx={{ px: 2, pt: 1.5, fontWeight: 600, color: "text.primary" }}
+          >
+            {title}
+          </Typography>
+        )}
+        <Box
+          component={motion.div}
+          initial={{ opacity: 0 }}
+          animate={{ opacity: showIntroSkeleton ? 0.35 : 1 }}
+          transition={{ duration: 0.24, ease: "easeOut" }}
+          sx={{ px: 1, pb: 1, minHeight: CHART_HEIGHT }}
         >
-          {title}
-        </Typography>
-      )}
-      <Box sx={{ px: 1, pb: 1 }}>
-        <ReactECharts
-          option={option}
-          style={{ height: 240, width: "100%" }}
-          notMerge
-          lazyUpdate
-        />
-      </Box>
-    </Paper>
+          <ReactECharts
+            option={option}
+            style={{ height: CHART_HEIGHT, width: "100%" }}
+            notMerge
+            lazyUpdate
+          />
+        </Box>
+      </Paper>
+    </motion.div>
   );
 };

src/components/chat/ChatToolCallBlock.tsx

@@ -118,6 +118,12 @@ const TOOL_META: Record<string, ToolMeta> = {
     actionLabel: "定位到地图",
     color: "#3ba272",
   },
+  zoom_to_map: {
+    label: "缩放到坐标",
+    icon: <LocationOnRounded sx={{ fontSize: 18 }} />,
+    actionLabel: "缩放到地图",
+    color: "#0ea5e9",
+  },
   view_history: {
     label: "查看计算结果",
     icon: <TimelineRounded sx={{ fontSize: 18 }} />,
@@ -176,6 +182,46 @@ function normalizeLocateIds(params: Record<string, unknown>): string[] {
   return [];
 }
 
+function readFiniteNumber(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+function buildZoomTo3857Action(
+  params: Record<string, unknown>,
+): Extract<ChatToolAction, { type: "zoom_to_map" }> | null {
+  const rawCoordinate = params.coordinate ?? params.coordinates ?? params.center;
+  const tuple = Array.isArray(rawCoordinate)
+    ? rawCoordinate
+    : [params.x ?? params.lon ?? params.longitude, params.y ?? params.lat ?? params.latitude];
+  const x = readFiniteNumber(tuple[0]);
+  const y = readFiniteNumber(tuple[1]);
+  if (x === null || y === null) {
+    return null;
+  }
+
+  const zoom = readFiniteNumber(params.zoom);
+  const durationMs = readFiniteNumber(params.duration_ms ?? params.durationMs);
+  const rawSourceCrs = params.source_crs ?? params.sourceCrs ?? params.crs;
+  const normalizedSourceCrs =
+    typeof rawSourceCrs === "string" ? rawSourceCrs.trim().toUpperCase() : "";
+  const sourceCrs =
+    normalizedSourceCrs === "EPSG:4326" ? "EPSG:4326" : "EPSG:3857";
+  return {
+    type: "zoom_to_map",
+    coordinate: [x, y],
+    sourceCrs,
+    zoom: zoom ?? undefined,
+    durationMs: durationMs ?? undefined,
+  };
+}
+
 function getToolDescription(toolCall: ToolCall): string {
   const { params } = toolCall;
   const resolveScadaFeatureInfos = (): [string, string][] => {
@@ -281,6 +327,14 @@ function getToolDescription(toolCall: ToolCall): string {
     case "render_junctions": {
       return (params.render_ref as string | undefined) ?? "渲染引用";
     }
+    case "zoom_to_map": {
+      const action = buildZoomTo3857Action(params);
+      if (!action) {
+        return "地图坐标";
+      }
+      const zoom = action.zoom === undefined ? "" : ` · zoom ${action.zoom}`;
+      return `${action.coordinate[0]}, ${action.coordinate[1]} · ${action.sourceCrs}${zoom}`;
+    }
     case APPLY_LAYER_STYLE_TOOL: {
       const payload = parseApplyLayerStylePayload(params);
       return payload ? describeApplyLayerStyle(payload) : "图层样式";
@@ -341,6 +395,8 @@ function buildAction(toolCall: ToolCall): ChatToolAction | null {
       (params.end as string | undefined),
   });
   switch (toolCall.tool) {
+    case "zoom_to_map":
+      return buildZoomTo3857Action(params);
     case "locate_features": {
       const featureTypeRaw = params.feature_type;
       const featureType =

src/components/chat/GlobalChatbox.test.tsx

@@ -0,0 +1,194 @@
+import "@testing-library/jest-dom";
+import React from "react";
+import { act, render, screen } from "@testing-library/react";
+
+import { GlobalChatbox } from "./GlobalChatbox";
+
+const createSession = jest.fn();
+const mockFetchAgentRuntimeHealth = jest.fn();
+const mockFetchAgentModels = jest.fn();
+let mockCurrentProjectId = "project-1";
+
+jest.mock("@refinedev/core", () => ({
+  useNotification: () => ({ open: jest.fn() }),
+}));
+
+jest.mock("@/lib/chatModels", () => ({
+  fetchAgentModels: (...args: unknown[]) => mockFetchAgentModels(...args),
+}));
+
+jest.mock("@/lib/agentRuntime", () => ({
+  fetchAgentRuntimeHealth: (...args: unknown[]) =>
+    mockFetchAgentRuntimeHealth(...args),
+}));
+
+jest.mock("@/store/projectStore", () => ({
+  useProjectStore: (selector: (state: { currentProjectId: string }) => unknown) =>
+    selector({ currentProjectId: mockCurrentProjectId }),
+}));
+
+jest.mock("./globalChatboxVoice", () => ({
+  useSpeechSynthesis: () => ({
+    speechState: "idle",
+    speakingMessageId: null,
+    speak: jest.fn(),
+    pause: jest.fn(),
+    resume: jest.fn(),
+    stop: jest.fn(),
+    isSupported: true,
+  }),
+  useSpeechRecognition: () => ({
+    isListening: false,
+    start: jest.fn(),
+    stop: jest.fn(),
+    isSupported: true,
+  }),
+}));
+
+jest.mock("./hooks/useAgentToolActions", () => ({
+  useAgentToolActions: () => jest.fn(),
+}));
+
+jest.mock("./hooks/useAgentChatSession", () => ({
+  useAgentChatSession: () => ({
+    messages: [],
+    chatSessions: [],
+    activeSessionId: undefined,
+    isHydrating: false,
+    loadingSessionId: null,
+    isStreaming: false,
+    sessionTitle: "新会话",
+    sendPrompt: jest.fn(),
+    createBranch: jest.fn(),
+    abort: jest.fn(),
+    replyPermission: jest.fn(),
+    replyQuestion: jest.fn(),
+    rejectQuestion: jest.fn(),
+    createSession,
+    renameSession: jest.fn(),
+    removeSession: jest.fn(),
+    switchSession: jest.fn(),
+  }),
+}));
+
+jest.mock("./AgentHeader", () => ({
+  AgentHeader: () => <div>Agent header</div>,
+}));
+
+jest.mock("./AgentHistoryPanel", () => ({
+  AgentHistoryPanel: () => <div>History</div>,
+}));
+
+jest.mock("./AgentWorkspace", () => ({
+  AgentWorkspace: ({ runtimeState }: { runtimeState: string }) => (
+    <div data-testid="agent-workspace">Workspace state: {runtimeState}</div>
+  ),
+}));
+
+jest.mock("./AgentComposer", () => ({
+  AgentComposer: React.forwardRef(function MockAgentComposer(props: { approvalMode: string }, _ref) {
+    return <div>Composer mode: {props.approvalMode}</div>;
+  }),
+}));
+
+jest.mock("./GlobalChatboxParts", () => ({
+  Blob: () => null,
+}));
+
+describe("GlobalChatbox lifecycle", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    createSession.mockClear();
+    mockFetchAgentRuntimeHealth.mockReset();
+    mockFetchAgentRuntimeHealth.mockImplementation(() => new Promise(() => {}));
+    mockFetchAgentModels.mockReset();
+    mockFetchAgentModels.mockImplementation(() => new Promise(() => {}));
+    mockCurrentProjectId = "project-1";
+  });
+
+  afterEach(() => {
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  it("keeps content mounted and preserves the session across close and reopen", async () => {
+    const { rerender } = render(<GlobalChatbox open onClose={jest.fn()} />);
+
+    act(() => jest.runOnlyPendingTimers());
+    expect(createSession).toHaveBeenCalledTimes(1);
+    expect(screen.getByTestId("agent-workspace")).toBeInTheDocument();
+
+    rerender(<GlobalChatbox open={false} onClose={jest.fn()} />);
+    act(() => jest.advanceTimersByTime(300));
+
+    expect(screen.getByTestId("agent-workspace")).toBeInTheDocument();
+
+    rerender(<GlobalChatbox open onClose={jest.fn()} />);
+    act(() => jest.runOnlyPendingTimers());
+
+    expect(createSession).toHaveBeenCalledTimes(1);
+
+    mockCurrentProjectId = "project-2";
+    rerender(<GlobalChatbox open onClose={jest.fn()} />);
+    act(() => jest.runOnlyPendingTimers());
+
+    expect(createSession).toHaveBeenCalledTimes(2);
+  });
+
+  it("defaults the composer to automatic permission approval", () => {
+    render(<GlobalChatbox open onClose={jest.fn()} />);
+
+    expect(screen.getByText("Composer mode: auto")).toBeInTheDocument();
+  });
+
+  it("passes backend startup failures into the existing workspace empty state", async () => {
+    mockFetchAgentRuntimeHealth.mockResolvedValueOnce(false);
+    render(<GlobalChatbox open onClose={jest.fn()} />);
+
+    await act(async () => Promise.resolve());
+
+    expect(screen.getByText("Workspace state: unavailable")).toBeInTheDocument();
+  });
+
+  it("reserves models unavailable for an empty model configuration", async () => {
+    mockFetchAgentRuntimeHealth.mockResolvedValueOnce(true);
+    mockFetchAgentModels.mockResolvedValueOnce({ models: [] });
+    render(<GlobalChatbox open onClose={jest.fn()} />);
+
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(screen.getByText("Workspace state: models_unavailable")).toBeInTheDocument();
+  });
+
+  it("reports an auth dependency failure as unavailable and retries quickly", async () => {
+    jest.spyOn(console, "error").mockImplementation(() => undefined);
+    mockFetchAgentRuntimeHealth.mockResolvedValue(true);
+    mockFetchAgentModels
+      .mockRejectedValueOnce(new Error("authentication service unavailable"))
+      .mockResolvedValueOnce({
+        defaultModel: "provider/model",
+        models: [{ id: "provider/model", label: "Model" }],
+      });
+
+    render(<GlobalChatbox open onClose={jest.fn()} />);
+
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(screen.getByText("Workspace state: unavailable")).toBeInTheDocument();
+    expect(mockFetchAgentModels).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      jest.advanceTimersByTime(5_000);
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(screen.getByText("Workspace state: ready")).toBeInTheDocument();
+    expect(mockFetchAgentModels).toHaveBeenCalledTimes(2);
+  });
+});

src/components/chat/GlobalChatbox.tsx

@@ -7,33 +7,54 @@ import React, {
   useState,
 } from "react";
 import { Box, Drawer, alpha, useTheme } from "@mui/material";
+import { useNotification } from "@refinedev/core";
 
-import type { AgentModel } from "@/lib/chatStream";
+import { getAccessToken } from "@/lib/authToken";
+import {
+  fetchAgentRuntimeHealth,
+  type AgentRuntimeState,
+} from "@/lib/agentRuntime";
+import { fetchAgentModels, type AgentModelOption } from "@/lib/chatModels";
+import type { AgentApprovalMode, AgentModel } from "@/lib/chatStream";
 import { useProjectStore } from "@/store/projectStore";
-import { AgentComposer } from "./AgentComposer";
+import { AgentComposer, type AgentComposerHandle } from "./AgentComposer";
 import { AgentHeader } from "./AgentHeader";
 import { AgentHistoryPanel } from "./AgentHistoryPanel";
 import { AgentWorkspace } from "./AgentWorkspace";
-import { Blob } from "./GlobalChatbox.parts";
+import { Blob } from "./GlobalChatboxParts";
 import type { Props } from "./GlobalChatbox.types";
-import { PRESET_PROMPTS } from "./GlobalChatbox.utils";
-import { useSpeechRecognition, useSpeechSynthesis } from "./GlobalChatbox.voice";
+import { PRESET_PROMPTS } from "./globalChatboxUtils";
+import { useSpeechRecognition, useSpeechSynthesis } from "./globalChatboxVoice";
 import { useAgentChatSession } from "./hooks/useAgentChatSession";
 import { useAgentToolActions } from "./hooks/useAgentToolActions";
 
+const STREAMING_BOTTOM_RESERVE_PX = 180;
+const STREAMING_SCROLL_RESTORE_AT_PX = STREAMING_BOTTOM_RESERVE_PX - 36;
+const AGENT_RUNTIME_POLL_MS = 30_000;
+const AGENT_RUNTIME_RETRY_MS = 5_000;
+const AGENT_RUNTIME_TIMEOUT_MS = 8_000;
+
 export const GlobalChatbox: React.FC<Props> = ({ open, onClose }) => {
-  const [input, setInput] = useState("");
   const [width, setWidth] = useState(520);
   const [isResizing, setIsResizing] = useState(false);
   const [isHistoryOpen, setIsHistoryOpen] = useState(false);
-  const [selectedModel, setSelectedModel] = useState<AgentModel>(
-    "deepseek/deepseek-v4-pro",
-  );
+  const [isCheckingAuth, setIsCheckingAuth] = useState(false);
+  const [modelOptions, setModelOptions] = useState<AgentModelOption[]>([]);
+  const [selectedModel, setSelectedModel] = useState<AgentModel | undefined>(undefined);
+  const [runtimeState, setRuntimeState] = useState<AgentRuntimeState>("checking");
+  const [approvalMode, setApprovalMode] =
+    useState<AgentApprovalMode>("auto");
 
   const bottomRef = useRef<HTMLDivElement>(null);
-  const inputRef = useRef<HTMLInputElement | null>(null);
-  const hasResetForOpenRef = useRef(false);
+  const workspaceScrollRef = useRef<HTMLDivElement>(null);
+  const isNearBottomRef = useRef(true);
+  const streamingScrollFrameRef = useRef<number | null>(null);
+  const composerRef = useRef<AgentComposerHandle | null>(null);
+  const initializedProjectIdRef = useRef<string | null | undefined>(undefined);
+  const runtimeRequestIdRef = useRef(0);
+  const runtimeAbortRef = useRef<AbortController | null>(null);
   const theme = useTheme();
+  const { open: openNotification } = useNotification();
   const currentProjectId = useProjectStore((state) => state.currentProjectId);
 
   const {
@@ -47,7 +68,7 @@ export const GlobalChatbox: React.FC<Props> = ({ open, onClose }) => {
   } = useSpeechSynthesis();
 
   const handleSpeechResult = useCallback((text: string) => {
-    setInput((prev) => prev + text);
+    composerRef.current?.append(text);
   }, []);
 
   const {
@@ -57,21 +78,103 @@ export const GlobalChatbox: React.FC<Props> = ({ open, onClose }) => {
     isSupported: isSttSupported,
   } = useSpeechRecognition(handleSpeechResult);
 
+  const refreshAgentRuntime = useCallback(async (showChecking = true) => {
+    const requestId = ++runtimeRequestIdRef.current;
+    runtimeAbortRef.current?.abort();
+    const controller = new AbortController();
+    runtimeAbortRef.current = controller;
+    const timeoutId = window.setTimeout(
+      () => controller.abort(),
+      AGENT_RUNTIME_TIMEOUT_MS,
+    );
+    let runtimeHealthy = false;
+
+    if (showChecking) setRuntimeState("checking");
+
+    try {
+      runtimeHealthy = await fetchAgentRuntimeHealth(controller.signal);
+      if (requestId !== runtimeRequestIdRef.current) return;
+      if (!runtimeHealthy) {
+        setRuntimeState("unavailable");
+        setModelOptions([]);
+        setSelectedModel(undefined);
+        return "unavailable" as const;
+      }
+
+      const modelConfig = await fetchAgentModels(controller.signal);
+      if (requestId !== runtimeRequestIdRef.current) return;
+      if (modelConfig.models.length === 0) {
+        setRuntimeState("models_unavailable");
+        setModelOptions([]);
+        setSelectedModel(undefined);
+        return "models_unavailable" as const;
+      }
+
+      setModelOptions(modelConfig.models);
+      setSelectedModel((current) => {
+        if (current && modelConfig.models.some((model) => model.id === current)) {
+          return current;
+        }
+        return modelConfig.defaultModel;
+      });
+      setRuntimeState("ready");
+      return "ready" as const;
+    } catch (error) {
+      if (requestId !== runtimeRequestIdRef.current) return;
+      console.error("[GlobalChatbox] Failed to check agent runtime:", error);
+      setRuntimeState("unavailable");
+      setModelOptions([]);
+      setSelectedModel(undefined);
+      return "unavailable" as const;
+    } finally {
+      window.clearTimeout(timeoutId);
+      if (runtimeAbortRef.current === controller) {
+        runtimeAbortRef.current = null;
+      }
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!open) return;
+
+    let cancelled = false;
+    let pollTimerId: number | undefined;
+
+    const pollRuntime = async (showChecking: boolean) => {
+      const nextState = await refreshAgentRuntime(showChecking);
+      if (cancelled || !nextState) return;
+      pollTimerId = window.setTimeout(
+        () => void pollRuntime(false),
+        nextState === "ready" ? AGENT_RUNTIME_POLL_MS : AGENT_RUNTIME_RETRY_MS,
+      );
+    };
+
+    void pollRuntime(true);
+
+    return () => {
+      cancelled = true;
+      if (pollTimerId !== undefined) window.clearTimeout(pollTimerId);
+      runtimeRequestIdRef.current += 1;
+      runtimeAbortRef.current?.abort();
+      runtimeAbortRef.current = null;
+    };
+  }, [open, refreshAgentRuntime]);
+
   const handleToolCall = useAgentToolActions();
   const {
     messages,
     chatSessions,
-    activeStorageSessionId,
-    branchGroups,
-    branchTransition,
+    activeSessionId,
     isHydrating,
+    loadingSessionId,
     isStreaming,
     sessionTitle,
     sendPrompt,
-    regenerate,
-    editAndResubmit,
-    cycleBranch,
+    createBranch,
     abort,
+    replyPermission,
+    replyQuestion,
+    rejectQuestion,
     createSession,
     renameSession,
     removeSession,
@@ -81,86 +184,154 @@ export const GlobalChatbox: React.FC<Props> = ({ open, onClose }) => {
     onToolCall: handleToolCall,
     onBeforeSend: stopListening,
     getModel: () => selectedModel,
+    getApprovalMode: () => approvalMode,
   });
 
-  useEffect(() => {
-    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
-  }, [messages, isStreaming]);
+  const scrollToBottom = useCallback((behavior: ScrollBehavior = "smooth") => {
+    bottomRef.current?.scrollIntoView({ behavior });
+  }, []);
+
+  const cancelStreamingScroll = useCallback(() => {
+    if (streamingScrollFrameRef.current === null) return;
+    window.cancelAnimationFrame(streamingScrollFrameRef.current);
+    streamingScrollFrameRef.current = null;
+  }, []);
+
+  const scheduleStreamingScrollToBottom = useCallback(() => {
+    if (streamingScrollFrameRef.current !== null) return;
+    streamingScrollFrameRef.current = window.requestAnimationFrame(() => {
+      streamingScrollFrameRef.current = null;
+      const container = workspaceScrollRef.current;
+      if (!container || !isNearBottomRef.current) return;
+
+      const distanceToBottom =
+        container.scrollHeight - container.scrollTop - container.clientHeight;
+      if (distanceToBottom < STREAMING_SCROLL_RESTORE_AT_PX) return;
+
+      container.scrollTop = container.scrollHeight - container.clientHeight;
+    });
+  }, []);
+
+  const handleWorkspaceScrollStateChange = useCallback((isNearBottom: boolean) => {
+    isNearBottomRef.current = isNearBottom;
+  }, []);
+
+  const resetConversationView = useCallback(() => {
+    composerRef.current?.clear();
+    setIsHistoryOpen(false);
+    window.setTimeout(() => {
+      composerRef.current?.focus();
+      isNearBottomRef.current = true;
+      cancelStreamingScroll();
+      scrollToBottom("auto");
+    }, 0);
+  }, [cancelStreamingScroll, scrollToBottom]);
 
   useEffect(() => {
-    if (!open) {
-      hasResetForOpenRef.current = false;
+    if (isStreaming) {
+      if (!isNearBottomRef.current) return;
+      scheduleStreamingScrollToBottom();
       return;
     }
-    if (hasResetForOpenRef.current || isHydrating) return;
-    hasResetForOpenRef.current = true;
+    cancelStreamingScroll();
+    scrollToBottom("smooth");
+  }, [
+    cancelStreamingScroll,
+    isStreaming,
+    messages,
+    scheduleStreamingScrollToBottom,
+    scrollToBottom,
+  ]);
 
-    const timer = window.setTimeout(() => {
-      createSession();
-      setInput("");
-      setIsHistoryOpen(false);
-      inputRef.current?.focus();
-      bottomRef.current?.scrollIntoView({ behavior: "auto" });
-    }, 0);
-    return () => window.clearTimeout(timer);
-  }, [createSession, isHydrating, open]);
+  useEffect(
+    () => () => {
+      cancelStreamingScroll();
+    },
+    [cancelStreamingScroll],
+  );
 
-  const handleSend = useCallback(() => {
-    const prompt = input.trim();
-    if (!prompt || isStreaming) return;
-    setInput("");
-    void sendPrompt(prompt);
-  }, [input, isStreaming, sendPrompt]);
+  useEffect(() => {
+    if (
+      !open ||
+      isHydrating ||
+      initializedProjectIdRef.current === currentProjectId
+    ) {
+      return;
+    }
 
-  const handlePresetPromptSelect = useCallback((prompt: string) => {
-    setInput(prompt);
-    window.setTimeout(() => {
-      inputRef.current?.focus();
-    }, 0);
-  }, []);
+    initializedProjectIdRef.current = currentProjectId;
+    createSession();
+    resetConversationView();
+  }, [createSession, currentProjectId, isHydrating, open, resetConversationView]);
+
+  const handleSend = useCallback(async (prompt: string) => {
+    if (isStreaming || isCheckingAuth || runtimeState !== "ready") return;
+
+    setIsCheckingAuth(true);
+    try {
+      const accessToken = await getAccessToken();
+      if (!accessToken) {
+        composerRef.current?.setValue(prompt);
+        openNotification?.({
+          type: "error",
+          message: "登录状态已失效",
+          description: "请重新登录后再发送对话。",
+        });
+        return;
+      }
+
+      void sendPrompt(prompt);
+    } catch (error) {
+      composerRef.current?.setValue(prompt);
+      openNotification?.({
+        type: "error",
+        message: "登录状态校验失败",
+        description: error instanceof Error ? error.message : "请重新登录后再试。",
+      });
+    } finally {
+      setIsCheckingAuth(false);
+    }
+  }, [isCheckingAuth, isStreaming, openNotification, runtimeState, sendPrompt]);
 
   const handleNewConversation = useCallback(() => {
     handleStopSpeech();
     stopListening();
     createSession();
-    setInput("");
-    window.setTimeout(() => {
-      inputRef.current?.focus();
-    }, 0);
-  }, [createSession, handleStopSpeech, stopListening]);
+    resetConversationView();
+  }, [createSession, handleStopSpeech, resetConversationView, stopListening]);
 
   const handleHistoryToggle = useCallback(() => {
     setIsHistoryOpen((prev) => !prev);
   }, []);
 
   const handleSelectSession = useCallback(
-    (storageSessionId: string) => {
-      setInput("");
-      void switchSession(storageSessionId);
+    (sessionId: string, title: string) => {
+      composerRef.current?.clear();
+      void switchSession(sessionId, title);
     },
     [switchSession],
   );
 
   const handleDeleteSession = useCallback(
-    (storageSessionId: string) => {
-      void removeSession(storageSessionId);
+    (sessionId: string) => {
+      void removeSession(sessionId);
     },
     [removeSession],
   );
 
   const handleRenameSession = useCallback(
-    (storageSessionId: string, title: string) => {
-      void renameSession(storageSessionId, title);
+    (sessionId: string, title: string) => {
+      void renameSession(sessionId, title);
     },
     [renameSession],
   );
 
   const handleRenameActiveSession = useCallback(
     (title: string) => {
-      if (!activeStorageSessionId) return;
-      void renameSession(activeStorageSessionId, title);
+      if (!activeSessionId) return;
+      void renameSession(activeSessionId, title);
     },
-    [activeStorageSessionId, renameSession],
+    [activeSessionId, renameSession],
   );
 
   const handleMouseDown = useCallback((event: React.MouseEvent) => {
@@ -201,6 +372,7 @@ export const GlobalChatbox: React.FC<Props> = ({ open, onClose }) => {
       hideBackdrop
       disableScrollLock
       disableEnforceFocus
+      ModalProps={{ keepMounted: true }}
       sx={{
         zIndex: (muiTheme) => muiTheme.zIndex.modal + 100,
         pointerEvents: "none",
@@ -260,9 +432,10 @@ export const GlobalChatbox: React.FC<Props> = ({ open, onClose }) => {
 
         <AgentHeader
           sessionTitle={sessionTitle}
-          canRenameSessionTitle={Boolean(activeStorageSessionId)}
+          canRenameSessionTitle={Boolean(activeSessionId)}
           isHydrating={isHydrating}
           isStreaming={isStreaming}
+          runtimeState={runtimeState}
           isHistoryOpen={isHistoryOpen}
           onHistoryToggle={handleHistoryToggle}
           onRenameSessionTitle={handleRenameActiveSession}
@@ -299,14 +472,16 @@ export const GlobalChatbox: React.FC<Props> = ({ open, onClose }) => {
           >
             <AgentHistoryPanel
               sessions={chatSessions}
-              activeSessionId={activeStorageSessionId}
+              activeSessionId={activeSessionId}
               isHydrating={isHydrating}
+              isLoadingSessions={isHydrating && chatSessions.length === 0}
+              loadingSessionId={loadingSessionId}
               onNewSession={() => {
                 handleNewConversation();
                 setIsHistoryOpen(false);
               }}
-              onSelectSession={(id) => {
-                handleSelectSession(id);
+              onSelectSession={(id, title) => {
+                handleSelectSession(id, title);
                 setIsHistoryOpen(false);
               }}
               onRenameSession={handleRenameSession}
@@ -317,10 +492,13 @@ export const GlobalChatbox: React.FC<Props> = ({ open, onClose }) => {
           <Box sx={{ flex: 1, display: "flex", minWidth: 0, flexDirection: "column" }}>
             <AgentWorkspace
               messages={messages}
-              branchGroups={branchGroups}
-              branchTransition={branchTransition}
               isStreaming={isStreaming}
+              runtimeState={runtimeState}
+              onRetryRuntime={() => void refreshAgentRuntime(true)}
+              isLoadingSession={Boolean(loadingSessionId)}
+              scrollContainerRef={workspaceScrollRef}
               bottomRef={bottomRef}
+              onScrollStateChange={handleWorkspaceScrollStateChange}
               speakingMessageId={speakingMessageId}
               speechState={speechState}
               onSpeak={handleSpeak}
@@ -328,27 +506,29 @@ export const GlobalChatbox: React.FC<Props> = ({ open, onClose }) => {
               onResumeSpeech={handleResumeSpeech}
               onStopSpeech={handleStopSpeech}
               isTtsSupported={isTtsSupported}
-              onRegenerate={regenerate}
-              onEditResubmit={editAndResubmit}
-              onCycleBranch={cycleBranch}
+              onCreateBranch={createBranch}
+              onReplyPermission={replyPermission}
+              onReplyQuestion={replyQuestion}
+              onRejectQuestion={rejectQuestion}
             />
 
             <AgentComposer
-              input={input}
-              inputRef={inputRef}
-              isHydrating={isHydrating}
+              ref={composerRef}
+              isHydrating={isHydrating || isCheckingAuth}
+              runtimeState={runtimeState}
               isStreaming={isStreaming}
               isListening={isListening}
               isSttSupported={isSttSupported}
               presets={PRESET_PROMPTS}
-              onInputChange={setInput}
               onSend={handleSend}
               onAbort={abort}
               onStartListening={startListening}
               onStopListening={stopListening}
-              onPresetSelect={handlePresetPromptSelect}
+              modelOptions={modelOptions}
               selectedModel={selectedModel}
               onModelChange={setSelectedModel}
+              approvalMode={approvalMode}
+              onApprovalModeChange={setApprovalMode}
             />
           </Box>
         </Box>

src/components/chat/GlobalChatbox.types.ts

@@ -1,3 +1,8 @@
+import type {
+  AgentQuestionRequest,
+  AgentTodoUpdate,
+} from "@/lib/chatStream";
+
 export type ChatProgress = {
   id: string;
   phase: string;
@@ -22,6 +27,32 @@ export type AgentArtifact = {
   params: Record<string, unknown>;
 };
 
+export type AgentPermissionStatus =
+  | "pending"
+  | "submitting"
+  | "approved_once"
+  | "approved_always"
+  | "rejected"
+  | "aborted"
+  | "error";
+
+export type AgentPermissionRequest = {
+  requestId: string;
+  sessionId: string;
+  permission: string;
+  patterns: string[];
+  target?: string;
+  always: string[];
+  tool?: {
+    messageID: string;
+    callID: string;
+  };
+  createdAt: number;
+  repliedAt?: number;
+  status: AgentPermissionStatus;
+  error?: string;
+};
+
 export type Message = {
   id: string;
   role: "user" | "assistant";
@@ -29,34 +60,9 @@ export type Message = {
   isError?: boolean;
   progress?: ChatProgress[];
   artifacts?: AgentArtifact[];
-  branchRootId?: string;
-};
-
-export type BranchState = {
-  activeIndex: number;
-  total: number;
-};
-
-export type MessageBranch = {
-  id: string;
-  label: string;
-  sessionId?: string;
-  messages: Message[];
-};
-
-export type BranchGroup = {
-  id: string;
-  rootMessageId: string;
-  parentCount: number;
-  activeIndex: number;
-  branches: MessageBranch[];
-};
-
-export type BranchTransition = {
-  rootMessageId: string;
-  parentCount: number;
-  activeBranchId: string;
-  nonce: number;
+  permissions?: AgentPermissionRequest[];
+  questions?: AgentQuestionRequest[];
+  todos?: AgentTodoUpdate;
 };
 
 export type Props = {
@@ -64,43 +70,22 @@ export type Props = {
   onClose: () => void;
 };
 
-export type SpeechState = "idle" | "playing" | "paused";
-
-export type LegacyPersistedChatState = {
-  messages: Message[];
-  sessionId?: string;
-  branchGroups?: BranchGroup[];
-};
-
-export type ChatSessionRecord = {
-  id: string;
-  title: string;
-  isTitleManuallyEdited?: boolean;
-  createdAt: number;
-  updatedAt: number;
-  sessionId?: string;
-  messages: Message[];
-  branchGroups: BranchGroup[];
-};
+export type SpeechState = "idle" | "loading" | "playing" | "paused";
 
 export type ChatSessionSummary = {
   id: string;
   title: string;
   createdAt: number;
   updatedAt: number;
-};
-
-export type ChatStorageMeta = {
-  key: "chat-meta";
-  activeSessionId?: string;
-  migratedFromLocalStorage?: boolean;
+  isStreaming?: boolean;
+  runStatus?: string;
 };
 
 export type LoadedChatState = {
-  storageSessionId?: string;
+  sessionId?: string;
   title?: string;
   isTitleManuallyEdited?: boolean;
   messages: Message[];
-  sessionId?: string;
-  branchGroups: BranchGroup[];
+  isStreaming?: boolean;
+  runStatus?: string;
 };

src/components/chat/GlobalChatbox.utils.ts

@@ -1,47 +0,0 @@
-import type { BranchGroup, Message } from "./GlobalChatbox.types";
-
-export const createId = () =>
-  `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-export const PRESET_PROMPTS = [
-  "分析当前管网中的水力瓶颈管道，并给出改造建议。",
-  "供水服务分区分析。",
-  "帮我分析当前管网压力异常点，并按风险等级排序。",
-  "帮我生成一份今日运行简报，包含问题、原因和建议。",
-  "查询关键 SCADA 点位最近 24 小时的异常波动。",
-  "排查当前管网爆管风险，并说明优先处置建议。",
-];
-
-export const stripMarkdown = (md: string): string =>
-  md
-    .replace(/```[\s\S]*?```/g, "")
-    .replace(/`([^`]+)`/g, "$1")
-    .replace(/!\[.*?\]\(.*?\)/g, "")
-    .replace(/\[([^\]]+)\]\(.*?\)/g, "$1")
-    .replace(/#{1,6}\s+/g, "")
-    .replace(/\*\*\*(.+?)\*\*\*/g, "$1")
-    .replace(/\*\*(.+?)\*\*/g, "$1")
-    .replace(/\*(.+?)\*/g, "$1")
-    .replace(/~~(.+?)~~/g, "$1")
-    .replace(/>\s+/g, "")
-    .replace(/[-*+]\s+/g, "")
-    .replace(/\d+\.\s+/g, "")
-    .replace(/\n{2,}/g, "\n")
-    .replace(/<[^>]+>/g, "")
-    .trim();
-
-export const cloneMessage = (message: Message): Message => ({
-  ...message,
-  progress: message.progress ? [...message.progress] : undefined,
-  artifacts: message.artifacts ? [...message.artifacts] : undefined,
-});
-
-export const cloneMessages = (messages: Message[]) => messages.map(cloneMessage);
-
-export const cloneBranchGroups = (branchGroups: BranchGroup[]) =>
-  branchGroups.map((group) => ({
-    ...group,
-    branches: group.branches.map((branch) => ({
-      ...branch,
-      messages: cloneMessages(branch.messages),
-    })),
-  }));

src/components/chat/GlobalChatbox.voice.ts

@@ -1,647 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from "react";
-import config from "@/config/config";
-import type { SpeechState } from "./GlobalChatbox.types";
-
-type AudioStreamStartResponse = {
-  stream_id?: string;
-  audio_url?: string;
-  status_url?: string;
-  result_url?: string;
-  sample_rate?: number;
-  channels?: number;
-  error?: string;
-};
-
-type AudioStreamStatusResponse = {
-  state?: "starting" | "running" | "done" | "failed" | "closed";
-  ready?: boolean;
-  failed?: boolean;
-  closed?: boolean;
-  status_text?: string;
-  error?: string;
-};
-
-type AudioStreamResultResponse = {
-  run_status?: string;
-  error?: string;
-};
-
-// WebKit Speech Recognition compatibility
-interface SpeechRecognitionEvent extends Event {
-  readonly resultIndex: number;
-  readonly results: SpeechRecognitionResultList;
-}
-
-interface SpeechRecognition extends EventTarget {
-  lang: string;
-  continuous: boolean;
-  interimResults: boolean;
-  onresult: ((event: SpeechRecognitionEvent) => void) | null;
-  onerror: ((event: Event) => void) | null;
-  onend: (() => void) | null;
-  start(): void;
-  stop(): void;
-  abort(): void;
-}
-
-declare global {
-  interface Window {
-    SpeechRecognition?: {
-      new (): SpeechRecognition;
-      prototype: SpeechRecognition;
-    };
-    webkitSpeechRecognition?: {
-      new (): SpeechRecognition;
-      prototype: SpeechRecognition;
-    };
-    webkitAudioContext?: typeof AudioContext;
-  }
-}
-
-export function useSpeechSynthesis() {
-  const [speechState, setSpeechState] = useState<SpeechState>("idle");
-  const [speakingMessageId, setSpeakingMessageId] = useState<string | null>(null);
-  const audioContextRef = useRef<AudioContext | null>(null);
-  const streamAbortControllerRef = useRef<AbortController | null>(null);
-  const activeSourceNodesRef = useRef<Set<AudioBufferSourceNode>>(new Set());
-  const streamIdRef = useRef<string | null>(null);
-  const closeUrlRef = useRef<string | null>(null);
-  const statusUrlRef = useRef<string | null>(null);
-  const resultUrlRef = useRef<string | null>(null);
-  const statusPollTimeoutRef = useRef<number | null>(null);
-  const playbackTokenRef = useRef(0);
-
-  const isSupported =
-    typeof window !== "undefined" &&
-    typeof window.FormData !== "undefined" &&
-    (typeof window.AudioContext !== "undefined" ||
-      typeof window.webkitAudioContext !== "undefined");
-
-  const trimTrailingSlash = useCallback((value: string) => value.replace(/\/+$/, ""), []);
-
-  const buildServiceUrl = useCallback(
-    (path: string) => `${trimTrailingSlash(config.AUDIO_SERVICE_URL)}${path.startsWith("/") ? path : `/${path}`}`,
-    [trimTrailingSlash],
-  );
-
-  const resolveServiceUrl = useCallback(
-    (pathOrUrl: string) => {
-      if (/^https?:\/\//i.test(pathOrUrl)) {
-        return pathOrUrl;
-      }
-      return buildServiceUrl(pathOrUrl);
-    },
-    [buildServiceUrl],
-  );
-
-  const withQueryParams = useCallback(
-    (urlString: string, params: Record<string, string>) => {
-      const url = new URL(urlString);
-      Object.entries(params).forEach(([key, value]) => {
-        url.searchParams.set(key, value);
-      });
-      return url.toString();
-    },
-    [],
-  );
-
-  const readErrorMessage = useCallback(async (response: Response, fallback: string) => {
-    try {
-      const payload = (await response.json()) as { error?: string; message?: string };
-      return payload.error || payload.message || fallback;
-    } catch {
-      return fallback;
-    }
-  }, []);
-
-  const closeStream = useCallback(async (closeUrl: string) => {
-    const response = await fetch(closeUrl, {
-      method: "POST",
-    });
-
-    if (!response.ok) {
-      console.error("[GlobalChatbox] Failed to close audio stream:", closeUrl);
-    }
-  }, []);
-
-  const stopStatusPolling = useCallback(() => {
-    if (statusPollTimeoutRef.current !== null) {
-      window.clearTimeout(statusPollTimeoutRef.current);
-      statusPollTimeoutRef.current = null;
-    }
-  }, []);
-
-  const fetchStreamResult = useCallback(
-    async (resultUrl: string) => {
-      const response = await fetch(resultUrl);
-      if (response.status === 202) {
-        return false;
-      }
-      if (!response.ok) {
-        throw new Error(
-          await readErrorMessage(
-            response,
-            `Audio stream result failed with status ${response.status}`,
-          ),
-        );
-      }
-
-      const payload = (await response.json()) as AudioStreamResultResponse;
-      if (payload.error) {
-        throw new Error(payload.error);
-      }
-
-      return true;
-    },
-    [readErrorMessage],
-  );
-
-  const clearAudio = useCallback(async () => {
-    const abortController = streamAbortControllerRef.current;
-    streamAbortControllerRef.current = null;
-    abortController?.abort();
-
-    activeSourceNodesRef.current.forEach((source) => {
-      try {
-        source.onended = null;
-        source.stop();
-      } catch {
-        // ignore stop errors when source already ended
-      }
-      source.disconnect();
-    });
-    activeSourceNodesRef.current.clear();
-
-    const audioContext = audioContextRef.current;
-    audioContextRef.current = null;
-    if (!audioContext) return;
-
-    try {
-      await audioContext.close();
-    } catch {
-      // ignore close errors when context already closed
-    }
-  }, []);
-
-  const playPcmStream = useCallback(
-    async ({
-      audioUrl,
-      sampleRate,
-      channels,
-      playbackToken,
-    }: {
-      audioUrl: string;
-      sampleRate: number;
-      channels: number;
-      playbackToken: number;
-    }) => {
-      const AudioContextCtor = window.AudioContext ?? window.webkitAudioContext;
-      if (!AudioContextCtor) {
-        throw new Error("WebAudio AudioContext is not available in this browser");
-      }
-
-      const abortController = new AbortController();
-      streamAbortControllerRef.current = abortController;
-
-      const response = await fetch(withQueryParams(audioUrl, { format: "pcm" }), {
-        signal: abortController.signal,
-      });
-      if (!response.ok) {
-        throw new Error(
-          await readErrorMessage(response, `Audio stream failed with status ${response.status}`),
-        );
-      }
-      if (!response.body) {
-        throw new Error("Audio stream response body is missing");
-      }
-
-      const audioContext = new AudioContextCtor({
-        sampleRate,
-      });
-      audioContextRef.current = audioContext;
-
-      const reader = response.body.getReader();
-      const bytesPerFrame = Math.max(1, channels) * 2;
-      let bufferedRemainder = new Uint8Array(0);
-      let nextStartTime = audioContext.currentTime + 0.05;
-      let activeSources = 0;
-      let streamEnded = false;
-      let resolvePlaybackDrain: (() => void) | null = null;
-      const playbackDrainPromise = new Promise<void>((resolve) => {
-        resolvePlaybackDrain = resolve;
-      });
-
-      const maybeResolvePlaybackDrain = () => {
-        if (streamEnded && activeSources === 0) {
-          resolvePlaybackDrain?.();
-        }
-      };
-
-      const schedulePcmChunk = (pcmBytes: Uint8Array) => {
-        const frameCount = pcmBytes.byteLength / bytesPerFrame;
-        if (frameCount <= 0) return;
-
-        const buffer = audioContext.createBuffer(Math.max(1, channels), frameCount, sampleRate);
-        const view = new DataView(pcmBytes.buffer, pcmBytes.byteOffset, pcmBytes.byteLength);
-        for (let frame = 0; frame < frameCount; frame += 1) {
-          for (let channel = 0; channel < Math.max(1, channels); channel += 1) {
-            const sampleIndex = frame * Math.max(1, channels) + channel;
-            const pcm = view.getInt16(sampleIndex * 2, true);
-            buffer.getChannelData(channel)[frame] = pcm / 32768;
-          }
-        }
-
-        const source = audioContext.createBufferSource();
-        source.buffer = buffer;
-        source.connect(audioContext.destination);
-        const sourceStartTime = Math.max(nextStartTime, audioContext.currentTime + 0.01);
-        nextStartTime = sourceStartTime + buffer.duration;
-
-        activeSources += 1;
-        activeSourceNodesRef.current.add(source);
-        source.onended = () => {
-          activeSources -= 1;
-          activeSourceNodesRef.current.delete(source);
-          source.disconnect();
-          maybeResolvePlaybackDrain();
-        };
-        source.start(sourceStartTime);
-      };
-
-      const concatUint8Arrays = (a: Uint8Array, b: Uint8Array) => {
-        if (a.byteLength === 0) return b;
-        if (b.byteLength === 0) return a;
-        const merged = new Uint8Array(a.byteLength + b.byteLength);
-        merged.set(a);
-        merged.set(b, a.byteLength);
-        return merged;
-      };
-
-      while (true) {
-        if (playbackToken !== playbackTokenRef.current) {
-          throw new DOMException("PCM stream playback cancelled", "AbortError");
-        }
-
-        const { done, value } = await reader.read();
-        if (done) break;
-        if (!value || value.byteLength === 0) continue;
-
-        const merged = concatUint8Arrays(bufferedRemainder, value);
-        const alignedByteLength = merged.byteLength - (merged.byteLength % bytesPerFrame);
-        if (alignedByteLength === 0) {
-          bufferedRemainder = new Uint8Array(merged);
-          continue;
-        }
-
-        const alignedChunk = merged.slice(0, alignedByteLength);
-        bufferedRemainder = new Uint8Array(merged.slice(alignedByteLength));
-        schedulePcmChunk(alignedChunk);
-      }
-
-      streamEnded = true;
-      maybeResolvePlaybackDrain();
-      await playbackDrainPromise;
-    },
-    [readErrorMessage, withQueryParams],
-  );
-
-  const stopPlayback = useCallback(async () => {
-    await clearAudio();
-    stopStatusPolling();
-
-    const closeUrl = closeUrlRef.current;
-    streamIdRef.current = null;
-    closeUrlRef.current = null;
-    statusUrlRef.current = null;
-    resultUrlRef.current = null;
-    setSpeechState("idle");
-    setSpeakingMessageId(null);
-
-    if (closeUrl) {
-      try {
-        await closeStream(closeUrl);
-      } catch (error) {
-        console.error("[GlobalChatbox] Failed to close audio stream:", error);
-      }
-    }
-  }, [clearAudio, closeStream, stopStatusPolling]);
-
-  const pollStreamStatus = useCallback(
-    (playbackToken: number, statusUrl: string, resultUrl: string) => {
-      stopStatusPolling();
-
-      statusPollTimeoutRef.current = window.setTimeout(async () => {
-        if (
-          playbackToken !== playbackTokenRef.current ||
-          statusUrlRef.current !== statusUrl ||
-          resultUrlRef.current !== resultUrl
-        ) {
-          return;
-        }
-
-        try {
-          const response = await fetch(statusUrl);
-          if (!response.ok) {
-            throw new Error(
-              await readErrorMessage(
-                response,
-                `Audio stream status failed with status ${response.status}`,
-              ),
-            );
-          }
-
-          const payload = (await response.json()) as AudioStreamStatusResponse;
-          if (
-            playbackToken !== playbackTokenRef.current ||
-            statusUrlRef.current !== statusUrl ||
-            resultUrlRef.current !== resultUrl
-          ) {
-            return;
-          }
-
-          if (payload.failed || payload.state === "failed") {
-            console.error(
-              "[GlobalChatbox] Audio stream failed:",
-              payload.error || payload.status_text || statusUrl,
-            );
-            playbackTokenRef.current += 1;
-            void stopPlayback();
-            return;
-          }
-
-          if (payload.closed || payload.state === "closed") {
-            stopStatusPolling();
-            return;
-          }
-
-          if (payload.ready || payload.state === "done") {
-            try {
-              const isResultReady = await fetchStreamResult(resultUrl);
-              if (isResultReady) {
-                stopStatusPolling();
-                return;
-              }
-            } catch (error) {
-              console.error("[GlobalChatbox] Failed to fetch audio stream result:", error);
-            }
-          }
-
-          pollStreamStatus(playbackToken, statusUrl, resultUrl);
-        } catch (error) {
-          if (
-            playbackToken === playbackTokenRef.current &&
-            statusUrlRef.current === statusUrl &&
-            resultUrlRef.current === resultUrl
-          ) {
-            console.error("[GlobalChatbox] Failed to poll audio stream status:", error);
-            pollStreamStatus(playbackToken, statusUrl, resultUrl);
-          }
-        }
-      }, 1000);
-    },
-    [fetchStreamResult, readErrorMessage, stopPlayback, stopStatusPolling],
-  );
-
-  const stop = useCallback(() => {
-    playbackTokenRef.current += 1;
-    void stopPlayback();
-  }, [stopPlayback]);
-
-  const speak = useCallback(
-    async (messageId: string, text: string) => {
-      const normalizedText = text.trim();
-      if (!isSupported || !normalizedText) return;
-
-      const playbackToken = playbackTokenRef.current + 1;
-      playbackTokenRef.current = playbackToken;
-      await stopPlayback();
-
-      setSpeakingMessageId(messageId);
-      setSpeechState("playing");
-
-      try {
-        const formData = new FormData();
-        formData.append("text", normalizedText);
-        formData.append("demo_id", "demo-1");
-
-        const response = await fetch(buildServiceUrl("/api/generate-stream/start"), {
-          method: "POST",
-          body: formData,
-        });
-
-        if (!response.ok) {
-          throw new Error(
-            await readErrorMessage(
-              response,
-              `Audio stream start failed with status ${response.status}`,
-            ),
-          );
-        }
-
-        const payload = (await response.json()) as AudioStreamStartResponse;
-        const streamId = payload.stream_id;
-        const sampleRate =
-          typeof payload.sample_rate === "number" && payload.sample_rate > 0
-            ? payload.sample_rate
-            : 24000;
-        const channels =
-          typeof payload.channels === "number" && payload.channels > 0
-            ? payload.channels
-            : 1;
-        const audioUrl = payload.audio_url
-          ? resolveServiceUrl(payload.audio_url)
-          : buildServiceUrl(
-              `/api/generate-stream/${encodeURIComponent(streamId ?? "")}/audio?format=pcm`,
-            );
-        const rawStatusUrl = payload.status_url
-          ? resolveServiceUrl(payload.status_url)
-          : buildServiceUrl(`/api/generate-stream/${encodeURIComponent(streamId ?? "")}/status`);
-        const statusUrl = withQueryParams(rawStatusUrl, { compact: "1" });
-        const rawResultUrl = payload.result_url
-          ? resolveServiceUrl(payload.result_url)
-          : buildServiceUrl(`/api/generate-stream/${encodeURIComponent(streamId ?? "")}/result`);
-        const resultUrl = withQueryParams(rawResultUrl, {
-          compact: "1",
-          include_audio: "0",
-        });
-        const closeUrl = buildServiceUrl(
-          `/api/generate-stream/${encodeURIComponent(streamId ?? "")}/close`,
-        );
-
-        if (!streamId) {
-          throw new Error(payload.error || "Audio stream start response is missing stream_id");
-        }
-
-        if (playbackToken !== playbackTokenRef.current) {
-          await closeStream(closeUrl);
-          return;
-        }
-
-        streamIdRef.current = streamId;
-        closeUrlRef.current = closeUrl;
-        statusUrlRef.current = statusUrl;
-        resultUrlRef.current = resultUrl;
-
-        pollStreamStatus(playbackToken, statusUrl, resultUrl);
-        await playPcmStream({
-          audioUrl,
-          sampleRate,
-          channels,
-          playbackToken,
-        });
-
-        if (playbackToken !== playbackTokenRef.current) {
-          return;
-        }
-
-        await clearAudio();
-        if (streamIdRef.current === streamId) {
-          streamIdRef.current = null;
-          closeUrlRef.current = null;
-          statusUrlRef.current = null;
-          resultUrlRef.current = null;
-          setSpeechState("idle");
-          setSpeakingMessageId(null);
-        }
-        stopStatusPolling();
-        await fetchStreamResult(resultUrl).catch((error) => {
-          console.error("[GlobalChatbox] Failed to fetch audio stream result:", error);
-        });
-        await closeStream(closeUrl);
-      } catch (error) {
-        await clearAudio();
-        if (
-          error instanceof DOMException &&
-          error.name === "AbortError" &&
-          playbackToken !== playbackTokenRef.current
-        ) {
-          return;
-        }
-        const closeUrl = closeUrlRef.current;
-        streamIdRef.current = null;
-        closeUrlRef.current = null;
-        statusUrlRef.current = null;
-        resultUrlRef.current = null;
-        setSpeechState("idle");
-        setSpeakingMessageId(null);
-        if (closeUrl) {
-          try {
-            await closeStream(closeUrl);
-          } catch (closeError) {
-            console.error("[GlobalChatbox] Failed to close audio stream:", closeError);
-          }
-        }
-        console.error("[GlobalChatbox] Failed to play audio stream:", error);
-      }
-    },
-    [
-      buildServiceUrl,
-      clearAudio,
-      closeStream,
-      fetchStreamResult,
-      isSupported,
-      playPcmStream,
-      readErrorMessage,
-      resolveServiceUrl,
-      pollStreamStatus,
-      stopPlayback,
-      stopStatusPolling,
-      withQueryParams,
-    ],
-  );
-
-  const pause = useCallback(() => {
-    if (!isSupported || !audioContextRef.current) return;
-    void audioContextRef.current.suspend().then(
-      () => {
-        setSpeechState("paused");
-      },
-      (error) => {
-        console.error("[GlobalChatbox] Failed to pause PCM playback:", error);
-      },
-    );
-  }, [isSupported]);
-
-  const resume = useCallback(() => {
-    if (!isSupported || !audioContextRef.current) return;
-    void audioContextRef.current.resume().then(
-      () => {
-        setSpeechState("playing");
-      },
-      (error) => {
-        playbackTokenRef.current += 1;
-        void stopPlayback();
-        console.error("[GlobalChatbox] Failed to resume audio playback:", error);
-      },
-    );
-  }, [isSupported, stopPlayback]);
-
-  useEffect(() => {
-    return () => {
-      playbackTokenRef.current += 1;
-      void stopPlayback();
-    };
-  }, [stopPlayback]);
-
-  return { speechState, speakingMessageId, speak, pause, resume, stop, isSupported };
-}
-
-export function useSpeechRecognition(onResult: (text: string) => void) {
-  const [isListening, setIsListening] = useState(false);
-  const recognitionRef = useRef<SpeechRecognition | null>(null);
-  const onResultRef = useRef(onResult);
-  useEffect(() => {
-    onResultRef.current = onResult;
-  }, [onResult]);
-
-  const isSupported =
-    typeof window !== "undefined" &&
-    ("SpeechRecognition" in window || "webkitSpeechRecognition" in window);
-
-  const start = useCallback(() => {
-    if (!isSupported || recognitionRef.current) return;
-    const Ctor = window.SpeechRecognition ?? window.webkitSpeechRecognition;
-    if (!Ctor) return;
-
-    const recognition = new Ctor();
-    recognition.lang = "zh-CN";
-    recognition.continuous = true;
-    recognition.interimResults = false;
-
-    recognition.onresult = (event: SpeechRecognitionEvent) => {
-      for (let i = event.resultIndex; i < event.results.length; i++) {
-        if (event.results[i].isFinal) {
-          onResultRef.current(event.results[i][0].transcript);
-        }
-      }
-    };
-
-    recognition.onerror = () => {
-      setIsListening(false);
-      recognitionRef.current = null;
-    };
-
-    recognition.onend = () => {
-      setIsListening(false);
-      recognitionRef.current = null;
-    };
-
-    recognitionRef.current = recognition;
-    recognition.start();
-    setIsListening(true);
-  }, [isSupported]);
-
-  const stop = useCallback(() => {
-    recognitionRef.current?.stop();
-    recognitionRef.current = null;
-    setIsListening(false);
-  }, []);
-
-  useEffect(() => {
-    return () => {
-      recognitionRef.current?.stop();
-    };
-  }, []);
-
-  return { isListening, start, stop, isSupported };
-}

src/components/chat/GlobalChatboxMarkdown.module.css

@@ -115,3 +115,8 @@
   color: var(--chat-md-quote-text);
   border-radius: 6px;
 }
+
+.streamFade {
+  box-decoration-break: clone;
+  -webkit-box-decoration-break: clone;
+}

src/components/chat/GlobalChatboxParts.tsx

@@ -2,36 +2,6 @@
 
 import React from "react";
 import { motion } from "framer-motion";
-import { Box, Stack } from "@mui/material";
-
-export const TypingIndicator = () => {
-  return (
-    <Stack direction="row" spacing={0.5} alignItems="center" sx={{ p: 1 }}>
-      {[0, 1, 2].map((i) => (
-        <motion.div
-          key={i}
-          initial={{ y: 0 }}
-          animate={{ y: [-4, 4, -4] }}
-          transition={{
-            duration: 0.6,
-            repeat: Infinity,
-            delay: i * 0.15,
-            ease: "easeInOut",
-          }}
-        >
-          <Box
-            sx={{
-              width: 8,
-              height: 8,
-              borderRadius: "50%",
-              background: "linear-gradient(135deg, #FF6B6B 0%, #FF8E53 100%)",
-            }}
-          />
-        </motion.div>
-      ))}
-    </Stack>
-  );
-};
 
 export const Blob = ({
   color,

src/components/chat/chatStorage.test.ts

@@ -1,6 +1,9 @@
 import {
-  loadActiveChatState,
-  saveActiveChatState,
+  createEmptyChatState,
+  deleteChatSession,
+  listChatSessions,
+  loadChatSessionById,
+  updateChatSessionTitle,
 } from "./chatStorage";
 
 const apiFetch = jest.fn();
@@ -9,93 +12,122 @@ jest.mock("@/lib/apiFetch", () => ({
   apiFetch: (...args: unknown[]) => apiFetch(...args),
 }));
 
-describe("chatStorage backend-only persistence", () => {
+describe("chatStorage backend session operations", () => {
   beforeEach(() => {
-    window.localStorage.clear();
     apiFetch.mockReset();
   });
 
-  it("starts from an empty conversation instead of restoring a stored active id", async () => {
-    window.localStorage.setItem("tjwater_agent_active_session_id_v2", "chat-active-1");
-
-    const loaded = await loadActiveChatState();
+  it("creates an empty initial conversation state without backend calls", () => {
+    const loaded = createEmptyChatState();
 
     expect(loaded).toMatchObject({
-      storageSessionId: undefined,
       title: undefined,
       messages: [],
       sessionId: undefined,
-      branchGroups: [],
     });
     expect(apiFetch).not.toHaveBeenCalled();
   });
 
-  it("starts from an empty conversation when a project has a stored active id", async () => {
-    window.localStorage.setItem(
-      "tjwater_agent_active_session_id_v2:project-a",
-      "chat-project-a",
-    );
-    window.localStorage.setItem(
-      "tjwater_agent_active_session_id_v2:project-b",
-      "chat-project-b",
-    );
-
-    const loaded = await loadActiveChatState("project-b");
-
-    expect(loaded.storageSessionId).toBeUndefined();
-    expect(loaded.title).toBeUndefined();
-    expect(loaded.messages).toEqual([]);
-    expect(apiFetch).not.toHaveBeenCalled();
-  });
-
-  it("creates a backend conversation when saving the first non-empty state", async () => {
-    apiFetch.mockImplementation(async (url: string, init?: RequestInit) => {
-      if (url.endsWith("/api/v1/agent/chat/session")) {
-        expect(init?.method).toBe("POST");
-        return {
-          ok: true,
-          json: async () => ({ session_id: "chat-new-1" }),
-        } as Response;
-      }
-
-      if (url.endsWith("/api/v1/agent/chat/session/chat-new-1")) {
-        expect(init?.method).toBe("PUT");
-        expect(JSON.parse(String(init?.body))).toMatchObject({
-          title: "新对话",
-          is_title_manually_edited: false,
-        });
-        return {
-          ok: true,
-          json: async () => ({ id: "chat-new-1", session_id: "chat-new-1" }),
-        } as Response;
-      }
-
-      throw new Error(`Unexpected request ${url}`);
-    });
-
-    const savedSessionId = await saveActiveChatState(
-      {
-        storageSessionId: undefined,
-        title: "新对话",
-        isTitleManuallyEdited: false,
-        messages: [
+  it("lists backend sessions sorted by created time", async () => {
+    apiFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        sessions: [
           {
-            id: "message-2",
-            role: "user",
-            content: "第一条消息",
-            branchRootId: "message-2",
+            id: "session-old",
+            title: "旧会话",
+            created_at: "2026-01-01T00:00:00.000Z",
+            updated_at: "2026-01-02T00:00:00.000Z",
+          },
+          {
+            id: "session-new",
+            title: "新会话",
+            created_at: "2026-01-03T00:00:00.000Z",
+            updated_at: "2026-01-03T00:00:00.000Z",
+            is_streaming: true,
+            run_status: "running",
           },
         ],
-        sessionId: undefined,
-        branchGroups: [],
-      },
-      "project-a",
-    );
+      }),
+    });
 
-    expect(savedSessionId).toBe("chat-new-1");
-    expect(
-      window.localStorage.getItem("tjwater_agent_active_session_id_v2:project-a"),
-    ).toBeNull();
+    await expect(listChatSessions()).resolves.toEqual([
+      expect.objectContaining({
+        id: "session-new",
+        title: "新会话",
+        isStreaming: true,
+        runStatus: "running",
+      }),
+      expect.objectContaining({
+        id: "session-old",
+        title: "旧会话",
+      }),
+    ]);
+    expect(apiFetch.mock.calls[0][1]).toMatchObject({ method: "GET" });
   });
 
+  it("loads a backend session state", async () => {
+    apiFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        id: "session-1",
+        title: "管网分析",
+        is_title_manually_edited: true,
+        messages: [{ id: "message-1", role: "user", content: "查压力" }],
+        is_streaming: false,
+      }),
+    });
+
+    await expect(loadChatSessionById("session-1")).resolves.toMatchObject({
+      title: "管网分析",
+      isTitleManuallyEdited: true,
+      sessionId: "session-1",
+      messages: [{ id: "message-1", role: "user", content: "查压力" }],
+    });
+    expect(String(apiFetch.mock.calls[0][0])).toContain("/sessions/session-1");
+    expect(apiFetch.mock.calls[0][1]).toMatchObject({ method: "GET" });
+  });
+
+  it("updates a backend session title through the title endpoint", async () => {
+    apiFetch.mockResolvedValueOnce({
+      ok: true,
+      text: async () => "",
+    });
+
+    await updateChatSessionTitle("session-1", " 新标题 ", {
+      isTitleManuallyEdited: true,
+    });
+
+    expect(String(apiFetch.mock.calls[0][0])).toContain("/sessions/session-1");
+    expect(apiFetch.mock.calls[0][1]).toMatchObject({ method: "PATCH" });
+    expect(JSON.parse(String(apiFetch.mock.calls[0][1]?.body))).toEqual({
+      title: "新标题",
+      is_title_manually_edited: true,
+    });
+  });
+
+  it("deletes a backend session and returns the next active session id", async () => {
+    apiFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        text: async () => "",
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          sessions: [
+            {
+              id: "session-next",
+              title: "下一会话",
+              created_at: "2026-01-01T00:00:00.000Z",
+              updated_at: "2026-01-01T00:00:00.000Z",
+            },
+          ],
+        }),
+      });
+
+    await expect(deleteChatSession("session-1")).resolves.toBe("session-next");
+    expect(apiFetch.mock.calls[0][1]).toMatchObject({ method: "DELETE" });
+    expect(apiFetch.mock.calls[1][1]).toMatchObject({ method: "GET" });
+  });
 });

src/components/chat/chatStorage.ts

@@ -2,44 +2,31 @@ import { apiFetch } from "@/lib/apiFetch";
 import { config } from "@config/config";
 
 import type {
-  BranchGroup,
   ChatSessionSummary,
   LoadedChatState,
   Message,
 } from "./GlobalChatbox.types";
-import { cloneBranchGroups, cloneMessages } from "./GlobalChatbox.utils";
+import { cloneMessages } from "./globalChatboxUtils";
 
-type RemoteSessionPayload = {
+type BackendSessionPayload = {
   id?: string;
   title?: string;
   created_at?: string | number;
   updated_at?: string | number;
+  is_streaming?: boolean;
+  run_status?: string;
 };
 
-const emptyLoadedChatState = (): LoadedChatState => ({
-  storageSessionId: undefined,
+export const createEmptyChatState = (): LoadedChatState => ({
   title: undefined,
   isTitleManuallyEdited: false,
   messages: [],
   sessionId: undefined,
-  branchGroups: [],
 });
 
 const sanitizeMessages = (messages: Message[] | undefined) =>
   Array.isArray(messages) ? cloneMessages(messages) : [];
 
-const sanitizeBranchGroups = (branchGroups: BranchGroup[] | undefined) =>
-  Array.isArray(branchGroups) ? cloneBranchGroups(branchGroups) : [];
-
-const hasChatContent = (state: {
-  messages: Message[];
-  branchGroups: BranchGroup[];
-  sessionId?: string;
-}) =>
-  state.messages.length > 0 ||
-  state.branchGroups.length > 0 ||
-  Boolean(state.sessionId);
-
 const compareSessionsByAnchorTime = (
   left: Pick<ChatSessionSummary, "id" | "createdAt" | "updatedAt">,
   right: Pick<ChatSessionSummary, "id" | "createdAt" | "updatedAt">,
@@ -58,18 +45,17 @@ const toMillis = (value: string | number | undefined) =>
 
 const normalizeTitle = (value?: string) => value?.trim() || "新对话";
 
-const fetchRemoteChatSessions = async (): Promise<ChatSessionSummary[]> => {
-  const response = await apiFetch(`${config.AGENT_URL}/api/v1/agent/chat/sessions`, {
+const fetchBackendChatSessions = async (): Promise<ChatSessionSummary[]> => {
+  const response = await apiFetch(`${config.AGENT_URL}/api/v1/agent/sessions`, {
     method: "GET",
     projectHeaderMode: "include",
-    userHeaderMode: "include",
     skipAuthRedirect: true,
   });
   if (!response.ok) {
     throw new Error(await response.text());
   }
   const payload = (await response.json()) as {
-    sessions?: RemoteSessionPayload[];
+    sessions?: BackendSessionPayload[];
   };
   return (payload.sessions ?? [])
     .map((session) => ({
@@ -77,24 +63,25 @@ const fetchRemoteChatSessions = async (): Promise<ChatSessionSummary[]> => {
       title: normalizeTitle(session.title),
       createdAt: toMillis(session.created_at),
       updatedAt: toMillis(session.updated_at),
+      isStreaming: session.is_streaming,
+      runStatus: session.run_status,
     }))
     .filter((session) => Boolean(session.id))
     .sort(compareSessionsByAnchorTime);
 };
 
-const fetchRemoteChatSession = async (sessionId: string): Promise<LoadedChatState> => {
+const fetchBackendChatSession = async (sessionId: string): Promise<LoadedChatState> => {
   const response = await apiFetch(
-    `${config.AGENT_URL}/api/v1/agent/chat/session/${encodeURIComponent(sessionId)}`,
+    `${config.AGENT_URL}/api/v1/agent/sessions/${encodeURIComponent(sessionId)}`,
     {
       method: "GET",
       projectHeaderMode: "include",
-      userHeaderMode: "include",
       skipAuthRedirect: true,
     },
   );
   if (!response.ok) {
     if (response.status === 404) {
-      return emptyLoadedChatState();
+      return createEmptyChatState();
     }
     throw new Error(await response.text());
   }
@@ -104,84 +91,26 @@ const fetchRemoteChatSession = async (sessionId: string): Promise<LoadedChatStat
     is_title_manually_edited?: boolean;
     session_id?: string;
     messages?: Message[];
-    branch_groups?: BranchGroup[];
+    is_streaming?: boolean;
+    run_status?: string;
   };
   return {
-    storageSessionId: payload.id,
     title: normalizeTitle(payload.title),
     isTitleManuallyEdited: payload.is_title_manually_edited ?? false,
     messages: sanitizeMessages(payload.messages),
-    sessionId: payload.session_id,
-    branchGroups: sanitizeBranchGroups(payload.branch_groups),
+    sessionId: payload.session_id ?? payload.id,
+    isStreaming: payload.is_streaming ?? false,
+    runStatus: payload.run_status,
   };
 };
 
-const createRemoteChatSession = async (payload?: {
-  sessionId?: string;
-  parentSessionId?: string;
-}) => {
-  const response = await apiFetch(`${config.AGENT_URL}/api/v1/agent/chat/session`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({
-      session_id: payload?.sessionId,
-      parent_session_id: payload?.parentSessionId,
-    }),
-    projectHeaderMode: "include",
-    userHeaderMode: "include",
-    skipAuthRedirect: true,
-  });
-  if (!response.ok) {
-    throw new Error(await response.text());
-  }
-  const body = (await response.json()) as {
-    session_id?: string;
-  };
-  const sessionId = body.session_id?.trim();
-  if (!sessionId) {
-    throw new Error("backend did not return session_id");
-  }
-  return sessionId;
-};
-
-const saveRemoteChatState = async (
-  sessionId: string,
-  state: LoadedChatState,
-): Promise<string> => {
-  const response = await apiFetch(
-    `${config.AGENT_URL}/api/v1/agent/chat/session/${encodeURIComponent(sessionId)}`,
-    {
-      method: "PUT",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        title: normalizeTitle(state.title),
-        is_title_manually_edited: state.isTitleManuallyEdited ?? false,
-        messages: sanitizeMessages(state.messages),
-        branch_groups: sanitizeBranchGroups(state.branchGroups),
-      }),
-      projectHeaderMode: "include",
-      userHeaderMode: "include",
-      skipAuthRedirect: true,
-    },
-  );
-  if (!response.ok) {
-    throw new Error(await response.text());
-  }
-  const payload = (await response.json()) as { id?: string; session_id?: string };
-  return payload.id ?? payload.session_id ?? sessionId;
-};
-
-const updateRemoteChatSessionTitle = async (
+const updateBackendChatSessionTitle = async (
   sessionId: string,
   title: string,
   isTitleManuallyEdited?: boolean,
 ) => {
   const response = await apiFetch(
-    `${config.AGENT_URL}/api/v1/agent/chat/session/${encodeURIComponent(sessionId)}/title`,
+    `${config.AGENT_URL}/api/v1/agent/sessions/${encodeURIComponent(sessionId)}`,
     {
       method: "PATCH",
       headers: {
@@ -192,7 +121,6 @@ const updateRemoteChatSessionTitle = async (
         is_title_manually_edited: isTitleManuallyEdited,
       }),
       projectHeaderMode: "include",
-      userHeaderMode: "include",
       skipAuthRedirect: true,
     },
   );
@@ -201,13 +129,12 @@ const updateRemoteChatSessionTitle = async (
   }
 };
 
-const deleteRemoteChatSession = async (sessionId: string) => {
+const deleteBackendChatSession = async (sessionId: string) => {
   const response = await apiFetch(
-    `${config.AGENT_URL}/api/v1/agent/chat/session/${encodeURIComponent(sessionId)}`,
+    `${config.AGENT_URL}/api/v1/agent/sessions/${encodeURIComponent(sessionId)}`,
     {
       method: "DELETE",
       projectHeaderMode: "include",
-      userHeaderMode: "include",
       skipAuthRedirect: true,
     },
   );
@@ -216,42 +143,13 @@ const deleteRemoteChatSession = async (sessionId: string) => {
   }
 };
 
-export const loadActiveChatState = async (
-  _projectId?: string | null,
-): Promise<LoadedChatState> => {
-  return emptyLoadedChatState();
-};
-
-export const saveActiveChatState = async (
-  state: LoadedChatState,
-  _projectId?: string | null,
-): Promise<string | undefined> => {
-  if (typeof window === "undefined") return state.storageSessionId;
-
-  if (!hasChatContent(state)) {
-    return undefined;
-  }
-
-  let remoteSessionId = state.sessionId ?? state.storageSessionId;
-  if (!remoteSessionId) {
-    remoteSessionId = await createRemoteChatSession();
-  }
-
-  const savedSessionId = await saveRemoteChatState(remoteSessionId, {
-    ...state,
-    storageSessionId: remoteSessionId,
-    sessionId: remoteSessionId,
-  });
-  return savedSessionId;
-};
-
 export const listChatSessions = async (): Promise<ChatSessionSummary[]> => {
   if (typeof window === "undefined") return [];
-  return await fetchRemoteChatSessions();
+  return await fetchBackendChatSessions();
 };
 
 export const updateChatSessionTitle = async (
-  storageSessionId: string,
+  sessionId: string,
   title: string,
   options?: {
     isTitleManuallyEdited?: boolean;
@@ -261,8 +159,8 @@ export const updateChatSessionTitle = async (
 
   const normalizedTitle = title.trim();
   if (!normalizedTitle) return;
-  await updateRemoteChatSessionTitle(
-    storageSessionId,
+  await updateBackendChatSessionTitle(
+    sessionId,
     normalizedTitle,
     options?.isTitleManuallyEdited,
   );
@@ -270,20 +168,18 @@ export const updateChatSessionTitle = async (
 
 export const loadChatSessionById = async (
   sessionId: string,
-  _projectId?: string | null,
 ): Promise<LoadedChatState> => {
-  if (typeof window === "undefined") return emptyLoadedChatState();
+  if (typeof window === "undefined") return createEmptyChatState();
 
-  return await fetchRemoteChatSession(sessionId);
+  return await fetchBackendChatSession(sessionId);
 };
 
 export const deleteChatSession = async (
   sessionId: string,
-  _projectId?: string | null,
 ): Promise<string | undefined> => {
   if (typeof window === "undefined") return undefined;
 
-  await deleteRemoteChatSession(sessionId);
+  await deleteBackendChatSession(sessionId);
   const nextActiveSession = (await listChatSessions())[0];
   return nextActiveSession?.id;
 };