浏览器
  │ HTTPS / SSE
  ▼
┌────────────────────────────────┐
│  Next.js 14 (App Router)       │  :3000
│  - 聊天界面（流式 + 思考链）   │
│  - KB 管理 / 协作邀请          │
│  - 系统设置 modal              │
│  - 内置 API proxy 转发到后端   │
└──────────────┬─────────────────┘
               │ proxy
               ▼
┌────────────────────────────────┐
│  FastAPI + LangGraph           │  :8000
│  ├─ Auth (JWT, bcrypt)         │
│  ├─ Conversations REST         │
│  ├─ KB REST (含协作 / 邀请)    │
│  ├─ Settings REST              │
│  └─ /api/chat (SSE)            │
│       └─ Agent 主循环          │
│            plan → call_tools → skill_report
└──┬─────────────────────┬───────┘
   │                     │
   ▼                     ▼
┌──────────────┐    ┌─────────────────────────────┐
│ App DB       │    │ Vector DB                   │
│ SQLite       │    │ Milvus Lite (默认)          │
│ (users / kbs │    │   或 Milvus Standalone      │
│  /docs /msgs)│    │   或 Qdrant                 │
└──────────────┘    └─────────────────────────────┘

外部服务（按 KB / 用户配置）：
  - LLM        : DeepSeek / Claude / OpenAI / SiliconFlow / Ollama
  - Embedding  : SiliconFlow BGE-M3 / OpenAI / Ollama
  - Reranker   : SiliconFlow / Cohere / 自托管 TEI (opt-in)
  - Web Search : DuckDuckGo (ddgs, 免 key)

