详细设计（Chameleon V1.2）

本文根据 DESIGN.md 整理，作为项目的设计说明文档（非 PRD）。如需查看原始设计记录，请参考仓库根目录的 DESIGN.md。

1. 目标与愿景

本系统旨在构建一个“人机耦合的增强型对话系统”，强调：

极致拟人化：通过流式输出、情感适应与长期记忆增强对话体验。
隐形人机协作（HIL）：人工坐席可无缝接管，前台零感知。
自主进化：管理员通过自然语言指令教会系统新技能，并快速上线。

2. 用户角色

终端用户：期望即时、专业且具温度的服务。
人工坐席：需要全局上下文、低负担介入与 AI 辅助建议。
AI 训练师/管理员：以自然语言方式配置或扩展能力。

3. 架构概览（Monorepo V1.2）

项目采用单体仓库的多模块形态，主要模块如下：

/Users/zata/code/aibot/
├── ai_service/            # AI 能力层（SSE 输出）
├── demo-backend/          # 业务中转层（WebSocket + Proxy）
├── demo-frontend/         # 展示层（React）
├── docker-compose.yml     # 一键编排
└── .env                   # 统一环境变量

概念架构图（V1.2 三层存储架构：MinIO/PostgreSQL/Qdrant）：

flowchart TB
    %% === 展示层 ===
    subgraph Frontend_Layer["demo-frontend"]
        UserUI["React Chat UI"]
    end

    %% === 业务中转层 ===
    subgraph Business_Layer["demo-backend"]
        SocketBroker["Socket.IO Broker"]
        HTTPClient["httpx Stream Client"]
    end

    %% === AI 核心能力层 ===
    subgraph AI_Core_Layer["ai_service"]
        FastAPI_SSE["FastAPI SSE Server"]
        Orchestrator["LangGraph Orchestrator"]
    end

    %% === 数据与存储（V1.2） ===
    subgraph Infra_Layer["Infrastructure (V1.2)"]
        Redis[(Redis - Lock/State)]
        Postgres[(PostgreSQL - Sessions/Messages/Chunks)]
        Qdrant[(Qdrant - Vector Index)]
        MinIO[(MinIO - Raw Documents)]
    end

    %% 数据流
    StreamEndpoint["POST /stream (SSE)"]
    UserUI <--> SocketBroker
    SocketBroker --> HTTPClient
    HTTPClient --> StreamEndpoint --> FastAPI_SSE
    FastAPI_SSE <--> Orchestrator
    Orchestrator <--> Redis
    Orchestrator <--> Postgres
    Orchestrator <--> Qdrant
    Orchestrator <--> MinIO

说明：前端与 demo-backend 通过 WebSocket/Socket.IO 交互；demo-backend 以 POST /stream (SSE) 调用 AI 服务。

4. 模块详细设计

4.1 ai_service（核心能力层）

职责：核心推理与编排服务，不持有前端连接，仅通过 SSE 进行流式输出。

技术栈：FastAPI、LangGraph、Pydantic。
关键流程：
接收 message 与 thread_id。
启动 LangGraph 编排流程。
捕获 on_chat_model_stream 事件并输出 SSE。
持久化：采用三层存储架构（MinIO/PostgreSQL/Qdrant），详见存储层文档。

4.2 demo-backend（业务中转层）

职责：维护前端 WebSocket 连接，并作为代理请求 ai_service。

技术栈：Python、Socket.IO、httpx。
关键流程：
接收前端 user_message。
请求 ai_service 的 SSE 流。
逐段读取 SSE 并通过 WebSocket 向前端转发。
处理业务逻辑（鉴权、人机接管状态等）。

4.3 demo-frontend（展示层）

职责：提供拟人化的流式对话界面体验。

技术栈：React、Vite、Socket.IO-client、Tailwind CSS。
关键交互：
监听 ai_response 事件并实时渲染。
使用流式文本状态模拟“打字机”效果。
Typing Indicator 提示动态生成。

5. 核心数据流（流式对话）

sequenceDiagram
    participant U as 用户浏览器 (demo-frontend)
    participant B as 业务后端 (demo-backend)
    participant A as AI 服务 (ai_service)

    U->>B: WebSocket: emit(user_message, payload)
    B->>A: HTTP POST: /stream (Thread-1)
    loop SSE Stream
        A-->>B: data: token -> 您
        B-->>U: emit(ai_response, token -> 您)
        A-->>B: data: token -> 好
        B-->>U: emit(ai_response, token -> 好)
    end
    A-->>B: data: done
    B-->>U: emit(ai_response, done)

6. 部署编排（Docker Compose）

以下示例与仓库根目录 docker-compose.yml 保持一致。

services:
  postgres:
    image: postgres:15-alpine
    networks: [aibot-internal]

  redis:
    image: redis:7-alpine
    networks: [aibot-internal]

  qdrant:
    image: qdrant/qdrant:latest
    networks: [aibot-internal]

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    networks: [aibot-internal]

  ai-service:
    build:
      context: .
      dockerfile: ai_service/Dockerfile
    ports:
      - "${AI_SERVICE_PORT:-18000}:8000"
    environment:
      # Local all-in-one example only. In staging/production the app host now
      # connects to a dedicated infra host via explicit remote endpoints.
      - DATABASE_URL=postgresql+psycopg2://${POSTGRES_USER:-admin}:${POSTGRES_PASSWORD:-123456}@postgres:5432/${POSTGRES_DB:-chameleon_meta}
      - MINIO_ENDPOINT=minio:9000
      - QDRANT_HOST=qdrant
      - REDIS_URL=redis://redis:6379
    depends_on:
      - postgres
      - redis
      - qdrant
      - minio
    networks:
      - aibot-internal

  demo-backend:
    build:
      context: ./demo-backend
    ports:
      - "${DEMO_BACKEND_PORT:-13000}:3000"
    environment:
      - AI_SERVICE_URL=http://ai-service:8000
    depends_on:
      - ai-service
    networks:
      - aibot-internal

  demo-frontend:
    build:
      context: ./demo-frontend
    ports:
      - "${DEMO_FRONTEND_PORT:-18080}:80"
    depends_on:
      - demo-backend
    networks:
      - aibot-internal

  admin-frontend:
    build:
      context: ./admin-frontend
    ports:
      - "${ADMIN_FRONTEND_PORT:-18081}:80"
    depends_on:
      - ai-service
    networks:
      - aibot-internal

  docs-site:
    build:
      context: .
      dockerfile: docs/Dockerfile
    ports:
      - "${DOCS_SITE_PORT:-18001}:80"
    networks:
      - aibot-internal

networks:
  aibot-internal:
    driver: bridge

7. MVP 路线（V1.2）

ai_service 骨架：SSE 生成器与基础编排流程。
demo-backend 代理：SSE -> WebSocket 实时转发。
demo-frontend 渲染：流式文本与 UI 交互体验。
HIL 联调：基于共享状态（如 Redis）进行接管逻辑测试。