ai-agent/
├── backend/                       Python 3.11 / FastAPI
│   ├── src/
│   │   ├── app.py                 FastAPI 入口 + SSE chat 端点 + lifespan
│   │   ├── settings.py            pydantic-settings（.env 驱动）
│   │   ├── auth/                  M1: JWT 认证（注册 / 登录 / me / 改密 / 删号）
│   │   │   ├── models.py          User SQLAlchemy 模型（17 列：4 主 + 5 LLM + 5 embed + 1 reranker_enabled + 2 平台标志 is_admin/is_active）
│   │   │   ├── password.py        bcrypt cost=12
│   │   │   ├── tokens.py          JWT HS256 编解码
│   │   │   ├── middleware.py      CurrentUser + require_admin/AdminUser 依赖（封禁拦截下沉于此）
│   │   │   └── routes.py          /api/auth/{register,login,me,change-password}
│   │   ├── kb/                    M2/M3: 知识库 + 文档 + ingest
│   │   │   ├── models.py          KB / Document / KBMember / KBInvitation
│   │   │   ├── routes.py          /api/kbs/* + /api/invitations/*
│   │   │   ├── ingest.py          后台异步 chunk + embed + upsert
│   │   │   ├── chunker.py         段落→句子→字符递归切分
│   │   │   ├── system_seed.py     启动注册 TravelGPT 演示库
│   │   │   └── parsers/           markdown / pdf (pymupdf) / docx / webpage (trafilatura)
│   │   ├── conversations/         v2-M3: 跨设备会话历史
│   │   │   ├── models.py          Conversation / Message (FK CASCADE)
│   │   │   └── routes.py          /api/conversations/* + bulk import + export
│   │   ├── settings_user/         v2-M1: 每用户自助配置
│   │   │   ├── models.py          UserLLMConfig / UserEmbeddingConfig / UserRerankerConfig
│   │   │   ├── kb_resolvers.py    v3-M7: KB 级 cfg 优先 → user 兜底
│   │   │   ├── probe.py           列模型 / 验 base_url+api_key
│   │   │   ├── gate.py            v2-M2: BYOK 强制 gate
│   │   │   └── routes.py          /api/settings/*
│   │   ├── agent/                 LangGraph 主循环
│   │   │   ├── graph.py           build_graph(kb, llm_cfg, embedding_cfg, reranker_cfg, ...)
│   │   │   ├── nodes.py           plan / call_tools / skill_report
│   │   │   ├── state.py           AgentState TypedDict
│   │   │   └── prompts.py         3 套 system prompt (general / travel / kb)
│   │   ├── tools/                 Agent 工具实现
│   │   │   ├── base.py            ToolRegistry 工厂（按 KB 模式三态切换工具集）
│   │   │   ├── kb_search.py       通用 KB 检索（含 reranker over-fetch + rerank reorder）
│   │   │   ├── web_search.py      DuckDuckGo / ddgs
│   │   │   ├── weather.py         高德天气（旅行示例）
│   │   │   ├── restaurant_rag.py  旅行 KB 检索（MMR）
│   │   │   └── amap_fallback.py   高德 POI 兜底
│   │   ├── skills/                结构化输出模板
│   │   │   ├── loader.py          invoke_skill (LLM JSON 输出)
│   │   │   ├── general_report/SKILL.md   v2-M8: 通用 KB 报告模板
│   │   │   └── travel_report/SKILL.md    旅行报告模板
│   │   ├── safety/                输入清洗 / 输出脱敏 / 工具守卫
│   │   └── infra/                 基础设施抽象层（解耦核心）
│   │       ├── database.py        SQLAlchemy async + init_db + 幂等 ALTER
│   │       ├── vector_store.py    VectorStore Protocol + Qdrant/Milvus/Local 三 adapter
│   │       ├── local_vector.py    SQLite 兜底向量实现
│   │       ├── embedding.py       OpenAI 兼容统一 embed 客户端 + provider 预设
│   │       ├── reranker.py        v3-M4: cross-encoder rerank 客户端
│   │       ├── llm.py             LLM 客户端（Anthropic / OpenAI 兼容）+ pick_model
│   │       ├── crypto.py          Fernet at-rest 加密（key 派自 JWT_SECRET）
│   │       └── rate_limit.py      内存 sliding window
│   ├── data/                      运行时数据（gitignored）
│   │   ├── app.db                 SQLite 应用库
│   │   ├── milvus_local.db        Milvus Lite 向量库
│   │   └── uploads/{kb_id}/       原始上传文件
│   ├── tests/                     smoke (reranker + milvus + graph) + test_admin (28) + conftest（临时 DB/HTTP 夹具）
│   ├── env.example                env 模板（每个字段含注释）
│   └── pyproject.toml             依赖（核心 + dev/ollama/openai/monitoring/milvus extras）
│
├── frontend/                      Next.js 14 App Router + Tailwind
│   ├── app/
│   │   ├── page.tsx               主聊天页（KB+Model selector + Sidebar + Chat）
│   │   ├── welcome/               未登录落地页
│   │   ├── login/ register/       双栏登录注册 + ?next= 回跳
│   │   ├── kbs/                   KB 列表 + 详情（含成员管理 / 邀请 / 高级设置）
│   │   ├── settings/              v3-M8 极简后只剩 LLM 凭据 + KB 选项
│   │   ├── invite/[token]/        v2-M9: 匿名邀请落地页
│   │   ├── api/                   catch-all proxy → 后端 :8000
│   │   └── layout.tsx             ThemeProvider + Toaster + Plausible 钩子
│   ├── components/
│   │   ├── Sidebar.tsx            对话列表 + 重命名 + 底部 UserMenu
│   │   ├── ChatBox.tsx            自适应高度 + Stop 按钮
│   │   ├── MessageBubble.tsx      用户/助手气泡 + 流式占位
│   │   ├── ThinkingChain.tsx      工具调用思考链可视
│   │   ├── ReportView.tsx         markdown 报告渲染（prose-tg）
│   │   ├── ExportActions.tsx      复制 MD / 导 PDF / 图文分享
│   │   ├── ShareCardDialog.tsx    品牌图文卡 portal 模态
│   │   ├── SystemSettingsDialog.tsx  v3-M5: DeepSeek 风 4-tab 设置 modal
│   │   ├── Select.tsx Dialog.tsx Brand.tsx ThemeToggle.tsx ...
│   │   └── CreateKbDialog.tsx     v3-M7/8.2: 含 Embedding+Reranker 配置 + 测试连接
│   ├── lib/
│   │   ├── auth.ts                token + authFetch + per-user storage key
│   │   ├── sseClient.ts           fetch+ReadableStream 手动 SSE 解析
│   │   ├── conversations-api.ts   会话 CRUD wrapper
│   │   ├── kb-api.ts              KB / 文档 / 成员 / 邀请 wrapper
│   │   ├── settings-api.ts        LLM / Embedding / Reranker probe + save
│   │   ├── conversationStore.ts   Message 类型 + deriveTitle
│   │   ├── byok-toast.ts          v2-M2: BYOK 422 → toast「去配置」
│   │   ├── storage-migrate.ts     一次性 anykb:* 命名空间迁移
│   │   ├── cn.ts                  clsx + tailwind-merge
│   │   └── theme.ts               class 策略 dark mode
│   ├── tailwind.config.ts         语义化 token + dark class 策略
│   └── package.json               (next 14 / react 18 / tailwind 3.4)
│
├── data/                          策展示例数据
│   ├── seed/{shanghai,beijing,chengdu,hangzhou}.json   20 家餐厅
│   ├── schema.json                seed 数据 schema
│   └── ingest.py                  独立 seed → vector store 入库脚本
│
├── docs/                          完整文档
│   ├── architecture.md            内部架构 / 状态图 / 解耦设计
│   ├── deploy.md                  本地启动 + 服务器部署 + 换部件
│   ├── rag-primer.md              小白入门：RAG / Embedding / BM25 / Hybrid / Rerank
│   ├── milvus-guide.md            Milvus 向量库详解
│   ├── curation-sop.md            策展 SOP
│   └── tutorial.md                端到端流程教学
│
├── docker-compose.yml             4 服务编排（postgres + backend + frontend + nginx）
├── env.docker.example             Docker 部署 env 模板
├── nginx/anykb.conf               nginx 反代配置（SSE-safe）
├── scripts/                       运维脚本
│   ├── deploy.sh                  build + up + 健康检查
│   ├── backup.sh                  备份 PG + backend-data 卷
│   └── logs.sh                    tail -f 服务日志
├── start_local.bat / start_local.sh   一键本地启动（非 Docker）
├── start.py                       Python 启动器
├── PROGRESS.md                    完整 changelog（M0 → v3-M8.2 + Docker 化）
└── README.md                      本文档

Backend (1~N worker) ──► PostgreSQL 15+   (App DB, 关系数据)
                    ──► Milvus Standalone (Vector DB, chunk 向量)
                    ──► SiliconFlow API   (Embedding + Reranker)
                    ──► Anthropic / DeepSeek API (LLM)

┌────────────────────────────────────────────┐
│           nginx:80 (host:80)               │
│   /api/chat → backend (SSE buffering off)  │
│   /api/...  → backend                      │
│   /        → frontend                      │
└──────────────────┬─────────────────────────┘
                   │ docker network: anykb_default
   ┌───────────────┼───────────────┐
   ▼               ▼               ▼
postgres        backend         frontend
(:5432)         (:8000)         (:3000)
   ▲                │
   │                │ asyncpg
   └────────────────┘

公网 :80
  │
  ▼
┌──────────────────────────────────┐
│ nginx (nginx:1.27-alpine)        │ host 端口 80
│   /api/chat → backend (SSE off)  │
│   /api      → backend            │
│   /         → frontend           │
└──┬─────────────┬─────────────────┘
   ▼             ▼
backend       frontend
(FastAPI +    (Next.js
 Milvus       standalone)
 Lite 嵌入式)
   │
   ▼
postgres (postgres:16-alpine)
  → volume anykb_postgres-data

data volumes:
  anykb_postgres-data   (PG 数据)
  anykb_backend-data    (Milvus Lite + uploads)